Skip to main content

Checkpointing

A long run should survive a power cut. clockwright checkpoints a single replication periodically and can resume it later — and the resumed run is not merely "close to" the one that would have run uninterrupted, it is proved bit-identical to it. This page is what that means in use. The format and the machinery behind it are held back until release.

note

This is an overview. The checkpoint format and the resume machinery will be published when clockwright is released.

Taking a checkpoint​

cwright simulate drives one replication and, given --checkpoint FILE --checkpoint-every EVENTS, writes a checkpoint after every EVENTS executed events (default 250,000):

cwright simulate model.yaml --checkpoint run.ckpt --checkpoint-every 250000

⭐ The write is atomic: the file is written to a temporary path and renamed into place, so a crash mid-write never leaves a corrupted checkpoint where a good one used to be — only ever the old good one, or the new one, never something in between.

Resuming: recover versus fork​

cwright resume always requires an explicit --mode, and there is deliberately no default:

  • recover continues the interrupted run. It is the one that carries the bit-identical guarantee, and it refuses anything that would break it.
  • fork deliberately continues a run from that state under different conditions. It is a different question, and it is not claimed to reproduce the original.

⚠️ The two look alike and mean opposite things, which is exactly why neither is the default. See cwright resume.

What makes this a reliable claim rather than a hopeful one​

A checkpoint records what produced it — engine version, toolchain, the model's content hash, which replication, simulated time, events executed — and refuses to resume into a different model, naming the hash that does not match. A refusal is the feature: silently resuming a checkpoint against an edited document would produce a plausible number belonging to neither.

warning

The engine version and toolchain are recorded and are NOT currently compared. Only the model hash is checked. A checkpoint written by a different build will resume, and the two halves of that run may not be bit-identical to either build alone. The recorded fields let you detect it afterwards from the result document; nothing stops it at the time. Tracked in #116.

The guarantee is checked rather than asserted: a run is killed at unpredictable points, resumed to completion, and required to produce the same trace hash as a run that was never interrupted.

Next​