Receipt Aggregation

One log per node, no log for the fleet

The bounded operational profile files the receipt and checkpoint plane at guarantee class local-only, and states the shipped truth and the non-claim in the same row.

Read the fourth column as the boundary of this page. Receipts replicate; checkpoints do not. The shared per-peer pull round names its streams by function pointer, and none of them is a checkpoint:

fn peer_pullers() -> [Puller; 4] {
    [
        sync_peer_budgets,
        sync_peer_tool_receipts,
        sync_peer_child_receipts,
        sync_peer_lineage,
    ]
}

Revocations replicate on their own round budget, and the capability authority arrives as a full snapshot. The word checkpoint does not appear in the trust-control router or its path constants at all, and nothing in the sync loop reads or writes kernel_checkpoints on a peer. A follower re-appends each replicated receipt into its own claim log at its own entry sequence and, if it checkpoints at all, signs with its own kernel key. Log identity is derived from that key:

#[must_use]
pub fn checkpoint_log_id(checkpoint: &KernelCheckpoint) -> String {
    let log_key_bytes: Vec<u8> = match checkpoint.body.kernel_key.algorithm() {
        SigningAlgorithm::Ed25519 => checkpoint.body.kernel_key.as_bytes().to_vec(),
        SigningAlgorithm::P256 | SigningAlgorithm::P384 | SigningAlgorithm::Hybrid => {
            checkpoint.body.kernel_key.to_hex().into_bytes()
        }
    };
    format!("local-log-{}", sha256_hex(&log_key_bytes))
}

Two nodes holding the same set of receipts therefore produce two logs, not one, with different sequence numbers over different orderings and different roots. Aggregation across a cluster is aggregation of receipts, not of logs.

What is on disk, and which of it moves

The claim log is the join that makes checkpointing possible over two receipt families at once. Both receipt tables project into it through AFTER INSERT triggers, under one autoincrementing sequence and one uniqueness constraint on the receipt id:

CREATE TABLE IF NOT EXISTS claim_receipt_log_entries (
    entry_seq INTEGER PRIMARY KEY AUTOINCREMENT,
    receipt_id TEXT NOT NULL UNIQUE,
    receipt_kind TEXT NOT NULL,
    source_seq INTEGER NOT NULL,
    timestamp INTEGER NOT NULL,
    ...
    raw_json TEXT NOT NULL,
    CHECK (receipt_kind IN ('tool_receipt', 'child_receipt'))
);

A checkpoint batch is a contiguous range of entry_seq, so a single Merkle tree can carry tool and child leaves together. validate_checkpoint_against_claim_log reloads exactly that range, rebuilds the tree, and refuses any checkpoint whose tree_size or merkle_root disagrees with the rows on disk.

Three evidence classes

Every node and edge in the lineage projection carries one of three classes. chio-lineage defines them as EvidenceClass, whose doc comment names spec/PROTOCOL.md as the source of the values; the receipt and capability types carry the parallel GovernedProvenanceEvidenceClass (aliased ProvenanceEvidenceClass) from chio-core-types. Read the third column as what the ingest paths actually emit, not as what the class names could cover.

That one upgrade is a single predicate, and it checks the binding as well as the signature. It runs over replay-corpus fixture rows, not over the live store:

fn signed_lineage_statement_verifies(row: &CorpusReceiptRow, parent: &str) -> bool {
    let Some(statement) = row.signed_lineage_statement.as_ref() else {
        return false;
    };
    statement.parent_receipt_id == parent
        && statement.child_receipt_id == row.receipt_id
        && statement.evidence_class == ProvenanceEvidenceClass::Verified
        && matches!(statement.verify_signature(), Ok(true))
}

A statement that fails any of the four conjuncts leaves the edge Observed. Nothing in the ingest path promotes on the strength of the declared class alone.

From one append to one bundle

Append, forward, re-read

POST /v1/receipts/tools, POST /v1/receipts/children, and POST /v1/lineage all open the same way: validate the service token, then hand the body to forward_post_to_leader. A follower forwards and returns the leader response verbatim; the leader writes locally and then runs respond_after_leader_visible_write, which re-reads under an admin read context and answers 500 with tool receipt was not visible on the leader after write when the read comes back empty. That re-read is not a point-load: it is a filtered list bounded to MAX_LIST_LIMIT rows, ordered seq DESC and scanned for the id, so a burst of more than 200 newer receipts matching the same capability, tool, and decision between the write and the re-read would report a durable write as a 500. It is one re-read, not a poll. The forwarding rules, the quorum and lease checks in front of them, and the 503 catalogue belong to Leader & Failover.

