# Linux20 — design research for metre-based strata and generation layers

**Date:** 2026-10-20  
**Scope:** read current owner/Core code and L19 evidence; measure unit conversions and LOD ring
errors; write the L20 design only.

## Findings

- `CHUNK_SIZE` is 32 and legacy `VOXEL_SIZE` is 12.5 cm, so the owner chunk is 4 m
  (`Source/VoxelForge/Public/VoxelTypes.h`). Core defaults to 25 cm and keeps 32 voxels per tile.
- `BuildSurfaceStratumPlan` computes SurfaceWorld layout from `Slot.*ChunkZ × CHUNK_SIZE` in Core
  voxel units. This is 32 × 25 cm = **8 m per slot chunk**. L18 records this as the retained
  SurfaceWorld `topChunkZ × 32` interpretation.
- `BuildFloatingIslandStratumPlan` serializes owner/Core voxel size and the reduced ratio. At the
  default 12.5/25 cm ratio, its slot chunk is 32 × 0.5 = 16 Core voxels = **4 m**. Core reverses
  sample Z using `GetCoreVoxelsPerOwnerChunk` in `ShapeWorldInternal.h`.
- This factor-of-two difference is real, but it is not enough to claim that it caused the L19 ring
  heights. L19's ring evidence points to LOD-dependent extraction of the lower SurfaceWorld field.
  It does mean there is no single metres-per-chunk conversion that both preserves the current native
  bounds and makes their shared slot indices one physical interface. The design records the current
  resolved bounds and treats a later interface unification as an explicit change.
- The L19 FloatingIslands-camera table reports LOD1→2 median / p95 / max = 147.141 / 148.403 /
  149.862 cm, zero no-hit samples; LOD2→3 = 128.603 / 200.789 / 773.318 cm, with 8 no-hit samples
  among 308. LOD1/2/3 step sizes at 25 cm are 0.5/1/2 m. The ring audit excludes skirts and masked
  triangles. Native far-ground refinement starts at LOD4, so it cannot fix those two transitions.
- The exact location and current geometry evidence are from `Linux19/REPORT.md`: lower SurfaceWorld
  terrain at approximately −60…−73 m; its terrain triangles remain visible below FloatingIslands.
  The worst sampled LOD1→2 roots are −60.497 m and −61.996 m. The LOD2→3 pair is −73.080 m and
  −65.347 m.

## Layer map

The owner-facing layout is composed by `VoxelStrateComposer.cpp`, stored/loaded by
`VoxelSeasonManifest.cpp`, and resolved into `FStrateSlot`s by `VoxelStrateManager.cpp`. The Core
snapshot adapter (`VoxelForgeCoreAdapter.cpp`) builds separate SurfaceWorld and FloatingIslands
plans. Core streams work from `VoxelForgeCore.cpp` and evaluates native fields in
`WorldAssemblerInternal.h` / `FloatingIslandsInternal.h`; legacy `UVoxelGenerator::GetDensityAt`
and operator-stack/cave paths remain in `VoxelGenerator.cpp`, `VoxelDensityOpStack.cpp`, and
`VoxelCaveMorphology.cpp`.

Shared pieces already include Core's FP-contract preamble, fixed-point field code, feature bounds,
column caches, and interval proofs. `ShapeWorldInternal.h` still chooses among native fields, manager
state, and the copied legacy evaluator. `World::generateTile` in `VoxelForgeCore.cpp` owns MC setup,
recipe feature branches, native SurfaceWorld far-ground/cap refinement, and recipe identity salts.
`FarShellsInternal.h` adds shared boundary ceilings and GPU far-shell repairs; its connector repair
input is prepared from FloatingIslands geometry in `ShapeWorldInternal.h`.

The complete mapping, boundary proposal, ranked violations, generator contract, and migration plan
are in [`DESIGN_STRATA_UNITS_AND_LAYERS.md`](../../../DESIGN_STRATA_UNITS_AND_LAYERS.md).

## Direction review

The proposed metre authoring, 25 cm per-strate default, fixed 32³ internal tiles, and separation of
director/generators/shared composition/mesher are sound. Two qualifications are recorded in the
design:

1. “Units cost nothing” is true for metre conversion itself. Voxel size affects the physical width
   of 32³ tiles and the number of tiles/tasks/caches; halving spacing in XYZ implies about 8× the
   density samples per physical volume, with more per-tile overhead on top.
2. A no-movement migration cannot use one global chunk-to-metre multiplier. Current Core paths use
   8 m per SurfaceWorld slot chunk and 4 m per FloatingIslands slot chunk at defaults. Preserve and
   report those current resolved bounds first; decide separately whether to leave any gap/overlap or
   intentionally make the new metre-authored interface contiguous.

The L19 density/mesh evidence supports LOD extraction as the direct cause of the measured lower-ground
ring steps. A shared explicit ceiling surface is the right approach for seals/caps, but not sufficient
for those upward-facing ground ledges. Step 5 therefore exposes the SurfaceWorld ground profile to a
generic explicit-surface/transition contract and remains subject to the protected LOD2 approval.

## Output and worktree status

No source, manifest, generator, mesher, or build input was changed. No build or world run was made.
Thus no new W12 hash claim is needed for this documentation-only round. The L19 reference hashes
remain the expected equality gates for later source changes:

- SurfaceWorld whole view: `c10697a8f48380c7 / 4197fc1072f0ff58 / 7b3e616ec9459851 / c879e35592bf33e5`
- FloatingIslands whole view: `00bc3607a7839854 / 4baa66127c2b0892 / e11ef05e851a1517 / 1278bc4b1fffb869`

The pre-existing untracked `Standalone/Research/WorldAssemblerM3/Linux18/exports/` directory was
left untouched. No commit, push, or stash was made.