VoxelForge/Standalone/Research/WorldAssemblerM3/Linux5/REPORT.md

# World Assembler M3 — Linux L5

**Result:** no octave tail is safely removable under the declared bounds. The exact far meshes already exceed the 1 px field-error and LOD-swap budgets, and the cutoff flag is 2.2% slower in the W12 view. The candidate therefore generated the exact same meshes; recipe version stays 1.

## Build and machine

Built `VoxelForgeCoreHeadless-linux5-l5-final7` and its capture target on `assembler/world` at `7770074` with Clang 19 `-ffp-contract=off`, then GCC 14 default contraction, both with 12 jobs. W1/W12 hashes match across both compilers; the L3 FP-contract preamble and runtime self-test remain active. Runs used CPUs 0–11, normal priority, and the 6 GiB process limit. Maximum process HWM was 898,692 KiB (GCC compile); the largest runtime process was 454,828 KiB. CPU governor stayed `powersave`. `/dev/dri/renderD128` was absent, so EGL used Mesa llvmpipe with `LP_NUM_THREADS=12`. No packages or system settings were changed.

## Capture and gate

`LinuxOffscreenCapture.cpp` reads the `.vfmesh` export from the headless streaming pipeline, creates a surfaceless EGL/GLES3 pbuffer, and writes 2560×1440 PNGs with libpng. `ffmpeg` made 1280×720 review JPEGs; the largest is 73,923 bytes. The shader combines surface normals and 80 m height bands. Only the small JPEGs were opened for review.

The gate samples a 65×65 XY grid on the closest native-surface tile at each LOD, excluding skirts. It reports two comparisons: displayed mesh against exact `Heightfield2D` ground/cap roots, and against a regenerated exact same-LOD mesh. The second is the zero-delta regression control; the first measures the actual field error. Swap error compares the coarse tile with its fine children at those same field roots. Full missing-surface, 2 m floating-surface, and missing fine-ring injections were rejected at every LOD3–8; so were both S13 controls.

This is a sampled heightfield gate, not a full camera-ray rasterizer. It can miss cracks narrower than one grid cell (1 m at LOD3, growing to 32 m at LOD8), and its direct-field row does not model tunnel walls or other non-heightfield faces. The same-LOD mesh comparison covers extra and missing mesh intersections at sampled points; a denser or full-screen geometry pass would be needed to certify sub-cell cracks and non-heightfield surfaces.

## Closest display distances and budgets

The code sweeps clipmap desired sets across X-boundary phases and measures tile AABB distance. The result matches the clipmap ring formula `3 × 32 chunks × 2^(LOD−1) × 0.25 m`; LOD0 is the player tile. The pixel angle is `90° / 2560 = 0.000613592 rad`.

| LOD | Closest display distance | 1 px at that distance | Active rule |
|---:|---:|---:|---:|
| 0 | 0 m | 0 cm | exact, 2 cm |
| 1 | 24.001 m | 1.473 cm | exact, 2 cm |
| 2 | 48.001 m | 2.945 cm | exact, 2 cm |
| 3 | 96.001 m | 5.891 cm | 1 px |
| 4 | 192.001 m | 11.781 cm | 1 px |
| 5 | 384.001 m | 23.562 cm | 1 px |
| 6 | 768.001 m | 47.124 cm | 1 px |
| 7 | 1,536.001 m | 94.248 cm | 1 px |
| 8 | 3,072.001 m | 188.496 cm | 1 px |

## Exact-field error and swap pop

Baseline and cutoff values are identical. The exact same-LOD regression control is 0.0000 px p50/p99/max at all LOD3–8, with no missing or floating samples. Against the continuous `Heightfield2D` roots, however, the current exact meshes already exceed 1 px at every LOD. The owner’s expected near-zero control holds for exact-versus-exact mesh output, not for the true-field comparison.

