Swarm Denial Codes

Repairs by failed binding

Read the stable code with its detail and the request’s evidence references. Reproduce the matching positive example, then compare the first input that diverges.

• Missing or untrusted witness signer. Configure the verified public key on the host with with_swarm_witness_keys, and remove trust material from the request. An issuer key that appears in a submitted artifact is never adopted for that reason. Example: configured kernel.
• Graph or witness digest mismatch. Finalize and sign the referenced object before hashing it, rebind and re-sign its dependent continuations, and store and reference the same serialized artifact. Example: graph and continuation binding.
• Route mismatch. Compare bridge, protocolTarget, and selectedRoute from the host’s selected route with the child’s signed receipt. A changed route needs a newly authorized plan; the host’s selection outranks request metadata. Example: task-bound route.
• Over-allocation or inactive allocation. Reconcile allocation units against the pool and the producer’s ledger. Admission requires the continuation’s allocation to be active, fan-out returns Reserved, and an operator-owned state transition authorizes activation. Example: reservation and release.
• Continuation replay. Find out whether the first attempt reached dispatch. Release only a reservation aborted before any effect; if an effect may have happened, reconcile the result before issuing new authority, and leave replay state intact. Example: abort and replay.
• Stale or revoked evidence. Obtain the current trusted epoch and newly authorized evidence. A revoked task re-signed under the same revoked set stays revoked. Example: signed revocation.

Failure sources

chio_swarm_authority_rejected groups bundle-verifier failures with live route mismatches, and a slug is derived from a message. Keep the exact message, artifact ids, request evidence references, trusted-key configuration, evaluation time, and relevant store state: together they separate an invalid artifact from wrong evidence selection, expired authority, or a replay reservation.

Check order

The runtime checks the request’s evidence references against its stored bundle, compares live route metadata, verifies the bundle, and then consumes a single-use continuation. A failure at one boundary stops the later checks. Presentations that share one coordinated store compete for the same continuation marker before policy evaluation runs. Proof verification evaluates the supplied artifacts only, so live route comparison and the store’s replay state belong to runtime admission.

Inside the library the order is pinned keys, task graph and its signature, required delegation evidence, routes, joins, budgets, revocation epoch, terminal receipts, continuations, then witness chains. The verifier returns its first error and produces no partial acceptance report. Swarm Authority covers the architecture.

Runtime and store codes

Admission refusals place a code in metadata.chio_runtime.failure_code. Store insertion and state-validation errors normally return through the store API. Other admission rules can also refuse a swarm-bound request; this table lists the swarm-specific codes.

The JSON store also emits duplicate_swarm_authority_bundle when its own state repeats a graph id.

An admission denial receipt carries the code; the ordinary denial path drops the verifier’s detail sentence. Dispatch revalidation wraps the detailed error in KernelError::Internal. To recover the sentence for a refused bundle, run the verifier on it.

Verifier messages by artifact

Search a diagnostic fragment to narrow these tables to matching rows. Braces show interpolated values. Message text is diagnostic vocabulary, several checks share one message, and the runtime codes are the stable contract.

Choose the repair from the cause: correct a reference, fix trusted-key configuration, obtain fresh authority, or reissue a changed signed artifact. Re-signing the same invalid fields fails the same check. A passing artifact replay says nothing about a runtime replay reservation.

Field-shape messages

An unknown JSON key fails deserialization before these checks. Signature-body conversion can separately report swarm {family} signature body invalid: {id}, optionally with an underlying error. Retain that detail when diagnosing serialization.

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

A continuation binds every other artifact, so this family is the largest. Each row points at the binding that failed.

Delegation witness chains

Route metadata, runtime only

These eight messages come from verify_route_metadata_matches in chio-runtime-core, which compares the live route selection the kernel is about to take with the signed route-plan receipt. They occur only at runtime, each arrives as chio_swarm_authority_rejected, and each belongs to Route Plans.

The outer key is read as route, route_selection, or routeSelection. Each inner field accepts the alternate spellings listed in the table, and the first match wins. On acceptance the hook stores its own normalized { route: { bridge, protocolTarget, selectedRoute } } under verified_swarm_route_metadata, and dispatch revalidation compares against that record.

Captured refusals

