docs(overhaul): contract exact S5 c4 detail material

docs/ISSUES.md

@@ -39,6 +39,32 @@ confirmed closed by the owner, 11 need a focused live gate, and 43 are safe to
 remain closed. See
 [`docs/research/2026-08-28-owner-closed-issue-validity-audit.md`](research/2026-08-28-owner-closed-issue-validity-audit.md).
 
+## #471 — Production walk-ordered building detail is classified but never rendered
+
+**Status:** OPEN — confirmed 2026-09-04 by the S5-c4 production audit;
+Campaign OVERHAUL v2 S5-c4 scope.
+
+**Evidence/mechanism:** the production path is
+`RetailPViewRenderer.DrawWalkDrivenStatics` → `WalkFrameDriver.Replay` →
+`PrepareOrderedStream` → `DrawOrderedRange`. Detail-category commands are
+uploaded and deliberately force solo merge runs, but
+`WbDrawDispatcher.OrderedStream.cs` issues only the base-pipeline indirect draw.
+Its file header still says the detail overlay was deferred. The classic
+`SubmitRhi` path does perform the second detail replay. Consequently opaque and
+ClipMap building shells drawn through the mandatory production walk omit their
+detail material even while the setting and category texture are live. The
+existing ordered submitter test proves only three base draws and therefore
+does not detect the omission.
+
+**Bounded repair:** S5-c4 packet §22 replaces all base-plus-overlay detail with
+retail's exact one-pass combined fragment. Arm that combine on the existing
+walk-ordered solo base run and retain its original order, blend/depth/cull,
+geometry, transform/sidecars, selected GfxObj, setting, sampler, and mip chain.
+Do not add an overlay replay or a compensating terrain flush. Prove an ordered
+ordinary → opaque-detail → ClipMap-detail → ordinary transcript, exact one draw
+per source subset, setting/unavailable-category off rows, nonzero shared
+transform prefix, and a pixel mutation that removes only the ordered arm.
+
 ## #470 — Atmospheric ordered world draws use absolute transform indices for local sidecars
 
 **Status:** OPEN — found 2026-09-04 while auditing the S5-c3 graphical gate;

docs/plans/2026-09-01-campaign-overhaul-world-solidity.md

