[Renderer] Add capability-tiered global material and texture indirection

[proggeramlug]

Parent: #126
Related: #27, #28

Problem

GPU-driven draws and visibility-buffer shading require geometry/material resources to be addressable from GPU-visible IDs. Bloom still relies heavily on per-material/per-draw binding, while wgpu feature support differs across Metal, DX12, Vulkan, mobile, and WebGPU. Making “bindless” mandatory would break the engine's broad platform promise; avoiding indirection blocks modern rendering architecture.

Outcome

One generation-safe resource-ID model with capability-tiered implementations:

• Tier A: descriptor-indexed/global texture and sampler tables where the adapter/backend supports the required features robustly;
• Tier B: paged texture arrays/atlases plus material indirection with bounded page switches;
• Tier C: existing bind-group material path as a correctness fallback.

Shaders and scene data consume stable IDs; only the backend table implementation varies.

Architecture contract

IDs and lifetime

• Separate typed IDs for material, texture, sampler, mesh, and buffer views.
• IDs contain or reference a generation so stale handles resolve to a diagnostic fallback, never an unrelated reused resource.
• A residency manager owns allocation, retirement after GPU completion, fallback resources, and per-frame update batches.
• Define hard limits and expose them through renderer capabilities.

Material data

• Move scalar/vector PBR parameters into a GPU storage buffer indexed by material_id.
• Store texture/sampler IDs in the material record; do not embed backend bind-group objects in scene/material ownership.
• Keep the existing custom-material ABI functional. Version the ABI only if unavoidable and provide migration diagnostics.

Capability selection

• Probe actual adapter features/limits at device creation; do not infer solely from OS/backend.
• Tier selection is logged and queryable from TypeScript.
• Allow a test/debug override to force each lower tier on capable hardware.
• Web/mobile limits must be derived from adapter.limits(), not desktop defaults.

Shader interface

• Centralize resource lookup helpers in shared WGSL.
• Out-of-range/nonresident IDs sample visible diagnostic defaults in debug and safe neutral defaults in release.
• Preserve correct color-space and normal-map sampling across table implementations.

Staged implementation

1. Introduce IDs, GPU material records, and Tier C adapter without changing draw behavior.
2. Implement Tier B using texture-array pages; group indirect draws by page when necessary.
3. Implement Tier A only behind explicit feature checks and backend tests.
4. Switch perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28 and perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 to consume the common IDs.
5. Add streaming residency hooks without implementing the full cooker/streamer here.

Acceptance criteria

• A stress scene with at least 4,096 material textures and 10,000 visible material instances renders without handle corruption; tier-specific documented limits may reduce resident textures but must stream/fallback deterministically.
• Tier A performs no per-material bind-group creation or switching inside the opaque GPU-driven pass.
• Tier B reports page count/switches and stays within documented adapter limits.
• Forced Tier C matches current rendering and keeps web/mobile adapters functional.
• Destroy/recreate/churn tests prove stale IDs cannot alias newly allocated resources.
• sRGB, linear data, HDR, normal, mip, and sampler modes have golden coverage.
• The quality corpus matches the existing material path within tolerance before perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 migration.
• TypeScript exposes a read-only capability/limit report and receives an actionable error when a requested resource class is unsupported.

Likely files

