Protocol Reference

Source

This page normatively reflects spec/PROTOCOL.md in the Chio repository, the signed-artifact registry spec/schemas/registry.json, and the wire schemas the Synopsis names. Status: Current bounded Chio release profile. Version 1.0. The keywords MUST, SHOULD, and MAY are normative. The contract is v1 and nothing else: earlier internal draft versions are folded into it, and no runtime carries a compatibility layer for one.

Where the crate is the truth for behavior the page follows the crate and names the file: crates/kernel/chio-kernel/src/checkpoint.rs for the checkpoint issuance schema, crates/core/chio-core-types/src/capability/token.rs for the token body, crates/core/chio-core-types/src/receipt/metadata.rs for the reserved receipt metadata keys, and crates/platform/chio-control-plane/src/trust_control/service_types/paths.rs for the trust-control routes.

Synopsis

Field meanings follow under the capability contract and the receipt contract; the negotiation envelope is under capability negotiation.

Purpose and scope

Chio is a capability-scoped mediation and evidence system for agent tool use: a native agent-to-kernel protocol for signed capability evaluation, a kernel that emits signed receipts for allow, deny, cancelled, and incomplete outcomes, and trust-control services for authority, revocation, receipt, budget, and federation state. The list below is the scope the v1 contract covers.

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.

Covered by the v1 contract

• native capability and receipt validation
• wrapped MCP mediation only where Chio owns dispatch; hosted or remote provider-executed activity is trace-only unless an implementation proves a live kernel-mediated dispatch boundary
• trust-control HTTP APIs for authority, receipts, revocation, budgets, federation, reputation comparison, and certification
• did:chio
• Agent Passport records and verifier-policy distribution
• federated evidence export and import, and cross-org delegation continuation
• A2A v1.0.0 consumption through chio-a2a-adapter only where receipt authority is backed by a live kernel authorization receipt
• signed certification checks plus operator-scoped registry and discovery-network interfaces
• one machine-readable extension inventory, an official Chio stack package, a custom extension manifest contract, a fail-closed negotiation report, and an extension qualification matrix; extension data cannot widen signed Chio truth or capability scope
• the web3 trust profile, contract package, chain configuration, anchor-proof, oracle-evidence, dispatch, settlement-receipt, and qualification record family, with the bounded chio-link, chio-anchor, and chio-settle runtime profiles and the Functions fallback, automation, CCIP, payment-interop, and operations profiles over that stack; these records remain evidence unless a kernel-mediated dispatch path is present
• the autonomous pricing, capital-pool, execution, rollback, drift, and qualification record family for the bounded automation lane
• the public identity-profile, wallet-directory, wallet-routing, and identity-interop qualification record family
• the Proof Room presentation interface (chio proof serve) and its bundle, verifier-report, fixture-catalog, receipt-evidence, and first-run evidence records, which render verified evidence and cannot widen signed Chio truth or capability scope

Not claimed by the v1 contract

These are distinct from the boundary items under Explicit gaps and are listed to prevent inferences from adjacent interfaces:

• OpenAI hosted-tool mediation, OpenAI remote MCP execution, Bedrock Lambda mediation, voice execution, broad live-directory import, or any other adapter execution that lacks merged and tested receipt semantics, durable commit, semantic authority, and tenant read-boundary gates
• OAuth authorization-server product status without an accepted ADR or equivalent decision note that defines scope, RAR grammar, telemetry, and feature gating
• manifest event publish and consume actions
• multi-region consensus or Byzantine replication
• a public certification marketplace
• automatic SCIM provisioning lifecycle
• synthetic cross-issuer passport scoring
• 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
• permissionless public identity or wallet discovery that widens local trust
• 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, or direct fund release from Functions or paymaster infrastructure beyond the documented bounded web3 interop interfaces
• a replacement of MCP or A2A at the wire-protocol ecosystem level

HTTP and OpenAPI surfaces

The v1 contract also covers:

• an HTTP substrate 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 maps deterministically to ChioReceipt, so receipt verification, checkpoint, and evidence-export workflows apply to it unchanged.

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, not an implementation detail.

Components and trust boundaries

The security boundary is constant across these interfaces:

• the agent never receives ambient authority
• every mediated action is bound to explicit capability or authenticated hosted session state
• denials are explicit, signed, and auditable
• extensions may replace only named integration points and must preserve local policy activation and signed Chio records
• registry and record mismatches fail closed instead of degrading silently

Serialization and identity

Canonical JSON

Signed Chio records use canonical JSON serialization (RFC 8785 JCS) before signing. Classical records remain 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. This 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 the Wire Protocol page.

