62 lines
3.5 KiB
Markdown
62 lines
3.5 KiB
Markdown
# 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.
|