Replay Artifacts

What Is An Evidence Pack?

An evidence pack is the record of a single Riptide run. It's a directory of files — machine-readable and human-readable — that together answer: what ran, what happened, and how do I reproduce this exactly?

The idea is that a finding should survive handoff. A screenshot of a terminal or a Slack message "hey this broke" loses context fast. A pack doesn't: it contains the committed inputs, the seed, which invariants fired and when, a full event trace, and a script that reruns the same invocation on any clean machine. A reviewer opens the pack and gets everything they need without asking you questions.

Why it has a canonical hash

Every pack is hashed over its output. If the same committed inputs produce the same hash on two different machines, you know the behavior is deterministic. If the hash drifts, something meaningful changed — a toolchain pin, the program bytes, the scenario config — and that's worth investigating before updating the pin.

What it is not

A pack is simulation evidence, not a broad review result. It doesn't certify a program safe, doesn't replace human code review, and doesn't reconstruct mainnet history. It proves this specific trajectory behaves this specific way — which is often exactly what you need when explaining a risk to CI or to a reviewer.

Pack Shape

Concretely, evidence packs land under .riptide/pack/<run-id>/. They index what ran, what fired, how to rerun it, and where the input and output paths live relative to the repo.

.riptide/pack/<run-id>/
  manifest.json
  summary.md
  trace.md
  rerun.sh
  inputs/paths.json
  outputs/paths.json

The pack indexes inputs and outputs with repo-relative paths. It is the reviewer-facing handle for a run, not a replacement for the committed adapter, scenario, trajectory, or program bytes that the run consumed.

manifest.json

The manifest is the machine-readable index: scenario, adapter, run id, canonical hash, invariant firings, exit code, inputs, outputs, and simulation boundaries.

summary.md

The summary is a short human-readable note for reviewers. It should tell them what ran, what crossed a boundary, and which files to inspect next.

trace.md

The trace captures per-tick review hooks: invariant firings, scheduled actions, oracle writes, bridge firings, and other events of interest.

rerun.sh

The rerun script is POSIX sh compatible. It changes to the repo root and replays the invocation that emitted the pack.

sh .riptide/pack/<run-id>/rerun.sh

Canonical Hash

The canonical hash is a SHA256 reproducibility check over the run output. The same committed inputs should reproduce the same canonical hash. Drift means the behavior or inputs changed and needs investigation.

Verify A Pack From A Clean Checkout

Use riptide review <pack> when you want to inspect a downloaded or mirrored evidence pack without rerunning the engine. The command reads the manifest, follows the input and output path indexes, verifies the Riptide canonical hash for the indexed simulation result, and checks that rerun.sh is syntactically valid without executing it.

riptide review fixtures/replays/lending-whale-bad-debt/
riptide review fixtures/replays/lending-whale-bad-debt/ --json

The JSON form includes the manifest digest, validation results, invariant fires, canonical hash verification result, and raw output SHA256 for piping into CI or reviewer notebooks.

Review mode does not execute rerun.sh. It validates the pack structure and hash so a reviewer can inspect existing evidence without starting the simulator.

Trust Boundary

Case Studies

Case studies mirror flagship replay packs into review pages with the canonical hash, deterministic rerun, invariant fires, and simulation evidence, not a broad review result. Lower proof-level entries live alongside the failure-pattern explainers.