VoxelForge/OPSTACK-HANDOFF.md

Handoff — VoxelForge operator stack, 2026-07-27 (end of day 2)

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. §5 SurfaceWorld, §6 shafts, §7 islands, §2 TunnelNetwork.
5. AUDIT-2026-07.md — §C9 is the top open risk (half fixed). §C10 is SOLVED — don't reopen.
6. CODEMAP.md — navigation. Trust symbol names over line numbers.

Where things stand — 5 of 8 archetypes ported, 11 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	❌ next (§7)
Underwater	❌ (§8 — TunnelNetwork + a water flag)
TunnelNetwork	❌ LAST, deliberately — owns BuildChunkCache's two-region window-invariance discipline (§8.4), the most delicate code in the plugin

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.

Two things Phase 2 invented that were not in the original design

1. Height space (VoxelHeightOp.h) — a second operator family. SurfaceWorld's terrain ops (cliff/terrace/layer-lines/beach) read and write an altitude, not a density: no input Z, XY-pure per column, neither density nor SDF touched. 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.

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

1. FloatingIslands (§7) — next port.
2. Underwater (§8) — TunnelNetwork + a flag; fold in once TunnelNetwork is done.
3. TunnelNetwork (§2) — last, and take §8.4's window-invariance discipline seriously.
4. PERF — deliberately parked by Jahni until the transition is complete. Generation is measurably slower on the op path. One cause found and fixed (the column memo was discarding 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.
5. AUDIT §C9 library half — FPSemantics = Precise fixed the compiler half; sinf/cosf are not IEEE-754 specified, so MSVC's CRT and glibc's libm can still differ. Currently 0 samples within 1e-6 of the isosurface, i.e. no measured risk. If it ever must be zero by construction, the fix is a deterministic in-house sin/cos, not a build flag. Also: run CrossPlatformDigest on Linux and compare the SHAPE digest, then pin it.
6. VerticalShafts proves 0 of 60 tiles (Maze 23, slabs 36-40). Pessimistic, not wrong: its EffectOverBox returns CarveOnly whenever any shaft is within a Spacing*1.6 halo instead of testing real connector capsules. Lost CPU, never a hole.
7. ClassifyTile still uses hand-written guards. ClassifyBox exists and is brute-force verified per archetype, but nothing consumes it in production yet. That is where the measured tile-skipping (23 / 36 / 40 of 60, against today's zero) actually turns into frames — arguably the biggest single win still on the table.

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 the §C2 note 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.

Method lessons this refactor actually paid for

• 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. Twice, a confident chain rested on an unchecked assumption, and twice the check reversed the answer — C1's documented fix was wrong, and "C9's risk is gone after FPSemantics" was wrong.
• A test that prints nothing on success is indistinguishable from one that never ran. Report coverage counts, not just failures. This bit three times before it stuck.
• A perf change can be a correctness change. The column-memo optimisation silently deleted the overhang; the test suite caught it the same day. This is the concrete answer to "why all these tests" — the failure was invisible to inspection and produced plausible terrain.
• 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.