@@ -692,7 +692,8 @@ Update immediately when a slice changes state. Chat is not the ledger.
 | S5-c1 | **LANDED 2026-09-04 after the owner-authorized documentation/evidence exception.** Mandatory stop `efb075619` remains in history; final campaign tip `1718832e2`, reviewed scratch tip `b2d56f9e3`. | G4 UNPASSED | Narrow exception re-review PASS. Clean evidence: hermetic 16,760/16,760; inclusive InstalledDat 385 pass / the same documented 10 fail / 1 skip; both exact `d6592d3ac`, `WorktreeDirty=false`, manifests fully verified. Fresh campaign Release 0W/0E, Core 111/111, visibility 38/38, allocation/AP-116 4/4. Lead graphical portal-haze gate PROVISIONAL PASS, exit 0/graceful, 10 PNGs under `logs/selfgate-20260904-171137-s5c1-particle-visibility`; owner inspection pending. |
 | S5-c2 | **LANDED + REVIEW-CLOSED 2026-09-04; lead graphical gate PROVISIONAL PASS.** Campaign stack `a4de2efc4` -> `048027e71` -> `ef819eedf`; reviewed scratch tip `521f5edda54`; packet §§14–16. The opt-in IA-24 path borrows the exact prior-completed landscape set/flag, selects world casters through S2 CELLARRAY or building `EffectCellId`, selects authored terrain slots, and projects exact active instance runs without rebuilding retained topology. Pack-off remains unchanged. | G4 UNPASSED | Retail/deviation PASS; production's documentation-only fix round 1 narrowly re-reviewed PASS. Fresh campaign Release 0W/0E and affected 137/137. Official evidence: hermetic 16,768/16,768; broader InstalledDat 468 pass / 10 fail / 1 skip; canonical 385 pass / the same 10 fail / 1 skip; manifests and nonpassing identities exact. Valid lead gate `logs/selfgate-20260904-183925-s5c2-candidate-shadow-ab`: seven PNGs, exit 0, graceful logout, no fatal match, no client left. Exact parent `5c106bcdf` A/B at `s5-c2-ab-parent/logs/selfgate-20260904-183815-s5c2-parent-shadow-ab` proves the gate-visible dark lighting switch predates c2; #469/IA-24 carry it for resolution or explicit owner acceptance before G4. Owner PNG inspection pending. |
 | S5-c3 | **LANDED + REVIEW-CLOSED 2026-09-04** at `c673f767e` (reviewed scratch `01e5a15d0`; packet §§17–21). | **C3 SCOPE SELF-GATE PROVISIONAL PASS; whole-renderer finding #470 OPEN. G4 UNPASSED.** | OpenAI retail pass 3/10 PASS and production narrow re-review pass 5/10 PASS. Fix round 3 added ordinary landblock-lifetime ownership for every unique nonzero ladder GfxObj, rearmed walk-frame miss requests, and made the one-tick-before-BeginFrame proof discriminating. Fresh clean campaign: Release 0W/0E; focused 101/101; hermetic 16,811/16,811; InstalledDat 469 pass / the unchanged documented 10 fail / 1 skip; manifests 30/30. Self-gate `logs/selfgate-20260904-223345-s5c3-building-degrade` produced five PNGs, exited 0/gracefully, and left no client. The selected building shells are complete; the Holtburg frame also exposed pre-existing atmospheric ordered-draw sidecar defect #470, which is not a c3 regression and blocks renderer-solid/G4 until repaired. |
-| S5 | IN FLIGHT — c1–c3 landed/review-closed/provisionally self-gated; c4–c5, #469/#470 disposition, closeout, and G4 remain | G4 | Packet §§7 and 12–21 are binding. Next: contract S5-c4's translucent-detail single-stage framebuffer equivalence; never merge main before G4. |
+| S5-c4 | **CONTRACTED 2026-09-04** in packet §22; implementation next. | G4 UNPASSED | Exact retail one-pass building/EnvCell detail equation, including final alpha `a*qA²`, original per-subset framebuffer state, explicit authored material opacity in prepared/GPU data, removal of every second overlay draw, and production ordered-path omission #471. OpenAI-only implementation then sequential retail and production reviews, maximum ten passes. |
+| S5 | IN FLIGHT — c1–c3 landed/review-closed/provisionally self-gated; c4 contracted; c5, #469/#470 disposition, closeout, and G4 remain | G4 | Packet §§7 and 12–22 are binding. Next: implement S5-c4 exactly; never merge main before G4. |
 
 ---
 

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

@@ -1,8 +1,7 @@
 # Campaign OVERHAUL v2 — S5 consumers, material, and closeout packet
 
-**Status:** S5-c1 and S5-c2 LANDED + lead graphical gates PROVISIONAL PASS;
+**Status:** S5-c1 through S5-c3 LANDED + REVIEW-CLOSED with lead graphical
-S5-c3 implemented in scratch; retail review pass 3 PASS, production review
+gates PROVISIONAL PASS; S5-c4 is contracted under §22.
-pass 4 FAIL, and bounded fix round 3 is contracted under §20.
 **Branch:** `claude/campaign-w-retail-frame-walk`.
 **Gate:** G4 remains unpassed. Nothing merges to `main` before G4.
 
@@ -1561,3 +1560,255 @@ based alpha/selection/light sidecars and omit the active atmospheric receiver
 pipeline/bindings. It exists at least at S4-c2 `252886e84`, is filed as #470,
 and must be repaired before renderer-solid/G4. S5-c4 is next; #469/#470, c5,
 the closeout program, and G4 remain. Nothing merges to `main` before G4.
