research: Astra low review of stamping tunnels along the curve (read-only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016dhxM43dnWvUu2B5Ph1iG1
2026-10-30 13:25:28 +01:00
1 parent 707bc61553
commit 103fa75e1c
@@ -0,0 +1,60 @@
 # VoxelForge — read-only design review: stamp tunnels along the curve instead of searching the curve per sample
 You are reviewing a design idea against real code. **Do not edit, create or delete any file, and do not build or run
 anything.** Read code and reason. Be thorough; mark each claim as [CODE] (with file:line), [MEASURED] (from a report),
 or [INFERENCE].
 ## Context
 VoxelForge Core (`Standalone/Core`) generates a density field: negative = solid, positive = air, 25 cm voxels, 32³ tiles,
 LOD0–8 clipmap, marching cubes. Same seed must give the same world on every machine and worker count; byte-identity with
 older versions is NOT required.
 Inter-strate tunnels ("passages") on branch `wip/l111-halfpipe-spline` (HEAD `707bc61`) are a smooth spline swept tube:
 - a D-shaped walkable floor with a continuous floor height h(s), max grade 15°;
 - a rounded crest;
 - an open-air half-pipe where there is no rock;
 - a thin solid shell ("plain shell rule": interior always air, a thin shell always solid);
 - smooth-min where tunnels meet;
 - mouths that ramp into the ground.
 Key code: `Standalone/Core/src/ShapeWorldInternal.h` (`FScopedPassageTileQueries`, `prepareSweptTubeBase`, around
 lines 374 and 11436), `Standalone/Core/src/VoxelForgeCore.cpp:~2747`. Reports: `Standalone/Research/WorldAssemblerM3/Linux109`
 … `Linux119` (REPORT.md each).
 Cost today [MEASURED, L117–L119]: the smooth tunnel is 13–22% slower than the coarse L109 tunnel at LOD0–2 readiness.
 About 95% of the extra cost is in passage-feature tiles. The causes: sweep pairs (sample × curve segment), exact
 fallbacks that re-scan segments for off-grid queries, segment visits, per-tile prepare, and smooth-min.
 ## The idea to review (owner + orchestrator)
 Today each sample "pulls": it searches for the nearest curve segment and computes a distance. Proposed: "push"/stamp.
 For each tile, walk the curve in rings (frames: position, forward, up, as with an Unreal spline mesh) and write the
 tube's signed distance into only the lattice samples near each ring. Only a narrow band of about one voxel around the
 wall needs an exact value; deep rock only needs "rock" and the tunnel interior only needs "air". Off-grid queries
 (normals/gradients at seams, gameplay point queries) would read the stamped lattice, interpolating, instead of
 re-searching the curve. Also: accept curve accuracy at one voxel (25 cm) rather than 2.5–10 cm, and build the curve
 frames once per route rather than per tile.
 ## Questions
 1. Is the cost model right? From the code, what does a passage-feature tile do per sample today, and what would stamping
   replace? Estimate the work ratio (samples touched × ops) for a typical LOD0 tile and for LOD1–2.
 2. What breaks or gets harder, concretely in this code?
   - box verdicts/tile skipping (`ClassifyTile`-style proofs that a tile is all solid/air);
   - seams between tiles: both neighbours must stamp identical values at shared samples, deterministically;
   - LOD levels (coarser lattices);
   - off-grid `DensityAtUnclamped` queries and gradients;
   - min/smooth-min with the rest of the field and with other tunnels;
   - the floor h(s), half-pipe, shell, mouths;
   - walk audits;
   - thread safety.
 3. Is "write into the lattice" compatible with how density is evaluated (lattice fill vs point evaluation)? If the
   pipeline is pull-only, what is the smallest change that gets the push benefit? For example, a per-tile sparse
   band list built by walking rings, then lookups during fill.
 4. Is there a simpler or cheaper alternative we're missing? For example, an analytic local frame per sample from the
   spline parameter, or a coarse per-tile segment window that is already almost free.
 5. Recommendation: the design you would build, in steps, with the evidence bar (what measurement would prove or kill
   it). Keep it short.
 Write your answer as plain Markdown, at most ~1,200 words.
@@ -0,0 +1,53 @@
 [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.