docs(overhaul): isolate issue 470 Vulkan proof

Record retail/behavior review pass 1/10: renderer behavior is correct, but the physical-device witness cannot live in the portable Release lane. Bind fix round 1 to an explicit Vulkan lane owned by the existing lavapipe job and current-machine proof.
This commit is contained in:
Erik 2026-09-05 02:50:35 +02:00
parent 67a8bc21f6
commit 011ab1c182
3 changed files with 95 additions and 3 deletions

View file

@ -2439,3 +2439,93 @@ complete data/descriptor/push/SPIR-V path, reproduce at least three mutations,
and rule on gate sufficiency. A failed pass receives a bounded fix contract;
the owner-authorized ceiling is ten review passes. Nothing lands or launches
graphically before both lenses pass.
## 28. S5-#470 fix round 1 — keep the hardware witness out of the portable lane
### 28.1 Retail/behavior review pass 1/10
Review of clean implementation `51f974da4f2262e6afdd336774326f29fb2aec33`
returned **FAIL** on one blocking gate-portability defect and found no renderer,
retail-behavior, shader, descriptor, or proof-mechanism defect.
The production repair is correct: the ordinary shader uses the absolute
base-instance domain only for `Instances[]`, subtracts the exact pushed prefix
for all five live local sidecar bindings, preserves draw-ID batch indexing and
global-light indirection, and regenerates the committed module exactly. The
reviewer reproduced the compiled SHA-256
`6194193764616BC88BF967D1FDC2BEA5F6F2D1EC2EF94FD492922137503F56E4`,
ran the production headless Vulkan witness successfully, and independently
restored mutations to both index domains. The named-retail sidecar meanings
and paired-binary anchors are unchanged.
The defect is test placement. `MeshModernSharedIndexOffscreenTests` is an
ordinary untagged `Fact`, so `tools/run-release-gate.ps1` includes it in the
complete **portable** Release lane. It unconditionally needs a Vulkan loader,
1.3-capable physical device/graphics queue, and coherent host-visible readback
memory. The reviewer forced a nonexistent ICD and reproduced a hard
`vkCreateInstance ErrorIncompatibleDriver`, not a skip. GitHub's
`complete-release` Windows runner installs none of those prerequisites; only
the existing `linux-vulkan` job installs lavapipe. Consequently the local
16,975-pass artifact is hardware-conditioned and cannot be credited as a
portable hermetic gate until the witness has an explicit capability lane.
### 28.2 Bounded evidence-lane repair
Keep every byte of the renderer, GLSL, SPIR-V, manifest, command-recording
proof, SPIR-V structural proof, and hardware witness logic unchanged. Change
only its ownership and execution:
1. mark the offscreen witness with one explicit `Lane=Vulkan` trait;
2. exclude `Lane=Vulkan` in the default filter of
`tools/run-release-gate.ps1`, alongside the existing platform/capability
lanes, so a machine with no Vulkan loader/device can run the truthful
portable gate;
3. split the existing `linux-vulkan` test step into the platform-independent
Vulkan tests (`FullyQualifiedName~...Gpu.Vk&Lane!=Vulkan`) and a separately
named `Lane=Vulkan` step after lavapipe installation. The latter must run the
real offscreen test and fail on absence or render/readback mismatch; do not
turn missing capability into a pass; and
4. update `docs/release-gate.md` narrowly to name the Vulkan lane, its required
capability, its portable exclusion, the existing lavapipe CI owner, and the
exact local command for running it.
Add a small contract test that reads the real test source, portable-gate
script, and headless-portability workflow and fails if any of the three sides
drift: the hardware witness loses its trait, the portable filter admits it, or
the lavapipe job stops invoking it explicitly. This test itself stays portable
and must not initialize Vulkan.
No product source, shader/generated output, test project option, recipe,
package, register, issue, plan, campaign packet beyond this lead-owned section,
or unrelated workflow/tool/doc changes are permitted. No dynamic success on
missing hardware, broad `Gpu.Vk` exclusion, OS-name proxy, environment-only
hidden gate, duplicated pixel oracle, copied shader, or second witness. No
graphical client launch.
### 28.3 Proof and narrow re-review
Apply and restore these mutations, recording the first failure in the fix
commit body:
1. remove the witness's `Lane=Vulkan` trait;
2. remove `Lane!=Vulkan` from the portable Release filter;
3. remove or weaken the explicit lavapipe `Lane=Vulkan` invocation; and
4. point the dedicated invocation at a class/name filter that could miss the
trait-owned witness.
Return one clean fix-round-1 commit atop `51f974da4`; exact changed-file and
line counts; all mutation first failures; both diff-check forms; the portable
contract test; the explicitly filtered `Lane=Vulkan` test on the current
physical device; Release solution build 0W/0E; a new clean official portable
hermetic artifact (the Vulkan witness excluded); and inclusive InstalledDat
with every accepted nonpassing identity named. The original exact-tip
hardware result remains supporting evidence, but the fixed exact tip must run
the dedicated lane again. No bake or graphical gate.
Because pass 1 found no renderer or retail-behavior defect, the next review is
a narrow retail/gate-honesty re-review pass 2/10 of this one finding. It must
reproduce at least mutations 13, prove the ordinary portable suite no longer
depends on Vulkan, and prove the dedicated local and lavapipe routes cannot
silently omit or pass the hardware witness. A PASS unlocks the full production
review as pass 3/10; a FAIL receives another bounded contract within the ten-
pass ceiling. Nothing lands or launches before both sequential lenses pass.