Underwriting Risk Taxonomy

Risk Classes

UnderwritingRiskClass tags every finding with one of four severity levels. The class is ordered: each higher level dominates the lower ones when rolling findings up to the report-level risk_class.

The taxonomy is versioned. Each signed decision record embeds the taxonomy version (chio.underwriting.taxonomy.v1) so consumers can audit which schema produced a given outcome.

Reason Codes

UnderwritingReasonCode is the machine-readable label attached to each input UnderwritingSignal. Thirteen codes are defined. The table below gives the trigger condition, the risk severity that signal carries when present, and the typical decision the evaluator routes it to.

These reason codes are the input vocabulary. The evaluator translates them into UnderwritingDecisionReasonCode values on findings (for example, PolicySignal, ReputationBelowApproveThreshold, RuntimeAssuranceBelowStepUpTier), which carry the original signal reason on the finding so consumers can trace the decision back to its evidence.

Decision Outcomes

UnderwritingDecisionOutcome has four ordered variants. The report-level outcome is the maximum of every finding's outcome, so any single deny finding wins.

Default Policy Thresholds

UnderwritingDecisionPolicy::default() ships with the values below. The policy is signed alongside the decision report so the thresholds in force at decision time are recoverable from the record.

pub struct UnderwritingDecisionPolicy {
    pub schema: String,
    pub version: String,
    pub minimum_receipt_history: u64,
    pub maximum_receipt_age_seconds: u64,
    pub minimum_approve_reputation_score: f64,
    pub deny_reputation_score_below: f64,
    pub minimum_step_up_runtime_assurance_tier: RuntimeAssuranceTier,
    pub minimum_approve_runtime_assurance_tier: RuntimeAssuranceTier,
    pub require_active_tool_certification: bool,
    pub require_compliance_score_reference: bool,
    pub reduce_ceiling_factor: f64,
}

// Default values:
// minimum_receipt_history = 1
// maximum_receipt_age_seconds = 60 * 60 * 24 * 30 = 30 days
// minimum_approve_reputation_score = 0.6
// deny_reputation_score_below = 0.25
// minimum_step_up_runtime_assurance_tier = RuntimeAssuranceTier::Attested
// minimum_approve_runtime_assurance_tier = RuntimeAssuranceTier::Verified
// require_active_tool_certification = true
// require_compliance_score_reference = false
// reduce_ceiling_factor = 0.5

policy.validate() rejects configurations that put the deny floor at or above the approve threshold, so the manual review band cannot collapse to zero width.

The same bands support risk classification: the approve and deny cuts on the underwriting policy line up with the scorecard bands the report ultimately resolves to.

Evidence Kinds and Compliance Bundle

Findings reference UnderwritingEvidenceReference records, each tagged with an UnderwritingEvidenceKind:

pub enum UnderwritingEvidenceKind {
    Receipt,
    ReputationInspection,
    CertificationArtifact,
    RuntimeAssuranceEvidence,
    SettlementReconciliation,
    MeteredBillingReconciliation,
    SharedEvidenceReference,
}

These kinds let consumers route evidence back to the system that produced it. A RuntimeAssuranceEvidence reference, for example, includes a SHA-256 digest and a verifier locator pointing at the attestation that justified the finding.

UnderwritingComplianceEvidence

When the optional compliance score is included in the input bundle, it ships in this fixed shape:

pub struct UnderwritingComplianceEvidence {
    pub schema: String,
    pub agent_id: String,
    pub score: u32,                          // 0..=1000
    pub generated_at: u64,                   // unix seconds
    pub total_receipts: u64,
    pub deny_receipts: u64,
    pub observed_capabilities: u64,
    pub revoked_capabilities: u64,
    pub attestation_age_secs: Option<u64>,   // None when no attestation observed
}

When require_compliance_score_reference is set on the policy and this field is None, the evaluator emits a ComplianceScoreRequired finding that routes to StepUp.

Imported Evidence Inputs

Two imported inputs feed the underwriting policy input at schema chio.underwriting.policy-input.v2: imported financial credentials carried on the passport (credit standing, exposure, settlement reliability, premium and loss history) and spend-anomaly findings drawn from the live receipt log. Both enter the evaluation as asserted imported evidence, not authority. Each provides a reason code the evaluator weighs and carries its own provenance, but neither grants standing on its own. See Portable Financial Credentials for the imported credential family and Comptroller Console for spend-anomaly findings.

Premium Pricing

Two premium interfaces ship with chio-underwriting: the decision-time premium quoted in the signed record, and the standalone price_premium function used by chio-market to quote-and-bind an insurance policy.

Decision-Time Premium

Each signed UnderwritingDecisionArtifact carries an UnderwritingPremiumQuote:

pub enum UnderwritingPremiumState {
    Quoted,
    Withheld,
    NotApplicable,
}

pub struct UnderwritingPremiumQuote {
    pub state: UnderwritingPremiumState,
    pub basis_points: Option<u32>,
    pub quoted_amount: Option<MonetaryAmount>,
    pub rationale: String,
}

