Protocol Reference

Contract scope

The contract connects delegated authority, runtime decisions, signed evidence, and cross-operator trust. An agent presents bounded permission, a kernel enforces it, and another operator verifies the resulting records under its own trust policy.

A section that names an adapter, bridge, external rail, hosted tool, or directory is normative only for the bounded record or kernel-owned path it describes. Trace-only provider activity, remote hosted execution, and advisory directory data never become an authoritative authorization receipt.

Interfaces in the v1 contract

HTTP and OpenAPI interfaces

• an HTTP sidecar protocol that protects arbitrary HTTP APIs through Chio policy evaluation, typed HTTP receipts, and structured verdicts (HTTP Transport)
• an OpenAPI-to-manifest pipeline that derives chio.manifest.v1 tool definitions from OpenAPI specifications with x-chio-* policy extensions (OpenAPI Integration)
• a reverse-proxy entrypoint, chio api protect, that combines OpenAPI ingestion, sidecar evaluation, and live traffic enforcement
• the chio cert generate, chio cert verify, and chio cert inspect commands, which generate, verify, and inspect compliance certificates for an ACP session

These interfaces share the receipt, capability, and policy types below. HttpReceipt has its own signing payload. Converting it to a signed ChioReceipt requires the matching kernel keypair and a fresh core signature. Verify each representation under its own contract; the HTTP signature is not transferable. The conversion and its field mapping are on HTTP Transport.

Compatibility rule

• Additive fields may appear in JSON responses and signed records.
• Unknown schema identifiers for schema-tagged records must be rejected.
• Fail-closed behavior is part of the protocol contract.

Exclusions from the v1 contract

An adjacent interface never implies any of these, and the v1 contract excludes each one:

• a replacement of MCP or A2A at the wire-protocol level
• multi-region consensus or Byzantine replication
• theorem-prover completion for concrete crypto, platform, or external-service behavior beyond the published audited assumptions
• arbitrary plugins that can redefine signed Chio truth or widen trust outside named extension points
• a permissionless or auto-trusting public federation or certification marketplace, beyond the documented federation-activation exchange, quorum, open-admission, reputation-clearing, and qualification interfaces
• permissionless mirror or indexer publication as automatic trust, sanction, or market-penalty authority
• portable reputation as a universal trust oracle, or synthetic cross-issuer passport scoring
• automatic SCIM provisioning lifecycle, or automatic enterprise identity propagation into every portable record
• permissionless public identity or wallet discovery that widens local trust, and automatic wallet distribution for passports
• generic OID4VP, SIOP, DIDComm, or permissionless wallet-network compatibility beyond the documented public identity-profile and routing contract
• permissionless anchor discovery or arbitrary chain anchoring beyond the documented EVM, OpenTimestamps, and Solana memo lanes
• arbitrary cross-chain fund routing, generic keeper authority, direct fund release from Functions or paymaster infrastructure, or arbitrary external capital dispatch beyond the documented web3 interop interfaces
• autonomous insurer-rate setting beyond the documented autonomous-pricing, capital-pool, rollback, live-capital, reserve-control, payout, and settlement interfaces

Components and trust boundaries

Agent

Untrusted caller that presents a capability or authenticates to a hosted edge.

Kernel

Trusted mediator that validates capabilities, runs guards, dispatches calls, and signs receipts.

Tool server

Native or wrapped implementation of tools, resources, and prompts.

Trust-control

Operator-facing authority, receipt, revocation, budget, federation, and certification service.

Hosted MCP edge

chio mcp serve-http, which exposes an MCP-compatible HTTP API with remote session lifecycle and admin APIs.

Operator stores

SQLite stores and file-backed registries for authoritative local state.

The security boundary is constant across these components:

• agents receive no ambient authority
• every mediated action is bound to an explicit capability or authenticated hosted session state
• denials are explicit, signed, and auditable
• extensions replace only named integration points and preserve local policy activation and signed Chio records
• registry and record mismatches fail closed

Serialization and identity

Canonical JSON

Signed Chio records use canonical JSON serialization (RFC 8785 JCS) before signing. Classical records are Ed25519 by default. Post-quantum hybrid records use the hybrid:<classical>:<pq>:<alg_set> string prefix, where pq is ML-DSA-65 bytes as lowercase hex and alg_set is one of ed25519+mldsa65, p256+mldsa65, or p384+mldsa65. Verifiers dispatch from the self-describing signature prefix and reject malformed or mismatched hybrid halves fail-closed. The rule covers capability tokens, receipts, manifests, checkpoints, verifier policies, passport presentations, and certification records.

Native wire format

The native agent-to-kernel protocol uses length-prefixed JSON messages with a type discriminator. The core messages are AgentMessage and KernelMessage in crates/core/chio-core-types/src/message.rs. The normative wire definition is on Wire Protocol.

• Request examples: tool_call_request, list_capabilities, heartbeat.
• Response examples: tool_call_chunk, tool_call_response, capability_list, capability_revoked, heartbeat.

Hosted wire format

The hosted edge uses MCP-compatible HTTP semantics in place of the native length-prefixed transport:

• JSON-RPC over HTTP POST
• standalone GET and SSE streams where the hosted edge supports them
• bearer-token or JWT-backed session admission
• remote admin APIs under /admin/...

The hosted contract:

• initialize is a POST /mcp request; there is no GET bootstrap.
• A successful initialize returns an SSE response plus MCP-Session-Id.
• Clients send notifications/initialized before relying on ready-state methods such as tools/list or tools/call.
• GET /mcp is the live-and-replay notification stream, with Last-Event-ID as the replay cursor.
• Shared-owner hosted deployments may reuse one upstream subprocess, but task handles and late notifications stay scoped to the originating session.
• Caller-supplied model metadata is preserved on the request path, and its provenance enters Chio as asserted until a trusted subsystem upgrades it.

Identity

Ed25519 keys are the primary cryptographic identity. Hybrid public keys use the same self-describing prefix discipline as signatures, hybrid:<classical-public-key>:<mldsa65-public-key>:<alg_set>, and classical encodings stay byte-identical. did:chio is the self-certifying DID method for those keys:

did:chio:{64-hex-ed25519-public-key}

Resolution is local and self-certifying. The resolving environment may attach optional service endpoints, such as a receipt-log URL. Public identity profiles may also name did:web, did:key, and did:jwk as compatibility inputs for wallet or issuer interoperability; did:chio stays the canonical provenance anchor.

Capability contract

The capability token is CapabilityToken from crates/core/chio-core-types. Capability tokens are schema-tagged signed records: newly issued tokens carry schema: "chio.capability.v1" in the schema-aware signing input, and load-time and verify-time paths reject any unknown capability schema.

CapabilityToken fields

Required fields follow the v1 JSON schema. Optional means the property may be omitted from the wire envelope; delegation and constraint rules can require additional evidence for a particular token.

Public-key fields and signatures use the self-describing encoding from the serialization section. A hybrid token sets algorithm: "hybrid" and encodes issuer, subject, delegation-link keys, and signatures as hybrid:<classical>:<mldsa65-hex>:<alg_set>. Verifiers MUST dispatch from the signature prefix, confirm that any present algorithm hint matches that prefix, and reject mismatches fail-closed. The algorithm enum MUST NOT contain concrete algorithm-set strings such as ed25519+mldsa65; those live only inside the hybrid wire value.

Scope

The scope model holds three grant lists:

• grants: Vec<ToolGrant>
• resource_grants: Vec<ResourceGrant>
• prompt_grants: Vec<PromptGrant>

ToolGrant includes:

• server_id, tool_name, operations, constraints
• max_invocations, max_cost_per_invocation, max_total_cost
• optional dpop_required

The Constraint enum has 27 variants. The portable matcher decides 8 of them from the call arguments and refuses the remaining 19 by name. The variants include ordinary argument constraints, the governed-transaction controls governed_intent_required, require_approval_above, and seller_exact, and the delivery controls output_digest_sha256 (the expected post-transform output digest, enforced at the output-aware durable terminal), require_finding_purchase (a provider-signed purchase marker binding finding_id, listing_id, and a closed settlement selector whose modes are local_reversible_hold and cross_org_escrow with a pinned settlement_profile_sha256), and require_finding_recovery (a no-charge recovery marker binding the original capability, the settled purchase, the successful delivery receipt, and one durable attempt ceiling shared by every deterministic re-mint).

Recovery capabilities are undelegated, DPoP-bound, single-grant authorities with exactly one output digest and no monetary ceiling. An interface without the matching output-aware, purchase-aware, or recovery-aware admission rejects these delivery controls fail-closed before any budget or payment mutation. Their Custom-keyed spellings, including the retired receipt-keyed and capability-keyed recovery aliases, are rejected as downgrade attempts.

