@forgeax/engine-render 0.1.28 → 0.1.30

package/src/assembly/material-shader-policy.ts

@@ -280,19 +280,18 @@ export async function prepareMaterialShaders(
   ]);
 
   // ── Step 0: storage-buffer cap gate ───────────────────────────────────────
-  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
-    .maxStorageBuffersPerShaderStage;
+  const capValue = rhiDevice.limits.maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
-  const storageBufferCapable = rhiDevice.caps.storageBuffer;
-  if (storageBufferCapable && typeof capValue === 'number') {
+  let storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer;
+  if (typeof capValue === 'number') {
     const capCheck = assertStorageBufferCap(capValue);
     if (!capCheck.ok) throw capCheck.error;
+    storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer && capCheck.value;
   }
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
   const projectorAvailable =
     (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
     STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
-
   // ── Step 1: manifest load ─────────────────────────────────────────────────
   const registry = getShader();
   const loaded = await registry.loadManifest();
@@ -301,35 +300,46 @@ export async function prepareMaterialShaders(
   }
 
   // ── Step 1b: material shader variant resolution + registration ───────────
-  // feat-20260609-hdrp-cluster-fragment-ggx M1 / w7: dual-axis variant
-  // resolution. At boot time isHdrpActive is always false (URP default),
-  // so CLUSTER_FORWARD_AVAILABLE=false variant is selected. HDRP variant
-  // (CLUSTER_FORWARD_AVAILABLE=true) is resolved later when
-  // clustered Standard profile activation selects the clustered variant.
-  const isHdrpActive = false; // M4: wire to actual renderSystem.frameState.isHdrpActive
+  // feat-20260609-hdrp-cluster-fragment-ggx M1 / w7: the boot resolver selects
+  // the non-clustered variant; clustered Standard activation resolves its own
+  // variant later at record time.
   for (const msEntry of registry.materialShaderManifestEntries()) {
     // bug-20260610: skip synthetic non-material engine entries piggy-backing
     // on the materialShaders channel for variant surfacing (shadow_caster).
     // They use the `forgeax::engine-` prefix and are consumed by Step 2's
     // engine-entry compile path, NOT by installMaterialArtifact.
     if (msEntry.identifier.startsWith('forgeax::engine-')) continue;
-    // buildVariantKey logic: sorted key=value pairs joined with +; all-true = ''.
-    const variantDefines: Record<string, boolean> = {};
-    if (msEntry.variants.some((variant) => 'STORAGE_BUFFER_AVAILABLE' in variant.defines)) {
-      variantDefines.STORAGE_BUFFER_AVAILABLE = storageBufferCapable;
-    }
-    // User material manifests may declare WEBGL2_COMPAT alongside the shared
-    // mesh-storage axis. The fallback backend must select that authored
-    // branch at boot; otherwise it asks for the impossible bare
-    // `STORAGE_BUFFER_AVAILABLE=false` key and fails before the first frame.
+    // The same closed resolver drives every manifest axis at boot. This keeps
+    // registration aligned with record-time capability/feature selection and
+    // supplies explicit defaults for opt-in axes such as shadow alpha-mask and
+    // GPU-driven scene-index variants.
+    // Build the exact boot key from the capability facts and explicit defaults.
+    // Record-time callers use resolveMaterialShaderVariantSet below; keeping
+    // the same axes here prevents a physical-material variant from being
+    // registered under a key that cannot be selected by the renderer.
+    const variantDefines: Record<string, boolean> = {
+      STORAGE_BUFFER_AVAILABLE: storageBufferCapable,
+    };
     if (msEntry.variants.some((v) => 'WEBGL2_COMPAT' in v.defines)) {
       variantDefines.WEBGL2_COMPAT = webgl2Downlevel;
     }
-    // Only include CLUSTER_FORWARD_AVAILABLE when the material shader declares
-    // the axis (has a variant with this key), preserving backward compat for
-    // entries without the pragma.
     if (msEntry.variants.some((v) => 'CLUSTER_FORWARD_AVAILABLE' in v.defines)) {
-      variantDefines.CLUSTER_FORWARD_AVAILABLE = isHdrpActive;
+      variantDefines.CLUSTER_FORWARD_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'GPU_DRIVEN_SCENE_INDEX_AVAILABLE' in v.defines)) {
+      variantDefines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'GPU_DRIVEN_SCENE_INDEX_EXPLICIT' in v.defines)) {
+      // The boot material is the compact visible-stream path.  Explicit
+      // scene-index dispatches select their own variant at record time; they
+      // must never make the default artifact key unsatisfiable.
+      variantDefines.GPU_DRIVEN_SCENE_INDEX_EXPLICIT = false;
+    }
+    if (msEntry.variants.some((v) => 'ALPHA_MASK' in v.defines)) {
+      // Alpha-mask admission is a per-draw producer fact.  Keep the boot
+      // artifact opaque and resolve ALPHA_MASK=true only for a receipt-owned
+      // shadow batch.
+      variantDefines.ALPHA_MASK = false;
     }
     if (msEntry.variants.some((v) => 'DIRECTIONAL_PCSS_AVAILABLE' in v.defines)) {
       variantDefines.DIRECTIONAL_PCSS_AVAILABLE = directionalPcssCapable(
@@ -339,16 +349,24 @@ export async function prepareMaterialShaders(
     if (msEntry.variants.some((v) => 'VERTEX_COLOR_AVAILABLE' in v.defines)) {
       variantDefines.VERTEX_COLOR_AVAILABLE = false;
     }
+    if (msEntry.variants.some((v) => 'COVERAGE_ONLY' in v.defines)) {
+      // Coverage-only is a producer-owned opt-in for sprite/temporal paths.
+      // Keep the ordinary boot material on the opaque variant; record-time
+      // coverage batches request the true variant explicitly.
+      variantDefines.COVERAGE_ONLY = false;
+    }
     if (msEntry.variants.some((v) => 'PROBE_BLEND_AVAILABLE' in v.defines)) {
       variantDefines.PROBE_BLEND_AVAILABLE = false;
     }
     if (msEntry.variants.some((v) => 'EXTENDED_LIGHTING_AVAILABLE' in v.defines)) {
       variantDefines.EXTENDED_LIGHTING_AVAILABLE = extendedLightingShaderAvailable;
     }
-    if (
-      msEntry.identifier === 'forgeax::default-standard-pbr' &&
-      msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)
-    ) {
+    // A material shader that declares the projector axis owns the same
+    // capability-selected resource pair, regardless of whether it is the
+    // engine Standard entry or a VFX particle entry. Omitting this value for
+    // particle variants asks the manifest for a partial key and fails before
+    // the first frame when the shader does not use the Standard root.
+    if (msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)) {
       variantDefines.PROJECTOR_AVAILABLE = projectorAvailable;
     }
     if (msEntry.variants.some((v) => 'TRANSMISSION_AVAILABLE' in v.defines)) {
@@ -409,6 +427,9 @@ export async function prepareMaterialShaders(
       registry.installMaterialArtifact(msEntry.identifier, {
         source: wgsl,
         paramSchema,
+        ...(chosen?.receipt === undefined && msEntry.receipt === undefined
+          ? {}
+          : { receipt: chosen?.receipt ?? msEntry.receipt }),
       });
       // feat-20260629 M4: store uvSetCount from naga reflection for
       // auto-fill in getMaterialShaderPipeline clamp-to-last alias.
@@ -457,6 +478,7 @@ export async function prepareMaterialShaders(
       registry.installMaterialArtifact(shadowCasterIdentifier, {
         source: manifestEntry.composedWgsl,
         paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
+        ...(manifestEntry.receipt === undefined ? {} : { receipt: manifestEntry.receipt }),
       });
       const shaderGuid = ENGINE_SHADER_GUIDS.get(shadowCasterIdentifier);
       if (shaderGuid !== undefined) {
@@ -516,7 +538,15 @@ export async function prepareMaterialShaders(
  * material-shader layouts add a `LayoutKind` member + a PipelineState slot
  * + a switch arm here in one cut (charter P3 extensibility).
  */
-export type LayoutKind = 'pbr' | 'pbr-skin' | 'hdrp-pbr' | 'hdrp-skin' | 'sprite-urp' | 'unlit-urp';
+export type LayoutKind =
+  | 'pbr'
+  | 'pbr-skin'
+  | 'gpu-driven-pbr'
+  | 'gpu-driven-skin'
+  | 'hdrp-pbr'
+  | 'hdrp-skin'
+  | 'sprite-urp'
+  | 'unlit-urp';
 
 function directionalPcssCapable(backendKind: RhiDevice['caps']['backendKind']): boolean {
   return backendKind === 'webgpu' || backendKind === 'wgpu-native';
@@ -583,9 +613,12 @@ export function selectNoColorPbrVariant(
 ): MaterialShaderManifestEntry['variants'][number] | undefined {
   const hdrpRequested = variantSet === '' || requestsClusterVariant(variantSet);
   const probeBlendRequested = requestsProbeBlendVariant(variantSet);
+  const coverageOnlyRequested = variantSet?.includes('COVERAGE_ONLY=true') === true;
   return manifestEntry?.variants.find(
     (variant) =>
       variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+      (!('COVERAGE_ONLY' in variant.defines) ||
+        variant.defines.COVERAGE_ONLY === coverageOnlyRequested) &&
       (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
         variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingShaderAvailable) &&
       variant.defines.VERTEX_COLOR_AVAILABLE === false &&
@@ -627,6 +660,17 @@ export function resolveMaterialShaderBindingContract(
     /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*1\s*\)\s*var\s+scene_depth\s*:\s*texture_depth_2d\b/u.test(
       withoutComments,
     );
+  const declaresSceneDepthAtZero =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*0\s*\)\s*var\s+scene_depth\s*:\s*texture_depth_2d\b/u.test(
+      withoutComments,
+    );
+  const hasMaterialGroup = groups.includes(1);
+  if (declaresView && declaresSceneDepth && hasMaterialGroup) {
+    return 'render-material-and-scene-depth';
+  }
+  if (declaresSceneDepthAtZero && hasMaterialGroup) {
+    return 'render-material-with-scene-depth';
+  }
   if (declaresView && declaresSceneDepth && groups.every((group) => group === 0)) {
     return 'view-and-scene-depth';
   }
@@ -760,8 +804,11 @@ export function shouldDeferMissingPreparedMaterialShader(
 ): boolean {
   return (
     vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance ||
     vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance ||
-    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance
   );
 }
 
@@ -773,6 +820,8 @@ export function selectPipelineLayoutForVariant(
     readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
     readonly pbrSkinPipelineLayout: PipelineLayout | null;
     readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
     readonly hdrpSkinPipelineLayout?: PipelineLayout | null;
   } | null,
   variantSet: string | undefined,
@@ -780,6 +829,12 @@ export function selectPipelineLayoutForVariant(
 ): PipelineLayout | null {
   if (state === null) return null;
   const probeBlendVariant = variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true;
+  if (layoutKind === 'gpu-driven-pbr') {
+    return state.gpuDrivenPbrPipelineLayout ?? null;
+  }
+  if (layoutKind === 'gpu-driven-skin') {
+    return state.gpuDrivenPbrSkinPipelineLayout ?? null;
+  }
   // bug-20260611: skin layout selection takes precedence over HDRP variant
   // resolution. HDRP × skin is OOS-1 (plan-strategy R-2 — left for a
   // dedicated feat); when an HDRP-variant skin call ever lands, we fail
@@ -853,6 +908,7 @@ export function resolveMaterialShaderVariantSet(
 ): string | undefined {
   const declaredAxes = new Set(variants.flatMap((variant) => Object.keys(variant.defines)));
   const declaresCapabilityVariants =
+    declaredAxes.has('COVERAGE_ONLY') ||
     declaredAxes.has('WEBGL2_COMPAT') ||
     declaredAxes.has('STORAGE_BUFFER_AVAILABLE') ||
     declaredAxes.has('EXTENDED_LIGHTING_AVAILABLE') ||
@@ -890,23 +946,31 @@ export function resolveMaterialShaderVariantSet(
           ? backendKind !== 'wgpu-webgl2' && storageBuffer
           : axis === 'SKINNING_DISABLED'
             ? (requested[axis] ?? true)
-            : axis === 'CLUSTER_FORWARD_AVAILABLE'
-              ? storageBuffer && backendKind !== 'wgpu-webgl2' && (requested[axis] ?? false)
-              : axis === 'PER_INSTANCE_REGION'
-                ? requestedVariantSet === '' || (requested[axis] ?? false)
-                : axis === 'VERTEX_COLOR_AVAILABLE'
+            : axis === 'ALPHA_MASK' ||
+                axis === 'GPU_DRIVEN_SCENE_INDEX_AVAILABLE' ||
+                axis === 'GPU_DRIVEN_SCENE_INDEX_EXPLICIT' ||
+                axis === 'COVERAGE_ONLY'
+              ? (requested[axis] ?? false)
+              : axis === 'CLUSTER_FORWARD_AVAILABLE'
+                ? storageBuffer && backendKind !== 'wgpu-webgl2' && (requested[axis] ?? false)
+                : axis === 'PER_INSTANCE_REGION'
                   ? requestedVariantSet === '' || (requested[axis] ?? false)
-                  : axis === 'EXTENDED_LIGHTING_AVAILABLE'
-                    ? extendedLightingAvailable
-                    : axis === 'PROBE_BLEND_AVAILABLE'
-                      ? storageBuffer && (requested[axis] ?? false)
-                      : axis === 'TRANSMISSION_AVAILABLE'
-                        ? (requested[axis] ?? false)
-                        : axis === 'DIRECTIONAL_PCSS_AVAILABLE'
-                          ? directionalPcssCapable(backendKind)
-                          : axis === 'PROJECTOR_AVAILABLE'
-                            ? projectorAvailable
-                            : (requested[axis] ?? false);
+                  : axis === 'VERTEX_COLOR_AVAILABLE'
+                    ? requestedVariantSet === '' || (requested[axis] ?? false)
+                    : axis === 'EXTENDED_LIGHTING_AVAILABLE'
+                      ? extendedLightingAvailable
+                      : axis === 'PROBE_BLEND_AVAILABLE'
+                        ? storageBuffer && (requested[axis] ?? false)
+                        : axis === 'TRANSMISSION_AVAILABLE' ||
+                            axis === 'REFLECTION_FALLBACK_AVAILABLE'
+                          ? (requested[axis] ?? false)
+                          : axis === 'DIRECTIONAL_PCSS_AVAILABLE'
+                            ? directionalPcssCapable(backendKind)
+                            : axis === 'PROJECTOR_AVAILABLE'
+                              ? projectorAvailable
+                              : // Authored axes keep the manifest's all-true default.
+                                // Only Engine-owned admission axes default to disabled.
+                                (requested[axis] ?? true);
   }
   const sorted = Object.entries(filtered).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
   return sorted.every(([, value]) => value)

package/src/assembly/recovery/device-loss-fanout.ts

@@ -50,6 +50,11 @@ export function attachDeviceLostFanout(
     }
     onDeviceLost?.(detail);
     lostRegistry.fire(safe);
+    // A `destroyed` loss is the terminal signal from an intentional
+    // GPUDevice.destroy() call. It is observable through the lost channel,
+    // but must not put the renderer into recoverable device-lost health or
+    // emit an error during normal teardown. Only an unexpected loss keeps the
+    // recovery/error fan-out active.
     if (safe.reason !== 'destroyed') {
       pack.instrumentation?.onDeviceLost?.();
       healthRegistry.fire({

package/src/assembly/recovery/failure-location.ts

@@ -0,0 +1,62 @@
+import type { DeviceResourceKind } from '../../device/resource-types';
+import type { RecoveryGuidance, RecoveryPhase } from '../renderer-lifecycle';
+
+export interface RecoveryFailureLocation {
+  readonly phase: RecoveryPhase;
+  readonly retryable: boolean;
+  readonly guidance: RecoveryGuidance;
+  readonly owner: string;
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+}
+
+function recoveryCauseCode(cause: unknown): string | undefined {
+  if (typeof cause !== 'object' || cause === null) return undefined;
+  const directCode = (cause as { readonly code?: unknown }).code;
+  if (typeof directCode === 'string') return directCode;
+  const detail = (cause as { readonly detail?: unknown }).detail;
+  if (typeof detail !== 'object' || detail === null) return undefined;
+  const detailCode = (detail as { readonly code?: unknown }).code;
+  if (typeof detailCode === 'string') return detailCode;
+  return recoveryCauseCode((detail as { readonly cause?: unknown }).cause);
+}
+
+export function createRecoveryFailureLocation(
+  phase: RecoveryPhase,
+  cause: unknown,
+  overrides: Partial<Omit<RecoveryFailureLocation, 'phase' | 'cause'>> = {},
+): RecoveryFailureLocation {
+  const code = recoveryCauseCode(cause) ?? '';
+  const resourceKind: DeviceResourceKind = code.includes('shader')
+    ? 'shader'
+    : code.includes('buffer')
+      ? 'buffer'
+      : code.includes('texture')
+        ? 'texture'
+        : code.includes('binding')
+          ? 'binding'
+          : phase === 'rehydrate'
+            ? 'shader'
+            : phase === 'acquire-adapter' || phase === 'acquire-device'
+              ? 'surface'
+              : phase === 'publish' || phase === 'cleanup'
+                ? 'surface'
+                : 'pipeline';
+  const owner =
+    code.includes('shader') || phase === 'rehydrate'
+      ? 'shader'
+      : phase === 'acquire-adapter' || phase === 'acquire-device'
+        ? 'backend'
+        : phase === 'compile-graph'
+          ? 'pipeline'
+          : 'renderer';
+  return {
+    phase,
+    retryable: false,
+    guidance: 'repair-owner',
+    owner,
+    resourceKind,
+    cause,
+    ...overrides,
+  };
+}

package/src/assembly/recovery/recovery-attempt.ts

@@ -12,6 +12,7 @@ import {
 } from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { RhiBackendPack } from '../backend-contract';
+import { deviceOptionsForAdapter } from '../device-feature-admission';
 import {
   RECOVERY_ADAPTER_DEADLINE_MS,
   RECOVERY_DEVICE_DEADLINE_MS,
@@ -20,13 +21,7 @@ import {
   type RecoveryPhase,
 } from '../renderer-lifecycle';
 
-const COMPRESSION_FEATURES: GPUFeatureName[] = [
-  'texture-compression-bc',
-  'texture-compression-etc2',
-  'texture-compression-astc',
-];
-
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export { deviceOptionsForAdapter } from '../device-feature-admission';
 
 const PROBE_TEXTURE_USAGE_COPY_SRC = 0x01;
 const PROBE_TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
@@ -573,28 +568,6 @@ export async function probeCandidateGraphExecution(
   }
 }
 
-export function deviceOptionsForAdapter(adapter: Pick<RhiAdapter, 'features' | 'limits'>):
-  | {
-      requiredFeatures?: GPUFeatureName[];
-      requiredLimits?: GPUDeviceDescriptor['requiredLimits'];
-    }
-  | undefined {
-  const requiredFeatures = COMPRESSION_FEATURES.filter((feature) => adapter.features.has(feature));
-  const supportsTransmission =
-    (adapter.limits.maxSampledTexturesPerShaderStage ?? 0) >=
-    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
-  return {
-    ...(requiredFeatures.length > 0 ? { requiredFeatures } : {}),
-    ...(supportsTransmission
-      ? {
-          requiredLimits: {
-            maxSampledTexturesPerShaderStage: STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES,
-          },
-        }
-      : {}),
-  };
-}
-
 export interface AcquiredDeviceGeneration {
   readonly adapter: RhiAdapter;
   readonly device: RhiDevice;

package/src/assembly/recovery/renderer-recover.ts

@@ -19,18 +19,13 @@ import {
   postProcessShaderEntrySignature,
   postProcessShaderPipelineLabel,
 } from '../../fullscreen-post-process-pass';
-import { createRecoveryColdWorkGuard } from '../../record/recovery-pipeline';
-import type {
-  PipelineState,
-  RecoveryColdWorkGuard,
-  RenderSystemInternals,
-} from '../../record/render-context';
+import type { PipelineState, RenderSystemInternals } from '../../record/render-context';
 import type {
   RecoveryGraphCandidate,
   RecoveryPostProcessResources,
   RecoveryRootBundle,
-  RenderSystem,
-} from '../../render-system';
+} from '../../recovery/types';
+import type { RenderSystem } from '../../render-system';
 import type { RhiBackendPack } from '../backend-contract';
 import {
   type LayoutKind,
@@ -42,8 +37,9 @@ import type { MeshSsboGrowResult, MeshSsboState } from '../mesh-ssbo-grow';
 import { structuredRendererCause } from '../renderer-facade';
 import { ensureContextConfigured } from '../renderer-helpers';
 import type { RecoveryContinuation, RecoveryDeadline, RecoveryPhase } from '../renderer-lifecycle';
-import type { RecoveryFailureLocation, WebGPURendererInternals } from '../webgpu-renderer';
+import type { WebGPURendererInternals } from '../webgpu-renderer';
 import { attachDeviceLostFanout } from './device-loss-fanout';
+import type { RecoveryFailureLocation } from './failure-location';
 import { buildGenerationAggregate, type GenerationAggregate } from './generation';
 import {
   acquireDeviceGeneration,
@@ -146,6 +142,9 @@ export interface RendererRecoveryDependencies {
   readonly getMaterialShaderPipelineEntry: NonNullable<
     RenderSystemInternals['getMaterialShaderPipelineEntry']
   >;
+  readonly getMaterialShaderArtifact: NonNullable<
+    RenderSystemInternals['getMaterialShaderArtifact']
+  >;
   readonly getCachedMaterialShaderBindingContract: NonNullable<
     RenderSystemInternals['getMaterialShaderBindingContract']
   >;
@@ -166,7 +165,6 @@ export interface RendererRecoveryDependencies {
     candidatePostProcessResources: RecoveryPostProcessResources,
     recoveryRootBundle: RecoveryRootBundle,
     recoveryGraphCandidate: RecoveryGraphCandidate | undefined,
-    recoveryColdWorkGuard: RecoveryColdWorkGuard,
   ) => void;
 }
 
@@ -205,6 +203,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     buildPipeline,
     getMaterialShaderPipeline,
     getMaterialShaderPipelineEntry,
+    getMaterialShaderArtifact,
     getCachedMaterialShaderBindingContract,
     getParamSchema,
     getMaterialBindGroupLayout,
@@ -253,7 +252,6 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     // old roots remain authoritative until the final synchronous publication.
     const candidateGpuStore = new GpuResidencyCache();
     const candidateDynamicTextureStore = new DynamicTextureStore();
-    const recoveryColdWorkGuard = createRecoveryColdWorkGuard();
     // Re-acquire through the SAME backend pack (the
     // idempotent factory primitives tryCreateWebGPURenderer uses). On the
     // adapter / device failure paths, health stays `device-lost` (A-AC-07):
@@ -334,6 +332,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
           candidateShaderCatalog.installMaterialArtifact(identifier, {
             source: entry.value.source,
             paramSchema: entry.value.paramSchema,
+            ...(entry.value.receipt === undefined ? {} : { receipt: entry.value.receipt }),
           });
         }
       }
@@ -568,14 +567,15 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     const candidateInternals = Object.create(internals) as WebGPURendererInternals &
       RenderSystemInternals;
     Object.defineProperties(candidateInternals, {
+      assets: { value: assets },
       device: { value: candidateState.device },
       context: { value: candidateState.context },
       deviceScope: { value: candidateState.scope },
       gpuStore: { value: candidateState.gpuStore },
       dynamicTextureStore: { value: candidateState.dynamicTextureStore },
-      recoveryColdWorkGuard: { value: undefined },
       getMaterialShaderPipeline: { value: getMaterialShaderPipeline },
       getMaterialShaderPipelineEntry: { value: getMaterialShaderPipelineEntry },
+      getMaterialShaderArtifact: { value: getMaterialShaderArtifact },
       getMaterialShaderBindingContract: { value: getCachedMaterialShaderBindingContract },
       getParamSchema: { value: getParamSchema },
       getMaterialBindGroupLayout: { value: getMaterialBindGroupLayout },
@@ -594,20 +594,20 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
         value: (
           id: string,
           bgl: BindGroupLayout,
-          colorFormat: GPUTextureFormat,
+          colorFormats: readonly GPUTextureFormat[],
           entryOverride?: PostProcessShaderEntry,
         ) => {
           const entry = entryOverride ?? candidateInternals.lookupPostProcess?.(id);
           if (entry === undefined || candidateInternals.buildPostProcessPipeline === undefined) {
             return null;
           }
-          const key = `${id}|${colorFormat}|${postProcessShaderEntrySignature(entry)}`;
+          const key = `${id}|${colorFormats.join(',')}|${postProcessShaderEntrySignature(entry)}`;
           const cached = candidatePostProcessPipelineCache.get(key);
           if (cached !== undefined) return cached;
           const built = candidateInternals.buildPostProcessPipeline(
             entry,
             bgl,
-            colorFormat,
+            colorFormats,
             postProcessShaderPipelineLabel(id, entry.source),
           );
           if (built === null) return null;
@@ -632,7 +632,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       releaseCandidate();
       return err(new RecoverError('recover-device-unavailable'));
     }
-    const graphPreparation = await renderSystem.prepareRecoveryGraphCandidate({
+    const graphPreparation = renderSystem.prepareRecoveryGraphCandidate({
       internals: candidateInternals,
       pipelineState: candidatePipelineState,
     });
@@ -872,7 +872,6 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
         candidatePostProcessResources,
         preparedRecoveryRoots,
         recoveryGraphCandidate,
-        recoveryColdWorkGuard,
       );
       if (recoveryGraphCandidate !== undefined) {
         recoveryGraphCandidate = undefined;

package/src/assembly/renderer-facade.ts

@@ -21,6 +21,7 @@ import {
   STANDARD_POST_STAGE_NAMES,
 } from '../pipeline/standard-profile';
 import type {
+  FrameObservationDomain,
   Renderer,
   RendererError,
   RendererEventListener,
@@ -29,6 +30,7 @@ import type {
   RenderProfile,
   RenderResult,
 } from '../render-contract';
+import { resolveSsaoParameters } from '../ssao-config';
 import type { RendererHostImplementation } from './host-contract';
 import { createRendererLifecycle, isRendererStateOperational } from './renderer-lifecycle';
 
@@ -88,6 +90,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
   });
 
   return {
+    instances: renderer.instances,
+    bounds: (world, entity) => (disposed ? undefined : renderer.bounds(world, entity)),
     attach: (world) => {
       const result = renderer.attach(world);
       return result.ok
@@ -105,6 +109,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
       candidate: DynamicGeometryCandidate,
       ordering: DynamicGeometryOrdering,
     ) => renderer.acceptDynamicGeometry(candidate, ordering),
+    acceptDynamicGeometryCandidates: (candidates, ordering) =>
+      renderer.acceptDynamicGeometryCandidates(candidates, ordering),
     dynamicGeometryReceipt: (candidate: DynamicGeometryCandidate) =>
       renderer.dynamicGeometryReceipt(candidate),
     cancelDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
@@ -147,10 +153,19 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           kind: 'frame-submitted',
           frameId: result.value.frameId,
           deviceGeneration: result.value.deviceGeneration,
+          receipt: result.value,
         }),
       );
       return ok(result.value);
     },
+    requestObservation: (domains: readonly FrameObservationDomain[]) =>
+      renderer.requestObservation?.(domains) ??
+      err(
+        new RendererOperationError('renderer-state-invalid', {
+          operation: 'request-observation',
+          state: lifecycle.state(),
+        }),
+      ),
     inspect: () => ({ ...renderer.inspect(), state: lifecycle.state() }),
     observe: (receipt, request) => renderer.observe(receipt, request),
     subscribe: (listener) => {
@@ -337,9 +352,26 @@ export function validateRenderProfile(profile: RenderProfile): string | undefine
   if (profile.shadows !== 'off' && profile.shadows !== 'hard' && profile.shadows !== 'filtered') {
     return "RenderProfile.shadows must be 'off', 'hard', or 'filtered'";
   }
-  for (const field of ['pbr', 'ibl', 'ssao'] as const) {
+  for (const field of ['pbr', 'ibl'] as const) {
     if (typeof profile[field] !== 'boolean') return `RenderProfile.${field} must be boolean`;
   }
+  if (
+    typeof profile.ssao !== 'boolean' &&
+    (typeof profile.ssao !== 'object' || profile.ssao === null || Array.isArray(profile.ssao))
+  )
+    return 'RenderProfile.ssao must be boolean or AO parameters';
+  if (typeof profile.ssao === 'object') {
+    if (
+      Object.keys(profile.ssao).some(
+        (key) => !['radius', 'bias', 'intensity', 'quality'].includes(key),
+      )
+    )
+      return 'RenderProfile.ssao contains an unsupported parameter';
+    const resolved = resolveSsaoParameters(profile.ssao);
+    if (!resolved.ok) return resolved.error.hint;
+  }
+  if (profile.ssao !== false && profile.renderPath !== 'deferred')
+    return 'SSAO needs current depth and normals: set renderPath to deferred';
   const stages = STANDARD_POST_STAGE_NAMES;
   if (
     !Array.isArray(profile.postStages) ||
@@ -354,6 +386,7 @@ export function validateRenderProfile(profile: RenderProfile): string | undefine
 export function freezeRenderProfile(profile: RenderProfile): RenderProfile {
   return Object.freeze({
     ...profile,
+    ssao: typeof profile.ssao === 'object' ? Object.freeze({ ...profile.ssao }) : profile.ssao,
     postStages: Object.freeze([...profile.postStages]) as RenderProfile['postStages'],
   });
 }

package/src/assembly/renderer-feature-inspection.ts

@@ -0,0 +1,13 @@
+import type { RenderFeatureHost } from '../features/host';
+import type { RenderInspection } from '../render-contract';
+
+/** Project feature-host lifecycle facts without exposing the live host. */
+export function projectRendererFeatureInspection(
+  featureHost: RenderFeatureHost | undefined,
+): Pick<RenderInspection, 'features' | 'featureDiagnostics' | 'featureHost'> {
+  return {
+    features: Object.freeze((featureHost?.features ?? []).map((feature) => feature.identity)),
+    featureDiagnostics: featureHost?.diagnostics() ?? Object.freeze([]),
+    ...(featureHost?.inspection === undefined ? {} : { featureHost: featureHost.inspection() }),
+  };
+}