Basis points (a basis point is 1/100 of a percent, so 100 bps = 1%) are a fixed schedule keyed off the outcome and the rolled-up risk class:

The quoted amount equals ceil(exposure_units * bps / 10_000) in the same currency as the quoted exposure. When no exposure is supplied, only the basis points appear on the quote.

Insurance-Flow Premium

The standalone price_premium function takes a compliance score in 0..=1000 plus an optional behavioral z-score and produces a PremiumQuote. It is deterministic and fail-closed: a missing compliance score returns a decline instead of silently approving.

Score band | Multiplier | Disposition
-----------|-----------:|------------
> 900      |       1.0  | Quoted
700..=900  |       2.0  | Quoted
500..700   |       5.0  | Quoted
< 500      |        -   | Declined

quoted_cents = base_rate_cents * (1 + risk_multiplier(score))

Behavioral anomalies erode the score through a per-sigma penalty before the band is chosen. Defaults: penalty per sigma above the threshold is 50 points, capped at 250 points total, with the threshold at 3 sigma. The quote's justification string records the inputs used for audit.

The behavioral z-score is populated from chio_kernel::behavioral_anomaly_score. The signed insurer-facing feed that reports it for premium pipeline is chio trust behavioral-feed export (HTTP GET /v1/reports/behavioral-feed), which exports the behavioral-anomaly signal consumed as PremiumInputs.behavioral_z_score.

See Liability Market for how this quote is bound into a policy via quote_and_bind.

Worked Example

Take an agent with two recent governed receipts, a Verified runtime assurance tier, and a reputation score of 0.4. The agent is still in its probationary window. The input carries one signal: ProbationaryHistory at Guarded severity.

UnderwritingPolicyInput {
    schema: "chio.underwriting.policy-input.v1",
    generated_at: 1_700_000_000,
    filters: UnderwritingPolicyInputQuery {
        agent_subject: Some("agent-42".into()),
        receipt_limit: Some(100),
        ..default()
    },
    taxonomy: UnderwritingRiskTaxonomy::default(),
    receipts: UnderwritingReceiptEvidence {
        matching_receipts: 2,
        // ... two recent governed receipts ...
    },
    reputation: Some(UnderwritingReputationEvidence {
        subject_key: "agent-42".into(),
        effective_score: 0.4,
        probationary: true,
        ..
    }),
    runtime_assurance: Some(UnderwritingRuntimeAssuranceEvidence {
        highest_tier: Some(RuntimeAssuranceTier::Verified),
        ..
    }),
    signals: vec![UnderwritingSignal {
        class: UnderwritingRiskClass::Guarded,
        reason: UnderwritingReasonCode::ProbationaryHistory,
        description: "subject is still probationary".into(),
        evidence_refs: vec![/* ... */],
    }],
    ..default()
}

The evaluator produces two findings:

• A reputation finding: score 0.4 is below the approve threshold of 0.6 and above the deny floor of 0.25, so it routes to ReduceCeiling at Elevated class with reason ReputationBelowApproveThreshold and signal_reason LowReputation.
• A signal-driven finding for ProbationaryHistory: routes to ReduceCeiling at Guarded class with reason PolicySignal.

Rolled up: report outcome is ReduceCeiling (the maximum of the two), risk class is Elevated (the maximum of the two), and suggested_ceiling_factor is 0.5 from the default policy. The signed decision record carries:

• review_state: Approved
• budget: Reduce with ceiling factor 0.5
• premium: Quoted at 400 bps (ReduceCeiling at Elevated). MonetaryAmount.units are integer minor units, so a $10.00 exposure is units: 1_000; the quoted premium is ceil(1000 * 400 / 10_000) = 40 minor units ($0.40) in the same currency.

Worked Decision Example

Consider an agent with reputation 0.42, eight governed receipts in the last 30 days, no tool-server certification on file. The operator wants to size a 1,000-unit ceiling against this agent and scopes the evaluation to a specific tool server. Walk through what the evaluator emits.

Reputation Evidence Shape

The reputation block on UnderwritingPolicyInput is fixed:

pub struct UnderwritingReputationEvidence {
    pub subject_key: String,
    pub effective_score: f64,
    pub probationary: bool,
    pub resolved_tier: Option<String>,
    pub imported_signal_count: usize,
    pub accepted_imported_signal_count: usize,
}

For our agent this resolves to:

{
  "subjectKey": "agent-vanguard-soc2",
  "effectiveScore": 0.42,
  "probationary": false,
  "resolvedTier": "tier-2",
  "importedSignalCount": 0,
  "acceptedImportedSignalCount": 0
}

Triggers

Two thresholds fire on this input:

• LowReputation: 0.42 is below the approve threshold of 0.6 and above the deny floor of 0.25, so it routes to a ReputationBelowApproveThreshold finding at Elevated class.
• MissingCertification: the policy default require_active_tool_certification is true, the query names a tool server, and no certification record resolves for it. The finding routes at Elevated class with outcome StepUp and reason PolicySignal. The certification arm only fires when the query is scoped to a tool server; an unscoped evaluation skips it entirely.

