Swarm Denial Codes

Source

This page reflects crates/kernel/chio-swarm-authority/src/verifier.rs and its three submodules, verifier/witness.rs, verifier/util.rs, and verifier/budget_accounting.rs, in the chio repository. A refusal carries a message rather than a schema, so the source of truth is the code that produces it. The Swarm Protocol reference carries the artifact set, the verification order, and the invariants a valid bundle satisfies; every mechanism column below links the page that shows what the named artifact looks like when it is correct.

The runtime side comes from crates/kernel/chio-runtime-core/src/admission_hook/swarm_authority.rs, which wraps the verifier and assigns a failure code, and crates/kernel/chio-runtime-core/src/schema.rs, which declares the code registry. The two variants a refusal can take are declared in crates/kernel/chio-swarm-authority/src/error.rs.

Nothing in this family is a registry code. spec/errors/registry.yaml declares 20 URN domains and 111 codes, and no domain among them is a swarm domain. A swarm refusal reaches an operator as one of the three names below instead.

Three names for one refusal

A swarm delegation is refused by one function, verify_swarm_authority_bundle, which returns SwarmAuthorityError::Rejected(String) carrying a sentence. That sentence reaches an operator under three different identities, and which one you get depends entirely on which call site refused:

• A runtime failure code. On the admission path the sentence is discarded and replaced by one of twelve stable snake-case codes in chio-runtime-core. The verifier writes most of its refusals out as sentences and generates the rest from field labels, and every one of them collapses into a single code: chio_swarm_authority_rejected.
• The verifier message, verbatim. chio proof verify prints it as proof verify: <message>. The proof room wraps it two ways: the source-verifier route emits proof-room.source-verifier.failed: <message>, and the fixture route emits proof-room.fixture.verify-failed: <fixture_id>: <message>.
• A proof-room negative slug. The doctor derives proof-room.negative.<slug> from the message so a negative fixture can pin a failure without pinning punctuation.

None of the three is a stable API in the sense a caller usually wants. The failure codes are stable strings but coarse; the messages are exact but unversioned; the slugs are derived from the messages and move when a message is reworded. The crate says so itself: its error type has two variants and no code enum. Use the tables below to look a refusal up; a caller that needs a stable value reads the runtime failure code.

Where each name is produced

chio-swarm-authority/src/verifier.rs and its two submodules, verifier/witness.rs and verifier/util.rs, hold every verifier message. chio-runtime-core/src/admission_hook/swarm_authority.rs wraps the verifier with the checks only a runtime can make, assigns codes, and adds the eight route-metadata messages that have no proof-path equivalent. chio-runtime-core/src/schema.rs declares the code registry. The stores contribute the replay and duplicate-insert codes.

Nothing here runs unless the request asks for it. swarm_ref_from_request returns Ok(None) when the request carries no governed intent, no context, or no chioSwarm key, and the hook then skips the whole sequence. Unlike the treaty path, which denies a federated request whose treaty context disappeared, there is no condition under which the runtime requires a request to declare a swarm context. Swarm admission is opt-in per request.

The reference check is the runtime-only part and it is worth being exact about. Each of the seven references in the chioSwarm context carries an id and a SHA-256. The id must equal the stored artifact’s own id field, and the digest must equal canonical_sha256 of the stored artifact, not of the bytes the request supplied. The request names evidence; it never carries it.

Each reference is accepted in two shapes. A nested object under a name like taskGraph reads id (or evidenceId or artifactId) plus sha256 (or artifactSha256); a flat pair like taskGraphId and taskGraphSha256 is read only if the nested form is absent. Several names have aliases: continuation, routePlan, witnessChain, witness, and budgetLease are all accepted.

Every expiry and freshness rule below reads bundle.now_unix_ms, and the caller always overwrites that field before verifying. The runtime hook sets it to the admission clock; the CLI and proof room set it to wall clock at verification. A value baked into a stored bundle never decides staleness.

if reference.evidence_id != stored_id
    || reference.artifact_sha256 != canonical_sha256(stored_artifact)?
{
    return rejected(
        "chio_swarm_authority_ref_mismatch",
        "swarm-bound request evidence hash does not match verifier-owned authority evidence",
    );
}