• 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 shipped hosted contract:

• initialize is a POST /mcp request, not a 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, but its provenance enters Chio as asserted until a trusted subsystem upgrades it.

Identity

Chio uses Ed25519 keys as the primary cryptographic identity mechanism. 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 shipped 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. Broader public identity profiles may also name did:web, did:key, and did:jwk as compatibility inputs for wallet or issuer interoperability; those methods do not replace did:chio as the canonical provenance anchor in this release.

Capability contract

The shipped 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. The v1 signed body is:

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 shipped scope model includes:

• 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:

• typed first-party caveats with { kind, predicate, sig? }
• 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.

The chain-binding rule (W1.1) binds attenuation_proof.parent_scope_hash to the upstream lineage. Every delegation hop carries 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. Without this rule an issuer could claim a larger parent scope and supply an internally consistent witness. A violation surfaces CapabilityError::AttenuationViolation with the offending hashes as hex.

Production kernels MUST route every inbound capability admission through chio_kernel_core::verify_capability_full, which chains the W1.1 chain-binding check and the W1.2 sibling-sum budget admission with signature, crypto-floor, and time-bound verification, exactly once per admission decision. The partial entry points (verify_capability_with_floor, verify_capability_with_negotiated_floor, verify_capability_with_floor_and_trust_root, verify_capability_with_floor_and_resolver) remain for isolated unit tests and bounded research adapters and MUST NOT be the sole verifier on a production hot path. The W1.2 admit phase MUST run on hosted tool dispatch and federated nested-flow bridges and MAY be omitted on plan-step pre-flight and on session, resource, and prompt operations; a kernel that omits it there MUST document the omission. The Lean theorem theorem.attenuation.witness_soundness models the chain-binding check.

Aggregate invocation budgets and threshold approval

The per-token budget_share_bps cap is necessary but not sufficient: a parent at 5000 bps could mint two children at 4000 bps each, and per-token validation would accept both. The sibling-sum rule (W1.2) closes that gap with a per-parent BudgetRegistry at the verifier (chio_kernel_core::InMemoryBudgetRegistry by default). When the verifier 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. The kernel entry point is chio_kernel_core::evaluate_with_crypto_floor_and_budgets; the Lean theorem theorem.budget.sibling_sum_soundness models the admit check.

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 is not authority for a family owner, and 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.

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 does not resolve from one versioned directory. Unsupported negotiation denies these features instead of downgrading them.

Capability negotiation

Federated peers exchange chio.capabilities.v1 during trust establishment. The envelope carries a string-keyed feature bitset, and peers proceed only with the intersection of features both sides advertise. Malformed feature names and unsupported schema ids fail closed before a peer can use a negotiated feature. The initial feature names are:

• accepts_anchor_batch_v1
• accepts_hybrid_signatures
• delegation_chain_binding

Peers that do not advertise the bitset stay on the v1 default. Capability schema selection is not negotiated: chio.capability.v1 is the only Chio-owned token schema accepted by runtime verifiers.

Governed transaction extensions

Tool-call requests may attach two optional 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.

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 does not match 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 normative provenance model distinguishes three evidence classes:

• asserted: caller-supplied context that Chio preserves but has not independently authenticated
• 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:

• Ed25519 signature validity
• current time is within issued_at <= now < expires_at
• the requested target is contained by the grant set
• the presented capability and any preserved delegation structure are syntactically valid for the bounded shipped profile
• revocation state is clear for the presented capability and any presented delegation ancestor ids
• the DPoP proof is valid when the selected grant requires it
• policy guards pass

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

Safety properties and evidence boundary

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

The evidence classes behind those claims are separate. Root-imported Lean proofs in formal/lean4 cover the bounded P1 to P10 protocol models named by formal/theorem-inventory.json; formal/assumptions.toml names the audited external primitives and platform services that are trusted instead of proved; differential tests in formal/diff-tests are the Rust-to-spec drift gate for scope-attenuation semantics; the Aeneas lane extracts the production-linked pure core of chio-kernel-core into Lean and hard-gates tracked equivalence; Creusot and Kani lanes carry public Kani harnesses for verify_capability, NormalizedScope::is_subset_of, resolve_matching_grants, evaluate, and sign_receipt; and scripts/check-adapter-no-bypass.sh checks adapter mediation markers so MCP, API protect, and OpenAPI sidecar flows cannot drift away from kernel evaluation and receipt production. The formal claim is implementation-linked and assumption-bounded: the protocol semantics are checked in Lean and tied to the pure Rust decision core, while concrete crypto, clock, storage, transport, subprocess, hosted-registry, and chain behavior stay inside the published audited assumptions.

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

