[Renderer] Compile the render graph with lifetime planning, aliasing, and topology caching

[proggeramlug]

Parent: #126
Prior design: docs/rfc/0001-material-render-graph.md

Problem

Bloom now has a useful pass scheduler in native/shared/src/renderer/graph.rs, a transient pool in renderer/transient.rs, and an explicit frame sequence in renderer/mod.rs. It is not yet a production render graph:

• topology is constructed during the frame instead of compiled and cached by feature/configuration key;
• resource versions, first/last use, alias compatibility, and read-before-write validation are not a complete contract;
• pass ordering is largely a pinned serial predecessor chain;
• resource usage transitions and queue intent are not represented for diagnostics/future scheduling;
• graph construction and resource churn contribute to the per-frame allocation tail documented as EN-056.

This makes quality features harder to add safely and encourages hidden pass-order dependencies such as the black-frame bind-group-cache regression described in #30.

Outcome

A compiled render graph that owns transient resource planning, validates every pass's data contract, caches stable topologies, and emits a deterministic execution plan without changing public rendering APIs.

Architecture contract

Resource model

• Typed logical handles for textures and buffers; no raw wgpu object access during graph declaration.
• Each write creates a new logical version. Reads name the version they consume.
• Imports for persistent/external resources (swapchain, histories, atlases) state initial/final usage and ownership.
• Descriptors include format, dimensions/scale, mip/layer count, samples, usage, clear/load policy, and alias class.

Pass model

• A pass declares reads, writes, read-writes, side effects, queue capability, and an execution closure.
• Compilation builds a DAG from resource edges, rejects cycles/read-before-write/double-writer mistakes, and topologically sorts deterministically.
• Optional passes are selected before compilation by a hashable FramePlanKey (resolution class, quality tier, toggles, capability tier, PT mode). Do not rebuild for values that only change uniforms.

Lifetime and allocation

• Compute first/last use for every transient resource.
• Alias only descriptor-compatible resources with non-overlapping lifetimes.
• Cache physical allocations by compiled plan and resize generation.
• Persist temporal histories explicitly; never allow them to alias transient resources.

Backend reality

wgpu performs backend barriers, so this issue does not invent a second barrier API. The graph must still validate declared usages and expose transition/queue metadata so incorrect resource contracts are found before wgpu validation and future multi-queue support is possible.

Diagnostics

• Stable pass/resource names and debug markers.
• DOT/JSON dump showing dependencies, lifetimes, aliases, and physical allocations.
• Per-pass CPU/GPU timings connected to the same stable names.
• Debug capture requests by logical resource name.

Migration sequence

1. Unit-test compiler and allocator with synthetic graphs.
2. Compile the existing serial order without aliasing; prove exact image parity.
3. Move transient allocation to the compiled lifetime plan.
4. Cache plans by FramePlanKey; rebuild only on key/resize changes.
5. Enable conservative aliasing, one resource class at a time.
6. Remove legacy manual ordering/allocation paths after all configurations are represented.

Acceptance criteria

• Unit tests cover cycles, missing producers, multiple writers, persistent imports, optional passes, alias compatibility, and deterministic sorting.
• The graph compiles once per stable configuration, not once/twice per frame; a counter/golden test enforces this.
• All current raster, GI, post-FX, custom material, screenshot, and path-tracing paths execute through the graph.
• No quality-corpus case changes beyond the approved tolerance during the no-aliasing migration.
• Conservative aliasing reduces peak transient texture bytes by at least 25% on the Ultra Sponza frame, or the PR documents measured constraints preventing that target.
• Graph dumps and debug markers make every frame pass/resource inspectable in RenderDoc/Xcode/PIX-compatible captures.
• Existing unsupported multi-queue behavior remains serial and correct; no direct wgpu-hal dependency is introduced.

Likely files

