From 6c3ffd79ec8f3aaf95eb7af76f93170403a0a3a4 Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 5 Sep 2026 13:43:01 +0200 Subject: [PATCH] docs(overhaul): bound consumed-light observation for dark dungeons --- ...478-consumed-light-observation-contract.md | 82 +++++++++++++++++++ .../s5-consumers-material-closeout-packet.md | 10 +++ 2 files changed, 92 insertions(+) create mode 100644 docs/research/2026-09-01-overhaul/478-consumed-light-observation-contract.md diff --git a/docs/research/2026-09-01-overhaul/478-consumed-light-observation-contract.md b/docs/research/2026-09-01-overhaul/478-consumed-light-observation-contract.md new file mode 100644 index 000000000..6759d3fb6 --- /dev/null +++ b/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. diff --git a/docs/research/2026-09-01-overhaul/s5-consumers-material-closeout-packet.md b/docs/research/2026-09-01-overhaul/s5-consumers-material-closeout-packet.md index 143ba8e95..f93a41bfe 100644 --- a/docs/research/2026-09-01-overhaul/s5-consumers-material-closeout-packet.md +++ b/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.