It also names the two shell entrypoints that may claim direct use of that pure core: 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 substrate 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 does not 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. The v1 shape makes authority structural: a receipt's receipt_kind, boundary_class, and trust_level together determine whether it is an authorization or only evidence.

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.

The protocol guarantee is that cancelled and incomplete outcomes are preserved explicitly instead of collapsing into an undifferentiated error state.

WYSIWYS signing invariant

Receipt signing is WYSIWYS (what you see is what you sign). The production signing primitive, chio_kernel_core::receipts::sign_receipt, takes the canonical content preimage alongside the receipt body: the RFC 8785 canonical JSON for a value output, the concatenated per-chunk digest preimage for a stream receipt, or the literal null canonicalization for an empty output. The signer recomputes content_hash from that preimage inside its own trust boundary and MUST NOT trust the caller's asserted value. When the recomputed hash disagrees with the body's claimed content_hash, signing MUST fail closed with ContentHashMismatch; the recompute runs before the kernel-key check and before any signing work, so a caller cannot render content A while submitting a body that claims the hash of content B.

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 do not hold the 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 DAG

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"] = pre_nonce_id

Before the id is computed, the producer binds a signing nonce into the body: the pre-binding receipt id, recorded under the reserved metadata key chio_receipt_signing_nonce. The binding happens once, in order: validate the body, write the nonce, then compute the id over the nonce-bound body. Because metadata is part of the id input, the nonce is covered by both the id and the signature. A non-object caller metadata value is preserved under original_metadata before the nonce is inserted; an empty or whitespace-only pre-binding id skips the binding; re-binding an already-bound body is a no-op. Every signed chio.receipt.v1 carries this key, and the inline and asynchronous kernel signing funnels emit byte-identical receipts because both apply the binding through one signing primitive.

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. The record schema fixes kernel_key -> ^([0-9a-f]{64}|p256:[0-9a-f]{130}|p384:[0-9a-f]{194})$; the P-256 and P-384 DER bodies are variable length and length-aware decoders validate them downstream of the regex. A present algorithm hint MUST agree with the signature prefix. Hybrid post-quantum signatures use the prefix shape from the serialization section and are not part of this enumeration. Ad hoc byte concatenation is not a valid signing input: verifiers reconstruct the typed 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. Replay and deduplication state keys exclusively on id, which verifiers recompute from canonical content before accepting the signature.

For multi-parent lineage, receipts carry chainId, sorted and deduplicated parentReceiptIds, parentSetHash = H(canonical(parentReceiptIds)), dagOrdinal, and the hybrid logical clock triple { wallSeconds, logical, kernelId } (ReceiptHybridLogicalClock in crates/core/chio-core-types/src/receipt/lineage.rs). The verifier rejects a child unless its parent descriptors match the signed parent set, every parent shares the same chainId, and child.dagOrdinal > max(parent.dagOrdinal). This rejects cross-kernel cycles without one global clock.

Authoritative spend

An authorization receipt for a spend-bearing call is authoritative only when it satisfies the structural conjunction of the chio.mediated_spend.v1 profile:

• The receipt is mediated_decision plus prevent plus trust_level = mediated with decision = Allow and no observation_outcome.
• Its budget_authority metadata names a hold_id that was atomically committed against the agent's cost-bearing capability and reconciled down to realized spend (authorize, then terminal.disposition = reconciled).
• A chio.execution_nonce.v1 nonce, signed by the same admitted kernel key, is bound to the same subject_id, request_id, capability_id, tool_server, tool_name, and parameter_hash, and the receipt records that nonce id in budget_authority.execution_nonce_id. The request_id binding is required: a binding that omits it still decodes, so a rolling upgrade does not fail at parse time, but it is denied at verification.

Advisory records and label-only receipts are never authorization. A guarantee level (single_node_atomic, ha_linearizable, partition_escrowed, advisory_posthoc) must be truthful to the backing store. The full four-check rule is on the Authoritative Spend page.

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.

Receipt metadata

The metadata object is extensible JSON with reserved top-level keys. The kernel writes its typed blocks under those keys, merges them last, and rejects a pre-existing collision from caller or hook metadata, so a verifier can treat a block found under a reserved key as kernel-authored and covered by the receipt signature. Unknown fields and unsupported schema versions fail closed. The constants in crates/core/chio-core-types/src/receipt/metadata.rs are the reader-side source of truth for the key names; the finding artifact family below lists them. Three of the blocks carry a schema id:

