docs(overhaul): bound consumed-light observation for dark dungeons

docs/research/2026-09-01-overhaul/478-consumed-light-observation-contract.md

@@ -0,0 +1,82 @@
+# #478 — one checkpoint of consumed EnvCell lighting
+
+Lead contract, 2026-09-05, base `7724b6311` (production `1e376c244`).
+Town Network High/off/High remains dark. This chunk obtains the missing
+light-selection evidence; it does NOT repair lighting or profile FPS.
+
+## Evidence and boundary
+
+Read `478-479-graphical-observations.md` and the lighting sections of
+`478-480-readonly-diagnosis.md`. Lead's named-retail/paired-executable proof
+there establishes sealed ambient 0.2 and separate retail static/dynamic
+products. Register AP-16/AP-35/AP-85 already records the modern selection
+limits. Neither that difference nor LightOwners214 proves which lights this
+frame used. No speculative ambient, capacity, attenuation, shader or pack
+change is authorized. No new retail claim is needed for this observation.
+
+## Minimal seam
+
+Use the existing explicitly enabled lifecycle checkpoint, not a new logger,
+flag, per-frame recorder, replay format, selector, or telemetry framework.
+
+1. Add an internal immutable checkpoint DTO and capture method in the
+   EnvCellRenderer partial. Observe already-produced data only: the retained
+   PointSnapshot's exact index order/identity and values, packed global-light
+   floats, and the eight cached indices for cells consumed this frame.
+   No call to BuildPointLightSnapshot, GetCellLightSet or SelectForCell from
+   observation; no reordering of lights/indices. Outer cell IDs may be sorted
+   solely for deterministic JSON. Copy only at an explicit checkpoint.
+2. Prefer existing generation/call-order facts over a new live state machine:
+   RenderFrameResourceController begins EnvCellRenderer each opened frame;
+   BeginFrame increments `_lightFrameGeneration`. GetCellLightSet has exactly
+   one production caller, SubmitRhi, which copies it to binding5 and packs
+   binding4. A successful post-frame checkpoint follows completion of those
+   binds and frame submission. Filter cache entries by the CURRENT generation;
+   no entries means no current EnvCell input. A zero-area or non-world outcome
+   must report no current EnvCell input, never the preceding frame's cache.
+   Do not claim GPU execution/pixel contribution from CPU-bound data. If this
+   chain cannot establish an exact current-frame observation, return the
+   concrete gap to the lead before adding per-frame stamps or copies.
+3. Export actual global-light upload bytes as uint float bits, including the
+   existing one-zero-light dummy upload when relevant; label logical count
+   separately. For each selected source retain index, owner/cell/kind,
+   dynamic/lit/TracksOwnerPose, position/forward/color, intensity/range/cone,
+   DistSq and LocalPose. Use explicit scalar/array data, NOT System.Numerics
+   public fields that serialize as `{}`. Export copied eight-index sets and
+   current frame generation/slot. The exported packed bytes are authoritative
+   for shader values; source records explain provenance, not another pack.
+4. Append one optional field to WorldLifecycleResourceSnapshot; wire the
+   canonical `live.EnvCellRenderer` (verify actual property) and `d.Lighting`
+   through WorldLifecycleResourceSnapshotSource at FrameRootComposition's
+   existing opt-in composition. Capture current ambient/sun scalar float bits
+   and LightManager.RegisteredCount; distinguish this count from selected
+   shader lights and LiveEntityLightController. No new default-on work. The
+   ordinary production render/selection path and runtime lifecycle stay intact.
+
+Expected source delta: EnvCellRenderer observation partial, existing
+WorldLifecycleResourceSnapshotSource/record and FrameRootComposition wiring.
+No algorithm or RHI submission change is expected. Avoid new general-purpose
+interfaces. Remove this temporary seam with the eventual #478 fix once its
+evidence is retained, per the project probe rule. Existing checkpoint launch
+option documentation may mention the additional payload; no new env var.
+
+## Discriminating tests and return
+
+Extend the existing RecordingGpuDevice EnvCell SubmitRhi fixture with real
+nonuniform lights and cell bounds. Invoke the actual SubmitRhi, observe the
+completed frame, and compare exported packed bits and per-cell eight indices
+to actual binding4/binding5 ring bytes (not another selector/packer result).
+Check source index/owner identity, serialization of nonzero vectors, empty
+logical-light dummy upload, and next BeginFrame with no draw returning no
+stale observation. Include zero-area/non-world gating at the checkpoint seam
+and a real nonempty checkpoint JSON assertion. Existing composition tests
+must prove the canonical owner is connected, not merely an optional default.
+
+Use focused Release tests and a Release build; record actual commands, TRX
+and exact source hashes. No clients or performance recipes. Recheck both
+AcDream.App/acclient before each build/test. One implementation return, lead
+independent actual-binding/JSON checks and one narrow production/lifetime
+review; no reopened review of unchanged retail algorithms. No third fix round.
+Do not commit or touch campaign integration; return a frozen scratch diff.
+Lead then integrates and replays unchanged Town Network High/off/High,
+records all PNGs and consumed-light observations. G4 remains FAIL; no main merge.

docs/research/2026-09-01-overhaul/s5-consumers-material-closeout-packet.md

@@ -4907,3 +4907,13 @@ scene narrowPASS. Twelve jump input pairs are not twelve proven airborne
 jumps, and this is not a long soak or proof against recurrence. See the
 ordinary-follow-up section in477-integrated-validation-r2.md. NOT an FPS gate.
 FPS/#481/C2 deferred. No main merge and G4 remains FAIL.
+
+## 58. Next bounded lighting observation
+
+Contract478-consumed-light-observation-contract.md permits only a copied
+view of already-consumed EnvCell light inputs at the existing explicit
+checkpoint. Actual GPU-bound bytes/indices, current-generation/no-draw guards
+and JSON serialization are the tests; no new selector or per-frame recorder.
+No lighting fix or FPS work. Register AP-16/AP-35/AP-85 remains unchanged.
+Lead owns the contract/integration; one OpenAI implementer and one narrow
+production/lifetime review. The next live result determines the repair scope.