Implement M5.6 canonical world snapshots and edit journals
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# 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.
|
||||
@@ -51,3 +51,5 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
- [ADR-0045: Bounded chunk ownership](0045-bounded-chunk-ownership.md) - accepted for M5.4 local memory, revision tokens and dirty eviction guards.
|
||||
|
||||
- [ADR-0046: Transactional excavation](0046-transactional-excavation.md) - accepted for M5.5 atomic local volume transfers and bounded exact-request replay.
|
||||
|
||||
- [ADR-0047: World codecs](0047-world-codec.md) - accepted for M5.6 bounded canonical snapshots and detached edit-journal replay.
|
||||
|
||||
Reference in New Issue
Block a user