+
+## 22. S5-c4 contract — exact one-pass detail material and ordered production closure
+
+This chunk replaces the acdream-only base-plus-`mesh_detail` replay with the
+single fragment retail emits when the hardware single-pass detail path is
+available. It applies to detail-active building and EnvCell subsets in every
+current world submission path: classic grouped, walk-ordered, immediate alpha,
+deferred alpha, and EnvCell opaque/transparent replay. One source subset must
+produce one physical draw and one `(rgb, alpha)` result while retaining that
+subset's existing queue position, blend family, alpha-test/depth state, cull,
+geometry, transform, material overrides, fog policy, sampler, and mip chain.
+
+The production audit found that the walk-ordered path currently uploads
+building detail categories and forces them into solo runs but issues only the
+base draw. That omission is filed as #471 and is part of this chunk: the new
+one-pass detail result must be armed on that existing base draw. Do not add a
+blended overlay after the run. An overlay would preserve AP-232, create a new
+terrain/`StreamMark` flush obligation, and remain unlike retail.
+
+### 22.1 Lead-verified retail and paired-binary facts
+
+The paired executable is `C:\Turbine\Asheron's Call\acclient.exe`, SHA-256
+`006FFEADC5D679C871497112A5BD1F87714D0E273E2166BAE5052DDE369297B1`.
+Its CodeView identity remains GUID `{9E847E2F-777C-4BD9-886C-22256BB87F32}`,
+age 1, matching the named PDB. The named pseudo-C and fresh paired-executable
+disassembly agree on these exact ranges:
+
+| Fact | VA range / length | SHA-256 |
+|---|---|---|
+| `SetSurface` detail stages | `0x0059C4D0..0x0059C5B5` / 229 | `090E24BE542E9DA4F77B547D091F5C2E676109495919BEA70027AD2B89E11426` |
+| `SetSurface` blend/alpha/depth state | `0x0059C6C5..0x0059C866` / 417 | `1F077DA1BB09FBAC0EAF7522E125C716AAF499DFA8763DD3DDF29CCC6A76C382` |
+| `RenderMeshSubset` single-pass arm | `0x0059CA10..0x0059CAF0` / 224 | `64A988D4B1611CEEA6DE135FF52CDF30FE1AFDAAFF5E3B76751FFA7FC833CC53` |
+| `DrawMesh` detail/alpha routing | `0x0059D4A0..0x0059D5A5` / 261 | `20B1E5D1E90C9E19C62047AF521F817CF6700B5FEA68CE78C7404CD238862CB3` |
+
+Named anchors are `D3DPolyRender::SetSurface @0x0059C4D0`
+(`acclient_2013_pseudo_c.txt` lines 425083–425303),
+`RenderMeshSubset @0x0059CA10` (lines 425382–425450),
+`DrawMesh @0x0059D4A0`, `RenderDeviceD3D::DrawEnvCell @0x0059F170`, and
+`DrawBuilding @0x0059F2A0`. The live capability result remains the VM2 CDB
+record in `2026-08-22-vm2-retail-detail-path-cdb.md`: retail takes the
+single-pass path, not its fallback.
+
+Let `B` be the sampled base RGB, `D` the active diffuse/lighting RGB, `a` the
+active diffuse/material alpha, and `Q=(q,qA)` the sampled detail texel. At
+`0x0059C51C/52B/53A/549` retail programs:
+
+- stage 0 colour `C0 = B * D`;
+- stage 0 alpha `PREMODULATE(DIFFUSE,DIFFUSE)`, whose visible stage-0 result is
+  `a` but whose stage-1 `CURRENT` alpha is premultiplied by the next texture,
+  `a*qA`;
+- stage 1 colour `BLENDCURRENTALPHA(TEXTURE,CURRENT)`; and
+- stage 1 alpha `MODULATE(TEXTURE,CURRENT)`.
+
+Therefore the exact pre-fog fragment is:
+
+```text
+w = a * qA
+C = q * w + (B * D) * (1 - w)
+X = a * qA * qA
+```
+
+The square in `X` is mandatory. Base texture alpha does not participate in the
+detail-active final alpha. Fog is applied to `C` after the combine wherever
+the subset's fixed-function policy enables fog; it never changes `X`.
+
+`SetBlendFunction @0x005A2B90` writes one colour/alpha factor set, so the
+framebuffer equations for destination `F` are:
+
+| Raw family | Result RGB | Result alpha |
+|---|---|---|
+| Alpha | `C*X + F.rgb*(1-X)` | `X*X + F.a*(1-X)` |
+| Alpha + Additive | `C*X + F.rgb` | `X*X + F.a` |
+| Additive without Alpha | `C + F.rgb` | `X + F.a` |
+| InverseAlpha | `C*(1-X) + F.rgb*X` | `X*(1-X) + F.a*X` |
+| InverseAlpha + Additive | `C*(1-X) + F.rgb` | `X*(1-X) + F.a` |
+| pure CLIP survivor | `C + F.rgb*(1-X)` | `X + F.a*(1-X)` |
+
+Pure CLIP rejects iff `X < r`, with `r=100/255` for paletted and `r=200/255`
+for DDS/non-paletted input; equality survives. CLIP combined with an
+Alpha/Additive/Inverse family keeps that family's factors and applies the same
+test. The later `TRANSLUCENT` branch at `0x0059C767..0x0059C7A6` then matters:
+ordinary `T` and `T|Alpha` are straight-alpha; `T|Additive` and
+`T|InverseAlpha` retain their respective family unless the skip arm applies;
+every `T|CLIP` combination is forced to straight-alpha and CLIP is disabled.
+Do not replace that table with a universal straight-alpha assumption.
+
+`a` is the active material alpha, including authored
+`1-Surface.Translucency` on a `Translucent` surface and the current object/part
+fade multiplier. The lead's installed Surface census found 261/261
+`Translucent`-flagged surfaces carry nonzero authored translucency, including
+real 0.25, 0.5, 0.75, and 1.0 values. Treating `a` as always one is disproven.
+Current prepared Wb payloads discard that scalar while the decoded base image
+bakes it into base alpha; because retail detail excludes base alpha, it cannot
+be recovered from the sampled texel. The implementation must carry authored
+surface opacity explicitly from extraction through the prepared payload and
+GPU batch data, multiply it by the existing live instance opacity, and use the
+product as `a`. Guessing from texture alpha, querying DAT from the renderer, or
+using `base.a` is forbidden.
+
+### 22.2 One draw, one material result
+
+Implement the combine in the ordinary and atmospheric world-mesh fragment
+families, sharing one source include or otherwise proving their arithmetic
+textually and numerically identical. The base texture remains the batch-owned
+array sample. A detail-active exact command supplies the category texture slot
+and tiling in the existing push fields; zero tiling is the unarmed value. The
+per-draw GPU batch record supplies authored surface opacity. The vertex stage
+passes that scalar without interpolation; the fragment multiplies it by the
+existing instance-opacity varying to obtain `a`.
+
+The prepared contract must gain the scalar without ambiguity:
+
+- `MeshExtractor` computes it from the resolved source `Surface` for ordinary
+  GfxObj and CellStruct batches using the existing
+  `OpacityFromSurfaceTranslucency` rule;
+- `TextureBatchData`, its deterministic serializer, and
+  `ObjectRenderBatch` preserve it exactly;
+- this is a prepared-payload schema change, so advance the bake-tool recipe
+  identity and update every recipe/round-trip/compatibility pin in the same
+  commit; an old recipe must be rejected clearly, never misread; and
+- the GPU batch ABI carries it explicitly with layout/stride tests for both
+  built-in shader families. Do not introduce a renderer-side surface table,
+  per-frame dictionary, or DAT lookup.
+
+For a detail-active fragment, compute `(C,X)` before the current discard/fog
+tail. Alpha testing uses `X`, not sampled base alpha. For detail-off fragments,
+preserve the current byte-for-byte logical path: base-alpha discard/reference,
+RGB lighting/fog, and `base.a * instanceOpacity` output alpha. The debug-light
+mode remains a deliberate diagnostic bypass and must not sample detail.
+
+At each production draw site:
+
+1. arm detail only when the existing Building Detail Textures option is on,
+   the correct category binding is resident, tiling is nonzero, and the exact
+   command/subset belongs to the building or EnvCell detail category;
+2. set the detail slot/tiling and draw that source subset exactly once through
+   its original base pipeline family;
+3. preserve its original queue position, blend, depth test/write/reference,
+   alpha test, cull, geometry, draw-id offset, absolute transform base, local
+   sidecars, selected building GfxObj, palette/original-texture override,
+   lighting, fog enable, and atmospheric receiver choice; and
+4. restore neutral detail push fields before the next non-detail draw.
+
+Delete every now-unreachable `RetailDetail`/`RetailDetailTransparent` pipeline,
+`GpuBlendMode.RetailDetail`, `DrawBuildingDetailRangeRhi`-style replay helper,
+`mesh_detail.vert/.frag`, compiled SPIR-V entries, manifest entries, and stale
+two-draw comments/tests. Keep CPU detail-category ownership only where it still
+selects exact eligible commands. Do not delete or weaken the building-detail
+setting, category textures, repeat/linear sampler, full mip chain, S4's two
+FIFO queues, AD-120 immediate placement, AP-238 token granularity, AP-239 raw
+mask residual, or AP-240 ordinary-GfxObj ClipMap placement.
+
+The ordered-path repair for #471 is a one-pass arm on the existing solo base
+run. It adds no second draw and therefore leaves `WalkFrameDriver`'s
+opaque/no-blended-overlay `StreamMark` terrain-flush premise true. Tests must
+prove that premise rather than adding a compensating terrain flush.
+
+### 22.3 Audited policy table and explicit nonchanges
+
+Add one data-driven policy test/table spanning Building and EnvCell × Opaque,
+Alpha, Additive, InverseAlpha, paletted CLIP, and DDS CLIP × detail on/off. For
+each row pin physical draw count, source order/FIFO, pipeline blend/depth/alpha
+test/reference, detail arm, emitted `(C,X)`, and framebuffer result on a
+nontrivial destination. Add raw `Translucent` combinations sufficient to pin
+the later override described in §22.1. Existing AP-238/AP-239/AP-240 facts
+remain visible in the table instead of being silently relabelled exact.
+
+This chunk does not change FIFO classification/token granularity, portal or
+terrain ordering, building-degrade selection, visibility/membership,
+directional-shadow caster selection, #469's lighting-direction transition, or
+#470's general ordered atmospheric sidecar/receiver defect. It must implement
+the same material arithmetic in the atmospheric shader so the later #470
+repair cannot expose a second result. No graphical client is launched by the
+implementer.
+
+Allowed production scope is the prepared mesh batch/extractor/serializer and
+bake-recipe identity; world GPU batch ABI and built-in ordinary/atmospheric
+mesh shaders; Wb/EnvCell detail draw/pipeline ownership; shader compiler
+outputs/manifest; and the smallest render-pack ABI pins required by those
+shader changes. Tests may change for those surfaces, deterministic prepared
+round trips, state/pixel equations, command transcripts, allocation, shader
+ABI, and package compatibility. The only authorized documentation file in the
+implementation commit is
+`docs/architecture/retail-divergence-register.md`: strike AP-232 with the exact
+new mechanism/evidence and amend counts; add or correct a row in the same
+commit for every discovered surviving deviation. Do not edit this packet,
+the plan, issues, architecture prose, scripts, or generated evidence reports.
+
+### 22.4 Required proof, mutations, and return
+
+Focused proof must include at least:
+
+1. independent CPU fixtures over nontrivial base/detail RGBA, diffuse colour,
+   authored opacity, live fade, fog, destination RGBA, and every §22.1 state;
+   they must distinguish `a*qA²` from `a*qA`, `base.a*a*qA²`, and today's two
+   draws;
+2. pure/paletted/DDS CLIP values immediately below, equal to, and above the
+   final-`X` reference plus `Translucent|CLIP`'s disabled-test override;
+3. extraction and prepared serialization round trips for opacity 1, 0.75,
+   0.5, 0.25, and 0, a bumped recipe identity, deterministic bytes, and clear
+   rejection of recipe 8 by the recipe-9 build;
+4. GPU ABI pins proving the batch scalar reaches both ordinary and atmospheric
+   fragments, detail-off never samples the category texture, and debug-light
+   mode stays independent;
+5. real Wb classic, walk-ordered, immediate-alpha, and delayed-alpha command
+   recordings proving one detail-active subset draw, original pipeline state,
+   exact slot/tiling/material alpha, no replay, and no stale detail arm on an
+   adjacent ordinary draw;
+6. real EnvCell opaque, Alpha, Additive, and both CLIP-reference recordings
+   with the same one-draw/state/order proof;
+7. production ordered sequence ordinary → opaque building detail → ClipMap
+   building detail → ordinary with exact one-draw adjacency and no added
+   terrain flush, closing #471;
+8. active/inactive atmospheric receiver shader/pipeline recordings proving
+   identical material equations while leaving #470's separate general repair
+   boundary explicit;
+9. setting-off and unavailable-category identity, selected-surface override,
+   sampler/mip, fog-after-combine, draw-id/transform-prefix, cull, and
+   lifecycle/reset/revisit preservation; and
+10. warmed extraction-free draw/classification paths at 0 managed bytes after
+    warmup, with no per-frame material lookup/table/allocation.
+
+Sabotage and restore at least these mutations, recording the first failing
+test/assertion for each in the implementation commit body: change `X` to
+`a*qA`; multiply `X` by base alpha; test CLIP against base alpha or 0.05;
+restore any second detail draw; bind straight alpha instead of the original
+subset family; omit the walk-ordered detail arm; omit the atmospheric combine;
+drop authored opacity during prepared serialization; and leave the detail push
+fields armed for the following ordinary draw. Include one allocation sabotage
+that builds a per-frame surface map and prove the 0-B pin catches it.
+
+Implementer return: one clean commit; exact changed-file and line-count list;
+all mutation first failures; `git diff --check`; Release solution build 0W/0E;
+shader compilation plus manifest/SPIR-V validation; focused content/serializer,
+renderer/state/pixel/command/allocation suites; official hermetic lane; and an
+inclusive InstalledDat lane with every accepted nonpassing identity named. If
+the package recipe changes, also return the exact deterministic bake command,
+artifact identity/size, and compatibility result. No client run.
+
+Sequential review 1 — retail/material/deviation fidelity: re-check the named
+and paired bytes, PREMODULATE semantics, squared alpha, every framebuffer and
+CLIP/Translucent row, authored opacity provenance, fog placement, AP-232
+retirement, AP-238/239/240 preservation, and all retail-facing mutations.
+Sequential review 2 — architecture/production/gate honesty: one physical draw,
+all five production paths including #471, prepared-schema compatibility, no
+renderer DAT lookup or per-frame map, shader/pack ABI, state/order/reset,
+allocation, build/lane/artifact provenance, and at least three independently
+reproduced sabotages. Reviews run sequentially. Every code finding receives a
+bounded fix contract and narrow re-review; documentation-only findings may be
+corrected directly by the lead. At most ten c4 review passes may run; stop
+before an eleventh. Nothing lands or launches graphically until both lenses
+pass.