4.2 KiB
ADR-0048: Local snapshot and journal publication
Status
Accepted for M5.7 single-process development files. Not the M7 production durable store.
Context
M5.6 provides canonical bounded buffers. Bytes become current only after a recoverable manifest points to verified payloads. A previous committed snapshot must survive while a replacement is prepared and published.
Decision
Use a trusted host-supplied root, then derive a directory from hex world/frame IDs. Hold an exclusive OS lock for one writer. Payloads use immutable content-addressed names containing the M5.6 FNV checksum; always compare complete bytes if a name exists. No object is overwritten. Write a same-directory temporary with exclusive/truncated access, flush file contents, atomically link/rename to its final payload name, then flush the directory.
Maintain two fixed manifest slots. A manifest carries magic/version/length, identity, monotonic generation, snapshot checksum/covered command, optional journal checksum and end command, and checksum. Write/flush a temporary manifest and atomically replace only the inactive slot; flush parent directory. That replacement is the local commit point. Never alter the active manifest or source payload before that point. If a failure is ambiguous after publication, poison this handle and require reopen/recovery. A valid manifest referencing missing/corrupt data fails closed; do not roll back acknowledged state silently. No automatic orphan deletion in this gate.
Snapshot checkpoint validates bytes by restoring them under budget before publication. A journal commit must match the current checkpoint's exact bytes and high-water, and pass detached replay. Only one journal segment is active per checkpoint. While one is published, compaction accepts only the byte-identical canonical snapshot of recovery's replayed result; command high-water alone cannot prove continuation or prevent a fork. Recovery validates the selected manifest and referenced payloads using M5.6, then replays the optional segment before returning a candidate. Existing valid manifest stays the source until new publication completes. A poisoned handle refuses recovery, reports no current generation, and requires reopen to resolve an ambiguous publication error.
Implement the minimal native OS boundary directly: POSIX lock/write/fsync/link/rename/ directory fsync; Windows exclusive CreateFile and write-through replacement. No third party library. Root directory is trusted and locally administered. Files are not network-safe/authenticated; FNV detects accidental corruption only.
Provide one-shot failure injection at payload sync, manifest sync, manifest publish, partial payload/manifest write (out of space), and post-replacement directory sync for deterministic crash-boundary tests. Partial-write failures leave only an ignored temp file and allow retry; injected interruptions poison the handle. After an interruption or ambiguous sync failure, discard the handle and reopen. A failure before manifest replacement yields old state; after replacement yields new state. Allocation/OS errors do not clear dirty state.
Alternatives Considered
In-place overwrite can destroy the old checkpoint on short write. A single manifest can be torn. Renaming the active file to a backup creates a missing-pointer crash interval. SQLite/database/object-store dependencies are future infrastructure, not a local gate.
Benefits
Clear commit point, old-source retention, bounded recovery scan and injected boundary tests.
Costs
Two manifests and immutable payloads; orphan accumulation and no concurrent writers. POSIX/Windows code paths need platform review and Linux CI.
Risks
Filesystem/controller hardware may violate flush guarantees. Windows/POSIX/network filesystems differ. Same-host files do not survive host loss. Fail-closed corruption may require operator recovery. No production DR/RPO claim.
Consequences
Test first checkpoint, journal, exact replay compaction, divergent-state rejection, restart continuation, competing lock, corrupt payload/manifest, every injected boundary, partial-write recovery, missing sequence and full-disk/OS errors. Record Linux checks separately. M5.8 performs the whole create/edit/compact/restart proof.