61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# 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](../engineering/CHUNK_LAYOUT_EVALUATION.md).
|
|
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.
|