Capability attenuation

chio.capability.v1 carries delegation and attenuation in the signed token body:

• reserved caveats with { kind, predicate, sig? }; nonempty values are rejected because admission does not evaluate these predicates
• scope_attenuations carrying the narrowing operations
• attenuation_proof with parentScopeHash, childScopeHash, and a normalizedSubsetProof
• optional budget_share_bps, a fixed-point child budget share capped at 10000; a larger value fails closed because it would re-amplify parent authority

Minting and verification use the witness API:

compute_attenuation_witness(parent: &ChioScope, child: &ChioScope)
verify_attenuation_witness(parent_hash, child_hash, witness)

Both paths check that the child scope hash in the proof matches the token scope, that the witness hashes match the normalized scopes, and that every recorded grant relation is a subset.

For a token requiring attenuation binding, the chain-binding rule binds attenuation_proof.parent_scope_hash to the upstream lineage. Every delegation hop in that token must carry a signed DelegationLink.scope_hash. A direct-issue token (empty delegation_chain) MUST have parent_scope_hash equal to the verifier's trust-root scope hash for the issuing authority; a delegated token MUST have it equal to delegation_chain.last().scope_hash; a chain whose hops omit scope_hash is rejected fail-closed. The rule stops an issuer from claiming a larger parent scope behind an internally consistent witness. A violation surfaces CapabilityError::AttenuationViolation with the offending hashes as hex.

Full capability verification combines signature and issuer trust, crypto-floor and time checks, parent-scope binding, negotiated features, and sibling-budget admission. Use verify_capability_full_with_root when delegated family evidence requires a direct root. The hosted kernel first verifies with a non-mutating registry, then admits the sibling share after its other checks pass. Partial verification helpers cover only part of this admission contract.

The Lean theorem theorem.attenuation.witness_soundness covers the modeled chain-binding check. Runtime enforcement also depends on authenticated parent resolution and the installed budget registry.

Aggregate invocation budgets and threshold approval

The per-token budget_share_bps cap bounds one child; the sibling-sum rule bounds them together. Without it, a parent at 5000 bps could mint two children at 4000 bps each and per-token validation would accept both. The verifier keeps a per-parent BudgetRegistry (chio_kernel_core::InMemoryBudgetRegistry by default). When it admits a freshly delegated child, it asks the registry whether the parent has enough remaining headroom; if the admitted sibling shares plus the new share would exceed the parent's share, verification fails closed with CapabilityError::BudgetSplitRejected(BudgetSplitError::OversubscribedSiblings).

The check composes across hops against the immediate parent's admitted share. Re-admitting the same child id with the same share succeeds silently; a different share for the same id is a hard failure. The running sum is computed in u32, so two u16::MAX siblings cannot wrap the cap. Full delegated evaluation uses evaluate_with_full_floor or evaluate_with_full_floor_and_root; the evaluate_with_crypto_floor_and_budgets entry point rejects attenuation proofs because it has no parent resolver. The Lean theorem theorem.budget.sibling_sum_soundness models the admit check. The in-memory registry enforces one process's admitted shares; independent kernels coordinate their allocations through a shared authority.

Aggregate invocation quota

An aggregate_invocation_budget bounds invocations across every grant in one capability or across every descendant in one delegation family. The crate type carries scope (capability or delegation_family), max_invocations, and an optional root_binding. Capability scope uses the capability id as the quota owner. Delegation-family scope derives the owner from a verified, CA-signed chio.aggregate-budget-root.v1 binding whose body names the root capability id and hash, root issuer and subject, maximum, root expiry, and root scope hash.

A family descendant MUST carry the identical root binding and signed maximum from its direct root and MUST NOT lower, raise, omit, replace, or create that family budget. A maximum of zero is valid and denies every capture. The verifier MUST authenticate the direct root token and bind the root capability id, root commitment hash, issuer, subject, scope hash, expiry, maximum, root-binding signature, and descendant binding digest. Presented delegation metadata carries no authority for a family owner: an untrusted root, forged field, changed digest, or missing direct-root token is a denial.

When a request is covered by grant, aggregate, or supplemental invocation quotas, the durable authority authorizes and captures the complete sorted quota set atomically; exhaustion or an immutable-maximum mismatch on any member leaves every member unchanged. Supplemental authorization is opaque caller input until an installed verifier returns a claim bound to the subject, request, destination, validity window, and authority state; a caller cannot construct a quota claim directly.

Threshold approval proposal and verified set

A governed operation that requires threshold approval uses a signed chio.threshold-approval-proposal.v1 from the active policy authority. The proposal fixes the request id, governed intent hash, subject, authorizing capability digest, policy hash, distinct eligible-key set digest, exact threshold, creation time, and deadline. Approval tokens count once per distinct eligible public key and MUST fall inside the proposal window. The verified set sorts the distinct token digests before applying the chio.verified-approval-set.v1 domain-separated hash, so token order cannot change the set hash or the decision.

On the policy side the threshold comes from the HushSpec extension human_in_loop.approvers with n, of, and an optional timeout_seconds. The policy compiler refuses a policy whose approvers cannot be resolved through an authenticated approver directory, an approver whose identifier the directory changes, and a set that resolves from more than one versioned directory. A peer that lacks the negotiated feature is denied these features; they never downgrade.

Capability negotiation

Federated peers exchange chio.capabilities.v1 during trust establishment. The envelope carries a string-keyed feature bitset, and optional feature use follows the negotiated profile. Attenuated tokens still require chain binding: an explicit peer opt-out rejects them. Malformed feature names and unsupported schema ids fail closed before a peer can use a negotiated feature. The keys are:

• accepts_anchor_batch_v1
• accepts_hybrid_signatures
• delegation_chain_binding
• aggregate_invocation_budget
• cumulative_approval_budget
• threshold_governed_approvals
• governed_active_response_plan

Peers that advertise no bitset stay on the v1 default. Capability schema selection is fixed: chio.capability.v1 is the only Chio-owned token schema runtime verifiers accept.

Governed transaction extensions

Tool-call requests may attach the following governed objects:

• governed_intent: a canonical request intent carrying id, server_id, tool_name, purpose, optional max_amount, optional seller-scoped commerce { seller, shared_payment_token_id }, optional metered_billing { settlement_mode, quote, max_billed_units }, optional asserted call_chain { chain_id, parent_request_id, parent_receipt_id?, origin_subject, delegator_subject }, and optional structured context.
• approval_token: a signed approval token bound to one subject, one request id, and one governed intent hash.
• approval_tokens and threshold_approval_proposal: the approval set and proposal for threshold approval. They must be supplied together; mixing the singular token with the set is rejected.

metered_billing.quote is the rail-neutral pre-execution estimate for non-rail tools: quote_id, provider, billing_unit, quoted_units, quoted_cost { units, currency }, issued_at, and optional expires_at. metered_billing.settlement_mode is one of must_prepay, hold_capture, or allow_then_settle. Both are evidence and operator context; the kernel still enforces issued budgets and explicit governed limits.

When a matched grant includes governed_intent_required, the kernel requires governed_intent. When a matched grant includes require_approval_above { threshold_units }, the kernel requires a valid approval_token whenever the provisional charged amount meets or exceeds that threshold. When a matched grant includes seller_exact, the kernel requires seller-scoped commerce approval context and denies if the governed seller differs from the grant seller scope.

Approval tokens are verified against trusted authority keys and are bound to:

• the request request_id
• the capability subject
• the canonical hash of the attached governed intent
• approval-token issued_at and expires_at time bounds

If governed_intent.call_chain is present, the kernel rejects empty fields and self-referential parent_request_id == request_id bindings. That input is always asserted provenance at admission time, and Chio upgrades it to observed or verified only when the runtime binds it to local request lineage, a signed receipt-lineage statement, or a verified continuation token scoped by the relevant session anchor.

Provenance evidence classes

The provenance model distinguishes three evidence classes:

• asserted: caller-supplied context that Chio preserves without independent authentication
• observed: local lineage facts Chio directly observed inside one authenticated session
• verified: lineage Chio checked against signed records such as chio.session_anchor.v1, chio.receipt_lineage_statement.v1, or chio.call_chain_continuation.v1

Verification rules

The kernel and the trust-control service verify at minimum the rules below, before guards or tools run.

Any failure denies or rejects the action instead of widening access.

Safety properties and evidence boundary