| LOD | Exact field p50 / p99 / max px (baseline → cutoff) | Swap p50 / p99 / max px | Swap cracks / floating |
|---:|---:|---:|---:|
| 3 → 2 | 0.9035 / 4.5839 / 7.3277 → same | 0.6714 / 4.1861 / 7.3277 | 0 / 0 |
| 4 → 3 | 1.1170 / 5.6056 / 8.3307 → same | 0.8269 / 5.1958 / 8.2105 | 0 / 0 |
| 5 → 4 | 1.5667 / 45.3010 / 126.2667 → same | 0.0000 / 20.7227 / 63.2266 | 0 / 0 |
| 6 → 5 | 0.5870 / 21.2445 / 82.3615 → same | 0.0000 / 21.2445 / 82.3615 | 0 / 0 |
| 7 → 6 | 0.3393 / 16.4341 / 47.9760 → same | 0.0000 / 16.4341 / 47.9760 | 0 / 0 |
| 8 → 7 | 0.9616 / 24.9479 / 50.0934 → same | 0.9616 / 24.9479 / 50.0934 | 0 / 0 |

The baseline gate rejects on the field row and every swap row. The cutoff run returns the same rejection. Fault injections also rejected: missing-surface samples were 4,225–13,642; floating-surface samples 4,225–13,641; missing fine-ring cracks 4,225–8,450.

| LOD | S13 octave-drop p99 / max px | Stride-2 column interpolation p99 / max px |
|---:|---:|---:|
| 3 | 960.2333 / 998.8654 | 9.3917 / 13.9093 |
| 4 | 3.7405 / 5.1103 | 9.2115 / 15.3435 |
| 5 | 105.7114 / 129.3089 | 125.1435 / 191.6424 |
| 6 | 218.7777 / 749.9535 | 82.1098 / 148.9485 |
| 7 | 95.1867 / 129.1796 | 40.6881 / 80.6012 |
| 8 | 38.1461 / 282.3288 | 28.8473 / 278.6236 |

Both controls were rejected at every LOD3–8. The octave-drop case produced missing samples at LOD3, 5–8 and floating samples at LOD5–8; stride-2 interpolation produced missing/floating samples at LOD5, 7 and 8.

## Cutoff contract and detail cost

The version-2 shared visual-detail contract declares stable octave terms with wavelength, octave count, displacement bound, and noise bound. A suffix is eligible only when its wavelengths are undersampled and its full displacement bound fits within one sixty-fourth of the tile’s pixel budget. Skipped zero-mean terms retain the original normalization denominator. Recipes with no terms keep the exact path; `FloatingIslandFieldV1` declares none, and its baseline/cutoff LOD hashes match. This is separate from content recipe version 1, which stays unchanged because output did not change.

SurfaceWorld declares 17 terms per LOD. No term or octave tail qualifies at LOD3–8. Sample steps are 16, 32, 64, 128, 256, and 512 voxels respectively. The bounds explain the result: even the smallest declared maximum displacement is 256 voxels, against a 0.2356-voxel 1 px budget at LOD3. The cutoff skips zero octaves, so eligible octave time is 0 ms.

| Octave | Terms | Wavelength range (voxels) | Max displacement range (voxels) |
|---:|---:|---:|---:|
| 0 | 17 | 25–10,000 | 1,024–640,000 |
| 1 | 17 | 12.5–5,000 | 512–320,000 |
| 2 | 15 | 6.25–1,250 | 256–160,000 |
| 3 | 4 | 41.664–250 | 3,968–24,800 |

W12 profile from the exact baseline; octave milliseconds are summed across evaluated calls/workers. They are all measured detail work, not removable work under the bound above.

| LOD | Worker sum s | Octave 0 ms | Octave 1 ms | Octave 2 ms | Octave 3 ms | Detail total ms (% worker sum) | Eligible ms |
|---:|---:|---:|---:|---:|---:|---:|---:|
| 3 | 1.660 | 71.585 | 69.911 | 68.535 | 15.407 | 225.437 (13.58%) | 0 |
| 4 | 3.321 | 135.512 | 131.224 | 128.645 | 26.506 | 421.887 (12.70%) | 0 |
| 5 | 2.283 | 82.131 | 80.450 | 77.545 | 16.262 | 256.388 (11.23%) | 0 |
| 6 | 3.587 | 153.409 | 148.854 | 144.175 | 29.984 | 476.422 (13.28%) | 0 |
| 7 | 1.447 | 35.301 | 34.493 | 33.138 | 7.069 | 110.001 (7.60%) | 0 |
| 8 | 2.685 | 58.763 | 57.751 | 56.277 | 11.848 | 184.638 (6.88%) | 0 |