• native/shared/src/renderer/material_system.rs
• native/shared/src/renderer/material_pipeline.rs
• native/shared/src/renderer/material_system_wasm.rs
• native/shared/src/renderer/shaders/
• native/shared/shaders/material_abi.wgsl
• native/shared/src/handles.rs
• device creation in native/*/src/lib.rs
• public capability API under src/core/ or src/models/

Non-goals

• Requiring descriptor indexing on all platforms.
• Virtual texture page streaming itself.
• Removing the compatibility renderer before every target passes.

Dependencies

• Independent first stage.
• Required before completing perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28/perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 and virtualized geometry.

[proggeramlug]

Implemented and qualified.

What landed

• Added generation-safe typed MaterialId, TextureId, SamplerId, MeshId, and BufferViewId values. Slot reuse increments the generation; stale IDs resolve to the fallback record/resource instead of aliasing a replacement.
• Added GPU-completion-delayed retirement, batched table updates, hard capacity accounting, and read-only residency/fallback telemetry.
• Added the 16-byte-aligned GPU PBR material record and shared WGSL lookup helpers for material, texture, and sampler IDs.
• Added capability selection from the granted wgpu::Device features/limits:
  • Tier A: persistent global texture/sampler tables.
  • Tier B: deterministic bounded texture-page planning.
  • Tier C: unchanged compatibility material bind groups.
• Device creation now requests Tier A only when the adapter advertises both required features, and requests the adapter's actual descriptor-array limits rather than desktop assumptions.
• Added a lower-tier-only debug override (BLOOM_MATERIAL_TIER and TypeScript API).
• Integrated texture, material, mesh, and buffer-view residency with model/texture creation, replacement, and cache eviction.
• Exposed getMaterialBindingCapabilities() and setMaterialBindingTierOverride() through TypeScript, native FFI, web parity, and watchOS stubs.
• Added architecture/consumer documentation in docs/material-texture-indirection.md. perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27 and perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28 can consume these stable IDs without owning backend bind groups.

Tier/stress evidence

• Device-backed Tier A test creates and binds 4,096 real texture descriptors on the local Metal adapter.
• That test renders through the shared WGSL lookup path, verifies manual sRGB decoding, retires/reuses a descriptor slot, and proves the old ID samples the white fallback rather than the replacement.
• Tier B stress test plans 4,096 textures across 10,000 visible draws into 16 bounded pages/switches with no fallback materials.
• Runtime telemetry on Apple M1 Max selected Tier A from granted features and reported:
  • texture capacity: 4,096
  • sampler capacity: 64
  • Tier B page capacity: 256
  • per-material Tier A switches: 0
  • Damaged Helmet residency: 1 material, 5 textures, 1 mesh, 2 buffer views, 0 stale fallbacks, 0 limit fallbacks

Visual and performance qualification

Exact post-refactor source:

• tools/quality/out/issue-130-final2-auto-full/result.json
• comparison to the previously qualified renderer:
  tools/quality/out/issue-130-final2-vs-issue-129/result.json

Results:

• 7/7 corpus cases passed the reproducibility comparison.
• 42/42 final, HDR, depth, and shadow artifacts passed.
• 28/28 CPU/GPU mean and p95 timing checks passed.
• Most artifacts are byte-identical. The largest non-identical final-frame delta was Bistro:
  SSIM 0.999903679, luminance RMSE 0.001074704, mean OKLab delta 0.000035214, mean edge delta 0.000026091 — all within the checked-in gates.
• The only bundle-level mismatch is expected stable metadata: this issue intentionally adds the material-binding capability/residency report.
• The report-only corpus still says approved baseline missing because governed portable baselines have not been human-approved. No baseline was installed or overwritten.

Forced Tier C was also captured and compared:

• tools/quality/out/issue-130-final-auto-full/result.json
• tools/quality/out/issue-130-final-tier-c-full/result.json
• tools/quality/out/issue-130-final-auto-vs-tier-c/result.json
• isolated Sponza timing repeat:
  tools/quality/out/issue-130-final-auto-vs-tier-c-sponza-rerun1/result.json

All Tier A-vs-C artifacts pass. The isolated repeat passes every timing bound (CPU mean delta 0.026 ms, GPU mean delta 0.802 ms); only the intentionally different selected-tier metadata remains.

Validation

• shared Rust tests: 159 passed, 1 ignored
• golden render tests: 10 passed, 2 hardware-only tests ignored
• quality runner governance/reproducibility tests: 8 passed
• bloom-diff negative-control/metric tests: 3 passed
• FFI validation: 0 failures, 0 warnings; 481 manifest functions covered
• release macOS check: passed
• wasm32 check: passed
• iOS, tvOS, and visionOS target checks: passed
• file-length policy: passed (material_system.rs split to 1,960 lines)
• new quality workflow actionlint: passed

Android cross-check reached its native dependencies but the local machine has no
aarch64-linux-android-clang/clang++; the failure is the missing NDK compiler,
not a Rust/source diagnostic. Android FFI coverage and the shared/wasm fallback
paths pass.