Outcome

The reputation finding carries ReduceCeiling; the certification finding carries StepUp. Eight receipts is enough history and the runtime assurance tier clears the approve target, so neither history nor runtime adds a finding. Because UnderwritingDecisionOutcome is ordered Approve < ReduceCeiling < StepUp < Deny and the report outcome is the maximum over every finding, the StepUp certification finding dominates. Rolled up: report outcome is StepUp, risk class is Elevated (the max of the two Elevated classes). Each UnderwritingDecisionFinding records its own reason (a UnderwritingDecisionReasonCode) plus an optional signal_reason that carries the originating input signal for traceability: ReputationBelowApproveThreshold with signal reason LowReputation on the first, PolicySignal with signal reason MissingCertification on the second.

Premium Calculation

A StepUp outcome withholds the premium. The signed UnderwritingDecisionArtifact includes an UnderwritingPremiumQuote with state Withheld, no basis_points, and no quoted_amount; nothing is priced until manual review or stronger evidence clears the step-up.

Had the certification resolved and this decision landed at ReduceCeiling at Elevated instead, the schedule prices that pair at 400 bps and the amount comes from the chio-underwriting helper:

fn quote_premium_amount(exposure: &MonetaryAmount, basis_points: u32) -> MonetaryAmount {
    // u128 keeps the intermediate multiplication exact for any u64 exposure
    // and any u32 basis_points. The conversion back to u64 saturates so a
    // future caller passing basis_points >= 10_000 cannot truncate silently;
    // an overflow here surfaces as the largest representable premium and is
    // preferred over wrap-around.
    let units = (u128::from(exposure.units) * u128::from(basis_points)).div_ceil(10_000_u128);
    let saturated_units = u64::try_from(units).unwrap_or(u64::MAX);
    MonetaryAmount {
        units: saturated_units,
        currency: exposure.currency.clone(),
    }
}

Apply it: units = ceil(1000 * 400 / 10_000) = 40. That counterfactual quote would carry basis_points = 400 and quoted_amount = MonetaryAmount{ units: 40, currency: "USD" }. The u64 conversion saturates: a basis-point figure large enough to overflow surfaces as u64::MAX instead of wrapping.

CLI Invocation

The evaluation runs through chio trust underwriting-decision evaluate, reading receipts from a local database (or a trust-control service via --control-url / --control-token):

$ chio trust underwriting-decision evaluate \
    --agent-subject agent-vanguard-soc2 \
    --tool-server ts-search-prod \
    --receipt-db ./receipts.db
schema:                 chio.underwriting.decision-report.v1
generated_at:           1735000000
outcome:                StepUp
risk_class:             Elevated
policy_version:         chio.underwriting.decision-policy.default.v1
matching_receipts:      8
findings:               2
- ReduceCeiling ReputationBelowApproveThreshold: effective score 0.42 below approve threshold 0.6
- StepUp PolicySignal: active tool-server certification not resolvable

evaluate is read-only: it returns the unsigned UnderwritingDecisionReport (schema, outcome, risk class, policy version, suggested ceiling factor, matching receipt count, and one line per finding) and never persists anything. The report itself has no decision_id, review_state, budget, or premium field. To mint the signed record that downstream consumers (chio-credit, chio-market) verify against the kernel signing key, run chio trust underwriting-decision issue instead. Its output adds the decision identity and the fields that only exist on UnderwritingDecisionArtifact:

$ chio trust underwriting-decision issue \
    --agent-subject agent-vanguard-soc2 \
    --tool-server ts-search-prod \
    --receipt-db ./receipts.db
schema:                 chio.underwriting.decision.v1
decision_id:            uwd-9c3f2a18b4e1...
issued_at:              1735000000
signer_key:             3f9a...c012
outcome:                StepUp
review_state:           ManualReviewRequired
budget_action:          Hold
premium_state:          Withheld

evaluate and issue share the same evidence filters (--capability, --tool-server, --tool-name, --since / --until, --receipt-limit). A third verb, simulate, replays an alternative policy file against the same evidence without persisting a decision.

Appeals

Decisions can be challenged via an UnderwritingAppealRecord. Appeals carry a status of Open, Accepted, or Rejected. An accepted appeal can reference a replacement_decision_id; creating that replacement supersedes the original decision (lifecycle state moves from Active to Superseded).

Next Steps

• Scorecards : the credit-scorecard view that pairs with the underwriting input bundle.
• Credit Facilities & Bonds : how an underwriting decision turns into a granted facility and a collateral bond.
• Liability Market : provider types, jurisdiction policies, and quote-and-bind mechanics.
• Claims Lifecycle : the seven-stage workflow from package to settlement receipt.
• Credit & Underwriting Guide : walkthrough that connects this taxonomy to the CLI.