[Rendering][P0] Restore deterministic path-tracing goldens and oracle correctness

[proggeramlug]

Parent: #126

Problem

Bloom's GPU path tracer is the closest in-engine correctness oracle for BRDF energy, direct/indirect visibility, motion reprojection, and denoising. It cannot serve that role unless its golden tests are deterministic and trusted.

The audit found the two path-tracing goldens in native/shared/tests/golden_render.rs failing on the audited worktree:

• pt_progressive: large mean error plus broad black/speckled regions;
• pt_realtime_motion: lower mean error but localized high-error trails/outliers.

The worktree contains renderer changes, so the first task is to reproduce on a clean main checkout before assigning blame. Do not update the goldens to make the test green. First determine whether the baseline, harness, backend, or renderer is wrong.

Outcome

A deterministic GPU path-tracing correctness suite that:

• passes on every supported ray-query backend within documented backend-specific tolerance;
• fails loudly on transport, TLAS/BLAS, temporal reprojection, denoiser, or resource-lifetime regressions;
• emits enough evidence for an agent to diagnose a failure without reproducing locally;
• can act as a reference for realtime renderer changes.

Implementation contract

1. Reproduce and classify

1. Run each PT golden separately on clean main, recording commit, OS, adapter, driver, backend, features, and actual diff metrics.
2. Capture pt_progressive.actual.png and pt_realtime_motion.actual.png plus heatmaps.
3. Add debug captures for raw radiance, albedo, normal, depth, motion, moments/variance, history length, and denoised output.
4. Classify the first divergent stage. Do not start by widening tolerances.

2. Make stochastic inputs explicit

• Put the sample seed, sample index, camera frame index, and jitter sequence under test control.
• Reset all path-tracing history and resource state at test start.
• Ensure headless initialization cannot inherit process-global or prior-test state.
• Document which floating-point/backend differences are expected and why.

3. Fix the first incorrect stage

Likely areas include native/shared/src/renderer/pt_pass.rs, native/shared/src/renderer/shaders/pt.rs, TLAS/BLAS update ordering in renderer/mod.rs, motion matrices, SVGF history validation, and render-graph resource ordering. Fix the earliest provably incorrect stage rather than compensating downstream.

4. Improve the failure artifact

On failure, write an artifact directory containing:

• expected, actual, absolute-diff, and false-color heatmap PNGs;
• JSON with mean/max error, outlier percentage, SSIM, adapter/backend, seed, frames/spp, and enabled features;
• named intermediate buffers when BLOOM_GOLDEN_DIAGNOSTICS=1.

Acceptance criteria

• golden_pt_progressive and golden_pt_realtime_motion pass three consecutive runs on the same adapter with identical or explicitly bounded metrics.
• At least one Metal and one DX12 or Vulkan ray-query adapter pass in CI or a documented scheduled hardware runner.
• Injecting a known reprojection error makes the motion golden fail; injecting a BRDF energy error makes the progressive golden fail.
• No black regions, block trails, NaN/Inf pixels, or uninitialized-history pixels are present in accepted output.
• CPU reference renders from tools/bloom-reference are used to sanity-check the static scene's energy and occlusion; any expected model difference is documented.
• Golden changes, if genuinely required after a correctness fix, are isolated in a second reviewable commit with before/after images and an explanation.
• Unsupported adapters skip with a structured reason; supported ray-query adapters may not silently skip because DXC or a feature was packaged incorrectly.

Verification

cd native/shared
cargo test --release golden_pt_progressive -- --nocapture
cargo test --release golden_pt_realtime_motion -- --nocapture
cargo test --release golden -- --nocapture

Run the relevant reference scene through tools/bloom-reference and attach the result metadata to the PR.

Non-goals

• Adding new path-tracing features.
• Raising tolerances to hide a structural regression.
• Requiring ray query on baseline adapters.

Dependencies

None. This blocks quality claims in every renderer issue under #126.

[proggeramlug]

Implementation status (2026-07-23): Metal implementation and qualification complete; DX12/Vulkan hardware qualification still pending.

What the investigation established:

• A clean git archive of e498433 reproduced the historical progressive PNG byte-for-byte on Apple M1 Max / Metal, but took 167.10 s for 300 frames. Clean-main realtime still had not completed after five minutes and was terminated. This separates the clean baseline from the newer dirty-worktree image corruption while proving a severe Metal performance defect.
• On the audited renderer worktree, named captures showed clean pipeline/depth/normal/albedo followed by nearly all-black sun visibility and workgroup holes in raw radiance. The first bad stage was the ray query, before accumulation/history/post.
• Naga 29.0.1 Metal lowering performs intersector.intersect(...) in rayQueryInitialize, sets ready = true, and its non-modern rayQueryProceed path only reads that flag. The canonical proceed loop can therefore fail to advance/terminate. PT, HW-SSGI, and HW-WSRC now skip that loop on Metal; DX12/Vulkan keep the original proceed loop.
• A second independent bug inverted PT's primary sun vector relative to the raster shader/public setter. PT and the test scene now use the point-to-sun convention (0.5, 1.0, 0.3) used by the CPU oracle.

Evidence:

• qualify_pt_oracle_hardware passed on Apple M1 Max / Metal:
  • three progressive repeats: byte-identical (mean/max/outliers = 0, SSIM = 1.0);
  • three realtime-motion repeats: byte-identical (mean/max/outliers = 0, SSIM = 1.0);
  • BRDF-energy fault failed as intended (mean 4.528 > 4);
  • reprojection/cross-surface-history fault failed as intended (6.0883% outlier pixels > 1%);
  • corrected render wall times across qualification runs: 300-frame progressive 0.851–3.537 s, 48-frame realtime 0.187–0.370 s.
• Full golden test binary: 10 passed, 0 failed, 2 explicitly ignored hardware diagnostics; both ordinary PT goldens reported exact matches.
• Shared library: 128 passed, 0 failed, 1 ignored; the new backend/query-guard unit tests also pass.
• CPU pt-golden reference: 256×256, 256 spp, 8 bounces, seed 0; topology/material tests pass and the rendered visibility, silhouettes, shadow direction, and energy agree with the corrected GPU result.
• Naga validation succeeds for production PT, HW-SSGI, and HW-WSRC as Metal 2.4 (BLOOM_RAY_QUERY_NEEDS_PROCEED=false) and HLSL SM6.0 (true, with RayQuery.Proceed() retained).
• Failure artifacts now include expected/actual/diff/heatmap, JSON metadata (adapter/features/seed/frame/spp/timing/metrics), and named intermediate captures. Unsupported adapters emit structured skips; BLOOM_REQUIRE_RAY_QUERY=1 makes a supported-runner skip fatal.

The two PT goldens were intentionally updated only after the corrected Metal intermediates and independent CPU reference were inspected. The old images encoded sunless transport; the new images add coherent direct light and cast shadows, with no block regions/trails or uninitialized history.

Remaining acceptance item:

• There is currently no DX12/Vulkan hardware result. GET /actions/runners reports total_count: 0, and hosted Windows/Linux runners do not expose a non-CPU ray-query adapter. I am leaving this issue open until [CI] Make local, PR, hardware, and release quality gates truthful #140 provisions/runs the required hardware gate rather than presenting static shader validation or a structured skip as hardware coverage.

Canonical hardware command:

cd native/shared
cargo test --release --test golden_render \
  qualify_pt_oracle_hardware -- --ignored --exact --nocapture

Detailed root-cause and reproduction record: docs/pt/PT-6-7-8-skinned-tlas-motion-oracle.md.