• 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) on digest-constrained calls records the expected_digest the grant fixed, the observed_digest of the delivered output (both lowercase 64-character hex SHA-256), and a result of matched (with an Allow) or mismatched (with the persisted zero-charge Deny). It carries no signature of its own; the enclosing receipt authenticates it.
• 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.

Settlement reconciliation state is not written back into the signed receipt: trust-control keeps mutable reconciliation state keyed by receipt_id and reports it beside the signed financial.settlement_status. 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 not authoritative receipt truth unless 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.

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. The bounded release emits session anchors and request-lineage records for local continuity and nested-flow provenance; the absence of a lineage statement or continuation token must not be treated as verified upstream truth, and none of these records alone proves 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 the Swarm Protocol page.

Transaction passport proof root

chio.transaction-passport.v1 is the canonical launch proof root. A verifier MUST treat the passport as a signed RFC 8785 canonical JSON envelope over one transaction graph, not 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 surface 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 do not match the order context.

Payment and mandate records are subordinate evidence, not 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 does not support the claimed state, settlement packet mismatch, duplicate completion, or a public order passport whose summary digests do not match 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 does not implement.

Disclosure records do not downgrade receipt authority: 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; they do not authorize additional fields, repair an over-disclosure, or make absent signatures 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 legacy 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 not, 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 and does not claim those protocols natively enforce Chio policy unless 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; it does not authenticate referenced receipts or checkpoints, verify bonds, status feeds, or pricing hints, check liveness, or establish the truth of a guarantee class.

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.

The reserved metadata keys the receipt crate names as constants, with the schema id a block pins where it pins one:

The signing path also reserves original_metadata for a non-object caller value displaced by the nonce binding, and the admission projection reserves admission_operation for the chio.admission-receipt.v1 block. Every schema in the family, with its fields, is on the Finding artifacts page.

Checkpoints

Receipt batches can be committed to a Merkle checkpoint. 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 remain valid for legacy verification and evidence import, but 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.

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 does not qualify a transaction as trust_anchored; readers MUST NOT interpret v1 proof bytes with the v2 semantics. The bounded release treats checkpoints as local audit evidence with derived log_id, log_tree_size, predecessor-witness, and consistency-proof fields; those support audit and transparency_preview claims only, because checkpoint leaves cover checkpointed tool-receipt batches and external trust anchors remain 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, which is a trust-anchored publication statement inside the preview tier, not an append_only promotion. Chio MUST NOT use public append-only or strong non-repudiation language until the published surface is claim-complete, child-receipt-complete, anti-equivocation-capable, and qualified under the declared verifier 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 a witness outage does not invalidate locally verifiable receipts. Batch verifiers fail closed on forged batch roots, inclusion proofs that do not match 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 do not satisfy require_public_witness.

HTTP receipts

The HTTP sidecar protocol introduces HttpReceipt, a domain-specific receipt for HTTP-layer policy evaluations that captures the evaluated method, path, query parameters, request headers, caller identity, authentication method, and the sidecar verdict. It is the receipt format the sidecar evaluation endpoint returns; ChioReceipt remains the unified storage and verification format for checkpoints, evidence export, and federation. The deterministic mapping preserves receipt_id across both formats, derives tool_server from the OpenAPI server identity or sidecar configuration and tool_name from the matched operationId, maps decision from the sidecar verdict, projects the HTTP context into metadata, and carries policy_hash and content_hash through unchanged. Checkpoint signing and evidence export always operate on the ChioReceipt representation. The mapping is specified on the HTTP Transport page.

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 it stays frozen in this release for compatibility.

OpenAPI-derived manifests

A pipeline derives chio.manifest.v1 tool definitions from OpenAPI 3.0.x and 3.1.x specifications. Each HTTP operation (method plus path) becomes one ToolDefinition. The x-chio-* extensions may appear at the operation, path, or root level: x-chio-scope (the capability scope the operation requires), x-chio-guard (guard expressions evaluated during policy admission), x-chio-rate-limit (per-operation rate constraints), and x-chio-require-auth (authentication requirements beyond the OpenAPI securitySchemes). When no extension is present, the pipeline applies a default deny-by-method policy that assigns conservative scope requirements from the HTTP method. The derived manifest is identical in structure to a hand-authored one, and the kernel, trust-control, and receipt pipeline do not distinguish them. The full pipeline is on the OpenAPI Integration page.

Runtime surfaces

Local CLI and kernel

The repository ships these primary 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 is a local narrator, not a replacement 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 the same receipt, capability, revocation, and policy types instead of defining separate trust models. Every command and flag is on the CLI page.

