Deterministic Replay Harness¶
Replay harness — instantiates Deterministic Transition Contract
Re-executes a transition from a recorded present-state snapshot and input trace, reproducing the original successor exactly — and flags any divergence as proof that some factor was never captured.
The strongest evidence that a transition is deterministic is that you can make it happen again on demand. A Deterministic Replay Harness is the execution engine that does this: it captures the present-state snapshot and the ordered trace of every input, event, and non-deterministic draw that fed a transition, then feeds them back through the same laws to regenerate the successor. Its defining move is re-execution from a record — it does not merely compare stored outputs or check a rule, it actually runs the transition forward again from the captured beginning. When the replay reproduces the original successor, determinism is demonstrated; when it drifts, the drift is a signal that some influence acted on the first run that the trace never captured, and the harness is the tool that turns that invisible influence into a reproducible bug.
Example¶
An online multiplayer strategy game runs its match logic in lockstep: every client simulates the same battle from the same starting board and the same stream of player commands, and they must stay bit-identical or the game "desyncs" — two players see different unit positions and the match corrupts. A desync report arrives: after forty minutes, one player's client shows a destroyed tank the other still sees alive.
The replay harness is how the developers catch it. During the match each client wrote a trace: the initial board snapshot and the exact ordered list of timestamped commands ("move unit 44 to tile 12,7 at tick 9,214"). The harness loads the snapshot, replays the command stream through the identical simulation code, and — on a healthy build — regenerates the same tick-9,214-onward board every time. Replaying the desynced match, the harness reproduces the divergence at tick 22,400: one code path read the system's floating-point rounding mode, which differed between the two players' CPUs. That factor was never in the trace, so replay across the two environments diverges exactly where the live match did. The fix is to capture or normalize that factor; the harness then replays clean.
How it works¶
The harness reconstructs a run rather than re-deriving it:
- Capture the starting point. Record a present-state snapshot precise enough that the transition can restart from it — every variable the laws will read, nothing they won't.
- Trace the inputs in order. Log the full ordered stream of external events and non-deterministic draws (commands, timestamps, random values, service responses) so nothing that entered the first run is left to chance on the second.
- Re-run through the same laws. Feed snapshot and trace back into the identical transition logic and let it execute forward, producing a fresh successor.
- Divergence is the diagnostic. If the replayed successor differs from the original, an uncaptured factor exists; the harness bisects the trace to localize the first tick where the two paths part.[n1]
Tuning parameters¶
- Snapshot granularity — how much state is captured at the start. Too little and replay cannot restart faithfully; too much and traces bloat and slow the live system being recorded.
- Trace fidelity — which non-deterministic sources are logged (inputs only, or also timing, scheduling, and randomness). Higher fidelity reproduces more but adds recording overhead and larger traces.
- Capture overhead budget — how much slowdown the live run will tolerate to be recordable. Cheap always-on tracing catches every incident; heavy tracing must be sampled and misses rare ones.
- Replay isolation — whether replay re-hits real dependencies or plays back recorded responses. Recorded playback is deterministic; live re-hits test the real substrate but reintroduce drift.
- Divergence tolerance — exact-match versus a numeric epsilon. Exact match catches everything but flags benign floating-point noise; a tolerance hides that noise and can also hide a real bug.
When it helps, and when it misleads¶
Its strength is incident reconstruction and hard-to-reproduce bugs: it turns "it happened once in production and we can't make it happen again" into a runnable, bisectable case, and it proves determinism by exhibiting it rather than asserting it.
It misleads when the trace is incomplete in a way that flatters the system. If the harness only replays inside the same environment that produced the original run, a hidden environmental factor rides along unnoticed and replay looks perfectly deterministic — right up until the same code runs elsewhere. A harness can thus certify a run as reproducible while an uncaptured factor waits to bite. The guarding discipline is to replay across a different environment than the one that recorded the trace, so that any factor the trace failed to capture is forced to reveal itself as divergence rather than hiding in a shared substrate.
How it implements the components¶
deterministic_replay_trace— the harness both produces and consumes the ordered record of inputs and draws, and its re-execution is the trace being exercised to regenerate the successor.present_state_snapshot— it captures and restores the starting state at the fidelity needed for a faithful restart.
It does not implement determinism_acceptance_test — that pass/fail verdict against a frozen reference is Golden Master Transition Test; the harness re-executes but does not itself assert acceptance. Nor does it implement hidden_state_exposure_register — cataloguing which factors are hidden is Differential Transition Comparison; the harness merely surfaces a divergence for that catalog to explain.
Related¶
- Instantiates: Deterministic Transition Contract — supplies the replay evidence the contract's verification step depends on.
- Consumes: Transition Audit Log supplies the recorded events the harness replays.
- Sibling mechanisms: Differential Transition Comparison · Golden Master Transition Test · Transition Audit Log
Editorial Notes¶
Form Classification¶
Form family: Experiment, Test & Rehearsal
Rationale: Deterministic Replay Harness operates as a bounded trial, probe, simulation, or rehearsal that generates evidence from performance because it re-executes a transition from a recorded present-state snapshot and input trace, reproducing the original successor exactly — and flags any divergence as proof that some factor was never captured.
Independent corroboration: The frozen evidence defines Deterministic Replay Harness as 'Re-executes a transition from a recorded present-state snapshot and input trace, reproducing the original successor exactly — and flags any divergence as proof that some factor was never captured', so its operative form is Experiment, Test & Rehearsal.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Debugging systems cohered record-and-replay harnesses that capture nondeterministic inputs and re-execute an exact run to reproduce divergence.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
[n1] Record-and-replay debugging captures a program's non-deterministic inputs on one run so the exact execution can be re-created deterministically later — the technique behind tools such as Mozilla's rr. Its power for diagnosis is that a bug seen once becomes a bug you can re-run as often as you like. ↩