durability · 09

Atomic promotion & the library

An accepted run is swapped into the library in one atomic rename — crash-safe at every step between working and done.

maps to as-built §8

crash-safe by construction · one rename flips a run to done
From working copy to library, atomically A left-to-right flow. First a guard: the gate marker must validate before promotion begins. Then the working directory is moved into a hidden staging directory named dot-run-id-dot-promoting, where the manifest.json is written. Finally a single atomic rename moves the staging directory to its final home under library/scope/run-id. Because each step is a rename, a kill at any point is recoverable: a half-finished promotion is detected and completed on the next attempt, and an already-promoted run is a no-op. guard gate marker must validate first working/ the run's tree source of truth rename .<run>.promoting/ staging dir + manifest.json rename library/ <scope>/<run>/ canonical, durable recovery: staging-only → finish the rename · both exist → clean up staging · no manifest → write it
Every step is an atomic rename. A kill -9 between steps is detected and finished on recovery: promotion is all-or-nothing.

When a run is accepted, its work moves from a private working copy to the library, the durable, global home for finished runs. The move is built so that it is impossible to end up half-promoted.

First a guard: promotion refuses unless the gate's signed marker validates, so nothing reaches the library without passing the gate. Then the working directory is moved into a hidden staging directory (.<run>.promoting/), where the manifest.json is written. Finally, a single atomic rename moves staging to its final home at library/<scope>/<run>/.

Because each step is a rename, a crash at any point is recoverable. On the next attempt, deadreckon detects the half-finished state and finishes it: if only staging exists, complete the rename; if both exist, clean up staging; if the manifest is missing, write it. A run that was already promoted is left untouched.

After promotion, the library copy is canonical. The working directory is gone, and state.working_dir now points at the library: the artifact you review, apply, or export.

source