There is a second runtime path with different behavior. revalidate_before_dispatch re-runs the whole reference and verification sequence after admission and before the call actually goes out. It does not deny; it returns KernelError::Internal with runtime swarm reference revalidation failed: {code} or runtime swarm authority revalidation failed: {error}. The second of those formats the whole ChioRuntimeError, whose Display is runtime admission rejected: {code}: {detail}. That is the one place on the runtime path where the verifier’s own sentence survives, and it only happens for a bundle that changed between admission and dispatch. A reservation that changed under it reports runtime admission reservation reserved_swarm_continuation_id changed before dispatch.

The runtime failure codes

Twelve codes in CHIO_RUNTIME_FAILURE_CODES name swarm state, plus two smuggling codes the swarm context shares with the treaty context. This is the complete set of swarm-specific values for metadata.chio_runtime.failure_code. A swarm-bound request is still subject to every other code in the registry: it can be denied for a missing governed intent, a treaty failure, or a pheromone policy verdict without any swarm-named code appearing. The last three rows are store-side codes raised on insert or on state validation, so they normally reach a caller as an error from the store API rather than as denial metadata.

Verifier messages, by artifact

Everything below arrives at the runtime as chio_swarm_authority_rejected and at the proof paths verbatim. Placeholders are shown as the variable the code interpolates. Since these are refusals to accept already-signed evidence, the operator action is uniform: re-mint the named artifact so it satisfies the rule, then re-present the bundle. The mechanism column is therefore also the fix.

Deriving the negative slug

