Route Plans

Source

This page reflects spec/schemas/chio-swarm/v1/route-plan-receipt.schema.json and spec/PROTOCOL.md section 6.4.2 in the chio repository. The Swarm Protocol reference carries the full set of artifacts and the verification order.

A signed claim about egress, checked twice

A route-plan receipt is one artifact family inside a swarm authority bundle, defined as SwarmRoutePlanReceipt in crates/kernel/chio-swarm-authority/src/types.rs, schema id chio.swarm.route-plan-receipt.v1, wire form pinned by spec/schemas/chio-swarm/v1/route-plan-receipt.schema.json. Sixteen fields, all required by the schema. The claim it carries, claim.swarm.route_plan_bound, is registered enforced in spec/registries/claim-registry.v1.json. There is one receipt per routed task node, and the graph’s declared route-plan refs and the receipt set must cover each other exactly.

Two different pieces of code read it, and they check different things. chio-swarm-authority checks the artifact: shape, closed vocabularies, internal prefix agreement, expiry against the bundle clock, and a signature from a pinned witness key. That pass has no I/O and no opinion about the call in flight. chio-runtime-core’s admission hook adds the part a stateless verifier cannot do: it takes the route metadata the calling edge supplied for this dispatch and compares it, field by field, against the receipt the request named.

The two halves ship differently. verify_swarm_authority_bundle runs in product binaries today: chio proof verify calls it on the swarm arm of its local family dispatch, and chio-proof-room on a bundle rebuilt from an evidence graph, both pinning keys from CHIO_SWARM_TRUSTED_WITNESS_KEYS. The runtime half is an embedder API. ChioRuntimeAdmissionHook starts with an empty witness key vector, the chio-runtime facade’s with_swarm_witness_keys is called only by tests, and an empty slice rejects every route-plan receipt, so a default-built hook denies a swarm-bound request rather than admitting it. The facade’s core_hook always forwards whatever it holds to the core hook’s method of the same name, so an embedder that never sets the keys forwards an empty vector. Swarm Authority states that bound in full.

The receipt belongs to the Swarm rung because the key that signs it is a planner’s, not the executing node’s. The node holds a pinned public key and a stored bundle; it did not pick the route and cannot re-derive it. What it can do is refuse a dispatch that will not say where it is going.

The receipt

Every field except the signature is inside the signature. route_plan_signature_body serializes the receipt and removes the signature key before hashing, leaving the other fifteen covered, so editing any binding invalidates the receipt rather than retargeting it. That includes schema and expiresAtUnixMs.

Three prefixes off one bridge id

validate_route_plan_target is the reason a route plan cannot quietly name one bridge and address another. It runs the same shape three times:

let selected_bridge = route
    .selected_route
    .split_once(':')
    .map(|(bridge, _)| bridge)
    .ok_or_else(|| {
        rejected(format!(
            "swarm route-plan selected route bridge mismatch: {}",
            route.route_plan_id
        ))
    })?;
if selected_bridge != route.bridge_id {
    return Err(rejected(format!(
        "swarm route-plan selected route bridge mismatch: {}",
        route.route_plan_id
    )));
}

The positive proof-room fixture shows the four fields agreeing: bridgeId is mcp, selectedRoute is mcp:task-child-a, protocolTarget is mcp://provider-a, and egressContractId is mcp:egress-contract-task-child-a (fixtures/proof-room/swarm-authority/valid-recursive-delegation/route-child-a.json). Read the check for what it is: a prefix agreement, not a URL parse. Nothing constrains the remainder, so on a reading of split_once a selectedRoute of mcp: and a protocolTarget of mcp:// both pass with empty remainders. No test in the tree constructs that case. The verifier only refuses a receipt that contradicts itself. Two of the three prefixes do have offline negatives, swarm_authority_stage0_rejects_route_plan_selected_route_bridge_mismatch and ..._protocol_target_bridge_mismatch; nothing exercises the egressContractId prefix, so treat that third branch as read, not proved.

Where the schema is stricter, and where it is not

The pinned schema carries additionalProperties: false, mirrored in Rust by deny_unknown_fields, and it is the stricter document in exactly one place: signature is pinned to ^[0-9a-f]{128}$, the bare Ed25519 encoding, while Signature::from_hex also accepts 0x, p256:, p384:, and hybrid: forms. A receipt carrying one of those parses in Rust and fails schema validation. It matches the verifier exactly on one closed vocabulary, an enum of one holding deny-private-network under minItems: 1 and uniqueItems: true.

