Files
aevolution/docs/adr/0047-world-codec.md
2026-10-08 12:08:53 -04:00

63 lines
3.5 KiB
Markdown

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