@forgeax/engine-render 0.1.21 → 0.1.24

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`:
@@ -324,6 +341,123 @@ interface CubemapGpuEntry {
   faceViews: readonly TextureView[];
 }
 
+interface PackedMeshLodGeometry {
+  readonly vertices: Float32Array;
+  readonly indices: Uint16Array | Uint32Array | undefined;
+  readonly lodRanges: readonly (readonly MeshGpuRange[])[] | undefined;
+}
+
+function packMeshLodGeometry(
+  root: TypesMeshAsset,
+  rootData: MeshRenderData,
+  lowerMeshes: readonly TypesMeshAsset[],
+): Result<PackedMeshLodGeometry, RhiError> {
+  if (lowerMeshes.length === 0) {
+    return ok({ vertices: root.vertices, indices: root.indices, lodRanges: undefined });
+  }
+  const rootStride = rootData.layoutProjection.arrayStride;
+  const allMeshes = [root, ...lowerMeshes];
+  const lowerData: MeshRenderData[] = [];
+  for (const lower of lowerMeshes) {
+    const projected = deriveRenderDataMesh(lower);
+    if (!projected.ok) {
+      return err(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'every MeshAsset LOD to project to a compatible GPU layout',
+          hint: 'repair the lower-detail MeshAsset attributes before drawing the LOD chain',
+        }),
+      );
+    }
+    lowerData.push(projected.value);
+  }
+  if (
+    lowerData.some(
+      (data) =>
+        data.layoutProjection.arrayStride !== rootStride ||
+        data.submeshes.length !== rootData.submeshes.length ||
+        data.indexFormat !== rootData.indexFormat,
+    )
+  ) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'LOD meshes to share vertex/index layout and material-slot topology',
+        hint: 'reimport LOD meshes with matching attributes, index format, and submesh slots',
+      }),
+    );
+  }
+  if (allMeshes.some((mesh) => (mesh.indices === undefined) !== (root.indices === undefined))) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'all LOD meshes to use the same indexed or non-indexed draw mode',
+        hint: 'reimport the LOD chain with consistent index data',
+      }),
+    );
+  }
+  const vertices = new Float32Array(allMeshes.reduce((sum, mesh) => sum + mesh.vertices.length, 0));
+  const ranges: MeshGpuRange[][] = [];
+  let vertexCursor = 0;
+  let indexCursor = 0;
+  const indexed = root.indices !== undefined;
+  const sourceIndices: number[] = [];
+  let requiresUint32 = root.indices instanceof Uint32Array;
+  for (let level = 0; level < allMeshes.length; level += 1) {
+    const mesh = allMeshes[level];
+    const data = level === 0 ? rootData : lowerData[level - 1];
+    if (mesh === undefined || data === undefined) continue;
+    vertices.set(mesh.vertices, vertexCursor);
+    const levelRanges: MeshGpuRange[] = [];
+    for (let submeshIndex = 0; submeshIndex < data.submeshes.length; submeshIndex += 1) {
+      const submesh = data.submeshes[submeshIndex];
+      const rootSubmesh = rootData.submeshes[submeshIndex];
+      if (
+        submesh === undefined ||
+        rootSubmesh === undefined ||
+        submesh.materialSlot !== rootSubmesh.materialSlot ||
+        submesh.topology !== rootSubmesh.topology
+      ) {
+        return err(
+          new RhiError({
+            code: 'asset-not-registered',
+            expected: 'LOD submeshes to preserve root material-slot and topology identity',
+            hint: 'repair LOD material slots and primitive topology before import',
+          }),
+        );
+      }
+      levelRanges.push(
+        indexed
+          ? {
+              first: indexCursor + submesh.indexOffset,
+              count: submesh.indexCount,
+              baseVertex: vertexCursor / (rootStride / 4),
+            }
+          : { first: vertexCursor / (rootStride / 4), count: submesh.vertexCount, baseVertex: 0 },
+      );
+    }
+    ranges.push(levelRanges);
+    if (indexed) {
+      const indices = mesh.indices;
+      if (indices === undefined) continue;
+      for (const value of indices) {
+        // Each LOD range carries its vertex cursor as baseVertex, so keep
+        // indices local to that LOD and apply the offset exactly once at draw.
+        sourceIndices.push(value);
+        if (value > 0xffff || indices instanceof Uint32Array) requiresUint32 = true;
+      }
+      indexCursor += indices.length;
+    }
+    vertexCursor += mesh.vertices.length;
+  }
+  const indices = indexed
+    ? requiresUint32
+      ? Uint32Array.from(sourceIndices)
+      : Uint16Array.from(sourceIndices)
+    : undefined;
+  return ok({ vertices, indices, lodRanges: ranges });
+}
+
 export interface MeshGpuHandles {
   readonly vertexBuffer: GpuBuffer;
   /**
@@ -374,6 +508,14 @@ export interface MeshGpuHandles {
    * For single-submesh meshes this is a 1-element array (byte-identical to pre-M4).
    */
   readonly submeshes: readonly import('@forgeax/engine-types').Submesh[];
+  /** Packed root + lower-detail geometry ranges in the shared mesh buffers. */
+  readonly lodRanges?: readonly (readonly MeshGpuRange[])[];
+}
+
+export interface MeshGpuRange {
+  readonly first: number;
+  readonly count: number;
+  readonly baseVertex: number;
 }
 
 /**
@@ -404,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;
 
@@ -482,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
@@ -570,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 -
@@ -845,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(
@@ -951,6 +1133,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     pod: TypesMeshAsset,
     worldId?: World | number,
+    lodMeshes?: readonly TypesMeshAsset[],
   ): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
   ensureResident(
     handle: Handle<'TextureAsset', 'shared'>,
@@ -961,6 +1144,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
     pod: TypesMeshAsset | TextureAsset,
     worldId: World | number = 0,
+    lodMeshes: readonly TypesMeshAsset[] = [],
   ): Result<TextureGpuEntry | MeshGpuHandles, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     // Hit: O(1) cache lookup, never re-projects (AC-09 -- deriveRenderData*
@@ -975,14 +1159,16 @@ 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);
+        return this.uploadMeshById(key, pod, projected.value, lodMeshes);
       }
       case 'texture': {
         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);
@@ -997,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
@@ -1491,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
@@ -1516,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,
@@ -1555,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
@@ -1574,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,
@@ -1621,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}`,
@@ -1648,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',
@@ -1660,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,
@@ -1690,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);
   }
 