Everywhere else the verifier is stricter, and the gap is worth knowing before you mint from the schema alone. The schema states nothing about the three bridge prefixes, accepts any non-empty attenuationDecision where the verifier demands the literal accepted, has no clock to judge expiresAtUnixMs against, and cannot see the task graph the receipt has to belong to. Validate against the schema to reject malformed input early. Do not read a schema pass as an authorization result.

The order the receipt is checked in

validate_route_plan_receipts walks the bundle’s receipts once, running per-receipt checks in a fixed sequence and returning on the first failure. Shape comes first: schema, the id, the graph id, then the remaining non-empty and digest-format checks, then the egress constraint vocabulary, then the three prefixes, then the attenuation decision, then the policy digest, then expiry. The signature is checked after all of those. Graph membership comes last: the receipt’s taskId must resolve, its routePlanId must be a declared ref, and the id must not already be indexed. Only when the loop finishes does the closure check run the other way, requiring a receipt for every ref. That closure is against the graph’s routePlanRefs list. A node’s own routePlanRef is bound separately, by the continuation token that names the node.

That ordering means a stale or self-contradictory receipt is refused before its signature is verified, so a rejection message says what is wrong with the plan rather than what is wrong with the key. The negatives are built to be honest about it anyway: swarm_authority_stage0.rs carries six route-plan mutations, and each is re-signed with sign_route_plan_receipt before the assertion runs, so nothing in the suite passes because a signature happened to break. fixtures/proof-room/swarm-authority/negatives/route-plan-mismatch.json is the same pattern in fixture form: it names the valid route-child-a.json as its base fixture, declares case RoutePlanMismatch against claim claim.swarm.route_plan_bound, and the generated receipt carries selectedRoute of a2a:task-child-a under an unchanged bridgeId of mcp, with a fresh signature.

Three of the eleven shipped negative bundles are route-plan cases: an egress constraint outside the vocabulary, the mismatch above, and an expired receipt. Each is its own directory, so the three refusals are one loop:

$ source scripts/proof-room-quickstart-env.sh
$ for n in egress-constraint-unsupported route-plan-mismatch stale-route-plan; do
$   chio proof verify \
    "fixtures/proof-room/swarm-authority/$n/transaction-passport.json" 2>&1 | head -1
$   echo "exit=${PIPESTATUS[0]}"
$ done

error [urn:chio:error:cli:other]: proof verify: unsupported swarm route-plan egress constraint: allow-private-network
exit=1
error [urn:chio:error:cli:other]: proof verify: swarm route-plan selected route bridge mismatch: route-child-a
exit=1
error [urn:chio:error:cli:other]: proof verify: swarm route-plan receipt is stale: route-child-a
exit=1

The first names the rejected constraint string, allow-private-network; the other two name the receipt, route-child-a. All three exit 1, and none of them mentions a key or a signature, which is the ordering property the paragraph before the loop describes: a plan that contradicts itself is refused before the signature is reached.

Two other artifacts have to agree with the route set for the bundle to verify at all. A continuation token binds one: validate_continuation_route requires the child node’s routePlanRef to equal the token’s routePlanReceiptId, requires that receipt to exist, and requires its taskId to equal the token’s childTaskId. A terminal graph receipt binds all of them: its routePlanReceiptIds must equal the bundle’s whole route set as sorted lists, not contain it.

Live metadata against the receipt

None of this runs unless the request asks for it. swarm_ref_from_request looks for a chioSwarm object in the governed intent’s context and returns Ok(None) when it is absent; a request that never claims a swarm binding is never route-checked. When the object is present it is all or nothing: seven evidence references are required, a missing one is missing_chio_swarm_evidence_ref, a block carrying its own trust material is request_smuggled_trust_root, and a kernel with no runtime admission hook installed denies the request with runtime_admission_hook_missing rather than dispatching it.

The comparison itself lives in crates/kernel/chio-runtime-core/src/admission_hook/swarm_authority.rs. Its order matters and is not the order you would guess. All seven evidence references are matched against the stored bundle by id and canonical digest first. Then the named route plan is located. Then live route metadata is compared against it. Only after that does verify_swarm_authority_bundle run, and only after that is the continuation looked up and its routePlanReceiptId compared to the reference the request named.

That comparison opens with the refusal that matters most. Metadata is not optional and its absence is not a skip:

