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.

**You cannot build, and nobody will build for you during this run.** Rule #1 still holds absolutely.
Everything you write stays unverified until he returns.

**That is his explicit, repeated decision, not an oversight — do not re-litigate it and do not
quietly scale the work down.** Verbatim: *"I'm fine with unverified work, if committed, I can always
manually go back and try — I want him to work towards the full op stack completeness."* So the goal
of an unattended run is **to finish the transition**, not to stop somewhere safe. Take the queue
below as far as it goes.

Two things make that reasonable rather than reckless, and they are worth knowing:

1. **Committing per group IS the safety net.** He reverts by sha. That is why the one-commit-per-group
   rule is the one thing not to bend.
2. **Reaching 8 of 8 does not change his world by itself.** `UsesOperatorStackForChunk` returns false
   unless a strate has `bUseOperatorStack` ticked, so adding `TunnelNetwork` and `Underwater` to the
   ported list is inert until *he* ticks a box. The flag flip is safe to include; pointing a live
   world at it stays his call.

### 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. Run it to the end — **8 of 8 is the finish line.**

- **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 subtlety that lets B precede 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 against strate-level params is therefore equivalent
*only while no room carries a detail-type op*. The test's pool is Pit/Chimney only and `ApplyTo(Pit)`
writes just the four pit fields, so the two are identical today. **Keep the pool that way through
B1–B5**; C1 is what makes a `Terrace` op in the pool legal. (B4's Column op is safe: `STEP 4d` reads
`SDFCache.Columns` from the bake, never the shadowed params.)

- **C1 — the per-room op override.** `§2` calls this the piece with "no clean home" and offers two
  options. **Take option (a), and note that the mechanism is already established in this codebase —
  do not invent a scoping predicate.** Three ops already read state owned by an upstream op via a
  non-owning pointer handed over at build time: `FOverhangShelfMod` ← `FSurfaceColumnSource`,
  `FShaftLedgeMod` ← `FShaftFieldSource`. Do the same here:

  `FRoomGraphSource` gains `const FStrateGenerationParams& LocalParamsAt(x, y, z) const`, which
  reproduces the original exactly — take the voxel's `NearestRoomIdx` (it already computes it), apply
  that room's `RoomOp` onto a `thread_local` copy of the params, return it. Every detail op holds a
  `const FRoomGraphSource*` and reads its fields from that copy instead of from its own.

  This is the pit/chimney resolution a second time: the difficulty in `§2` came from assuming each
  modifier must own its params. Let one op own the shared state and the rest read it, and the problem
  disappears. **Transcribe the per-voxel copy as-is** — yes, the original copies a ~74-field struct
  per voxel inside the gate; note it in the log as a perf item and change nothing.

  Acceptance: put a `Terrace` op in the test's room pool alongside Pit/Chimney and require
  bit-identity. That is the check B could not make.
- **C2 — `Underwater`.** Nearly free: `§8` establishes there is **no density difference at all** —
  `GetDensityAt` routes it to `GetDensityWithParams` and `WaterLevelRelative` is consumed by the
  render-side water system, not by density. So it is the TunnelNetwork stack, reached from a second
  `case`. Add the wiring case and an equivalence test that samples the `Underwater` slot. If you find
  a real density difference, **stop and write it down** — that would contradict `§8` and is worth
  more as a finding than as code.
- **C3 — 8 of 8.** Add `TunnelNetwork` and `Underwater` to `UsesOperatorStackForChunk`'s ported list.
  Update `CODEMAP §3.2d` and its `UsesOperatorStackForChunk` row, tick `OPSTACK-PLAN` Phase 2, and
  write the closing `OPSTACK-PROGRESS` entry: the archetype `switch` now has a complete operator-stack
  twin, per-strate opt-in, every one equivalence-tested.

### After 8 of 8 — keep going, in this order

1. **Settle `AUDIT §C2`'s suspected item.** Does `GetGenerationParams` actually vary within one strate
   across a Gradient transition? Answerable by *reading* `GetGenerationParams` and
   `FStrateGenerationParams::Lerp` — no build. Turn the suspicion into a yes or a no with the
   evidence, and correct the audit either way. Cheap, and it closes an open question honestly.
2. **The worm amplitude cap (`DECOMPOSITION §0.2`).** The largest single perf item in the plan, and
   the reason TunnelNetwork proves 0 of 40 tiles. It needs the fold to carry a **number**, not just a
   direction: add a numeric carve/fill amplitude alongside `EVoxelOpEffect`, have
   `FWormFieldSource::MaxCarveAmplitude()` (already written, already unused) feed it, and let
   `AllSolid` survive when the rock is solid by more than the sum of every remaining carve.
   **⚠️ This changes the fold contract that all 13 tests rest on — its own commit, nothing else in
   it,** and `VoxelForge.OpStack.BoxVerdictFold` must be extended in the same commit.
3. **Make `ClassifyTile` consume `ClassifyBox`.** Verified per archetype, still unconsumed in
   production — this is where measured tile-skipping (Maze 23/60, slabs 36–40/60) becomes frames.
   A false verdict is an invisible hole, so keep the brute-force check in every archetype's test.
4. **Re-read your own diffs against the original**, group by group, as a reviewer rather than an
   author. On a run with no builds, a second reading is the only oracle you have. Do this rather than
   starting anything new when the queue runs out.

### Still not yours to do, even unattended

- **Do NOT build, do not launch the editor, do not push.** Unchanged, not negotiable.
- **Do NOT tick `bUseOperatorStack` on any strate asset.** C3 makes the archetypes *available*;
  pointing a live world at an unverified path stays Jahni's decision.
- **Do NOT start Phase 3** (ops as data assets). It is a design conversation, not a transcription.

### 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
feat(opstack C1): per-room op override — detail ops read LocalParamsAt from the room source
feat(opstack C3): TunnelNetwork + Underwater in the ported list — 8 of 8
```

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.

**Close the run with one `OPSTACK-PROGRESS` entry** listing every commit made, in order, with a
one-line "what this touches" each, and the test filter to run (`VoxelForge`). Jahni's first action on
return is a single build; that entry is what makes it efficient. Then shut down if he asked you to.

## 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.