Join & Terminal Receipts

Two signed receipts close a delegated graph

A join receipt reconciles one fan-in that the graph declares. A terminal graph receipt reconciles the complete graph: its task, join, and route sets, plus budget totals computed from its allocations.

The fixture’s terminal receipt lists all four tasks, the root included, the one join, and the three route plans. Each child holds 2,500 usd_minor units of the 10,000-unit pool, so 7,500 is allocated and 2,500 stays unallocated. The verifier checks that each allocation’s counters sum to its maxUnits and that the ceilings fit inside the pool.

Both receipts carry an issuer signature over their canonical body with the signature removed, checked against the same pinned trust set as every other swarm artifact family; closing a graph needs no separate authority role. Every declared join needs exactly one matching join receipt, the bundle needs at least one terminal receipt, and every supplied terminal receipt must pass. These requirements hold wherever the authority verifier runs, its runtime admission path included.

A join pairs each parent task with its receipt by position

In the fixture, join-child-results expects receipts from three child tasks under the predicate all_success, finds all three in its actual list, and names task-root as its next task.

The verifier zips the graph join’s parentTaskIds with the receipt’s expectedParentReceiptIds, keeps the pairs whose receipt id appears in actualParentReceiptIds, and requires the explicit parentTaskReceipts array to hold exactly those pairs, each task id and receipt id unique. Reordering the explicit pairs is harmless. Reordering only the expected list reassigns receipts to different tasks, so build the pairing in graph order.

• all_success requires the actual and expected id sets to be equal.
• any_success requires at least one expected receipt id.
• quorum:N requires at least N expected receipt ids, with 1 ≤ N ≤ the expected parent count.

Every actual id must belong to the expected set, neither list may repeat an id, and the graph requires at least two parent tasks per join. An invalid quorum or an unknown predicate is unsupported. The predicate names describe a selection rule over receipt ids and signed fields; the verifier reads no success verdict inside a parent receipt.

A join authorizes nothing on its own. A join-mode continuation binds the join, the same target task, and the same actual parent ids; the fixture’s join targets the root, which has no continuation token.

Read more in Continuation Tokens.

The terminal receipt must match the graph exactly

Three id sets must equal the validated bundle’s, and the budget rollup must equal the allocations dimension by dimension.

1. completedTaskIds. Every task id in the graph, the root included.
2. joinReceiptIds. Every validated join receipt id.
3. routePlanReceiptIds. Every validated route-plan receipt id.
4. budgetRollups. The dimension-to-counter map computed from the allocations, with a combined total inside the pool.

A subset fails, and every supplied terminal receipt must reconcile the same complete sets. terminalTaskIds takes a narrower check: its entries are unique and name known tasks, and the verifier derives no graph leaves from it.

For each dimension the verifier sums reserved, active, consumed, released, and reversed units with checked arithmetic. A verified terminal receipt can therefore carry active allocations, as the fixture’s 7,500 units are. These checks relate the supplied artifacts: the swarm verifier loads no parent receipt body, observes no execution, and leaves settlement to the settlement records.

Read more in Sub-Agent Budgets.

A missing parent stops the join before its hash is compared

The parent-set-mismatch fixture keeps all_success with two expected parents and only receipt-child-a actual. Its parent-set hash is recomputed over the shorter list and the receipt is signed, so the predicate check is the one that fails.

$ chio proof verify ./swarm/negatives/join-parent-set-mismatch --trust ./swarm/trust.toml

REFUSED   join-parent-set-mismatch  swarm join receipt parent set mismatch: join-child-results
trust     ./swarm/trust.toml (fixture keys)

The retained invocation exits 1 and names join-child-results. The same message covers an unmet quorum, an empty any_success selection, and an unexpected actual id, so read both lists and the predicate to find the cause.

Source tests accept any_success and quorum subsets and reordered explicit pairs. They refuse an unmet quorum, a changed pair, and a terminal rollup re-signed with one unit of drift.

Read more in Swarm Denial Codes.

Issuers mint the receipts and the authority verifier admits the bundle

