acdream/docs/research/2026-07-08-186-connector-grey-flap-handoff.md

Handoff: #186 — indoor GREY flap at a top-floor connecting room (new house type)

Date: 2026-07-08 · Status: ROOT CAUSE NARROWED (report-only) — fix NOT started. It lives in the FROZEN portal-flood / viewer-cell render code (the doorway-FLAP family that cost weeks), so it needs a retail cdb trace to pin the last fork BEFORE any code, then a careful change. Milestone: M1.5.

Read these first, in order:

1. This handoff.
2. claude-memory/project_render_pipeline_digest.md — the render/doorway-FLAP SSOT + DO-NOT-RETRY table ("root at VIEWER cell"; the deleted EyeInsidePortalOpening rescue; PortalSideEpsilon root-lag).
3. docs/architecture/retail-divergence-register.md rows AD-17 (≤8 clip-plane / union-AABB scissor), AD-20 (camera-sweep fallback seeds eye cell from PLAYER cell), AD-21 (null-clipRoot outdoor fallback).
4. docs/ISSUES.md #186.

---

0. Symptom (user, live)

Top floor of a house type not tried before; a connecting opening/room between two parts of the house. Passing through → a brief GREY flap (the framebuffer clear color). Stopping at the precise spot → the WHOLE screen is grey and stays; turning the camera clears it, turning back → grey again (camera-DIRECTION dependent, player stationary). A jump is NOT involved (that's #185). Retail is SEAMLESS at the same spot (user-confirmed) → this is a real acdream bug, not inherent.

1. The cells + the grey pose (ACDREAM_PROBE_FLAP capture)

Landblock 0xF682. Three cells, all envId 0x0365, cell-struct origin (132,84,62):

cell	render polys	physics polys	portals	role
0xF6820116	15	12	→0117,0118,0113	player's room (closed)
0xF6820117	10	6	→0118,0116,0115,0119	next room (closed)
0xF6820118	5	3	→0117,0116	thin connector (root when grey)

Grey-pose facts (from [flap]/[flap-cam]/[flap-sweep], 88,249 frames; the grey frames are vis=1 root=0xF6820118, ~6,725 frames):

• [flap-cam]: root=viewerCell=0xF6820118 playerCell=0xF6820116 eyeInRoot=Y playerInRoot=n terrain=Skip outVisible=False eye=(134.81,83.59,69.07) player=(137.30,83.32,66.82).
• [flap] grey line: root=0118 | p0->0x0117 D=0.14 TRV proj=4 clip=0 | p1->0x0116 D=0.18 CULL proj=5 clip=4 || outPolys=0 vis=1. (Dominant D to 0117 ≈ 0.14; ALWAYS positive 0.00–0.50 → eye is genuinely INSIDE 0118, never across the plane.)
• [flap-sweep]: ok=True resolved=Y pulledIn=-0.00 (the chase boom reaches FULL distance, NO collision pull-in, seating the eye in the connector).

Read of the geometry: the eye sits in the sparse connector 0118, in the doorway threshold, looking BACK toward the player's room 0116. p1->0116 is ON-screen (proj=5 clip=4) but side-CULLED (eye ~0.18–0.31 on 0116's side of the p1 plane — a back-portal). p0->0117 is genuinely OFF-screen (clip=0 with proj≥3 = off-screen per the builder's own probe doc, PortalVisibilityBuilder.cs:818-821). So no neighbour floods, only the 5-poly connector draws, and its shell doesn't cover the forward view → the framebuffer clear color (fog, GameWindow.cs:8968) shows through = GREY. Turning re-aims off the back-portal → a room floods → picture.

2. What is CONFIRMED / RULED OUT (workflow wf_362bbeda-933, 4 tracers + synthesis, + my own re-checks)

• ❌ NOT null viewer-root / AD-21 — the render root is a valid indoor cell on 88,248/88,249 frames (one lone [outdoor-node] root=OUT). (This refutes THE FIRST hypothesis in this investigation.)
• ❌ NOT viewer-cell root-lag / AD-20 — eyeInRoot=Y at every grey frame: the eye is geometrically INSIDE 0118's BSP. The root is the fresh eye-derived swept curr_cell (PhysicsCameraCollisionProbe.cs:92), NOT a stale player-seeded fallback. (Refutes the workflow synthesis's own leading "31 cm gap" theory — the eye is NOT across the boundary; I checked the eyeInRoot flag directly.)
• ❌ NOT the flood-admission being unfaithful — the empty-clip cull (PortalVisibilityBuilder.cs:320-324) and the back-portal side-CULL (:292-298, CameraOnInteriorSide :857-863) are faithful ports: retail PView::ClipPortals gates neighbour processing on if (ecx_8 != 0) (pc 005a5660) and AddViewToPortals on view_count != 0 (pc 005a5357). #177 already proved acdream's flood is retail-identical.
• ❌ NOT the color clear (the tempting "3-line fix" — DEAD END, do not revisit). Retail's DrawCells (0x005a4840, decomp line 432709) has its only Clear INSIDE if (outside_view.view_count > 0) (line 432715), right AFTER LScape::draw (the landscape draw, 432719). The Clear is Clear(4, &RGBAColor_Black, 1.0f) (0x820fc0 = RGBAColor_Black) — but clearing COLOR after drawing the landscape would erase it, so that 4 flag is depth/stencil, not color. So retail's color clear is NOT gated here, and matching "don't color-clear a sealed interior" would be WRONG. (This is why I did the cdb prep — it killed a wrong fix before shipping.)
• ✅ It IS a real acdream bug (retail seamless) in the doorway-FLAP flood/pick family: acdream drops the room the camera looks back at (0116) from the connector root; retail keeps it drawn.

