notarius/docs/adr/0007-separate-checkpoint-recording-from-reuse.md

ADR-0007: Separate checkpoint recording from reuse

Status: Accepted Date: 2026-07-19

Context

ADR-0006 made checkpoint I/O conditional on an explicit --resume invocation. That policy requires an operator to anticipate the need for recovery before a run begins. A failed ordinary run cannot reuse completed work because it did not record checkpoints.

Recording reconstructible state and authorizing reuse are separate operational decisions. Recording consumes storage and retains sensitive derived application data, while reuse may change which module operations execute during a run.

Decision

ADR-0006's separation of output, cache, and debug surfaces remains in effect; this decision supersedes only its checkpoint invocation policy.

Checkpoint recording is controlled by an explicit persistent Boolean configuration setting and remains disabled by default. When recording is enabled, every run records checkpoint transitions and reusable approved stage results.

Checkpoint loading remains an invocation policy. Only a run with --resume loads and reuses compatible completed work. A recording-enabled run without --resume executes every stage normally and never loads checkpoints. A resume request while recording is disabled is rejected.

The existing checkpoint identities, compatibility rules, payload format, filesystem root behavior, and pipeline collaborator contracts remain unchanged.

Alternatives considered

• Continue coupling reads and writes to --resume. This is safe by default but prevents recovery unless resume was anticipated on the earlier run.
• Always record checkpoints. This maximizes recovery but creates potentially sensitive state without explicit operator consent.
• Add a multi-value recording policy. This preserves the old behavior as an option but adds configuration complexity without a current need.

Consequences

Operators can opt into recovery-ready runs while keeping checkpoint reuse explicit. Enabled successful, rejected, and failed runs may all leave sensitive checkpoint state, so operators remain responsible for access and retention. Disabled configurations perform no checkpoint I/O, and --resume requires the operator to enable recording first.