VoxelForge/Standalone/Research/WorldAssemblerM3/Astra2/REVIEW.md

[INFERENCE] Build a tighter passage cache first. Ring stamping is promising, but the code already pushes segment contributions into a tile lattice. The main opportunity is reducing coverage, overlap, and off-grid fallback work—not reversing a purely pull-based architecture.

References below: H = Standalone/Core/src/ShapeWorldInternal.h; C = Standalone/Core/src/VoxelForgeCore.cpp; M = Standalone/Source/VoxelForge/Private/VoxelMarchingCubesMesher.cpp. Report references mean Standalone/Research/WorldAssemblerM3/LinuxNNN/REPORT.md.

1. Cost model

[CODE] prepareSweptTubeBase allocates per-passage (cells+3)³ sample records, including a one-step halo. It walks candidate bounding boxes, lattice samples, then fine segments; individual segment bounds reject some pairs. Accepted pairs compute projection, deterministic square root, radius, floor profile, and potentially shell distance. A final pass flattens the selected tube and caches relief (H:11436, H:11489, H:11521, H:11659).

[CODE] During density evaluation, aligned samples retrieve that cache, then still perform relief weighting, floor shaping, mouth fades, shell composition, and host-field composition. Misses invoke two hierarchy searches: nearest body/floor and nearby shells—not necessarily a linear whole-route scan (H:1247, H:1346, H:1427, H:1435).

[MEASURED] L119 reports 29.40M preparation pairs and 24.46M segment visits across its four LOD0–2 profiles. Preparation fell 59.8% versus L118, while fallbacks increased 55–58%. L117 attributes about 95% of the tile-worker regression to passage-feature tiles. Thus the diagnosis is sound, but those counters do not establish equivalent costs per operation.

[INFERENCE] For an illustrative straight crossing, assume exposed surface perimeter (P=16) m, tile crossing length (L=32\Delta), and exact band ±one lattice step. Unique band samples are approximately (2PL/\Delta^2):

[INFERENCE] Normal tile	LOD0	LOD1	LOD2
Spacing Δ	0.25 m	0.5 m	1 m
Band samples	4,096	2,048	1,024
Fraction of 35³ prepared grid	9.6%	4.8%	2.4%

[INFERENCE] These are geometric estimates, not measured “typical tiles”; clipping, floor/outer-shell surfaces, bends, and crossings change them. If today fraction (f) of the grid receives (k) segment evaluations, and stamping averages (m) contributions per band sample, the expensive-work ratio is approximately (table fraction × m)/(f × k), multiplied by relative operation cost. For f=0.5, k=2, m=2, that is 19%, 9.6%, 4.8%. Allocation, classification, host evaluation, and composition remain. Dense rings can make (m) large and erase this advantage.

2. Concrete difficulties

• [CODE] Skipping: passage-bound overlap currently vetoes a uniform proof and returns Mixed (H:5684). [INFERENCE] Retain conservative bounds, expanded for approximation and reconstruction support. “No band samples written” proves neither solid nor air: a thin shell can lie between samples.

• [CODE] Seams: cache coordinates derive from integer world coordinates; nearest ties use segment index (H:11448, H:11564, H:11640). [INFERENCE] Generate rings from route-global parameters, never tile-local stepping. Include every contributor affecting shared samples and halos; use stable ordering and arithmetic. Independently clipping ring generation at tile boundaries risks disagreement.

• [INFERENCE] LOD: distinguish 25 cm curve error from lattice spacing. A fixed 25 cm band is insufficient around 1 m cells; cover interpolation corners and gradient support. A 0.75 m shell can disappear at coarse resolution. Independently reconstructed LOD fields also disagree off-grid; define one canonical point-query field.

• [CODE] Off-grid: sweptSample rejects non-lattice coordinates; public point queries call DensityAtUnclamped without requiring a tile cache (H:11721; C:1875). Gradients normally use density-grid values, with unclamped fallback (M:1972). [INFERENCE] Interpolation needs all eight valid corners, including outside loaded tiles. It changes gradients and zero crossings; interpolating only passage channels also differs from interpolating the fully composed field.

• [CODE] Composition: passage bodies and shells use separate hard minima; final composition includes host/native-floor exceptions (H:1496–1519). The floor corner uses smooth-max, implemented through smooth-min (H:3493, H:6940). [INFERENCE] Do not assume the measured smooth-min cost is tunnel-to-tunnel joining. Preserve separate void/shell channels and composition order. Arbitrary “rock/air” magnitudes can move interpolated crossings and smooth blends.

• [CODE] Shape: floor selection is independent of minimum round distance; the code explicitly warns that minimizing flattened segment distances makes downhill floors jump (H:1328). Floor evaluation uses horizontal projection, authored h(s), and XY mouth blending (H:3448). Shells have rounded crests and five-metre mouth fades (H:1461, H:3503). [INFERENCE] A conventional spline-normal D-section changes this geometry. Stamped isolated rings can scallop; rasterize bounded slabs between frames while preserving gravity-relative floors, shell unions, and interior priority.

• [MEASURED] Walkability: L119’s maximum sampled floor-root offset was 7.884 mm; L113 documented voxel-aligned floor ribs. [INFERENCE] A 25 cm curve tolerance does not authorize 25 cm floor error or guarantee ≤15° grade. Audit reconstructed density and meshes, including mouths, overlaps, support, and headroom—not only planner h(s).

• [CODE] Threads: copied worker scopes share prepared data through a shared pointer; active scope is thread-local (H:353, H:11411; C:2854). [INFERENCE] Finish stamping before publication. Parallel ring writes require deterministic reductions; mutable shared lazy caches introduce synchronization and lifetime problems.

3. Smallest useful change

[CODE] Preparation already precedes GenerateMesh, whose fill calls lattice evaluators (C:2747, C:2892; M:1488). Route segments are already prepared globally with 10 cm chord tolerance and an 8 m spacing cap (H:4601).

[INFERENCE] Replace preparation’s broad pair enumeration with conservative slab-to-grid spans or small spatial bins. Keep indexed lookups during pull-based fill. Store body/floor ownership and shell contributions separately; use explicit outside/interior/band states. A dense index plus compact records may beat a sparse hash map. Additional frames can be route-global, but this does not eliminate existing per-tile rasterization.

4. Alternatives and recommendation

[MEASURED] L115 already reduced coarse candidates 74.1% without reducing fine pairs. L118’s restriction of fallbacks to prepared spans changed output; L116’s 20.8% pair reduction did not recover readiness.

[INFERENCE] An analytic local frame still needs a parameter lookup, especially near folds. Prefer globally indexed conservative segment bins, shared by preparation and exact point queries.

[INFERENCE] Build in three steps: instrument unique samples, overlap, misses by caller, memory, and per-LOD time; implement tighter bins/slabs while preserving geometry; then separately trial 25 cm curve tolerance and canonical interpolation. Accept only reproducible near-readiness gains against L119/L109 plus unchanged walk/seam requirements and cross-compiler/worker determinism. Kill the approach if saved distance work becomes rasterization, memory, or reconstruction cost.