hraness
Theme
Appearance

replay without clocks: deterministic reruns as evidence

if you can replay it, you can debug it

drafted with ai assistance by ben guo

the rest of this lesson is free: add your email to keep reading.

Debugging a non-deterministic run is archaeology: the failure happened once, in an environment that no longer exists, and every attempt to reproduce it is a new experiment. A deterministic run is different: replay the input, get the same failure, at the same step, every time. The discipline that makes a run replayable is the discipline of removing hidden inputs, and the receipt is the evidence that they were removed.

the debugging problem

Most programs read the world implicitly: the wall clock, the filesystem order, the network's mood, the entropy source, the map's iteration order. Each implicit read makes the run unreproducible and the bug report unfalsifiable. "It failed at 3am" is not a reproducible statement.

The fix is a rule, not a tool: every input the decision-making code consumes arrives as a value. Clocks come in as now parameters, entropy as byte parameters, environment reads behind ports at the shell. When the core consumes only explicit values, the run becomes a pure function of the recorded inputs, and "replay" stops being a hope and becomes a command.

what a receipt is

A receipt is the run's canonical trace: the inputs, the decisions, and the outputs, serialized deterministically. The rule across the portfolio is that receipts contain no wall-clock fields: a timestamp inside a receipt would make two identical runs produce different receipts, which would make verification itself non-deterministic. Time, where it matters, enters as a recorded input with an explicit source.

ALGAL's verify command is the reference shape: algal verify replays a recorded run bit-for-bit and compares the receipt. If the replay diverges, either the run was not deterministic (a hidden input leaked in) or the receipt was tampered with; either way the failure is loud and localized.

how replay works

xcb's task verification is the same law at the task level: xcb tasks verify replays a task's recorded history and checks the replayed outcome against the recorded one, which turns task history from a log into evidence. Clankdar's puzzle archives apply the same idea to evaluation: the scoring run is archived with the inputs so a later audit replays the scoring and gets the same scores.

The pattern's engineering core is the port boundary: the deterministic core consumes recorded inputs; the shell's job is to record those inputs faithfully at run time. Where the shell fails to record (a clock read it forgot to log), replay exposes the gap: the receipt cannot be regenerated, and the missing input names itself.

the honest limits

Replay proves determinism, not correctness. A run can replay its bug perfectly; the receipt says what the system did, not that what it did was right. The receipt is evidence for audit and debugging, not proof of good behavior, and the projects' claims ledgers keep that distinction explicit.

Replay also only covers the recorded boundary. Anything the run read but did not record is a replay hole, and the discipline's weak point is exactly there: the input nobody thought to log. The defense is the rule that receipts carry no ambient state and that verification replays from the receipt alone; a run that cannot be re-driven from its own recorded inputs fails verification, which is the leak detector working as designed.

The third limit is the boundary itself: replay verifies what happened inside the sealed core. The outside world's behavior (the provider's response at the time, the file that existed then) is only recorded, not re-executed. A receipt attests the system's decisions given recorded inputs; it does not resurrect the world.

Kept in that scope, though, replay is the cheapest debugging and audit infrastructure in the portfolio: a failing run is a case you can hand to a fuzzer, a shrunken counterexample you can attach to a report, and a deployment you can verify from an artifact without trusting the machine that produced it.

keep reading: free for subscribers

the rest of this lesson is free. enter your email to subscribe, and every subscriber lesson unlocks in this browser.

already subscribed? enter the same email to unlock.