5.4 KiB
M5.4 bounded active chunks
Implemented by evo::world, header evo/world/chunks.hpp.
ADR-0045 scopes local ownership; this is
not a region lease, distributed authority mechanism or durable store.
Contract
Create a store with one immutable BaseDescriptor, 1..4096 slots and an explicit accounted-byte budget. All operations are single-owner/sequential; callers must not race reads against mutation. World/frame identity belongs to the containing host. Different stores are separate local domains; revision numbers are not globally unique. The owning unique_ptr may move, but the store itself cannot move or copy.
| Operation | Success | Refusal / invariant |
|---|---|---|
| minimum_bytes(slots) | Store object + fixed directory + replay records + 32 KiB scratch reservation | Invalid slot count rejected before multiplication |
| create | Empty store with validated descriptor | Invalid config/version/budget before directory allocation |
| load(address) | Return current token or regenerate and publish one base chunk | Invalid address, slot or byte exhaustion, revision exhaustion; no existing state changes |
| view(address) | Token for loaded address | Missing is explicit; no implicit load |
| read(view, local) | Copy one CellSample | Foreign/stale token or out-of-range local cell; no raw storage pointer |
| mark_dirty(view) | Pin chunk, invalidate previous token, return current token | Stale token or revision exhaustion; repeat on current dirty token is idempotent |
| evict(view) | Free clean payload and directory slot | Stale or dirty token rejected; no auto eviction |
Views contain owner/slot/revision internally. They are read tokens, not immutable historical snapshots: every read checks current ownership and revision. Old tokens fail after dirty marking or eviction/reload. They must not outlive the store, including an object later allocated at the same address. They cannot authorize persistence or cross-process operations. Epoch exhaustion is checked before increment; no wraparound.
Dirty marking currently changes only lifecycle metadata, not geometry. There is no clear-dirty API. M5.5 now adds accounted excavation; M5.6/5.7 must establish durable revision coverage before permitting cleanup. Destruction at host shutdown frees memory and is not a save operation. No production host should use this in-memory store as its sole durable copy of changes.
stateDiagram-v2
Absent --> Clean: load, budget available
Clean --> Absent: explicit current-view eviction
Clean --> Dirty: conservative pin, new revision
Dirty --> Dirty: repeated current-view pin
Dirty-to-Absent is deliberately unavailable. Capacity pressure returns to the host. It cannot regenerate modified data to make room.
Representation and budgets
CompactCells accepts exactly 4096 validated CellSample values. It is immutable and move-only; moves reset the source to uniform void. Material keys and fills both participate in equality. This geometry utility checks structural cells, not material table membership or resource authority. ChunkStore loads only M5.3 table-valid base.
- Uniform: one inline word, zero allocated payload bytes.
- Palette: first-occurrence keys (2..256), plus 4096 byte indexes, stored as keys followed by 1024 packed uint32 index words. Payload = 4*K+4096 bytes.
- Dense: 4096 uint32 words = 16384 bytes after the 257th distinct key.
Logical words combine material low 16 bits and fill high 16 bits. Native arrays are not a wire format. M5.6 must specify canonical serialization independently.
Fixed directory bytes include optional payload objects and lifecycle metadata for all configured slots, occupied or not. Accounted bytes add exact allocated payload array element sizes plus a permanent 32 KiB conservative scratch allowance and fixed replay records under ADR-0046. Loads use 4096 logical words and 256 palette keys. Load generates through point queries to avoid an extra dense vector, computes required payload before allocation, then publishes without throwing. On allocator failure existing state is unchanged; allocation exceptions propagate to the host. Clean eviction subtracts payload only.
The allowance remains charged when no load runs. Allocator headers/cookies, ordinary call frames, caller buffers and OS runtime are excluded: this is not RSS or an OS memory cap. Standalone CompactCells creation is outside a store's budget. It uses the same bounded scratch plus output, with no budget parameter. Future replacement/edit operations must budget old and new buffers simultaneously; they cannot inherit a claim of in-place promotion from this immutable implementation.
Verification and next boundary
CTest world-chunk-contracts checks distinct counts 1/2/255/256/257/4096, every stored
sample, material/fill distinction, invalid lengths/indexes, moved-from validity,
far-apart addresses, clean regeneration, slot and byte backpressure, stale and foreign
tokens, conservative dirty pinning and rejection without changing resident state.
Existing generator goldens remain active. Counter exhaustion is guarded in code but
not forced via a public test-only state injection API.
M5.5 now adds transaction IDs, full request identity, expected revisions, a finite debris destination and atomic excavation; see TERRAIN_EDITS.md. Snapshot/crash recovery, threading, automatic LRU, renderer and Kubernetes integration remain later work.