The cutoff is recipe-generic, display-mesh-only, and activated only for LOD3+. Exact density, detail, collision, edit, and walkability paths remain outside it. LOD0–2 keep the 2 cm path. ARCHITECTURE §8.10 invariants remain: lazy thread-local caches, two-pass MC, SSE noise, and clipmap streaming. The cutoff state is scoped to mesh generation under the async-safety rules.

## W12 speed, interleaved with L4

Three L4/candidate pairs, all W12, measured on the L1 camera. The candidate is the final build with `--visual-detail-cutoff`.

| Measure (median) | L4 binary | Candidate | Change |
|---|---:|---:|---:|
| Whole-view ready | 2.183 s | 2.232 s | +2.2% |
| Stream wall | 1.895 s | 1.963 s | +3.6% |
| Far worker sum, LOD3–8 | 12.247 s | 12.458 s | +1.7% |

| LOD | L4 worker sum s | Candidate worker sum s |
|---:|---:|---:|
| 0 | 3.799 | 4.094 |
| 1 | 5.304 | 5.573 |
| 2 | 1.281 | 1.340 |
| 3 | 1.102 | 1.138 |
| 4 | 2.723 | 2.719 |
| 5 | 1.898 | 1.976 |
| 6 | 2.875 | 2.944 |
| 7 | 1.243 | 1.282 |
| 8 | 2.355 | 2.400 |

There is no speed benefit because nothing qualifies for skipping; the small regression is cutoff setup and bookkeeping.

## Hashes and captures

Baseline and cutoff hashes match for all LOD0–8. The old L4 binary’s aggregate hashes also match: whole view `c10697a8f48380c7 / e75c9119a1498cd5 / 49a9a8d1835a6c8c / edcb23288b5e8724` and full detail `0ee0579bd15cbbe4 / 32e5d4964d610fee / 1932b96ee4b1d910 / 69743c6bad3447dc`. The recipe stays version 1 because output did not change.

| LOD | Density | Mesh | Payload | Topology |
|---:|---|---|---|---|
| 0 | 769f2a706d585a72 | 33eeeb39fa443816 | 645621a1d968983f | c2457ed905036c9d |
| 1 | 69cc5a5c0a2c60af | b48335f5410c57d5 | d15c5480162ab8ba | feca1bd025823604 |
| 2 | 85deed5683a77202 | 53469895987aeea2 | e55f8ae7e1532033 | d5feb12a0e85c09b |
| 3 | 6518caefb3be7e7f | ec513c90b853a614 | f62fa1137ff17f82 | ccf1dcf681965816 |
| 4 | 62d4be96021992f4 | f1e4c6efcc2615a9 | 9dc5f9c88be02f33 | fe6f55125a07c3bf |
| 5 | 5e4a8c38b8cea6fc | 08ee56998aaf21e5 | 541eea8558f26cc8 | 6539374a8b3336d8 |
| 6 | e036e95b9006945b | 624a33f941a99b02 | 81b73e14f68bdf86 | 4de4c63ce1f80a56 |
| 7 | 8ee358af56a30d8d | 46ab3c6184048b7c | 0a6164b7e68e80c5 | 0c26b85bb03bc831 |
| 8 | c3458e1cbdb9c471 | 46c03d0994d75192 | 8f89fc5bde12d230 | d16dc0cf62031898 |

Nine direct-Core query probes also match baseline/cutoff and W1/W12 Clang/GCC: density and unclamped `e4d4a8eb95b35933`, detail `efcba20c0c70c415`, collision `e604823a249029bf`.

