acdream/docs/research/2026-07-06-177-stairs-pickup-handoff.md

🅿️ SUPERSEDED 2026-07-07 — #177 is PARKED and this doc's premise is WRONG. The "portal-visibility miss" framing below was DISPROVEN by a live retail cdb trace (retail's flood collapses identically to ours). Do NOT follow the flood/clip workflow here. Current truth + the fresh lead (step statics) live in ISSUES #177 (session-3 + 3b blocks) and the render digest top banner. Kept only for the apparatus map.

Pickup handoff — #177 dungeon stairs pop in/out (portal-visibility miss at the stair cells)

Paste the companion prompt (bottom) into a fresh session. Read this file, then claude-memory/project_render_pipeline_digest.md (top banners), then ISSUES #177 (full entry — including the superseded lighting attribution and why it was re-attributed to VISIBILITY at the 2026-07-06 gate).

TL;DR — what #177 is

Facility Hub (0x8A02), the staircase connecting two levels (corridor 0x0178 → ramp 0x0182 → lower room 0x0183): (a) invisible looking into the stair room from the corridor, (b) pops into existence on entering the room, (c) the last step vanishes running down. The 2026-07-06 gate PROVED this is NOT lighting (the A7 visible-cell light fix shipped and the stairs were still missing looking back from the corridor) — it is a portal-flood admission miss: the stair cells are not reached by PortalVisibilityBuilder from the viewer's cell until the viewer crosses in. The digest tags it "#119 class, dungeon edition; floor-portal level links."

Acceptance: the staircase renders whenever its room is visible through the connecting opening, and stays rendered through the full descent.

Where to start (the apparatus already exists)

1. tests/AcDream.App.Tests/Rendering/Issue176177FacilityHubFloodReplayTests.cs — headless flood replays against the REAL dat, with two scenarios written for exactly this issue and never fully mined:
   • Scenario A (stair approach): eye in corridor 0x0178 at several x positions + pitches, printing whether ramp 0x0182 / lower 0x0183 are admitted.
   • Scenario B (descent): eye path down the ramp, printing per-step admitted-set diffs (the "last step vanishes" case). Run these FIRST — the miss should reproduce headlessly, and the printed admitted sets name which portal hop fails.
