@forgeax/engine-render 0.1.28 → 0.1.30

package/src/record/view-ubo.ts

@@ -129,6 +129,7 @@ export function writePointsLinesViewUbo(
  *   folded from standalone binding 9 to fix WebGL2 fragment uniform-buffer
  *   overflow; lane N = spot with shadowAtlasTile === N, 16 f32 / lane,
  *   16 B-aligned at byte 528 = float 132).
+ *   [236..239] ssrParams (maxDistance, thickness, maxRoughness, enabled).
  *
  * @internal
  */
@@ -218,6 +219,16 @@ export function writeViewUbo(
     viewPayload[234] = previousCameraPosition[2] ?? 0;
     viewPayload[235] = 1;
   }
+  // SSR uses the fixed View tail as its single per-camera parameter carrier.
+  // Admission has already validated these values; the enabled lane remains
+  // zero when the component is absent so disabled frames carry no demand.
+  const ssr = camera.screenSpaceReflection;
+  if (ssr !== undefined) {
+    viewPayload[236] = ssr.maxDistance;
+    viewPayload[237] = ssr.thickness;
+    viewPayload[238] = ssr.maxRoughness;
+    viewPayload[239] = 1;
+  }
   // splitPlanes at [108..123] (four vec4 lanes: split/world texel/depth span/reserved).
   if (lights.splitPlanes !== undefined) {
     for (let s = 0; s < 4; s++) {
@@ -233,7 +244,7 @@ export function writeViewUbo(
   // accepted quality union occupies the existing four-float tail [128..131].
   // Point and Spot pcfKernelSize stay in their own snapshot paths and never
   // enter this Directional View projection.
-  viewPayload[126] = lights.depthBias ?? 0.005;
+  viewPayload[126] = lights.depthBias ?? 0.00001;
   viewPayload[127] = lights.normalBias ?? 0.05;
   const filterCarrier = directionalShadowFilterCarrier(lights.directionalShadowQuality);
   viewPayload[128] = filterCarrier[0] ?? 0;

package/src/recovery/render-system-candidate.ts

@@ -27,16 +27,20 @@ import {
   type PostProcessShaderEntry,
   postProcessShaderEntrySignature,
 } from '../fullscreen-post-process-pass';
+import { collectGpuDrivenMaterialArtifacts } from '../gpu-driven/material-artifacts';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
-import { disposeInstanceBufferChunks, disposeInstanceBuffers } from '../instance-buffer-cache';
 import { inspectStandardLighting } from '../pipeline/standard-lighting/inspection';
+import { retireAutoExposureGpuResources } from '../pipeline/standard-output/auto-exposure/gpu';
+import {
+  prepareStandardOutputResources,
+  resetStandardOutputForDeviceLoss,
+} from '../pipeline/standard-output/resources';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import { inspectPointShadow } from '../point-shadow-inspection';
 import type { PreparedGraphicsResolver } from '../prepare/prepared-graphics-resolver';
-import { validateRenderables } from '../record/frame';
+import { gpuDrivenMeshesForFrame, validateRenderables } from '../record/frame';
 import { prepareFrameLighting } from '../record/frame-lighting';
 import type { RenderFrameState, ValidatedRenderable } from '../record/frame-snapshot';
-import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
 import { computeSplitLdrSprite } from '../record/main-pass-sprite-draws';
 import {
   prepareRecoveryPipelineReadiness,
@@ -50,13 +54,10 @@ import {
 } from '../record/typed-frame-graph';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
 import type {
-  RecoveryGraphCandidate,
-  RecoveryGraphCandidatePreparation,
-  RecoveryGraphCandidateRuntime,
-  RecoveryGraphSetupSubmission,
-  RecoveryPointsLinesCandidate,
-} from '../render-system';
-import type { ExtractedFrame, MaterialSnapshot } from '../render-system-extract';
+  ExtractedFrame,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
 import type { PersistentGpuDrivenCandidate, PersistentRenderScene } from '../scene/render-scene';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
 import { createTemporalFrameTransaction } from '../temporal/frame';
@@ -64,7 +65,15 @@ import {
   getTemporalBindGroupResources,
   getTemporalGpuState,
   getTemporalParamsBuffer,
+  TEMPORAL_HISTORY_FORMATS,
 } from '../temporal/gpu';
+import type {
+  RecoveryGraphCandidate,
+  RecoveryGraphCandidatePreparation,
+  RecoveryGraphCandidateRuntime,
+  RecoveryGraphSetupSubmission,
+  RecoveryPointsLinesCandidate,
+} from './types';
 
 export interface PreparedResolverCaches {
   readonly preparedPipelineIds: WeakMap<object, string>;
@@ -123,7 +132,7 @@ export interface RenderSystemRecoveryOwner {
   setLastSuccessfulFrameSeed(seed: RecoveryFrameSeed): void;
   prepareRecoveryGraphCandidate(
     runtime: RecoveryGraphCandidateRuntime,
-  ): Promise<RecoveryGraphCandidatePreparation>;
+  ): RecoveryGraphCandidatePreparation;
   submitCandidateSetup(
     candidate: RecoveryGraphCandidate,
     isValid: () => boolean,
@@ -132,22 +141,36 @@ export interface RenderSystemRecoveryOwner {
   discardRecoveryGraphCandidate(candidate: RecoveryGraphCandidate): void;
 }
 
-export function materialTextureHandles(
-  material: MaterialSnapshot,
+/**
+ * Keep the missing-texture sentinel out of residency preparation. A zero
+ * handle is the same absent-reference value used by materialHandle; resolving
+ * it as a real TextureAsset would otherwise pass an undefined pod to the GPU
+ * store and fail before the renderer can produce a structured readiness
+ * result.
+ */
+export function materialTextureHandlesForResidency(
+  candidates: Iterable<Handle<'TextureAsset', 'shared'> | undefined>,
 ): readonly Handle<'TextureAsset', 'shared'>[] {
   const handles = new Map<number, Handle<'TextureAsset', 'shared'>>();
-  const add = (handle: Handle<'TextureAsset', 'shared'> | undefined): void => {
-    if (handle !== undefined) handles.set(Number(handle), handle);
-  };
-  for (const handle of material.textureHandles?.values() ?? []) add(handle);
-  add(material.baseColorTexture);
-  add(material.metallicRoughnessTexture);
-  add(material.normalTexture);
-  add(material.emissiveTexture);
-  add(material.occlusionTexture);
+  for (const handle of candidates) {
+    if (handle !== undefined && Number(handle) !== 0) handles.set(Number(handle), handle);
+  }
   return [...handles.values()];
 }
 
+export function materialTextureHandles(
+  material: MaterialSnapshot,
+): readonly Handle<'TextureAsset', 'shared'>[] {
+  return materialTextureHandlesForResidency([
+    ...(material.textureHandles?.values() ?? []),
+    material.baseColorTexture,
+    material.metallicRoughnessTexture,
+    material.normalTexture,
+    material.emissiveTexture,
+    material.occlusionTexture,
+  ]);
+}
+
 export function materialSamplerHandles(
   material: MaterialSnapshot,
 ): readonly Handle<'SamplerAsset', 'shared'>[] {
@@ -196,6 +219,13 @@ export function createRenderSystemRecovery(
       successfulTemporalFrameIndex: 0,
       temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
       temporalFrameInput: undefined,
+      ssrRequested: false,
+      ssrSpatialAdmission: undefined,
+      ssrHistoryOwner: undefined,
+      ssrHistoryCandidate: undefined,
+      ssrTemporalParamsPayload: undefined,
+      ssrLastCameraEntity: undefined,
+      ssrLastHistoryVersion: undefined,
       graphTargetCapture: undefined,
       perFrameGraph: null,
       directionalShadowCache: null,
@@ -227,8 +257,6 @@ export function createRenderSystemRecovery(
       currentDirectionalShadowView: null,
       currentSpotShadowView: null,
       instanceBuffers: new Map(),
-      instanceBufferChunks: new Map(),
-      instanceResidency: new Map(),
       morphBuffers: new Map(),
       hdrpClusterBinScratch: createClusterBinScratch(),
       hdrpClusterGridScratch: null,
@@ -248,7 +276,7 @@ export function createRenderSystemRecovery(
       instancesBgShared: new WeakMap(),
       materialBgShared: new Map(),
       materialBgAssemblyCache: new Map(),
-      singletonMaterialCache: new Map(),
+      shadowMaterialBindGroups: new WeakMap(),
       postProcessBgCache: new WeakMap(),
       probeBlendBuffers: new Map(),
       probeBlendRecordBufferCapacity: 0,
@@ -257,7 +285,11 @@ export function createRenderSystemRecovery(
   };
 
   const publishRecoveryGraphCandidate = (candidate: RecoveryGraphCandidate): void => {
-    candidate.recoveryReadiness.assertFirstRecoveryFrame();
+    if (candidate.recoveryReadiness.assertFirstRecoveryFrame) {
+      candidate.recoveryReadiness.assertFirstRecoveryFrame();
+    } else {
+      candidate.recoveryReadiness.assertPreparedCache();
+    }
     const previousFeatureHost = internals.featureHost;
     // The caller enters this method only after the active generation swap and
     // after resetForRecover() has shed every lost-device owner. Replace the
@@ -317,9 +349,9 @@ export function createRenderSystemRecovery(
     candidate.release();
   };
 
-  const prepareRecoveryGraphCandidate = async (
+  const prepareRecoveryGraphCandidate = (
     runtime: RecoveryGraphCandidateRuntime,
-  ): Promise<RecoveryGraphCandidatePreparation> => {
+  ): RecoveryGraphCandidatePreparation => {
     const seed = lastSuccessfulFrameSeed;
     if (seed === undefined) return { kind: 'no-seed' };
     const camera = seed.frame.cameras[0];
@@ -330,6 +362,7 @@ export function createRenderSystemRecovery(
     if (camera === undefined) return { kind: 'no-seed' };
 
     const candidateFrameState = createRecoveryCandidateFrameState();
+    resetStandardOutputForDeviceLoss(candidateFrameState, runtime.internals.deviceScope.generation);
     Object.assign(candidateFrameState, {
       temporalFrame: undefined,
       bloomFrameReceipts: undefined,
@@ -356,6 +389,9 @@ export function createRenderSystemRecovery(
     const releaseCandidate = (): void => {
       if (candidateReleased || candidatePublished) return;
       candidateReleased = true;
+      const pendingOutput = candidateFrameState.pendingAutoExposureGpuResources;
+      if (pendingOutput !== undefined) retireAutoExposureGpuResources(pendingOutput);
+      candidateFrameState.pendingAutoExposureGpuResources = undefined;
       for (const work of setupWorks) work.discard();
       setupWorks.length = 0;
       const graph = candidateFrameState.compiledFrameGraph;
@@ -386,13 +422,6 @@ export function createRenderSystemRecovery(
       candidateGpuDrivenScene = undefined;
       candidatePointsLines?.release();
       candidatePointsLines = undefined;
-      disposeInstanceBuffers(candidateFrameState.instanceBuffers, runtime.internals.errorRegistry);
-      if (candidateFrameState.instanceBufferChunks !== undefined) {
-        disposeInstanceBufferChunks(
-          candidateFrameState.instanceBufferChunks,
-          runtime.internals.errorRegistry,
-        );
-      }
       candidateGpuStore.destroyAll();
     };
     const markPublished = (): void => {
@@ -408,30 +437,77 @@ export function createRenderSystemRecovery(
     };
 
     try {
+      const output = prepareStandardOutputResources(
+        candidateFrameState,
+        runtime.internals,
+        camera,
+        seed.worlds[seed.cameraOwner] as World,
+      );
+      if (!output.ok) return failed('candidate Standard output preparation failed', output.error);
       const gpuScene = persistentRenderScene.prepareRecoveryGpuDrivenCandidate(
         runtime.internals.device,
       );
       if (!gpuScene.ok) return failed('candidate GPU scene preparation failed', gpuScene.error);
       candidateGpuDrivenScene = gpuScene.value;
       if (candidateGpuDrivenScene.state !== undefined) {
-        const production = await GpuDrivenProduction.forRecoveryDevice(
+        candidateGpuDrivenProduction = GpuDrivenProduction.forDevice(
           runtime.internals.device,
           gpuDrivenShaderFactory,
-          (descriptor) =>
-            internals.createShaderModule === undefined
-              ? Promise.resolve(gpuDrivenShaderFactory.createShaderModule(descriptor))
-              : internals.createShaderModule(runtime.internals.device, descriptor),
         );
-        if (!production.ok)
-          return failed('candidate GPU-driven shader preparation failed', production.error);
-        candidateGpuDrivenProduction = production.value;
+        const shadowProjection = persistentRenderScene.shadowCasterProjection();
+        // The retained scene owns prepared draw receipts. The extraction seed
+        // precedes GPU admission and must not stand in for that projection.
+        const preparedSnapshots = new Map(
+          candidateGpuDrivenScene.state.slots.map((slot) => [
+            `${slot.snapshot.worldId}:${slot.snapshot.entityKey}`,
+            slot.snapshot,
+          ]),
+        );
+        const artifactRows = (renderables: readonly RenderableSnapshot[]) =>
+          renderables.map((source, renderableIndex) => ({
+            source: {
+              ...source,
+              gpuDrivenDraws:
+                preparedSnapshots.get(`${source.worldId}:${source.entityKey}`)?.gpuDrivenDraws ??
+                source.gpuDrivenDraws ??
+                [],
+            },
+            renderableIndex,
+          }));
+        const { materialArtifacts, shadowMaterialArtifacts, firstArtifact, firstSkinArtifact } =
+          collectGpuDrivenMaterialArtifacts({
+            rows: artifactRows(seed.frame.renderables),
+            shadowRows: artifactRows(shadowProjection?.renderables ?? []),
+            dispatch: seed.frame.dispatch,
+            shadowDispatch: shadowProjection?.dispatch ?? seed.frame.dispatch,
+            resolve: runtime.internals.getMaterialShaderArtifact,
+            clustered:
+              seed.frame.lights.point.length +
+                seed.frame.lights.spot.length +
+                seed.frame.lights.rect.length >
+                0 || candidateFrameState.installedPipelineConfig?.ssao?.enabled === true,
+            reflectionFallback: candidateFrameState.reflectionFallbackDemand === true,
+          });
         const prepared = candidateGpuDrivenProduction.prepare({
           scene: candidateGpuDrivenScene.state,
           camera,
-          meshes: runtime.pipelineState.meshes,
+          meshBySlot: gpuDrivenMeshesForFrame(
+            runtime.internals,
+            runtime.pipelineState,
+            seed.worlds,
+            candidateGpuDrivenScene.state,
+          ),
           viewBindGroupLayout: runtime.pipelineState.viewBindGroupLayout,
           meshResidencyEpoch: runtime.internals.gpuStore.meshResidencyEpoch,
-          hdrp: false,
+
+          ...(firstArtifact === undefined ? {} : { materialArtifact: firstArtifact }),
+          ...(firstSkinArtifact === undefined ? {} : { materialSkinArtifact: firstSkinArtifact }),
+          ...(materialArtifacts.size === 0 ? {} : { materialArtifacts }),
+          ...(shadowMaterialArtifacts.size === 0 ? {} : { shadowMaterialArtifacts }),
+          materialPipelineState: runtime.pipelineState,
+          ...(runtime.internals.getMaterialShaderPipelineEntry === undefined
+            ? {}
+            : { materialPipelineFactory: runtime.internals.getMaterialShaderPipelineEntry }),
         });
         if (!prepared.ok) return failed('candidate GPU-driven preparation failed', prepared.error);
         preparedGpuDriven = prepared.value;
@@ -501,8 +577,14 @@ export function createRenderSystemRecovery(
           ...(batches.length === 0
             ? {}
             : { preparedResourceKey: `recovery-${runtime.internals.deviceScope.generation}` }),
-          onRejected: releaseBatches,
-          onAbandoned: releaseBatches,
+          onRejected: () => {
+            featureFrame.onAborted();
+            releaseBatches();
+          },
+          onAbandoned: () => {
+            featureFrame.onAborted();
+            releaseBatches();
+          },
         };
       }
       for (const renderable of seed.frame.renderables) {
@@ -596,25 +678,6 @@ export function createRenderSystemRecovery(
       if (candidateValidated.length !== seed.frame.renderables.length) {
         return failed('candidate validation did not retain every LKG-visible renderable');
       }
-      for (const entry of candidateValidated) {
-        if (entry.source.instances === undefined) continue;
-        const prepared = resolveGeometryInstanceBuffer(
-          {
-            runtime: runtime.internals,
-            pipelineState: runtime.pipelineState,
-            frameState: candidateFrameState,
-            bindGroupCounts: { createBindGroup: 0, keys: [] },
-          },
-          entry,
-          [],
-          false,
-        );
-        if (prepared === null) return failed('candidate instance preparation failed');
-      }
-      // These uploads belong to recovery preparation, never to a rendered frame.
-      for (const [id, residency] of candidateFrameState.instanceResidency ?? []) {
-        candidateFrameState.instanceResidency?.set(id, { ...residency, frameNumber: -1 });
-      }
       const lighting = prepareFrameLighting(
         runtime.internals,
         candidateFrameState,
@@ -680,7 +743,7 @@ export function createRenderSystemRecovery(
         ) {
           throw new Error(`recovery post-process bindings are unavailable: ${id}`);
         }
-        const pipeline = postProcessPipeline(id, built.bindGroupLayout, colorFormat, entry);
+        const pipeline = postProcessPipeline(id, built.bindGroupLayout, [colorFormat], entry);
         if (pipeline === null) {
           throw new Error(`recovery post-process pipeline is unavailable: ${id}`);
         }
@@ -714,7 +777,11 @@ export function createRenderSystemRecovery(
         const taaPipeline = postProcessPipeline(
           'forgeax.taa-resolve',
           temporalBindings.layout,
-          'rgba16float',
+          [
+            TEMPORAL_HISTORY_FORMATS.color,
+            TEMPORAL_HISTORY_FORMATS.temporal,
+            TEMPORAL_HISTORY_FORMATS.stability,
+          ],
           taaEntry,
         );
         if (taaPipeline === null) {

package/src/recovery/render-system-roots.ts

@@ -0,0 +1,113 @@
+import type { LifecycleResourceSpec } from '../device/device-scope';
+import type { EnvironmentGeneration } from '../environment/generation';
+import type { EnvironmentLifecycle } from '../environment/lifecycle';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import type { RecoveryRootBundle, RecoveryRootRuntime } from '../render-system';
+
+/**
+ * Assemble replacement-device roots without letting candidate construction
+ * publish through the active RenderSystem owner.  The caller supplies the
+ * small state handoff explicitly so this recovery seam remains independent
+ * from frame orchestration.
+ */
+export function prepareRenderSystemRecoveryRoots(
+  runtime: RecoveryRootRuntime,
+  environmentLifecycle: EnvironmentLifecycle,
+  frameState: RenderFrameState,
+  publishEnvironmentLifecycle: (lifecycle: EnvironmentLifecycle) => void,
+): RecoveryRootBundle {
+  const candidateEnvironmentLifecycle = environmentLifecycle.createRecoveryCandidate(runtime.scope);
+  const roots: LifecycleResourceSpec<unknown>[] = [];
+  let candidateEnvironmentGeneration: EnvironmentGeneration | undefined;
+  let environmentRootCleaned = false;
+  let published = false;
+  if (candidateEnvironmentLifecycle.hasRecoveryFrame()) {
+    const environmentRoot = candidateEnvironmentLifecycle.createRecoveryRoot(runtime.scope);
+    roots.push({
+      ...environmentRoot,
+      create: async () => {
+        const generation = (await environmentRoot.create()) as EnvironmentGeneration;
+        candidateEnvironmentGeneration = generation;
+        return generation;
+      },
+      cleanup: (value) => {
+        if (environmentRootCleaned) return;
+        environmentRootCleaned = true;
+        if (candidateEnvironmentGeneration === value) candidateEnvironmentGeneration = undefined;
+        if (published) {
+          candidateEnvironmentLifecycle.retirePublishedGeneration(value as EnvironmentGeneration);
+        } else {
+          environmentRoot.cleanup(value);
+        }
+      },
+    });
+  }
+  const graphCandidate = runtime.graphCandidate;
+  if (graphCandidate !== undefined) {
+    const releaseGraphCandidate = (): void => graphCandidate.release();
+    const compiledGraph = graphCandidate.frameState.compiledFrameGraph;
+    if (compiledGraph !== null) {
+      roots.push({
+        kind: 'pipeline',
+        create: () => {
+          if (!runtime.scope.isAlive())
+            throw new Error('Recovery graph candidate scope is not active.');
+          if (graphCandidate.frameState.compiledFrameGraph !== compiledGraph) {
+            throw new Error('Recovery graph candidate was changed before aggregate assembly.');
+          }
+          return compiledGraph;
+        },
+        cleanup: releaseGraphCandidate,
+      });
+    }
+    if (graphCandidate.featureHost !== undefined) {
+      const featureRoot = graphCandidate.featureHost.createRecoveryRoot(runtime.scope);
+      roots.push({ ...featureRoot, cleanup: releaseGraphCandidate });
+    }
+    if (graphCandidate.featureGpuWork !== undefined) {
+      const featureWorkRoot = graphCandidate.featureGpuWork.createRecoveryRoot(runtime.scope);
+      roots.push({ ...featureWorkRoot, cleanup: releaseGraphCandidate });
+    }
+    if (graphCandidate.gpuDrivenProduction !== undefined) {
+      const productionRoot = graphCandidate.gpuDrivenProduction.createRecoveryRoot(runtime.scope);
+      roots.push({ ...productionRoot, cleanup: releaseGraphCandidate });
+    }
+    if (graphCandidate.gpuDrivenScene?.state !== undefined) {
+      const sceneRoot = graphCandidate.gpuDrivenScene.createRecoveryRoot(runtime.scope);
+      roots.push({ ...sceneRoot, cleanup: releaseGraphCandidate });
+    }
+    if (graphCandidate.pointsLines !== undefined) {
+      const pointsLinesRoot = graphCandidate.pointsLines.createRecoveryRoot(runtime.scope);
+      roots.push({ ...pointsLinesRoot, cleanup: releaseGraphCandidate });
+    }
+    if (runtime.gpuStore.recoveryResourceCount() > 0) {
+      const gpuStoreRoot = runtime.gpuStore.createRecoveryRoot(runtime.scope);
+      roots.push({ ...gpuStoreRoot, cleanup: releaseGraphCandidate });
+    }
+  }
+  let discarded = false;
+  return {
+    roots: Object.freeze(roots),
+    publish: () => {
+      if (published || discarded) return;
+      if (candidateEnvironmentGeneration !== undefined && !candidateEnvironmentGeneration.retired) {
+        environmentLifecycle.retireActiveForReplacement();
+        candidateEnvironmentLifecycle.publish(candidateEnvironmentGeneration);
+      }
+      published = true;
+      publishEnvironmentLifecycle(candidateEnvironmentLifecycle);
+      Object.assign(frameState, { environmentLifecycle: candidateEnvironmentLifecycle });
+    },
+    discard: () => {
+      if (published || discarded) return;
+      discarded = true;
+      if (candidateEnvironmentGeneration !== undefined) {
+        candidateEnvironmentLifecycle.discard(candidateEnvironmentGeneration);
+        candidateEnvironmentGeneration = undefined;
+      }
+      candidateEnvironmentLifecycle.discardRecoveryCandidates();
+      graphCandidate?.release();
+      runtime.scope.abandon();
+    },
+  };
+}

package/src/recovery/types.ts

@@ -0,0 +1,77 @@
+import type { MipmapEncoderWork } from '@forgeax/engine-assets-runtime';
+import type { Buffer, RenderPipeline, RhiDevice } from '@forgeax/engine-rhi';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
+import type { GpuResidencyCache } from '../device/gpu-residency';
+import type { RenderFeatureHost } from '../features/host';
+import type { RenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
+import type { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import type { RecoveryPipelineReadiness } from '../record/recovery-pipeline';
+import type { PipelineState, RenderSystemInternals } from '../record/render-context';
+import type { RenderFeatureGraphCandidate } from '../record/typed-frame-graph';
+import type { PersistentGpuDrivenCandidate } from '../scene/render-scene';
+
+/** The single Points/Lines owner's staged device-generation handoff. */
+export interface RecoveryPointsLinesCandidate {
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
+  publish(): void;
+  release(): void;
+}
+
+/** Candidate-only device/runtime inputs used by the recovery prepare seam. */
+export interface RecoveryGraphCandidateRuntime {
+  readonly internals: RenderSystemInternals;
+  readonly pipelineState: PipelineState;
+}
+
+/** Detached graph state prepared on a replacement device, before publication. */
+export interface RecoveryGraphCandidate {
+  readonly frameState: RenderFrameState;
+  readonly setupWorks: readonly MipmapEncoderWork[];
+  readonly device: RhiDevice;
+  readonly generation: number;
+  readonly gpuDrivenProduction?: GpuDrivenProduction;
+  readonly gpuDrivenScene?: PersistentGpuDrivenCandidate;
+  /** Staged CPU-expanded Points/Lines buffers owned by the same RenderSystem. */
+  readonly pointsLines?: RecoveryPointsLinesCandidate;
+  readonly featureHost?: RenderFeatureHost;
+  readonly featureGpuWork?: RenderFeatureGpuWorkOwner;
+  readonly featureGraphCandidate?: RenderFeatureGraphCandidate;
+  readonly postProcessPipelines?: ReadonlyMap<string, RenderPipeline>;
+  readonly recoveryReadiness: RecoveryPipelineReadiness;
+  /** Release all candidate roots before publication; safe to call repeatedly. */
+  readonly release: () => void;
+  /** Transfer candidate-root ownership to the published RenderSystem. */
+  readonly markPublished: () => void;
+}
+
+/** Candidate setup completion; completion is bounded by the recovery owner. */
+export interface RecoveryGraphSetupSubmission {
+  readonly completion?: PromiseLike<unknown>;
+}
+
+export type RecoveryGraphCandidatePreparation =
+  | { readonly kind: 'no-seed' }
+  | { readonly kind: 'ready'; readonly candidate: RecoveryGraphCandidate }
+  | { readonly kind: 'failed'; readonly reason: string; readonly cause?: unknown };
+
+/** Explicit candidate-owned inputs for lifecycle-root preparation. */
+export interface RecoveryRootRuntime {
+  readonly scope: DeviceScope;
+  readonly device: RhiDevice;
+  readonly gpuStore: GpuResidencyCache;
+  readonly graphCandidate?: RecoveryGraphCandidate | undefined;
+}
+
+/** Candidate roots plus the one synchronous owner switch at publication. */
+export interface RecoveryRootBundle {
+  readonly roots: readonly LifecycleResourceSpec<unknown>[];
+  publish(): void;
+  discard(): void;
+}
+
+/** Device-bound post-process resources prepared off to the side of the active renderer. */
+export interface RecoveryPostProcessResources {
+  readonly device: RhiDevice;
+  readonly paramsBuffers: Map<string, Buffer>;
+}