let Some(metadata) = route_metadata else {
    return Err(ChioRuntimeError::Rejected {
        code: "chio_swarm_authority_rejected",
        detail: format!(
            "swarm route metadata missing for route plan {}",
            route_plan.route_plan_id
        ),
    });
};
let Some(route) = metadata
    .get("route")
    .or_else(|| metadata.get("route_selection"))
    .or_else(|| metadata.get("routeSelection"))
else {
    return Err(ChioRuntimeError::Rejected {
        code: "chio_swarm_authority_rejected",
        detail: format!(
            "swarm route metadata missing routed entry for route plan {}",
            route_plan.route_plan_id
        ),
    });
};

spec/PROTOCOL.md section 6.4.2 states the same rule in one line: omitting route metadata is a denial, not a way to bypass route-plan enforcement. chio_runtime_hook_denies_swarm_missing_route_metadata_before_dispatch drives it directly, passing extra_metadata: None to a hook whose store already holds a valid bundle and whose witness keys are pinned, and asserting a denial with failure code chio_swarm_authority_rejected. All eight metadata refusal strings, and every other swarm-specific one, are listed in Swarm Denial Codes.

Inside the routed entry, three values are looked for and each is compared by exact string equality. Every candidate name is tried in order and the first one carrying a JSON string wins, so a field present with a non-string value is skipped rather than fatal.

All eight of those details travel under one failure code, chio_swarm_authority_rejected, which is also the code a verifier rejection produces. The denial metadata records the code, not the sentence, so an operator distinguishing a routing mismatch from a stale witness signature reads the detail string, not the classification.

On success the function does not hand back what it was given. It builds a normalized projection under the canonical names and returns that:

Ok(serde_json::json!({
    "route": {
        "bridge": bridge,
        "protocolTarget": protocol_target,
        "selectedRoute": selected_route
    }
}))

An admitted request carries that projection into its receipt as chio_runtime.verified_swarm_route_metadata. Before the tool is reached the hook re-runs the entire swarm verification, and on that second pass it feeds the recorded projection back in place of fresh live metadata. So the accepted-spellings table has a second job: the canonical names are the ones the runtime feeds itself. Two consequences are worth stating plainly. Revalidation re-proves the bundle against the request clock, and re-proves the route against what admission recorded, not against the call as it stands at dispatch. And a failure on that second pass is not a deny receipt: it becomes KernelError::Internal("runtime swarm authority revalidation failed: ..."), so the classification an operator sees for a pre-dispatch swarm failure differs from the one admission produces for the same condition.

Two of these checks are held in place structurally. cargo xtask check adapter-no-bypass parses verify_swarm_authority_reference_from_store and requires at least one call to verify_route_metadata_matches and at least one to verify_swarm_authority_bundle inside it, plus a binary comparison whose text contains both continuation.route_plan_receipt_id and reference.route_plan_receipt.evidence_id. A third contract holds the other end: the tokens "routePlanReceipt" and "routePlanReceiptSha256" must appear in swarm_ref_from_request’s evidence-reference calls. Deleting the route comparison to make something else pass fails the check by name.

What the shipped edges actually send

The metadata the hook reads is extra_metadata on the kernel call, which is caller-supplied and also lands in the receipt. Every in-tree path that populates it from a route planner goes through one helper. McpTargetExecutor in chio-mcp-edge, the function execution path in chio-openai-adapter, the execution and orchestrator paths in chio-cross-protocol, and authorize_via_kernel in chio-http-core all call route_selection_metadata, which wraps a RouteSelectionEvidence under the key route_selection. That struct serializes camelCase and carries selectedRouteId and selectedTargetProtocol, which is why both spellings are in the accepted lists.

The conformance matrix at crates/tooling/chio-conformance/tests/runtime_edges/r_t03_runtime_edge_matrix.json records seven runtime edges, each asserting admission before dispatch, a deny receipt, and a downstream dispatch count of zero. Only two set routeMetadataBound true: mcp_tools_call_route_metadata and openai_function_call. The test also requires a row claiming that binding to name a routed entrypoint, which is how the matrix stays honest about which edges carry route evidence at all.

Guarantees and limits

Next Steps

• Continuation Tokens · the token that binds this receipt to one child dispatch, and the id burned before the tool runs
• Node Egress Contract · what one process does with its own socket, including the private-range denial no contract can lower
• Swarm Authority · the whole-bundle pass this receipt is validated inside, and the pinned key slice it needs
• Task Graphs · routePlanRefs, the node ref, and the closure both directions
• 3-Vendor Walkthrough · one delegated scenario carried end to end