Swarm Protocol

Source

This page normatively reflects spec/PROTOCOL.md section 6.4.2 and the schemas under spec/schemas/chio-swarm/v1/ in the chio repository. Status: Current bounded Chio release profile. Version 1.0. The keywords MUST, SHOULD, and MAY are normative.

Where the crate is the truth for behavior the page follows the crate and names the file: crates/kernel/chio-swarm-authority/src/verifier.rs with its submodules verifier/witness.rs, verifier/util.rs, and verifier/budget_accounting.rs; the bundle types in crates/kernel/chio-swarm-authority/src/types.rs; the budget-pool digest projection in crates/kernel/chio-swarm-authority/src/finding_pool.rs; and the worked example crates/kernel/chio-swarm-authority/examples/agent_os.rs.

This specification describes chio-swarm/v1. Validate against the schema identifier carried in the artifact. A change to the shape or meaning of any required field mints a new version identifier.

Synopsis

A hop presents one bundle, and verify_swarm_authority_bundle accepts it whole or rejects it.

pub struct SwarmAuthorityBundle {
    pub task_graph: SwarmTaskGraph,
    pub continuation_tokens: Vec<SwarmContinuationToken>,
    pub witness_chains: Vec<SwarmDelegationWitnessChain>,
    pub join_receipts: Vec<SwarmJoinReceipt>,
    pub route_plan_receipts: Vec<SwarmRoutePlanReceipt>,
    pub budget_pool: SwarmBudgetPool,
    pub revocation_epoch: SwarmRevocationEpoch,
    #[serde(default)]
    pub terminal_receipts: Vec<SwarmTerminalGraphReceipt>,
    pub now_unix_ms: u64,
}

Bundle artifacts

The registry tracks 9 schema files under chio-swarm/v1. Every artifact is a signed, closed object: unknown fields are rejected on both the schema and the Rust side. The field shape of each one is specified on its own page.

An accepted report carries claim ids drawn from a closed set of 8, declared as constants in crates/kernel/chio-swarm-authority/src/types.rs: claim.swarm.task_graph_bound, claim.swarm.continuation_fresh, claim.swarm.attenuation_witness_chain_bound, claim.swarm.route_plan_bound, claim.swarm.join_receipt_bound, claim.swarm.budget_pool_bound, claim.swarm.revocation_epoch_bound, and claim.swarm.terminal_graph_receipt_bound. All but one appear on every acceptance. A graph with no fan-in in it carries no fan-in receipt, so its report omits claim.swarm.join_receipt_bound.

Verification order

A verifier runs these steps in this order. Any failing step rejects the bundle immediately and produces no partial report.

1. Reject if the trusted witness issuer key set is empty, before any artifact is read.
2. Validate task-graph shape, then its signature.
3. Require at least one continuation token and one witness chain.
4. Validate and index route plan receipts, then join receipts, then the budget pool, then the revocation epoch, in that order.
5. Validate terminal graph receipts against the task, route, fan-in, and budget indexes.
6. Validate continuation tokens against the task graph canonical sha256, witness chains, routes, budget allocations, and the revocation epoch.
7. Validate that witness chains cover every task-graph hop exactly once, with continuous scope hashes and capability digests hop to hop.
8. Assemble the verifier report: one hop report per continuation-bearing task, plus the claim ids for the checks that ran.

Step 4 is not uniform in how it binds. Route plan receipts, join receipts, and the revocation epoch each carry an issuer and a signature, and a verifier checks the signature against a pinned key. The budget pool carries neither. It binds to the bundle through the signed graph, which names the graph the pool must belong to and the pool identifier itself, and through the allocations the continuation tokens draw on. A caller who trusts a pool because it looks signed has misread the artifact.

Invariants

Schema conformance does not make a delegation graph admissible. The structural rules below are checked in code, and a bundle that breaks any one of them is rejected whole.

