3.4 KiB
ADR-0043: Bounded chunk layout comparison
Status
Accepted for the bounded M5 geometry experiment; production scale remains unproven. No production container, wire codec, generator or meshing dependency is introduced.
Context
ADR-0042 supplies cells and edge candidates but selects no physical representation. M5.2 needs evidence for uniform terrain, sparse edits, varied material, excavation and high entropy.
Decision
Select edge 16 (4096 cells) with uniform/palette/dense geometry for M5.3/M5.4, based on the measured comparison. Limit palette keys to 256 including fill; promote on the 257th retained key. Dense payload is 16 KiB, indexes 4 KiB, palette at most 1 KiB. Production storage must bound capacity, budget simultaneous promotion buffers (21 KiB plus overhead), and reject allocations outside M5.4's explicit resident/dirty-state budget. This selects a scoped policy, not an implemented production container or memory SLA. Edge 8 raises directory count; 32/64 raise dense allocation and edit/load granularity. The 16 choice balances these costs; it is not a planet-scale optimum. Sparse pages remain a later optional-field candidate, not the geometry default.
Compare three dependency-free test-only representations: dense 32-bit logical cells; uniform -> 8-bit palette indexes -> dense fallback at 257 distinct retained values; and uniform base plus sorted sparse 4x4x4 dense pages. Palette keys include fill as well as material. Exercise edges 8/16/32/64 with independent dense equality checks. Use deterministic fixtures and explicit seeded edit streams. Measure construction, full scans, edits, object plus owned capacity, sampled peak owned capacity, and an explicit encoding-size estimate (not an implemented codec). Include a 128-cube tiled memory estimate so per-chunk metadata is visible when comparing edges. No library choice, new dependency or permanent simulation rule follows from timing.
Use one warmup and three measured fresh runs. Timed phases exclude oracle checks. Do not gate CI on wall time. Verify uniform compression, palette promotion/fallback, page release, edit-to-original restoration, bounds and canonical logical equality. Storage mutation is a fixture operation only, not an authorized terrain/mass edit.
Alternatives Considered
Dense alone is the baseline. Bit-packed variable palettes and per-page compression add decoding complexity; measure these later if byte indexes prove inadequate. General octrees and planet allocation would conflate topology with local storage.
Benefits
Same logical cells and edits expose correctness independently of representation. A bounded experiment can reject a layout before adopting a public container API.
Costs
Prototype algorithms include linear palette lookup and sorted page insertion. No claim is made that each alternative is optimized. Encoding estimates omit shared address/version/digest metadata, compression and journaling.
Risks
Owned capacity is not RSS or allocator peak; transient reallocation, allocator headers, fixture inputs and future halos/journals/caches are excluded. A tiled-volume estimate is not a generated world. One workstation cannot establish server capacity.
Consequences
Raw measurements and the report are archived. Keep production implementation for M5.3/M5.4. Comparisons run in CTest without timing gates and under sanitizers. No coordinate API default or existing persisted simulation version is changed.