The safety inventory, with the evidence kinds and the number of named proofs the proof manifest records for each property:

The proof manifest connects bounded Lean protocol models, extracted Rust helpers, refinement harnesses, and declared external assumptions. A listed symbol or proof count identifies coverage of the modeled property, not every call or external service. Formal Assurance connects these evidence classes to the kernel.

Verified core boundary

The implementation-linked verified-core contract is defined in formal/proof-manifest.toml, with external-system assumptions in formal/assumptions.toml and theorem coverage in formal/theorem-inventory.json. The manifest names the Rust symbols inside the proof-facing boundary:

• chio_kernel_core::capability_verify::{verify_capability, verify_capability_with_trusted}
• chio_kernel_core::scope::{resolve_matching_grants, resolve_capability_grants}
• chio_kernel_core::evaluate::evaluate
• chio_kernel_core::receipts::sign_receipt

Shell entrypoints listed by the manifest include chio_kernel::ChioKernel::evaluate_portable_verdict and chio_kernel::ChioKernel::build_and_sign_receipt. Anything outside the manifest is outside the proof boundary; concrete cryptography, clocks, storage, transport, subprocess behavior, hosted registries, clustering, and external settlement rails are assumption-bound unless they receive their own manifest entry and proof lane.

Signed-artifact registry

spec/schemas/registry.json is the signed-artifact compatibility registry. Every signed record schema id that a verifier accepts must be listed there, and verifier builds expose the same ids through KNOWN_SIGNED_ARTIFACT_SCHEMAS. An unknown signed-artifact schema is rejected at load time and again at signature verification time. At registry version 1.0.0 the registry lists 382 schema ids across 32 families; the chio-wire family registers 13 of them.

Other contracts register their signed schemas the same way. The FROST quorum contract registers chio.frost.roster.v1, chio.frost.epoch-checkpoint.v1, chio.frost.authorization-slot-checkpoint.v1, and chio.frost.authorization.v1; the parametric-insurance contract registers chio.parametric.policy.v1; the credit-admission contract registers chio.credit.facility-bind.v1; the receivables-factoring contract registers chio.obligation.status-proof.v1, chio.credit.receivable-iou-envelope.v1, and the four chio.factor.assignment-* envelopes; and verified-outcome pricing registers the chio.outcome.* schemas with the outcome_ registry kinds, while chio.outcome.request.v1 and chio.outcome.verdict.v1 are unsigned projections.

The factoring projections chio.factor.normalized-assignment-request.v1, chio.factor.receivable-claim.v1, chio.factor.assignment-offer.v1, and chio.factor.discount-quote.v1 are unsigned and become evidence only through an exact digest bound by a signed record; a receivables verifier MUST reject every unknown schema version before signature verification and MUST NOT downgrade, reinterpret, or fall back to a known version.

Roster, epoch-checkpoint, and authorization-slot signatures MUST verify against separately configured Ed25519 trust roots for their exact authority role and key id. Those records carry key ids, never authority public keys, and a verifier MUST reject an embedded-key field, an unknown key id, a key trusted for another role, or a signature that fails to verify over the record's domain-separated RFC 8785 preimage under the prefixes CHIO-FROST-ROSTER-V1\0, CHIO-FROST-EPOCH-CHECKPOINT-V1\0, and CHIO-FROST-AUTHORIZATION-SLOT-CHECKPOINT-V1\0. Checkpoint digests commit the signed checkpoint including its authority signature; sequence one has no predecessor and every later sequence names the previous checkpoint digest. An active authorization verifier MUST reread and authenticate the rollback-independent epoch checkpoint immediately before execution, MUST authenticate the exact permanently completed authorization-slot checkpoint, and MUST compare its canonical authorization blob byte for byte. Schema validity alone is never signature or trust-root validity.

Receipt contract

The v1 receipt envelope is ChioReceipt from crates/core/chio-core-types. Authority is structural: a receipt's receipt_kind, boundary_class, and trust_level together determine whether it is an authorization or only evidence.

ChioReceipt fields

Each field below is part of the signed envelope. Receipt Format gives the generated Rust types, omission rules, and signing coverage.

id

Authoritative content-addressed receipt identifier.

timestamp

Unix timestamp seconds.

capability_id

Capability exercised or presented.

tool_server

Target server id.

tool_name

Target tool.

action

Canonicalized tool parameters plus parameter_hash.

receipt_kind

mediated_decision, trace_observation, or advisory_evaluation.

boundary_class

Runtime boundary: prevent, detect_only, or advisory_only.

observation_outcome

Trace or advisory outcome; omitted for mediated decisions.

tool_origin

Where the tool effect executed relative to Chio.

redaction_mode

Signed redaction mode for receipt details.

actor_chain

Signed actor attribution chain.

decision

Present only for mediated_decision plus prevent receipts; omitted on trace and advisory receipts.

content_hash

Hash of the evaluated content or outcome payload.

policy_hash

Hash of the policy material used.

evidence

Per-guard evidence.

metadata

Optional structured metadata; the reserved keys are listed under receipt metadata.

trust_level

mediated, verified, or advisory, coherent with receipt_kind.

tenant_id

Optional authenticated tenant id.

bbs_projection_version

Present only when bbs_signature is present, included in the receipt id, and fixed to chio.bbs-projection.receipt.v1.

kernel_key

Verifying public key: bare 64-hex Ed25519, p256:<130-hex> SEC1 P-256, p384:<194-hex> SEC1 P-384, or an algorithm-tagged hybrid key. Exact encodings.

bbs_signature

Optional BBS material for selective disclosure; when present it is covered by the authoritative receipt signature.

algorithm

Optional envelope hint (ed25519, p256, p384, or hybrid); verification dispatches off the signature prefix.

signature

Algorithm-aware signature over canonical JSON of ChioReceiptSigningBody { id, body: ChioReceiptIdInput, bbs_signature? }. The receipt schema encoding reference gives the exact classical and hybrid patterns.

Receipt kinds and decisions

The receipt_kind tri-state binds each receipt's boundary class, trust level, and decision presence:

• mediated_decision receipts use boundary_class = prevent, trust_level = mediated, and MUST carry a decision.
• trace_observation receipts use boundary_class = detect_only, trust_level = verified, and MUST omit decision.
• advisory_evaluation receipts use boundary_class = advisory_only, trust_level = advisory, and MUST omit decision.

Only mediated_decision plus prevent plus Allow may be displayed or exported as authorization. Trace and advisory records can be evidence, but they are never authorization receipts.

When present, the decision enum (wire tag verdict) is:

• Allow (allow): The tool call was allowed and executed.
• Deny { reason, guard } (deny): The tool call was denied.
• Cancelled { reason } (cancelled): The tool call was interrupted by explicit cancellation.
• Incomplete { reason } (incomplete): The tool call did not reach a complete terminal result.

Cancelled and incomplete outcomes are preserved explicitly as their own variants instead of collapsing into an undifferentiated error state.

WYSIWYS signing invariant

chio_kernel_core::sign_receipt recomputes content_hash from the supplied receipt-content preimage and refuses a mismatched body with ContentHashMismatch before the kernel-key check or signing. Depending on the receipt path, the preimage can be canonical output JSON, stream digest material, canonical null, or redacted receipt content.

The producer must bind that preimage to the evaluated or displayed artifact. The signer checks the bytes supplied to it; what a separate interface rendered is outside what signature verification establishes.

One exception exists. sign_receipt_relaying_trusted_body is the auditable trusted-relay entrypoint for thin FFI and WASM transport adapters (mobile FFI, browser WASM, C++ FFI) that receive an already-minted, serialized receipt body across their boundary and hold no content preimage. It trusts the caller-supplied content_hash while still enforcing the kernel-key match. It MUST NOT be used on any path that holds the evaluated content; every such path MUST call sign_receipt or the one-time-handle variant that delegates to it.

Receipt identity and lineage

chio.receipt.v1 is content-addressed, and id is the authoritative identity. The id input contains every receipt body field except id; it includes bbs_projection_version when present and excludes the bbs_signature bytes.

id = H(canonical_jcs(ChioReceiptIdInput))
ChioReceiptSigningBody { id, body: ChioReceiptIdInput }
ChioReceiptSigningBody { id, body: ChioReceiptIdInput, bbs_signature }
metadata["chio_receipt_signing_nonce"] = nonblank_pre_binding_id

Preparation validates the body, copies a nonblank caller-supplied id into metadata.chio_receipt_signing_nonce, then computes the authoritative content-addressed id. The metadata value is covered by both the id and signature. A non-object caller metadata value is preserved under original_metadata. Blank caller ids skip nonce insertion. Prepare a body once: preparing an already-prepared body again can change its nonce and id.

