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.

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.