3.7 KiB
[Reviewed]
ADR-0045: Bounded local chunk ownership
Status
Accepted for M5.4. Single local owner, not distributed region authority or durability.
Context
M5.3 produces reproducible base cells; ADR-0043 selects compact 16-cube storage. Address extent must not drive allocation. Eviction must not lose pending dirty state.
Decision
Use a noncopyable/nonmovable ChunkStore created with a fixed slot count (1..4096), byte budget and immutable BaseDescriptor. A fixed directory bounds metadata and linear lookup; no implicit eviction, threads or global cache. Loading an absent chunk regenerates base data. Existing loads are idempotent. Missing capacity returns backpressure and leaves prior state unchanged. Allocation exceptions reach the host.
CompactCells is an immutable value with uniform, byte-palette (<=256 distinct keys), or dense representation. Keys include material and fill. Palette order is first X-fast occurrence. Packed byte indexes share one exactly-sized uint32 array with keys; this is an in-memory implementation, not a wire format. Uniform has no payload allocation. Dense contains 4096 uint32 values. Build publishes only after success.
Charge sizeof(store), all directory entries, owned payload bytes, and 17 KiB reserved for construction scratch (4096 logical words plus 256 palette keys). Check budget before allocating payload. Allocator headers/runtime stack/caller buffers are outside this accounted budget; report it as accounted bytes, never RSS. Array element counts are exact, no vector growth. The standalone compact factory is outside store budgets.
Views contain owner, slot and monotonic incarnation/revision token; reads revalidate before access and return copied cells, never dangling spans. Views must not outlive their store. Store is immovable; foreign-store views fail. Successful load and first dirty marking consume nonwrapping tokens; exhaustion rejects changes. Evict/reload cannot revive an old view. Revision tokens are local, not durable edit revisions.
mark_dirty is conservative pre-write pinning, changes no geometry and invalidates old views. Repeated marking of the current dirty view is idempotent. There is no mark-clean, overwrite, or edit API: M5.5 introduces accounted transactions; later persistence must prove durable coverage before clearing dirty state. Explicit eviction requires a current clean view. Destruction is a host shutdown boundary, not durable storage; the host must not destroy a store with unsaved changes in a running world.
Alternatives Considered
Automatic LRU hides eviction decisions and requires pin lifetime accounting. Shared snapshots can retain unbudgeted payloads. Raw spans invite dangling reads. Maps complicate allocator accounting; linear fixed slots suffice for this bounded gate.
Benefits
Bounded metadata/payloads, reproducible regeneration and explicit stale/dirty refusal. No edit or persistence shortcut leaks into the geometry library.
Costs
Linear lookup, reconstruction scratch reservation and copied point reads. No concurrent mutation support, auto eviction, persistence or dirty recovery yet.
Risks
Accounted bytes exclude allocator overhead and are not an OS ceiling. Owner lifetime is a caller obligation. Dirty pinning can exhaust capacity intentionally; host must apply backpressure rather than dropping state. Larger workloads require measurement.
Consequences
Test far-apart chunks, uniform/palette/dense equality, exact budget boundaries, slot exhaustion, invalid input, stale/foreign views and dirty eviction refusal. Retain existing generator goldens and simulation formats. Next is M5.5.
M5.5 follow-up
ADR-0046 adds atomic excavation and fixed replay metadata. Its 32 KiB scratch reservation supersedes the original 17 KiB allowance; dirty clearing remains absent.