Credit Facilities & Bonds

chio-credit is the accounting layer underneath agent autonomy. A facility is a pre-approved spending line, a bond is the collateral that backs that line for a specific call, and the capital book is the per-subject ledger that records every commit, hold, draw, disburse, release, repay, and impair event. This page describes the structures in chio-credit exactly as they ship today.

Credit Facilities

A credit facility is a pre-approved spending line, like a corporate credit card with a ceiling and terms. Once granted, an agent (or its operator) can draw against the facility to fund tool invocations, capped by the ceiling and policy attached to the facility.

Facility Terms

pub struct CreditFacilityTerms {
    pub credit_limit: MonetaryAmount,        // total ceiling
    pub utilization_ceiling_bps: u16,        // max % of limit drawable at once (basis points)
    pub reserve_ratio_bps: u16,              // collateral reserve as % of outstanding
    pub concentration_cap_bps: u16,          // max % of limit toward one provider
    pub ttl_seconds: u64,                    // facility lifetime
    pub capital_source: CreditFacilityCapitalSource,
}

pub enum CreditFacilityCapitalSource {
    OperatorInternal,        // operator's own treasury
    ManualProviderReview,    // requires explicit external review
}

Three independent ratios shape what a facility can do:

• Utilization ceiling: caps concurrent outstanding draws as a fraction of credit_limit. A $10,000 facility with 8,000 bps (80%) ceiling allows up to $8,000 outstanding.
• Reserve ratio: the fraction of outstanding exposure that must be held as locked collateral. 1,500 bps (15%) means $150 of reserve for every $1,000 outstanding.
• Concentration cap: limits exposure to any single counterparty. 3,000 bps (30%) on a $10,000 facility means at most $3,000 routed to one provider at a time.

Facility Dispositions and Lifecycle

The underwriting evaluation rolls into a CreditFacilityDisposition:

• Grant: facility may be issued at the proposed terms.
• ManualReview: borderline; a human or higher-authority signer must approve before issuance.
• Deny: the application fails minimum criteria.

Once issued, the artifact moves through CreditFacilityLifecycleState:

Facility Reason Codes

CreditFacilityReasonCode attaches to findings on the facility report:

• ScoreRestricted, ProbationaryScore, LowConfidence: scorecard gates.
• MixedCurrencyBook: the subject's exposure ledger spans more than one currency, which chio-credit does not currently net across.
• MixedRuntimeAssuranceProvenance, MissingRuntimeAssurance, CertificationNotActive: attestation and certification gates.
• FailedSettlementBacklog, PendingSettlementBacklog: unsettled exposure blocks a fresh facility.
• FacilityGranted: the successful-issuance marker recorded on the report.

Credit Bonds

A bond is the collateral object that backs a specific call against a facility. Like a performance bond on a construction contract, the bond locks capital that can be impaired (seized) if the agent fails to settle or violates policy. Bonds reference their facility by id and carry their own currency-coherent terms.

Bond Terms

pub struct CreditBondTerms {
    pub facility_id: String,
    pub credit_limit: MonetaryAmount,
    pub collateral_amount: MonetaryAmount,
    pub reserve_requirement_amount: MonetaryAmount,
    pub outstanding_exposure_amount: MonetaryAmount,
    pub reserve_ratio_bps: u16,
    pub coverage_ratio_bps: u16,
    pub capital_source: CreditFacilityCapitalSource,
}

The two ratios on a bond have specific meanings:

• Reserve ratio (bps): the fraction of outstanding exposure that must remain locked as reserve.
• Coverage ratio (bps): the fraction of the facility's credit limit covered by this bond's collateral. A coverage ratio of 10,000 bps (100%) means the bond covers the full facility limit.

Bond Lifecycle States

CreditBondLifecycleState tracks where a bond is in its life. Five states ship today:

Bond Disposition Actions

CreditBondDisposition is the action the bond evaluator recommends, distinct from the lifecycle state the artifact lives in. Four actions ship:

• Lock: lock additional collateral against this bond (typical when sizing up a bond before dispatch).
• Hold: place a hold on the bond (collateral cannot be released or drawn against pending investigation).
• Release: return collateral to the source after clean settlement.
• Impair: seize collateral as a credit loss; pairs with a CreditLossLifecycle event.

Bond Reason Codes

Findings on a bond report carry a CreditBondReasonCode: ActiveFacilityMissing, MixedCurrencyBook, PendingSettlementBacklog, FailedSettlementBacklog, ProvisionalLossOutstanding, ReserveLocked, ReserveHeld, ReserveReleased, UnderCollateralized.

Bond Lifecycle Diagram

Exposure Ledger

The exposure ledger answers the question how much is this subject currently on the hook for? It scopes by capability, agent subject, or tool server (one anchor is required) and reports both the receipt-by-receipt detail and an aggregate summary. Its support boundary is explicit:

pub struct ExposureLedgerSupportBoundary {
    pub governed_receipts_authoritative: bool,
    pub underwriting_decisions_authoritative: bool,
    pub settlement_reconciliation_authoritative: bool,
    pub cross_currency_netting_supported: bool,    // false today
    pub claim_adjudication_supported: bool,        // false today
    pub recovery_lifecycle_supported: bool,        // false today
}

