Route Plans

The kernel compares the route at admission and again from its record before dispatch

Route data reaches the checks from two places: the caller’s metadata at admission, and the route the hook recorded when it admitted the call.

Admission matches every artifact’s id and digest first, then compares three exact strings in order: bridge, protocol target, selected route. It then verifies the whole bundle at the request’s evaluation time and confirms that the continuation names this route plan, so a matching route alone admits nothing. The normalized route is recorded on the admission receipt, and revalidation compares that record with the stored receipt again before dispatch.

Read more in Continuation tokens, which covers the rest of the admission order.

One signed receipt binds a child to its route

The receipt has sixteen required fields, and its signature covers all of them except signature: the schema tag, every routing field, the expiry, and the issuer.

{
  "schema": "chio.swarm.route-plan-receipt.v1",
  "routePlanId": "route-child-a",
  "graphId": "swarm-graph-proof-valid",
  "taskId": "task-child-a",
  "selectedRoute": "mcp:task-child-a",
  "candidateSetDigest": "0a1a64dd…ab79",
  "registrySnapshotHash": "e2239b78…e2c0",
  "bridgeId": "mcp",
  "protocolTarget": "mcp://provider-a",
  "egressContractId": "mcp:egress-contract-task-child-a",
  "egressConstraints": ["deny-private-network"],
  "attenuationDecision": "accepted",
  "policyDigest": "58d22090…b44a",
  "expiresAtUnixMs": 1800000061000,
  "issuer": "did:chio:43046bfe…a5de",
  "signature": "f37a7968…780e"
}

The receipt’s task must exist in the graph, its id must be one of the graph’s route-plan references, and the child’s continuation must name the same receipt. Pointing the child somewhere else takes a newly signed receipt and consistent evidence references. The receipt above comes from the fixture, with digests and the signature shortened.

Three prefixes keep a route on one bridge

The selected route, the protocol target, and the egress contract each start with the receipt’s bridgeId.

These are string-prefix comparisons. They require no suffix after the prefix, leave the rest of each string unparsed, resolve no provider, and load no egress contract. The deny-private-network constraint, the one value egressConstraints accepts, records what the planner required; the configured egress implementation refuses the private-network connection.

The graph, the continuation, and the terminal receipt each commit to the route set

The route stage of verify_swarm_authority_bundle checks each receipt, then its place in the bundle. The first failure ends verification.

1. Task graph. Its routePlanRefs and the supplied receipt ids cover each other exactly, and receipt ids are unique.
2. Continuation. The child node’s routePlanRef equals the token’s routePlanReceiptId, and that receipt’s taskId equals the token’s childTaskId.
3. Terminal receipt. Its routePlanReceiptIds, sorted, equal the whole validated route set.
4. Runtime request. Its route-plan evidence id and canonical digest match the stored receipt, and its continuation names the same route plan.

To check the artifacts offline, run chio proof verify on a transaction passport that carries the swarm bundle. A proof pass covers the supplied artifacts; runtime route metadata and replay state belong to the admission path.

Read more in 3-Vendor Walkthrough, which carries the evidence workflow around it.

The prepared example signs a route and refuses a borrowed one

The downloadable Rust project signs a route-plan receipt for mcp://analysis-provider, verifies the graph, then binds the child to its sibling’s route and signs the changed continuation.

cargo run --locked --bin route -- mcp://analysis-provider

use chio_swarm_authority::verify_swarm_authority_bundle;
use swarm_authority_examples::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut bundle = build_bundle()?;
    let route = &mut bundle.route_plan_receipts[0];
    route.protocol_target = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "mcp://analysis-provider".into());
    sign_route_plan_receipt(route)?;
    verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())?;
    println!(
        "signed route: {}",
        bundle.route_plan_receipts[0].protocol_target
    );
    bundle.continuation_tokens[0].route_plan_receipt_id = "route-child-b".into();
    sign_continuation_token(&mut bundle.continuation_tokens[0])?;
    println!(
        "cross-task route: {}",
        verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())
            .expect_err("a child cannot take its sibling's route")
    );
    Ok(())
}

pub fn route_plan_receipt(
    route_plan_id: &str,
    task_id: &str,
    bridge_id: &str,
    protocol_target: &str,
) -> Result<SwarmRoutePlanReceipt, Box<dyn Error>> {
    let mut receipt = SwarmRoutePlanReceipt {
        schema: CHIO_SWARM_ROUTE_PLAN_RECEIPT_SCHEMA.to_string(),
        route_plan_id: route_plan_id.to_string(),
        graph_id: "analysis-graph".to_string(),
        task_id: task_id.to_string(),
        selected_route: format!("{bridge_id}:{task_id}"),
        candidate_set_digest: sha256_hex(format!("candidates-{task_id}").as_bytes()),
        registry_snapshot_hash: sha256_hex(b"registry-snapshot"),
        bridge_id: bridge_id.to_string(),
        protocol_target: protocol_target.to_string(),
        egress_contract_id: format!("{bridge_id}:egress-contract-{task_id}"),
        egress_constraints: vec!["deny-private-network".to_string()],
        attenuation_decision: "accepted".to_string(),
        policy_digest: sha256_hex(b"swarm-route-policy"),
        expires_at_unix_ms: now_ms() + 60_000,
        issuer: witness_issuer(),
        signature: String::new(),
    };
    sign_route_plan_receipt(&mut receipt)?;
    Ok(receipt)
}

signed route: mcp://analysis-provider
cross-task route: swarm continuation route-plan ref mismatch: continuation-child-a

You should see the signed target printed, then the cross-task binding refused with swarm continuation route-plan ref mismatch: continuation-child-a. The program contacts no provider; the signed target is routing metadata.

A refused route names the relationship that failed

Three negative fixtures each break one route rule: an unsupported egress constraint, a selected route on the wrong bridge, and an expired receipt.

$ chio proof verify \
  ./swarm/negatives/egress-constraint-unsupported \
  ./swarm/negatives/route-plan-mismatch \
  ./swarm/negatives/stale-route-plan \
  --trust ./swarm/trust.toml --expect refuse

REFUSED   egress-constraint-unsupported  unsupported swarm route-plan egress constraint: allow-private-network
REFUSED   route-plan-mismatch            swarm route-plan selected route bridge mismatch: route-child-a
REFUSED   stale-route-plan               swarm route-plan receipt is stale: route-child-a
3 of 3 refused, as expected
trust     ./swarm/trust.toml (fixture keys)

Each line names the negative and the rule it breaks. The summary line and exit status 0 say every input was refused, as --expect refuse required; a negative that verified would print VERIFIED and exit 1. At runtime, ordinary refusal metadata keeps chio_swarm_authority_rejected and drops the detailed string; dispatch revalidation keeps the detail inside an internal error.

A signed route records the planner’s decision; the edge and its egress controls carry it out

A verified receipt establishes that a pinned key signed these routing fields, that they agree with the graph and continuation, and that the receipt had not expired at the evaluation time the caller supplies. The operator decides which keys may sign routes, and any pinned witness key may; the operator also stores the current authorized bundle and keeps the admission state.

The candidate set, registry snapshot, and policy are carried as signed digests; reproducing the planner’s choice takes those inputs and its selection logic. The executing edge must still use the authorized destination under the node’s egress controls, and the library sets no maximum lifetime or newest-plan sequence.

Read more in Node Egress Contract, which governs the connection itself.

Route metadata, receipt fields, and diagnostics

{
  "route": {
    "bridge": "mcp",
    "protocolTarget": "mcp://provider-a",
    "selectedRoute": "mcp:task-child-a"
  }
}

Next: bind the child’s admission