Ledger verification

Replay

Replay reconstructs runtime state from append-only execution history.

Replay

Replay is the process of proving that a trajectory ledger can be folded into a valid world projection.

Replay is not a transcript viewer. It is a verifier over structured runtime records.

Replay Inputs

Replay consumes ordered ledger entries for a trajectory:

• Root
• Commit
• Rejection
• PendingApproval
• Delegation
• Branch

Only Commit entries mutate world projection. Other entries remain part of the audit history and execution path.

Verification Procedure

Replay performs these checks:

1. Recompute each entry id from its canonical payload.
2. Verify that every non-root entry points to the previous entry id.
3. Verify contiguous sequence numbers.
4. Apply each committed structured delta in order.
5. Record head commit and head sequence.
6. Record compiler versions seen.
7. Optionally require all commits to match a pinned compiler version.
8. Optionally require every commit to carry a valid ed25519 signature from a given public key (identity / tamper drift).
9. Optionally require every commit to declare a pinned policy-set hash (policy drift).
10. Optionally compare the rebuilt world hash with an observed world hash.

Pins 7–9 are drift detectors: they let a verifier prove, long after a run, that the compiler, the signing identity, and the policy rule set match what was expected. They do not re-execute cognition or tools — replay remains a ledger-fold verification, not a re-derivation of model decisions.

The current Rust implementation exposes this path through thymos-ledger functions:

• replay(entries, cfg)
• replay_and_match(entries, observed, cfg)
• ReplayConfig::pinned_to_current()
• ReplayConfig::require_signed_by(pubkey)
• ReplayConfig::require_policy_set(hash)

Replay Output

A successful replay returns:

• rebuilt world projection
• trajectory id
• entries seen
• commits replayed
• head commit id
• head sequence
• compiler versions seen

Failure is an invariant violation. Common causes are hash mismatch, parent mismatch, non-contiguous sequence, compiler version drift, or invalid delta application.

Replaying Policy

Replay reports policy-visible ledger outcomes: rejections, pending approvals, and commit proposal ids. PendingApproval entries include the suspended proposal and its policy trace. Plain committed entries currently store the proposal id, not the full staged proposal body, so full policy-trace replay for every committed action is future work.

Replay does not re-run policy against a different policy engine unless an audit tool is explicitly performing historical policy simulation.

This distinction matters. Verification answers “what happened under the recorded runtime.” Simulation answers “what would happen under another policy version.”

Replaying Providers

Replay MUST NOT call cognition providers. Provider outputs are not stable enough to serve as replay input. The replay boundary begins after the provider has emitted intents and after runtime outcomes have been ledgered.

Replaying Tools

Replay MUST NOT call tools to rediscover observations. Tool observations and structured deltas are committed data. The replay engine folds committed deltas.

Tool re-execution is a separate diagnostic mode and should be labeled as such. It cannot be used as the primary proof of historical state.

Branch Replay

A branch first folds the source trajectory up to the source commit, then folds the branch trajectory entries. The branch root records its source trajectory and source commit. This allows isolated exploration without rewriting the original trajectory.

Delegation Replay

Delegation entries link parent and child trajectories. A parent replay can verify that delegation occurred and identify the child trajectory. A complete multi-agent replay traverses the execution DAG and verifies child trajectories under their own ledgers and writs.

CLI

thymos audit run_847
thymos replay run_847 --verify --fold-world --policy-trace

Use audit when a human needs the governance trail; use replay when a tool or script needs the verifier/fold result directly.

Expected verifier phases:

load ledger entries
verify content hashes
verify parent chain
verify sequence continuity
fold committed deltas
compare projected world
emit replay report

See demos/deterministic-replay.md for a full terminal walkthrough.