Expand description
Recoverable multi-file writes.
Three primitives, used first by the user-scope skill installer and reused by the repository apply. A lock serializes writers over one record. A stage writes every intended byte beside its destination and replaces it by rename. A journal names every destination before the first replacement, so a run the process did not finish is rolled back by the next invocation rather than left half-applied.
What this guarantees, and what it does not. Each replacement is atomic
on its own; the set is not. A process that dies at any boundary of the
persistence order below leaves a journal, and the next invocation
restores every destination before it plans new work. Recovery after
power loss rests on that order and on the platform’s fsync semantics,
and is claimed no further.
The persistence order is fixed and the same for every domain. Every backup copy is written and synced. The journal is written and synced, and its directory synced. Each scratch file is written and synced, then renamed over its destination, then the destination’s directory synced. Each journal state change is a rewrite through the same pair. The record is replaced last. The journal is unlinked and its directory synced.
Modules§
- journal
- The record a run leaves before its first replacement.
- lock
- An OS advisory lock with holder metadata.
- stage
- Scratch files beside their destinations, and backups by digest.
Functions§
- sync_
dir - Flush a directory entry, so a rename into it survives a crash.
- sync_
parent - Flush the directory holding
path, where it has one.