docs(lighting): A7 Fix D investigation RESOLVED + implementation spec (#140)

Resolve the Fix D contradiction with decomp (workflow wf_f660eb88 + adversarial
verify) + 4 live cdb captures. The D3D-FF model was the WRONG oracle: retail has
TWO light systems — STATIC torches BAKE into wall vertices (calc_point_light,
triple-clamped: range gate + per-channel min(scale*color,color) + per-vertex
[0,1] from black), DYNAMIC lights go D3D hardware. The captured intensity=100 is
the purple PORTAL (magenta, dynamic), not a wall torch. Ground truth: 38 static
warm torches (orange (1,0.588,0.314)/cream, intensity=100, falloff 3-5) + 2 dynamic.

acdream over-brightness = two confirmed bugs: D-1 mesh_modern.vert folds
ambient+sun+torches into one UNCLAMPED accumulator (single frag clamp) -> warm
blowout; D-2 EnvCellRenderer never binds SSBO 4/5 so the cell shell reads a leaked
light set. Spec: D-1 in-shader clamp-split (clamp the torch sum on its own before
ambient/sun); D-2 bind the shell's own per-cell light set (mirror WbDrawDispatcher);
LightBake.cs is the C# conformance oracle. Adds the 4 reusable cdb capture scripts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/research/2026-06-18-lighting-a7-fixABC-shipped-fixD-handoff.md

@@ -45,57 +45,83 @@ was wrong (Fix C). Don't re-investigate the purple.
 
 ---
 
-## OPEN — Fix D: outdoor OBJECTS too bright near torches
+## RESOLVED — Fix D: outdoor walls too bright near torches (contradiction settled 2026-06-18)
 
-**Symptom (user, 2026-06-18):** the Holtburg meeting-hall walls blow out warm/bright
-in acdream vs dim in retail. Fix A/B/C did NOT touch this. It's the per-object
-point-light **contribution on objects**.
+**Symptom (user):** Holtburg meeting-hall walls blow out **warm**/bright in acdream
+vs dim in retail. The contradiction ("D3D-FF math says color×100 should blow WHITE,
+yet retail is DIM") is **resolved**: the D3D-FF model was the WRONG ORACLE for these
+walls. Settled by a 5-thread decomp workflow (`wf_f660eb88`) + adversarial verify +
+4 live cdb captures. **⚠ The "DO NOT port the D3D-FF model" warning still stands** —
+not because it'd be too bright, but because it's the wrong path entirely.
 
-### Grounded (cdb + decomp) — retail's object point-light path
-`Render::config_hardware_light` (0x0059ad30) builds the `D3DLIGHT9`:
-- `Diffuse = color × intensity`
-- `Attenuation = (0, 1, 0)` ⇒ **1/d** (inverse-LINEAR; acdream's `calc_point_light`
-  is `~1/d²` via norm = distsq·d)
-- `Range = falloff × rangeAdjust`, **`rangeAdjust = 1.5`** (0x00820cc4) ⇒ torch Range
-  = 6×1.5 = **9 m** (LARGER than acdream's falloff×1.3 = 7.8 m — range is NOT why
-  we're brighter)
-- live `LIGHTINFO` captured: torch `type=0 intensity=100 falloff=6`; a 2nd light
-  `intensity=2.25 falloff=10`
-- `d3d_material.Diffuse = (1,1,1)` white (decomp 0x00539774)
+### Render path (Ghidra xrefs — unambiguous, two SEPARATE light systems)
+- **STATIC lights → CPU vertex BAKE.** `RenderDeviceD3D::DrawEnvCell` (0x0059F170) →
+  `D3DPolyRender::SetStaticLightingVertexColors` (0x0059CFE0) → `calc_point_light`
+  (0x0059C8B0, its SOLE caller). Wall torches are STATIC objects → baked into vertex
+  colours. AC town buildings are EnvCell structures, so their walls take this path.
+- **DYNAMIC lights → D3D hardware FF.** `add_dynamic_light` → `insert_light` (0x0054D1B0)
+  → `config_hardware_light` (0x0059AD30); `minimize_envcell_lighting` (0x0054C170)
+  enables ONLY the dynamic subset (class 2) for the cell — statics are NEVER hardware-
+  enabled for the cell. (`minimize_object_lighting` 0x0054D480 enables both, for free
+  GfxObjs.) So `config_hardware_light` — where last session's `intensity=100` was seen —
+  carries DYNAMIC lights for cells, not the wall torches.
 
-### THE CONTRADICTION (resolve this FIRST next session)
-By `mat(1)×color×100×(N·L)×(1/d)`, a torch 3 m away = `color×33` ⇒ retail's walls
-SHOULD blow to **WHITE** — but they're **DIM**. Material diffuse, range, and
-intensity are all captured and ruled out. So the scaling lives in the building's
-**RENDER PATH**, which is unknown. **⚠ DO NOT port the D3D-FF model — by this math it
-would make objects BRIGHTER (white), the opposite of the fix.**
+### Why retail stays warm-but-DIM (the bake is triple-clamped — `calc_point_light`)
+Per light: `range = falloff×1.3` hard gate; half-Lambert wrap `(1/1.5)(N·D + 0.5·d)`;
+`norm = (distsq>1)? distsq·d : d` (~1/d²); `scale = (1−d/range)·intensity·(wrap/norm)`;
+then the **decisive per-channel cap `result = min(scale·color, color)`** — one light adds
+**at most its own (sub-1.0, warm) colour**, however large intensity is. Caller sums from
+**BLACK** (no ambient/sun in the accumulator) over all static lights, then **clamps the
+sum to [0,1]** per channel before packing `vertex.diffuse`. White needs many in-range
+lights stacking past 1.0; a hall has a handful, each warm-capped.
 
-### The decisive next capture
-Determine the static building's ACTUAL render path:
-- **Hypothesis (a) — MOST LIKELY:** static buildings DON'T use D3D hardware lighting.
-  They use the `D3DPolyRender::SetStaticLightingVertexColors` BAKE (0x0059cfe0 →
-  `calc_point_light`), like EnvCells. The `config_hardware_light` lights I captured
-  were for a DIFFERENT object (player / creature / the purple PORTAL — note the
-  `intensity=100` could be the portal, not the wall torch). If (a) holds, acdream's
-  `calc_point_light` is the RIGHT model and the over-brightness is the **per-channel
-  cap** (`min(scale×col,col)` lets several torches each reach full colour and sum to
-  white) and/or **too many torches selected** per object and/or a missing clamp step.
-- **Hypothesis (b):** `D3DRS_LIGHTING` off / lights not `LightEnable`'d for the
-  building draw.
-- **How to capture:** break at `SetStaticLightingVertexColors` (0x0059cfe0) and see
-  whether it's called for the building's mesh (confirms the bake path); and/or
-  inspect the render state around the static-object `DrawIndexedPrimitive`
-  (`D3DRS_LIGHTING`, which lights are enabled). Also: at `config_hardware_light`,
-  dump WHICH object/owner the light is being configured for to identify whether the
-  `intensity=100` light is the torch or the portal.
+### Live cdb ground truth (4 captures; scripts in `tools/cdb/a7-fixd-*.cdb`)
+`Render::world_lights` @ **0x008672a0** (LightParms): `num_static_lights` @ +0x104,
+`sorted_static_lights[]` (RenderLight*, info @ RL+0x70) @ +0x3498, `num_dynamic_lights`
+@ +0x3588. Captured standing in Holtburg:
+- **num_static_lights = 38**, **num_dynamic_lights = 2.**
+- **2 DYNAMIC** (`add_dynamic_light`, d3dIdx 1–2): viewer light `intensity=2.25 falloff=10
+  color=(1,1,1)` white; **PORTAL** `intensity=100 falloff=6 color=(0.784,0,0.784)` MAGENTA.
+  → **the `intensity=100` light is the purple PORTAL (dynamic/hardware), NOT a wall torch.**
+- **38 STATIC** wall torches, all `type=0 intensity=100`, **WARM**: orange
+  `(1.0, 0.588, 0.314)` falloff 4, and cream `(0.980, 0.843, 0.612)` falloff 3–5
+  (→ bake range ~3.9–6.5 m). Torches DO carry intensity=100, but the per-channel cap
+  pins each to its warm colour ⇒ retail walls go warm, not white.
 
-### acdream side — where the fix lands
-- acdream runs `calc_point_light` (wrap/norm + per-channel cap) for ALL meshes via
-  `mesh_modern.vert` `pointContribution` (objects AND cells — Fix A).
-- If buildings use the bake, the likely fix is in the **cap / sum / count**, not the
-  attenuation model. Files: `src/AcDream.App/Rendering/Shaders/mesh_modern.vert`
-  (`pointContribution` + `accumulateLights`), `src/AcDream.Core/Lighting/LightManager.cs`
-  (`SelectForObject`), `LightBake.cs` (verbatim calc_point_light, still unwired).
+### acdream's actual bug — TWO real causes (both verified in source)
+- **D-1 (math, primary): unclamped accumulator folding ambient+sun+torches.**
+  `mesh_modern.vert` `accumulateLights` starts `lit = uCellAmbient.xyz` (:184), ADDS
+  sun (:196), ADDS each capped torch (:206), returns UNCLAMPED (:208); the ONLY clamp is
+  one `min(lit,1.0)` in `mesh_modern.frag:92` AFTER a lightning bump (:89). The per-light
+  cap (:180) IS faithful. But pouring ambient + sun + up-to-8 intensity-100 WARM torches
+  into ONE bucket and trimming only at the end overflows to warm-white. Retail clamps the
+  torch sum on its OWN (from black); ambient/sun are a separate term.
+- **D-2 (state, compounding): EnvCell shell SSBO binding leak.**
+  `EnvCellRenderer.cs:1225-1230` (RenderModernMDIInternal) binds SSBO 0/1/2/3 only, NEVER
+  4 (`gLights`) or 5 (`instanceLightIdx`) — which the shared `mesh_modern.vert` reads at
+  :204-206. Only `WbDrawDispatcher` binds 4/5. Indoor DrawInside interleaves the two, so a
+  cell shell reads whatever LEAKED light set the last WbDrawDispatcher draw left bound —
+  a different entity's torches, wrong per-instance indices ⇒ wrong/over-bright walls.
+- `LightBake.cs` (verbatim CPU port) exists but is UNWIRED (zero callers); the live path is
+  the in-shader version missing the clamp shape.
+
+### Fix plan (REPORT-ONLY — implement in a separate session, with the no-workaround rule)
+- **D-1:** accumulate point/spot into a LOCAL `pointAcc`, `saturate` it to [0,1] BEFORE
+  adding ambient + sun — mirrors `SetStaticLightingVertexColors` (sum-from-black, clamp the
+  point sum). Keep the per-light `min(scale·baseCol, baseCol)` (vert:180). Files:
+  `mesh_modern.vert` (split accumulator + clamp), `mesh_modern.frag` (reorder/drop the
+  single clamp). Conformance golden: a wall ≤~5 m from an orange `(1,0.588,0.314)` torch
+  bakes warm-but-≤[0,1], NOT white.
+- **D-2:** EnvCell shell must bind binding 4 (global lights) + 5 (per-instance light set)
+  for ITS OWN instances — compute a per-shell set like `WbDrawDispatcher.ComputeEntityLightSet`
+  (LightManager.SelectForObject); option (b) all-(-1) fallback = NO point lights is a STOPGAP
+  (needs approval + a divergence-register row). File: `EnvCellRenderer.cs` RenderModernMDIInternal.
+- **Stale doc to fix in the D-1 commit:** divergence-register `AP-35` still describes the
+  point-light path as per-pixel `mesh_modern.frag:52` with the wrap "NOT ported"; Fix A
+  (`aa94ced`) moved it to per-vertex `mesh_modern.vert:163` WITH the wrap.
+- **Do NOT port the D3D-FF hardware model for the walls** (config_hardware_light's
+  color×intensity / (0,1,0)=1/d / Range=falloff×1.5) — it lights GfxObjs/dynamics, not the
+  baked walls.
 
 ---