75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
[Reviewed]
|
|
# 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.
|