• native/shared/src/renderer/graph.rs
• native/shared/src/renderer/transient.rs
• native/shared/src/renderer/mod.rs
• pass modules under native/shared/src/renderer/*_pass.rs
• native/shared/src/profiler.rs

Verification

cd native/shared
cargo test --release

Run the quality corpus at every quality/capability tier and attach before/after graph dumps, peak transient bytes, and pass timings.

Non-goals

• Async compute while safe multi-queue support is unavailable; track perf ticket 010: async compute for post-FX (blocked on wgpu multi-queue) #29.
• Rewriting shaders or changing visual algorithms.
• A public user-programmable graph API in this issue.

Dependencies

Can start immediately. It should land before virtual shadow maps and before broad visibility-pipeline migration.

[proggeramlug]

Implemented and qualified on Apple M1 Max / Metal.

What landed

• Typed/versioned logical texture and buffer handles with complete descriptors, persistent/external imports, initial/final usage, and ownership.
• A deterministic compiler that validates missing producers, divergent writers, usage/type contracts, self-read hazards, and cycles before wgpu validation.
• DAG construction, stable topological ordering, inclusive resource lifetimes, usage/queue transition metadata, stable FNV plan IDs, and deterministic JSON/DOT output.
• Conservative physical planning for textures and buffers: exact descriptor + alias-class compatibility and strictly non-overlapping lifetimes.
• Physical allocation caches keyed by compiled plan ID and exact render/output resize generation.
• FramePlanKey topology caching for resolution class, quality tier, feature mask, capability tier, PT mode, post-pass count, and RT output.
• Optional SSAO, SSR, SSGI, bloom, refractive snapshots, and debug capture are selected before compilation.
• Live execution binds frame-local closures directly into ExecutableGraph; the legacy scheduler and manual transient fallback are no longer used by the retained renderer.
• The live plan now includes GI preparation (accel_rebuild, card capture/light, SDF/clipmap, WSRC), raster, custom materials/planar probes, PT, translucency, Hi-Z/AO, SSR, SSGI, bloom, post-FX, auto exposure, final composite, overlay, and keyed capture readback.
• Screenshot/qualification readback is a terminal graph pass over logical resource names (output, hdr-scene, scene-depth, and the three shadow cascades).
• Stable graph debug groups are available with BLOOM_GRAPH_DEBUG_MARKERS=1.
• BLOOM_GRAPH_DUMP_DIR emits one deterministic JSON/DOT pair per plan. Native telemetry reports compile/hit/plan counters, plan ID/pass count, aliasing state, transient bytes, and physical slots.
• Implementation/operation notes and the measured alias constraint are documented in docs/compiled-render-graph.md; RFC 0001 and the quality README were updated.

No direct wgpu-hal dependency was added. All actual execution remains serial through wgpu; queue capability is diagnostic metadata only.

Stable-plan evidence

Final full-corpus normal plans:

Configuration	Passes	Compile count	Cache hits
High/Ultra retained renderer	24	1	419 (479 for Sponza)
Constrained renderer	12	1	419

The post-measurement capture variants contain 25 and 13 passes respectively and have separate stable plan IDs. Qualification telemetry is intentionally serialized before that debug-only frame.

Final normal high plan: 7ead8d0477965a86; capture plan: e36c395d1d4e3c65. Repeated runs produced byte-identical JSON and DOT for the same plan ID.

Aliasing acceptance

The Ultra Sponza topology currently has zero eligible transient bytes: its post-FX products are persistent imports with stable bind-group views or temporal/history ownership. There is therefore no meaningful percentage reduction to report for that frame (0 -> 0, zero slots).

The only currently materialized optional transients are the refractive scene-color and scene-depth snapshots. They overlap in the translucent pass and have incompatible exact descriptors (Rgba16Float color vs Depth32Float depth), so conservative aliasing correctly keeps two slots:

• 24,883,200 bytes at 1920x1080, 0% savings;
• 4,320,000 bytes at the 800x450 Sponza extent, 0% savings.

Moving persistent post-FX targets would require a broader view/bind-group rebinding migration and was deliberately excluded from this no-regression change. Synthetic allocator coverage proves the positive case: two compatible non-overlapping resources collapse from two slots to one (50%), while overlapping/incompatible and persistent resources never alias.

Visual qualification

Final report-only full run: tools/quality/out/issue-129-final3-full/result.json

• All seven cases captured final output plus five named intermediates: 42 artifacts total.
• 35/42 are byte-identical to bootstrap-full-current.
• The seven non-identical hardware-ray-query artifacts all pass the tighter reproducibility thresholds.
• Worst observed non-identical metric:
  • SSIM: 0.999902129
  • luminance RMSE: 0.001077258
  • mean OKLab delta: 0.000034142
  • mean edge delta: 0.000025811
• PBR high/constrained, Damaged Helmet, and draw/light stress are completely byte-identical.
• The runner's only per-case failure is the already-governed absence of human-approved [Quality][P0] Add deterministic reference-scene visual and GPU performance qualification #128 baselines. No baseline was created or installed.

Final measured timings (CPU mean/p95, GPU mean/p95 in ms):

Case	CPU	GPU
PBR high	2.198 / 2.437	14.693 / 15.967
PBR constrained	1.135 / 1.310	4.943 / 5.450
Damaged Helmet	1.911 / 2.267	8.510 / 9.408
Sponza	2.143 / 2.345	40.768 / 42.528
Bistro	2.728 / 2.964	30.708 / 39.218
Skinned alpha motion	3.006 / 3.452	21.420 / 24.927
Draw/light stress	55.487 / 60.347	17.011 / 28.145

CPU mean and p95 are lower than the pre-#129 full-corpus evidence in every case. GPU p95 deltas remain within the same-machine reproducibility envelope; focused repeat comparisons at the migration boundary were flat or improved (PBR 15.929 -> 15.967 ms, Helmet 9.583 -> 9.408 ms, Sponza 42.585 -> 42.528 ms, constrained 5.607 -> 5.450 ms). No new GPU work or shader algorithm was introduced.

Tests and platform gates

• cargo test --release in native/shared:
  • library: 151 passed, 1 ignored;
  • golden render: 10 passed, 2 hardware-only ignored;
  • render targets: 3 passed;
  • doc tests: 2 ignored.
• Render-graph suite: 29 passing tests, including every required compiler/cache/diagnostic/capture contract.
• Compiled transient materialization covers stable cache hits, exact resize rebuilds, texture slots, and aliased buffer slots.
• cargo check --release passes for shared and macOS.
• cargo check --release --target wasm32-unknown-unknown passes for web (existing warnings only).
• FFI parity: 0 failures, 0 warnings across all platform manifests.
• Quality workflow Actionlint check passes.
• Android cross-check reaches native dependencies but this host lacks the NDK compilers (aarch64-linux-android-clang / clang++); this is an environment limitation, not a Rust/render-graph failure.
• git diff --check passes; renderer/mod.rs is 12,540 lines, below the 13,058-line ratchet.

This satisfies the implementation acceptance criteria. The remaining baseline approval and external Vulkan/Android hardware qualification belong to #128's governance/hardware boundary, not this graph migration.

[proggeramlug]

Closed after the implementation and qualification evidence above. The next dependency-ordered rendering issue is #130.