acdream/docs/research/2026-06-05-shell-sealing-cellar-floor-handoff.md

# Handoff — Indoor SHELL-SEALING / wrong-flood-root (cellar floor + interior walls drop to grey) — 2026-06-05 (PM/eve)

> **For the next session/model. Read this FIRST.** The previous model (me) spent this session on the
> "viewer-cell flicker" 3-part plan, shipped two real-but-partial fixes, and **conflated two distinct
> problems**. The user's PRIMARY pain — **interior walls + cellar floor render as grey background with
> dynamic objects / outdoor slices showing through, plus flicker when changing rooms / entering the
> cellar** — is the **KNOWN, already-documented "R1-completion" problem**, NOT the boom and NOT the
> branch I touched. Get a SCREENSHOT + `[shell]` evidence EARLY; do not re-litigate the disproven causes
> below.
>
> **Tree:** branch `claude/thirsty-goldberg-51bb9b`, worktree
> `C:/Users/erikn/source/repos/acdream/.claude/worktrees/thirsty-goldberg-51bb9b`. HEAD `2b7f5a1`.
> Do NOT branch/worktree. Do NOT push without asking. NEVER `git stash`/`gc`. PowerShell on Windows;
> launch logs are UTF-16 (use `Select-String`/`Get-Content`, they handle it).

---

## 0. The honest TL;DR

- The user reports (with a screenshot): standing **inside** the cottage, the **floor draws but the walls
  are grey** (the time-of-day clear color), with NPCs/doors/chests and a slice of the **outdoor world**
  floating in the grey. In the **cellar**, the **floor is missing** (just grey). It **flickers** when
  changing rooms / entering the cellar. This persisted through both of this session's fixes.
- **Decisive evidence (live, this session):**
  ```
  [flap-cam] root=0xA9B40171  viewerCell=0xA9B40171  playerCell=0xA9B40174  eyeInRoot=Y
             eye=(153.46,6.66,94.92)  player=(153.58,8.88,92.76)  terrain=Planes outVisible=True
  [flap]     root=0xA9B40171 ... | p0->0170 proj=4 | p1->0173 proj=0 | p2->0175 proj=5 || outPolys=1 vis=4
  ```
  The render **roots the visibility flood at the CAMERA's cell `0171`** (the room, z≈95), but the
  **PLAYER is in `0174`** (the cellar, z≈93). The flood reaches `vis=4` cells **from the room**; the
  player's actual cell `0174` is **not sealed** by it (the stair-chain portal `p1→0173` is `proj=0`).
  So the cellar shell around the player isn't drawn → grey.
- **This is exactly what the 2026-06-05 Residual-A handoff already flagged as NEXT:** *"when the player
  is in the cellar but the eye is up in the room, clipRoot = room → the PVS flood from the room does NOT
  reach the cellar → the cellar floor drops."* And the 2026-06-02 design doc §3 calls the grey a
  **SHELL-SEALING bug** ("the closed cell mesh is not covering those pixels"). **The answer was in the
  docs the whole time.**
- **Two fixes shipped this session (both real, both PARTIAL, neither is the cellar/walls fix):**
  - `d2212cf` — Part 1 camera boom convergence snap (retail `UpdateCamera` 0x00456fcd). Freezes the
    at-rest boom drift. Test-covered. The user confirmed the at-rest room was **never** flickering, so
    this fixed a real-but-invisible thing. KEEP (faithful) or reassess.
  - `2b7f5a1` — branch inside/outside on `is_player_outside` (retail `RenderNormalMode` 0x453aa0) instead
    of the camera cell. **Reduced** the player-OUTSIDE doorway grey ("reduced a lot" — user). Test-covered.
    Does NOT touch the player-inside case. KEEP (no regression — see §4) or reassess.

---

## 1. The two problems (do NOT conflate them — I did, and it cost the session)