3. THE ONE OPEN FORK → the retail cdb trace (do this FIRST in the new session)

Retail is seamless, so retail either (A) roots at the player's room 0116, not the connector (a viewer-cell PICK divergence — acdream over-switches to 0118), or (B) roots at 0118 but its flood still admits 0116 (a FLOOD divergence — retail keeps the back-portal / uses an on-screen sliver acdream drops). Static decomp cannot decide; observe retail.

Toolchain (CLAUDE.md "Retail debugger toolchain"; binary CONFIRMED pairs with refs/acclient.pdb via py tools/pdb-extract/check_exe_pdb.py "C:/Turbine/Asheron's Call/acclient.exe" → MATCH).

• User: launch retail, connect to local ACE, walk to the SAME connecting room, and HOLD the grey pose (so most captured frames are it).
• bp acclient!SmartBox::update_viewer (0x00453ce0) → dump viewer_cell (a CObjCell*, acclient.h:35194) and its cell id. AND/OR bp acclient!PView::DrawCells (0x005a4840) → dump cell_draw_num + cell_draw_list.data[] ids (acclient.h:45939-45940) — the drawn cell set.
• Decide: retail viewer_cell == 0116 → PICK fix (acdream's viewer-cell pick/hysteresis over-retains the connector — CellTransit.cs:862-916 BuildCellSetAndPickContaining, or the camera boom coasting the eye into the connector at pulledIn=-0.00 where retail's PathClipped viewer_sphere sweep hard-stops in 0116). retail viewer_cell == 0118 but cell_draw_list ⊇ 0116 → FLOOD fix (retail admits the back-portal from the connector; acdream's side-CULL / the deleted EyeInsidePortalOpening rescue is the site).
• cdb watchouts (CLAUDE.md): qd ONLY at a top-level threshold, never inside a conditional bp action (strands cdb → kills retail); dt acclient!Class @ecx field for reads (@@c++ is broken here); .sympath <local> (no srv*, the ; splits); spaced .if () lets qd detach.

4. Apparatus (re-create in the new session — temp files won't persist)

• Flap capture: launch acdream with ACDREAM_PROBE_FLAP=1 (canonical live cmd, CLAUDE.md). Emits per frame: [flap] (root + per-portal proj/clip/side, PortalVisibilityBuilder.cs:790), [flap-cam] (root/viewerCell/playerCell/eyeInRoot/playerInRoot/terrain/outVisible, GameWindow.cs:11142-11152), [flap-sweep] (ok/resolved/pulledIn/viewerCell, PhysicsCameraCollisionProbe.cs:74-87), [outdoor-node] (root=IN/OUT). ⚠️ heavy (per-frame); output goes to the raw background-task .output, not the Tee'd log. Have the user HOLD the grey pose + turn to clear + turn back a couple times.
• Offline cell geometry dump: tests/AcDream.Core.Tests/Physics/Issue186ConnectorCellGeometryInspectionTests.cs (Dump_ConnectorCells_ShellAndCollision) loads 0116/0117/0118 from the dat and prints render/physics poly counts + normal-axis buckets. No live launch needed. (That's how the §1 table was produced.)
• Decomp workflow: wf_362bbeda-933 (this session) — the 4-tracer + synthesis analysis; results in its journal under the session's subagents/workflows/ dir.

5. DO-NOT-RETRY (each already refuted or a known trap)

• Do NOT re-open the null-root / AD-20 / AD-21 angle — root is valid, eyeInRoot=Y.
• Do NOT implement the color-clear gating — retail's gated Clear is depth/stencil (post-LScape::draw); matching it would add non-retail stale-content.
• Do NOT re-add the deleted EyeInsidePortalOpening rescue (PortalVisibilityBuilder.cs:314-319) blindly — it caused the 0171↔0173 flood-cycle churn (the ORIGINAL doorway flap).
• Do NOT widen PortalSideEpsilon (:38-56) — a documented root-lag band, NOT retail (F_EPSILON=0.0002); BR-4 refuted tightening/widening without eye-exact tracking.
• Do NOT "fix" the flood by propagating an empty/edge-on portal — the empty-clip cull is retail-faithful.
• The sparse connector geometry (0118 = 5 render / 3 physics polys) is FAITHFUL to the dat (retail draws the same). It is context, not the bug — the bug is that 0116 isn't drawn, not that 0118 is thin.

6. Key code sites

• Frame-top clear (unconditional color+depth+stencil to fog): GameWindow.cs:8968-8983. NOT the fix.
• Viewer-cell resolution: GameWindow.cs:9137-9148 (viewerCellId = _retailChaseCamera.ViewerCellId).
• Camera boom sweep: PhysicsCameraCollisionProbe.cs (SweepEye, PathClipped, pulledIn, r.CellId=curr_cell).
• Viewer-cell PICK: CellTransit.cs:862-916 (BuildCellSetAndPickContaining, center-based point_in_cell, current-cell-first hysteresis, port of find_cell_list pseudo_c:308788-308825).
• Portal FLOOD: PortalVisibilityBuilder.cs (Build; side-test CameraOnInteriorSide :857-863; empty-clip cull :320-324; PortalSideEpsilon :38-56; the off-screen-vs-sliver note :818-821).

7. Retail decomp anchors

• PView::DrawCells 0x005a4840 (decomp line 432709): Clear gated on outside_view.view_count>0 (432715), Clear at 432732 (depth/stencil, post-LScape::draw); cells drawn unconditionally after (432815+).
• SmartBox::update_viewer 0x00453ce0: viewer_cell = sphere_path.curr_cell (the render root = swept cell).
• PView::ClipPortals empty-clip gate if(ecx_8!=0) pc 005a5660; AddViewToPortals view_count!=0 pc 005a5357.
• PView::InitCell side test decomp:432962. RGBAColor_Black @ 0x820fc0.

8. Acceptance

• No grey flap passing through OR stopping in the connecting room at any camera angle; matches retail's seamless.
• Regression: the outside→inside doorway + other multi-room houses + the #177/#181 render-flap suites unchanged.

9. Context: this session also FIXED #185 (unrelated, DONE + gated)

The outdoor-stairs "invisible wall" (07c5b832) — a shadow part-id uint32 overflow dropping stair collision. Unrelated to #186 (that was collision/registration; #186 is render/visibility). See docs/superpowers/specs/2026-07-08-185-outdoor-stairs-fix-design.md.