semantic_negative_failure_code first takes whatever follows proof verify: and truncates at the first (. Then stable_negative_failure_code strips any prefix in a fixed list of about thirty (for this family, swarm authority invalid: and proof-room.source-verifier.failed: ), strips everything after the first : unless the remainder already looks like a dotted code, lowercases, collapses every run of non-alphanumeric characters to a single hyphen, trims hyphens, and prefixes proof-room.negative.. An empty result falls back to proof-room.negative.unknown. So swarm route-plan receipt is stale: route-child-a becomes proof-room.negative.swarm-route-plan-receipt-is-stale, and the id drops out. A message with no : keeps everything, which is why the graph-cycle fixture pins proof-room.negative.swarm-task-graph-cycle-at-task-child-a with a task id baked into the slug. The strip list does not contain proof-room.fixture.verify-failed: , and that prefix parses as a dotted code, so a failure from the fixture route is returned unchanged and never becomes a proof-room.negative. slug at all.

Every negative fixture under fixtures/proof-room/swarm-authority/negatives/ carries an expected_failure_code slug and is registered in fixtures/proof-room/catalog.json as negative-transaction-passport, so chio proof doctor --scenario proof-package replays each one against the derived slug. Most of them are also listed in SWARM_AUTHORITY_CHECKS, where chio proof doctor --scenario swarm-authority matches a literal substring of the message instead. egress-constraint-unsupported and max-depth-exceeded are replayed under the proof-package scenario only.

The negative fixtures and their sentences

Each descriptor names a sibling directory holding the mutated bundle, so the whole set is one loop from a Chio checkout. scripts/proof-room-quickstart-env.sh exports the fixture trust anchors; cut -d' ' -f3- drops the error [urn:chio:error:cli:other]: prefix each line carries so the sentences line up.

$ source scripts/proof-room-quickstart-env.sh
$ for n in $(ls fixtures/proof-room/swarm-authority/negatives/*.json \
             | xargs -n1 basename | sed 's/\.json$//'); do
$   printf '%-30s ' "$n"
$   chio proof verify \
    "fixtures/proof-room/swarm-authority/$n/transaction-passport.json" \
    2>&1 | head -1 | cut -d' ' -f3-
$ done

budget-allocations-exceed-pool proof verify: swarm budget allocations exceed pool total
egress-constraint-unsupported  proof verify: unsupported swarm route-plan egress constraint: allow-private-network
graph-cycle                    proof verify: swarm task graph cycle at task-child-a
join-parent-set-mismatch       proof verify: swarm join receipt parent set mismatch: join-child-results
max-depth-exceeded             proof verify: swarm task exceeds max depth: task-child-a
replayed-continuation-nonce    proof verify: swarm continuation nonce replay: continuation-child-b
revoked-task                   proof verify: swarm task is revoked: task-child-a
route-plan-mismatch            proof verify: swarm route-plan selected route bridge mismatch: route-child-a
stale-continuation             proof verify: swarm continuation token is stale: continuation-child-a
stale-route-plan               proof verify: swarm route-plan receipt is stale: route-child-a
witness-child-scope-mismatch   proof verify: swarm witness child scope mismatch: witness-child-a

Each message is the second identity in full: the verifier's own sentence, which chio proof verify prefixes with proof verify:. All but two name the artifact or task that failed, and that trailing id is the only place an operator gets it: the pool-total refusal names nothing, and the egress refusal names the rejected constraint value instead. The admission path reports each of them as chio_swarm_authority_rejected. Every invocation exits 1; the full stderr also carries a context object and a suggested fix line, dropped by head -1.

Field-shape messages, generated from a label

Four helpers in verifier/util.rs generate their messages from a template and a label, so the catalogue of them is short even though the call sites are many. The label names the field, and the template names the rule it broke.

The same file holds six *_signature_body helpers, one per signable family, and each can produce swarm {family} signature body invalid: {id} with or without a trailing : {error}. That is twelve more strings on the verification path, and they are listed here for completeness only: both arms require serde_json::to_value of a plain struct to fail or to return something other than an object. Delegation witnesses have no such helper, because witness_signature_body builds a typed struct and cannot fail.

Bundle level and trust

Task graph structure

Route-plan receipts

Join receipts

Budget pool and allocations

Revocation epoch

Terminal graph receipts

Join & Terminal Receipts owns the artifact and the set-equality rule. Sub-Agent Budgets owns the rollup arithmetic these rows compare against, so the budget rows point there.

Continuation tokens

This is the largest family, because a continuation is the artifact that binds all the others. Its rows point at whichever binding failed rather than at continuations generically.

Delegation witness chains

Route metadata, runtime only

These eight messages have no counterpart on the proof paths. They come from verify_route_metadata_matches in chio-runtime-core, which compares the live route selection the kernel is about to take against the signed route-plan receipt. Every one arrives as chio_swarm_authority_rejected and every one belongs to Route Plans. The outer key is read as route, route_selection, or routeSelection. The three inner fields each take a list of alternates, spelled out in the table: the bridge accepts four names, two of which do not contain the word bridge at all, and the selected route accepts four. First match wins; the rest are not consulted.

On acceptance the hook does not store what it read. It stores its own normalized { route: { bridge, protocolTarget, selectedRoute } } under verified_swarm_route_metadata, and dispatch revalidation compares against that, not against whatever alternate spellings the original request used.

Constructor messages, not a runtime path

The crate’s mint_*, sign_*, and budget fan-out and fan-in helpers also return Rejected. Their callers in the workspace are the crate’s tests and its examples/agent_os.rs binary, so these strings appear in a test failure or an example run rather than a denial. The two mint_* helpers and the two budget fan-out and fan-in helpers are the test-only ones; every sign_* helper is also called by the example. Two shapes are formulaic across seven families, where {family} is one of task graph, continuation, join receipt, route-plan, revocation epoch, terminal receipt, and witness: swarm {family} issuer public key invalid: {detail} and swarm {family} signer does not match issuer: {id}. The witness member of the first pair collides with the verification-path message of the same wording, so swarm witness issuer public key invalid does not tell you which side produced it; every other family’s version of that string is constructor-only. The remainder are swarm continuation expiry must be after issue time: {token_id}, swarm join receipt parent task receipts missing: {join_id}, swarm join receipt actual parent receipts missing: {join_id}, swarm budget fanout allocations missing, swarm budget fanout allocation units missing: {allocation_id}, swarm budget fanout overflow, swarm budget fanout exceeds pool total, swarm budget fanin completed tasks missing, swarm budget fanin release overflow, swarm budget fanin release exceeds allocation: {allocation_id}, and swarm budget fanin task has no allocation.

Guarantees and limits

Next steps

• Swarm Authority · the verifier that produces every message above, and the order it reads a bundle in
• Continuation Tokens · the replay codes in context: reserve, consume, release, and the resumable exemption
• Task Graphs · depth arithmetic, the single root, and the ceilings behind a third of these strings
• Delegation Witnesses · edge cover, hop continuity, and the attenuation proof whose errors are nested inside one message
• Route Plans · the bridge prefix rules and the live-metadata comparison that has no proof-path equivalent
• Join & Terminal Receipts · the fan-in parent set and the closing receipt behind two of the tables above
• Sub-Agent Budgets · allocation states, rollup arithmetic, and the terminal receipt that reconciles them
• Revocation Epochs · the signed block-list every continuation commits to by root hash
• Proof Room · where the negative fixtures live, and the path that prints the sentence rather than the code