The producer canonicalizes the signing wrapper with RFC 8785 JCS and signs the bytes with the kernel identity key. Verifiers dispatch off the signature prefix: bare lowercase 128-hex is Ed25519 with a bare 64-hex kernel_key; p256:<DER hex> is ECDSA P-256 with a p256:<130-hex> uncompressed SEC1 key; p384:<DER hex> is ECDSA P-384 with a p384:<194-hex> key. Hybrid signatures pair a supported classical algorithm with ML-DSA-65 under the algorithm-tagged prefix described in Receipt Format. The P-256 and P-384 DER bodies are variable length and length-aware decoders validate them downstream of the schema regex.

A present algorithm hint MUST agree with the signature prefix; use verify_signature_with_floor to enforce the hint and configured crypto policy, which plain verify_signature skips. The signing input is the typed wrapper, never ad hoc byte concatenation: verifiers reconstruct the wrapper, re-canonicalize it, select the algorithm from the prefix, and only then verify against the embedded kernel_key, which must agree with the same prefix. Verifiers recompute id from canonical content before accepting the signature. A consumer separately establishes whether that signing key is trusted for its use.

A receipt id identifies one signed evaluation record. Cross-request and cross-kernel relationships use separate signed lineage statements and continuation tokens. Swarm joins use their own SwarmJoinReceipt record and bundle verifier; parent sets and DAG ordinal checks belong to that record, outside the base ChioReceipt envelope. Swarm Protocol specifies that contract.

Authoritative spend

The chio.mediated_spend.v1 receipt predicate verifies the signed record and admitted signer, an Allow decision with mediated_decision, prevent, and mediated structure, reconciled budget evidence, and the linked execution nonce's call and hold bindings.

Runtime execution-nonce admission separately checks the expected subject, nonempty request id, expiry, and replay state. Apply the configured guarantee-floor check as well: the backing store's guarantees come from that check, not from the receipt predicate.

The guarantee classes are single_node_atomic, ha_linearizable, partition_escrowed, and advisory_posthoc. Their use must agree with the installed authority. Authoritative Spend gives the complete acceptance rule.

Child receipts

Nested flows such as sampling, elicitation, and resource reads use ChildRequestReceipt, which records session_id, parent_request_id, request_id, operation_kind, terminal_state, outcome_hash, policy_hash, and optional metadata.

HTTP receipts

The HTTP sidecar returns HttpReceipt, which binds the request identifier, method, route pattern, caller identity hash, request-content hash, verdict, and guard evidence. It carries hashes of request and identity context, never raw authentication headers or the complete request. The core ChioReceipt is the representation used by core receipt stores, checkpoints, and evidence exports.

The library helper to_chio_receipt_with_keypair constructs a core action from method, route pattern, and request ID; uses server http and tool METHOD route_pattern; maps the verdict; recomputes the core content hash; and signs the new core record with the matching kernel keypair. Core signing derives a new content-addressed ID and retains the input HTTP ID in the signed nonce metadata. The no-keypair helper fails closed. This library conversion is distinct from the proxy's separate chio_http_authority kernel decision receipt, linked through metadata.chio_kernel_receipt_id. HTTP Transport covers the conversion and HTTP Proxy the two stored records.

Receipt metadata

The receipt signature authenticates the metadata bytes. Consumers also decode and validate each block they rely on. Closed, versioned blocks such as delivery_contract reject unsupported shapes and schema versions through typed validators, a step separate from signature verification. Reserved key handling is specific to the producer path: the delivery path rejects collisions, while generic metadata merging can overwrite nested values.

Key names are defined in crates/core/chio-core-types/src/receipt/metadata.rs. The following blocks carry explicit schema identifiers:

• admission_operation (chio.admission-receipt.v1) on durable governed calls binds the receipt to the admission operation and request namespace, terminal projection and dispatch state, trusted time, coordinator lease and store fence, retained dispatch commit, and optional tool outcome.
• delivery_contract (chio.delivery-contract.v1) records the grant's expected_digest, a receipt-visible observed_digest, and the comparison result. On a match, the observed value is the delivered output digest. On a mismatch, it is a domain-separated redaction commitment; the delivered output and digest stay in privileged durable evidence. The enclosing receipt authenticates the block.
• finding_delivery (chio.finding.delivery.v1) on a reveal admitted under a provider-signed purchase marker names the finding_id and listing_id, the kernel-proved transform_profile, the digest_check and media_type_check comparisons, the settlement_mode, the canonical digests of the accepted-bid and venue-admission envelopes, and the authoritative reservation_id, purchase_intent_id, and authoritative_payment_operation_id. Every field derives from kernel-verified state, and the block appears only when the purchase context arrived through verified signed records.

The governed_transaction block carries intent_id, intent_hash, purpose, server_id, tool_name, and optional max_amount, commerce, metered_billing, approval, runtime_assurance, and call_chain blocks. runtime_assurance.tier is the accepted tier after any configured verifier trust-policy rebinding, and call_chain records the strongest provenance projection Chio signs for the receipt, with the original caller assertion kept separately under assertedContext. Governed receipt metadata also admits a versioned economic_authorization envelope with version, economic_mode, payer, merchant, payee, rail, amount_bounds, optional pricing_basis, metering, and liability_refs, budget, and settlement; it is additive and the compatibility fields stay intact.

Trust-control keeps mutable settlement reconciliation state keyed by receipt_id and reports it beside the signed financial.settlement_status; the signed receipt never changes. Post-execution metered evidence from an external adapter is stored in a mutable sidecar keyed by receipt_id and is never merged into the signed receipt JSON. Exporter, report, and OpenTelemetry projections are authoritative receipt truth only when they embed and verify the full signed ChioReceipt; a consumer that needs authorization, billing, lineage, or audit authority must verify the signed receipt or a signed receipt-lineage statement and fail closed when that record is missing, stale, malformed, or mismatched.

Reserved receipt metadata keys

Evidence record families

These records connect receipts to provenance, coordinated execution, commerce, disclosure, and information markets. Each family has its own verification rules.

Provenance graph records

• chio.session_anchor.v1: session anchors capture authenticated session continuity, binding session_id, agent_id, transport and auth context, proof-binding material, and auth epoch
• chio.request_lineage_record.v1: request-lineage records capture request nodes and local parent edges, keyed by request_id
• chio.receipt_lineage_statement.v1: receipt-lineage statements capture authenticated receipt-to-receipt edges
• chio.call_chain_continuation.v1: continuation tokens capture authenticated cross-kernel or cross-session provenance transfer

Receipts prove kernel-observed evaluation events; receipt-lineage statements and continuation tokens prove authenticated linkage between those events. Kernels emit session anchors and request-lineage records for local continuity and nested-flow provenance. A missing lineage statement or continuation token is never verified upstream truth, and these records prove nothing about an external side effect beyond the observation boundary.

Swarm authority runtime admission

Recursive delegation and multi-swarm execution are governed at runtime. A protocol or kernel edge that dispatches swarm-bound child work MUST verify a stored swarm authority bundle before the child action runs. Missing, stale, malformed, or mismatched swarm evidence denies the action. Runtime admission and offline proof verification call the same bundle verifier, so both apply one definition of acceptance.

The admission reference binds the child dispatch to:

• the task graph digest
• the parent or join receipt
• the continuation token
• the delegation witness chain for the hop
• the route-plan receipt
• the revocation epoch id and root hash
• the budget pool allocation or lease

The signed task graph carries a maxDepth bound on task depth and a maxFanout bound on per-parent fan-out; the admission verifier enforces both over the whole graph, every edge target MUST sit at exactly the parent depth plus one, and depth overflow is a rejection. Route metadata is mandatory for swarm-bound dispatch, and omitting it is a denial. chio proof verify requires signed swarm delegation evidence and rejects a root-only swarm proof fail-closed. Listing or exporting swarm evidence leaves runtime authority where it was: a child action runs when the admission verifier accepts the current stored bundle under pinned witness keys. The full record set, verification order, and invariants are on Swarm Protocol.

Transaction passport proof root

chio.transaction-passport.v1 is the canonical proof root. A verifier MUST treat the passport as a signed RFC 8785 canonical JSON envelope over one transaction graph, never as advisory metadata. The proof root binds the root identity fields (schema, id, subject, transaction_kind, issuer, issued_at, expires_at, and signature), verifier-owned trust material (trust_roots, trusted issuer keys, and the verifier policy digest), the record closure (artifact_refs, evidence_graph_path and evidence_graph_sha256, verifier_policy_path and verifier_policy_sha256, claim_set_path and claim_set_sha256), and omission policy entries for verifier-policy-declared missing claims. A verifier MUST NOT infer a subject, transaction kind, trust root, or record reference from filenames, directory layout, or bundle-local prose.