| Before / after pair | View |
|---|---|
| `before_l1.jpg` / `after_l1.jpg` | Exact L1 camera `0,-35,-487.94,0,-22` |
| `before_horizon.jpg` / `after_horizon.jpg` | Same position, pitch −2° |
| `before_boundary_lod2_3.jpg` / `after_boundary_lod2_3.jpg` | 20 m above local heightfield, aimed at the 96 m LOD3 entry band |

The boundary camera is `0,-35,-480.77246,0,-12`; the local heightfield is at −500.77246 m, placing the ground intersection about 96 m away.

The six review JPEGs are byte-identical within each pair. PNGs are in `Saved/Linux/captures/`; JPEGs are in `Linux5/captures/`.

## Failed and retried runs

- The first headless invocation omitted required streaming flags; the next used the default binary-relative data path and could not open the owner JSON. Both were retried with all flags and the explicit `Standalone/data/owner_world.json` path.
- The first process-monitor wrapper errored after its Clang build had completed; the run was repeated with `MeasureProcess.py` to record process HWM and duration.
- The first capture named a nonexistent mesh path and exited 2; the exported `.vfmesh` path was corrected.
- The first gate build failed on a duplicate `Distances` local; the corrected build passed. A first stride-2 control changed the MC lattice instead of reproducing S13’s every-second-column interpolation; the final control uses bilinear column interpolation.
- Initial comparison against only the continuous field mixed surface interpolation with unrelated tunnel intersections. The final instrument reports exact heightfield roots separately from the exact-mesh regression and ring checks.
- Early W12 cutoff candidates took 2.70–2.91 s. The zero-eligible path and distance setup were moved off the expensive profiling/phase-sweep path; the final interleaved candidate median is 2.232 s. It still does not improve L4.
- One final GCC W12 command omitted `--stream-pipeline` and exited 2; the corrected rerun passed. The initial −50° boundary capture mostly showed near ground; the final pair uses the camera listed above.
- The final baseline and cutoff gate commands exit 6 by design: both correctly reject the exact-field error and swap pops. No process exceeded 30 minutes or stalled for 15 minutes.

Core/API changes are in `VoxelForgeCore.h`, `WorldAssemblerInternal.h`, `FloatingIslandsInternal.h`, and `VoxelForgeCore.cpp`. Standalone changes are in `StreamingWorld.h`, `StreamBenchmarkPipeline.h`, `StreamBenchmarkHeadless.cpp`, `LinuxScreenSpaceGate.h`, `LinuxOffscreenCapture.cpp`, and `BuildLinux.sh`; process measurements are in `MeasureProcess.py`.

**For the owner:** Far terrain will look exactly as it does now because no octave tail met the bound. Existing far LOD swaps exceed the 1 px target, so the mesh sampling and transition error need attention before octave skipping can be used.

## Orchestrator review (Claude)

- **Not merged into `assembler/world`:** kept on side branch `wip/l5-far-cutoff`. With the cutoff flag OFF,
  the L5 build is slower than L4. My interleaved W12 runs: L4 2.054/2.097/2.179 s vs L5 `final7`
  2.127/2.193/2.208 s (medians 2.097 → 2.193, +4.6%), same world. Cost and no benefit.
- **Instrument caveat:** the gate prints `metric=vertical_height_error`. On steep slopes and cliffs, a
  small horizontal offset becomes a large vertical error, so vertical error overstates screen
  displacement. p50 is ~1 px but p99/max reach 20–126 px, the pattern such an artifact produces. The
  claims "today's far meshes exceed 1 px" and "LOD swaps pop by up to 126 px" are therefore NOT yet
  established. They need a screen-space measure: error along the surface normal or along camera rays,
  projected at the display distance.
- The cutoff criterion (full displacement supremum ≤ 1/64 px) cannot pass for any SurfaceWorld octave
  (smallest bound 256 voxels vs 0.24), so the null result was decided by the criterion, not measured.
- The capture path (EGL/GLES pbuffer; llvmpipe, since the sandbox hides `/dev/dri`) works and is worth keeping.