Per-currency positions in the ledger track the full exposure picture: governed_max_exposure_units, reserved_units, settled_units, pending_units, failed_units, provisional_loss_units, recovered_units, quoted_premium_units, active_quoted_premium_units.

The ledger is the input to the underwriting evaluator and the scorecard, and it is the authoritative record of which receipts and decisions back a bond.

Capital Book

The capital book aggregates a subject's funding sources and the events that have moved capital through them. Where the exposure ledger is receipt-shaped (what did the agent spend?), the capital book is treasury-shaped (where did the money come from and go?).

Funding Sources

Each entry on the book is a CapitalBookSource tagged with a kind and counterparty roles:

pub enum CapitalBookSourceKind {
    FacilityCommitment,
    ReserveBook,
}

pub enum CapitalBookRole {
    OperatorTreasury,
    ExternalCapitalProvider,
    AgentCounterparty,
}

Event Kinds

Every movement of capital is one of seven CapitalBookEventKind records:

Capital Execution Instructions

Capital movements are dispatched through signed CapitalExecutionInstructionArtifact records. Each instruction carries an authority chain (multi-sig approvers), an execution window, and a rail descriptor:

pub enum CapitalExecutionInstructionAction {
    LockReserve,
    HoldReserve,
    ReleaseReserve,
    TransferFunds,
    CancelInstruction,
}

pub enum CapitalExecutionRailKind {
    Manual,
    Api,
    Ach,
    Wire,
    Ledger,
    Sandbox,
    Web3,
}

pub enum CapitalExecutionRole {
    OperatorTreasury,
    ExternalCapitalProvider,
    AgentCounterparty,
    LiabilityProvider,
    Reinsurer,
    FacilityProvider,
    Custodian,
}

Intended-vs-reconciled state lets external execution catch up with the signed instruction: CapitalExecutionIntendedState is PendingExecution or CancellationPending; CapitalExecutionReconciledState is NotObserved or Matched.

Bonded Execution

Bonded execution is the runtime gate that says this agent has an active bond covering this dispatch, so we can proceed. The gate consults a CreditBondedExecutionControlPolicy on every call:

pub struct CreditBondedExecutionControlPolicy {
    pub version: String,
    pub kill_switch: bool,
    pub maximum_autonomy_tier: Option<GovernedAutonomyTier>,
    pub minimum_runtime_assurance_tier: Option<RuntimeAssuranceTier>,
    pub require_delegated_call_chain: bool,
    pub require_locked_reserve: bool,
    pub deny_if_bond_not_active: bool,
    pub deny_if_outstanding_delinquency: bool,
}

The gate produces a deterministic decision: dispatch proceeds when the bond is active, the runtime assurance tier meets the minimum, the autonomy tier is within bounds, and there is no outstanding delinquency. Otherwise the call is held or denied.

Loss Lifecycle

When a bonded call goes wrong, the bond moves through a loss lifecycle. CreditLossLifecycleEventKind has five variants:

• Delinquency: outstanding obligation past due.
• Recovery: previously delinquent amount recovered.
• ReserveRelease: held reserve released back to the source.
• ReserveSlash: reserve seized to cover the loss.
• WriteOff: portion of the loss formally written off.

Reserve control execution and appeal windows are tracked separately: CreditReserveControlExecutionState is PendingExecution or Executed, and CreditReserveControlAppealState is Unsupported, Open, or Closed.

Worked Example

An issuer creates a USD facility for agent-42 with a $1,000 ceiling, an 8,000 bps utilization ceiling (so up to $800 outstanding at once), and a 1,000 bps reserve ratio (10% of outstanding must be held as locked reserve).

let terms = CreditFacilityTerms {
    credit_limit: MonetaryAmount { units: 100_000, currency: "USD".into() }, // $1,000 in cents
    utilization_ceiling_bps: 8_000,
    reserve_ratio_bps: 1_000,
    concentration_cap_bps: 5_000,
    ttl_seconds: 86_400 * 30, // 30 days
    capital_source: CreditFacilityCapitalSource::OperatorInternal,
};

The agent now wants to make a $100 (10,000 cents) call. Before dispatch, the bonded-execution gate locks 10% of that as bond reserve on top of the $100 draw:

1. Lock: $10 of operator treasury moves to ReserveBook as a Hold event tied to the bond.
2. Draw: $100 is drawn from the facility commitment to fund the call. The exposure ledger now shows pending_units = 10_000 and reserved_units = 1_000.
3. Disburse: on settlement, $100 is disbursed to the provider. The pending position settles to settled_units.
4. Release: the $10 hold is released back to operator treasury. Bond moves to Released.

Dispute path: if the receipt is later disputed and the loss adjudicates against the agent, the bonded reserve can be impaired. A ReserveSlash event records the seizure, and the bond moves to Impaired. The capital book records the seizure as an Impair event with the operator treasury as owner role.