The evidence graph is a bounded DAG: every node MUST have a schema id, bundle-relative path, role, and SHA-256 digest, and every edge MUST identify source, target, predicate, and evidence class. Graph verification rejects path escapes, missing records, digest mismatches, cycles, duplicate required roles, unbound root records, and unsupported roles; the claim-set digest is verified over the loaded claim-set bytes. chio.transaction.claim-set.v1 inventories the required verifier claims; verified means the referenced verifier accepted the claim, omitted claims must appear in both the verifier policy and the signed omission policy, and any unsupported status is a rejection. A claim-set self-report cannot satisfy a domain claim such as risk, commerce, disclosure, swarm, settlement, or agent-web; the external family report MUST supply it. The transaction verifier emits registered transaction_* failure codes for root failures, and a proof interface that collapses them into a generic success state fails the protocol.

Commerce order and settlement family

chio.commerce.order-context.v1 binds one order id to buyer, agent, merchant or provider subjects, current order state, quote, provider admission, mandate allowance, payment lifecycle, settlement packet, reconciliation, and event-log digests. chio.commerce.order-passport.v1 is the selective public summary over the same order and MUST NOT be accepted unless its record digests match the order context and the verified claim set. The order event log is a monotonic state-transition ledger: each event MUST bind an idempotency key, actor, prior state, next state, transition, occurred time, authority receipt reference, event digest, and evidence references, and a verifier rejects missing authority receipts, duplicate event ids, skipped states, backwards transitions, inconsistent order ids, and event-log digests that differ from the order context.

Payment and mandate records are subordinate evidence, never ambient authority. chio.commerce.payment-lifecycle.v1 binds payment status, capture, dispute, fraud, transfer, amount, currency, PSP references, and quote digest; chio.commerce.mandate-allowance-ledger.v1 binds maximum amount, currency, validity window, single-use or occurrence limits, protocol payload digests, and usage count; chio.commerce.settlement-packet.v1 binds settlement dispatch, reconciliation, destination, amount, currency, and external settlement references. AP2, x402, ACP-Commerce, or PSP payloads are accepted only as digest-bound protocol payload evidence named by the mandate or payment record. Commerce verification fails closed on currency drift, amount drift, merchant or provider mismatch, untrusted provider evidence, expired or overused mandates, missing authority receipts, PSP status that contradicts the claimed state, settlement packet mismatch, duplicate completion, or a public order passport whose summary digests differ from the private order context.

Disclosure and lineage family

chio.disclosure.capsule.v1 binds a disclosure policy, source record digests, reveal set, redaction or hidden-field commitments, verifier privacy profile, leakage ledger reference, issuer, subject, and signature. chio.lineage.signed-subgraph.v1 binds the disclosed lineage edges that justify the reveal. Disclosure verification accepts only the facts the verifier policy allows and rejects excess fields, missing required revealed fields, policy digest drift, stale or untrusted lineage signer keys, and hidden predicate claims the capsule leaves unimplemented.

Disclosure records leave receipt authority unchanged: a revealed fact that claims authorization, payment, settlement, risk, or runtime authority MUST be backed by the corresponding signed receipt, transaction claim, or family report. The signed lineage subgraph keeps verified, observed, asserted, unverifiable, and rejected edges distinct, and an asserted edge MUST NOT satisfy a verifier requirement for verified lineage. Leakage ledgers and crypto-context reports are verifier inputs to privacy evaluation only: they authorize no additional fields, repair no over-disclosure, and make no absent signature trusted.

Agent web envelope family

chio.agent-web-proof-envelope.v2 is the projection envelope for external protocol objects. It binds one source protocol and version, one external subject path and digest, unique Chio receipt references, a transaction passport reference and canonical passport-scope digest, a projection manifest reference and digest, optional settlement, risk, and disclosure references, limitation text, Chio claim references, and the envelope signature; the scope digest and receipt action bindings prevent replay against a different passport scope, manifest, source protocol, or source version. The envelope is accepted only with chio.agent-web.external-projection-manifest.v1 and chio.agent-web.interop-verifier-report.v1 for the same projection.

chio.agent-web-proof-envelope.v1 is a verification-only compatibility format whose signed payload has no passport-scope digest: new producers MUST emit v2, and a verifier that accepts v1 MUST use the v1 identifier and payload, require the v1 receipt-to-envelope bindings, and MUST NOT reinterpret v1 as carrying v2 scope authority.

The projection manifest declares which external fields were used and which were left out, the digest algorithm, source protocol version, sidecar-bound fields, claim mapping, unsupported claims, copy limitations, and whether an external signature is required. The interop verifier report MUST recompute external subject digests, enforce source-version-specific required fields, bind receipt and passport references, and mark unsupported native-authority claims as limited. MCP, A2A, ACP-Client, ACP-Commerce, AG-UI, OpenAPI, AP2, x402, Kubernetes admission, GraphQL, CloudEvents, in-toto, SLSA, Sigstore, browser automation, email, Slack, SCIM, and related protocols remain external systems: Chio proves the digest-bound relationship between those objects and Chio receipts. A protocol enforces Chio policy only where the runtime adapter path separately verifies authority and emits receipts.

Finding artifact family

chio.finding.v1 is the signed information-good record for Cognition Market findings. It binds a machine-matchable descriptor, a commitment to the reveal envelope, evidence references and cost, guarantee and evidence classes, bond and status references, an Ed25519 issuer, and a validity window. Its finding_id is the SHA-256 digest of canonical JSON for the record after setting both finding_id and signature to the empty JSON string; the members stay present and MUST NOT be omitted or encoded as null. The inline signature covers canonical JSON with the populated finding_id and only signature emptied, so the signature binds the content-addressed identifier.

Finding records MUST use bare lowercase Ed25519 key and signature encodings; issuer verification MUST reject weak, low-order keys and use strict verification; evidence_cost.currency MUST be a three-letter uppercase ISO 4217-style code; an absent runtime_assurance_tier is the sole encoding for no runtime assurance; deterministic_replay findings MUST carry replay_recipe_sha256; and any non-asserted guarantee or evidence class, or any present runtime assurance tier, MUST carry at least one evidence receipt reference. Record verification proves structural invariants, content-address binding, and the issuer signature. Referenced receipts and checkpoints, bonds, status feeds, pricing hints, liveness, and the truth of a guarantee class each need their own verification.

Finding signatures and envelope carriers

The rest of the family travels in one of three carriers. chio.finding.v1 is inline-signed. The market families below travel as signed export envelopes { body, signerKey, signature } whose bodies are strict snake_case JSON that rejects unknown members; most carry a content-addressed identifier derived exactly like finding_id, with chio.finding.purchase-record.v1 (purchase_key over two members) and chio.finding.challenge-outcome.v1 (outcome_id over the whole body) using domain-separated preimages, and the key revocation, audit-round authorization, and authority status named by the envelope digest of the statement itself.

Envelope verification MUST verify against an externally pinned authority key, MUST reject weak Ed25519 keys, MUST require the embedded signerKey to equal the pinned authority, and MUST require the body's authority member, where one exists, to equal the envelope signer. Verifying an envelope against its own embedded key alone is never sufficient for a market or value-moving decision. An envelope digest that another record references is SHA-256 over the canonical JSON of the complete envelope, never the body alone. The remaining carriers are unsigned and carry no envelope at all.

Inline-signed

chio.finding.v1

Signed export envelope

chio.finding.challenge-verifier-profile.v1, chio.finding.market-terms.v1, chio.finding.seller-authorization.v1, chio.finding.bond-backing.v1, chio.finding.verifier-report.v1, chio.finding.admission.v1, chio.finding.purchase-record.v1, chio.finding.failed-delivery.v1, chio.finding.challenge.v1, chio.finding.challenge-outcome.v1, chio.finding.challenge-enforcement.v1, chio.finding.finalized-bond-snapshot.v1, chio.finding.audit-epoch.v1, chio.finding.audit-report.v1, chio.finding.audit-round-authorization.v1, chio.finding.key-revocation.v1, chio.finding.authority-status.v1, chio.finding.status-epoch.v1

Unsigned, no envelope

chio.finding.replay-recipe-input.v1, chio.finding.purchase-context.v1, chio.finding.replay-observation.v1, chio.finding.recovery-context.v1, chio.finding.status-proof-input.v1