| | Problem A — doorway transition grey | Problem B — interior shell not sealed (THE user's pain) |
|---|---|---|
| **When** | Player **fully outside** (landcell `<0x100`), camera lags **inside** the doorway | Player **inside** cell X, camera **inside** a DIFFERENT cell Y (camera in room, player in cellar) |
| **Why** | Branch keyed on camera → wrongly ran `DrawInside` rooted at the threshold | Flood roots at the camera's cell Y; the player's cell X isn't in/sealed by the flood from Y |
| **Symptom** | Whole screen grey at the in↔out threshold | Walls/cellar-floor grey while standing inside; flicker at room/cellar transitions |
| **Status** | **Reduced** by `2b7f5a1` (retail-verified) | **UNSOLVED** — this is the real target |
| **Evidence** | `outPolys=0` while the exit portal projects full-screen (`proj=6 clip=8`) | `root=0171` vs `playerCell=0174`; `vis=4` from the room excludes the cellar |

**Problem B is the one to fix.** Problem A's fix is a genuine retail-faithful improvement that happens to
share a "grey" symptom, which is what made me conflate them.

---

## 2. Problem B — what we know, and the core open question

**The render roots the PView flood at `clipRoot = visibility.CameraCell` (the VIEWER/camera cell)** —
`GameWindow.cs:7322` (now wrapped by the `ShouldRenderIndoor` branch, but still the **viewer cell** when
indoor). Retail `RenderNormalMode` (0x453aa0:92675) literally calls `DrawInside(this->viewer_cell)`. So
rooting at the viewer cell is retail-faithful **on its face**.

**But** when the 3rd-person camera is in a different interior cell than the player (room vs cellar), the
flood from the camera's cell does **not** seal the player's cell → the geometry **around the player**
(cellar floor, near walls) isn't drawn → grey. The decisive `[flap-cam]` line (`root=0171`,
`playerCell=0174`) is the whole story.

**The core open question the next model MUST resolve against the decomp (don't guess — this is the
crux):** how does **retail** avoid this? Candidate mechanisms, each needs decomp verification:

- **(a) Retail's collided camera stays in (or floods to) the player's cell.** Residual A
  (`SmartBox::update_viewer` 0x00453ce0, swept `viewer_sphere`) is shipped, but verify: does retail's
  `viewer_cell` actually equal the player's cell when the player is in the cellar and the boom would put
  the eye up in the room? The spring arm sweeps from the **head-pivot** — if the pivot is the player's
  head in the cellar, the swept eye may be stopped by the cellar ceiling and stay in `0174`. **Check
  whether acdream's `viewer_cell` SHOULD be `0174` here and isn't** (i.e. the camera-collision/cell-
  resolution is putting the eye in `0171` when retail would keep it in `0174`).
- **(b) Retail's flood from the viewer cell DOES reach the player's cell**, because retail's portal clip
  is robust and the stair-chain portals don't go `proj=0`. Here `p1→0173 proj=0` stops the flood. Is
  `0174` reachable only through `0173` (which is culled)? If so, the flood-reach is the bug, not the root.
- **(c) The design doc §5 intent: visibility roots at the PLAYER's physics cell** (`CellGraph.CurrCell`),
  **eye drives projection only.** The 2026-06-05 viewer-cell handoff said *don't* switch the root to the
  player cell ("retail roots `DrawInside` at viewer_cell"). **This is a real contradiction in our own
  docs** — design doc §5 says player-cell-roots-visibility; the later handoff says viewer-cell-roots.
  The next model should settle it from the decomp: in `RenderNormalMode`, `viewer_cell` is the argument
  to `DrawInside` — but WHAT sets `viewer_cell`, and is it ever != the player's cell in normal play? If
  retail's `viewer_cell` is always the player's cell (because the camera collision keeps it there), then
  (a) and (c) converge and acdream's bug is that its `viewer_cell` drifts to the camera's room cell.

**Strong hypothesis to test first (cheap):** acdream's `viewer_cell` (`visibility.CameraCell`) is wrong
here — it's the *room* because the eye is geometrically up in the room, but **retail's collided
`viewer_cell` would be the cellar** (the swept sphere from the head-pivot is stopped by the cellar
ceiling / the pivot is in the cellar). I.e. this is a **camera-cell-resolution** bug, not a flood/root
bug. Verify by reading how `visibility.CameraCell` / `viewerCellId` is computed (`CellVisibility.
FindCameraCell` + `PhysicsCameraCollisionProbe.SweepEye`) and whether the pivot/sweep should keep the
cell in `0174`.

---

## 3. The next diagnostic step (do this BEFORE any fix — evidence first)

The apparatus is committed and ready. Stand the player in the cellar with the camera up in the room
(the exact repro), and capture:

```powershell
$env:ACDREAM_DAT_DIR="$env:USERPROFILE\Documents\Asheron's Call"; $env:ACDREAM_LIVE="1"
$env:ACDREAM_TEST_HOST="127.0.0.1"; $env:ACDREAM_TEST_PORT="9000"
$env:ACDREAM_TEST_USER="testaccount"; $env:ACDREAM_TEST_PASS="testpassword"
$env:ACDREAM_PROBE_FLAP="1"; $env:ACDREAM_PROBE_SHELL="1"; $env:ACDREAM_PROBE_VIS="1"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object launch.log
```

