Determinism and replay

The same inputs reach the same verdict

An agent’s planning can vary from run to run while the portable decision logic stays reproducible. An evaluation is a function of its inputs: hold every input fixed and its value repeats; change one input and the value can change with it.

pub struct EvaluateInput<'a> {
    /// Tool call request being evaluated.
    pub request: &'a PortableToolCallRequest,
    /// The capability token authorising this call.
    pub capability: &'a CapabilityToken,
    /// Trusted issuer public keys (typically CA + kernel + authority).
    pub trusted_issuers: &'a [PublicKey],
    /// Clock used for time-bound enforcement.
    pub clock: &'a dyn Clock,
    /// Guard pipeline. Evaluated in order, fail-closed on deny or error.
    pub guards: &'a [&'a dyn Guard],
    // … session_filesystem_roots
}

The browser exercise runs a real signed grant through the same check. Its first two cases use the same request, grant, trusted issuer, and fixed clock, and they return identical values. Advancing only the clock past the grant’s expires_at returns capability has expired. The context comparison lists all five executed cases with their returned reasons.

Reproducibility therefore needs the complete context. Repeating an outside buyer’s pricing.quote request for sku-118 with the same parameters is not enough if the capability has expired, the issuer configuration has changed, or a runtime budget has been consumed. A receipt identifies a recorded decision; it does not carry every input needed to reconstruct that decision.

The core receives time through a clock interface and compares it with the capability’s signed validity window. The host supplies a trustworthy time source in production; a test supplies a fixed clock to reproduce a time-dependent decision. The evaluation also receives trusted issuer keys, the ordered guards, and any session filesystem roots. Richer entry points accept a cryptographic floor, trust-root context, and a delegated-budget registry. All of these, and the behavior of the supplied guards, belong to the reproducibility contract.

Entropy sits behind its own adapter boundary for operations that need unpredictable identifiers or nonces, and it is not an argument to EvaluateInput. Production adapters supply cryptographically secure randomness. A deterministic test generator makes tests repeatable and is unsuitable as a production nonce source.

Canonical JSON fixes the bytes for each value

Independent participants need to recover the same signed bytes from the records they exchange. Chio signs canonical JSON: the encoder fixes object-key order, number representation, escaping, and whitespace, so a supported logical value has exactly one byte representation. It rejects integer magnitudes beyond the I-JSON safe bound of 2^53 − 1.

const I_JSON_MAX_SAFE_INTEGER: u64 = (1 << 53) - 1;
// …
fn write_canonical_object(map: &Map<String, Value>, out: &mut String) -> Result<()> {
    let mut pairs: Vec<_> = map.iter().collect();
    // RFC 8785: sort object keys by UTF-16 code unit comparison.
    pairs.sort_by(|(a, _), (b, _)| cmp_utf16_code_units(a.as_str(), b.as_str()));
    // …
}
// … strict text entry: visit_u64
        if v > I_JSON_MAX_SAFE_INTEGER {
            return Err(de::Error::custom(format!(
                "integer {v} outside I-JSON safe range [-(2^53-1), 2^53-1]"
            )));
        }

Canonical bytes make records comparable, and they also make clear what a comparison establishes. A byte-identical receipt requires the entire signing input to match: request and policy bindings, decision, metadata, timestamps, receipt semantics, signing nonce, and key. Two allowed calls with the same arguments legitimately produce different receipt bytes. Each comparison answers its own question:

The canonical encoder implements the serialization boundary, receipt signing binds the signing nonce and canonical content into each record, and the wire protocol specifies the envelopes readers exchange.

Each replay mode answers one question

Select a replay check from the material you retained and the conclusion you need. A valid signature, a matching root, and a reproduced policy decision are separate results, and a mode reports only the ones it checks.

Verify a capture, then compare a candidate policy

Suppose you are reviewing a policy change and want to know whether recorded invocations would be admitted differently, without dispatching those tools again. Authenticate the capture first; then compare it with the candidate policy.

Download the architecture exercise and use the CLI from Installation. The exercise contains a signed frame, a tenant public key, an allow-all candidate policy, and a deliberately altered frame. Its key signs only this exercise.

# Authenticate the original recorded denial.
chio replay traffic --from recorded-deny.ndjson \
  --tenant-pubkey tenant.pub --json

# Compare that invocation with an allow-all candidate policy.
chio replay traffic --from recorded-deny.ndjson \
  --tenant-pubkey tenant.pub --against candidate-policy.yaml \
  --run-id architecture-tour --json

# The frame was edited without resigning: verification must fail.
chio replay traffic --from tampered.ndjson \
  --tenant-pubkey tenant.pub --json

The recorded run produced three exits, one per command:

{
  "captured": {
    "verdict": "deny",
    "guard": "policy",
    "reason": "drift"
  },
  "replay": {
    "verdict": "deny",
    "guard": "kernel.receipt_persistence",
    "reason": "internal error: durable receipt persistence unavailable: no receipt store configured"
  }
}

Read the comparison before drawing a conclusion about policy. Both verdicts are deny: the replay kernel refused because durable receipt persistence was unavailable, so the run stopped at a runtime prerequisite before policy evaluation could decide anything. Treat that as a stop condition. The selected CLI’s comparison path must provide the runtime prerequisites for policy evaluation; until it does, use the controlled evaluator exercise for reproducibility and the authenticated capture checks for evidence.

{
  "first_error": {
    "exit_code": 20,
    "line": 1,
    "message": "tenant signature verification failed: signature verify failed: signature error: Verification equation was not satisfied"
  },
  "from": "tampered.ndjson",
  "ok": false,
  "passes": 0,
  "schema": "chio-tee-frame.v1",
  "total": 1
}

The third command edits the denial reason while preserving the frame’s schema. Its invalid signature is why authentication comes before trusting content. For real captures, obtain the tenant key through a trusted channel; a key supplied alongside untrusted evidence authenticates nothing. Keep each JSON report with its exit status, since the report names the inputs and policy behind a difference and the exit code does not. The exercise retains its verification and comparison reports.

Policy comparison creates an ephemeral kernel for the run, then a fresh agent, capability, and session context for each frame, and compares the resulting decision and attribution with the capture. A tee frame does not retain the original tool-server ID or the response bytes, so this mode rejects concrete-server grants and post-output guards. It also leaves the original identity, delegated authority, runtime budget, and external effect unreconstructed. The optional --run-id namespaces report attribution; the signing keys it generates are new on every run.

See the replay traffic reference for exact arguments. For a retained receipt, such as the buyer’s approved quote for sku-301, Export evidence verifies the record; that verification establishes the record, and the original call stays unreconstructed.

Read the tests at their stated boundary

The replay corpus checks deterministic fixture artifacts against raw-byte goldens. Its generator builds synthetic records from each manifest’s expected verdict and fixed context. That catches encoding and fixture drift; establishing that those expected decisions are correct needs the full kernel, which the generator does not run.

Separate receipt property tests exercise deterministic signing and repeated Merkle construction, and differential tests compare named production functions with reference models. Each supplies evidence for the behavior it exercises. Together they stop short of a blanket replay guarantee for every runtime path or historical release.

Replay never reverses an external effect. Establishing what a tool changed requires evidence from that execution and its environment, and recovering an interrupted operation uses the runtime’s durable admission and recovery state.

Follow a decision or its evidence