2. Issue181VisFlapReplayTests.cs — the same-file pattern for perturbation sweeps + per-cell view-region AREA measurement (the shoelace diagnostic). Cell 0x8A020181 — right next to the stair complex 0x0182/0x0183 — rides a knife-edge zero-area admission; the #177 miss and the #181 sliver are plausibly the SAME flood defect seen two ways (a floor-portal chain that clips to nothing from above).
3. The builder: src/AcDream.App/Rendering/PortalVisibilityBuilder.cs. The admission gates per portal hop, in order: the side test (CameraOnInteriorSide, PortalSideEpsilon 0.01 — AP-19), then ClipPortalAgainstView (homogeneous clip against the parent's accumulated region; clippedRegion.Count == 0 ⇒ the flood stops there). For a DOWNWARD stair chain the suspect class is the FLOOR-portal hop: a horizontal portal seen edge-on from the corridor clips to ~zero area (exactly the 0x0181 sliver signature) and the chain below never floods. ACDREAM_A8_DUMP_PV=1 dumps per-portal census + EXIT-PROJ/EXIT-CLIP lines for the camera cell (first 2 builds per cell).
4. Retail oracle: retail PView floods portals with per-poly clip (polyClipFinish — the W=0 clip pseudocode doc 2026-06-11) and DOES show stair rooms through their openings. If our clip collapses a genuinely-visible aperture to zero, compare ClipPortalAgainstView against PView::ClipPortals/GetClip (decomp:433572) at the failing hop's exact geometry. #119's lesson applies: visibility must derive from the same data that gets drawn (feedback_culling_bounds_from_drawn_data).

What tonight's #180/#181 session gives you for free

• All camera/sweep mechanisms are Ghidra-verified faithful (stateful sought, adjust_to_plane, adjust_sphere_to_poly, viewer radius-anchored stepping) — commits 48aaab81/f10fe4e9/3f34bca0. The camera's ViewerCellId is trustworthy; the render roots at it (Option A).
• The wall-pressed camera wanders ~0.5 mm/frame in a bit-exact 12-frame limit cycle (Issue181WallPressEquilibriumTests — measured, all local algorithms verified; plausibly retail-class). Any admission knife-edge within that wobble band flaps ~10 Hz ([flap] vis 31↔32, whole-session). For #177 this matters at stair THRESHOLDS: expect flappy admission exactly at descent transitions.
• Lighting is now retail-shaped: resident+player-anchored pool (d8984e87), idempotent re-apply (87cddce2), stationary fixtures on the verified static curve (233b469b). Do NOT re-open lighting for #177 — the gate already refuted it.
• #181 is PARKED (see its ISSUES entry for the still-open leads). Do not resume it inside the #177 arc; if stair work surfaces new flicker evidence, append to #181's entry instead.

Watchouts

• The old #177 root-cause text (128-cap light eviction) is SUPERSEDED — kept in the entry for history. The re-attribution is the ⚠️ UPDATE block at the top of #177.
• The flood replay's ViewProj must match production FOV/aspect (π/3, 16:9) — the Issue181 test does; the older Issue176177 scenarios use 1.2 rad / 1280×720 (fine for admission questions, but keep in mind for NDC-sensitive comparisons).
• Issue120ReciprocalPingPongTests.LoadAllInteriorCells + CornerFloodReplayTests. ResolveDatDir are the shared fixtures loaders (App.Tests); Core.Tests has its own ConformanceDats.
• A client may be running — the user manages its lifecycle; ASK before rebuilding if the App DLL is locked (MSB3027 = lock, not code).

State

• Branch claude/vigorous-joliot-f0c3ad @ 233b469b+ (this handoff's commit). Suites green: Core 2600+2skip / App 733+2skip / UI 425 / Net 385 / Content 56.
• Test char spawns in the Facility Hub corridor (0x8A020142 area); the stair complex is 0x0178/0x0182/0x0183 (+0x0181 adjacent).
• Launch recipe + graceful-close rules: CLAUDE.md "Running the client". The GDI-capture + keybd_event autonomous visual loop scripts live in this session's scratchpad (capture-still.ps1, imgdiff.ps1, imgdiffmap.ps1, crop.ps1) — recreate from the #180 handoff's recipe if the scratchpad is gone.

Companion prompt (paste into the fresh session)

Fix #177 — Facility Hub stairs pop in/out across levels (invisible from the
corridor, pop on entry, last step vanishes running down). The 2026-07-06 gate
re-attributed this from lighting to a PORTAL-FLOOD ADMISSION MISS at the stair
cells (0x8A020178 corridor → 0x0182 ramp → 0x0183 lower; 0x0181 adjacent) — do
NOT re-open lighting (gate-refuted; the A7 fixes are in and verified).

READ FIRST, in order:
1. docs/research/2026-07-06-177-stairs-pickup-handoff.md (apparatus map, the
   #181 park boundary, watchouts)
2. claude-memory/project_render_pipeline_digest.md (top banners)
3. docs/ISSUES.md #177 (the ⚠️ UPDATE block supersedes the old root cause)

START by running the existing headless replays (Issue176177FacilityHubFloodReplay
Tests Scenarios A/B — real dat, no client): they print per-pose admitted sets for
the stair cells and should reproduce the miss offline. Then trace the failing
portal hop through PortalVisibilityBuilder's gates (side test → ClipPortalAgainst
View; the floor-portal seen edge-on clipping to ~zero area is the suspect class —
the same signature as #181's 0x0181 sliver next door). Retail oracle for the clip:
PView::ClipPortals/GetClip (decomp:433572) + the 2026-06-11 polyClipFinish W=0
pseudocode doc. Workflow: replay → identify the gate → read retail → pseudocode →
port → the replays become pins → autonomous visual loop (stair approach/descent
drive) → user gate.

#181 (the pressed-camera flicker) is PARKED with its evidence ledger in ISSUES —
if stair work surfaces flicker evidence, append there; don't resume it in this arc.

State: branch claude/vigorous-joliot-f0c3ad, suites green (Core 2600+2skip / App
733+2skip). Test char spawns in the Facility Hub corridor. A client may be
running — the user manages its lifecycle; ASK before rebuilding if the App DLL
is locked.