Every refusal on this page can be reproduced on your machine. chio proof fixture generate recursive-runtime-swarm --with-negatives --out ./swarm writes the eleven negatives and a fixture trust file; one command verifies the whole directory and expects each bundle to be refused.

$ chio proof verify ./swarm/negatives --trust ./swarm/trust.toml --expect refuse

REFUSED   budget-allocations-exceed-pool  swarm budget allocations exceed pool total
REFUSED   egress-constraint-unsupported   unsupported swarm route-plan egress constraint: allow-private-network
REFUSED   graph-cycle                     swarm task graph cycle at task-child-a
REFUSED   join-parent-set-mismatch        swarm join receipt parent set mismatch: join-child-results
REFUSED   max-depth-exceeded              swarm task exceeds max depth: task-child-a
REFUSED   replayed-continuation-nonce     swarm continuation nonce replay: continuation-child-b
REFUSED   revoked-task                    swarm task is revoked: task-child-a
REFUSED   route-plan-mismatch             swarm route-plan selected route bridge mismatch: route-child-a
REFUSED   stale-continuation              swarm continuation token is stale: continuation-child-a
REFUSED   stale-route-plan                swarm route-plan receipt is stale: route-child-a
REFUSED   witness-child-scope-mismatch    swarm witness child scope mismatch: witness-child-a
11 of 11 refused, as expected
trust     ./swarm/trust.toml (fixture keys)

Each line names the negative and the verifier’s reason, the string the tables above index. Exit status 0 means every input met --expect refuse; a negative that verified would print VERIFIED and fail the run with exit 1, which makes the command a regression check for your own verifier build.

Negative-fixture slugs

The CLI takes the text after proof verify:, removes supported wrapper prefixes, and drops a suffix after : unless the remaining message already looks like a dotted code. It lowercases an ordinary message, replaces each run of non-alphanumeric characters with a hyphen, and prefixes proof-room.negative..

message  swarm route-plan receipt is stale: route-child-a
slug     proof-room.negative.swarm-route-plan-receipt-is-stale

message  swarm task graph cycle at task-child-a
slug     proof-room.negative.swarm-task-graph-cycle-at-task-child-a

The first message loses its artifact id at the colon; the cycle message keeps its task id. Already-dotted codes are preserved, and an empty normalized value becomes proof-room.negative.unknown. Slugs belong to proof fixture matching; admission reports the runtime codes above.

Negative transaction-passport descriptors carry an expected failure code for the proof-package doctor scenario. The swarm-authority doctor scenario checks its selected cases against message substrings, so a passing scenario covers the cases it lists.

Construction failures

Minting, signing, and the budget fan-out and fan-in helpers also return SwarmAuthorityError::Rejected. An issuer and signer mismatch, an invalid expiry, a missing parent receipt, or a budget arithmetic error can arise while producing evidence, before any admission attempt.

A constructor failure has no admission outcome to recover: correct the inputs and issue the artifact. The shared swarm witness issuer public key invalid message also occurs during verification, so the calling operation tells the two paths apart.

Refusal scope

• First error. The library returns one refusal and no partial report. Later artifacts may hold further failures, so repair and verify again.
• Evaluation time. The library evaluates the supplied bundle at the time it carries. Proof paths supply their clock; the runtime supplies its admission or revalidation time.
• Runtime replay. Single-use continuations are consumed through the admission store; resumable tokens take no consume path. Duplicate nonces inside one bundle are a separate verifier rule.
• Ambiguous consumption. A consume error or panic leaves ownership uncertain. The hook records the ambiguous swarm id and attempts to release the treaty reservation; inspect the recorded state before authorizing a new action.
• Admission path. The kernel’s admission path runs the swarm hook against the configured store and the pinned witness keys, so these codes come from the serving path itself.
• Completed graphs. Verification requires terminal receipts whose completed task set equals the graph’s task set. A refusal reports a broken binding; scheduler status lives elsewhere.
• Message stability. Error variants carry strings. Preserve the original detail, and key automation on the runtime codes.

Source files

The bundle verifier, its witness checks, and field helpers define the artifact messages. The runtime authority adapter and request-reference parser define the admission boundary. The proof command defines negative-fixture normalization.