@@ -1702,6 +1997,7 @@ export class GpuResidencyCache {
     id: string | number,
     mesh: TypesMeshAsset,
     renderData: MeshRenderData,
+    lodMeshes: readonly TypesMeshAsset[] = [],
   ): Result<MeshGpuHandles, RhiError> {
     const device = this.gpuDevice;
     if (device === undefined) {
@@ -1714,13 +2010,15 @@ export class GpuResidencyCache {
       );
     }
 
-    const indices = mesh.indices;
+    const packed = packMeshLodGeometry(mesh, renderData, lodMeshes);
+    if (!packed.ok) return packed;
+    const { vertices, indices, lodRanges } = packed.value;
     const indexBytesUnpadded = indices === undefined ? 0 : indices.byteLength;
-    const indexBytes = renderData.indexByteLength;
+    const indexBytes = ((indexBytesUnpadded + 3) >> 2) << 2;
 
     const vboResult = device.createBuffer({
       label: `mesh-${id}-vbo`,
-      size: renderData.vertexByteLength,
+      size: vertices.byteLength,
       usage: renderData.vertexUsage,
       mappedAtCreation: false,
     });
@@ -1740,7 +2038,7 @@ export class GpuResidencyCache {
       ibo = iboResult.value;
     }
 
-    const vboWriteResult = device.queue.writeBuffer(vbo, 0, mesh.vertices);
+    const vboWriteResult = device.queue.writeBuffer(vbo, 0, vertices);
     if (!vboWriteResult.ok) return err(vboWriteResult.error);
 
     if (indices !== undefined) {
@@ -1766,10 +2064,10 @@ export class GpuResidencyCache {
     const entry: MeshGpuHandles = {
       vertexBuffer: this.wrapBuf(vbo),
       indexBuffer: ibo === null ? null : this.wrapBuf(ibo),
-      vboBytes: renderData.vertexByteLength,
+      vboBytes: vertices.byteLength,
       iboBytes: indices === undefined ? 0 : indexBytes,
-      indexCount: renderData.indexCount,
-      indexFormat: renderData.indexFormat,
+      indexCount: mesh.indices === undefined ? 0 : mesh.indices.length,
+      indexFormat: indices instanceof Uint32Array ? 'uint32' : 'uint16',
       layout: renderData.layoutProjection.attributes.some(
         (attribute) => attribute.key === 'skinIndex' || attribute.key === 'skinWeight',
       )
@@ -1778,9 +2076,10 @@ export class GpuResidencyCache {
       layoutProjection: renderData.layoutProjection,
       uvSetCount: 1 + extraUvSets,
       vertexCount: mesh.vertices.byteLength / renderData.layoutProjection.arrayStride,
-      indexed: indices !== undefined,
+      indexed: mesh.indices !== undefined,
       topology: renderData.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: renderData.submeshes,
+      ...(lodRanges === undefined ? {} : { lodRanges }),
     };
     this.meshGpuHandles.set(id, entry);
     this.meshResidencyEpoch += 1;

package/src/device/lifecycle-transaction.ts

@@ -0,0 +1,12 @@
+export {
+  type DeviceResourceKind,
+  DeviceResourceRef,
+  DeviceScope,
+  type DeviceScopeReceipt,
+  type DeviceScopeState,
+  type LifecycleFailure,
+  type LifecycleResourceSpec,
+  type LifecycleResult,
+  LifecycleTransaction,
+  type ResourceRef,
+} from './device-scope';

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,
   });
 }