VoxelForge/OPSTACK-HANDOFF.md

# VoxelForge handoff — the operator stack is DONE. Read this, not the old jargon.

> Paste this into a fresh session. Written 2026-08-16, deliberately in plain language: the previous
> version of this file had become a private dialect that Jahni could not read, which is a failure of
> the document, not of the reader.

---

## 1. What the operator stack was, in one paragraph

Cave generation used to be one big `switch`: each cave type (tunnels, maze, shafts, floating
islands, surface…) was its own hardcoded ~200–1000 line C++ function. The refactor replaced that with
small composable pieces ("operators") that stack up to produce the same terrain. **The promise was
that you could eventually invent new world types by combining pieces in the editor instead of asking
for another thousand-line function.**

**That promise — "Phase 3", ops as data assets — was never built, and is NOT being built now.**

## 2. Status: done. Stop refactoring.

- **8 of 8 archetypes ported**, running in production (`bUseOperatorStack` is ticked on the game's
  strate assets), and **bit-for-bit identical** to the old path. Verified by a 115 000-sample field
  digest plus eight per-archetype equivalence tests.
- **14/14 automation tests green, 0 violations anywhere.**
- **39 % of tiles are skipped in the running game** (`Tiles Meshed` 1.15 vs `Tiles Classified` 1.88).
  It was 0 % on the morning of 2026-08-16. Each skipped tile avoids ~43 000 density evaluations plus
  marching cubes.

**Decision taken 2026-08-16, with Jahni:** the op stack is finished. **Do not start Phase 3. Do not
start another refactor.** The old `switch` stays in place as the correctness oracle — deleting it
buys nothing today. Next work should be things Jahni can *see*: see `fable-idea.md` (F7 set-pieces,
F9 audio were queued before this started).

### The honest ledger, so nobody re-litigates it

Three weeks, 120 commits, from 2026-07-27. Every `feat:` commit in that window is a *port* of
something that already worked. **The world did not change by a single voxel — that was the
acceptance criterion.** What Jahni actually got: the 39 % perf win, two genuine pre-existing bugs
found (a use-after-free on every strate-asset edit while streaming, and an under-bounded room
collection that could make two multiplayer peers generate different geometry), and a number of fixes
to bugs the refactor itself introduced. That is a thin return for three weeks, and it is why the
direction changed.

## 3. The jargon, translated

Almost all of it means one thing: **can we prove a chunk of world is entirely rock or entirely air
without checking every point in it, so we can skip the expensive work?**

| term | plain meaning |
|---|---|
| **T1.d / tile skipping** | that idea. The single biggest perf item in the plan. |
| **box verdict / `ClassifyBox`** | "is this whole box uniform?" → `AllSolid`, `AllAir`, or `Mixed` (don't know) |
| **`Mixed`** | "can't prove it" — always safe, just means we do the work |
| **`ClassifyTile`** | the function that decides, per tile, whether to skip meshing |
| **operator / op stack** | one generation step (rock, carve, roughness…) and the list of them |
| **equivalence test** | proof the new path produces byte-identical terrain to the old one |
| **`violations`** | ⚠️ **the only number that means danger.** A tile wrongly proved uniform has *no geometry and no collision* — a player falls through the floor. Must always be 0. |

## 4. What is verified, and what is not

**Verified:** everything through commit `871ca19` — tests green, digests unchanged, 39 % measured
in game.

⚠️ **Built but NOT re-verified:** `4d33321` (Sol's boundary fold — lets a tile that straddles cave and
open air still resolve) and `91585ea` (a test-only warning demotion). Jahni built these and says the
game *looks* fine, but **the test suite has not been re-run and the counters have not been re-read
since.** Before trusting them:

1. run the `VoxelForge` automation filter — **`violations` must be 0 and all eight equivalences
   bit-identical**;
2. `stat VoxelForge` in game — the accounting must close:
   `Tiles Meshed + Skipped All Air + Skipped All Solid = Tiles Classified`.

If either fails, `git revert 4d33321` — the 39 % win does not depend on it.

## 5. Rules that still prevent real bugs

- **Never build.** Jahni builds; he has the editor open and it costs him real time. Say "ready to
  build" and list likely compile-error spots.
- **`violations` 0 and the eight equivalences bit-identical** — the only non-negotiable results.
- **A bound used to skip work must be PROVED, not observed.** Use `VF_PerlinAbsBound` (= 1.5);
  `FMath::Lerp(A,B,t)` spans `[min(A,B), max(A,B)]`, so a radius envelope is `max(Min,Max)`.
- **Never change `ClassifyTile`'s conditions or return values casually.** Every `return` there fails
  safe to `Mixed`.
- **Never state a `.uasset` value from memory** (like `bUseOperatorStack`). Ask, or read it in the
  editor. This sent a full day sideways.
- `FindSlotIndexForChunkZ` is **protected**; `GetStrateChunkZBounds` is the public equivalent.
- Push `experimental` freely. **Never push `main`.**

## 6. Two lessons that generalise beyond this plugin

- **A signal that always says the same thing measures nothing.** A counter that can fire for two
  reasons is not a measurement — splitting one such counter is what finally cracked T1.d after a day
  of wrong inference. A warning that fires every run and always means "this is fine" is noise that
  trains the reader to ignore warnings; one of those quietly worried Jahni for several sessions.
- **Verify the premise, and verify it completely.** Multiple confident chains reversed on checking
  this month. Twice the failure was a *partial* read — grepping a symbol and reporting it as checked
  for something else. A grep that finds a declaration has not checked its access specifier.

## 7. The open question, which matters more than any of the above

**What do you want the world to *do* that it doesn't?** Three weeks went into a pipeline instead of
that question. Start there.