acdream/docs/research/2026-06-09-flap-outdoor-fullworld-building-flood-merge-handoff.md

# HANDOFF — §4 outdoor FULL-WORLD flap: onset pinned to the building-flood merge

**Date:** 2026-06-09 (late evening). **Branch:** `claude/thirsty-goldberg-51bb9b`, HEAD `fafe5d6`.
**Status:** trigger pinned frame-exact; kill mechanism NOT yet pinned — one purpose-built
probe (or RenderDoc) decides it. Read this top-to-bottom before touching code.

---

## 0. TL;DR

1. **The user-visible bug:** standing/running OUTDOORS at specific spots, the WHOLE world
   (terrain + buildings + entities + the player model + sky) drops to the fog-tinted clear
   color. It strobes at onset then HOLDS; rotating the camera pops it back; walking
   forward through the trigger zone reproduces it; sidestep/backwards through the same
   zone does not. Confirmed distinct from #106 (membership healthy throughout).
2. **Frame-exact onset (the day's key result):** the flap begins at EXACTLY the frame the
   nearby cottage's per-building flood merges into the outdoor root —
   `[pv-input] flood=1 → flood=5` with player/yaw frozen and only the camera boom settling
   (~3 cm/frame). Same frame, the `[gl-state]` tripwire shows the leftover scissor box
   flip from full-screen to a **drifting 9×21 px doorway footprint** (the cottage doorway
   projected to screen, moving with the eye's micro-settle). Onset evidence:
   `flap-glstate-capture.log` (gl-state frame 4977 = log line 5006); the same transition
   with full render-sig fields: `flap-residual-capture.log` (38 such transitions, e.g.
   frame 1745→1746: ONLY `ids=`/`draw=` gain a cell — every other field identical,
   `out=10529` instances submitted in BOTH frames).
3. **Massive exoneration chain (all probe-verified, do not re-tread):** membership/root/
   viewer cell stable; `res=None`; camera view-projection matrix sane and NaN-free
   (11,767 frames, 6 dp); eye 1.6–2.1 m ABOVE terrain (buried-eye refuted); flood/
   outPolys/outSlices/outMode constant; full-screen quad clip planes mathematically
   cannot cull; `MergeNearbyBuildingFloods` does NOT touch OutsideView; cross-frame GL
   state leak refuted (`[gl-state]` shows scissor test OFF + sane depth/blend/cull/vp/fbo
   entering every frame, `err=0x0`); `ClipFrameAssembler` slices carry their own plane
   arrays (slot repacking can't swap planes per se); `ClipFrame.AppendSlot/UploadShared`
   have dynamic capacity + full re-upload (no overflow).
4. **What remains (the kill mechanism, one of):**
   a. **Per-instance clip-slot routing** (`WbDrawDispatcher.SetClipRouting` +
      `ResolveEntitySlot`, binding=3 slot SSBO): the landscape slice installs routing
      UNCONDITIONALLY (`RetailPViewRenderer.cs:215`) even for OUTDOOR roots, while the
      U.4 contract (`WbDrawDispatcher.cs:309-331`) says outdoor frames should
      `ClearClipRouting`. When the flood merges, `CellIdToSlot` gains cells and slot
      indices REPACK (cells pack before the outside view in the assembler) — if any
      instance's slot resolution or the slot SSBO content goes stale/wrong, the world's
      instances clip against the cottage's doorway planes (or CULL).
   b. **Terrain/sky UBO content at draw time** — `SetTerrainClip(slice.Planes)` should
      hold the full-screen planes; if the merge path overwrites it with doorway planes
      (or count) before terrain samples it, terrain + sky die together.
   c. Something in the per-slice draw orchestration (`DrawLandscapeThroughOutsideView`,
      `RetailPViewRenderer.cs:208-230`) that behaves differently when cell slices exist.
5. **Why this matters beyond the spot:** the same merge boundary is crossed every time
   you run past cottages (the original "parts of the screen flash while running") and at
   cottage enter/exit — this is very likely THE remaining §4 visible flap, with the
   edge-on doorway grey (2a) and corner seal (2b) as siblings in the same family.

## 1. The decisive next probe (do this first)

Add a `[clip-route]` print-on-change probe (gate: reuse `ACDREAM_PROBE_GLSTATE` or a new
var) emitting, per frame:
- In `RetailPViewRenderer.DrawLandscapeThroughOutsideView`: `slice.Slot`, `slice.Planes`
  values (all 4–8 vec4s), `clipAssembly.CellIdToSlot` contents, and the first 16 bytes of
  `_clipFrame`'s terrain bytes (the count + first plane) as uploaded.
- In `WbDrawDispatcher.Draw` (when routing active): a histogram of `ResolveEntitySlot`
  outcomes — instances per slot index + CULL count.

One repro run (the user triggers the flap, holds 3 s, rotates, closes) then diff the
held-flap frames vs healthy frames. Whichever of (a)/(b) shows wrong values is the bug.
If BOTH look correct → RenderDoc frame capture during the flap (the GPU truth).

## 2. Repro protocol (user-validated, fast)

Spot: Holtburg south slope, player ≈ (167–169, −31..−37) world frame (A9B4 anchor), the
slope SE of town with the A9B3 cottage. Walk FORWARD downhill through the zone → strobe →
hold. Rotate camera → recovers. `eyeAbove` stays ~+2 m (do not chase buried-eye).
Launch with `ACDREAM_PROBE_PVINPUT=1` + `ACDREAM_PROBE_GLSTATE=1` (+ the new probe);
AVOID `ACDREAM_PROBE_FLAP` for visual judgment runs (timing skew — render digest landmine).

## 3. Evidence inventory (this session's captures, worktree root, untracked)

| File | What it holds |
|---|---|
| `flap-residual-capture.log` | Full flap probes; 38 flood-merge transitions w/ render-sig field diffs; the held-flap [flap-cam]/[flap] stability blocks |
| `flap-pvinput-capture2.log` | 11,767 pv-input frames; NaN-free matrix proof; held blocks at 6 dp |
| `flap-eyeterr-capture.log` | eyeAbove (terrain-burial refutation) |
| `flap-glstate-capture.log` | GL-state tripwire; frame-exact onset marker (frame 4977) + doorway-box fingerprint |

## 4. DO-NOT-RETRY additions from this session (full chain in §0.3)

- Camera matrix NaN / degenerate orientation — REFUTED (6 dp capture).
- Eye buried in terrain — REFUTED (`eyeAbove` +1.6..2.1 m).
- Cross-frame GL scissor/depth/blend leak — REFUTED (`[gl-state]` stable + scis=0 entering frames).
- Full-screen outdoor quad plane collapse / winding — impossible (static CCW NDC quad).
- `MergeNearbyBuildingFloods` contaminating OutsideView — code-verified NOT (explicitly skipped).
- `ClipFrame` slot-capacity overflow — dynamic capacity, full re-upload, code-verified.
- The earlier "stale render anchor explains the running distortion" attribution — PARTIAL
  only; #106 fixed the anchor, this flap persists (correction noted in the #105/#106 docs).

## 5. Probe-semantics gotchas (cost an hour today)

- `[render-sig]`'s `terrain=` prints a STALE pre-DrawInside local (always `Skip` when a
  clipRoot exists); the REAL assembler mode is `[flap-cam]`'s `terrain=` and render-sig's
  `outMode=`. Don't diff the wrong field.
- `[render-sig]` prints on signature change only; the EYE coords are part of the
  signature → a settling boom spams lines with nothing else changing.
- `Tee-Object` writes UTF-16LE; Python analyzers must BOM-detect (`b'\xff\xfe'`).
- The first pv-input run produced 0 lines because the client was closed pre-entry —
  check `auto-entered player mode` exists before analyzing.