3.5 KiB
[Reviewed]
ADR-0047: Bounded world snapshot and edit-journal codecs
Status
Accepted for M5.6 local binary buffers. File publication/crash consistency is M5.7.
Context
Geometry, debris and retry state form one consistency boundary. Host allocation budgets are runtime policy, not saved physical laws. Unknown versions fail closed.
Decision
Implement explicit little-endian snapshot v1 and journal v1; no native object dumps. Bind nonzero world/frame IDs supplied by the host and retain all base versions. Snapshots sort chunks by address and successful replay records by command ID, record slot capacity, revision high-water, command high-water, successful edit count, debris capacities/balances, dirty state, logical samples and full retained requests and receipts. Covered sequence is the command high-water (IDs may have gaps). Use logical cells for the initial codec; resident compression is independent.
Bounds: 4096 slots, 64 replay records, 70 MiB snapshot, 256 KiB journal, at most 64 journal commands. Total length and FNV-1a corruption checksum precede semantic acceptance. FNV is not authenticity or a security primitive. The host must provide trusted provenance for durable data; future production manifests need strong digests. Input/output buffers and bounded codec workspace are separate from resident budget. No unchecked length controls allocation or iteration. Restore takes an explicit host byte budget, builds an unpublished store and validates all state before return.
Validate cell structure/materials against the recorded procedural base: excavation cannot change material, add fill, or alter clean chunks. Removed volume across resident chunks must equal debris exactly. All changed chunks remain dirty/resident. Validate replay shape/digest/receipt amounts, chronology, current revision linkage and reverse volume feasibility for retained commands. Persist successful edit count to distinguish a full bounded replay window from accidentally dropped retry records.
Journals contain predecessor snapshot checksum, base command high-water, ordered full fresh edit requests and expected final snapshot checksum. Replay restores a detached base then applies ordinary atomic excavation, verifies the final canonical snapshot, and publishes only success. No partial replay escapes. Journal construction requires already-loaded chunks and no intervening load/evict/pin operations; those require a new snapshot. Empty journals are valid. Retry requests are not fresh journal events.
Alternatives Considered
Native structs are ABI-dependent. Geometry-only snapshots lose conservation/retry state. Reconstructing everything from 64 retained requests loses older edits. A full database/event-sourcing backend is outside this gate. Compression is deferred.
Benefits
Canonical round trips, strict version/identity boundaries and real snapshot+edit replay.
Costs
Dense logical wire cells and full exact retry payloads trade bytes for simple validation. Restore recomputes base geometry and validates history; this is not a latency SLA.
Risks
Checksums do not stop malicious forgery. This codec does not fsync, atomically publish, clear dirty flags, authenticate a client or acknowledge permanent outcomes durably. Allocation exceptions propagate to the host; failed candidates are discarded.
Consequences
Test canonical round trips, post-restore continuation/retries, journal chaining, truncation/corruption/oversize/version/identity/budget and semantic rejections with recomputed checksums. Add a bounded fuzz entry point; preserve existing goldens.