@forgeax/engine-render 0.1.23 → 0.1.25

package/src/device/gpu-residency.ts

@@ -32,7 +32,9 @@
 import {
   blitMipmapsSync,
   getOrCreateMipmapPipeline,
+  type MipmapEncoderWork,
   type MipmapShaderModuleFactory,
+  prepareMipmaps,
 } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
 import {
@@ -98,6 +100,7 @@ import {
   runIblPrecompute,
 } from '../ibl/IblPipelineCache';
 import type { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RecoveryColdWorkGuard } from '../record/render-context';
 import {
   type CubeRenderData,
   deriveRenderDataCubemap,
@@ -106,7 +109,7 @@ import {
   type MeshRenderData,
   type TextureRenderData,
 } from '../render-data';
-import type { DeviceScope } from './device-scope';
+import type { DeviceScope, LifecycleResourceSpec } from './device-scope';
 
 const DYNAMIC_OFFSET_STRIDE = 256;
 const FACE_COUNT = 6;
@@ -182,6 +185,7 @@ export function writePrefilterUniforms(
   subPassIdx: number,
   roughness: number,
   mipFaceSize: number,
+  sourceMipLevelCount = 1,
 ): Result<void, RhiError> {
   if (subPassIdx < 0 || subPassIdx >= PREFILTER_SUBPASS_COUNT) {
     return invalidUniformInput(
@@ -189,13 +193,20 @@ export function writePrefilterUniforms(
       `writePrefilterUniforms received subPassIdx=${subPassIdx}`,
     );
   }
-  const payload = new Float32Array([roughness, mipFaceSize, 0, 0]);
+  if (!Number.isInteger(sourceMipLevelCount) || sourceMipLevelCount < 1) {
+    return invalidUniformInput(
+      'sourceMipLevelCount is a positive integer matching the bound source cube mip levels',
+      `writePrefilterUniforms received sourceMipLevelCount=${sourceMipLevelCount}`,
+    );
+  }
+  const payload = new Float32Array([roughness, mipFaceSize, sourceMipLevelCount, 0]);
   return device.queue.writeBuffer(buffer, subPassIdx * DYNAMIC_OFFSET_STRIDE, payload);
 }
 
 export function writeAllPrefilterUniforms(
   device: FaceUniformsDevice,
   buffer: Buffer,
+  sourceMipLevelCount = 1,
 ): Result<void, RhiError> {
   for (let mip = 0; mip < PREFILTER_MIP_LEVELS; mip++) {
     const roughness = mip / (PREFILTER_MIP_LEVELS - 1);
@@ -207,6 +218,7 @@ export function writeAllPrefilterUniforms(
         mip * FACE_COUNT + face,
         roughness,
         mipFaceSize,
+        sourceMipLevelCount,
       );
       if (!result.ok) return result;
     }
@@ -303,6 +315,11 @@ export interface TextureGpuEntry {
   readonly receipt: TextureResidencyReceipt;
 }
 
+/** Candidate-only residency work; no queue submission is hidden here. */
+export interface RecoveryResidencyPreparation {
+  readonly mipmapWork?: MipmapEncoderWork;
+}
+
 // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M2 / w11
 // (D-3): the projection-status truth lives here (the store's cubemap map is the
 // single authority — the SkylightSnapshot carries no status, D-3). `status`:
@@ -529,6 +546,7 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
+  private recoveryColdWorkGuard: RecoveryColdWorkGuard | undefined;
   private deviceEpoch = 0;
   private textureGeneration = 0;
 
@@ -607,6 +625,11 @@ export class GpuResidencyCache {
     this.deviceScope = scope;
   }
 
+  /** Arm the first-published-frame assertion on this generation's store. */
+  setRecoveryColdWorkGuard(guard: RecoveryColdWorkGuard | undefined): void {
+    this.recoveryColdWorkGuard = guard;
+  }
+
   /**
    * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
    * reference to the device so `.destroy()` forwards to
@@ -695,6 +718,39 @@ export class GpuResidencyCache {
     this.meshGpuHandles.clear();
   }
 
+  /** Number of candidate-owned GPU resources currently held by this cache. */
+  recoveryResourceCount(): number {
+    let cubemapResources = 0;
+    const seen = new Set<GpuTexture>();
+    for (const entry of this.cubemapGpuHandles.values()) {
+      if (entry.texture !== null && !seen.has(entry.texture)) {
+        seen.add(entry.texture);
+        cubemapResources += 1;
+      }
+    }
+    return (
+      this.meshGpuHandles.size +
+      this.textureGpuHandles.size +
+      this.samplerGpuHandles.size +
+      cubemapResources
+    );
+  }
+
+  /** Candidate root for the cache owner, not a scalar readiness marker. */
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'texture',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('GPU residency candidate scope is not active.');
+        if (this.recoveryResourceCount() === 0) {
+          throw new Error('GPU residency candidate has no prepared resources.');
+        }
+        return this;
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   /**
    * Set the error registry channel (wired by createRenderer). evict /
    * releaseUnreferenced fire structured errors here instead of throwing -
@@ -970,6 +1026,7 @@ export class GpuResidencyCache {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
     if (existing !== undefined) return ok(existing);
+    this.recoveryColdWorkGuard?.noteUploadColdWork();
     const device = this.gpuDevice;
     if (device === undefined) {
       return err(
@@ -1102,6 +1159,7 @@ export class GpuResidencyCache {
         const key = this.worldKey(id, worldId);
         const existing = this.meshGpuHandles.get(key);
         if (existing !== undefined) return ok(existing);
+        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1110,6 +1168,7 @@ export class GpuResidencyCache {
         const texKey = this.worldKey(id, worldId);
         const existing = this.textureGpuHandles.get(texKey);
         if (existing !== undefined) return ok(existing);
+        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataTexture(pod);
         if (!projected.ok) return projected;
         const decoded: DecodedImage = decodedFromTexture(pod);
@@ -1124,6 +1183,101 @@ export class GpuResidencyCache {
     }
   }
 
+  /**
+   * Prepare one candidate-visible resource without the normal draw-time mip
+   * submission. Base writes and resource creation stay owned by this cache;
+   * generated mip passes are returned to the recovery transaction for one
+   * explicit finish/submit before publication.
+   */
+  prepareResidentForRecovery(
+    handle: Handle<'MeshAsset', 'shared'>,
+    pod: TypesMeshAsset,
+    worldId?: World | number,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
+  prepareResidentForRecovery(
+    handle: Handle<'TextureAsset', 'shared'>,
+    pod: TextureAsset,
+    worldId?: World | number,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
+  prepareResidentForRecovery(
+    handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
+    pod: TypesMeshAsset | TextureAsset,
+    worldId: World | number = 0,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError> {
+    const id = handleSlot(handle);
+    if (pod.kind === 'mesh') {
+      const key = this.worldKey(id, worldId);
+      if (this.meshGpuHandles.has(key)) return ok({});
+      const projected = deriveRenderDataMesh(pod);
+      if (!projected.ok) return projected;
+      const uploaded = this.uploadMeshById(key, pod, projected.value);
+      return uploaded.ok ? ok({}) : uploaded;
+    }
+
+    const cacheKey = this.worldKey(id, worldId);
+    if (this.textureGpuHandles.has(cacheKey)) return ok({});
+    const projected = deriveRenderDataTexture(pod);
+    if (!projected.ok) return projected;
+    const decoded = decodedFromTexture(pod);
+    const prepared = this.prepareTextureUpload(
+      handle as Handle<'TextureAsset', 'shared'>,
+      pod,
+      decoded,
+      projected.value,
+    );
+    if (!prepared.ok) return prepared;
+    const device = this.gpuDevice;
+    const gpuTexture = prepared.value.gpuTexture;
+    if (device === undefined || gpuTexture === undefined) {
+      return err(
+        new RhiError({
+          code: 'rhi-not-available',
+          expected: 'GpuResidencyCache.configureGpuDevice wired before recovery residency',
+          hint: 'configure the candidate store before preparing recovery resources',
+        }),
+      );
+    }
+
+    let mipmapWork: MipmapEncoderWork | undefined;
+    if (!projected.value.compressed && pod.mips.kind === 'generate' && prepared.value.levels > 1) {
+      const preparedMipmaps = prepareMipmaps(device, gpuTexture, {
+        format: projected.value.format,
+        width: pod.shape.extent.width,
+        height: pod.shape.extent.height,
+        levels: prepared.value.levels,
+      });
+      if (!preparedMipmaps.ok) {
+        new GpuTexture(device, gpuTexture).destroy();
+        return preparedMipmaps;
+      }
+      mipmapWork = preparedMipmaps.value;
+    }
+    const viewRes = device.createTextureView(gpuTexture, {
+      label: `texture-view-${cacheKey}`,
+      dimension: projected.value.shape.viewDimension,
+    });
+    if (!viewRes.ok) {
+      new GpuTexture(device, gpuTexture).destroy();
+      return viewRes;
+    }
+    const previous = this.textureGpuHandles.get(cacheKey);
+    const entry: TextureGpuEntry = {
+      texture: this.wrapTex(gpuTexture),
+      view: viewRes.value,
+      receipt: this.textureReceipt(pod, projected.value),
+    };
+    this.textureGpuHandles.set(cacheKey, entry);
+    this.materialResourceEpoch += 1;
+    if (
+      previous !== undefined &&
+      previous.texture !== entry.texture &&
+      !previous.texture.isDestroyed
+    ) {
+      previous.texture.destroy();
+    }
+    return ok(mipmapWork === undefined ? {} : { mipmapWork });
+  }
+
   /**
    * Eager public surface: upload decoded image bytes into a GPU texture and
    * cache (texture + view) under the handle. The TextureAsset POD supplies the
@@ -1618,6 +1772,7 @@ export class GpuResidencyCache {
     // universally renderable rgba8 path; the same format is threaded through
     // the cubemap and all three IBL side textures by IblPipelineCache.
     const outputFormat = this.caps?.rgba16floatRenderable === false ? 'rgba8unorm' : tex.format;
+    const sourceMipLevelCount = 1;
 
     // Lazy projection runs from the record arm, where the RHI device is always
     // wired (research R-5). The IBL path is deliberately independent from the
@@ -1643,7 +1798,7 @@ export class GpuResidencyCache {
     const gpuTextureResult = device.createTexture({
       label: `cubemap-${sourceId}`,
       size: { width: cubeFaceSize, height: cubeFaceSize, depthOrArrayLayers: 6 },
-      mipLevelCount: 1,
+      mipLevelCount: sourceMipLevelCount,
       sampleCount: 1,
       dimension: '2d',
       format: outputFormat,
@@ -1682,13 +1837,6 @@ export class GpuResidencyCache {
     // surfacing exactly one destroy call per physical resource.
     const gpuTextureWrapper = this.wrapTex(gpuTexture);
 
-    this.cubemapGpuHandles.set(sourceId, {
-      status: 'ready',
-      texture: gpuTextureWrapper,
-      view: cubeView,
-      faceViews,
-    });
-
     // The minted cubemap handle is a synthetic shared ref (identity token for
     // the GPU cube residency); its POD is an EquirectAsset placeholder matching
     // the projected dimensions/format (D-3: the retired cube-texture asset kind
@@ -1701,20 +1849,6 @@ export class GpuResidencyCache {
       data: tex.data,
       colorSpace: 'linear',
     };
-    const regResult = registerCube(world, cubeAsset);
-    if (!regResult.ok) return recordFailed(regResult.error);
-    const cubeHandle = regResult.value;
-    const cubeId = handleSlot(cubeHandle);
-
-    this.cubemapGpuHandles.set(cubeId, {
-      status: 'ready',
-      texture: gpuTextureWrapper,
-      view: cubeView,
-      faceViews,
-    });
-
-    this.cubemapIdempotentMap.set(sourceId, cubeHandle);
-
     const pipelinesResult = await createIblPipelines(
       scope,
       device,
@@ -1748,6 +1882,9 @@ export class GpuResidencyCache {
     });
     if (!equirectTextureResult.ok) return recordFailed(equirectTextureResult.error);
     const equirectGpuTex = equirectTextureResult.value;
+    scope._adopt('texture', equirectGpuTex, (texture) => {
+      device.destroyTexture(texture);
+    });
 
     const equirectViewResult = device.createTextureView(equirectGpuTex, {
       label: `equirect-view-${sourceId}`,
@@ -1775,9 +1912,15 @@ export class GpuResidencyCache {
     const faceBufferResult = createFaceUniformsBuffer(device);
     if (!faceBufferResult.ok) return recordFailed(faceBufferResult.error);
     const faceBuf = faceBufferResult.value;
+    scope._adopt('buffer', faceBuf, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
     const prefilterBufferResult = createPrefilterUniformsBuffer(device);
     if (!prefilterBufferResult.ok) return recordFailed(prefilterBufferResult.error);
     const prefBuf = prefilterBufferResult.value;
+    scope._adopt('buffer', prefBuf, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
 
     const cubeVertexResult = device.createBuffer({
       label: 'ibl-cube-verts',
@@ -1787,15 +1930,18 @@ export class GpuResidencyCache {
     });
     if (!cubeVertexResult.ok) return recordFailed(cubeVertexResult.error);
     const cubeVertex = cubeVertexResult.value;
+    scope._adopt('buffer', cubeVertex, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
 
     const cubeVertexWriteResult = device.queue.writeBuffer(cubeVertex, 0, CUBEMAP_FACE_VERTICES);
     if (!cubeVertexWriteResult.ok) return recordFailed(cubeVertexWriteResult.error);
     const faceUniformsResult = writeAllFaceUniforms(device, faceBuf);
     if (!faceUniformsResult.ok) return recordFailed(faceUniformsResult.error);
-    const prefilterUniformsResult = writeAllPrefilterUniforms(device, prefBuf);
+    const prefilterUniformsResult = writeAllPrefilterUniforms(device, prefBuf, sourceMipLevelCount);
     if (!prefilterUniformsResult.ok) return recordFailed(prefilterUniformsResult.error);
 
-    const runResult = runIblPrecompute({
+    const runResult = await runIblPrecompute({
       scope,
       device,
       equirectGpuTex,
@@ -1817,6 +1963,28 @@ export class GpuResidencyCache {
       );
     }
 
+    // A source becomes visible to the record arm only after all four passes
+    // completed their queue fence. Registration and the idempotent map are
+    // publication, not allocation, so a failed precompute cannot expose a
+    // ready cube or a loadable handle.
+    this.cubemapGpuHandles.set(sourceId, {
+      status: 'ready',
+      texture: gpuTextureWrapper,
+      view: cubeView,
+      faceViews,
+    });
+    const regResult = registerCube(world, cubeAsset);
+    if (!regResult.ok) return recordFailed(regResult.error);
+    const cubeHandle = regResult.value;
+    const cubeId = handleSlot(cubeHandle);
+    this.cubemapGpuHandles.set(cubeId, {
+      status: 'ready',
+      texture: gpuTextureWrapper,
+      view: cubeView,
+      faceViews,
+    });
+    this.cubemapIdempotentMap.set(sourceId, cubeHandle);
+
     return ok(cubeHandle);
   }
 

package/src/environment/frame.ts

@@ -12,6 +12,12 @@ import { environmentFactSignatures } from './signature';
 
 export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
 
+/** Producer-local fallback while replacement environment storage is uninitialized. */
+export const SKYLIGHT_RECOVERY_FALLBACK = Object.freeze({
+  kind: 'skylight',
+  active: false,
+} as const);
+
 export interface SunCandidate {
   readonly entityKey: number;
   readonly direction: readonly [number, number, number];

package/src/environment/inspection.ts

@@ -38,6 +38,14 @@ export interface EnvironmentInspection {
   readonly residentBytes: number;
   readonly retiringBytes: number;
   readonly lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+  readonly recovery:
+    | {
+        readonly token: number;
+        readonly deviceGeneration: number;
+        readonly status: 'uninitialized';
+        readonly fallback: 'skylight';
+      }
+    | undefined;
 }
 
 export function inspectEnvironment(
@@ -50,6 +58,7 @@ export function inspectEnvironment(
     readonly lkg?: EnvironmentInspectionGeneration;
     readonly candidate?: EnvironmentInspectionGeneration;
     readonly lastCandidateFailure?: EnvironmentInspectionFailure;
+    readonly recovery?: EnvironmentInspection['recovery'];
     readonly retiringBytes?: number;
   } = {},
 ): EnvironmentInspection {
@@ -83,5 +92,6 @@ export function inspectEnvironment(
     residentBytes: active?.residentBytes ?? 0,
     retiringBytes: details.retiringBytes ?? active?.retiringBytes ?? 0,
     lastCandidateFailure: details.lastCandidateFailure,
+    recovery: details.recovery,
   });
 }

package/src/environment/lifecycle.ts

@@ -1,7 +1,7 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
-import type { DeviceScope } from '../device/device-scope';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import { EnvironmentGenerationFailedError } from '../errors/render';
-import type { EnvironmentFrame } from './frame';
+import { type EnvironmentFrame, SKYLIGHT_RECOVERY_FALLBACK } from './frame';
 import type { EnvironmentGeneration, EnvironmentGenerationFailure } from './generation';
 import { sharedEnvironmentFrame } from './graph';
 import {
@@ -20,8 +20,11 @@ interface RetiredGeneration {
   readonly generation: EnvironmentGeneration;
 }
 
+let nextEnvironmentToken = 1;
+
 /** Owns candidate, active, LKG, and DeviceScope generation transitions. */
 export class EnvironmentLifecycle {
+  private readonly token = nextEnvironmentToken++;
   private currentScope: DeviceScope;
   private nextGeneration = 0;
   private active: EnvironmentGeneration | undefined;
@@ -31,6 +34,13 @@ export class EnvironmentLifecycle {
   private readonly retired: RetiredGeneration[] = [];
   private readonly leaseCounts = new Map<number, number>();
   private lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+  private recovery:
+    | {
+        readonly deviceGeneration: number;
+        readonly frame: EnvironmentFrame;
+        readonly lane: 'direct' | 'clustered';
+      }
+    | undefined;
 
   constructor(scope: DeviceScope) {
     this.currentScope = scope;
@@ -41,6 +51,63 @@ export class EnvironmentLifecycle {
     this.currentScope = scope;
   }
 
+  resetForRecover(deviceGeneration: number): void {
+    if (!Number.isSafeInteger(deviceGeneration) || deviceGeneration < 0) {
+      throw new RangeError('deviceGeneration must be a non-negative safe integer.');
+    }
+    const frame = this.active === undefined ? undefined : this.frames.get(this.active.signature);
+    if (frame !== undefined) {
+      this.recovery = Object.freeze({
+        deviceGeneration,
+        frame,
+        lane: this.active?.lane ?? 'direct',
+      });
+    }
+  }
+
+  /**
+   * Create an environment owner for a recovery candidate without moving the
+   * active owner's scope or generation maps. Only the selected CPU frame and
+   * its lane are shared; every candidate generation/frame map starts empty.
+   */
+  createRecoveryCandidate(scope: DeviceScope): EnvironmentLifecycle {
+    const candidate = new EnvironmentLifecycle(scope);
+    const activeFrame =
+      this.recovery?.frame ??
+      (this.active === undefined ? undefined : this.frames.get(this.active.signature));
+    if (activeFrame !== undefined) {
+      candidate.recovery = Object.freeze({
+        deviceGeneration: scope.generation,
+        frame: activeFrame,
+        lane: this.recovery?.lane ?? this.active?.lane ?? 'direct',
+      });
+    }
+    candidate.lastCandidateFailure = this.lastCandidateFailure;
+    return candidate;
+  }
+
+  /** True when a CPU environment frame is available for candidate recovery. */
+  hasRecoveryFrame(): boolean {
+    return (
+      this.recovery?.frame !== undefined ||
+      (this.active !== undefined && this.frames.has(this.active.signature))
+    );
+  }
+
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'texture',
+      create: async () => {
+        const recovered = await this.recover(scope);
+        if (!recovered.ok) throw recovered.error;
+        return recovered.value;
+      },
+      cleanup: (value) => {
+        this.discard(value as EnvironmentGeneration);
+      },
+    };
+  }
+
   isActive(generation: EnvironmentGeneration): boolean {
     return (
       this.active?.generation === generation.generation &&
@@ -56,6 +123,14 @@ export class EnvironmentLifecycle {
     this.frames.delete(generation.signature);
     generation.retired = true;
     generation.scope.retire();
+    if (this.recovery?.frame.signature === generation.signature) this.recovery = undefined;
+    if (this.candidates.size === 0) this.recovery = undefined;
+  }
+
+  /** Drop every uncommitted generation owned by an abandoned candidate. */
+  discardRecoveryCandidates(): void {
+    for (const generation of [...this.candidates.values()]) this.discard(generation);
+    this.recovery = undefined;
   }
 
   recordCandidateFailure(error: EnvironmentGenerationFailedError): void {
@@ -157,6 +232,28 @@ export class EnvironmentLifecycle {
     }
     this.active = generation;
     this.lkg = generation;
+    this.recovery = undefined;
+  }
+
+  /** Close the old active generation before a replacement owner is installed. */
+  retireActiveForReplacement(): void {
+    const active = this.active;
+    if (active === undefined) return;
+    this.active = undefined;
+    if (this.lkg === active) this.lkg = undefined;
+    active.retired = true;
+    active.scope.retire();
+    this.recovery = undefined;
+  }
+
+  /** Close an already-published generation when its owning scope retires. */
+  retirePublishedGeneration(generation: EnvironmentGeneration): void {
+    if (this.active !== generation) return;
+    this.active = undefined;
+    if (this.lkg === generation) this.lkg = undefined;
+    generation.retired = true;
+    generation.scope.retire();
+    this.recovery = undefined;
   }
 
   acquire(): EnvironmentLease {
@@ -237,24 +334,33 @@ export class EnvironmentLifecycle {
       ...(this.lastCandidateFailure === undefined
         ? {}
         : { lastCandidateFailure: this.lastCandidateFailure }),
+      ...(this.recovery === undefined
+        ? {}
+        : {
+            recovery: {
+              token: this.token,
+              deviceGeneration: this.recovery.deviceGeneration,
+              status: 'uninitialized' as const,
+              fallback: SKYLIGHT_RECOVERY_FALLBACK.kind,
+            },
+          }),
     });
   }
 
   async recover(
     scope: DeviceScope,
   ): Promise<Result<EnvironmentGeneration, EnvironmentGenerationFailedError>> {
-    if (this.active === undefined)
-      return err(new EnvironmentGenerationFailedError('none', 'prepare'));
     this.currentScope = scope;
     const previous = this.active;
-    this.candidates.delete(previous.signature);
-    const previousFrame = this.frames.get(previous.signature);
+    const previousFrame =
+      this.recovery?.frame ??
+      (previous === undefined ? undefined : this.frames.get(previous.signature));
     if (previousFrame === undefined) {
       return err(new EnvironmentGenerationFailedError('none', 'prepare'));
     }
     const result = await this.ensure(
-      sharedEnvironmentFrame(previousFrame, previous.lane),
-      previous.lane,
+      sharedEnvironmentFrame(previousFrame, previous?.lane ?? 'direct'),
+      this.recovery?.lane ?? previous?.lane ?? 'direct',
     );
     if (!result.ok) return result;
     return ok(result.value);