90 lines
5.4 KiB
Markdown
90 lines
5.4 KiB
Markdown
# M5.4 bounded active chunks
|
|
|
|
Implemented by `evo::world`, header `evo/world/chunks.hpp`.
|
|
[ADR-0045](../adr/0045-bounded-chunk-ownership.md) 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](TERRAIN_EDITS.md); 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.
|
|
|
|
```mermaid
|
|
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.
|