MCP compatibility

Chio does not claim to replace MCP. It ships an MCP-compatible mediation layer that covers tools, resources, prompts, completions, logging, tasks, progress notifications, nested sampling, elicitation, and roots callbacks, plus remote HTTP auth discovery. Compatibility claims are grounded in checked-in conformance scenarios, live JS and Python peers, and the release-qualification wave corpus.

Hosted remote admin

chio mcp serve-http ships operator-facing admin APIs, part of the supported 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 (W2.2). 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; because such a caller buffers before the byte-cap check, the ceiling bounds what it accepts, not what the transport transfers. Unmarked direct reqwest dispatch fails the workspace lint scripts/check-http-egress-contract.sh.

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 does not verify it). Serving, listing, or rendering Proof Room records creates no authorization and does not widen signed Chio truth or capability scope; 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 is the shipped trust-control HTTP service. The core operator and cluster endpoints, each a path constant in crates/platform/chio-control-plane/src/trust_control/service_types/paths.rs:

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.

Launch and standards boundary

The launch and standards-facing profile is bounded to shipping evidence plus deterministic operator-visible runtime evaluation: 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; and 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; it does not claim an insurer network, an open-ended recovery-clearing network, autonomous pricing beyond the bounded authority-envelope and rollback lane, or a permissionless market.

Version negotiation

The machine-readable negotiation file is spec/versions/chio-protocol-negotiation.v1.json. The Wire Protocol page 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 the Schemas and Errors page.

Portable trust and federation

Chio issues these portable-trust and federation schema identifiers:

Issuer and subject identities inside shipped passport records remain 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, local activation requires one signed trust pack and still evaluates per entry, and Chio does not publish a 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.

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.

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/, and discovery visibility never equals local trust activation or runtime admission.

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 remain informational or reviewable inputs unless 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 but is not eligible for admission.

A2A adapter contract

chio-a2a-adapter is a thin bridge for A2A v1.0.0, not a new A2A wire standard. The shipped behavior covers Agent Card discovery, the JSONRPC and HTTP+JSON interface bindings, SendMessage, SendStreamingMessage, GetTask, SubscribeToTask, CancelTask, push-notification config create, get, list, and delete, fail-closed auth negotiation for bearer, OAuth and OpenID, HTTP Basic, API key, and mTLS, optional durable task correlation through a file-backed registry, and explicit partner-admission policy by tenant, skill, security scheme, and allowed interface origin. A frozen adapter-local metadata convention routes a call to one A2A skill; it is explicit and is not presented as a core A2A protocol field:

{
  "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 and does not widen runtime trust from visibility alone. Search and transparency are signed visibility feeds, not public transparency-log semantics, and the interface is neither a permissionless trust oracle nor an automatic runtime-admission mechanism.

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, the deterministic ranking algorithm freshness-status-kind-actor-published-at-v1, 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 remains visibility-only until local review accepts it; and missing, stale, divergent, expired, denied, unsigned, or policy-incompatible state fails closed.

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.

Cross-surface 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 but does not independently prove 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 prevents the runner from emitting a signed matrix.

Observability contract

Production observability is part of the shipped contract. The stable operator surfaces 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.

Explicit gaps

The following are outside the shipped v1 contract and are documented so operators and integrators do not have to infer them from source code:

• permissionless or auto-trusting public federation or certification marketplace semantics
• permissionless mirror or indexer publication as automatic trust, sanction, or market-penalty authority
• public federation beyond the documented bounded federation-activation exchange, quorum, open-admission, reputation-clearing, and qualification interfaces
• portable reputation as a universal trust oracle or automatic cross-issuer score
• automatic enterprise identity propagation into every portable record
• custom A2A auth schemes beyond the shipped matrix
• full automatic wallet and distribution semantics for passports
• permissionless or arbitrary external capital dispatch beyond the documented official web3 lane, or autonomous insurer-rate setting beyond the documented autonomous-pricing, capital-pool, rollback, live-capital, reserve-control, payout, and settlement interfaces
• performance claims beyond the qualification and documentation interfaces

Related

• Wire Protocol: frame-level native framing, hosted session lifecycle, and trust-control lifecycle endpoints
• HTTP Transport: the sidecar contract and the HttpReceipt mapping
• Swarm Protocol: the swarm authority bundle and its verification order
• Finding artifacts: every schema in the finding artifact family
• Receipt Format: the receipt record field by field
• Schemas and Errors: the registry families and the error code table
• Bindings API
• CLI: every command the binary answers
• Cognition Market: the market the finding artifact family serves