Worked Exposure Ledger Trace

Walk through a $1,000 facility with a 10% bond ratio across four events: lock the bond, draw against the facility, disburse on settlement, release the bond. Each line is a snapshot of the per-source ledger position on the capital book after the event lands; the JSON below shows the matching CreditBondArtifact view.

The seven event kinds tracked on the capital book, verbatim:

pub enum CapitalBookEventKind {
    Commit,
    Hold,
    Draw,
    Disburse,
    Release,
    Repay,
    Impair,
}

1. Lock the bond

The bonded-execution gate locks $100 (10% of the $1,000 facility ceiling) onto the reserve book as a Hold event. Position on the facility commitment source:

source: facility-cap-001
  committed:  1000.00 USD
  held:        100.00 USD
  drawn:         0.00 USD
  available:   900.00 USD

{
  "schema": "chio.credit.bond.v1",
  "bondId": "bond-vanguard-soc2-001",
  "issuedAt": 1735000000,
  "expiresAt": 1735086400,
  "lifecycleState": "active",
  "report": {
    "terms": {
      "facilityId": "facility-lattice-001",
      "creditLimit":             { "units": 100000, "currency": "USD" },
      "collateralAmount":        { "units": 10000,  "currency": "USD" },
      "reserveRequirementAmount":{ "units": 10000,  "currency": "USD" },
      "outstandingExposureAmount":{ "units": 0,     "currency": "USD" },
      "reserveRatioBps":   1000,
      "coverageRatioBps":  10000,
      "capitalSource":     "operator_internal"
    }
  }
}

2. Draw $100

The agent draws $100 from the facility commitment to fund the call. A Draw event lands on the capital book; the bond now backs $100 of outstanding exposure.

source: facility-cap-001
  committed:  1000.00 USD
  held:        100.00 USD
  drawn:       100.00 USD
  available:   800.00 USD

{
  "bondId": "bond-vanguard-soc2-001",
  "lifecycleState": "active",
  "report": {
    "terms": {
      "facilityId": "facility-lattice-001",
      "creditLimit":              { "units": 100000, "currency": "USD" },
      "collateralAmount":         { "units": 10000,  "currency": "USD" },
      "reserveRequirementAmount": { "units": 10000,  "currency": "USD" },
      "outstandingExposureAmount":{ "units": 10000,  "currency": "USD" },
      "reserveRatioBps":  1000,
      "coverageRatioBps": 10000,
      "capitalSource":    "operator_internal"
    }
  }
}

3. Disburse on settlement

On settlement, $100 is disbursed to the provider. A Disburse event records the payout; the position shifts from pending to settled on the exposure ledger.

source: facility-cap-001
  committed:  1000.00 USD
  held:        100.00 USD
  drawn:       100.00 USD
  disbursed:   100.00 USD
  pending:       0.00 USD
  settled:     100.00 USD
  available:   800.00 USD

{
  "bondId": "bond-vanguard-soc2-001",
  "lifecycleState": "active",
  "report": {
    "terms": {
      "facilityId": "facility-lattice-001",
      "creditLimit":              { "units": 100000, "currency": "USD" },
      "collateralAmount":         { "units": 10000,  "currency": "USD" },
      "reserveRequirementAmount": { "units": 10000,  "currency": "USD" },
      "outstandingExposureAmount":{ "units": 10000,  "currency": "USD" },
      "reserveRatioBps":  1000,
      "coverageRatioBps": 10000,
      "capitalSource":    "operator_internal"
    }
  }
}

4. Release the bond

With no outstanding exposure left, the operator releases the bond. A Release event returns the $100 hold to operator treasury; the bond moves to Released.

source: facility-cap-001
  committed:  1000.00 USD
  held:          0.00 USD
  drawn:       100.00 USD
  disbursed:   100.00 USD
  settled:     100.00 USD
  available:   900.00 USD

{
  "bondId": "bond-vanguard-soc2-001",
  "lifecycleState": "released",
  "report": {
    "terms": {
      "facilityId": "facility-lattice-001",
      "creditLimit":              { "units": 100000, "currency": "USD" },
      "collateralAmount":         { "units": 0,      "currency": "USD" },
      "reserveRequirementAmount": { "units": 0,      "currency": "USD" },
      "outstandingExposureAmount":{ "units": 0,      "currency": "USD" },
      "reserveRatioBps":  1000,
      "coverageRatioBps": 10000,
      "capitalSource":    "operator_internal"
    }
  }
}

The facility is back at available = 900 with a clean bond cycle on the books. The same source-of-funds position would surface as a CapitalBookSummary entry on the next signed report.

Next Steps

• Underwriting Risk Taxonomy : the inputs that decide whether a facility is granted.
• Scorecards : the credit scorecard that summarizes the subject's exposure and reputation context.
• Reconciliation : how external rails reconcile capital execution back into the capital book.
• Claims Lifecycle : how an insured loss reconciles back into facility and bond accounting.
• Settlement : the rails that actually move capital across counterparties.
• Credit & Underwriting Guide : narrative walkthrough that ties this reference to the CLI.