VoxelForge/AUDIT-2026-07.md

# VoxelForge — Independent Audit, 2026-07-26

*Scope: every file under `Source/VoxelForge/` (~16,400 lines, 30 files) + all five design docs, read in
full. Axes requested: **correctness & threading**, **perf & algorithm choice**, **architecture &
maintainability**. Bar: **fitness for purpose for VoxelM** — not marketplace-grade generality.*

> ⚠️ This file is currently **untracked** — the strict-whitelist `.gitignore` only keeps `Source/`,
> `CODEMAP.md` and the `.uplugin`. See P1.

---

## 0. Verdict

**This is good work.** Well above the median for a solo UE plugin: the perf reasoning is real and
measured (Insights traces cited with numbers), the invariants are named and defended, the caches are
box-validated rather than key-validated for the right reasons, and almost every expensive path is
budgeted. The clipmap + trivial-tile-reject + worker-built streams architecture is the correct shape
for this game. Nothing in here reads as cargo-cult.

**And it is not in a state where you can answer "does it work?"** Three separate things have quietly
gone wrong at the process layer, and they compound:

1. **~3 weeks of work sits in one commit called `tmp`** (3,903 insertions / 1,029 deletions across 20
   files). No bisect, no per-feature revert, no "when did seed X stop matching".
2. **The design record isn't in version control.** `ARCHITECTURE.md`, `fable-idea.md`,
   `REVIEW_FINDINGS.md`, `CLAUDE.md` are all excluded by `.gitignore`. Only `CODEMAP.md` survives.
3. ~~A stack of "CODE-COMPLETE, PENDING BUILD"...~~ **CORRECTED 2026-07-26 (Jahni):** everything has
   been built and verified working. The *documents* are stale, not the code — `fable-idea.md` and
   `ARCHITECTURE.md` still carry "PENDING BUILD" markers dated 07-04/-06/-08 that were resolved and
   never ticked. That's a doc-hygiene item, not a project-state risk. The uncommitted tree is
   deliberate: the current 3D work is experimental (see §7).

For a codebase whose central promise is **determinism**, having no per-change history is the sharpest
internal contradiction in the project. That's the headline.

The code findings below are secondary to that, but there are real ones — including one latent bug
that will silently flatten your terrain the day you pass a large seed.

---

## 1. Correctness & threading

### C1 — Large seeds destroy the noise field ⚠️ **highest-severity latent bug**

`VoxelGenerator.cpp` uses `const float SeedF = (float)Seed;` and then adds `SeedF * k` (k up to
**97.7**) directly into Perlin coordinates — ~40 call sites, e.g.:

```cpp
// VoxelGenerator.cpp:1390 (Scallop)
CellularNoise3D(FVector(WorldX * SF + SeedF * 83.1f, ..., EffectiveZ * SF + SeedF * 97.7f));
```

Float has a 24-bit mantissa. At magnitude `V` the ULP is `V · 2⁻²³`:

| `Seed` | `SeedF · 97.7` | ULP there | Effect on a coordinate stepping by ~0.02/voxel |
|---|---|---|---|
| 1,000 | 9.8e4 | 0.012 | fine |
| 100,000 | 9.8e6 | 1.2 | noise lattice-snaps; detail gone |
| 10,000,000 | 9.8e8 | **117** | the coordinate term is *completely* absorbed → that noise field becomes **constant** |

`ChangeSeed(int32)` is `BlueprintCallable`. The moment game code calls it with anything like
`FMath::Rand()` (up to 2³¹), whole noise terms collapse to a constant and terrain goes flat or
degenerate. It works today only because your seeds are small.

