Files
aevolution/docs/engineering/CHUNK_LAYOUT_EVALUATION.md
T

5.8 KiB

M5.2 chunk layout evaluation

Measured 2026-09-26 on Windows x64, AMD Ryzen 7 9800X3D (8 cores/16 logical), MSVC 19.44 Release, CMake 3.31.6/Ninja 1.12.1. Decision: ADR-0043. Raw evidence: 180 samples.

Method and correctness

Build Release with tools/windows-check.ps1 -Preset release -Action check, then run build/release/evo-chunk-layout.exe to stdout (JSONL). Portable equivalent: configure and build the release preset, then ./build/release/evo-chunk-layout. evo-chunk-layout --verify is registered in CTest with a 120-second limit.

Four edges (8,16,32,64), five fixtures, three layouts, one discarded warmup then three fresh measured samples each. Fixed order dense/palette/pages4; medians below are observations, not performance gates. No pinning or statistical confidence claim. Fixture generation and correctness checks are outside measured sections. Edits use seed 123456 and 4096 alternating void/rock writes at seeded indexes; byte accounting is included in edit timing. Scans include a logical hash accumulation. Construction includes conversion from an existing dense source, not procedural generation.

Uniform is full rock; sparse has three isolated void cells; mixed cycles eight full materials; excavated cuts an XY tunnel and a Z plane; entropy varies material/fill beyond 256 keys. Every initial and edited cell is compared with an independent dense oracle. All samples/layouts have matching initial and edited hashes per fixture/edge. Release-active checks cover bounds, exactly 256 keys then dense promotion at 257, page removal and edit/revert equality across all edges. These tests validate storage, not terrain mass transfer authorization. No simulation golden or format changes.

Owned memory and measured costs

Bytes include C++ object and vector capacity, including indexes and unused capacity. Peak is sampled after construction and each edit; it misses constructor transitions and simultaneous old/new allocations during reallocation. It is not RSS. Allocator headers, source/oracle arrays, edit lists, future directory/halo/cache/journal costs are excluded explicitly. Pages retain capacity after erasure; palettes retain obsolete keys and never recompress after edits. Thus logical restoration does not imply memory restoration. Future production allocation must be budgeted separately.

At edge 16 (times are median microseconds):

Fixture Layout Initial B Sampled peak B Encoded estimate B Build us Scan us 4096 edits us
uniform dense 16408 16408 16385 3.9 3.2 1.6
uniform palette 84 4184 5 11.0 3.2 12.8
uniform pages4 32 24472 9 16.5 16.5 112.0
sparse dense 16408 16408 16385 3.7 3.2 1.6
sparse palette 4184 4184 4107 13.0 3.1 10.5
sparse pages4 812 24472 789 19.8 16.7 96.7
mixed dense 16408 16408 16385 3.8 3.1 1.6
mixed palette 4212 4212 4131 13.4 3.2 10.6
mixed pages4 24472 24472 16649 45.4 22.0 95.1
excavated dense 16408 16408 16385 4.2 3.1 1.6
excavated palette 4184 4184 4107 13.6 3.1 10.4
excavated pages4 7312 24472 7289 24.7 18.8 103.5
entropy dense 16408 16408 16385 4.1 3.1 1.6
entropy palette 16464 16464 16385 13.8 5.1 4.9
entropy pages4 24472 24472 16649 32.7 21.2 90.9

Palette edge comparison, mixed fixture. Tiled bytes estimate a 128-cube using repeated identical fixtures, not an actual generated volume. No chunk directory is included.

Edge Dense payload B Owned B Tiled 128-cube B Build us Scan us
8 2048 628 2572288 2.3 0.4
16 16384 4212 2156544 13.4 3.2
32 131072 32884 2104576 82.3 25.2
64 1048576 262260 2098080 668.7 203.7

Encoding estimates are layout body proposals only: dense 1+4*N^3; uniform 5; palette 3+4*K+N^3 (tag/count plus retained keys and byte indexes); pages 9+260*P (tag/base/page count plus keys and 64 cells). These are not serialized files; headers, addressing, versions, checksums, canonical palette normalization and compression await M5.6. No native structs will be dumped to disk.

Scoped choice and limits

Select 16-cube uniform/palette/dense geometry for the bounded M5 implementation. It reduces the mixed fixture to roughly one quarter of dense memory while keeping scan cost comparable on this host. Dense remains faster to construct/edit; that tradeoff is acceptable for the initial bounded terrain proof, not a throughput SLA. Sparse pages win for three isolated holes at larger sizes but lose on mixed geometry and scattered edit throughput. They remain a candidate for M6 optional fields only.

Edge 8 multiplies directory entries eightfold versus 16 for the same volume; edge 32 reduces metadata but expands worst-case dense edit/load unit eightfold to 128 KiB; 64 reaches 1 MiB. Edge 16 is a conservative bounded choice, not a measured global optimum: 4096 cells, 16 KiB dense payload, 4 KiB byte indexes, at most 256 retained 32-bit palette keys. Budget up to 21 KiB simultaneous logical buffers when promoting (16+4+1 KiB), plus object/allocator overhead; use bounded capacity allocation in the production implementation, not unspecified vector growth. Allocation rejection and total resident chunk/dirty-state budgets are M5.4 requirements. The prototype measures standard vector capacity and does not enforce a process memory ceiling.

No final planet/LOD/chemistry/mesher choice follows. ADR-0042's explicit coordinate edge candidates remain valid. M5.3 introduces versioned abiotic generation; M5.4 implements owned storage under the selected policy. Repeat measurements on Linux and the R730xd before adopting production capacity or latency limits.