Pin these three things from the log while standing in the cellar:
1. **Is the player's cell (`0174`) in the visible set?** `[flap-cam]` shows `root=` vs `playerCell=`;
   `[vis]`/`[flap]` shows `vis=` count + (turn on `ACDREAM_PROBE_VIS` for the cell-id list). If `0174`
   is NOT in the set → **flood-reach / wrong-root** problem (§2 a/b/c).
2. **If `0174` IS in the set, does its shell DRAW?** `[shell]` probe (`ACDREAM_PROBE_SHELL`) reports
   per-cell shell draw (geometry/texture/depth). If `0174` is visible but its shell is skipped / a
   polygon is back-facing / depth-culled → **mesh-seal** problem (design doc §3: dat-dump the `0174`
   EnvCell mesh, look for a missing/back-facing floor polygon).
3. **What `viewer_cell` SHOULD it be?** Compare the live `viewerCell=` to where the player is. If the
   camera collision (Residual A) is failing to keep the eye's cell == the player's cell, that's §2(a).

This single capture discriminates root-vs-flood-vs-mesh. **Don't pick a fix until it does.**

---

## 4. Exactly what's committed this session (and why each is safe to keep)

| SHA | What | Keep? |
|---|---|---|
| `d2212cf` | Part 1 boom convergence snap — `RetailChaseCamera.ApplyConvergenceSnap` + wiring; retail `UpdateCamera` 0x00456fcd (`SnapEpsilon=2×0.000199999995`, `RotCloseEpsilon=0.000199999995`). 4 new App tests. | **Keep** — retail-faithful, fixes at-rest boom drift, no regression. Not the visible fix. |
| `2b7f5a1` | Branch inside/outside on `is_player_outside` (`RenderingDiagnostics.ShouldRenderIndoor` + `GameWindow.cs:7322`). 5 new Core tests. | **Keep** — retail-faithful, reduced Problem A. **Provably no Problem-B regression:** for the player-inside case it yields `clipRoot = CameraCell`, identical to the pre-fix `visibility?.CameraCell`. |

Plan doc (Part 1's TDD steps; Parts 2/3 there are SUPERSEDED by this handoff —
see §5): `docs/superpowers/plans/2026-06-05-indoor-viewer-cell-flicker-fix.md`.

**Working tree is clean** (the TEMP w-stat probe added to `PortalVisibilityBuilder.cs` was stripped;
`git status` shows nothing under src/tests). Test baseline: **App 187p/0f**, **Core 1331p / 4f / 1s**,
build green. The 4 Core fails are the documented set (2× `DoorBugTrajectoryReplay.LiveCompare_*`,
`BSPStepUpTests.D4`, `DoorCollisionApparatusTests`).

---

## 5. DO NOT RE-LITIGATE (evidence-disproven this session)

- **The flicker is NOT viewer-cell oscillation / cell-membership instability.** Captured the render gate
  (`terrain=Skip/Planes`, `outVisible`) flapping with the **viewer cell STABLE at `0171`**. The planned
  **Part 2 (point_inside_cell_bsp ±0.2 mm dead-zone) was NOT implemented and is NOT the fix.**
- **The doorway grey is NOT the portal PROJECTION degenerating.** At the grey frame the exit portal
  `p0→0170` projects **full-screen** (`proj=6 clip=8`, ndc spans ±1) while `outPolys=0`. So
  `ProjectToNdc` is fine; the **`OutsideView`/flood assembly** (and, per §2, the **root/flood-reach**)
  is the issue. Do not "harden the w-clip" (5f596f2 already did the clip-space side-plane clip; the
  9f95252 eye-in-portal flood band-aid is still in — reassess only after Problem B is understood).
- **The boom drift (Part 1) was real but is NOT the visible flicker.** Freezing the boom did not change
  the user-visible symptom.
- The 3-part plan's framing (flicker = boom + cell dead-zone; void = clip) was the previous-session
  hypothesis; this session's live evidence **reassigns** the dominant symptom to Problem B (shell
  sealing / flood root). Treat the plan's Parts 2-3 as superseded.

---

## 6. Canonical prior art (already documents Problem B — read these)

- **`docs/research/2026-06-05-render-residual-a-shipped-core-inside-render-handoff.md`** — *"player in
  cellar, eye in room → clipRoot=room → flood doesn't reach the cellar → cellar floor drops. NEXT = the
  CORE inside render (R1 completion)."* THE pointer.