The public Rust API exports mint_swarm_join_receipt and signing helpers for both receipt types. The mint helper checks for non-empty actual and paired-parent lists and a positive ordinal, computes the parent-set hash, fills the issuer, and signs. Run the full authority verifier over the assembled bundle before relying on it.

The workflow that runs the graph decides when to issue each receipt, gathers the parent evidence, and publishes one consistent bundle to its admission store. The admission hook reuses the authority verifier, so the stored bundle carries its terminal evidence: the request’s seven artifact references name no terminal receipt directly, and the hook validates every terminal receipt in the stored bundle.

cargo run --locked --bin terminal

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut bundle = build_bundle()?;
    let join = &bundle.join_receipts[0];
    let request = SwarmJoinReceiptMintRequest {
        join_id: join.join_id.clone(),
        graph_id: join.graph_id.clone(),
        chain_id: join.chain_id.clone(),
        dag_ordinal: 2,
        hlc_unix_ms: now_ms(),
        parent_task_receipts: join.parent_task_receipts.clone(),
        expected_parent_receipt_ids: vec!["receipt-child-a".into(), "receipt-child-b".into()],
        actual_parent_receipt_ids: vec!["receipt-child-b".into(), "receipt-child-a".into()],
        join_predicate: "all_success".into(),
        result_digest: join.result_digest.clone(),
        next_task_id: "task-root".into(),
    };
    bundle.join_receipts[0] = mint_swarm_join_receipt(request, &witness_keypair())?;
    verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())?;
    println!("join: both parent IDs bound, independent of input order");
    println!(
        "terminal: {} declared completed tasks; {} active units",
        bundle.terminal_receipts[0].completed_task_ids.len(),
        bundle.terminal_receipts[0].budget_rollups[0].active_units
    );
    // These are signed declarations; this example does not execute the tasks.
    bundle.terminal_receipts[0].completed_task_ids.pop();
    sign_terminal_graph_receipt(&mut bundle.terminal_receipts[0])?;
    println!(
        "missing completion: {}",
        verify_swarm_authority_bundle(&bundle, &trusted_witness_keys())
            .expect_err("terminal must cover every graph task")
    );
    Ok(())
}

pub fn terminal_graph_receipt() -> Result<SwarmTerminalGraphReceipt, Box<dyn Error>> {
    let mut receipt = SwarmTerminalGraphReceipt {
        schema: CHIO_SWARM_TERMINAL_GRAPH_RECEIPT_SCHEMA.to_string(),
        receipt_id: "terminal-analysis".to_string(),
        graph_id: "analysis-graph".to_string(),
        chain_id: "analysis-chain".to_string(),
        terminal_task_ids: vec!["task-root".to_string()],
        completed_task_ids: vec![
            "task-root".to_string(),
            "task-child-a".to_string(),
            "task-child-b".to_string(),
        ],
        join_receipt_ids: vec!["join-child-results".to_string()],
        route_plan_receipt_ids: vec!["route-child-a".to_string(), "route-child-b".to_string()],
        budget_pool_id: "budget-pool-analysis".to_string(),
        budget_rollups: vec![SwarmTerminalBudgetRollup {
            dimension_id: "usd_minor".to_string(),
            reserved_units: 0,
            active_units: 5_000,
            consumed_units: 0,
            released_units: 0,
            reversed_units: 0,
            total_units: 5_000,
        }],
        revocation_epoch_ref: "revocation-epoch-analysis".to_string(),
        result_digest: sha256_hex(b"joined-child-results"),
        completed_at_unix_ms: now_ms(),
        issuer: witness_issuer(),
        signature: String::new(),
    };
    sign_terminal_graph_receipt(&mut receipt)?;
    Ok(receipt)
}

join: both parent IDs bound, independent of input order
terminal: 3 declared completed tasks; 5000 active units
missing completion: swarm terminal completed task set mismatch: terminal-analysis

The downloadable project mints a join from two task-to-receipt bindings and an unordered list of actual parents. Its captured output binds both parent ids regardless of input order, declares three completed tasks with 5,000 active units, and refuses a terminal receipt re-signed with one completion removed.

Next: authorize the step after a join