Swarm Overview

The rung

The Platform ladder climbs by asking what a single answer needs. The Kernel decides one governed action and signs the receipt that attests it. The Node decides whether one process is still fit to decide. The Cluster holds state no single process can hold, under one authority keypair. Swarm is the first rung where the actor holding the authority is not one you run.

Filing test, two clauses. Is the actor’s authority derived from another party’s rather than issued to it, or does the action require signatures from parties under different keys? Either clause firing puts the subject at this rung.

The adjacent rung is easy to confuse and easy to separate. Federation owns the standing relationship between two authorities: the handshake, the pinned peer key, the import control that keeps another operator’s data out of local trust until someone activates it. Swarm owns the derived authority that travels across that relationship, and the joint actions that cross it. A read-path agreement policy over what other operators publish fires neither clause and belongs to Federation.

Where the name comes from

The rung is not named after a metaphor. Three artifacts in the Chio repo carry the word, and they are the reason the section exists.

• chio-swarm-authority, a crate at crates/kernel/chio-swarm-authority, filed under crates/kernel because its callers are admission-adjacent rather than transport code.
• chio_swarm_continuation_replay, a runtime denial code in chio-runtime-core, returned by every bundled admission store when a single-use continuation is presented twice.
• spec/PROTOCOL.md section 6.4.2, Swarm Authority Runtime Admission, which fixes the admission reference a swarm-bound child dispatch must bind to.

In that vocabulary a swarm is recursive delegation under one signed task graph. It names a shape, not a behavior. The ceilings on that shape live inside the graph signature, so a planner cannot widen recursion or fan-out after issuance without invalidating the graph it signed.

The warrant

An operational rung earns its place with shipped code, a frozen wire surface, and evidence that the failure paths are exercised. Three facts together are this rung’s warrant.

One fail-closed verifier

chio-swarm-authority exposes a single entry point. It holds no runtime state and performs no I/O: every fact it checks comes from the bundle it was handed or from the caller-supplied trusted witness key set, and the clock arrives as a field on the bundle rather than being read.