- **`docs/superpowers/specs/2026-06-02-render-pipeline-redesign-design.md`** §2 (the binary
  `RenderNormalMode` model), §3 (grey = SHELL-SEALING bug; `[shell]` probe + dat dump), §5 (the
  two-camera invariant — and the doc/handoff contradiction to settle, §2 above).
- **`memory/reference_render_pipeline_state.md`** — Residual A made the viewer cell *accurate*, which
  **exposed** that the flood doesn't reach the player's cell. (This session is more evidence for that.)
- **`memory/feedback_render_one_gate.md`** + **`memory/feedback_verify_render_seal_before_layering.md`**
  — get a SCREENSHOT + `[shell]` evidence EARLY; one gate for all geometry.
- **`memory/feedback_render_downstream_of_membership.md`** — a transition flicker can be a membership/
  flood-root bug, not a render bug.

---

## 7. Kickoff prompt (copy-paste)

```
Continue acdream M1.5 indoor render in worktree thirsty-goldberg-51bb9b (branch
claude/thirsty-goldberg-51bb9b, HEAD 2b7f5a1). Do NOT branch/worktree; do NOT push without asking;
NEVER git stash/gc. PowerShell on Windows; launch logs are UTF-16. Running the client: see CLAUDE.md;
+Acdream spawns at the Holtburg cottage.

TARGET BUG (the user's real pain, with a screenshot): standing INSIDE the cottage, the floor draws but
the WALLS are grey (the time-of-day clear color) with NPCs/doors/outdoor-slices showing through; in the
CELLAR the FLOOR is missing (grey); flicker when changing rooms / entering the cellar. This is the KNOWN
"R1-completion" SHELL-SEALING / wrong-flood-root problem, NOT the camera boom and NOT the inside/outside
branch (both partially fixed this session).

READ FIRST (in order):
1. docs/research/2026-06-05-shell-sealing-cellar-floor-handoff.md  (THIS handoff — the two problems §1,
   the decisive root=0171/playerCell=0174 evidence §2, the next diagnostic step §3, the DO-NOT-RETRY §5).
2. docs/research/2026-06-05-render-residual-a-shipped-core-inside-render-handoff.md (the R1-completion
   pointer) + docs/superpowers/specs/2026-06-02-render-pipeline-redesign-design.md (§2/§3/§5).
3. memory: reference_render_pipeline_state, feedback_render_one_gate,
   feedback_verify_render_seal_before_layering, feedback_render_downstream_of_membership.

DO (evidence first — this bug has burned many speculative fixes; do NOT add a workaround):
- Reproduce + capture with ACDREAM_PROBE_FLAP=1 ACDREAM_PROBE_SHELL=1 ACDREAM_PROBE_VIS=1, player in the
  CELLAR with the camera up in the room. Pin: (1) is the player's cell (0174) in the visible set? (2) if
  so, does its shell DRAW ([shell] probe) or is a floor polygon missing/back-facing (dat-dump the 0174
  EnvCell mesh, design doc §3)? (3) is acdream's viewer_cell wrong — should retail's collided viewer_cell
  be the cellar (0174), not the room (0171)? (See §2 a/b/c — settle the design-doc-vs-handoff
  viewer-cell-vs-player-cell contradiction against the decomp: RenderNormalMode 0x453aa0 / update_viewer
  0x00453ce0 / what sets viewer_cell.)
- THEN fix the actual cause (camera-cell-resolution keeping the eye in the player's cell, OR the flood
  reaching the player's cell, OR the mesh seal) — retail-faithful, TDD where the logic is pure,
  visual-verify with the user.

DON'T (§5, evidence-disproven): the flicker is NOT viewer-cell oscillation (Part 2 dead-zone is NOT the
fix); the doorway grey is NOT the portal projection (it projects full-screen while OutsideView is empty);
the boom (Part 1) is not the visible bug. Get a SCREENSHOT/[shell] evidence EARLY; don't declare a fix
before the user's eyes confirm it.

TEST BASELINE: App 187p/0f. Core 1331p / 4f (documented) / 1s. Build green.
```

---

## 8. A note from the outgoing model (honest)

I repeatedly presented fixes with too much confidence and conflated Problem A (doorway grey, which I did
reduce) with Problem B (the cellar/walls shell-sealing, which I did not touch). The user called this out
correctly. The two committed changes are real and test-backed, but the **next model should treat the
user's screenshot symptom (walls + cellar floor grey, interior-transition flicker) as Problem B from the
start**, gather `[shell]`/`[flap]` evidence in the cellar BEFORE proposing anything, and **get the user's
eyes on a sealed result before claiming success.**