1. Single root. A task graph MUST contain exactly one task at root depth, that task MUST have no parent, and every task below root depth MUST name one. Checked by validate_roots.
2. Acyclic. The graph MUST be acyclic. A verifier walks it depth first and rejects on re-entry to a task already on the current path. Checked by validate_acyclic and visit_task.
3. Exact depth arithmetic. Every hop target MUST sit at exactly the source depth plus one. Depth overflow MUST reject instead of wrapping. Checked by validate_edge_depths, and stated in spec/PROTOCOL.md section 6.4.2.
4. Signed ceilings, enforced graph-wide. The depth ceiling and the fan-out ceiling MUST sit inside the signed body, so widening either one requires a fresh signature from a pinned key. A verifier MUST enforce both across the whole graph: any task deeper than the depth ceiling rejects the bundle, and so does any task with more outgoing hops than the fan-out ceiling. The fan-out ceiling MUST be positive. Checked by validate_graph_limits.
5. Exactly one parent context per hop. Each continuation token MUST name either a direct parent task or a fan-in receipt. Naming both rejects. Naming neither rejects. Checked by validate_continuation_parent.
6. Witness coverage exactly once per hop. Every hop in the graph MUST be covered by exactly one witness chain. A missing chain rejects and a duplicate chain rejects. Every chain MUST terminate on a hop the graph actually declares. Checked by validate_witness_chains in crates/kernel/chio-swarm-authority/src/verifier/witness.rs.
7. Budget balance and budget ceiling. Each allocation's own five-way unit rollup MUST equal its ceiling exactly, and arithmetic overflow MUST reject instead of clamping. The allocation ceilings summed MUST NOT exceed the pool total. A terminal receipt's per-dimension rollup MUST equal the sum over allocations exactly, and its total MUST NOT exceed the pool total. Checked by validate_budget_allocation_units, validate_budget_pool, and validate_terminal_budget_rollups. A cognition-market pool_sha256 MUST hash the RFC 8785 canonical bytes of the chio.swarm.budget-pool-digest-projection.v1 preimage rather than the wire serialization of the pool. That preimage carries the projection identifier, the source pool schema, the pool id, graph id, and currency, and the allocations in their original order; the pool total and every allocation unit field MUST be the shortest unsigned base-10 string, with 0 as the only representation carrying a leading zero. Built by swarm_budget_pool_digest_projection_bytes and hashed by swarm_budget_pool_sha256 in crates/kernel/chio-swarm-authority/src/finding_pool.rs.
8. Closed egress constraint set. A route plan receipt MUST carry a non-empty, duplicate-free constraint list, and every entry MUST be deny-private-network. That is the whole set: any other string rejects the bundle as an unsupported constraint, and the schema enum lists the same one value. Checked by validate_route_plan_egress_constraints at crates/kernel/chio-swarm-authority/src/verifier.rs:979, and mirrored in spec/schemas/chio-swarm/v1/route-plan-receipt.schema.json:70. Route plans carries the rest of the receipt.

Run it

The crate ships one runnable bundle. examples/agent_os.rs mints a three-task incident graph, signs every artifact with keys it generates in process, verifies the bundle, and then re-verifies four tampered copies of it.

$ cargo run -p chio-swarm-authority --example agent_os

chio swarm authority  ·  one task graph, verified before any child runs

task graph  swarm-incident-42
  orchestrator      depth 0  scope 6ab7b09faf2a  route -                budget holds the pool
  researcher        depth 1  scope c5a04ca641ec  route route-researcher budget 2500 of 10000 units
  writer            depth 1  scope c5a04ca641ec  route route-writer     budget 2500 of 10000 units
  join researcher + writer -> orchestrator  (all_success)

verdict  verified  (3 tasks, 2 continuations, 1 joins, 2 routes)
  researcher   continuation continuation-researcher    witness witness-researcher (1 hop)
  writer       continuation continuation-writer        witness witness-writer (1 hop)
claims   claim.swarm.task_graph_bound, claim.swarm.continuation_fresh, claim.swarm.attenuation_witness_chain_bound, claim.swarm.route_plan_bound, claim.swarm.join_receipt_bound, claim.swarm.budget_pool_bound, claim.swarm.revocation_epoch_bound, claim.swarm.terminal_graph_receipt_bound

then someone tries to
  add an edge from the writer back to the orchestrator rejected: swarm task graph cycle at task-orchestrator
  hide a hop by understating the writer's depth        rejected: swarm task depth mismatch: task-researcher -> task-writer
  allocate 5,000 units out of a 100 unit pool          rejected: swarm budget allocations exceed pool total
  run the researcher after its task was revoked        rejected: swarm task is revoked: task-researcher

The checked-in fixtures verify the same way through the CLI. The proof doctor loads one valid bundle and the negative bundles beside it, and reports whether each was rejected for the reason its fixture pins, which is a different check from rejecting at all.

$ source scripts/proof-room-quickstart-env.sh
$ chio proof doctor --scenario swarm-authority --root .

chio proof doctor swarm-authority
  [passed] swarm_recursive_delegation: transaction passport verified
  [passed] swarm_stale_continuation: transaction passport rejected
  [passed] swarm_budget_allocations_exceed_pool: transaction passport rejected
  [passed] swarm_graph_cycle: transaction passport rejected
  [passed] swarm_join_parent_set_mismatch: transaction passport rejected
  [passed] swarm_replayed_continuation_nonce: transaction passport rejected
  [passed] swarm_revoked_task: transaction passport rejected
  [passed] swarm_stale_route_plan: transaction passport rejected
  [passed] swarm_route_plan_mismatch: transaction passport rejected
  [passed] swarm_witness_child_scope_mismatch: transaction passport rejected
verdict: passed

The refusals in that output are the verifier's own sentences. Swarm denial codes indexes every one of them back to the check that produced it, and the 11 signed negative bundles under fixtures/proof-room/swarm-authority/ replay the same refusals through chio proof verify.

Guarantees and limits

Related

• Swarm Authority · the same verifier as a mechanism, with the runtime admission path around it
• Swarm Denial Codes · every refusal string, and the runtime code that replaces it
• Swarm Overview · the field-level shape of each artifact, one page per family
• Protocol Reference · the single-call protocol a hop sits inside
• Schemas and Errors · the signed-artifact registry these 9 files are listed in