acdream/docs/research/2026-06-07-cutover-flip-render-residuals-diagnosis-handoff.md

Handoff — Cutover FLIP shipped; see-through + oscillation DIAGNOSED (evidence-based) — 2026-06-07 (PM)

CANONICAL PICKUP for the render-unification residuals. Worktree thirsty-goldberg-51bb9b, branch claude/thirsty-goldberg-51bb9b, HEAD 774cb22. The cutover flip is SHIPPED (one render path, no branch-toggle flap). It exposed two residuals — see-through building walls and oscillation — whose root causes are now PROVEN with a live probe (not guessed). The fixes are identified but NOT yet implemented. Read §3 (diagnosis) and §5 (do-not-retry) before touching code.

---

1. What shipped (committed, keep)

The CUTOVER FLIP from 2026-06-07-render-unification-cutover-flip-handoff.md landed:

Commit	What
5379f6e	Step A — PortalVisibilityBuilder.Build seeds a full-screen OutsideView when the root is the outdoor node (LoadedCell.IsOutdoorNode, set by OutdoorCellNode.Build). +2 UnifiedFloodTests, +2 flag assertions.
445e861	Step B — the flip: GameWindow.cs:~7387 clipRoot = viewerRoot ?? _outdoorNode. Drops the playerIndoorGate gate. ONE path, no inside/outside branch. Preserves the LiveDynamic draw for the outdoor root.
88caa0d	depth-clear fix — ClearDepthSlice = null for the outdoor root (the full-screen depth clear was painting the cellar over the player; fixed).
774cb22	Revert of 0030dac (the slot-0 skip — a FAILED fix, see §5).

The flip's PRIMARY goal succeeded: [render-sig] shows branch=RetailPViewInside every frame, zero OutdoorRoot frames across a whole session. The two-branch-toggle flap is gone by construction. Baselines: build green, App.Tests 216/0.

---

2. The two residuals the flip exposed (user-observed)

1. See-through building walls from outside — standing outside a building you see into it through the walls (doors closed).
2. Oscillation — the interior/walls flicker between "showing nothing", "see-through", and "full interior" frame-to-frame while standing still.

---

3. ROOT CAUSE — proven by a live [bshell] probe (NOT guessed)

A throttled probe in RetailPViewRenderer.DrawInside (now stripped; re-add from git history of this doc's session if needed) logged, for the outdoor-node root on a loaded frame at the Holtburg cottage:

[bshell] total=6 withMesh=6 inOutdoorPartition=6 envCellsFlooded=1 outdoorEntities=637

Interpretation (each number is decisive):

• total=6 withMesh=6 inOutdoorPartition=6 — there ARE 6 building ModelId "shell" entities (WorldEntity.IsBuildingShell, created in LandblockLoader.cs:75-91 from LandBlockInfo.Buildings[].ModelId), ALL carry meshes, ALL land in partition.Outdoor (they have ParentCellId==null; InteriorEntityPartition line 47 → Outdoor; WbDrawDispatcher.EntityPassesVisibleCellGate returns true for null visibleCellIds). So the ModelId exterior DOES render.
• BUT the earlier "skip all interior shell draws for the outdoor root" experiment (uncommitted, reverted) made the building fully see-through — i.e. drawing ONLY the ModelId shells is NOT a solid building. Therefore the ModelId Setup is a partial frame, and the building's actual WALLS are the EnvCell shell geometry (ObjectMeshManager.PrepareCellStructMeshData, drawn by DrawEnvCellShells).
• envCellsFlooded=1 — in this frame the outdoor-node flood reached ZERO building interior cells (only the node itself). Earlier [render-sig] frames at the same spot showed ids=[node + ~12 building cells] (≈13). So the flood membership swings between 1 and ~13 frame-to-frame.

The two residuals, explained

1. Oscillation = flood instability gating the walls. The flip made wall-drawing depend on the portal flood reaching each building's interior cells. That flood is unstable (1 ↔ ~13), so the EnvCell walls blink in and out. ("showing nothing" = flood=1, no interior; "full interior / see-through" = flood reached the building.)
2. See-through = single-sided EnvCell walls. Even when the walls DO draw, the EnvCell wall polys are single-sided for SidesType==CounterClockwise (interior-facing). PrepareCellStructMeshData (ObjectMeshManager ~1299-1310) builds the back face only for SidesType==None (front twice reversed) and SidesType==Clockwise (neg surface). A CounterClockwise wall = front face only → from outside you see its culled back → see-through.

---

4. Fix path (identified, NOT implemented)

Two independent fixes, both needed:

• F1 — Stabilise the flood membership so a building's interior cells are CONSISTENTLY in/out of the visible set (no 1↔13 swing). This is the same metastability family as the indoor flicker. Likely levers: ground the outdoor-node flood's building membership in the cell stab_list/PVS (stable, precomputed) instead of the per-frame portal-side test + projection; or hysteresis on which buildings are flooded. Probe to re-add: envCellsFlooded per frame (RLE it; it should be constant when standing still).
• F2 — Make the EnvCell walls solid from outside. Either build the missing back faces for SidesType==CounterClockwise walls in PrepareCellStructMeshData, or render those shells double-sided (CullMode.None) when the viewer is outside the cell. Verify against retail: dump a real Holtburg cell's wall-poly SidesType distribution first.

Open research question (reconcile before F2): pre-flip the buildings looked SOLID from outside. What drew the solid walls pre-flip — a global EnvCell-shell render, the DrawPortal/BuildFromExterior look-in, or were the ModelId shells solid then? Find what the flip replaced. The old outdoor else block (GameWindow.cs:~7557-7663, now dead-when-clipRoot-non-null but still present) is the place to read. This answers whether F2 is "build back faces" or "restore a pre-flip draw".

---

5. DO NOT RETRY (failed this session, with evidence)

• Slot-0 skip (0030dac, reverted 774cb22): "for the outdoor root, skip flooded cells whose clip degenerated to no-clip slot 0." Made the oscillation WORSE — slot-0-ness flickers per frame, so cells blinked. Wrong: the see-through is not the slot-0 fallback.
• Skip-all-interiors experiment (uncommitted, reverted): "outdoor root draws terrain + ModelId exteriors only, no EnvCell shells." Made buildings FULLY see-through + flashing — proved the ModelId Setup is not the walls (the walls are the EnvCell shells). Do not ship this.
• Backface-culling-of-shells hypothesis (never coded): plausible but the cull mode is already data-driven (poly.SidesType); the real gap is single-sided geometry (no back face built), not a cull-state bug.
• The subagent hypothesis "ModelId exterior occludes; interior overdraws it; fix = gate DrawEnvCellShells off for the outdoor root" is disproven — that gate IS the skip-all-interiors experiment, which removed the walls entirely.

---

6. State + how to resume

• HEAD 774cb22, tree clean, build green, App.Tests 216/0. The flip + depth-clear are committed; the branch renders with the two residuals (see-through + oscillation).
• The flip is on this BRANCH only (main is unaffected). To get a stable client meanwhile, revert the flip commits (445e861 Step B is the behaviour change; reverting it alone restores the pre-flip outdoor path — verify Step A 5379f6e is inert without it).
• Re-add the [bshell] / envCellsFlooded probe (see this session's git reflog for the exact code) to watch flood stability while working F1.
• Memory: project_indoor_flap_rootcause (update with this corrected diagnosis), reference_render_pipeline_state, feedback_render_downstream_of_membership (the oscillation IS a membership/flood-stability bug, per that note).