The complete schema catalog and field definitions are in Finding artifacts.

Checkpoints

Receipt batches are committed to signed Merkle checkpoints, and each checkpoint names the digest of the one before it.

pub struct KernelCheckpointBody {
    /// First receipt seq in this batch.
    pub batch_start_seq: u64,
    /// Last receipt seq in this batch.
    pub batch_end_seq: u64,
    /// Number of leaves in the Merkle tree.
    pub tree_size: usize,
    /// Root from MerkleTree::from_leaves.
    pub merkle_root: Hash,
    // … issued_at, kernel_key
    /// Hash of the immediately preceding checkpoint body when this checkpoint extends a prior batch.
    // … serde attributes
    pub previous_checkpoint_sha256: Option<String>,
    // … chain_root (absent on v1 checkpoints)
}

New issuers use chio.checkpoint_statement.v2 (CHECKPOINT_SCHEMA in crates/kernel/chio-kernel/src/checkpoint.rs). The v2 signed body may carry chain_root, the RFC 6962 commitment over the checkpoint chain. chio.checkpoint_statement.v1 checkpoints stay valid for verification and evidence import, and a v1 body MUST NOT carry chain_root. New cryptographic prefix proofs use chio.checkpoint_consistency_proof.v2; the v1 consistency record is a metadata-only continuity record and MUST NOT be read as a cryptographic prefix proof.

A checkpoint set presented without a separately pinned boundary MUST carry the predecessor chain back to checkpoint 1, and a checkpoint that cites a predecessor absent from the set MUST fail verification. Scoped evidence exports therefore include the checkpoint prefix through the newest checkpoint covering the selected receipts.

Receipt inclusion and publication claims

The checkpoint-anchored receipt format is chio.transparency.inclusion-proof.v2: RFC 6962 leaf and node hashing, a leaf bound to the transaction receipt bytes, and an embedded, strictly parsed checkpoint statement signed by a verifier-pinned checkpoint key. The registered v1 inclusion proof keeps its selective-disclosure hash construction and never qualifies a transaction as trust_anchored; readers MUST NOT interpret v1 proof bytes with the v2 semantics.

Checkpoints are local audit evidence with derived log_id, log_tree_size, predecessor-witness, and consistency-proof fields. Those support audit and transparency_preview claims, because checkpoint leaves cover checkpointed tool-receipt batches and external trust anchors are optional. A checkpoint publication record may carry a trust_anchor_binding with typed publication_identity and trust_anchor_identity declarations; when all three validate, Chio may say the checkpoint was published under declared trust anchors and publication policy. That is a trust-anchored publication statement inside the transparency_preview tier, short of an append_only promotion. Chio MUST NOT use public append-only or strong non-repudiation language until the published log is claim-complete, child-receipt-complete, anti-equivocation-capable, and qualified under the declared verifier policy.

Anchor batches and public witness policy

chio.anchor_batch.v1 is an additive batch record that builds a Merkle tree over receipt or checkpoint ids, signs the batch root and inclusion proofs, and binds the root to a public witness lane: rekor, ots, or solana_memo. Per-receipt local signatures remain the authority for individual receipts, and locally verifiable receipts stay valid through a witness outage. Batch verifiers fail closed on forged batch roots, inclusion proofs that differ from the checkpoint at the same index, witness entries whose root differs from treeRoot, and witness lanes outside the verifier allow-list.

Each batch carries a WitnessState of Pending, Witnessed, or Stale. A verifier configured with require_public_witness rejects new pending batches while accepting already-witnessed batches inside its own cache window, and MUST route that load-bearing verification through verify_anchor_batch_with_witness_policy_async, because the synchronous entry point rejects any policy carrying require_public_witness=true before structural verification. OpenTimestamps receipts are advisory and leave require_public_witness unsatisfied.

Manifest contract

Tool discovery uses the frozen manifest schema chio.manifest.v1. The manifest defines server identity, one or more tool definitions, per-tool input and optional output schemas, and operator-facing descriptions and metadata. It is the authoritative discovery contract for native tool servers and for mediated adapters that synthesize a Chio tool interface from another protocol, and its schema stays frozen for compatibility.

OpenAPI-derived manifests

The OpenAPI pipeline derives ToolDefinition values for manifest assembly from OpenAPI 3.0.x and 3.1.x documents. It reads operation-level x-chio-side-effects, x-chio-approval-required, x-chio-sensitivity, x-chio-budget-limit, and x-chio-publish annotations. Side effects and approval intent determine the method-based route policy; publication controls tool generation. Sensitivity and budget hints are parsed metadata and install no controls on the proxy path. Generated tools still require normal manifest signing, registration, capability scope, and runtime enforcement. The exact field projection and precedence rules are on OpenAPI Integration.

Runtime entrypoints

Local CLI and kernel

The chio CLI provides these runtime entrypoints:

• chio check: single-call policy evaluation in preflight mode, or full mode with an explicit output fixture for post-output guards
• chio run
• chio mcp serve
• chio mcp serve-http
• chio trust serve
• chio receipt explain: loads a content-addressed receipt from the local receipt database or the control plane and renders the signed decision, policy hash, guard evidence, parent receipt set, batch witness reference when present, and a repair hint for denials or incomplete receipts; it narrates locally and is no substitute for signature verification
• chio proof serve: static, read-only Proof Room server over a collected and verified proof bundle
• chio api protect: reverse proxy that enforces Chio policy over an HTTP API using an OpenAPI spec
• chio cert generate: generate a compliance certificate for an ACP session
• chio cert verify: verify a compliance certificate against a trusted kernel key
• chio cert inspect: inspect a compliance certificate and display its contents

These entrypoints share one set of receipt, capability, revocation, and policy types and one trust model. Every command and flag is on the CLI page.

MCP compatibility

Chio interoperates with MCP and leaves the MCP wire protocol to MCP. Its MCP-compatible mediation layer covers tools, resources, prompts, completions, logging, tasks, progress notifications, nested sampling, elicitation, and roots callbacks, plus remote HTTP auth discovery. Claude Code and Codex connect as ordinary remote MCP clients with no plugin. Compatibility claims rest on checked-in conformance scenarios, live JavaScript and Python peers, and the release-qualification corpus.

Hosted remote admin

chio mcp serve-http serves operator-facing admin APIs as part of the production-diagnostics contract for the hosted edge:

• /admin/health
• /admin/authority
• /admin/sessions
• /admin/sessions/{session_id}/trust
• /admin/receipts/...
• /admin/revocations
• /admin/budgets

HTTP egress contract enforcement

Every kernel, guard, and adapter outbound HTTP path declares a typed HttpEgressContract and routes its dispatch through chio_egress_contract::send_with_contract (or, for non-reqwest transports, the URL-only enforce_url and enforce_response_bytes helpers) before any byte leaves the process. The contract carries a tenant-scoped namespace, a lowercase scheme allow-list, an exact authority allow-list, explicit denials for loopback, IPv4 and IPv6 link-local, IPv6 unique-local (fc00::/7), and private-network targets, a max_redirect_chain ceiling, and a max_response_bytes ceiling.

Each rejection is a structured HttpEgressError. The target denials are LoopbackDenied, LinkLocalDenied, Ipv6UlaDenied, and PrivateNetworkDenied; a URL carrying userinfo is UserinfoDenied; a scheme or authority outside its allow-list is SchemeDenied or AuthorityDenied; and the two ceilings raise RedirectLimitExceeded and ResponseTooLarge.

A reqwest caller that cannot route through send_with_contract carries the CHIO_EGRESS_LINT_ALLOW_DIRECT_REQWEST: classification marker and MUST still run enforce_url before dispatch, disable automatic redirects, and run enforce_response_bytes against the declared Content-Length and the buffered body. Such a caller buffers before the byte-cap check, so the ceiling bounds what it accepts rather than what the transport transfers. Unmarked direct reqwest dispatch fails the http-egress-contract release gate.

Proof Room

