# 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.