Every receipt append verifies before it queues. append_verified_chio_receipt_record calls ensure_chio_receipt_verified first, so a receipt whose signature or action parameter hash does not check never reaches the commit actor. That applies to receipts arriving over the wire from a peer exactly as it applies to locally minted ones. Read the scope of that check precisely: it verifies the receipt against the key the receipt itself carries, at the ReceiptCryptoFloor::AllowHybrid floor, with no policy handle in scope. It does not check that key against a trust anchor or an issuer allowlist. Whoever clears Cluster Peer Auth can push any internally consistent self-signed receipt into a follower’s claim log.

Replicate, then rebuild

A pull round applies each receipt page through the same append_chio_receipt and append_child_receipt the public routes use, so a replicated receipt is signature-checked on arrival, takes a fresh local sequence, and fires the claim-log trigger on the follower. The lineage stream is different: sync_peer_lineage calls upsert_capability_snapshot, which runs validate_snapshot_for_transport and, against an existing row, ensure_snapshots_compatible. Neither verifies a signature. Three consequences follow.

• The streams are non-dense. Receipt sequences are AUTOINCREMENT written with ON CONFLICT DO NOTHING and pruned by retention, so gaps are legitimate. The page guard is require_forward_progress, not contiguity. Lineage paginates on the capability_lineage rowid, which is non-dense for its own reason: an upsert on an existing capability keeps its rowid, and deletes leave holes. A follower cannot distinguish a row that was pruned from a row it never received, which is why cross-node append-only coverage is a non-claim rather than a bug.
• The delta stream is admin-scoped. Both receipt delta handlers read with ReceiptReadContext::admin_service() and are gated only by validate_cluster_peer_auth. Tenant isolation is a property of the read routes below, not of the wire between peers, which is why Cluster Peer Auth is load-bearing here.
• Ordering is local. Two nodes that receive the same receipts in different orders assign different entry_seq values, so their checkpoint batch boundaries and roots differ even when their row sets converge.

Checkpoint, where a signer exists

The background signer is installed by the kernel at attach, when checkpoint_batch_size is greater than zero and the store reports checkpoint support. DEFAULT_CHECKPOINT_BATCH_SIZE is 100; a value of 0 disables automatic checkpointing, and the attach then refuses any retention policy, because a retention watermark can only advance to a checkpoint boundary. A web3-enabled deployment refuses 0 outright, through validate_web3_evidence_prerequisites. The builder is incremental: it loops while claim_log_max_seq - checkpointed_entry_seq >= max_batch, rebuilding one bounded batch at a time from the cached head rather than re-verifying the chain, and each batch passes ensure_claim_log_range_contiguous before it is built, so a hole in the claim log stops the chain rather than being checkpointed over.

The trust-control service installs no signer. Every handler opens the store with a bare SqliteReceiptStore::open(path). A control-plane node that only replicates therefore accumulates receipts and produces no checkpoints of its own; checkpoints on that file come from a kernel attached to it, or from chio receipt checkpoint create --kernel-seed-file. Plan the fleet accordingly: chio receipt checkpoint status reports the gap, and chio receipt audit runs the claim-log projection check plus a full checkpoint-chain verification.

Both readings against a database holding two receipts and no checkpoint yet. next_range is the batch each verb would build next, which is why the two disagree: status reports the whole uncheckpointed prefix and audit reports the first batch it would verify.

chio --receipt-db ./.chio/receipts.db receipt checkpoint status
chio --receipt-db ./.chio/receipts.db receipt audit

$ chio --receipt-db ./.chio/receipts.db receipt checkpoint status
status: healthy
committed_entry_seq: 2
checkpoint_seq: none
checkpointed_entry_seq: 0
next_range: 1..=2
retention_watermark_entry_seq: none

$ chio --receipt-db ./.chio/receipts.db receipt audit
status: healthy
committed_entry_seq: 2
checkpoint_seq: none
checkpointed_entry_seq: 0
next_range: 1..=1
retention_watermark_entry_seq: none

Point either verb at a control plane and it refuses rather than proxying, which is the callout above as the operator meets it:

$ chio --control-url https://ctl-a.internal:8940 \
    --receipt-db ./.chio/receipts.db receipt audit
error [urn:chio:error:cli:other]: receipt audit requires local --receipt-db; remote receipt operator operations are not supported in this release
context: {"domain":"cli","severity":"error","stability":"deprecated","string_code":"CHIO-CLI-OTHER"}
suggested fix: Preserve the original message and migrate the call site to a specific registry code when touched.
exit=1

Roll up

Reads resolve a principal before they touch a store, and the resolved ReceiptReadContext is what the SQL filters on. Tenancy & Read Scoping owns that resolution. What matters for aggregation is which rollups a tenant token can reach at all.