pub fn verify_swarm_authority_bundle(
    bundle: &SwarmAuthorityBundle,
    trusted_witness_issuer_keys: &[PublicKey],
) -> Result<SwarmAuthorityVerifierReport, SwarmAuthorityError> {

Three crates reach it. chio-runtime-core calls it from a trusted pre-dispatch admission hook, before a child task runs. chio-proof-room calls the same function from an untrusted-input public proof path, after the fact, and chio-cli calls it again on the swarm arm of chio proof verify. Because every call site in the workspace runs one function against one bundle shape, there is a single definition of delegation authority rather than three. An empty trusted key set rejects the bundle before any artifact is read, and a bundle whose continuation-token or witness-chain roles are empty is denied rather than accepted with a suppressed claim.

Nine schemas, eight registered claims

The wire surface is pinned at spec/schemas/chio-swarm/v1/. Eight of the nine artifacts carry a registered proof claim in spec/registries/proof-manifest.v1.json. The ninth is the report the verifier emits.

Signed negatives, one per refusal

Positive fixtures show the verifier accepting a valid recursive delegation. The negatives show it refusing. Each one names the claim it breaks, the base fixture it mutates, and the failure code the proof room must produce, so a regression that starts accepting a broken bundle fails a test instead of shipping. The table names all 11 files in fixtures/proof-room/swarm-authority/negatives/, listed by the arc dataset rather than typed here, each against the claim_ref its descriptor carries.

What the rung documents

Six mechanisms carry the rung. Each one is a signed artifact plus the check that binds it to the others.

• The signed delegation graph. One root, acyclic, every edge target at exactly parent depth plus one, with depth arithmetic that rejects overflow instead of wrapping. The maxDepth and maxFanout ceilings sit inside the signature. Cluster has no notion of depth. This is the first thing on the ladder that exists only here.
• Per-hop attenuation witnesses. Every graph edge carries a witness chain, covered exactly once, with hop-to-hop capability-digest and scope-hash continuity, expiry checked against bundle time, a pinned issuer, and a machine-checked scope-subset proof. This is what turns “authority only ever narrows” from an assertion into a check.
• The conserved budget pool. A pool is split across child tasks at fan-out and reclaimed at fan-in across five allocation states. Each allocation’s reserved, active, consumed, released, and reversed units must sum exactly to its ceiling, the sum of every allocation ceiling must not exceed the pool total, and the terminal rollup must reconcile against the live allocations before the graph can close.
• Single-use continuations. A child task runs only against a signed continuation token binding the graph digest, the parent or join receipt, the route plan, the budget allocation, the revocation epoch id and root hash, a session anchor, and a nonce. A token declares itself single_use or resumable, and the runtime consumes a single-use id during admission.
• Task-level revocation. A signed epoch carries revoked subjects and revoked task ids with a validity window, and its root hash is bound into every continuation token, so a stale epoch invalidates the hop. Cluster revokes a capability. Swarm revokes one task, mid-graph, without stopping the graph.
• Joint authorization. The second filing clause. Two kernels sign one canonical body so either organization can verify the chain without trusting the other unilaterally, and action classes the governance ladder marks quorum-required escalate to a threshold signature over a pinned roster. See Bilateral Co-Sign and Governance Ladder.

One child task, admitted

The sequence below is the runtime path. The proof-room path calls the same verifier on the same bundle shape and reaches the same verdict. It does so on untrusted input after the fact instead of before dispatch.

Run it

The same verifier runs over the checked-in fixture bundles from a Chio checkout, once cargo build --release -p chio-cli has produced the binary. scripts/proof-room-quickstart-env.sh exports the fixture trust anchors the verifier pins its keys from; without it the run stops at the missing-key check rather than at a swarm rule.

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

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

Nine of the ten checks are refusals. passed on a rejected passport means the bundle failed for the reason the scenario named, not that it verified: each entry in SWARM_AUTHORITY_CHECKS carries an expected_error substring, and a bundle refused for anything else reports failed for the wrong reason with both strings. Each refusal is the subject of one page below.

Where the rung stops

The containment is real and it is narrow. Six limits are worth carrying into every page below this one.

• The verifier is a pure function. No state, no I/O, no clock of its own. Continuation nonce uniqueness is checked within one bundle. Cross-bundle replay is caught by the runtime store, not by the crate, and a store that does not implement continuation consumption denies with chio_swarm_continuation_store_unsupported rather than passing the request through.
• Trust is caller-supplied. Every signed artifact verifies against a key in the slice the caller passed. The ceilings inside the graph signature bind a planner, not a holder of a pinned witness key.
• There is no issuance path here. The mint_* and sign_* constructors and the budget fan-out and fan-in helpers are fixture and lifecycle helpers exercised by tests. No production code path in the workspace calls them. This rung specifies verification. Issuance is the operator’s.
• The conformance surface is bounded. spec/PROTOCOL.md states it plainly: recursive-delegation positive fixtures, generated malformed graph, budget, epoch, route, and terminal-rollup cases, plus edge-dispatch checks for MCP, A2A, ACP-Client, OpenAI function-call execution, and OpenAPI bridge dispatch. Listing or exporting swarm evidence does not widen runtime authority.
• Budget conservation is arithmetic. The pool reconciles declared units against declared units. It bounds what a graph is authorized to spend. It does not observe settlement, which is the Economy area’s subject.
• Nothing here scores conduct. A sub-agent operating inside its attenuated scope, its depth ceiling, and its allocation is admitted every time, because that is what admission means. What it costs an adversary to buy that position is the subject of the next page.

Reading order

• New to the rung. This page, then the 3-Vendor Walkthrough for one scenario carried end to end.
• Implementing against it. Governance Ladder first, because the per-action-class declarations every other artifact keys off live there, then Bilateral Co-Sign and Selective Disclosure for the wire formats and validation rules.
• Evaluating the model. Reputation & Scarcity for what the structure bounds and what it does not, then Pheromone Store for the coordination signal that analysis is about.
• Arriving from the concepts side. Federation & Swarms is the one-page summary, and this section is its operational counterpart. Capability attenuation itself is Kernel content, documented at Capabilities.