`fable-idea.md` **flagged this exact issue** in T2.a ("seed offsets like `SeedF * 7.3f` can reach 1e8+
where float precision is ~64 units — hash the seed into a bounded offset range (e.g. [0, 16k])") and it
was never done.

**Fix (one line, one world re-tune):**
```cpp
const float SeedF = (float)(VoxelHash::Mix((uint32)Seed) & 0x3FFF);   // bounded [0, 16383]
```
Applied consistently at all `SeedF` definitions (`:682`, `:1756`, `:2066`, `:2208`, `:2275`, `:2687`).
**Verify:** set `Seed = 1234567` in the data asset and look at the terrain. If it's flat, this is live.

---

#### ⛔ CORRECTION 2026-07-27 — **the fix above is WRONG. Do not apply it.**

It bounds `SeedF` but leaves the **multiplier** in place, and the multiplier is where the magnitude
comes from. `SeedF · 97.7` with `SeedF ≤ 16383` still reaches **1.6e6**, where the float ULP is:

| | max coord term | ULP there | vs the ~0.02/voxel coordinate step |
|---|---|---|---|
| `Seed = 1000` today | 9.8e4 | 0.012 | 0.6× — fine |
| **audit's proposed fix, worst case** | **1.6e6** | **0.19** | **9.5× — still lattice-snaps** |

So the "fix" would have made the bug *less catastrophic* while leaving it live, and — worse —
**closed the ticket.** It would have cost a build and a world re-roll to discover that mid-range
seeds still degrade. (Found by doing the arithmetic before applying it, not after.)

**The actual fix: bound the OFFSET, not the seed — i.e. delete the multipliers.**

The `· 7.3f … · 97.7f` multipliers exist only to decorrelate the ~40 noise call sites from each
other. That is a *hashing* job, and hashing does it better: give each site its own offset drawn from
the full seed entropy, already in final units, with no multiplier to re-inflate it.

```cpp
// VoxelHash — one definition, so the bound cannot drift per site.
// Site-salted, final units, bounded: ULP at 16384 is 0.002 = 10% of a voxel step.
FORCEINLINE float SeedOffset(int32 Seed, uint32 Site)
{
    return (float)(Mix((uint32)Seed ^ (Site * 2654435761u)) & 0x3FFF);
}
```
`WorldX * SF + SeedF * 83.1f` → `WorldX * SF + VoxelHash::SeedOffset(Seed, kSiteScallopX)`.

**Why this is strictly better, not just smaller:** bounding `SeedF` alone would squeeze all seeds
through 16384 distinct noise offsets *shared across every site*, so two colliding seeds would give
identical noise everywhere. Per-site salting means two seeds must collide at **all** ~40 sites to
produce the same world — which is never.

**Scope:** ~40 call sites, mechanical, plus the same bug now inherited by the operator stack
(`FSlabVoidSource::SeedF`, `VoxelDensityOpStack.cpp`). Must land in **both** paths in one change, or
the equivalence tests will (correctly) scream. **Cost of delay: every archetype ported copies it
again.**

---

#### ⚠️ REOPENED AND RE-CLOSED 2026-07-28 — the sweep missed one site, and the search pattern is why

`§C1` was reported fixed on 2026-07-27 (85 sites, *"0 left behind"*), and
`VoxelForge.Determinism.LargeSeedSurvives` went green on seeds up to 2e9. **One site had survived**,
found by reading `GetFloatingIslandDensity` line by line to port it:

```cpp
// VoxelGenerator.cpp — the floating-island domain warp
const float WX = WorldX + FractalNoise3D(FVector(WorldX * 0.04f + (float)S * 0.0007f, ...));
```

**Why the sweep missed it:** the sweep matched the `SeedF * K` spelling. This site spells the same
thing `(float)S * K`, where `S` is the archetype's salted seed. A textual sweep finds a *spelling*,
not a *bug* — and the green property test could not compensate, because `LargeSeedSurvives` asserts
that the **heightfield** still varies, and this site perturbs an **island outline**. Neither the
comparison oracle nor the property oracle covered it; a human read did.

**Impact, before the fix:** at `Seed = 2e9` the term reaches ~1.4e6, where the float ULP is 0.125
against a per-voxel step of 0.04 — the warp flattens and every island silhouette snaps back to a
perfect circle. Cosmetic rather than catastrophic (the C1 failure mode for a *heightfield* is a flat
world), which is exactly why nothing screamed.

**Fixed** in both paths in one pass (`VoxelHash::SeedOffset(S, 0.0007f)` in `GetFloatingIslandDensity`
and in `FIslandBlobSource`), so `FloatingIslandEquivalence` stays a valid oracle.

**One sharp edge recorded:** `SeedOffset` quantises the site key by `×100 + 0.5`, so `0.0007f` maps to
site **0**. That is unique today — every other key in the plugin is ≥ 0.19 — but the next sub-`0.005`
key will collide silently. Two sites sharing an offset is a correlation, not a collapse; still, it is
a footgun in a helper whose whole job is decorrelation.

**Lesson, and it is the session's third instance of the same one:** *verify the premise before
reasoning from it.* "C1 is closed" was load-bearing for two days and was 1 site short. `grep` over a
spelling is evidence about the spelling.

---

### C2 — Per-chunk parameter caches have no layout key (stale after live-edit) ⚠️ **real, reproducible**

`VoxelGenerator.cpp:503-524`:

```cpp
thread_local FIntVector CP_Chunk(INT32_MAX, INT32_MAX, INT32_MAX);
thread_local ECaveGeneratorType CP_GenType;
thread_local FStrateGenerationParams CP_Tunnel;   // + CP_Slab, CP_Maze, CP_Surface, CP_Vert,
                                                  //   CP_Float, CP_Dist, CP_BiomeCtx, ...
if (ChunkCoord != CP_Chunk) { /* refetch everything */ }
```

The key is **`ChunkCoord` alone** — no seed, no layout version. After `RebuildStrates()` or an
`OnObjectModifiedInEditor` live edit, `StrateManager::Initialize` rebuilds the layout and bumps
`PassagesVersion`, but a pooled worker thread whose `CP_Chunk` still equals the chunk it's now asked to
regenerate **skips the refetch and generates with the old params**. Since `RegenerateAllChunks` reloads
the *same* tile coords, often on the *same* workers, this is likely rather than exotic.

Same pattern, same gap:
- `OC_Chunk` — the `GetSurfaceHeightAt` oracle cache (`:2420`)
- `BM_Chunk` — `GetBiomeMaterialAt` (`:3045`)
- `FChunkBiomeCache::Contains` — keyed on `(box, ChunkZ, Seed)` but **not** the biome context, so
  editing a strate's `Biomes[]` leaves stale cells

Note the asymmetry: the SDF cache (`CachedSeed`) and the surface-column cache (`GSurfColCache`, keyed on
Seed) **are** seed-guarded, and the strate-index memo **is** version-guarded (`SI_Version`). So
`ChangeSeed` mostly survives; **live-edit is where this bites**. Symptom: "I tweaked the strate asset,
regenerated, and one patch kept the old shape."

#### ✅ CONFIRMED BY READING, 2026-07-28 — the SDF cache DOES serve stale rooms *within* a strate

Raised as a suspicion while porting TunnelNetwork, then checked rather than believed. **It holds**,
on default settings, with no live edit and no unusual asset configuration.

The chain, each link read in the code rather than inferred:

1. **`GetGenerationParams` really does vary within one strate.** Its Gradient branch computes
   `Alpha = 1 − DistFromBottom / EffectiveBlend` where `DistFromBottom = ChunkCoord.Z −
   Slot.BottomChunkZ`, then returns `FStrateGenerationParams::Lerp(BaseParams, BelowParams, Alpha)`.
   `Alpha` is a function of **chunk Z inside the slot**, so two chunk Zs in the *same* slot get
   genuinely different params. The top boundary mirrors it.
   *(`VoxelStrateManager.cpp`, `GetGenerationParams`, the `case EVoxelStrateTransition::Gradient:`
   arms — both of them.)*
2. **It varies in exactly the fields that place rooms.** `Lerp` expands the
   `VF_STRATE_PARAM_FIELDS` X-macro, which lists `RoomSpacing`, `RoomDensity`, `MinRoomRadius`,
   `MaxRoomRadius`, `RoomHeightRatio`, `RoomShapeVariety`, `SDFBlendRadius`, `CaveWarpStrength`,
   the tunnel fields — every input `BuildChunkCache` reads.
3. **And it is the DEFAULT.** `UVoxelStrateDefinition::TransitionType = Gradient` and
   `TransitionBlendChunks = 2`. So at each end of every strate there are two chunk-Z layers with
   distinct params (`Alpha` 1.0 and 0.5), out of the box.
4. **`StrateIndex` cannot save it.** The memo resolves the *slot* index from the band centre, so it
   is identical for every chunk Z within the slot. The cache key is `(XY box, StrateIndex, Seed)`
   and the XY box does not change when the worker moves down a column. **No rebuild happens.**

⇒ A worker that generates `(X, Y, Z1)` and then `(X, Y, Z2)` in the same strate and the same XY box
evaluates the second chunk against **the room list baked from the first chunk's params**.

**Two consequences, and the second is the serious one:**
- a visible seam / wrong room sizes in the transition band, and
- **the result depends on which chunk that worker happened to build first.** That is a window-
  invariance break (`ARCHITECTURE §8.4`) rather than a cosmetic bug, and in multiplayer it means two
  peers can generate different geometry for the same chunk from the same seed — a direct
  `OPSTACK-PLAN §2.6.1` violation on the *original* path.

**Why nothing caught it:** the test fixture sets `TransitionType = Hard` on every strate on purpose
(so "which archetype owns this chunk" stays unambiguous), which switches the blend off entirely.
The one configuration the tests never build is the default one.

#### ✅ FIXED 2026-07-28 (the SDF-cache half) — pending build

The params now travel into the key, and the shape of the fix is worth recording because the obvious
version of it was the wrong one.

`GetDensityWithParams` takes **two new required arguments**, `ParamsFingerprint` and `LayoutVersion`,
and both go into the `bNeedRebuild` test next to the existing `(box, strate, seed)`.

- **Required, not defaulted.** A caller that forgets must fail to compile rather than silently
  inherit the hole — the same discipline that put `LayoutVersion` inside `FVoxelOpContext`.
- **The CRC is computed once per chunk, not per voxel.** `FCrc::MemCrc32` over ~300 bytes on the
  hottest path in the plugin would have been a real regression; instead it is taken where the params
  memo already lives (`CP_TunnelFP`, refreshed in the same block that refetches `CP_Tunnel`), so the
  per-voxel cost is two integer compares.
- **Why not "add chunk Z to the key" (the alternative this section used to offer):** it is not
  actually cheaper *and* it is not sufficient. `Interleaved` makes `Alpha` depend on chunk **XY**
  too, and chunk XY is *not* pinned by the existing key — the box deliberately outlives the chunk so
  that `WorldX ± 1` gradient probes don't thrash it (`ARCHITECTURE §8.10`). Pinning chunk XY to fix
  the params would have destroyed that invariant. The fingerprint fixes the cause and leaves the box
  reuse intact: what forces a rebuild now is a *real* params change, once per chunk in a transition
  band, which is the number of rebuilds this cache should always have done.

The three test call sites pass `VF_FP(P)` so the **oracle no longer shares the defect under test** —
see the rewritten note at check 3 of `VoxelForgeOpStackTunnelTest.cpp`.

**Still open in this section:** the `OC_Chunk` / `BM_Chunk` / `FChunkBiomeCache` sites listed above.
Those are the live-edit staleness half, not the determinism half, and they are untouched.

The operator-stack port does **not** inherit this: `FRoomGraphSource` folds a `FCrc::MemCrc32`
fingerprint of the params (plus `LayoutVersion`) into its key, so differing params force a rebuild.
`VoxelForge.OpStack.TunnelNetworkSpineEquivalence` check 3 exercises exactly that — and deliberately
does *not* compare against the original there, because the original would fail it.

**Fix:** the getter already exists and is already used elsewhere —
```cpp
const uint32 LV = StrateManager->GetLayoutVersion();
if (ChunkCoord != CP_Chunk || LV != CP_Version) { CP_Version = LV; /* refetch */ }
```
Three sites. Cheap, and it closes a whole class of "why didn't my edit apply".

---

### C3 — `FMath::PerlinNoise2D` survived the SIMD migration, on the per-voxel hot path

`VoxelCaveMorphology.cpp:799-800`, inside `EvaluateSDFCached`'s **per-room, per-voxel** loop:

```cpp
float N = FMath::PerlinNoise2D(FVector2D(Pos.X * RF + SF, Pos.Y * RF + SF * 1.7f)) * 0.65f
        + FMath::PerlinNoise2D(FVector2D(Pos.X * RF * 2.3f + SF * 3.1f, ...)) * 0.35f;
```

Two **double-precision, permutation-table** UE Perlin calls per voxel per in-range room. The entire T2.a
pass existed to remove exactly this from the density path, and `ARCHITECTURE §8.10` states outright:
*"Don't reintroduce `FMath::PerlinNoise3D` on the density path."* The 2D sibling slipped through the net.

Gated by `FloorReliefStrength > 0` (default 0), so it's **dormant today** — but the moment you author a
room floor with relief (the tooltip recommends 5-10 for "clear hills and basins — interesting to walk
across"), every TunnelNetwork voxel near a room pays up to ~6 double-precision Perlin evals. That is
plausibly larger than everything T2.a saved.

**Fix:** `VoxelNoise::Perlin3D(x, y, 0.0f)` (or add a `VoxelNoise::Perlin2D`). One-time visual re-tune of
the floor relief; nothing else moves.

---

### C4 — Streaming stops if the pawn is at exactly the origin, or before a pawn exists

`VoxelWorld.cpp:453`:
```cpp
FVector PlayerLastPos = GetPlayerPosition();          // returns ZeroVector when no PC/pawn
if ((PlayerLastPos != FVector::ZeroVector)) { UpdateChunksAroundPosition(...); ... }
```

Two problems with using a value as a validity sentinel:
- **(0,0,0) is a real, designed location** — it's the (0,0) descent spine, the landing column in every
  strate. A pawn resting exactly there freezes chunk streaming, atmosphere, decorations and the density
  volume for that frame.
- **No pawn ⇒ permanent silent stall.** Early `BeginPlay`, a cinematic without a possessed pawn, or a
  future headless/dedicated path (§9 explicitly plans for this) gets a world that never generates and
  logs nothing.

**Fix:** `bool bHasPlayer` out-param on `GetPlayerPosition`, or return `TOptional<FVector>`.

---

### C5 — Shutdown spin-waits time out and then destroy objects workers are still reading

`AVoxelWorld::EndPlay` (`:319-330`) waits 3 s on `ActiveTaskCount`, logs a warning, then **falls through
to teardown** while a worker may still be inside `GenerateTileResult` holding `Generator`/`Mesher`/
`StrateManager`. `UVoxelContentManager::NotifyShutdown` does the same (3 s, then `break`), and its task
lambda captures raw `this` (a UObject) — so after the timeout, `bShuttingDown.load()` and
`DecoResults.Enqueue()` touch freed memory.

`UVoxelDensityVolume` gets this right (`FillThread->Kill(true)` — unbounded, blocks until `Run()`
returns). The other two should either be unbounded too, or hold a shared-ownership handle the workers
keep alive.

Low probability. High confusion cost when it does fire — it presents as a random PIE-exit crash.

---

### C6 — The diff layer is an unbounded append-only list of brush strokes

`UVoxelDiffLayer` stores each `FVoxelModification` in **every chunk its AABB overlaps**, and
`EvaluateMods` iterates **all** of a chunk's mods per voxel:

```cpp
for (const FVoxelModification& Mod : Mods) { /* sphere/box/capsule falloff */ }
```

- `MaxModifications` defaults to **0 = unlimited**.
- No compaction, no rasterization to a sparse voxel grid, no spatial subdivision within a chunk.
- No serialization (`fable-idea` F4 save/load is unbuilt), so the entire player footprint dies with the
  session.

Cost of re-meshing a chunk grows **linearly in the number of strokes ever made in it**, forever. For a
game whose stated core verb is digging, this is the most significant architectural gap in the plugin.
It's invisible today because nobody has dug 500 times in one chunk.

The threading is correct (`FRWLock` + the version-stamped snapshot cache is a genuinely nice design —
~27 lock ops per tile instead of ~86k). It's the *data structure* that won't scale, not the concurrency.

**When it matters:** the moment mining becomes a real loop. The natural answer is a per-chunk sparse
`uint8`/`int8` delta grid that strokes rasterize into (O(1) per voxel, bounded memory, trivially
serializable, and it's the same representation MP §9.5's "compacted diff snapshot" wants).

---

### C7 — The density volume runs by default for a feature that's switched off

`bEnableDensityVolume = true` (`VoxelSettings.h:268`). What that buys, per frame while streaming:

- a dedicated OS thread (`FVoxelDensityFillRunnable`),
- a `CHUNK_SIZE³` quantize + 32 KB queue payload per capture-eligible level-0 tile,
- a `TMap<FIntVector, TArray<uint8>>` capture cache,
- and the big one — `UploadDirtyTextures()` copies **the whole `Res³` array** and issues a full
  `RHIUpdateTexture3D` per dirty level. `BlitCaptureToWindow` sets `bGPUDirty = true` on *every* tile
  ingest, so level 0 is dirty essentially every frame a tile lands.

At the default `Res = 128` that's **2 MB CPU copy + 2 MB GPU upload per level per frame** during
streaming; at 192 it's ~7 MB. The code itself flags it: *"Sub-box upload (with toroidal wrap-splitting)
is a later optimisation."*

**CONFIRMED 2026-07-26 (Jahni): the lighting system is deprecated for now.** So this is not
speculative — the volume, the fill thread, the capture path and the per-frame texture upload are all
running to feed a consumer that no longer exists.

**Action:** set `bEnableDensityVolume = false`. Straight cost deletion, no behavioural change. If the
volume is revived later, the sub-box upload (with toroidal wrap-splitting) must land first — a full
`Res³` re-upload per frame was never meant to be the steady state.

Also worth deleting while it's cold rather than leaving it half-live: `UpdateTerrainMaterialParams`
still recomputes and pushes `TVP0..TVP9` onto every terrain MID each Tick, and `ApplyMeshToTile` still
routes every material through `GetOrCreateTerrainMID` when the volume is enabled. With `bEnable...` off,
both self-disable — but the code paths stay as a trap for whoever reads them next.

---

### C8 — Documented invariant that isn't checked: `OriginRoomRadius` vs the COLLECT margin

`BuildChunkCache` guarantees window-invariance by collecting rooms within
`CollectMargin = 2·MaxTunnelLength + MaxInfluence`. The origin room is special-cased: it's also added when
`RoomReachesSearchBox(...)` succeeds even if `(0,0)` is *outside* the collect box. In that case
`NearestNeighbor[OriginIdx]` and the `OriginDowngraded` ranking are computed over a **different candidate
set** than a chunk near `(0,0)` computes → different tunnel decisions → a discontinuity ring at roughly
`CollectMargin` from origin.

**Cannot fire at defaults** (`OriginRoomRadius = 20`, `MaxTunnelLength = 200` ⇒ margin ≈ 434). It becomes
reachable only with a very large origin room *and* short tunnels. Flagging it because the tooltip invites
"30+ → massive starting cavern" and there's nothing stopping someone typing 500.

**Fix:** an `ensureMsgf(OriginRoomRadius < CollectMargin)` in `BuildChunkCache`, plus a line in
`ARCHITECTURE §8.4`.

---

### C9 — The build uses `/fp:fast`, and the MP plan assumes bit-reproducible terrain 🔴 **NOW THE TOP OPEN RISK — promoted 2026-07-27**

> **Why this outranks everything else in this document now.** Jahni stated the actual acceptance bar:
> *"only having it 99.99% at worst reproducible if two people share the same seed, since everyone
> rebuilds it on multiplayer."* That is **precisely and only** the guarantee this entry says
> `/fp:fast` weakens. Fidelity to the old world was dropped as a requirement (`§C10`); peer agreement
> replaced it as the single bar. **This entry is now load-bearing.**
>
> **The concrete case to decide:** a **Linux dedicated server** generating collision geometry and nav
> against **Windows clients** compiles the same density code under *opposite* float models
> (`ClangToolChain` → precise, `VCToolChain` → `/fp:fast`). That is not a theoretical divergence.
> Same-platform peers on the same build are fine.
>
> ### ✅ HALF FIXED 2026-07-27 — and the other half is a different mechanism
>
> **`FPSemantics = Precise` is set** (IWYU debt cleared to allow it). MSVC now gets `/fp:precise`,
> Clang gets `-ffp-contract=off`; both are IEEE-754 with no contraction, so **the compiler half is
> closed by construction.** It also dissolved `§C10` entirely.
>
> **⚠️ THE LIBRARY HALF IS STILL OPEN, and I nearly missed it by assuming.** After setting Precise I
> reasoned the cross-platform risk was gone. It is not:
>
> **`sinf`/`cosf` are not specified by IEEE-754.** MSVC's CRT and glibc's libm may legitimately
> return different results (typically ≤ 1 ULP). And `FMath::Sin`/`FMath::Cos` are used throughout the
> density path — layer lines (`VoxelGenerator.cpp:2275`, `VoxelHeightOpStack.cpp:232`), ribs (`:1357`),
> room placement (`:1520`), rotations (`:362`, `:408`, `:1663`). So a Windows host and a Linux client
> can still disagree, just by ~1 ULP instead of by a whole reassociation.
>
> **Measured, not assumed:** `CrossPlatformDigest` now reports a *profile* — samples within 1e-4 /
> 1e-5 / 1e-6 of the isosurface. Only the tight band matters (a libm delta is ~1e-6 absolute on
> densities of magnitude ~10), and the first run showed **2 / 115 000 within 1e-4** — i.e. the wide
> band, which over-states the risk by ~100×. The tight-band number is the one to watch.
>
> **If it must be zero:** a deterministic in-house `sin`/`cos` in the density path (a polynomial with
> defined rounding), which costs one more world re-tune. **Not another build flag** — no compiler
> setting can make two different libm implementations agree.

Found while chasing a 1-ULP difference between `GetMazeDensity` and its operator-stack port. The
difference survived a full bisect down to code that is character-for-character identical, which
pointed at the toolchain rather than the port. It is:

```csharp
// UnrealBuildTool/Platform/Windows/VCToolChain.cs
case FPSemanticsMode.Default: // Default is imprecise FP semantics.
case FPSemanticsMode.Imprecise: Arguments.Add("/fp:fast"); break;
```

and UBT's own doc for that mode: *"FP math isn't IEEE-754 compliant: the compiler is allowed to
transform math expressions in ways that might result in differently rounded results from what
IEEE-754 requires."* The plugin sets no `FPSemantics` override, so it gets the default.

**⚠️ And the default is not the same default everywhere.** `ClangToolChain.cs` — used by Linux, Mac,
and Windows-with-Clang:

```csharp
case FPSemanticsMode.Default: // Default to precise FP semantics.
case FPSemanticsMode.Precise:
    Arguments.Add("-ffp-contract=off");
```

`VCToolChain` additionally forces `Precise` when the Windows compiler is Clang. So **the same
`FPSemanticsMode.Default` resolves to opposite float models per toolchain**, and Windows/MSVC is the
only imprecise configuration in the engine's defaults. Two builds of identical source are therefore
not merely *permitted* to diverge — they are compiled under different rules.

**Two consequences, one benign and one not:**

**Benign — refactors are not bit-identical in practice.** See `§C10` for the measured detail: the
Maze port reproduces the original's SDF *bit for bit* but its final density differs by 1-2 ULP on
~2% of samples, with zero isosurface crossings. The acceptance criterion is encoded in
`VoxelForge.OpStack.MazeEquivalence`: **hard-fail on any isosurface crossing, tolerate ULP-scale
deltas, warn on anything larger.**

**Not benign — `ARCHITECTURE §9.1`'s multiplayer model rests on this.** The plan is "replicate the
seed + layout + diff, never the geometry; every peer regenerates identically." That guarantee is
only as strong as the floating-point reproducibility of the density path, and under `/fp:fast` it
holds **only between bit-identical binaries**. Same build, same platform: fine — `DensityPurity`
proves the field is pure across threads and query order. But a different compiler version, a
different optimisation level (Debug vs Shipping), or a different platform's toolchain may produce a
subtly different world from the same seed.

The docs already reject GPU density partly because *"cross-GPU float determinism is fatal for
replicate-the-seed"*. The same argument applies to the CPU across build variants, and had not been
stated.

**How much it matters depends on a design question that is Jahni's, not the audit's:**

- **If listen-server only, one binary per platform, and clients never regenerate authoritative
  geometry** — this is a non-issue. Ship as is.
- **If a dedicated server on Linux and Windows clients both regenerate terrain and compare** — this
  is a real desync source, and it will present as rare, unreproducible, geometry-only divergence:
  approximately the worst bug class to diagnose.

**Calibration, so this isn't over-feared.** In 20,000 Maze samples, **zero** crossed the isosurface
under a 1-ULP perturbation. Divergence would therefore be occasional *single-voxel* surface
differences, not visibly different terrain — sub-voxel, near-certainly imperceptible for
collision-vs-visual mismatch. The case that would genuinely bite is **topological**: a cave
pinch-point that connects on one build and not the other. Rare — but "rare and unreproducible" is
the expensive kind of rare.

**Even `Precise` everywhere would not buy guaranteed cross-platform bit-identity.** `FMath::Sqrt` is
IEEE-exact and `VoxelNoise`'s hash-gradient core is integer + basic arithmetic, so those are safe.
But `FMath::Sin`/`Cos` (disturbance bridge/ridge angles) route to platform libm, which is not
bit-standardised across OSes. Aligning the FP model closes the large gap, not every gap.

**The knob, if it turns out to matter:** `ModuleRules.FPSemantics = FPSemanticsMode.Precise` in
`VoxelForge.Build.cs`, module-scoped. Note it would *align Windows with every other platform's
default* rather than being a one-sided cost. **Still do not do this speculatively** — the density
path is the plugin's hot loop, precise semantics block exactly the vectorisation and contraction
T2.a's SIMD noise work was chasing, and the cost is unmeasured. Decision needs a profile in hand and
a confirmed cross-platform requirement.

**Verification, when it becomes relevant:** the cross-build claim above is *inferred*, not measured —
no Linux build has been made. The cheap decisive test is to compile the plugin once with
`FPSemantics = Precise` on Windows and re-run `VoxelForge.OpStack.MazeEquivalence`: if the residual
454-sample difference vanishes, the FP model is confirmed as the sole cause and the cross-toolchain
risk is real. That is one build, and it settles it.

---

### C10 — The op-stack ULP residue: ~~PARKED~~ **CLOSED PERMANENTLY**, 2026-07-27

> # ✅ SOLVED, 2026-07-27 — and the cause was `/fp:fast`, exactly as hypothesis 3 said.
>
> **Setting `FPSemantics = Precise` (see `§C9`) made both `MazeEquivalence` and `SlabEquivalence`
> report BIT-IDENTICAL.** The residue is gone — not tolerated, *gone*.
>
> **So hypothesis 3 had the right mechanism and every isolation experiment built on it was doomed.**
> Under `/fp:fast` the compiler may reassociate and contract *based on surrounding context*, with
> **no single isolable axis** — which is precisely why five carefully-designed one-variable tests
> (FVector round-trip, transcription, cross-TU, inlining, const-vs-runtime) all came back negative
> while the difference stayed. There was no variable to find. Removing the *permission* removed the
> difference.
>
> ### The lesson, and it is not the one I expected
>
> **The answer arrived for free, from work done for an unrelated reason.** Nobody solved C10; C9 got
> fixed because Jahni wants Linux/Windows cross-play, and C10 fell out of it. Six more builds spent
> hunting would have found nothing, because the thing that resolved it was a *build setting nobody
> was looking at* while I was busy bisecting source code.
>
> **The decision to stop was therefore right on its own terms and right in hindsight** — the
> information was not obtainable by continuing along that path at any price. Park a question whose
> every consequence is measured and benign; it may well be answered later by something else.
>
> **What this changes going forward:** ports can now aim for and *achieve* bit-identity, so the
> equivalence tests are much sharper instruments than they were — any diff at all is now a real
> finding rather than noise to be graded. The ULP-grading machinery in both tests is kept, because it
> is what would tell us if this ever regresses.

**Status: accepted and closed by decision (Jahni), not by explanation.** Do not reopen this without
reading the whole entry — five hypotheses have already been measured and refuted, and re-deriving
them costs a build each.

**The observation.** `VoxelForge.OpStack.MazeEquivalence`: the ported Maze operator stack differs
from `GetMazeDensity` on ~2% of samples (454/20000) by 1-2 ULP. Deterministic — same samples, same
delta, same coordinates on every run.

**What is PROVEN by measurement, and is the reason this is benign:**

- **Zero isosurface crossings out of 20000.** Not one triangle would move. The two are
  *geometrically identical*.
- **The SDF is reproduced BIT FOR BIT** — 126/126 of the mismatches, and `stack SDF != verbatim SDF`
  counted unconditionally came back **0**. So the lattice sweep, the edge hashes, the `{-1,0}³`
  node set and `VoxelSDF::Capsule` are all exactly correct. The port has no logic error in the part
  that shapes the world.
- The entire difference is born in the final SDF→density conversion, amplified because `Blend - Sdf`
  cancels catastrophically at the edge of the blend shell.

**What was tested and REFUTED** (each cost a build; listed so nobody repeats them):

| # | Hypothesis | Refuted by |
|---|---|---|
| 1 | `FVector` float→double→float round-trip in the noise coords | identical result after the change |
| 2 | A transcription slip in the roughness window / carve blend / octaves | a four-stage bisect: residue survives into `corridors + carve ONLY` |
| 3 | `/fp:fast` reassociating across **translation units** | three-way test: generator TU == test TU exactly (0 differ) |
| 4 | Different **inlining context** (virtual call vs straight-line) | `FORCEINLINE` vs `FORCENOINLINE` in one TU: 0 differ |
| 5 | **Compile-time-constant** `Blend` vs runtime member | const and runtime forms bit-identical to each other; both miss the verbatim on the same 126 |

**Where that leaves it.** Two carve implementations, character-identical, in the **same translation
unit**, fed a **provably identical** input, produce outputs differing by 1 ULP on 126 of 5000. For
deterministic code that is only possible if they compile to different instruction sequences — which
is exactly what `/fp:fast` permits, based on surrounding context, with no single isolable axis. So
hypothesis 3 was right about the *mechanism* and wrong about every clean variable proposed for it.

**The one experiment that would settle it** is building this module with
`FPSemantics = FPSemanticsMode.Precise`. **It is blocked**: doing so costs VoxelForge the engine's
shared PCH and exposes ~30 missing includes across seven files (see the note in `VoxelForge.Build.cs`).
Clearing that IWYU debt is worth doing on its own terms; it is not worth doing to chase 1 ULP.

**The operational rule that DOES matter, and is the real takeaway:**
**never run the archetype `switch` and the operator stack in the same world, and never compare their
outputs for equality.** A half-migrated strate would produce a seam. This is **not** a client-desync
risk — within one binary the field is proven bit-pure across threads and query order
(`VoxelForge.Determinism.DensityPurity`) and every peer runs the same path. The genuine
cross-platform concern is `§C9`, which stands independently.

---

### Threading — what's *right*, for the record

Worth stating plainly, because it's the part that's easy to get wrong and this doesn't:

- `ProcessQueue` is correctly `Mpsc`, with the failure mode documented at the declaration.
- The `FTaskGuard` RAII decrement covers every early-exit path in `LoadTile`.
- Epoch carrying is consistent across all four async paths (tile gen, deco march, volume fill, band re-gen).
- `DiffLayer`'s `FRWLock` + lock-free `bHasAnyMods` fast-reject + per-(chunk,version) snapshot is a genuinely
  good piece of engineering, and the comment records the AV it fixed.
- `BuildCellSpawns` is correctly `static` — no implicit `this` on the worker.
- `VoxelGenLOD::OctaveBias` is `TGuardValue`-scoped per tile, so deco snapping and volume fills can't
  inherit a stale bias.

---

## 2. Performance & algorithm choice

### Is Marching Cubes still the right call in 2026? — **Yes, for this game.**

- **Transvoxel** ([transvoxel.org](https://transvoxel.org/)) remains the canonical answer to LOD seams,
  and `fable-idea` already schedules it correctly ("whenever LOD cracks become the loudest remaining
  flaw"). Your skirts are a legitimate substitute: they cost extra verts and some overdraw on boundary
  contour edges, but they're ~80 lines instead of a transition-cell rewrite, and they work for *any*
  level delta rather than only ±1.
- **Surface Nets / Dual Contouring** would cut triangle count meaningfully and are faster per chunk, but
  naive Surface Nets can't hold a sharp 90° feature and DC brings QEF solving + self-intersection
  handling. You'd trade a rewrite for a benefit you aren't currently bottlenecked on. Correct to skip.
- **GPU meshing** — `fable-idea` rejects it for readback latency, CPU-side collision, and cross-GPU float
  determinism. All three are still true, and the last one is fatal for a game whose MP model is
  "replicate the seed, regenerate identically on every peer". Right call, right reasons.

**The verdict is: your mesher isn't the problem.** T1.a–f and T2.a–e genuinely took per-tile generation
into diminishing returns. The remaining cost lives elsewhere (C3, C7) and in the scaling cliffs below.

### Scaling cliffs nobody has hit yet

**`BuildChunkCache` is O(N²) in rooms, and N grows quadratically with the tunnel/spacing ratio.**
`PickNeighbor` is O(N) per room and the connection loop is O(N²), over the COLLECT box which spans
`2·MaxTunnelLength + MaxInfluence`. So room count `N ≈ ((2L + I)/S)²` and the graph build is
**O((L/S)⁴)**:

| `MaxTunnelLength` | `RoomSpacing` | ≈ rooms in COLLECT | pair iterations |
|---|---|---|---|
| 200 (default) | 80 (default) | ~40 | ~800 |
| 300 | 60 | ~140 | ~10,000 |
| 400 | 40 | ~500 | ~125,000 |

Per cache rebuild, per worker. Amortised over 32,768 voxels it's survivable at defaults; at row 3 it
isn't. Worth a comment on `MaxTunnelLength` and a soft clamp.

**`AnyPassageNearBox`** walks every passage per tile with no spatial index. Fine at 10-20 passages; grows
linearly with `TotalStrates × Connections`.

**`FindSlotIndexForChunkZ`** is a linear scan called extremely often — per lattice-Z in `ClassifyTile`,
per archetype param getter, on every `GetDensityAt` chunk change. The comment acknowledges it ("with
~10-20 strates this is fine"). It is. But it's the classic death-by-a-thousand-cuts profile entry.

**`GetDominantBiomeAt`** is fully uncached: it builds an `FBiomeContext` (heap-allocating a `TArray`) and
runs the warped Voronoi + up to 2 `ClassifyBiomeAtSite` (4 fBM evals). `AtmosphereManager::UpdateForPlayer`
calls it **every Tick**, unconditionally. Small, but it's a per-frame game-thread allocation for a value
that changes maybe once a minute.

### The external development you should know about: **RealtimeMeshComponent 6.0**

You're on **RMC 5.3.2**. [RMC 6.0.0 shipped June 2026](https://triaxis.games/realtime-mesh/) with:

- **Runtime Nanite** — "real cluster groups, full LOD DAG, per-page streaming. No cooked bake, no
  `UStaticMesh` round-trip."
- **Lumen card generation** + **distance field support** (Pro tier, $49 one-time).
- UE 5.2–5.7 support (you're on 5.7).

This matters more to VoxelForge than to most plugins, because it potentially subsumes **three separate
hand-built systems**:

| Your system | What RMC 6.0 offers instead |
|---|---|
| Clipmap levels + `CoarseTileCells` + `LODOctaveDrop` + skirts | Nanite's own LOD DAG, no seams by construction |
| F18 sheet ring (`GenerateSheetMesh`, XY hole, band re-queue) | far-field falls out of Nanite streaming |
| Density volume + raymarched mini-sun shadows (currently gated off) | runtime Lumen cards + distance fields |

I am **not** saying "rewrite on Nanite" — runtime Nanite on procedurally-remeshed geometry is new, and
digging (constant re-meshing) is the adversarial case for cluster building. But this is the single
biggest change in the landscape since your architecture was designed, and it argues strongly for a
**timeboxed spike before building any more LOD machinery**. Measure: build time per tile, re-mesh cost
on carve, and whether skirts/sheets become unnecessary.

(For reference on the alternative path: [Voxel Plugin 2.0](https://docs.voxelplugin.com/) now targets
5.6/5.7 and its [VoxelCore](https://github.com/VoxelPlugin/VoxelCore) module is open-source — worth
knowing exists, not worth switching to. Your strate/archetype model is the whole game; theirs isn't.)

---

## 3. Architecture & maintainability

### The structural risk: ~30 hand-rolled `thread_local` caches

The density field is a *pure function by convention*, and that convention is enforced by roughly thirty
hand-written memo caches, each with a hand-written invalidation key:

`GSurfColCache` · `CP_Chunk`+9 param slots · `SDFCache`+`CachedSMinX/Y`+`CachedStrate`+`CachedSeed` ·
`SI_ChunkZ`/`SI_Version` · `DiffSlots[64]` · `CH_*` chasms · `BR_*` bridges · `RG_*` ridges · `SC_*` slab
columns · `MZ_*` maze edges · `VS_*` shafts · `FI_*` islands · `OC_*` oracle · `BM_*` biome material ·
`TC_BiomeCache` · `Slots[2]` · `SL_*` passage shortlist · the mesher's `VertexMap`/`DensityGrid`/
`SurfColMemo`/`VertexClasses`/`GroundTris`/`CapTris`/`SheetCols`/`GroundIdx`/`CapIdx`.

Every one is individually justified and individually documented. Collectively they mean **the
correctness of the entire world rests on ~30 key lists each enumerating every input**, audited by hand.
Two are provably incomplete (C2). This isn't a bug count — it's an *unbounded bug surface that grows
with every feature*, and the failure mode is the worst kind: a seam or hole that appears only under a
particular thread/edit interleaving.

The existing mitigation, `ValidateDeterminism`, is the right instinct but a narrow test: one axis (X
boundary), near the player, one alignment pair, **on the game thread**. It would not have caught C2
(worker-thread caches) or C8 (origin ring).

**What would actually help**, in rough order of value-per-hour:

1. A `VF_CACHE_KEY(...)` macro that bundles `(coord, seed, layoutVersion)` so a new cache can't forget
   the standard fields.
2. A **debug-only "no-cache" mode** (`#if VF_VALIDATE_PURITY`) where every memo is bypassed, plus an
   automation test that samples N random points in both modes and asserts bit-equality. That converts
   *all* "bit-identical, I promise" claims — of which the docs make dozens — into a machine check.
3. Extend `ValidateDeterminism` to run its samples across **multiple worker threads** in shuffled order.

### No tests, no automation

Zero test files. UE ships an automation framework you're not using. Three tests would cover most of the
risk surface:

- **Density purity**: sample 10k points, shuffle the query order, re-sample, assert bit-equality.
- **`ClassifyTile` soundness**: for random tiles, if the verdict is `AllSolid`/`AllAir`, brute-force the
  lattice and assert every sample agrees. A false verdict is a *hole* — this is the highest-consequence
  function in the plugin and it's validated only by reasoning.
- **`DiffLayer` under contention**: N reader threads + a writer, assert no crash and monotonic version.

### Function size (the open item that stays open)

`REVIEW_FINDINGS.md` has listed these splits as open through three passes:

| Function | Lines | Note |
|---|---|---|
| `GetDensityWithParams` | ~1,080 | listed as "~600-1000 L" — it has grown since |
| `BuildChunkCache` | ~640 | |
| `UpdateChunksAroundPosition` | ~300 | + 5 nested lambdas, 3 of them capturing by reference |
| `BuildCellSpawns` | ~350 | contains a **175-line nested lambda** (`PlaceAtCrossing`) |
| `ClassifyTile` | ~200 | |

An item that survives three review passes isn't going to get done voluntarily. Either accept it
explicitly (write "we are keeping these monolithic, here's why" in `REVIEW_FINDINGS`) or bind it to the
next feature that touches each one. Leaving it as a permanent open checkbox just makes the checklist
lie.

### Smaller structural notes

- **`FStrateGenerationParams` is a 74-field god-struct**, and blend correctness depends on remembering
  to add every new field to `VF_STRATE_PARAM_FIELDS`. The X-macro was the right fix; make drift a
  *compile* error by putting `static_assert(sizeof(FStrateGenerationParams) == N, "add the new field to
  VF_STRATE_PARAM_FIELDS")` right next to it.
- **Chunk-quantised param blending.** `GetGenerationParams` computes the Gradient/Interleaved blend
  `Alpha` from `ChunkCoord`, so within a transition band the density field has a **step at every chunk
  boundary**. MC samples corners from both sides, so it won't tear, but small ledges at chunk borders in
  Gradient zones are expected behaviour, not a mystery, if you ever see them.
- **Dead knobs still shipping**: `ViewDistanceXY` (only `Up`/`Down` are read), `CeilingViewMultiplier` and
  `CeilingBandChunks` (the wide-ceiling system was removed by the clipmap), `DensityVolumeMaxTasks`
  (deprecated in its own tooltip). Each is a lever a designer will pull and get nothing.
- **`EVoxelPassageType` vs `EVoxelPassageStyle`** — two overlapping passage-shape enums, both live.
  Already open in `REVIEW_FINDINGS`; still open.
- **Leftover tutorial scaffolding** in `VoxelWorld.h/.cpp`: `// CHUNK MANAGEMENT - YOU IMPLEMENT THESE`,
  `// This one is tricky with Unreal's API, so I'll give you more help:`, and a 20-line `STEPS: 1. Try to
  dequeue...` block inside the now-finished `ProcessPendingChunks`. Cosmetic, but it's the first thing a
  reader hits.
- **`.uplugin` metadata**: `"CreatedBy": "You"`, `"Description": "...built from scratch to learn"`.

### The documentation, honestly

The prose is genuinely excellent — better than most commercial plugins. `ARCHITECTURE §8.10` in
particular is a real asset: it records *why* each optimisation exists and what regressing it costs.

Two problems:

1. **The numbers have drifted.** `CODEMAP.md` header says *"~8,300 lines of C++ across 25 files"*;
   reality is **~16,400 across 30**. §3.5's line anchors are badly stale (`LoadChunk :445` → actually
   ~1336; `ApplyModification :691` → ~1816). Since `CLAUDE.md` already instructs "trust symbol names over
   line numbers", I'd **delete the line column entirely** — it's a maintenance tax that buys nothing and
   actively misleads.
2. **The comment density is optimised for one kind of reader.** Blocks like the F17 row in
   `ARCHITECTURE §8.1` (a single table cell running ~40 lines, narrating v1 → v2 → v3 with rationale and
   quoted feedback) are superb context for an AI collaborator picking the file up cold, and a genuine
   liability for a human trying to find the code. You've made a real trade here; it's worth making it
   knowingly. A `HISTORY.md` for the "we tried X, it failed because Y" narrative would let the source
   comments shrink to *what the code does now*.

---

## 4. Process — what I'd fix first

### P1 — Track the design docs. Today. ⚠️

```
.gitignore:  *  →  !/Source/  !VoxelForge.uplugin  !CODEMAP.md
```
`git ls-files` confirms **`ARCHITECTURE.md`, `fable-idea.md`, `REVIEW_FINDINGS.md`, `CLAUDE.md` and this
audit are all untracked.** `fable-idea.md` even says so in its own header — *"the strict-whitelist
`.gitignore` will ignore this file. Add `!fable-idea.md` if you want it tracked"* — and it never was.

These documents *are* the project's memory. Losing them loses more than losing the code, because the code
can be re-read and the reasoning can't. Two lines:
```
!*.md
```

### P2 — Stop batching three weeks into `tmp`

| Commit | Date | Content |
|---|---|---|
| `69fa73e` **tmp** | 2026-07-26 | **+3,903 / −1,029 across 20 files** — F17, F18, F19 anchors, F20 ph.1+2, companions, landmark merge, strate cut, sheet ring |
| `cb61c8b` potential perf regression | 2026-07-04 | |
| `6875614` Fix Decoration Placement | 2026-06-26 | |
| `e6cd852` Another pass | 2026-06-23 | |
| `db558d9` j | 2026-06-16 | |

Seven commits in seven weeks, and the message quality (`j`, `tmp`, `Another pass`) means even the
existing history isn't navigable. You don't need discipline theatre — one commit per *feature*, with the
feature's name in the subject, would be enough to bisect "which change broke seed 42".

This matters disproportionately *here* because determinism is the product. When a world stops matching,
"which commit changed the field" is the only question, and right now it's unanswerable.

### P3 — Reconcile the "pending build" backlog before adding anything

`fable-idea.md` and `ARCHITECTURE.md` currently carry, unreconciled:

- F20 **phase 1** — "CODE-COMPLETE, PENDING BUILD (2026-07-08)"
- F20 **phase 2** — "CODE-COMPLETE, PENDING BUILD (2026-07-08)"
- §8.14 biome full-param redesign — "code-complete, pending build"
- §8.15 F6 vertex palette — "C++ code-complete, pending in-editor build + the master material graph"
- `REVIEW_FINDINGS` perf pass 2 + batch 3 — "CODE-COMPLETE, pending build"

That's three weeks of unverified code stacked on unverified code, on a system where the failure modes
(seams, holes, stale caches) are *visual* and only appear in-editor. **The honest statement of project
state is: unknown for everything after 2026-07-04.**

Suggested order before any new feature:
1. Build. Fix compile errors.
2. Run `ValidateDeterminism` at several locations (including far from origin).
3. `bEnableDensityVolume = false` → trace → compare (C7).
4. Set `Seed = 1234567` → look (C1).
5. Live-edit a strate asset, regenerate, look for patches that kept old params (C2).
6. Commit, per feature, with real messages.

---

## 5. Priority list

*Re-ordered 2026-07-26 around the live 3D work.*

| # | Item | Cost | Why |
|---|---|---|---|
| 1 | **§6.1** — `ClassifyTile` guard for 3D caves | ~30 lines | **blocks the current feature**; a false `AllSolid` is an invisible, collision-less cave |
| 2 | **P1** — track the `.md`s (`!*.md`) | 2 min | irreplaceable if lost; the docs *are* the design record |
| 3 | **C7** — `bEnableDensityVolume = false` | 1 min | confirmed dead weight — lighting is deprecated |
| 4 | **§6.6** — branch the experimental 3D work | 1 min | restores a known-good world to diff against |
| 5 | **C1** — bound `SeedF` | 1 line + re-tune | silent terrain collapse on large seeds |
| 6 | **C2** — add `GetLayoutVersion()` to 3 cache keys | ~10 lines | closes "my edit didn't apply" |
| 7 | **§6.2** — keep 3D caves *placed*, not *fielded* | a design call | decides whether T1.d keeps its 44 % |
| 8 | **C4** — explicit no-player flag | ~5 lines | origin-standing / no-pawn stall |
| 9 | **C5** — unbounded joins on shutdown | ~20 lines | random PIE-exit crashes |
| 10 | Automation tests (purity, `ClassifyTile`, `DiffLayer`) | ~a day | `ClassifyTile` is now the highest-consequence function in the plugin |
| 11 | **P2** — per-feature commits | ongoing | determinism without history is a contradiction |
| 12 | **C3** — `PerlinNoise2D` off the SDF hot path | ~5 lines | dormant, but violates a stated invariant |
| 13 | **RMC 6.0 spike** (runtime Nanite / Lumen cards) | timeboxed | may subsume clipmap LOD + sheets + density volume |
| 14 | **C6** — diff-layer delta grid | a design pass | the scaling wall for the game's core verb |
| 15 | Tick the stale "PENDING BUILD" markers in the docs | 20 min | they currently misreport project state |
| 16 | Drop line numbers from CODEMAP §3; fix the header count | 30 min | the map misstates its own scale (8.3k → 16.4k) |
| 17 | Delete dead settings + tutorial scaffolding | 30 min | knobs that do nothing mislead |

---

## 6. Going 3D — what the current architecture will fight you on

*Added 2026-07-26 after Jahni confirmed the live direction: 3D density features — overhangs, caves
inside mountains, volumetric generation inside `SurfaceWorld`. This is the section that matters most
right now; everything above is maintenance by comparison.*

### 6.1 `ClassifyTile` will delete your caves. This is the one to get right first. ⚠️

T1.d proves a tile `AllSolid`/`AllAir` and **skips `GenerateMesh` entirely**. For `SurfaceWorld` the
proof is (`VoxelGenerator.cpp`, `TestColumn`):

```cpp
if (Z >= TerrainZ && Z <= CeilSurf) { bCanSolid = false; }   // air side
else                                { bCanAir   = false; }   // below terrain, or in the cap
```

So **any point below `TerrainZ` is treated as provably solid.** A tile entirely inside a mountain
returns `AllSolid`, emits no mesh, and never calls the density function. Carve a cave in there and:

- the cave's walls are **never meshed** — you get an unrendered void,
- there is **no collision** (level-0 collision is per-section, and there are no sections),
- and it is invisible until you enter it from a passage, at which point you fall through nothing.

The code comment states the rule exactly: *"A false `Mixed` only costs CPU; the code must NEVER emit a
false `AllSolid`/`AllAir` (that's a hole)."* This is the same failure that got T1.d **v1 reverted on
2026-06-26** — a global analytic ceiling bound that wasn't conservative.

The existing guards are the template — each kills one hypothesis, cheaply, per tile:

| Guard | Kills | Mechanism |
|---|---|---|
| `AnyPassageNearBox` | `AllSolid` | sphere-vs-AABB over the passage list |
| origin spine | `AllSolid` | circle-vs-box in XY |
| chasm disturbances | `AllSolid` | `ChasmDensity > 0` on the strate |
| bridges / ridges | `AllAir` | density > 0 on the strate |
| `HasAnyModInChunkRange` | both | one key walk of the diff map |
| F20 overhang | both, in a band | `(TerrainZ, TerrainZ + OverhangMargin]` ⇒ `Mixed`, upward only |

**Every new 3D feature needs one of these before it ships.** For hash-placed cave systems that means a
per-tile shortlist exactly like `EvaluateModifierSDF`'s passage shortlist: collect the feature bounds
that reach this tile once, and if the list is non-empty, `bCanSolid = false`. `fable-idea`'s own F20
phase-3 GOTCHA already says this for spikes/holes — it applies verbatim to caves.

> **Test that catches it:** generate a mountain with caves, then stand outside and fly the camera through
> the mountain volume. Any cave that renders from inside a passage but shows nothing when approached
> through rock is a false `AllSolid`.

### 6.2 The T1.d economics invert as caves get more volumetric

The 2026-07-05 trace justified T1.d with: **84 % of `GenerateMesh` calls produced empty tiles**
(83,925 gens vs 13,227 meshes, ~500 s of 617 s worker CPU wasted), and shipping it cut worker CPU 44 %.

The bulk of those `AllSolid` tiles **is deep rock below `TerrainZ`** — precisely the volume "caves inside
mountains" occupies. Every tile a cave touches must now generate. So there's a direct, quantifiable
tension:

- **Bounded caves** (hash-placed systems with bounding volumes, like rooms/tunnels already are) wake only
  the tiles they actually intersect. The shortlist proves the rest of the mountain still solid. T1.d keeps
  most of its win.
- **A global 3D noise field** (`if (noise3D(x,y,z) > t) carve`) is unprovable *everywhere* below terrain →
  every deep tile becomes `Mixed` → you hand back a large slice of that 44 %, plus you now mesh and cook
  collision for tiles that are 99 % solid rock.

**Recommendation: make 3D caves placed, not fielded.** Same discipline as `FCachedRoom`/`FCachedTunnel` —
they exist at hash-determined locations with known bounds. That keeps the classifier effective, makes the
shortlist guard trivial to write, and gives you authored control over cave density per biome. It's also
the only version that stays cheap at the render-distance ring.

### 6.3 Do not put Z-dependent data in `FSurfaceColumn`

`FSurfaceColumnBox` is keyed `(XY box, StrateKey, Seed)` with **no `ChunkZ`**, held as a 6-box LRU, and
deliberately **shared down the entire vertical chunk stack** — that's the whole T1.a win (the heightfield
was being recomputed once per altitude). `ARCHITECTURE §8.10` states it: *"ZERO Z dependence... Don't
re-introduce a ChunkZ key."*

So the rule for every new 3D feature is:

- **XY-pure data** (a per-column gate, amplitude, direction, a cave-system ID) → cache on `FSurfaceColumn`.
- **Z-dependent evaluation** → do it per-voxel in `SurfaceDensityFromColumn`, reading the cached column.

Your F20 phase-2 overhang is the correct template and worth copying deliberately: `OverhangAmp` (strength ×
slope-gate) and the unit uphill `(DirX, DirY)` are resolved **once per column** in `ComputeSurfaceColumn`;
the actual warped-terrain union is per-voxel. Anything that violates this silently corrupts every chunk in
the vertical stack, and `ValidateDeterminism` — which samples along an **X** boundary — would not catch it.

### 6.4 Window invariance: pick the cheap pattern where you can

Two existing precedents, and the difference is worth being deliberate about:

- **`Maze`** — edge identity is a pure hash of `(lower node, axis)`. Two adjacent chunks *cannot* disagree.
  No cache, no COLLECT region, no seam risk, zero invariant maintenance.
- **`BuildChunkCache`** — because tunnel existence depends on a *connectivity decision over a neighbourhood*,
  it needs the two-region COLLECT/STORE split (§8.4), and that invariant is delicate enough to have its own
  documentation section.

If your cave systems need connectivity (a cave network that must be traversable), you inherit the second
pattern and its COLLECT-margin discipline. If each cave is independently placed, use the first — a pure
`hash(cell, seed)` placement with per-voxel SDF evaluation and no cross-chunk decision at all.

**Pick the Maze pattern unless connectivity is a gameplay requirement.** The complexity delta is large and
it's all seam-risk.

### 6.5 Smaller things that will bite

- **Route new per-voxel volumetric noise through `VoxelGenLOD::Eff(N)`.** That's the T2.b contract: per-voxel
  3D noise gets the LOD octave drop, XY-field noise deliberately does not. New 3D code that calls
  `FractalNoise3D(..., 3)` directly silently opts out of far-tile savings.
- **LOD-gate the expensive 3D ops.** Your own note on F20 phase 2 flags it: *"KNOWN v1 LIMIT: applies at ALL
  LODs (may alias far) — gate to fine tiles later."* With one op that's a wart; with several it's a far-field
  cost multiplier. A `Step > N` early-out per volumetric op is a few lines and compounds.
- **F17 already handles cave roofs correctly** — the surface class is semantic, not geometric: down-facing but
  *below* `TerrainZ` ⇒ ground/rock, not sky-cap. This was designed for exactly your current case and needs
  nothing. Good call at the time.
- **The F18 sheet ring won't show caves** — sheets are two heightfields, so carved features don't exist there.
  Already an accepted trade-off; just don't expect a cave mouth to be visible at render-distance.
- **`SurfaceDensityFromColumn` is now the hot path**, not the SDF morphology. The overhang block already
  re-runs `SampleSurfaceStructuralZ` per lip voxel. Each new volumetric op that re-samples structural height
  per voxel stacks on that. Budget it consciously — the per-column cache saved you ~33×, and per-voxel
  structural re-evals spend it back.

### 6.6 Since it's experimental and uncommitted

You said the tree is uncommitted *because* the 3D work is experimental. That's a reasonable instinct pointed
at the wrong tool — experimental work is exactly what branches are for:

```
git switch -c 3d-density        # experiment freely, commit noisily
git switch main                 # a known-good world is always one command away
```

The specific thing you lose right now: when a seed stops matching or a hole appears mid-experiment, there
is no known-good state to diff against, and the 3D features are the *highest*-risk changes in the project
for exactly that failure mode (§7.1). A branch costs nothing and gives you the bisect back.

---

## 7. What I'd tell someone joining this project

The generation core is strong and the perf work is honest and measured — the person who wrote this knows
what they're doing and has the traces to prove it. The weakness is **everything around verification**:
no history you can bisect, no tests, design docs outside version control, and a habit of stacking
features on top of unbuilt features. Nothing in the code list above is hard to fix; the process items
are the ones that decide whether the next three weeks are as productive as the last three.

*Sources consulted for the external comparison: [transvoxel.org](https://transvoxel.org/) ·
[triaxis.games/realtime-mesh](https://triaxis.games/realtime-mesh/) ·
[TriAxis-Games/RealtimeMeshComponent](https://github.com/TriAxis-Games/RealtimeMeshComponent) ·
[docs.voxelplugin.com](https://docs.voxelplugin.com/) ·
[VoxelPlugin/VoxelCore](https://github.com/VoxelPlugin/VoxelCore) ·
[UE 5.7 release notes](https://www.unrealengine.com/news/unreal-engine-5-7-is-now-available)*