Analytics returns counts by decision plus three derived ratios: reliability as allows over terminal outcomes (allow plus cancelled plus incomplete, denials excluded), compliance as non-denials over total, and budget utilization as charged over charged plus attempted. Each is None rather than zero when its denominator is zero. The grouped dimensions are truncated top-N lists, not complete ones: group_limit defaults to 50 and clamps at MAX_ANALYTICS_GROUP_LIMIT = 200 per dimension, and the time bucket defaults to a day. Only summary covers every matching row. Every one of those numbers is computed over the rows on the node answering the request, which for a clustered node means the rows its own pull rounds have caught up on.

chio-lineage performs no file or network I/O; it folds frames and rows already read from disk into an in-memory graph, and chio lineage query|diff|roots reads JSON dumps rather than a live cluster. The persistent recursive-CTE walk lives in chio-store-sqlite/src/lineage_cte.rs behind a lineage cargo feature that is off by default, so a stock build of the receipt store does not carry it. Both paths carry the same DEFAULT_DEPTH_LIMIT = 20 constant, but neither enforces it on its own: the in-memory walk takes a QueryBounds whose default also caps rows at 10,000 and returns a typed TruncationMarker, while the CTE takes depth and row caps as arguments and returns a plain truncated boolean alongside depth_reached. A deep delegation graph returns a bounded answer that says it is bounded, in two different shapes.

Prove

Inclusion proofs are not stored. build_evidence_export_bundle rebuilds the tree from receipts_canonical_bytes_range over the checkpoint’s full claim-log range, child leaves included, and reads the leaf index for each selected tool receipt off it. That is the aggregation step that matters here: a proof is only as wide as one node’s claim log, and anything outside a checkpointed range is named in uncheckpointed_receipts rather than dropped.

Child receipts get a second, blunter bound before any of that, decided by the query alone and recorded in the manifest as one of three scopes. That trichotomy, the package format, the offline verifier, and the import path are Evidence Export.

Anchoring is a separate lane

Turning a local checkpoint into evidence a third party can check without trusting the operator is the job of chio-anchor. It projects a KernelCheckpoint into a Web3CheckpointStatement, assembles an inclusion proof straight from an evidence bundle, and normalizes multi-lane proofs across an EVM root registry, a Bitcoin OpenTimestamps super-root, and a Solana memo. Its verifiers are fail-closed in the directions that matter here: build_anchor_inclusion_proof_from_evidence_bundle refuses a receipt listed in uncheckpointed_receipts, and requires exactly one matching receipt, one inclusion proof, and one checkpoint; verify_checkpoint_publication_records rejects a publication that carries neither a trust-anchor binding nor a successor witness. The economic and settlement side of that lane is On-Chain Settlement.

No report may collapse asserted into verified

The rule is written into the profile, not left to reviewer discipline:

- delegated `call_chain` fields remain `asserted` on outward surfaces unless
  Chio can back them with observed local lineage or verified signed provenance
  artifacts
- no report or export surface may collapse `asserted` lineage into `verified`
  truth
- checkpoint continuity records support local audit and
  `transparency_preview` claims only; current checkpoints are built over the
  local claim log, so child receipts with persisted canonical bytes can be
  covered without turning the local log into public transparency
- child receipt inclusion-proof export remains deferred unless an evidence
  package explicitly exports child receipt proof rows

The authorization-context report obeys it structurally rather than by convention: it counts asserted_call_chain_receipts, observed_call_chain_receipts, and verified_call_chain_receipts as three separate summary fields, alongside counts of how many receipts carried a session anchor, a request-lineage record, and a receipt-lineage statement. A call_chain_receipts total sits beside them, but it is a count of receipts carrying any class at all: nothing sums asserted into verified, and a reader who wants a verified count reads the verified field. The profile files that whole report family at informational-only: a derived projection over signed receipt metadata, which does not upgrade asserted call-chain fields into verified upstream truth.

Guarantees and limits

Next Steps

• Receipts & Audit · the signed body, canonical JSON, and the checkpoint statement this page aggregates
• Retention & Archive · the checkpoint-aligned watermark that makes the streams non-dense in the first place
• Replication & Convergence · the pull round, its page guards, and the snapshot backstop
• Evidence Export · the digest-bound package these rollups leave in, and the offline verifier for it
• Cluster Peer Auth · the only boundary in front of an admin-scoped receipt delta stream
• Tenancy & Read Scoping · which of these rollups a per-tenant read token can reach, and why
• On-Chain Settlement · chio-anchor, its lanes, and what a published root buys a verifier
• Delegation Witnesses · what evidence looks like once the counterparty is not yours to run