Risk Comptroller Reports

Public API

Five entry points and two public types. Every other struct in the schema is private, so the report's shape stays behind the validators. The full internal-consistency check against a Transaction Passport:

pub fn validate_risk_report(
    passport: &TransactionPassport,
    report: &RiskComptrollerReport,
) -> Result<(), TransactionPassportError> {

Signature check, deserialize, then validate_risk_report:

pub fn validate_signed_risk_report(
    passport: &TransactionPassport,
    report_value: &serde_json::Value,
    trusted_authority_keys: &[PublicKey],
) -> Result<RiskComptrollerReport, TransactionPassportError> {

Signature check only, against a raw JSON value:

pub fn validate_risk_report_signature(
    report_value: &serde_json::Value,
    trusted_authority_keys: &[PublicKey],
) -> Result<(), TransactionPassportError> {

Cross-report capital adequacy and reserve consumption:

pub fn validate_risk_portfolio_reports(
    reports: &[RiskComptrollerReport],
) -> Result<(), TransactionPassportError> {

Evidence-graph membership through a caller callback:

pub fn validate_risk_evidence_refs(
    report: &RiskComptrollerReport,
    mut contains_ref: impl FnMut(&str, RiskEvidenceRefKind) -> bool,
) -> Result<(), TransactionPassportError> {

On RiskComptrollerReport, only id, order_id, subject, and signature are public fields; verified_claims() returns the claim ids the comptroller asserts. Cited evidence refs resolve through a callback, so the crate stays independent of any evidence-graph representation:

pub enum RiskEvidenceRefKind {
    AuthorityReceipt,
    SupportingEvidence,
    ReserveLedgerReceipt,
    Settlement,
    Jurisdiction,
}

Report envelope and top-level gates

The report deserializes into RiskComptrollerReport. The struct and every nested struct derive #[serde(deny_unknown_fields)], so an unrecognized field fails at deserialization, before any validator runs. The snippet starts below the report struct's two attribute lines, #[derive(Debug, Deserialize)] and #[serde(deny_unknown_fields)], at crates/platform/chio-risk-comptroller/src/lib.rs:15-16.

pub struct RiskComptrollerReport {
    schema: String,
    pub id: String,
    issued_at: String,
    passport_id: String,
    pub order_id: String,
    pub subject: String,
    verdict: String,
    risk_state: String,
    #[serde(default)]
    pub signature: String,
    facility: RiskFacilityState,
    #[serde(default)]
    facility_lifecycle: Vec<RiskFacilityTransition>,
    coverage: RiskCoverageBinding,
    reconciliation: RiskReconciliation,
    #[serde(default)]
    premium: Option<RiskPremiumBinding>,
    actuarial_evidence: RiskActuarialEvidence,
    insurance_copy: RiskInsuranceCopy,
    #[serde(default)]
    capital_decomposition: Option<RiskCapitalDecomposition>,
    #[serde(default)]
    capital_instructions: Vec<RiskCapitalInstruction>,
    #[serde(default)]
    reserve_ledger: Vec<RiskReserveLedgerEntry>,
    #[serde(default)]
    sanction_reserve_ledger: Vec<RiskSanctionReserveLedgerEntry>,
    #[serde(default)]
    appeals: Vec<RiskClaimAppeal>,
    verified_claims: Vec<String>,
}

validate_risk_report starts with fixed envelope gates before it descends into the sub-records:

• Every scalar id field is non-empty, and schema equals chio.risk.comptroller-report.v1.
• passport_id equals the verifying passport's id.
• verdict is verified and risk_state is reconciled. A rejected report is never admitted.
• verified_claims contains the marker claim claim.risk.comptroller_report_bound.

premium and capital_decomposition are Option on the Rust type, and both the schema and the validators require them. A report missing either fails with risk premium binding missing or risk capital decomposition missing.

Authority signature

The signature travels on the report and covers the report body with the signature field removed. The wire form is a colon-delimited triple:

sig-ed25519:<public-key-hex>:<signature-hex>

validate_risk_report_signature rejects an empty trusted-key list up front, parses the prefix, resolves the embedded public key against trusted_authority_keys, strips the signature field, and verifies the remainder with PublicKey::verify_canonical (RFC 8785 canonical JSON). An untrusted signer, a malformed prefix, and a failed verification all fail closed. Receipts use the same canonical-JSON signing model.

Facility states

The facility block declares the facility's current state, its capital and reserve amounts, and a reserve_ref. The reserve is non-zero, at most the capital, and in the capital's currency. The state is one of twelve, in replay order:

1. evidence_cold: Replay origin; no facility yet.
2. underwriting_ready: Underwriting inputs assembled.
3. facility_granted: Facility committed.
4. reserve_held: Reserve carved out of capital.
5. capital_allocatable: Capital ready to allocate.
6. coverage_bound: Coverage bound against the reserve.
7. claim_open: A claim is open on the coverage.
8. claim_decided: Claim adjudicated.
9. payout_matched: Payout observed and reconciled.
10. settlement_matched: Settlement observed and reconciled.
11. reserve_controlled: Residual reserve under control.
12. closed: Facility fully reconciled and closed.

Coverage, capital adequacy, and reconciliation

The coverage block binds an exposure to the facility reserve. It references the report's order_id and subject, the facility's reserve_ref and currency, a status of bound, and a facility state that reaches coverage_bound. The solvency invariant is checked here with checked_add:

exposure_units + reserve_units <= capital_units   // adequacy
exposure_units                 <= capital_units   // exposure fits capital
reserve_units                  <= capital_units   // reserve fits capital

The reconciliation block then balances the money ledger against coverage and facility: its currency matches the coverage, its exposure_units match the coverage, its reserve_units match the facility, consumed_reserve_units stays within the reserve, payout_units equals settlement_units, and status is balanced. A closed facility must have consumed its full reserve, so it leaves nothing unreconciled.

Premium binding

The premium block ties the bound coverage to a quote. It references the same coverage id, order, subject, currency, and exposure, and the bound premium equals the quoted premium. Its status is one of two:

• bound: quoted and bound, with collected_premium_units at zero.
• collected: collected_premium_units equals the bound premium, and observed_payment_ref or settlement_ref is present as collection evidence.

The comptroller checks that the bound and collected amounts agree and leaves pricing to Underwriting, where the premium is set.

Actuarial evidence and insurance copy

The actuarial_evidence block carries a model reference, a supported exposure ceiling, a confidence level in basis points (1..=10000), and a backtest. The backtest has status: passed, a non-inverted RFC 3339 window, a non-zero sample, loss ratios inside 0..=10000 bps, and an observed loss ratio at most its maximum. Coverage exposure stays within the supported exposure.

The insurance_copy is the authority's coverage statement. Its actuarial_evidence_ref equals the actuarial model_ref, and its maximum_coverage_units equals the bound coverage exposure exactly. Undercovering fails with risk insurance copy undercovers exposure and overcovering with risk insurance copy exceeds bound coverage, so the copy can never widen or narrow the coverage the rest of the report rests on.

Capital decomposition

The capital_decomposition breaks the facility commitment into buckets. Its source_kind is facility_commitment, its currency matches the facility, committed_units equals the facility capital, and held_units equals the facility reserve. The available balance is derived:

available_units = committed_units
    - (held_units + drawn_units + disbursed_units + impaired_units)

The deductions are summed with checked_add, so an overflow is a validation error and never a panic, and the remainder is taken with saturating_sub. A declared available_units that disagrees fails with risk capital available mismatch.

Reserve ledger

The reserve_ledger lists movements against the reserve. Each entry is scoped to the facility's reserve_ref and to a claim id inside coverage.covered_claim_ids, and entry ids and receipt refs are unique within the report. The lanes:

Terminal consumption is single-use per (reserve_ref, claim_id) pair within a report; a second terminal entry on the same pair fails with risk reserve double consumption. A reverse_slash unwinds only units a prior reserve_slash consumed on the same pair, up to the amount slashed. The running totals close: summed consumption equals reconciliation.consumed_reserve_units, and summed claim_payout units equal reconciliation.payout_units.

Settlement counterparties

A claim_payout entry carries both a payer_subject and a payee_subject. The payer is the coverage subject; the payee is the coverage's beneficiary_subject when one is set, otherwise the subject itself. A non-payout lane that carries counterparties is rejected, so counterparties appear only where funds move.

Capital instructions

Every claim_payout entry binds exactly one RiskCapitalInstruction, keyed by reserve_entry_id and matching the entry's order, claim, reserve, currency, units, and settlement ref. The instruction is pre-observed, so a report never asserts a payout that has already executed:

intended_action:        transfer_funds
source_kind:            facility_commitment
intended_state:         pending_execution
reconciled_state:       not_observed
observed_execution_ref: <absent>

A report with no payout entries carries no instructions; a dangling instruction fails with risk capital instruction unbound. The observed side of the payout is admitted downstream: Claims Lifecycle covers the payout instruction and receipt stages, and Reconciliation how rail observations close instructions.

Market slash and the sanction bridge

A market_slash entry requires a sanction_bridge bound to the coverage subject and capped by maximum_slash_units, and the entry amount stays within that cap. Each market slash maps one-to-one to an entry in the sanction_reserve_ledger, which repeats the same receipt, reserve, claim, currency, units, and settlement ref plus the bridge's authority receipt, evidence, and jurisdiction refs. A market slash without a matching sanction entry, or a sanction entry without a market slash, fails closed. Liability Market covers the sanction context.

Claim appeals

A RiskClaimAppeal carries a status of open, resolved, denied, or withdrawn, and a non-empty blocks list drawn from claim_payout, reserve_release, reserve_slash, market_slash, facility_closure, and write_off. Appeal ids are unique, and every appeal names a claim inside coverage.covered_claim_ids.

An open appeal blocks only its own claim, and only the lanes it names. A terminal reserve entry on a blocked lane for that claim fails with risk open appeal blocks reserve action, and a closed facility with an open appeal naming facility_closure fails with risk open appeal blocks facility closure. Resolved, denied, and withdrawn appeals block nothing.

Evidence references

A report cites ids for authority receipts, supporting evidence, reserve-ledger receipts, settlement, and jurisdiction. validate_risk_evidence_refs walks them all and calls the caller's contains_ref closure with each ref and its RiskEvidenceRefKind; the crate reads no graph itself. In the proof-room verifier, the closure resolves each kind to a set of allowed node schemas:

• AuthorityReceipt: chio.enterprise.approval-case.v1, chio.risk.guarantee-decision.v1, chio.receipt.v1.
• SupportingEvidence: chio.enterprise.data-governance-report.v1, chio.enterprise.evidence-export-bundle.v1, chio.enterprise.telemetry-projection.v1, chio.enterprise.control-evidence-map.v1, chio.commerce.provider-selection-report.v1.
• ReserveLedgerReceipt: chio.enterprise.approval-case.v1, chio.risk.guarantee-decision.v1, chio.receipt.v1.
• Settlement: chio.enterprise.evidence-export-bundle.v1, chio.web3-settlement-execution-receipt.v2, chio.web3-settlement-proof-bundle.v1, chio.receipt.v1.
• Jurisdiction: chio.risk.adjudication-jurisdiction-receipt.v1, chio.enterprise.approval-case.v1, chio.receipt.v1.

Where the verifier runs

chio-control-plane re-exports the crate as chio_control_plane::risk_comptroller. chio-commerce-order, chio-enterprise-export, chio-trust-market-context, and chio-proof-room consume it wherever a report is admitted as evidence for a Transaction Passport. The CLI path is the proof dispatcher, which writes the verifier report to stdout at crates/products/chio-cli/src/cli/dispatch/proof.rs:560.