VoxelForge/OPSTACK-HANDOFF.md

# Handoff — VoxelForge operator stack, 2026-07-28 (end of day 3)

> Paste the block below into a fresh session. Everything it refers to is on disk and in git.

---

You're picking up an agreed refactor of the VoxelForge UE5 voxel plugin, on branch `experimental`
(already checked out — do not create another). I'm Jahni. Design and progress are written down so you
don't re-derive them.

## Read first, in this order

1. **`CLAUDE.md`** — project rules. **Rule #1 is absolute: never build, compile, or run the editor.**
   I build everything myself. When code is done, stop, say "ready to build", list the likely
   compile-error spots, and wait.
2. **`OPSTACK-PROGRESS.md` — THE LAST ENTRY FIRST.** Append-only log of what is built vs merely
   written. This is the resume point.
3. **`OPSTACK-PLAN.md`** — the plan. **§2.6.1 is the current acceptance bar** and supersedes §2.6.
4. **`OPSTACK-DECOMPOSITION.md`** — all 8 archetypes broken into ops. §2 TunnelNetwork (the one in
   progress), §0.2 the worm bound, §7 islands, §5 SurfaceWorld.
5. **`AUDIT-2026-07.md`** — §C9's library half is the top open risk. **§C10 is SOLVED — don't
   reopen.** §C1 was reopened and re-closed on 2026-07-28; §C2 has a new *suspected* item worth
   verifying before acting on.
6. **`CODEMAP.md`** — navigation. Trust symbol names over line numbers.

## Where things stand — 6 of 8 ported and wired, the 7th half-ported, 13 tests green

| Archetype | State |
|---|---|
| `Maze` | ✅ ported, bit-identical, wired |
| `FlatPlain` + `CrystalChamber` | ✅ **one op for both**, bit-identical, wired |
| `SurfaceWorld` | ✅ ported incl. **biome blending**, bit-identical, wired |
| `VerticalShafts` | ✅ ported, bit-identical, wired — 3 ops reused from Maze unchanged |
| `FloatingIslands` | ✅ ported, bit-identical, wired — the stack that runs **backwards** |
| `TunnelNetwork` | 🔶 **STAGE A of 3 done and verified.** Not wired — see below |
| `Underwater` | ❌ TunnelNetwork + a water flag; folds in at stage C |

Everything is behind `UVoxelStrateDefinition::bUseOperatorStack`; the ported list lives **only** in
`UVoxelStrateManager::UsesOperatorStackForChunk`. Un-ported archetypes ignore the flag, so ticking it
anywhere is harmless.

## TunnelNetwork is staged — read this before touching it

`GetDensityWithParams` is ~1080 lines: 13 detail modifiers, a two-region cache, worms, and a per-room
op override. Porting it whole before anything can be checked would be ~600 unverified lines on top of
~200 — the `AUDIT §P3` pattern this refactor has dodged seven times. So:

- **Stage A — DONE, bit-identical over 6000 samples.** Vertical scale · base rock · cave warp · room
  graph (+ pits + chimneys) · carve · worms · structural post. **7 ops.**
- **Stage B — NEXT.** The 13 detail modifiers of `STEP 4b–4h`, gated on `Sdf < SDFBlendRadius·3`.
  They insert between the carve and the worms, so the op-count assertion in the test must move.
