docs(assembler): Sol 6.1 review of the L20 strate/units design

Verdict: direction right; preserve today's bounds as compatibility data but reject overlaps in new layouts; approve the LOD2 boundary fix with a precise affected region; one director-owned vertical partition (strate interior / shared bedrock band / explicit void); bedrock = solid volume + explicit LOD-stable surface; first step = versioned resolved-layout snapshot + validator, no output change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CSFYgsdW8ejZSyiMf4qRSX
2026-10-20 09:20:33 +02:00
1 parent 6f9c7bd652
commit 5d5447dc32
@@ -0,0 +1,233 @@
 # Sol 6.1 (medium) read-only review of the L20 design — 2026-10-20
 Requested by the owner. Prompt: `Saved/Linux/claude/sol-l20-review.md` (copied below the answer). Session `01a1582c-547a-7701-9d9e-35239b7f0a26`, 68,458 tokens, sandbox read-only.
 **The direction is right. Preserve today’s world during conversion, but treat inconsistent bounds as compatibility data, not valid new layout. Allow the SurfaceWorld LOD2 boundary fix, with a precisely defined affected region and unchanged density.**
 L20 needs a stronger bedrock model and an earlier ownership contract. Adding floor bedrock everywhere is also a deliberate geometry change: current FloatingIslands v3 explicitly omits its lower seal.
 I only read files; I did not build, run, or modify anything.
 **1. The two decisions**
 **Decision 1: preserve first, repair separately.** L17 demonstrates why: unifying the chunk scale removed the approved SurfaceWorld ground and moved the world ([Linux17/REPORT.md:168](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux17/REPORT.md:168)).
 The mismatch is real. SurfaceWorld uses slot chunks directly as 32 Core voxels; FloatingIslands applies the owner/Core ratio ([VoxelForgeCoreAdapter.cpp:290](/home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp:290), [VoxelForgeCoreAdapter.cpp:464](/home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp:464)).
 However, preserve **effective behavior**, not just converted endpoints. Dispatch itself uses different conversions: SurfaceWorld divides Z by 32, while FloatingIslands uses the owner/Core scale ([ShapeWorldInternal.h:2130](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:2130), [ShapeWorldInternal.h:2158](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:2158)). An apparent interval between bounds therefore does not prove that interval currently generates air.
 Keep historical overlaps and ambiguities in a versioned compatibility snapshot. **Reject overlaps in newly authored layouts.** Otherwise preservation becomes permanent acceptance of the bug.
 **Decision 2: approve the change in principle.** L19 measured actual lower-ground extraction differences, not ceiling triangles: up to 1.50 m and 7.73 m ([Linux19/REPORT.md:9](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux19/REPORT.md:9)). An explicit ceiling cannot fix these.
 Define the affected tiles from the observed surface and transition support, including halos—not merely distance from a nominal strate plane. Preserve exact queries and unaffected near-player geometry. Validate against the same physical surface so the audit cannot “improve” by pairing different surfaces or hiding terrain.
 Metre authoring and default 25 cm voxels are sound. Fixed 32³ tiles mean physical tile width still follows voxel size; if Jahni wants fixed physical streaming regions, introduce those separately from internal tiles.
 **2. A concrete strate structure**
 Use one immutable, versioned director output. Distinguish a strate’s **generator interior** from the bedrock separating interiors. This makes thickness and ownership unambiguous.
 ```text
 ResolvedWorld
  schemaVersion, evaluatorVersion, seed, worldIdentity
  physicalUnit = fixed integer unit independent of voxel size
  strates[]                 // ordered downward
  verticalSegments[]        // exact partition of declared world extent
  interfaces[]
  passages[]
 Strate
  stableId                  // persisted; independent of array position
  order
  bottomM, topM             // generator interior: [bottomM, topM)
  voxelSizeM = 0.25
  latticeOriginM
  generatorKind
  recipeId, recipeVersion, resolvedRecipe, seedKey
  floorBandId, ceilingBandId
  interfaceAboveId, interfaceBelowId
 VerticalSegment
  stableId, bottomM, topM
  kind = StrateInterior | Bedrock | VoidGap
  ownerId
 BedrockBand
  stableId, bottomM, topM
  thicknessM = topM - bottomM
  volumeMaterialId
  upperFaceMaterialId, lowerFaceMaterialId
  digPolicy = Diggable | Protected | Restricted
  allowedPassageIds[]
  surfaceDescriptorIds[]
 Interface
  stableId, upperStrateId, lowerStrateId
  orderedSegmentIds[]       // bedrock, optional void, further bedrock
  passagePlacementRecipe
  resolvedPassageIds[]
 Passage
  stableId, interfaceId
  physical tunnel shape, aperture boundaries
  upper/lower endpoints, landing/support geometry
  crossedBandIds[], clearance, carvePermission
 ```
 Author in metres; serialize canonical fixed physical units with explicit rounding. The resolved fields above are produced once, not independently editable copies.
 For a shared slab, the upper strate’s floor and lower strate’s ceiling reference **the same band**. Its thickness and digging policy cannot disagree between sides. Separate skins with a void between them require three explicit segments.
 I recommend ordinary inter-strate bedrock remain diggable, preserving the established player-dug descent behavior ([ARCHITECTURE.md:472](/home/jahni/VoxelM/Plugins/VoxelForge/ARCHITECTURE.md:472)). Protection should be an explicit band policy.
 The invariants are:
 - Unique stable IDs; explicit order; finite bounds; positive interior height and bedrock thickness.
 - Every physical height within the declared stack belongs to exactly one segment. No overlaps or implicit gaps.
 - Every strate has floor and ceiling bedrock, including terminal strates.
 - Interiors remain closed except through registered passages or authorized player-created apertures.
 - A void gap lies between closed skins. A freely open connection requires an explicit aperture, potentially covering the whole interface.
 - Passages cross every intervening band and provide usable entrances, exits, and support.
 - All generators, proofs, streaming, meshing, collision, and material queries consume this snapshot. None reconstruct boundaries from chunk indices.
 Keep legacy recipe seed keys frozen during migration. Switching randomness from strate index to stable ID must be versioned separately to avoid changing the world.
 **3. Bedrock should be both volume and explicit geometry**
 Use an authoritative solid volume for density, digging, collision queries, and conservative proofs, plus explicit boundary surfaces for reliable extraction. Both representations derive from the same band and aperture descriptors.
 Density alone cannot guarantee a thin band survives coarse sampling. Conversely, a visual plane alone supplies no solid interior and can disagree with collision or digging.
 Current code illustrates the mismatch: the upper seal fills inward over its thickness, while fallback ceiling vertices are placed at `Bounds.TopZ` ([VoxelDensityPrimitives.h:44](/home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Public/VoxelDensityPrimitives.h:44), [FarShellsInternal.h:1238](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/FarShellsInternal.h:1238)). The new contract must distinguish the band’s outer boundary from its room-facing surface.
 For a ceiling above an interior, its lower face is at `topM`; for a floor below an interior, its upper face is at `bottomM`. Thickness extends away from the interior.
 The mesher should own each exposed face once, suppress overlapping ordinary extraction, and use shared edge anchors across LODs. Passage mouths need explicit clipping and wall geometry; corner sampling alone can miss a small aperture.
 Authorized edits must modify both density and surface extraction. Protected bands require explicit edit masking. Generated passages carve after bedrock composition, consistent with today’s passage ordering ([VoxelDensityPrimitives.h:86](/home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Public/VoxelDensityPrimitives.h:86)).
 Collision uses the same geometry semantics at a gameplay resolution independent of camera LOD. Peers reproduce bands and generated passages from the versioned plan; only player edits need synchronization.
 Cost stays local: cheap band queries and flat faces generally, extra refinement around openings and edited areas.
 **4. What I would change in L20**
 My top three risks are:
 1. **Migrating bounds without migrating dispatch.** Today’s “resolved” bounds still consult the manager and branch by generator ([ShapeWorldInternal.h:67](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:67)). Snapshot ownership, fallback behavior, and recipe anchors together.
 2. **Changing gameplay under structural cleanup.** FloatingIslands v3 applies only an upper seal ([ShapeWorldInternal.h:2192](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:2192)). Restoring a floor changes visibility and descent. Require a new layout version; do not silently reintroduce the removed floor.
 3. **Maintaining conflicting density, mesh, and collision boundaries.** Explicit surfaces must be authoritative constraints derived from bands, rather than another repair overlay.
 Reorder the migration to: compatibility snapshot → canonical ownership and bedrock schema → minimal shared boundary composition → targeted LOD transition prototype → metre authoring and generator adapters. Keep the broad generator/helper refactor incremental. Mixed resolutions remain last.
 **5. Smallest first implementation**
 Implement a **versioned resolved-layout snapshot and validator**, populated by the existing director/adapter. Record actual physical bounds, recipe/cap anchors, voxel sizes, current floor/ceiling behavior, and dispatch provenance. Flag incompatible intervals explicitly. Leave evaluation unchanged.
 Its acceptance test should require:
 - Exact preservation of existing resolved anchors and recipe values, including routes and cap profiles.
 - Boundary probes immediately below, at, and above every endpoint, comparing actual old dispatch with the snapshot’s recorded behavior.
 - Deterministic identity across worker counts and serialization round trips.
 - Rejection of overlapping or uncovered new layouts.
 - Existing SurfaceWorld density and geometry hashes unchanged; L19 ceiling coverage unchanged.
 This delivers inspectable strate structure first. Enforcing new floors and repairing ledges then become separate, measurable world changes.
 ---
 ## Prompt
 # VoxelForge — design review (Sol, read-only): strate structure, bedrock and the L20 decisions
 You are reviewing a design for VoxelForge, a voxel terrain plugin for a multiplayer Unreal Engine
 game, with its generation done in a C++ Core library. The game is underground: the world is a
 vertical stack of **strates** (layers). Each strate has its own generator type:
 - SurfaceWorld: an enclosed surface-like heightfield world;
 - FloatingIslands;
 - caves, and future types.
 Players travel between strates through passages. Every machine generates the same terrain from a
 seed. Only player edits cross the network.
 **This is a read-only review.** Read files, but don't build, run, edit or create anything. The
 owner pays for this review, so be efficient: read what you need, and keep the answer focused and
 concrete.
 ## Read first
 - `/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/DESIGN_STRATA_UNITS_AND_LAYERS.md`: the design
  under review (round L20).
 - `/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux20/REPORT.md`
 - For the bugs that motivated it: `.../Linux17/REPORT.md`, `.../Linux18/REPORT.md` and
  `.../Linux19/REPORT.md`, in the same folder. Each has an "Orchestrator review" section at the end.
 - Code, as needed:
  - `Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp` (plan building: SurfaceWorld vs
    FloatingIslands chunk conversion);
  - `Source/VoxelForge/Private/VoxelStrateManager.cpp` and `Source/VoxelForge/Public/VoxelStrateTypes.h`
    (strate slots and params);
  - `Standalone/Core/src/ShapeWorldInternal.h` (`FResolvedStratumBounds`, `GetResolvedStratumBounds`);
  - `Standalone/Core/src/FarShellsInternal.h` (`AppendStratumBoundaryCeilings`);
  - `Source/VoxelForge/Public/VoxelDensityPrimitives.h` (boundary seals);
  - `CLAUDE.md`, and `ARCHITECTURE.md` (§8) for the hard rules.
 ## The owner's direction
 The owner is Jahni. Quotes:
 - "Everything should use a parameter like on the strate, saying which voxel size it is, by default
  25 for everyone, same for island."
 - "Our system should be in different categories: the director/orchestrator, the generators (all
  using the same kind of format, helper functions … from a shared library like noise functions) and
  the mesher; the generators are dictated by our current strate parameters."
 - "The voxel size shouldn't dictate the size of a chunk … wouldn't it be better to have like Unreal
  unit distance, and have x voxels fill it?"
 - "Any strate should have a ceiling, since we're underground."
 - "The ceiling height is decided by the strate parameter, it's not something unique to sky island."
 - Now: **"we need proper strate structure, knowing where each starts etc."**, including the strate
  **bedrocks (ceiling and floor)**.
 ## What I (the orchestrator) recommended, which he wants judged
 1. **Layout is authored in metres;** each strate has a voxel size (default 25 cm); internal tiles
   stay 32³ voxels. Units cost nothing at run time, while the voxel count does.
 2. **Decision 1 (preservation):** when converting today's chunk-based strate parameters to metres,
   keep every strate exactly where it currently is in the generated world, including any gap or
   overlap that the current 8 m (SurfaceWorld) vs 4 m (FloatingIslands) per-chunk mismatch creates.
   Report those gaps and overlaps, then tune in metres. The alternative is to force them to meet
   during the migration.
 3. **Decision 2:** allow step 5 of the migration (an explicit, LOD-stable interface surface) to
   change SurfaceWorld LOD2 output near strate boundaries, to fix the owner's "ledges" (cross-LOD
   ring steps of up to 1.5 m and 7.7 m at the FloatingIslands/SurfaceWorld interface). Near-player
   terrain away from boundaries must stay identical.
 ## Questions (answer each)
 1. **Are the two decisions and the direction right?** Say where you'd decide differently, and why.
   Is preserving today's possibly-inconsistent bounds the right first step, or does it entrench a
   bug? Is there a better migration order?
 2. **Propose a proper strate structure.** A concrete data model the director owns. For each strate:
   - its stable ID and order;
   - top and bottom in metres;
   - **floor bedrock and ceiling bedrock:** thickness in metres, material, whether players can dig
     through, and how passages pierce them;
   - its voxel size;
   - its generator and recipe;
   - its interfaces to the strate above and below: solid bedrock band, open void, passage
     placement.
   Define the invariants: no overlaps; every metre owned by exactly one strate or one explicit
   bedrock/gap band; ceiling and floor always closed, except at passages; contiguous or explicit
   gaps. Show how "where each strate starts and ends" becomes a single source of truth that every
   generator and the mesher read, never re-derive.
 3. **Bedrock as geometry.** Should a ceiling or floor be a density band (a seal), an explicit
   surface the mesher knows about, or both? Weigh LOD stability (the ledge problem: thin seals
   extract at different heights per LOD), collision, player digging, multiplayer determinism, and
   cost. Give a recommendation.
 4. **What in the L20 design would you change, cut, or reorder?** Name the top 3 risks.
 5. **The smallest first implementation step** that delivers the strate structure without moving the
   approved SurfaceWorld world, and its acceptance test.
 ## Answer format
 Plain English. The owner reads it, so lead with your verdicts in a few lines, then the details.
 Around 1,500 words at most, plus the data-model sketch. Cite file:line where you rely on code.