acdream/docs/research/2026-07-06-176-177-handoff-A7-lighting.md

Pickup prompt — #176/#177 root-caused, deferred to A7 dungeon lighting (paste into a fresh session)

Read claude-memory/project_render_pipeline_digest.md FIRST (top banner is the #176/#177 outcome + DO-NOT-RETRY), then ISSUES #176 and #177, then this file. Then read roadmap Phase A7 (docs/plans/2026-04-11-roadmap.md §"Phase A7 — Indoor lighting fidelity") — this session effectively pre-paid A7's analysis for the light-cap slice.

Where we are (2026-07-06 end of session)

Currently working toward: M1.5 — Indoor world feels right. Critical path: #137 dungeon collision (DONE, gated), #138 teleport-OUT, A7 dungeon lighting (#79/#93 + now #176/#177).

HEAD = d591e3bb on main AND branch claude/vigorous-joliot-f0c3ad (fast-forwarded, in sync). Working tree clean. All suites green (Core 2591 + 3 skip / App 719 + 2 skip / UI 425 / Net 385).

Three commits this session:

Commit	What
b8e9e204	#176/#177 investigation: 12 mechanisms refuted, apparatus shipped, probe protocol staged
4d25e04d	fix attempt: MaxGlobalLights 128→1024 (stops the pops) — REVERTED
d591e3bb	revert to 128 + full deferral docs (register AP-85 rewritten, ISSUES back to OPEN, digest DO-NOT-RETRY)

A client may still be running (launch-176-revert-check.log) — the user manages lifecycle. It is on the reverted 128 baseline (rooms normal, seam flashes present = the still-open issue).

THE ROOT CAUSE (confirmed, not a hypothesis)

#176 and #177 are ONE bug: per-cell 8-light SET COMPOSITION churning under a camera-nearest snapshot cap. LightManager.BuildPointLightSnapshot keeps only the MaxGlobalLights=128 point lights nearest THE CAMERA; the Facility Hub registers 366 fixtures, so 238 are evicted per frame by camera distance. SelectForObject (the faithful per-object 8-cap, retail minimize_object_lighting 0x0054d480) can only choose from the surviving 128 — so an in-range torch of a VISIBLE cell that ranks past the cap drops out of that cell's 8-set, and the cell's per-vertex Gouraud lighting flips as the camera moves.

• #176 — the flipping unit is a CELL → discontinuities at exactly cell-seam granularity; camera-angle dependent (the chase boom swings the camera position, re-ranking the 128); the dominant flipping light is the under-room PORTALS' purple → purple flashes on the floor at seams.
• #177 — a stair room whose fixtures ALL rank past the cap renders at bare 0.2 ambient (near-black = "not visible from the corridor"); approach re-admits them ("pops into existence"); the eviction boundary sweeping during the descent strips the ramp's lights ("disappears on the last step"). The geometry never vanished — its LIGHTS did.

How it was confirmed (the discriminator): the user reproduced the flash while [light] (ambient branch — stable 0.2 grey) AND [pv-input] (portal flood — zero drops in 54k frames) read provably healthy in the probe log. That eliminated every CPU signal the probes COULD see and left the one they can't: set composition ([light] prints counts, not membership). The log's headline number — registeredLights=366 vs cap 128 — closed it.

WHY THE FIX IS DEFERRED (do not re-raise the cap alone)

Uncapping (128→1024, 4d25e04d) stopped the pops but the full 366-fixture pool exposed three UNPORTED retail lighting semantics that then dominated the Hub — this is why it was reverted (user: "rooms have no textures" → actually a magenta light wash over intact textures; then "purple stripes… something fighting to draw the purple lightning over the floor"):

1. Light-through-solid-floors. Retail registers lights per-CELL (insert_light 0x0054d1b0); a light belongs to a cell and only lights that cell's geometry. Our snapshot is a flat world-space sphere-overlap with NO reach/occlusion notion → the under-room portals' purple light washed the corridors ABOVE them. This is the big one. The 128 cap accidentally MASKED it by keeping the pool camera-local (far under-room lights fell off the list before they could reach up).
2. Fixture falloff curve misassignment. Stationary weenie fixtures (ACE serves dungeon lanterns/braziers as CreateObject weenies) register via the isDynamic:true path → D3D 1/d falloff (LightInfoLoader.cs:89, GameWindow weenie-light block ~3688). Retail bakes STATIONARY fixture light with the static 1/d³ curve (calc_point_light 0x0059c8b0, static_light_factor 1.3). 1/d is ~9× stronger at 3 m → every pool over-broad + over-saturated. The isDynamic flag should be reserved for genuinely MOVING lights (portal swirls, projectiles); a stationary fixture — even server-spawned — is static.
3. Striped floor z-fight-like artifact. User's 2nd screenshot: regular magenta bands across one floor region, "like something is fighting to draw the purple over the floor." NOT attributed. Ruled out: not coincident dat geometry (the CorridorNeighborhood_CoplanarOverlappingDrawnPolyPairs sweep found only the legit z=−12 under-hall floor quad-fan, nothing near the −6 corridor floor); not a striped texture (all corridor surfaces are plain Base1Image stone 0x08000375/6/7/8). Leading guess: two draws of the same floor with DIFFERENT light sets (the per-cell-vs-per-something set assignment splitting), or an MDI instance-order/light-set-index desync exposed only when the purple light is stably present. Hunt this in A7 with the full pool temporarily on — it's invisible at cap 128.

THE A7 FIX SHAPE (the real fix, in order)

1. Port per-cell light registration (insert_light 0x0054d1b0 + the per-cell light list retail keeps). A light lights its OWN cell's geometry + cells reachable through portals — NOT arbitrary world-space overlap. This kills #1 (through-floor) and makes the global pool cap irrelevant (per-cell sets are naturally bounded), which is what actually lets #176/#177 close.
2. Static curve for stationary fixtures. Decide isDynamic by whether the light MOVES, not by dat-static-vs-weenie origin. A server-spawned wall lantern is stationary → static 1/d³. (Register AP-67/AP-44 are the weenie-light path; AP-85 is the pool cap; #143 is the curve-by-path decision to revisit.)
3. Hunt the stripes with the full pool on (see #3 above).
4. THEN uncap MaxGlobalLights — un-skip LightManagerTests.PointSnapshot_HubScaleLightCount_ObjectSelectionIsCameraInvariant (it asserts the retail end-state: an in-range light of a cell is never camera-evicted).

Tooling built this session (reuse, don't rebuild)

• tests/AcDream.Core.Tests/Rendering/Issue176177DungeonSeamInspectionTests.cs — dat truth for the Hub: portal-poly draw verdicts, reciprocal coincidence, stair geometry owner (0x8A020182's ramp shell, vertical portals, ZERO statics), CellBSP containment (partitions exactly at portal planes), under-hall + corridor drawn-poly surface colors, DXT1 alpha histograms (0 transparent texels), and CorridorNeighborhood_CoplanarOverlappingDrawnPolyPairs (the stripe-geometry sweep — came back empty for the −6 floor).
• tests/AcDream.App.Tests/Rendering/Issue176177FacilityHubFloodReplayTests.cs — production-matched portal-flood replays (approach/descent/gaze-sweep/walk + the ScenarioE incoherent-root sensitivity pin). Flood is HEALTHY — do not re-investigate it for these issues.
• tests/AcDream.Core.Tests/Physics/Issue176177SeamTransitLagTests.cs — resolver cell-flip is plane-exact (membership is NOT the bug).
• LightManagerTests.PointSnapshot_HubScaleLightCount_* — Skip'd end-state pin (RED@128, GREEN@1024).
• Ledger: docs/research/2026-07-06-176-177-render-pair-investigation.md (13 refuted mechanisms + the probe-run discriminator + the OUTCOME banner).

Live probe env (all zero-cost off; use for the A7 spike)

ACDREAM_PROBE_LIGHT=1      # [light] insideCell/ambient/sun/registeredLights/activeLights — rate-limited
ACDREAM_PROBE_PVINPUT=1    # [pv-input] one line/frame: exact flood inputs + count
ACDREAM_PROBE_CELL=1       # [cell-transit] timeline anchors
ACDREAM_PROBE_TEXFLUSH=1   # [tex-flush] staged-upload drain (proves #105 healthy: after=0)

A7.L1's planned [indoor-light] probe (per-cell active-light dump: position, color, attenuation, direction) is the natural next apparatus — it prints exactly the SET COMPOSITION the current [light] counts can't. Build it FIRST.

Launch protocol (unchanged)

dotnet build green first; PowerShell launch with the CLAUDE.md env block (+ the probes above), background + Tee to launch-*.log. User manages client lifecycle (graceful close → ACE clears in ~5 s; hard kill → ~3 min). Strip \000 before grep (PowerShell Tee = UTF-16): tr -d '\000' < launch.log | grep .... Test char spawns near 0x8A020179 (the ramp corridor); the 015E↔017A corridor loop is the #176 repro; look-into + descend the 0178→0182→0183 stairs for #177.