- **Stage C.** The per-room op override (`§2`'s option (a)), the `Underwater` water flag, and only
  then does `UsesOperatorStackForChunk` return true for either.

**Why stage A is verifiable while incomplete:** every detail modifier is amplitude-gated, and
`FStrateGenerationParams` already defaults all of them to zero. Zeroing `SurfaceRoughness` (the one
exception) sends the *original* down exactly the path stage A ported. Stage B's test will do the
reverse — turn them on one group at a time.

**⚠️ The decision that must not be undone:** `FRoomGraphSource` **CALLS** `BuildChunkCache` /
`EvaluateSDFCached`; it does not transcribe them. That is where `ARCHITECTURE §8.4`'s two-region
window-invariance discipline lives, and a transcription would *fork* it — with the fork "validated"
by a test that compares it to the original. Only the ~60 lines of glue are transcribed.

## Three things Phase 2 settled that were not in the original design

1. **Height space** (`VoxelHeightOp.h`) — a *second operator family*. SurfaceWorld's terrain ops read
   and write an **altitude**, not a density: no input Z, XY-pure per column. They do not fit
   `IVoxelDensityOp`. §0.1 found density needed a second *channel*; this found terrain needs a second
   **space**. Bonus: a height stack *cannot* hold Z-dependent data, because there is no Z in the
   signature — `AUDIT §6.3`'s hazard became a type error instead of a convention.
2. **`IVoxelBiomeField`** — ops depend on a *capability*, never on `UVoxelGenerator`. The adapter
   (`FGeneratorBiomeField`) lives in `VoxelGenerator.cpp`. This is what lets ops become assets in
   Phase 3; an op holding a generator pointer never could.
3. **`FRAME` ops are RETIRED — porting all three candidates killed the idea.** `CaveWarp`'s scope is
   exactly one operator (pits/chimneys explicitly read *unwarped* coords, the thing §2 called the
   fiddliest in the decomposition — inside one op it evaporates). `VerticalScale` is `Z / Scale`, a
   one-line pure function. The island warp was already local. **Zero frames from three candidates:**
   not missing infrastructure, one idea seen three times from a distance. Marked retired in §1.

## What is left, in the order I'd do it

1. **Stage B** — the 13 detail modifiers. The bulk of the remaining lines.
2. **Stage C** — per-room op override + `Underwater` + flip both on in `UsesOperatorStackForChunk`.
   **The override is NOT optional polish:** pits, chimneys and columns exist *only* through a
   per-room `UVoxelTerrainOpDefinition` (`BuildChunkCache` opens its bake with
   `if (!CR.RoomOp) continue;` and then reads a *fresh* param struct). No override ⇒ no pits, ever.
3. **The worm amplitude cap (`DECOMPOSITION §0.2`)** — the largest single perf item in the plan.
   TunnelNetwork proves **0 of 40** tiles today because a fielded-noise carve has no spatial bound.
   But its amplitude is bounded and trivial (`t ∈ [0,1]`, `Mask ∈ [0,1]` ⇒ at most `WormStrength`
   toward air), and that bound already has a home in `FWormFieldSource::MaxCarveAmplitude()`. It
   needs a fold that carries **numbers**, not just directions.
4. **`ClassifyTile` still uses hand-written guards.** `ClassifyBox` is brute-force verified per
   archetype but **nothing consumes it in production**. That is where measured tile-skipping turns
   into frames — arguably the biggest single win still on the table.
5. **PERF — parked by Jahni until the transition is complete.** The op path is measurably slower.
   One cause found and fixed (the column memo discarded itself every chunk). Remaining suspects in
   order: the hashed column lookup vs `GSurfColCache`'s direct-indexed box, then per-voxel virtual
   dispatch. **Measure before optimising** — that is the C10 lesson.
6. **`AUDIT §C9` library half** — `sinf`/`cosf` are not IEEE-754 specified, so MSVC's CRT and glibc's
   libm can differ. Currently **0 samples within 1e-6 of the isosurface**, i.e. no measured risk. The
   real fix, if ever needed, is a deterministic in-house sin/cos. Also: run `CrossPlatformDigest` on
   Linux, compare the SHAPE digest, pin it.
7. **`AUDIT §C2`, suspected** — `GetGenerationParams` blends params across Gradient transitions, so
   two chunk Zs inside one strate may hold different params with the same XY box, strate index and
   seed ⇒ the SDF cache never rebuilds ⇒ the lower chunk gets the upper chunk's rooms. **Verify the
   premise before acting** (does Gradient blending actually vary within a strate?). The op stack does
   not inherit it — its key folds in a params CRC.
8. **VerticalShafts proves 0 of 60 tiles.** Pessimistic, not wrong: `EffectOverBox` returns
   `CarveOnly` whenever any shaft is within a `Spacing*1.6` halo instead of testing real connector
   capsules. Lost CPU, never a hole.

## ⚠️ IF YOU ARE RUNNING UNATTENDED — read this section before starting

Jahni may start this session and leave, then have you shut the PC down when you're done. If so:

**You cannot build, and nobody will build for you during this run.** Rule #1 still holds absolutely.
So everything you write stays unverified until he returns — which is exactly the `AUDIT §P3` pattern
("unverified code on top of unverified code") this refactor has dodged seven times. You cannot avoid
it while he is away. **What you CAN do is shape the work so a single build afterwards diagnoses it
cheaply.** That is the whole job of this section.

### The rules that replace "build after each step"

1. **One commit per group below. Never bundle two.** Jahni reverts by group, and a failed build must
   bisect to a group rather than to 700 lines. Name the group explicitly in the subject line.
2. **Every commit leaves the tree coherent.** No half-written op, no dangling brace, no factory
   declared without a definition. Assume the next thing that happens is a compile.
3. **Transcribe literally. Do not improve anything.** With no test feedback, a "cleanup" is an
   unfalsifiable guess. Keep the original's operation order, its constants, its `FVector`
   round-trips, its odd `FMath::Max` floors. If something looks wrong, **write it down in the
   progress log and port it as-is** — that is how `§C1` and the `MinDivisor` split were both found
   without breaking anything.
4. **Update the test in the same commit as the code it covers**, including its coverage counters. Do
   not leave "I'll add the test after" — after is a build away.

### The work queue, in order. Stop at the first hard stop.

- **B1 — Surface roughness** (`STEP 4b`, ~130 lines). Density-space variant: a *different op* from
  `FSdfRoughnessMod` (quadratic fade, anti-fill clamp, 4 noise types). See `DECOMPOSITION §1`.
- **B2 — Terrace · LayerLines · Ribbing** (~150 lines). The three "sedimentary" remaps.
- **B3 — Overhang · Cliff · Scallop · Arch** (~210 lines).
- **B4 — Columns · Domes · Pinch · FloorBias** (~190 lines). Columns read `SDFCache.Columns`, so this
  group needs a Column op in the test's room pool — and the stage-A guard that *errors* on
  `TotalColumns > 0` must move to this commit, not before it.
- **B5 — the gate itself.** All of B1–B4 live inside `if (bNearCaveSurface)`, i.e.
  `Sdf < SDFBlendRadius·3 && Sdf < FLT_MAX`. Decide deliberately whether that is one scoping wrapper
  or a repeated early-out in each op, write down which and why, and make the test prove a voxel
  *outside* the gate is untouched.

After each group, extend the test: turn that group's amplitudes ON in `EnableTunnelFeatures`, add a
coverage counter proving the group actually fired (**not** just that its param is non-zero — see the
pit/chimney lesson below), and move the op-count assertion.

**⚠️ The one subtlety that lets B happen before C.** Inside `if (bNearCaveSurface)` the original
*shadows* `Params` with `LocalTerrainParams` — a copy with the nearest room's terrain op applied — and
**all 13 modifiers read the shadowed copy**. Porting them to read strate-level params is therefore
equivalent *only while no room carries a detail-type op*. The test's room pool is Pit/Chimney only,
and `ApplyTo(Pit)` writes just the four pit fields, so the two are identical today. **Keep it that
way until stage C**: the moment a `Terrace` op enters the pool, the ported group must read the
per-room value or the equivalence breaks — and that break is the correct signal, not a bug.
(B4's Column op is safe: `STEP 4d` reads `SDFCache.Columns` from the bake, never the shadowed params.)

### 🛑 HARD STOPS — do not cross these unattended

- **Do NOT flip `TunnelNetwork` or `Underwater` on in `UsesOperatorStackForChunk`.** That points the
  live world at an unverified path. It waits for a green build, always.
- **Do NOT start stage C (the per-room op override).** It is the one piece with genuine design
  freedom (`§2` offers two options and argues for (a)), and design without feedback is where an
  unattended run does damage. **Instead, if you reach it: write the design up in
  `OPSTACK-DECOMPOSITION §2` and stop.** A reviewed design is worth more than unreviewed code.
- **Do NOT start the worm amplitude cap / numeric intervals.** It changes the fold contract that all
  13 green tests depend on. It deserves a build cycle of its own.
- **Do NOT build, do not launch the editor, do not push.** Unchanged, and not negotiable.

### If you finish B1–B5 and still have time

Prefer work that is **valuable without a build**, in this order:

1. **Settle `AUDIT §C2`'s suspected item** — does `GetGenerationParams` actually vary within one
   strate across a Gradient transition? That is answerable by *reading* `GetGenerationParams` and
   `FStrateGenerationParams::Lerp`. Turn the suspicion into a yes or a no, with the evidence, and
   correct the audit either way. **This is the highest-value build-free task available.**
2. **Write the stage-C design** (above) without implementing it.
3. **Re-read your own B1–B4 diffs against the original**, function by function, as a reviewer rather
   than an author. On a run with no tests, a second reading is the only oracle you have.

### The commit messages ARE the ledger

**Jahni's words: "just commit with explicit name what changed, I'll revert if needed."** So there is
no separate bookkeeping — the commit history is the record, and it has one job: let him revert a
single group without touching the others.

That makes the subject line load-bearing. Name the group and the scope, not the intent:

```
feat(opstack B2): port Terrace, LayerLines, Ribbing detail modifiers
feat(opstack B4): port Columns, Domes, Pinch, FloorBias + column op in the test pool
```

Body: what was transcribed, anything that looked wrong and was ported as-is anyway, and what breaks
first if the group is wrong. One group per commit — that rule exists *because* of the revert
workflow, so it is the one thing not to bend.

## Hard rules that prevent real bugs

- **Density sign:** negative = solid at the mesher. Inside the op stack the convention is INTERNAL
  (**positive = solid**), negated once by the caller. The SDF channel uses standard SDF convention.
- **Never run both density paths in one world.**
- **The acceptance bar is `§2.6.1`:** *same seed ⇒ same world on every peer*. Resemblance to the
  pre-refactor world is **not** required. The equivalence tests are **port-correctness oracles**, not
  fidelity checks — keep them for that reason.
- **Every cache key includes `LayoutVersion` AND the params.** See `§C2` and the overhang regression
  of 2026-07-27, where omitting the params silently deleted the overhang and only 1 sample in 20 000
  crossed the isosurface.
- `ProcessQueue` stays `EQueueMode::Mpsc`; `Epoch` carries through every async path; don't "optimize"
  the `ARCHITECTURE §8.10` invariants.
- Commit per coherent unit with a real message. **Never push.** `main` is the known-good fallback.
- Update `CODEMAP §3`, `ARCHITECTURE §8`, tick `OPSTACK-PLAN`, append to `OPSTACK-PROGRESS.md`.
- **When inserting a class into `VoxelDensityOpStack.cpp` / `VoxelHeightOpStack.cpp`, put it ABOVE
  the labelled end of the anonymous namespace.** Anchoring on the FACTORIES banner puts it outside,
  and the brace added with it closes nothing. Made that mistake twice; both files now say so at the
  exact line.

## Method lessons this refactor actually paid for

Ordered by how much they cost.

- **Instrument before hypothesising.** §C10 cost six builds and five refuted hypotheses, then was
  solved for free by a build setting changed for an unrelated reason. Park a question whose
  consequences are measured and benign.
- **Verify the premise before reasoning from it.** Four times now, a confident chain rested on an
  unchecked assumption and the check reversed it: C1's *documented* fix was wrong; "C9's risk is gone
  after FPSemantics" was wrong; "C1 is closed, 0 sites left behind" was wrong (the sweep matched a
  *spelling*, `SeedF * K`, and the survivor spelled it `(float)S * K`); "PitDensity enables pits" was
  wrong. **A grep over a spelling is evidence about the spelling.**
- **A perf change can be a correctness change.** The column-memo optimisation silently deleted the
  overhang; the tests caught it the same day. The failure was invisible to inspection and produced
  plausible terrain.
- **Coverage is a number, not a boolean.** Three related traps, each of which produced a green run
  that proved almost nothing:
  - *A test that prints nothing on success is indistinguishable from one that never ran.* Report
    counts, not just failures.
  - *A guard that only trips at zero does not measure coverage, it notices absence.* A run with 65 of
    6000 samples in open cave (1.1 %) passed a `== 0` guard silently. Use fractions.
  - *A success message that **asserts** coverage instead of reporting it reads as evidence while
    measuring nothing.* One said "pits and chimneys exercised" through a whole run in which zero pits
    existed.
- **Enabling a feature is not evidence it fired — ask the structure, not the output.** Setting
  `PitDensity` did nothing (wrong struct). Diffing two stacks with/without the op pool would have
  *lied* (the pool is not in the SDF cache key, so both share the `thread_local` cache). What worked:
  call `BuildChunkCache` and look at `Pits.Num()`. Prefer the check that can fail for exactly one
  reason.
- **An oracle that shares the defect under test proves nothing.** The stale-cache check was going to
  compare two interleaved param sets against the original — which keys its SDF cache without the
  params and would have failed. Compare against the thing itself evaluated alone instead.