wip(assembler): round L37 -- FI mouth carve-fade fix, no raised bridge (style 0); research R1

The passage mouth fade multiplied the signed carve distance by zero, which turned native rock into an
open surface (the reason earlier rounds stamped walk pads at mouths); it now blends between the
uncarved field and the full signed carve. The FI style-0 route followed a lifted grade envelope over
the crater (the "bridge"); it now runs on the rim and follows the native surface. New built-shape and
crease audits with thresholds frozen before the fix (L36 and box controls fail). 24/24 passage rows,
30/30 determinism, 16/16 invariants, 18/18 interface/ring. Unreal: one recipe setter (uncompiled).
Research R1 (read-only, web): ranked proposals for natural walkable mouths, floor-limited carve first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016dhxM43dnWvUu2B5Ph1iG1

Standalone/Research/WorldAssemblerM3/Research1/REPORT.md

@@ -0,0 +1,31 @@
+# Research R1 — natural, walkable cave mouths and tunnels
+
+## What the references show
+
+- **Deep Rock Galactic** separates room/exit structure from biome noise and debris; designers test generated variants for traversal and wayfinding. **Minecraft 1.18** distinguishes caverns from spaghetti and noodle tunnels, and its noise caves form entrances where they intersect the surface. These support a planned route plus a terrain-native mouth, not a portal stamp. [Ghost Ship’s cave-generation post](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1729500950&feed=steam_community_announcements), [Mojang 1.18 notes](https://www.minecraft.net/de-de/article/caves---cliffs--part-ii-out-today-java)
+- **Astroneer** describes layered on-the-fly noise with separate cave layers. **No Man’s Sky** identifies navigable caves as a goal and documents dual marching-cubes performance work, but does not publish the cave-shape algorithm. Use these as support for deterministic layers and navigation goals, not as evidence of a specific implementation. [Astroneer](https://www.unrealengine.com/spotlights/how-system-era-softworks-leveraged-ue4-to-create-astroneer-s-wonderful-universe?lang=en-US), [NMS terrain](https://www.nomanssky.com/next-update/), [NMS meshing](https://www.nomanssky.com/worlds-part-I-update/)
+- **Enshrouded** describes sculpted macro-topology and hand-placed voxel stamps. **Valheim** documents room assets used by its dungeon generator; **Teardown** documents VoxTool for complex voxel terrain assets. These are topology/tooling examples, not disclosed SDF mouth techniques. [Enshrouded](https://enshrouded.com/ja-JP/news/enshrouded-world-design-team-reddit-ama-recap), [Valheim](https://valheim.com/support/modding-faq-for-the-asset-bundle-update-0-217-40/), [Teardown](https://teardowngame.com/voxtool/)
+- Cave research separates playable topology from cave appearance. A karst SDF paper models irregular cross-sections and warns that curved sweeps can lose continuity at high curvature; tortuous paths use a union of spheres. Erosion papers model morphology at generation time, not per voxel. [Playable cave systems](https://santosgrueiro.com/papers/2014/2014-Santam-Cave.pdf), [geological cave SDFs](https://diglib.eg.org/items/a4e7985c-af52-4b55-bd1a-eeeff6c47422), [karst erosion](https://www.sciencedirect.com/science/article/pii/S0097849321002132)
+
+These references do not guarantee VoxelForge’s walk-only contract. Keep its deterministic route, 0.34 m × 1.76 m capsule, supported floor, and slope checks authoritative.
+
+## Ranked proposals
+
+| Rank | Proposal and code location | Expected gain | Main risk / cost |
+|---|---|---|---|
+| **1** | **Limit the carve by a route floor.** Keep grade-safe route/floor data in [`PlanResolvedLayoutPassagesV1`](../../../../Standalone/Core/src/ResolvedLayoutInternal.h); in [`ApplyResolvedStratePassageCarves`](../../../../Standalone/Core/src/ShapeWorldInternal.h), constrain the tunnel void to above that floor and subtract it from native solid. For negative-is-solid fields: `void = max(tubeSdf, floorZ - z)`, then `carvedSolid = max(nativeSolid, -void)`. Blend the floor to native terrain height along route distance. Replace broad decks where native rock supports the route; keep only narrow fallback support where it does not. | Best chance of a worn path that remains part of the crater/rock instead of reading as a platform. The floor stays explicit and testable. | Medium walkability risk where the source has no solid underfoot or where FI coils overlap. Keep capsule, support, open-air, and slope gates. Low-to-moderate per-sample cost. |
+| **2** | **Blend the mouth along route distance.** Refine `mouthCarveFade` / `roughSignedDistance` in `ApplyResolvedStratePassageCarves` (around lines 1168–1209) with a local smooth CSG transition between native terrain and bore. Carving uses smooth-max with the negated void field. Keep the floor cap separate. [Smooth-min reference](https://iquilezles.org/articles/smin/). | Removes a visible seam while letting the entrance follow the local landform. | Smooth CSG moves the zero surface and can round off thin rock or support. L36’s broad filter still left a 27° crease against the earlier 20° probe. Keep it local and hold the crease gate before comparing. Small field cost. |
+| **3** | **Shape walls, not the walk plane.** Extend `considerCarveSegment` / `VF_FieldPassageWallRelief` (around lines 933–1043) with one bounded, seeded, low-frequency displacement or asymmetric profile, masked by wall orientation and distance from floor. [Domain warping](https://iquilezles.org/articles/warp/), [karst SDFs](https://diglib.eg.org/items/a4e7985c-af52-4b55-bd1a-eeeff6c47422). | Unequal pockets and folds add geology without ribs or a straight tread outline. | Too much detail can narrow capsule clearance or become periodic. One noise term is cheap; nested warps and curved cross-section sweeps are more expensive and need updated slope/Lipschitz bounds. |
+| **4** | **Reuse the current spatial culling.** Bound each new mouth feature so `BuildPassageFeatureTileList`, `PassageMayAffectDensity`, and the nearest-segment BVH skip distant voxels. These AABB and route BVHs already exist ([architecture §8.45](../../../../ARCHITECTURE.md)). Lipschitz pruning is safe only with proven bounds that include smooth blend radii and warp derivatives. [SDF pruning research](https://onlinelibrary.wiley.com/doi/10.1111/cgf.70057). | Protects CPU budget with little geometry risk; lowest-risk performance path. | Little visual gain. Full cached/interpolated distance volumes add memory and can move the zero surface; consider only after profiling, with exact evaluation near the walk surface. |
+
+## What not to repeat from L33–L37
+
+- Regular world-space octaves produced visible 8 m / 4 m wall ribs. Keep relief irregular and seeded.
+- Per-segment one-sided tread clamps produced floor washboard. Removing support altogether then caused unsupported samples; keep one continuous floor profile.
+- The L34 apron, L36 trapezoid, and L37 raised bridge read as built geometry. The bridge SDF is a separate deck primitive in `ShapeWorldInternal.h`; do not widen it to repair cave shape.
+- L36’s broad field filter removed most fragments but left a 27° crease, above the earlier 20° gate. Avoid broad blur and do not tune gates after seeing results.
+- Wall-only ripple checks missed the floor beat. Keep walk-floor profiles and negative controls for periodic relief and built shapes.
+
+## Recommendation
+
+Prioritize the floor-limited carve and local terrain-to-bore blend. Let `ResolvedLayoutInternal.h` own the deterministic walk route and grade; let native density provide visible support; confine seeded detail to walls and ceiling. The owner has accepted the current L37 crater mouth, so apply this to the remaining bridge and future shaping without reopening that look.

Standalone/Research/WorldAssemblerM3/Research1/shared-notes.md

@@ -0,0 +1,32 @@
+# Shared notes (researcher R1 <-> implementer L37), newest at bottom
+
+- **Separate cave shape from cave dressing:** Ghost Ship describes a constrained room-and-exit skeleton, then biome-specific surface noise and debris; its designers test generated variants for traversal, wayfinding, visibility and class playability ([official DRG cave-generation post](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1729500950&feed=steam_community_announcements)). For VoxelForge, keep `ResolvedLayoutInternal.h` responsible for the deterministic route / clearance skeleton and keep material-scale irregularity in `ShapeWorldInternal.h`; do not let a wall-noise change move the walk floor or route.
+- **Use distinct tunnel and cavern scales:** Minecraft 1.18 explicitly separates large “cheese” rooms from spaghetti and narrow noodle passages, and lets those noise caves form mouths where they intersect the surface ([Mojang 1.18 notes](https://www.minecraft.net/de-de/article/caves---cliffs--part-ii-out-today-java)). This supports a broad, irregular crater-to-bore transition from intersecting fields, while preserving a narrower path-aligned walk lane; a single uniform portal cylinder is the wrong visual abstraction.
+- **Layer deterministic noise, with a gameplay mask:** Astroneer’s published terrain system uses layered noise and separate cave layers evaluated on the fly without neighboring-cell dependency ([Unreal Engine interview](https://www.unrealengine.com/spotlights/how-system-era-softworks-leveraged-ue4-to-create-astroneer-s-wonderful-universe?lang=en-US)). This maps to pure seeded coordinate noise in `ShapeWorldInternal.h`, masked by distance-from-route / wall orientation so only the rock contour gets warped; keep the walk surface’s slope and capsule clearance under the existing route constraints.
+- **Treat navigation as a hard constraint, then test variety:** DRG’s designers say a structurally valid room can still be unplayable after generator variation and playtest it repeatedly; No Man’s Sky’s patch notes identify navigability as an explicit terrain-generation goal ([DRG](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1729500950&feed=steam_community_announcements), [NMS terrain update](https://www.nomanssky.com/next-update/)). For this code, keep the capsule/support/open-air and max-grade audits as geometry gates across seeded styles; visual naturalness checks supplement, never replace, them.
+- **Author macro topology, procedurally fill the in-between:** Enshrouded’s world team describes sculpted rough models and hand-placed voxel stamps for topology between POIs ([official AMA recap](https://enshrouded.com/ja-JP/news/enshrouded-world-design-team-reddit-ama-recap)). Translation: route points and surrounding crater shape should determine the large form; use bounded relief as finish. Noise alone is not a substitute for an intentional entrance profile.
+- **Avoid a single axisymmetric tube at the entrance:** The karst SDF work describes passage sections as irregular and asymmetric; for tortuous curves it switches from sweeps to a union of spheres to retain a continuous, 1-Lipschitz field ([Paris et al., *Synthesizing Geologically Coherent Cave Networks*, PDF](https://diglib.eg.org/bitstreams/fd2a57a6-f1fa-4c74-8b3e-9aea2aeb6047/download)). `ShapeWorldInternal.h::considerCarveSegment` already smooths eligible route joins; a later shape pass could add a small asymmetric cross-section / radius profile there, but preserve a conservative bound and leave floor geometry constrained. Risk: true curved cross-section frames and nearest-point evaluation cost more than the present capsule sweep.
+- **Use erosion as a shape model, not a per-voxel simulation:** Cave-network research produces natural branching/channel forms with hydraulic flow and erosion simulation ([Pytel & Mann, JCGT](https://jcgt.org/published/0004/02/02/); [Franke & Müller, karst caves](https://www.sciencedirect.com/science/article/pii/S0097849321002132)). Translate the erosion cues (unequal scallops, asymmetric channel widening, larger pockets at bends) into fixed-seed route descriptors or one bounded noise term; do not run flow/erosion iterations in `ApplyResolvedStratePassageCarves`, which is on the per-voxel CPU path.
+- **Smooth the solid/void intersection locally and watch the field bound:** Polynomial smooth-min gives a cheap continuous blend for implicit surfaces ([Quilez, smooth minimum](https://iquilezles.org/articles/smin/)); for solid carving, apply the corresponding smooth-max to the solid and negated void field. Restrict it to the opening region and fade it by distance along the path. Smooth CSG shifts the zero-set and may round away a floor or thin rock, so use capsule, support and crease audits after each change.
+- **Do not warp the walk plane:** Domain warping samples a field at noise-displaced coordinates ([Quilez, domain warping](https://iquilezles.org/articles/warp/)). It can break periodic wall bands, but its derivative changes the field slope and repeated warps add several noise evaluations; in `ShapeWorldInternal.h` apply only bounded low-frequency displacement to the wall/ceiling contour, masking by wall orientation and distance from the floor, not to the whole carve or tread field.
+- **Keep the existing broad phase; use Lipschitz pruning only with proven bounds:** VoxelForge already selects passage candidates per tile with an AABB BVH and bounds the nearest-segment search with a per-passage BVH ([architecture §8.45](../../../ARCHITECTURE.md)). Recent SDF pruning work is explicit that pruning needs exact 1-Lipschitz fields or valid updated bounds for smooth operators ([Barbier et al., *Lipschitz Pruning*, Computer Graphics Forum](https://onlinelibrary.wiley.com/doi/10.1111/cgf.70057)). Keep new fields inside those bounds; do not assume warped/smoothed noise remains 1-Lipschitz. Cached/trilinearly interpolated fields are a later option only if profiling shows repeated exact queries; interpolation can move the zero surface and needs an exact fallback near the walk surface.
+- **Bridge code lead for L37:** In the current capture-matching source, `ApplyResolvedStratePassageCarves` unions `PassageBridgeSignedDistance` for `IsPassageShortSpanSegment`; that field is a separate deck with 3.3–3.65 m half-width and about 4 m thickness ([ShapeWorldInternal.h](../../../Standalone/Core/src/ShapeWorldInternal.h), around `PassageBridgeSignedDistance`). Also check `IsPassageColumnSegment`, which routes through the same support-deck path. The render can therefore come from a planned support feature, independent of cave-wall relief; trace the flagged segment back to its bridge/column plan before changing mouth noise.
+- **Some examples use authored pieces rather than SDF mouths:** Valheim documents room assets consumed by `DungeonGenerator` ([official modding FAQ](https://valheim.com/support/modding-faq-for-the-asset-bundle-update-0-217-40/)); Teardown documents a voxel asset tool used for complex campaign terrain ([VoxTool](https://teardowngame.com/voxtool/)). These are useful for authored topology and asset tooling, but neither documents a natural carved mouth algorithm. No Man’s Sky publicly promises more navigable cave systems and reports dual marching-cubes performance work, while leaving its cave-shape algorithm unspecified ([NMS terrain update](https://www.nomanssky.com/next-update/), [Worlds Part I](https://www.nomanssky.com/worlds-part-I-update/)); don't infer its internal method.
+- **Implementer control, L37:** Disabling the FI short-span deck left the owner ground-mouth and overview JPEGs byte-identical, while the rock-column audit failed on its four short spans. The deck is needed elsewhere in the route and is not the visible crater-mouth bridge; restored it and traced the entrance carve/support path instead.
+- **Implementer control, L37:** Passage tread and native-route blend ablations left the crater ridge; disabling the route-to-mouth support handoff broke 18 FI route support samples. Current trace points to the final FloatingIslands surface-route heights: its 17-probe maximum footing and grade envelope lift the approach over the crater. L167 tests centerline footing for that final segment, with route audits still binding.
+- **Implementer trace, L37:** `FloatingIslandsInternal.h::ConnectorDensity` adds an arch up to twice the connector thickness (8 m here), so lowering connector endpoints alone leaves a crater-crossing hump. Testing the v171 version removes that arch and seats connectors 1 m below native island tops; the route is still derived and checked from the resulting field.
+- **Implementer correction, L37:** The owner FI JSON defaults to `geometryVersion=4`; v171's `>=5` experiment gate was inert and its capture matched v170. The actual L37 fix is gated by `WorldAssemblyEvaluatorVersion>=172`.
+- **Implementer result, L37:** The active v172 no-arch/−1 m connector build retained the surface route but its close capture still showed a central fin. L173 tests the previously effective −2 m sink with the arch removed; passage and both route audits remain gates.
+- **Implementer result, L37:** L173 removed the visible fin; its four surface-route misses were on the western island-0-to-1 connector at x≈−5…−3.5 m. L174 sinks only links touching anchored island 2 by 2 m, preserving the western connector height.
+- **Implementer trace, L37:** L37 ripple diagnostics show later coil queries matching the entrance relief by XY although they are about 55 m below it. The versioned L175 correction also gates the mouth fade to a 4 m vertical window around the entrance floor; the signed carve-distance lerp stays intact.
+- **Implementer experiment, L37:** The largest failing ripple window crosses two helix turns only 0.05 m apart horizontally and 4.17 m apart vertically at 3 m radius. L176 tests the 14.54° (still below 15°) route grade to increase turn separation.
+- **Implementer result, L37:** L176 reduced wall ripple to 3.01 cm but failed capsule support at one sample and left floor ripple at 2.18 cm. L177 restores the prior grade and tapers the anchored tunnel from 3 m to 2 m radius over 8–16 m from the mouth, after the fixed close camera.
+- **Implementer result, L37:** L177's 2 m tunnel radius was rejected: 103 blocked capsule samples and 3.15 cm floor ripple. The final source reverts L176/L177 route experiments and uses the v175 tunnel profile.
+- **Implementer correction, L37:** The final v175 close capture still shows a fin, so root-only connector sinking was insufficient. The global −2 m v173 view removed it, while four support misses were confined to island 0–1; v178 keeps that single link at −1 m and sinks every other connector to −2 m.
+- **Implementer result, L37:** v178 still shows the fin. L179 tests the island-0-to-1 connector at −1.5 m as a visual/support compromise; all other links stay at −2 m.
+- **Implementer result, L37:** L179's capture is byte-identical to the all−2 m v173 control, but route0 has two unsupported samples. L180 tests −1.25 m on the western link to recover those supports while keeping that appearance.
+- **Implementer trace, L37:** The crater bridge is the FI passage helix, not the island connector or short-span deck. Current control points put the route floor 5.4 m above native ground at radius 3 m inside the crater; the mesh at radius 7 m is about 0.1–0.3 m below the intended route floor. L185 tests moving the non-spiral FI passage ring from 3 m to mouth-offset+2 m (7 m), onto the native crater rim; the route/capsule/support audits remain gates.
+- **Implementer result, L37:** v188 fixes the bridge by placing the FI passage coil at 7 m (the 5 m mouth offset plus 2 m), on the native crater rim, and splitting the FI route legs after the entry into 1.375 m supports. The bridge is absent in the 6 m and 17 m views. FI route/capsule/support/open-air checks pass; floor ripple falls to 1.39 cm (1.5 cm gate), wall ripple passes. Full style/compiler audits still pending.
+- **Implementer result, L37 resumed:** v208 passes owner FI styles 0–3. Style 0 uses the terrain-following crater route and crater tread; other FI styles keep the native route/tread profile. The 8.5–12.5 m native mouth filter now applies to every FI passage style; this cleared open-air and style 1/2/3 ripple regressions. Full SW/fixture and compiler matrix still pending.
+- Implementer follow-up, L37 v208: a temporary support-off build reproduces the same 25.542° overview sample as the final mesh, so the remaining crease is not the route tread/support. At the 6 m view it is 4.396°; at 17 m the failing sample interval is 0.125 m and projects to 14.34 px at 2560×1440. The 20° overview gate remains a measured failure; no source change was made after the owner accepted the crater appearance.
+- Implementer cost, L37 v208: five interleaved pairs completed; median whole-view change was +0.63% surface-world and +2.04% floating-islands, within pair noise.