chio proof serve serves a static, read-only Proof Room over a collected proof bundle. The router exposes / (a redirect into the UI view), /manifest.json, /artifacts/*, /negatives/*, /roots/*, /ui/*, and /verifier/*, plus the fixture catalog, trusted-bundle-signer, fixture-asset, and upload-verification endpoints. Served bundle paths are pinned to the manifest's declared record set; a request outside that set is rejected instead of resolved against the filesystem.

The three load-bearing record kinds are the signed bundle manifest chio.proof-room.bundle.v1 (with a detached DSSE signature of payload type application/vnd.chio.proof-room.bundle.v1+json), the verifier report chio.proof-room.verifier-report.v1 (a presentation-plane projection that MUST NOT be treated as stronger than the verified bundle signature, pinned trusted signer keys, and the signed evidence it binds), and the fixture catalog chio.proof-room.fixture-catalog.v1 (advisory discovery data; listing a fixture verifies nothing). Serving, listing, or rendering Proof Room records creates no authorization and leaves signed Chio truth and capability scope unchanged; the upload-verify endpoint re-verifies a submitted bundle against pinned trusted signer keys and the schema set before reporting a verdict.

Trust-control contract

chio trust serve runs the trust-control HTTP service. Each operator and cluster operation below is a path constant the service router registers, and its methods are read from that router.

Service health

GET /health

Additive JSON with authority, store, federation, and cluster summaries; also reports whether a runtime-assurance issuance policy is configured.

Authority status and rotation

GET | POST /v1/authority

GET returns the authority status; POST rotates the authority key behind the mutation fence, forwarding to the elected leader first.

Issue a capability

POST /v1/capabilities/issue

The typed capability-issuance contract the local CLI path uses, including optional runtimeAttestation evidence; with extensions.runtime_assurance in the policy, issuance resolves the highest satisfied tier and enforces its scope ceiling.

Cluster status

GET /v1/internal/cluster/status

Cluster status; a stable observability route.

Query receipts

GET /v1/receipts/query

Receipt query by capabilityId, toolServer, toolName, outcome, since, until, minCost, maxCost, costCurrency, cursor, limit, and agentSubject; returns totalCount, nextCursor, and receipts.

Operator report

GET /v1/reports/operator

Operator report with settlement backlog rows and multi-dimensional budget profiles: dimensions.invocations and dimensions.money usage blocks, and signed financial.settlement_status paired with mutable sidecar reconciliation state keyed by receipt_id.

Behavioral evidence feed

GET /v1/reports/behavioral-feed

Signed insurer and risk export: filter scope, export-boundary metadata, decision, governed-action, settlement, and metered-billing summaries, an optional subject reputation summary, and per-receipt detail rows.

Underwriting input snapshot

GET /v1/reports/underwriting-input

Signed underwriting policy-input snapshot: a bounded query scope, the chio.underwriting.taxonomy.v1 vocabulary, one canonical evidence snapshot, and derived risk signals that reference existing evidence identifiers.

Underwriting decision

GET /v1/reports/underwriting-decision

Deterministic underwriting decision over that snapshot: one outcome of approve, reduce_ceiling, step_up, or deny, the decision-policy snapshot, explanation findings, and a ceiling factor only for reduce_ceiling.

Exposure ledger

GET /v1/reports/exposure-ledger

Signed economic-position ledger over governed receipt, settlement, metered-billing, and persisted underwriting-decision state.

Credit scorecard

GET /v1/reports/credit-scorecard

Signed, subject-scoped credit scorecard built from the exposure ledger plus the local reputation inspection.

Settlement report

GET /v1/reports/settlements

Settlement reconciliation report over the receipt store for one operator query.

Economic receipt envelope

GET /v1/reports/economic-receipts

One receipt-scoped economic envelope alongside mutable settlement and metering reconciliation state.

Economic completion flow

GET /v1/reports/economic-completion-flow

One deterministic bundle over the metering, underwriting, credit, and settlement path for persisted local records.

Authorization context

GET /v1/reports/authorization-context

A standards-legible projection of governed receipts into derived authorization_details rows plus a separate transaction_context block.

Authorization profile metadata

GET /v1/reports/authorization-profile-metadata

The same profile as a machine-readable chio.oauth.authorization-metadata.v1 record for enterprise review.

Authorization review pack

GET /v1/reports/authorization-review-pack

A reviewer-facing evidence bundle over the same filters as authorization-context.

Metered billing report

GET /v1/reports/metered-billing

Post-execution metered-cost evidence for governed non-payment-rail tools, signed truth beside a mutable sidecar.

Reconcile metered billing

POST /v1/metered-billing/reconcile

Reconciliation of that metered-cost sidecar state.

Reconcile a settlement

POST /v1/settlements/reconcile

Upserts the reconciliation state and note for one receipt id.

Shared federation evidence

GET /v1/federation/evidence-shares

Shared evidence reference report over the receipt store for one shared-evidence query.

Compare a passport

POST /v1/reputation/compare/{subject_key}

Compares a submitted passport against the local reputation inspection, the shared-evidence report, and imported portable trust for one subject key.

Issue a reputation summary

POST /v1/reputation/portable/summaries/issue

Signs one portable reputation-summary record over explicit issuer, subject, evidence, and freshness state.

Issue a negative reputation event

POST /v1/reputation/portable/events/issue

Signs one portable negative-event record over the same explicit state.

Evaluate portable reputation

POST /v1/reputation/portable/evaluate

Evaluates imported portable records only through one local weighting profile: subject agreement, unique and allowed issuers, bounded freshness, non-contradictory timing, and explicit attenuation or penalty settings.

Federation and certification administration

Federation and certification administration includes:

• GET /v1/federation/providers
• DELETE, GET, PUT /v1/federation/providers/{provider_id}
• GET, POST /v1/certifications
• GET /v1/certifications/{artifact_id}
• GET /v1/certifications/resolve/{tool_server_id}
• POST /v1/certifications/discovery/publish
• GET /v1/certifications/discovery/resolve/{tool_server_id}
• GET /v1/certifications/discovery/search
• GET /v1/certifications/discovery/transparency
• POST /v1/certifications/discovery/consume
• POST /v1/certifications/{artifact_id}/revoke
• POST /v1/certifications/{artifact_id}/dispute
• GET /v1/public/certifications/metadata
• GET /v1/public/certifications/resolve/{tool_server_id}
• GET /v1/public/certifications/search
• GET /v1/public/certifications/transparency

Cluster snapshots that carry immutable pre-upgrade budget usage anchors MUST also carry chio.budget-snapshot-anchor-provenance.v1, which binds the canonical anchor-set digest into an append-only authority commitment chain signed by the serving leader and authenticated against the cluster service trust root; a follower MUST accept a previously absent wire anchor only from its locally elected leader, at the exact local election term, after verifying the chain from its genesis digest.

Standards-facing profile

The standards-facing profile is evidence plus deterministic, operator-visible runtime evaluation. It covers:

• signed receipts, checkpoints, and evidence export; portable-trust and certification interfaces
• the signed behavioral feed, underwriting input, underwriting decisions with budget, premium, and appeal linkage, and non-mutating underwriting simulation
• the signed exposure ledger and credit scorecard; bounded facility-policy evaluation, signed facility records, and deterministic credit backtests; signed provider-facing risk packages
• reserve-backed autonomy-tier gating over delegation-bond state; immutable bond-loss lifecycle records with executable reserve release and slash controls; non-mutating bonded-execution simulation with operator control policy and kill-switch semantics
• the curated liability-provider registry; delegated pricing-authority records with coverage and premium ceilings; provider-neutral liability quote, placement, and bound-coverage records; automatic coverage-binding decisions subordinate to those ceilings
• immutable claim-package, provider-response, dispute, and adjudication records; automatic claim-payout and claim-settlement instruction and receipt records
• runtime-assurance-aware issuance and governed-execution constraints

Chio proves a curated provider discovery and selection admission flow and a delegated pricing, quote and bind, and claim, dispute, adjudication, payout, and settlement orchestration layer over canonical evidence. The profile excludes an insurer network, an open-ended recovery-clearing network, autonomous pricing beyond the bounded authority-envelope and rollback profile, and a permissionless market.

Version negotiation

The machine-readable negotiation file is spec/versions/chio-protocol-negotiation.v1.json. Wire Protocol carries the negotiation rules across native, hosted, and trust-control endpoints.

Error model

The error registry is spec/errors/chio-error-registry.v1.json. Its 25 numeric codes fall into 8 categories: protocol, auth, capability, guard, budget, tool, internal, and transaction. The complete code table is on Schemas and Errors.

Portable trust and federation

Chio issues these portable-trust and federation schema identifiers:

Passport verification and cross-issuer records

Issuer and subject identities inside passport records are did:chio. A passport may contain credentials from different issuers as long as they all bind to one subject; verifier evaluation is per credential, and acceptance requires at least one credential to satisfy the verifier policy. A cross-issuer portfolio is a holder- or operator-assembled evidence set over existing passport records; imported entries stay distinguishable through sourceKind, subject rebinding requires one signed cross-issuer migration record, and local activation requires one signed trust pack and still evaluates per entry. Chio publishes no synthetic cross-issuer trust score. Replay-safe challenge verification can be backed by durable SQLite state, and non-Chio schema identifiers are rejected instead of treated as compatibility aliases.

Passport issuance and lifecycle status

The OID4VCI-compatible issuance lane is GET /.well-known/openid-credential-issuer, POST /v1/passport/issuance/offers, POST /v1/passport/issuance/token, and POST /v1/passport/issuance/credential. The always-available native profile is configuration id chio_agent_passport with format chio-agent-passport+json; an issuer with an explicit signing key may also advertise chio_agent_passport_sd_jwt_vc (application/dc+sd-jwt) and chio_agent_passport_jwt_vc_json (jwt_vc_json), both derived from the same verified passport truth without a second identity root. Pre-authorized codes and issuance access tokens are single-use and short-lived; the HTTPS credential_issuer is a transport identifier, not a trust root.

Portable lifecycle resolution is GET /v1/public/passport/statuses/resolve/{passport_id} with states active, stale, superseded, revoked, and notFound; only active is healthy, every distributed resolve_url must pair with a cache_ttl_secs, and a stale state is denied fail closed.

Passport presentation and discovery

The OID4VP verifier bridge is GET /.well-known/chio-oid4vp-verifier, GET /.well-known/jwks.json, POST /v1/passport/oid4vp/requests, and the public /v1/public/passport/wallet-exchanges/{request_id}, /v1/public/passport/oid4vp/requests/{request_id}, /v1/public/passport/oid4vp/launch/{request_id}, and /v1/public/passport/oid4vp/direct-post routes. Verifier identity is one HTTPS client_id with client_id_scheme=redirect_uri; request objects are signed with EdDSA and fetched by request_uri; holder responses use response_type=vp_token and response_mode=direct_post.jwt; exactly one credential of format application/dc+sd-jwt is requested; canonical transaction states are issued, consumed, and expired.

The holder presentation transport keeps challenge creation on POST /v1/passport/challenges and verification on POST /v1/passport/challenges/verify, with optional public holder fetch and submit at GET /v1/public/passport/challenges/{challenge_id} and POST /v1/public/passport/challenges/verify; the public routes are challenge-bound, read-only for fetch, and consume the replay-safe challenge record on a successful submit. Public discovery adds signed, versioned, TTL-bounded issuer, verifier, and transparency documents under /v1/public/passport/discovery/. Discovery visibility is separate from local trust activation and runtime admission.

Public identity and federated evidence

The public identity network records preserve did:chio as the provenance anchor while making any did:web, did:key, or did:jwk compatibility input explicit; wallet-directory entries and routing manifests stay informational or reviewable inputs until a local verifier or operator imports them under policy. The federation contract covers signed bilateral evidence-export policy documents, verified import of exported evidence packages, shared-evidence reporting that keeps foreign receipts distinct from native local receipts, and parent-bound continuation from an imported upstream capability into a new local delegation anchor; tenant-scoped export manifests carry a structured disclosure notice of the cross-tenant aggregate fields the signed checkpoint set reveals.

Bearer-authenticated hosted sessions may normalize enterprise identity into authContext.method.federatedClaims and authContext.method.enterpriseIdentity; the provider-admin registry supports oidc_jwks, oauth_introspection, scim, and saml record kinds, and an invalid provider record stays visible for diagnostics and ineligible for admission.

A2A adapter contract

chio-a2a-adapter is a thin bridge to A2A v1.0.0 and defines no new A2A wire standard. It covers Agent Card discovery, the JSONRPC and HTTP+JSON interface bindings, SendMessage, SendStreamingMessage, GetTask, SubscribeToTask, CancelTask, push-notification config create, get, list, and delete, optional durable task correlation through a file-backed registry, and explicit partner-admission policy by tenant, skill, security scheme, and allowed interface origin.

Auth negotiation is fail-closed over bearer, OAuth and OpenID, HTTP Basic, API key, and mTLS; any other scheme is refused. A frozen adapter-local metadata convention routes a call to one A2A skill. It is explicit and stays adapter-local, outside the core A2A protocol fields:

{
  "chio": {
    "targetSkillId": "research",
    "targetSkillName": "Research"
  }
}

Certification contract

Signed certification checks use the primary schema chio.certify.check.v1; the local or trust-control-backed registry uses chio.certify.registry.v1; the multi-operator discovery network uses chio.certify.discovery-network.v1. The contract evaluates a declared conformance result corpus under one fail-closed criteria profile, conformance-all-pass-v1, and one fail-closed evidence profile, conformance-report-bundle-v1, and signs records with verdict, criteria profile, evidence profile, corpus digests, findings, and signer-bound evidence provenance. It covers registry publication, listing, get, resolve, revoke, and dispute recording; public read-only metadata, resolve, search, and transparency per operator; and authenticated multi-operator publication, discovery aggregation, search, transparency, and policy-bound consume flows.

Resolution states are active, revoked, superseded, and not-found; dispute states are open, under-review, resolved-no-change, and resolved-revoked. Registry and discovery results stay scoped to the operator that published them, public discovery metadata fails closed when stale, mismatched, or malformed, and consuming a public listing is policy-controlled: runtime trust never widens from visibility alone. Search and transparency are signed visibility feeds without public transparency-log semantics, and the interface is neither a permissionless trust oracle nor an automatic runtime-admission mechanism.

Registry visibility and local trust activation

A bounded generic public registry sits over those operator-owned interfaces: GET /v1/public/registry/namespace, GET /v1/public/registry/listings/search, POST /v1/registry/trust-activations/issue, and POST /v1/registry/trust-activations/evaluate. It carries one signed namespace record, one signed listing envelope shared across tool-server, credential-issuer, credential-verifier, and liability-provider publication, explicit origin, mirror, and indexer publisher roles with freshness windows, and the deterministic ranking algorithm freshness-status-kind-actor-published-at-v1.

It also carries one signed local trust-activation record with the admission classes public_untrusted, reviewable, bond_backed, and role_gated, signed governance charter and governance-case records, a signed federation-activation exchange record, a signed federation-quorum report, a signed kernel-trust handshake over a SigningBackend (Ed25519, P-256, P-384, or hybrid PQ), signed open-admission and reputation-clearing records, and a signed federation-qualification matrix. Listing visibility never implies trust import, runtime admission, or market activation; imported activation stays visibility-only until local review accepts it; and missing, stale, divergent, expired, denied, unsigned, or policy-incompatible state fails closed.

Federation conformance tiers

Federation handshakes bind a conformance_tier into the signed challenge; the receiving kernel stores it on the pinned FederationPeer, and QuorumPolicy.min_tier rejects peers below the configured floor before a peer enters a quorum set. A peer with schema-valid evidence that meets neither threshold set below is bronze.

Cross-interface conformance is mandatory before a Silver or Gold federation tier is advertised: the same negative fixture family must run across MCP wrapped mode, hosted and native HTTP, and A2A or HTTP edge interfaces, and each must prove that deny receipts emit, lineage class is preserved, revocation propagates, budget enforcement holds, and no adapter bypass can skip capability, scope, or guard checks.

Economic simulation qualification artifacts

chio.econsim.scenario-result.v1 and chio.econsim.qualification-matrix.v1 describe deterministic, synthetic campaigns against named production economy validators. The v1 matrix enumerates sybil pricing, bid integrity, credit exposure, oracle divergence, cumulative approval, and settlement retry classes, and each result binds its seed, corpus digest, exact assertion scope, and explicit limits. An econsim matrix is self-signed internal qualification: its signature binds the runner's assertion and recorded provenance, and it is no independent proof of what executed. Econsim records are not runtime wire messages, external evidence, underwriting inputs, insurance facts, or capability claims, and a missing production target or an unresolved High or Critical finding stops the runner from emitting a signed matrix.

Observability contract

Production observability is part of the contract. The stable operator routes are trust-control /health and /v1/internal/cluster/status; hosted edge /admin/health, /admin/sessions, and the session trust views; provider-admin registry inspection; certification registry status; certification metadata, search, transparency, and dispute interfaces; operator report and shared-evidence analytics; durable A2A task-registry rejection when follow-up correlation is unsafe; and bounded web3 runtime reports for chio-link, chio-anchor, and chio-settle with explicit drift, replay, recovery, and emergency-mode state.

Field additions are allowed; a silent fail-open downgrade is a contract violation. Operational guidance is in docs/release/OBSERVABILITY.md, docs/release/OPERATIONS_RUNBOOK.md, and docs/release/CHIO_WEB3_OPERATIONS_RUNBOOK.md.