@forgeax/engine-render 0.1.4 → 0.1.6

package/src/{gpu-resource-store.ts → device/gpu-residency.ts}

@@ -1,5 +1,5 @@
-// @forgeax/engine-runtime - GpuResourceStore
-// (feat-20260601-gpu-resource-store-extraction M1; M2 added the deriveRenderData
+// @forgeax/engine-runtime - GpuResidencyCache
+// (feat-20260601-device/gpu-residency-extraction M1; M2 added the deriveRenderData
 // projection seam — see render-data.ts).
 //
 // Owns the GPU residency layer extracted from AssetRegistry: per-handle GPU
@@ -23,30 +23,42 @@
 //
 // Texture residency is SYNCHRONOUS (D-9): `uploadTexture`'s only async source
 // was the one-time per-device mipmap shader-module build, which is hoisted to
-// `prewarmMipmapPipeline` (called from `createRenderer.ready`, already async).
+// `prewarmMipmapPipeline` (called from `createRenderer.initialization`, already async).
 // After prewarm the per-texture mipmap blit is pure synchronous encoder work,
 // so the sync `draw(world)` frame contract is preserved. A format that was
 // not prewarmed surfaces a structured RhiError on the sync path -- it is never
 // lazily awaited (that would break the sync draw contract).
 
+import {
+  blitMipmapsSync,
+  getOrCreateMipmapPipeline,
+  type MipmapShaderModuleFactory,
+} from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
-import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
+import {
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  type VertexLayoutProjection,
+} from '@forgeax/engine-geometry';
 import { halfFloat } from '@forgeax/engine-math';
 import {
   type Buffer,
+  type BufferDescriptor,
   err,
   ok,
   type Result,
   type RhiCaps,
   type RhiDevice,
   RhiError,
+  type RhiQueue,
   type Sampler,
   type Texture,
+  type TextureFormat,
   type TextureView,
 } from '@forgeax/engine-rhi';
 import {
   ASSET_ERROR_HINTS,
   type AssetError,
+  countExtraUvSets,
   type DecodedImage,
   type EquirectAsset,
   type Handle,
@@ -61,37 +73,29 @@ import {
   type Submesh,
   type TextureAsset,
   type MeshAsset as TypesMeshAsset,
+  toShared,
 } from '@forgeax/engine-types';
-import { GpuBuffer, GpuTexture } from './gpu-resource';
-import { GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING } from './gpu-texture-usage';
+import { GpuBuffer, GpuTexture } from '../gpu-resource';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
   GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_UNIFORM,
   GPU_BUFFER_USAGE_VERTEX,
-} from './gpu-usage';
-import {
-  createFaceUniformsBuffer,
-  createPrefilterUniformsBuffer,
-  writeAllFaceUniforms,
-  writeAllPrefilterUniforms,
-} from './ibl/face-uniforms';
+} from '../gpu-usage';
 import {
+  CAPTURE_VIEW_PROJS,
   CUBEMAP_FACE_VERTICES,
   createIblPipelines,
+  type IblShaderModuleFactory,
+  PREFILTER_MIP_LEVELS,
+  PREFILTER_SIZE,
   runIblPrecompute,
-} from './ibl/IblPipelineCache';
-import type { RhiErrorListenerRegistry } from './lifecycle';
-import {
-  type MeshRangeInvalidReason,
-  MeshUpdateError,
-  type MeshUpdateError as MeshUpdateErrorType,
-} from './mesh-update-errors';
-import {
-  blitMipmapsSync,
-  getOrCreateMipmapPipeline,
-  type MipmapBlitDevice,
-  type MipmapShaderModuleFactory,
-} from './mipmap-generator';
+} from '../ibl/IblPipelineCache';
+import type { RhiErrorListenerRegistry } from '../lifecycle';
 import {
   type CubeRenderData,
   deriveMipUploadLayout,
@@ -100,7 +104,114 @@ import {
   deriveRenderDataTexture,
   type MeshRenderData,
   type TextureRenderData,
-} from './render-data';
+} from '../render-data';
+import type { DeviceScope } from './device-scope';
+
+const DYNAMIC_OFFSET_STRIDE = 256;
+const FACE_COUNT = 6;
+const PREFILTER_SUBPASS_COUNT = PREFILTER_MIP_LEVELS * FACE_COUNT;
+
+export type FaceUniformsDevice = Pick<RhiDevice, 'createBuffer'> & {
+  readonly queue: Pick<RhiQueue, 'writeBuffer'>;
+};
+
+function invalidUniformInput(expected: string, hint: string): Result<never, RhiError> {
+  return err(new RhiError({ code: 'webgpu-runtime-error', expected, hint }));
+}
+
+export function createFaceUniformsBuffer(device: FaceUniformsDevice): Result<Buffer, RhiError> {
+  const descriptor: BufferDescriptor = {
+    label: 'ibl-face-uniforms',
+    size: FACE_COUNT * DYNAMIC_OFFSET_STRIDE,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  };
+  return device.createBuffer(descriptor);
+}
+
+export function createPrefilterUniformsBuffer(
+  device: FaceUniformsDevice,
+): Result<Buffer, RhiError> {
+  const descriptor: BufferDescriptor = {
+    label: 'ibl-prefilter-uniforms',
+    size: PREFILTER_SUBPASS_COUNT * DYNAMIC_OFFSET_STRIDE,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  };
+  return device.createBuffer(descriptor);
+}
+
+export function writeFaceUniforms(
+  device: FaceUniformsDevice,
+  buffer: Buffer,
+  faceIdx: number,
+  viewProj: Float32Array,
+): Result<void, RhiError> {
+  if (faceIdx < 0 || faceIdx >= FACE_COUNT) {
+    return invalidUniformInput(
+      'faceIdx is an integer in the inclusive range [0, 5]',
+      `writeFaceUniforms received faceIdx=${faceIdx}`,
+    );
+  }
+  if (viewProj.length !== 16) {
+    return invalidUniformInput(
+      'viewProj contains exactly 16 floats',
+      `writeFaceUniforms received ${viewProj.length} floats`,
+    );
+  }
+  return device.queue.writeBuffer(buffer, faceIdx * DYNAMIC_OFFSET_STRIDE, viewProj);
+}
+
+export function writeAllFaceUniforms(
+  device: FaceUniformsDevice,
+  buffer: Buffer,
+): Result<void, RhiError> {
+  for (let face = 0; face < FACE_COUNT; face++) {
+    const viewProj = CAPTURE_VIEW_PROJS[face];
+    if (viewProj === undefined) continue;
+    const result = writeFaceUniforms(device, buffer, face, viewProj);
+    if (!result.ok) return result;
+  }
+  return ok(undefined);
+}
+
+export function writePrefilterUniforms(
+  device: FaceUniformsDevice,
+  buffer: Buffer,
+  subPassIdx: number,
+  roughness: number,
+  mipFaceSize: number,
+): Result<void, RhiError> {
+  if (subPassIdx < 0 || subPassIdx >= PREFILTER_SUBPASS_COUNT) {
+    return invalidUniformInput(
+      `subPassIdx is an integer in the inclusive range [0, ${PREFILTER_SUBPASS_COUNT - 1}]`,
+      `writePrefilterUniforms received subPassIdx=${subPassIdx}`,
+    );
+  }
+  const payload = new Float32Array([roughness, mipFaceSize, 0, 0]);
+  return device.queue.writeBuffer(buffer, subPassIdx * DYNAMIC_OFFSET_STRIDE, payload);
+}
+
+export function writeAllPrefilterUniforms(
+  device: FaceUniformsDevice,
+  buffer: Buffer,
+): Result<void, RhiError> {
+  for (let mip = 0; mip < PREFILTER_MIP_LEVELS; mip++) {
+    const roughness = mip / (PREFILTER_MIP_LEVELS - 1);
+    const mipFaceSize = PREFILTER_SIZE / 2 ** mip;
+    for (let face = 0; face < FACE_COUNT; face++) {
+      const result = writePrefilterUniforms(
+        device,
+        buffer,
+        mip * FACE_COUNT + face,
+        roughness,
+        mipFaceSize,
+      );
+      if (!result.ok) return result;
+    }
+  }
+  return ok(undefined);
+}
 
 // AssetError is constructed without importing the AssetRegistry's class; the
 // store builds the 4-field surface (.code / .expected / .hint / .detail)
@@ -158,28 +269,6 @@ function makeImageError<C extends ImageErrorCode>(
   return new RuntimeImageError<C>(detail);
 }
 
-// Extended device shape adding `queue.writeTexture` on top of
-// `MipmapBlitDevice` (the mipmap-generator only needs the encoder + queue
-// submit surface; uploadTexture additionally writes pixel bytes via
-// `queue.writeTexture` -- spec anchor: WebGPU 26.6.4.4).
-type MipmapBlitDeviceWithWriteTexture = MipmapBlitDevice & {
-  readonly queue: MipmapBlitDevice['queue'] & {
-    // biome-ignore lint/suspicious/noExplicitAny: shim accepts any descriptor
-    writeTexture(dst: any, data: any, layout: any, size: any): Result<void, any>;
-  };
-};
-
-// Extended device shape adding `createBuffer` + `queue.writeBuffer` on top of
-// `MipmapBlitDevice` for the user-mesh GPU upload path.
-type MipmapBlitDeviceWithBuffer = MipmapBlitDevice & {
-  // biome-ignore lint/suspicious/noExplicitAny: shim accepts any descriptor
-  createBuffer(desc: any): Result<any, any>;
-  readonly queue: MipmapBlitDevice['queue'] & {
-    // biome-ignore lint/suspicious/noExplicitAny: shim accepts any descriptor
-    writeBuffer(buffer: any, offset: number, data: any): Result<void, any>;
-  };
-};
-
 /** Cube-POD register-relay injected by the wire layer (D-3). */
 type RegisterCube = (
   world: World,
@@ -215,13 +304,11 @@ interface TextureGpuEntry {
 interface CubemapGpuEntry {
   status: 'pending' | 'ready' | 'failed';
   texture: GpuTexture | null;
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU cubemap view (not a GpuResource)
-  view: any;
-  // biome-ignore lint/suspicious/noExplicitAny: per-face 2D views (6 faces; not GpuResources)
-  faceViews: readonly any[];
+  view: TextureView | undefined;
+  faceViews: readonly TextureView[];
 }
 
-interface MeshGpuEntry {
+export interface MeshGpuHandles {
   readonly vertexBuffer: GpuBuffer;
   /**
    * Index buffer wrapper, or `null` for a vertex-only mesh
@@ -239,15 +326,31 @@ interface MeshGpuEntry {
   readonly vboBytes: number;
   /** Allocation byte size for the ibo, or 0 when indexBuffer is null. */
   readonly iboBytes: number;
-  /** Immutable geometry-owned layout projection used for all resident stride checks. */
-  readonly layoutProjection: VertexLayoutProjection;
   readonly indexCount: number;
   readonly indexFormat: 'uint16' | 'uint32';
-  /** Vertex count is derived from the geometry-owned projection stride. */
+  /**
+   * Vertex stride discriminator (feat-20260611). `'12F'` = 48 B
+   * (position+normal+uv+tangent); `'18F'` = 72 B (12F + skinIndex(uint16x4) +
+   * skinWeight(float32x4)). Mirrors `MeshRenderData.layout` in render-data.ts
+   * and `MeshRenderData.layout` -- the residency and render-data layout
+   * fields are the same union and move together.
+   */
+  readonly layout: '12F' | '18F';
+  /** Geometry-owned vertex layout projection used by every GPU consumer. */
+  readonly layoutProjection: VertexLayoutProjection;
+  /**
+   * Number of UV sets the interleaved buffer carries (1 = single `uv`, +1 per
+   * `uv1..uv7`). feat-20260629-multi-uv-set-support: threaded to the record
+   * stage so the forward PSO's vertex layout stride matches the buffer for
+   * meshes with a real extra UV set. Mirrors MeshRenderData.uvSetCount /
+   * MeshRenderData.uvSetCount.
+   */
+  readonly uvSetCount: number;
+  /** Vertex count uses 18F for skin or the geometry-owned canonical base stride. */
   readonly vertexCount: number;
   /** True when `MeshAsset.indices` is present (indexed draw path). */
   readonly indexed: boolean;
-  /** Primitive topology (default 'triangle-list'). Mirrors MeshGpuHandles. */
+  /** Primitive topology (default 'triangle-list'). */
   readonly topology: PrimitiveTopology;
   /**
    * Submeshes from MeshAsset.submeshes, carried through to the record stage
@@ -257,41 +360,22 @@ interface MeshGpuEntry {
   readonly submeshes: readonly import('@forgeax/engine-types').Submesh[];
 }
 
-function meshStrideBytes(layoutProjection: VertexLayoutProjection): number {
-  if (layoutProjection.arrayStride <= 0) {
-    throw new Error('mesh layout projection must have a positive array stride');
-  }
-  return layoutProjection.arrayStride;
-}
-
-function submeshesEqual(a: readonly Submesh[], b: readonly Submesh[]): boolean {
-  return (
-    a.length === b.length &&
-    a.every((left, index) => {
-      const right = b[index];
-      return (
-        right !== undefined &&
-        left.indexOffset === right.indexOffset &&
-        left.indexCount === right.indexCount &&
-        left.vertexCount === right.vertexCount &&
-        left.topology === right.topology &&
-        left.materialSlot === right.materialSlot
-      );
-    })
-  );
-}
-
 /**
  * GPU residency store. Owns the per-handle GPU caches and the upload
  * primitives that build them. Constructed once per renderer; wired with the
- * GPU device via `configureGpuDevice` after `Renderer.ready` resolves.
+ * GPU device via `configureGpuDevice` after `Renderer.initialization` resolves.
  */
-export class GpuResourceStore {
+export class GpuResidencyCache {
   /** Monotonic token for mesh GPU residency or contents changes. */
   meshResidencyEpoch = 0;
   /** Monotonic token for texture/sampler identities used by material bind groups. */
   materialResourceEpoch = 0;
-  private gpuDevice: MipmapBlitDevice | undefined = undefined;
+  private gpuDevice: RhiDevice | undefined = undefined;
+  /** RHI-only owner for IBL projection; never populated with a raw GPUDevice. */
+  private iblDevice: RhiDevice | undefined = undefined;
+  /** RHI Result-returning shader factory paired with `iblDevice`. */
+  private iblShaderModuleFactory: IblShaderModuleFactory | undefined = undefined;
+  private deviceScope: DeviceScope | undefined;
   // Shader-module factory injected at `configureGpuDevice`; threaded into the
   // mipmap-pipeline prewarm + the IBL precompute path. `undefined` until wired.
   private asyncCreateShaderModule: MipmapShaderModuleFactory | undefined = undefined;
@@ -305,32 +389,45 @@ export class GpuResourceStore {
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
 
-  private readonly textureGpuHandles: Map<number, TextureGpuEntry> = new Map();
-  private readonly samplerGpuHandles: Map<number, Sampler> = new Map();
+  private readonly textureGpuHandles: Map<string | number, TextureGpuEntry> = new Map();
+  private readonly samplerGpuHandles: Map<string | number, Sampler> = new Map();
   private readonly cubemapGpuHandles: Map<number, CubemapGpuEntry> = new Map();
   // Maps source EquirectAsset handle id -> minted cubemap handle so the same
   // equirect source always resolves to the same cubemap (idempotent, A2).
   private readonly cubemapIdempotentMap: Map<number, Handle<'EquirectAsset', 'shared'>> = new Map();
-  private readonly meshGpuHandles: Map<number, MeshGpuEntry> = new Map();
+  private readonly meshGpuHandles: Map<string | number, MeshGpuHandles> = new Map();
 
   /**
-   * feat-20260723-cross-world-gpu-cache-collision: compose a cache key from
-   * the raw handle slot and the worldId so two worlds that independently
-   * allocate assets at the same slot number never collide in the GPU store.
-   * worldId=0 produces the bare slot (backward compat with single-world path).
+   * Compose a cache key from the raw handle slot and its owning World. The
+   * draw-time world index is only a position in one frame's `worlds[]`; it is
+   * not an asset identity and can be reused by a later World. World objects
+   * therefore receive a renderer-local namespace, while numeric callers keep
+   * the legacy namespace for low-level tests and built-in upload paths.
    */
-  private worldKey(slot: number, worldId: number): number {
-    return worldId === 0 ? slot : worldId * 0x1000000 + slot;
+  private readonly worldNamespaces = new WeakMap<World, number>();
+  private nextWorldNamespace = 1;
+
+  private worldKey(slot: number, world: World | number): string | number {
+    if (typeof world === 'number') {
+      return world === 0 ? slot : world * 0x1000000 + slot;
+    }
+    let namespace = this.worldNamespaces.get(world);
+    if (namespace === undefined) {
+      namespace = this.nextWorldNamespace;
+      this.nextWorldNamespace += 1;
+      this.worldNamespaces.set(world, namespace);
+    }
+    return `world:${namespace}:${slot}`;
   }
 
   /**
    * Wire the GPU device, shader-module factory, and cube-POD register relay.
-   * Called once by createRenderer after `Renderer.ready` resolves. This
-   * performs NO replay of CPU asset state:
+   * Called once by createRenderer after `Renderer.initialization` resolves. Unlike the
+   * pre-extraction AssetRegistry.configureGpuDevice, this performs NO replay:
    * the pull model builds resources lazily at first `ensureResident` access.
    */
   configureGpuDevice(
-    device: MipmapBlitDevice,
+    device: RhiDevice,
     asyncCreateShaderModule: MipmapShaderModuleFactory | undefined,
     registerCube: RegisterCube,
     caps: RhiCaps,
@@ -342,6 +439,25 @@ export class GpuResourceStore {
     this.caps = caps;
   }
 
+  /**
+   * Bind the IBL projection to the same opaque RhiDevice used by assembly.
+   * This is deliberately separate from the legacy-compatible mipmap fixture
+   * seam: unit fixtures that only exercise ordinary residency do not need an
+   * IBL device, while a real IBL projection never accepts a raw GPUDevice.
+   */
+  configureIblDevice(
+    device: RhiDevice,
+    shaderModuleFactory: IblShaderModuleFactory | undefined,
+  ): void {
+    this.iblDevice = device;
+    this.iblShaderModuleFactory = shaderModuleFactory;
+  }
+
+  /** Bind residency ownership to the renderer's single DeviceScope tree. */
+  bindDeviceScope(scope: DeviceScope): void {
+    this.deviceScope = scope;
+  }
+
   /**
    * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
    * reference to the device so `.destroy()` forwards to
@@ -353,19 +469,28 @@ export class GpuResourceStore {
    * surfaces as a non-null assertion rather than a structured error.
    */
   private wrapBuf(rawHandle: Buffer): GpuBuffer {
-    const device = this.gpuDevice as MipmapBlitDevice & RhiDevice;
-    return new GpuBuffer(device, rawHandle);
-  }
-
-  private destroyMeshBuffer(buffer: GpuBuffer): void {
-    const result = buffer.destroy();
-    if (!result.ok) this.errorRegistry?.fire(result.error);
+    const device = this.gpuDevice;
+    if (device === undefined) {
+      throw new Error('GpuResidencyCache.wrapBuf called before configureGpuDevice');
+    }
+    const resource = new GpuBuffer(device, rawHandle);
+    this.deviceScope?._adopt('buffer', resource, (value: GpuBuffer) => {
+      if (!value.isDestroyed) value.destroy();
+    });
+    return resource;
   }
 
   /** Wrap a raw RHI Texture handle into a GpuTexture (mirror of wrapBuf). */
   private wrapTex(rawHandle: Texture): GpuTexture {
-    const device = this.gpuDevice as MipmapBlitDevice & RhiDevice;
-    return new GpuTexture(device, rawHandle);
+    const device = this.gpuDevice;
+    if (device === undefined) {
+      throw new Error('GpuResidencyCache.wrapTex called before configureGpuDevice');
+    }
+    const resource = new GpuTexture(device, rawHandle);
+    this.deviceScope?._adopt('texture', resource, (value: GpuTexture) => {
+      if (!value.isDestroyed) value.destroy();
+    });
+    return resource;
   }
 
   /**
@@ -386,16 +511,17 @@ export class GpuResourceStore {
    */
   destroyAll(): void {
     if (this.meshGpuHandles.size > 0) this.meshResidencyEpoch += 1;
+    const scopeOwnsResources = this.deviceScope !== undefined;
     // The cubemap path registers two entries (sourceId + cubeId) sharing one
     // GpuTexture wrapper, so destroyAll must dedupe on the wrapper identity
     // before forwarding `.destroy()` -- otherwise the second call surfaces
     // `'destroy-after-destroy'` from the RHI shim. The `isDestroyed` getter
     // on the wrapper is the dedupe gate (architecture-principles §6).
     const destroyTex = (gpuTex: GpuTexture): void => {
-      if (!gpuTex.isDestroyed) gpuTex.destroy();
+      if (!scopeOwnsResources && !gpuTex.isDestroyed) gpuTex.destroy();
     };
     const destroyBuf = (gpuBuf: GpuBuffer): void => {
-      if (!gpuBuf.isDestroyed) gpuBuf.destroy();
+      if (!scopeOwnsResources && !gpuBuf.isDestroyed) gpuBuf.destroy();
     };
 
     for (const entry of this.textureGpuHandles.values()) {
@@ -439,7 +565,7 @@ export class GpuResourceStore {
    */
   evictTexture(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): { freed: number; errors: RhiError[] } {
     const id = this.worldKey(handleSlot(handle), worldId);
     const entry = this.textureGpuHandles.get(id);
@@ -465,7 +591,7 @@ export class GpuResourceStore {
 
   evictMesh(
     handle: Handle<'MeshAsset', 'shared'>,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): { freed: number; errors: RhiError[] } {
     const id = this.worldKey(handleSlot(handle), worldId);
     const entry = this.meshGpuHandles.get(id);
@@ -533,9 +659,15 @@ export class GpuResourceStore {
     const errors: RhiError[] = [];
     let meshResidencyChanged = false;
     let materialResidencyChanged = false;
+    const liveSlots = new Set([...liveSet].map((slot) => String(slot)));
+    const isLiveKey = (key: string | number): boolean => {
+      const slot =
+        typeof key === 'number' ? String(key % 0x1000000) : key.slice(key.lastIndexOf(':') + 1);
+      return liveSlots.has(slot);
+    };
 
     for (const key of this.textureGpuHandles.keys()) {
-      if (!liveSet.has(key)) {
+      if (!isLiveKey(key)) {
         const entry = this.textureGpuHandles.get(key);
         if (entry !== undefined) {
           if (!entry.texture.isDestroyed) {
@@ -554,14 +686,14 @@ export class GpuResourceStore {
     }
 
     for (const key of this.samplerGpuHandles.keys()) {
-      if (!liveSet.has(key)) {
+      if (!isLiveKey(key)) {
         this.samplerGpuHandles.delete(key);
         materialResidencyChanged = true;
       }
     }
 
     for (const key of this.cubemapGpuHandles.keys()) {
-      if (!liveSet.has(key)) {
+      if (!liveSlots.has(String(key))) {
         const entry = this.cubemapGpuHandles.get(key);
         if (entry !== undefined) {
           // A 'failed' entry holds no GPU texture (texture:null) — nothing to free.
@@ -580,7 +712,7 @@ export class GpuResourceStore {
     }
 
     for (const key of this.meshGpuHandles.keys()) {
-      if (!liveSet.has(key)) {
+      if (!isLiveKey(key)) {
         const entry = this.meshGpuHandles.get(key);
         if (entry !== undefined) {
           if (!entry.vertexBuffer.isDestroyed) {
@@ -615,7 +747,7 @@ export class GpuResourceStore {
 
   /**
    * Prewarm the mipmap pipeline cache for the given texture formats (D-9).
-   * Called from `createRenderer.ready` (already async): builds the one-time
+   * Called from `createRenderer.initialization` (already async): builds the one-time
    * mipmap shader module + per-format render pipeline into the mipmap-generator
    * deviceCache so the per-texture mipmap blit at record-stage `ensureResident`
    * is pure synchronous encoder work. A format absent from this list will make
@@ -623,8 +755,8 @@ export class GpuResourceStore {
    * than lazily await a build (which would break the sync draw contract).
    */
   async prewarmMipmapPipeline(
-    device: MipmapBlitDevice,
-    formats: readonly GPUTextureFormat[],
+    device: RhiDevice,
+    formats: readonly TextureFormat[],
   ): Promise<Result<void, RhiError>> {
     const factory = this.asyncCreateShaderModule;
     if (factory === undefined) {
@@ -660,7 +792,7 @@ export class GpuResourceStore {
    */
   _getTextureGpuTexture(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): GpuTexture | undefined {
     return this.textureGpuHandles.get(this.worldKey(handleSlot(handle), worldId))?.texture;
   }
@@ -671,7 +803,7 @@ export class GpuResourceStore {
    */
   getTextureGpuView(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): TextureView | undefined {
     return this.textureGpuHandles.get(this.worldKey(handleSlot(handle), worldId))?.view;
   }
@@ -684,12 +816,12 @@ export class GpuResourceStore {
   ensureSamplerResident(
     handle: Handle<'SamplerAsset', 'shared'>,
     pod: SamplerAsset,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): Result<Sampler, RhiError> {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
     if (existing !== undefined) return ok(existing);
-    const device = this.gpuDevice as (MipmapBlitDevice & RhiDevice) | undefined;
+    const device = this.gpuDevice;
     if (device === undefined) {
       return err(
         new RhiError({
@@ -719,14 +851,14 @@ export class GpuResourceStore {
   }
 
   /** Return the full-cube texture view, or `undefined` if not uploaded yet. */
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture view
-  getCubemapGpuView(handle: Handle<'EquirectAsset', 'shared'>): any | undefined {
+  getCubemapGpuView(handle: Handle<'EquirectAsset', 'shared'>): TextureView | undefined {
     return this.cubemapGpuHandles.get(handleSlot(handle))?.view;
   }
 
   /** Return per-face 2D views (6 faces), or `undefined` if not uploaded yet. */
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture views
-  getCubemapFaceViews(handle: Handle<'EquirectAsset', 'shared'>): readonly any[] | undefined {
+  getCubemapFaceViews(
+    handle: Handle<'EquirectAsset', 'shared'>,
+  ): readonly TextureView[] | undefined {
     return this.cubemapGpuHandles.get(handleSlot(handle))?.faceViews;
   }
 
@@ -753,11 +885,30 @@ export class GpuResourceStore {
    */
   getMeshGpuHandles(
     handle: Handle<'MeshAsset', 'shared'>,
-    worldId: number = 0,
-  ): MeshGpuEntry | undefined {
+    worldId: World | number = 0,
+  ): MeshGpuHandles | undefined {
     return this.meshGpuHandles.get(this.worldKey(handleSlot(handle), worldId));
   }
 
+  /**
+   * Drop one mutable shared mesh's GPU copy after ECS publishes `markChanged`.
+   * The next record pass resolves the same POD and rebuilds residency through
+   * the normal pull path, so ECS remains the payload authority.
+   */
+  invalidateMesh(handle: number, worldId: World | number = 0): void {
+    // SharedRefMutation publishes the encoded handle value, while the cache
+    // key is derived from the decoded slot. Keep the invalidation path aligned
+    // with getMeshGpuHandles/ensureResident so an in-place ECS payload change
+    // cannot leave the old VBO resident.
+    const key = this.worldKey(handleSlot(toShared<'MeshAsset'>(handle)), worldId);
+    const entry = this.meshGpuHandles.get(key);
+    if (entry === undefined) return;
+    entry.vertexBuffer.destroy();
+    if (entry.indexBuffer !== null) entry.indexBuffer.destroy();
+    this.meshGpuHandles.delete(key);
+    this.meshResidencyEpoch += 1;
+  }
+
   /**
    * Pull-model residency: build the GPU resource for `handle` from the
    * caller-provided POD on a miss, return the cached handles on a hit (D-2).
@@ -772,12 +923,21 @@ export class GpuResourceStore {
    * (`_uploadCubemapFromEquirect`). Builtin meshes are NOT routed here either
    * (createRenderer step-3 owns them; D-1).
    */
+  ensureResident(
+    handle: Handle<'MeshAsset', 'shared'>,
+    pod: TypesMeshAsset,
+    worldId?: World | number,
+  ): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
+  ensureResident(
+    handle: Handle<'TextureAsset', 'shared'>,
+    pod: TextureAsset,
+    worldId?: World | number,
+  ): Result<TextureGpuEntry, RhiError | AssetError | ImageError>;
   ensureResident(
     handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
     pod: TypesMeshAsset | TextureAsset,
-    worldId: number = 0,
-    // biome-ignore lint/suspicious/noExplicitAny: opaque GPU handle entry union
-  ): Result<any, RhiError | AssetError | ImageError> {
+    worldId: World | number = 0,
+  ): Result<TextureGpuEntry | MeshGpuHandles, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     // Hit: O(1) cache lookup, never re-projects (AC-09 -- deriveRenderData*
     // runs only on a miss). The miss arms below dispatch on `pod.kind` with NO
@@ -825,7 +985,7 @@ export class GpuResourceStore {
     handle: Handle<'TextureAsset', 'shared'>,
     pod: TextureAsset,
     decoded: DecodedImage,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): Promise<Result<void, AssetError | ImageError | RhiError>> {
     const device = this.gpuDevice;
     const projected = deriveRenderDataTexture(pod);
@@ -844,7 +1004,7 @@ export class GpuResourceStore {
           new RhiError({
             code: 'rhi-not-available',
             expected: 'asyncCreateShaderModule wired by configureGpuDevice',
-            hint: 'GpuResourceStore.uploadTexture mipmap branch needs a shader-module factory; rhi-webgpu / rhi-wgpu shims expose it via pack.createShaderModule. Explicit-rhi instances must surface the factory on the RhiInstance.',
+            hint: 'GpuResidencyCache.uploadTexture mipmap branch needs a shader-module factory; rhi-webgpu / rhi-wgpu shims expose it via pack.createShaderModule. Explicit-rhi instances must surface the factory on the RhiInstance.',
           }),
         );
       }
@@ -854,7 +1014,7 @@ export class GpuResourceStore {
           new RhiError({
             code: 'rhi-not-available',
             expected: `mipmap pipeline for format ${tex.format} builds`,
-            hint: 'GpuResourceStore.uploadTexture could not build the mipmap pipeline',
+            hint: 'GpuResidencyCache.uploadTexture could not build the mipmap pipeline',
           }),
         );
       }
@@ -900,7 +1060,7 @@ export class GpuResourceStore {
     pod: TextureAsset,
     decoded: DecodedImage,
     renderData: TextureRenderData,
-    worldId: number = 0,
+    worldId: World | number = 0,
   ): Result<TextureGpuEntry, AssetError | ImageError | RhiError> {
     const device = this.gpuDevice;
     const prepared = this.prepareTextureUpload(handle, pod, decoded, renderData);
@@ -909,7 +1069,7 @@ export class GpuResourceStore {
       return err(
         new RhiError({
           code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before ensureResident',
+          expected: 'GpuResidencyCache.configureGpuDevice wired before ensureResident',
           hint: 'a texture ensureResident ran before the GPU device was wired; call gpuStore.configureGpuDevice in createRenderer',
         }),
       );
@@ -957,8 +1117,7 @@ export class GpuResourceStore {
     decoded: DecodedImage,
     renderData: TextureRenderData,
   ): Result<
-    // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture handle
-    { id: number; tex: TextureAsset; levels: number; gpuTexture: any | undefined },
+    { id: number; tex: TextureAsset; levels: number; gpuTexture: Texture | undefined },
     AssetError | ImageError | RhiError
   > {
     const id = handleSlot(handle);
@@ -996,9 +1155,7 @@ export class GpuResourceStore {
     // upload before allocating a handle; binding a texture that the backend
     // accepted syntactically but cannot use later surfaces only as a generic
     // invalid-bind-group submit error.
-    const maxDimension =
-      (device as unknown as { readonly limits?: { readonly maxTextureDimension2D?: number } })
-        .limits?.maxTextureDimension2D ?? 16_384;
+    const maxDimension = device.limits.maxTextureDimension2D;
     if (tex.width > maxDimension || tex.height > maxDimension) {
       return err(
         makeImageError({
@@ -1022,10 +1179,11 @@ export class GpuResourceStore {
       format: renderData.format,
       usage: renderData.usage,
       viewFormats: [],
+      textureBindingViewDimension: undefined,
     });
     if (!createTexRes.ok) return createTexRes;
     const gpuTexture = createTexRes.value;
-    const queue = (device as unknown as MipmapBlitDeviceWithWriteTexture).queue;
+    const queue = device.queue;
 
     if (renderData.compressed) {
       // feat-20260707 M5 / w36 (AC-08): block-compressed textures carry their
@@ -1137,7 +1295,7 @@ export class GpuResourceStore {
       return recordFailed(
         makeAssetError({
           code: 'asset-not-found',
-          expected: 'GpuResourceStore.configureGpuDevice wired with registerCube',
+          expected: 'GpuResidencyCache.configureGpuDevice wired with registerCube',
           hint: 'call gpuStore.configureGpuDevice(device, factory, registerCube) before _uploadCubemapFromEquirect',
         }),
       );
@@ -1162,7 +1320,7 @@ export class GpuResourceStore {
     // guard above. The entry holds no live GPU resources yet (record binds the
     // white fallback while pending); the texture/views are filled in below when
     // the projection completes (status flips to 'ready'), or replaced by a
-    // 'failed' entry via recordFailed if any later step errors.
+    // 'failed' entry via recordFailed if a later step errors.
     this.cubemapGpuHandles.set(sourceId, {
       status: 'pending',
       texture: null,
@@ -1231,45 +1389,28 @@ export class GpuResourceStore {
     // the cubemap and all three IBL side textures by IblPipelineCache.
     const outputFormat = this.caps?.rgba16floatRenderable === false ? 'rgba8unorm' : tex.format;
 
-    // Lazy projection runs from the record arm, where the device is always
-    // wired (research R-5). The device-not-wired queue + placeholder cube path
-    // is removed (D-7); a missing device here is a fail-fast, not a queue.
-    const device = this.gpuDevice;
-    if (device === undefined) {
+    // 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
+    // ordinary mipmap fixture seam: it accepts only the opaque RhiDevice and
+    // its Result-returning shader factory, never a raw GPUDevice or unwrap
+    // fallback.
+    const device = this.iblDevice;
+    const shaderModuleFactory = this.iblShaderModuleFactory;
+    const scope = this.deviceScope;
+    if (device === undefined || shaderModuleFactory === undefined || scope === undefined) {
       return recordFailed(
         new RhiError({
           code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before cubemap projection',
-          hint: 'a cubemap projection ran before the GPU device was wired; the record arm projects only after the device is configured',
+          expected:
+            'GpuResidencyCache is configured with an RhiDevice, shader factory, and DeviceScope',
+          hint: 'bind the renderer DeviceScope before a cubemap projection; raw GPU fallback is not supported',
         }),
       );
     }
 
     // Usage flags for the small equirect helper texture (sampled source for the
     // IBL precompute pass); the cube texture's usage comes from the projection.
-    // biome-ignore lint/suspicious/noExplicitAny: union of shim/raw return shapes
-    const unwrap = (r: any): any => {
-      if (r === null || r === undefined) return undefined;
-      if (typeof r === 'object' && 'ok' in r) return r.ok ? r.value : undefined;
-      return r;
-    };
-    // biome-ignore lint/suspicious/noExplicitAny: shim/raw device split
-    const makeTextureView = (dev: any, texture: any, desc: any): any => {
-      if (typeof dev.createTextureView === 'function') {
-        const u = unwrap(dev.createTextureView(texture, desc));
-        if (u !== undefined) return u;
-      }
-      if (texture !== null && texture !== undefined && typeof texture.createView === 'function') {
-        try {
-          return texture.createView(desc);
-        } catch {
-          return undefined;
-        }
-      }
-      return undefined;
-    };
-
-    const gpuTextureRet = device.createTexture({
+    const gpuTextureResult = device.createTexture({
       label: `cubemap-${sourceId}`,
       size: { width: cubeFaceSize, height: cubeFaceSize, depthOrArrayLayers: 6 },
       mipLevelCount: 1,
@@ -1278,52 +1419,29 @@ export class GpuResourceStore {
       format: outputFormat,
       usage: projected.cubeUsage,
       viewFormats: [],
+      textureBindingViewDimension: undefined,
     });
-    const gpuTexture = unwrap(gpuTextureRet);
-    if (gpuTexture === undefined) {
-      return recordFailed(
-        makeAssetError({
-          code: 'ibl-precompute-not-dispatched',
-          expected: `device.createTexture cubemap-${sourceId} to return a valid texture`,
-          hint: ASSET_ERROR_HINTS['ibl-precompute-not-dispatched'],
-        }),
-      );
-    }
+    if (!gpuTextureResult.ok) return recordFailed(gpuTextureResult.error);
+    const gpuTexture = gpuTextureResult.value;
 
-    const cubeView = makeTextureView(device, gpuTexture, {
+    const cubeViewResult = device.createTextureView(gpuTexture, {
       label: `cubemap-view-${sourceId}`,
       dimension: 'cube',
       arrayLayerCount: 6,
     });
-    if (cubeView === undefined) {
-      return recordFailed(
-        makeAssetError({
-          code: 'ibl-precompute-not-dispatched',
-          expected: `device.createTextureView cubemap-view-${sourceId} to return a valid view`,
-          hint: ASSET_ERROR_HINTS['ibl-precompute-not-dispatched'],
-        }),
-      );
-    }
+    if (!cubeViewResult.ok) return recordFailed(cubeViewResult.error);
+    const cubeView = cubeViewResult.value;
 
-    // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture views
-    const faceViews: any[] = [];
+    const faceViews: TextureView[] = [];
     for (let face = 0; face < 6; face++) {
-      const fv = makeTextureView(device, gpuTexture, {
+      const faceViewResult = device.createTextureView(gpuTexture, {
         label: `cubemap-face-${sourceId}-${face}`,
         dimension: '2d',
         baseArrayLayer: face,
         arrayLayerCount: 1,
       });
-      if (fv === undefined) {
-        return recordFailed(
-          makeAssetError({
-            code: 'ibl-precompute-not-dispatched',
-            expected: `device.createTextureView cubemap-face-${sourceId}-${face} to return a valid view`,
-            hint: ASSET_ERROR_HINTS['ibl-precompute-not-dispatched'],
-          }),
-        );
-      }
-      faceViews.push(fv);
+      if (!faceViewResult.ok) return recordFailed(faceViewResult.error);
+      faceViews.push(faceViewResult.value);
     }
 
     // M-3 / w11: a single GpuTexture wrapper is shared between sourceId
@@ -1367,89 +1485,95 @@ export class GpuResourceStore {
 
     this.cubemapIdempotentMap.set(sourceId, cubeHandle);
 
-    if (this.asyncCreateShaderModule !== undefined) {
-      // biome-ignore lint/suspicious/noExplicitAny: device shim narrowed at runtime
-      const ipDevice = device as any;
-      const pipelinesRes = await createIblPipelines(
-        ipDevice,
-        // biome-ignore lint/suspicious/noExplicitAny: factory signatures are interoperable; device shim is structural
-        this.asyncCreateShaderModule as any,
-        outputFormat,
+    const pipelinesResult = await createIblPipelines(
+      scope,
+      device,
+      shaderModuleFactory,
+      outputFormat,
+    );
+    if (!pipelinesResult.ok) {
+      return recordFailed(
+        makeAssetError({
+          code: 'ibl-precompute-not-dispatched',
+          expected: pipelinesResult.error.expected,
+          hint: pipelinesResult.error.hint,
+        }),
+      );
+    }
+
+    const equirectTextureResult = device.createTexture({
+      label: `equirect-${sourceId}`,
+      size: { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      mipLevelCount: 1,
+      sampleCount: 1,
+      dimension: '2d',
+      format: tex.format,
+      usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST,
+      viewFormats: [],
+      textureBindingViewDimension: undefined,
+    });
+    if (!equirectTextureResult.ok) return recordFailed(equirectTextureResult.error);
+    const equirectGpuTex = equirectTextureResult.value;
+
+    const equirectViewResult = device.createTextureView(equirectGpuTex, {
+      label: `equirect-view-${sourceId}`,
+      dimension: '2d',
+    });
+    if (!equirectViewResult.ok) return recordFailed(equirectViewResult.error);
+    const equirectView = equirectViewResult.value;
+
+    const bytesPerPixel = tex.format === 'rgba32float' ? 16 : tex.format === 'rgba16float' ? 8 : 4;
+    const equirectWriteResult = device.queue.writeTexture(
+      { texture: equirectGpuTex },
+      tex.data,
+      { bytesPerRow: tex.width * bytesPerPixel, rowsPerImage: tex.height },
+      { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+    );
+    if (!equirectWriteResult.ok) return recordFailed(equirectWriteResult.error);
+
+    const faceBufferResult = createFaceUniformsBuffer(device);
+    if (!faceBufferResult.ok) return recordFailed(faceBufferResult.error);
+    const faceBuf = faceBufferResult.value;
+    const prefilterBufferResult = createPrefilterUniformsBuffer(device);
+    if (!prefilterBufferResult.ok) return recordFailed(prefilterBufferResult.error);
+    const prefBuf = prefilterBufferResult.value;
+
+    const cubeVertexResult = device.createBuffer({
+      label: 'ibl-cube-verts',
+      size: CUBEMAP_FACE_VERTICES.byteLength,
+      usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!cubeVertexResult.ok) return recordFailed(cubeVertexResult.error);
+    const cubeVertex = cubeVertexResult.value;
+
+    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);
+    if (!prefilterUniformsResult.ok) return recordFailed(prefilterUniformsResult.error);
+
+    const runResult = runIblPrecompute({
+      scope,
+      device,
+      equirectGpuTex,
+      equirectView,
+      cubeGpuTex: gpuTexture,
+      cubeView,
+      cubeFaceViews: faceViews,
+      faceUniformsBuffer: faceBuf,
+      prefilterUniformsBuffer: prefBuf,
+      cubeVertexBuffer: cubeVertex,
+    });
+    if (!runResult.ok) {
+      return recordFailed(
+        makeAssetError({
+          code: 'ibl-precompute-not-dispatched',
+          expected: runResult.error.expected,
+          hint: runResult.error.hint,
+        }),
       );
-      if (pipelinesRes.ok) {
-        // biome-ignore lint/suspicious/noExplicitAny: device shim
-        const fdevice = device as any;
-        const equirectGpuTexRet = fdevice.createTexture({
-          label: `equirect-${sourceId}`,
-          size: { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
-          mipLevelCount: 1,
-          sampleCount: 1,
-          dimension: '2d',
-          format: tex.format,
-          usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST,
-          viewFormats: [],
-        });
-        const equirectGpuTex = unwrap(equirectGpuTexRet);
-        if (equirectGpuTex !== undefined && typeof fdevice.queue?.writeTexture === 'function') {
-          const bytesPerPixel =
-            tex.format === 'rgba32float' ? 16 : tex.format === 'rgba16float' ? 8 : 4;
-          fdevice.queue.writeTexture(
-            { texture: equirectGpuTex },
-            tex.data,
-            { bytesPerRow: tex.width * bytesPerPixel, rowsPerImage: tex.height },
-            { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
-          );
-        }
-        const equirectView =
-          equirectGpuTex !== undefined
-            ? makeTextureView(fdevice, equirectGpuTex, {
-                label: `equirect-view-${sourceId}`,
-                dimension: '2d',
-              })
-            : undefined;
-        const faceBuf = unwrap(createFaceUniformsBuffer(ipDevice));
-        const prefBuf = unwrap(createPrefilterUniformsBuffer(ipDevice));
-        const cubeVertex = unwrap(
-          fdevice.createBuffer({
-            label: 'ibl-cube-verts',
-            size: CUBEMAP_FACE_VERTICES.byteLength,
-            usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
-            mappedAtCreation: false,
-          }),
-        );
-        if (
-          equirectGpuTex !== undefined &&
-          equirectView !== undefined &&
-          faceBuf !== undefined &&
-          prefBuf !== undefined &&
-          cubeVertex !== undefined &&
-          typeof fdevice.queue?.writeBuffer === 'function'
-        ) {
-          fdevice.queue.writeBuffer(cubeVertex, 0, CUBEMAP_FACE_VERTICES);
-          writeAllFaceUniforms(ipDevice, faceBuf);
-          writeAllPrefilterUniforms(ipDevice, prefBuf);
-          const runRes = runIblPrecompute({
-            device: ipDevice,
-            equirectGpuTex,
-            equirectView,
-            cubeGpuTex: gpuTexture,
-            cubeView,
-            cubeFaceViews: faceViews,
-            faceUniformsBuffer: faceBuf,
-            prefilterUniformsBuffer: prefBuf,
-            cubeVertexBuffer: cubeVertex,
-          });
-          if (!runRes.ok) {
-            return recordFailed(
-              makeAssetError({
-                code: 'ibl-precompute-not-dispatched',
-                expected: runRes.error.expected,
-                hint: runRes.error.hint,
-              }),
-            );
-          }
-        }
-      }
     }
 
     return ok(cubeHandle);
@@ -1461,116 +1585,88 @@ export class GpuResourceStore {
    * `uploadMeshById` byte-for-byte. Returns the cached entry on success.
    */
   private uploadMeshById(
-    id: number,
+    id: string | number,
     mesh: TypesMeshAsset,
     renderData: MeshRenderData,
-  ): Result<MeshGpuEntry, RhiError> {
-    const device = this.gpuDevice as MipmapBlitDeviceWithBuffer | undefined;
+  ): Result<MeshGpuHandles, RhiError> {
+    const device = this.gpuDevice;
     if (device === undefined) {
       return err(
         new RhiError({
           code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before mesh ensureResident',
+          expected: 'GpuResidencyCache.configureGpuDevice wired before mesh ensureResident',
           hint: 'a mesh ensureResident ran before the GPU device was wired; call gpuStore.configureGpuDevice in createRenderer',
         }),
       );
     }
 
-    // biome-ignore lint/suspicious/noExplicitAny: union of shim/raw return shapes
-    const unwrapBuffer = (r: any): any => {
-      if (r === null || r === undefined) return undefined;
-      if (typeof r === 'object' && 'ok' in r) return r.ok ? r.value : undefined;
-      return r;
-    };
-    // biome-ignore lint/suspicious/noExplicitAny: union of shim/raw write return
-    const writeOk = (r: any): boolean => {
-      if (r === undefined) return true;
-      if (typeof r === 'object' && 'ok' in r) return r.ok === true;
-      return true;
-    };
-
     const indices = mesh.indices;
     const indexBytesUnpadded = indices === undefined ? 0 : indices.byteLength;
     const indexBytes = renderData.indexByteLength;
 
-    const vboRet = device.createBuffer({
+    const vboResult = device.createBuffer({
       label: `mesh-${id}-vbo`,
       size: renderData.vertexByteLength,
       usage: renderData.vertexUsage,
       mappedAtCreation: false,
     });
-    const vbo = unwrapBuffer(vboRet);
-    if (vbo === undefined) {
-      return err(
-        new RhiError({
-          code: 'webgpu-runtime-error',
-          expected: `device.createBuffer mesh-${id}-vbo to return a valid buffer`,
-          hint: 'mesh vertex buffer allocation returned undefined',
-        }),
-      );
-    }
+    if (!vboResult.ok) return vboResult;
+    const vbo = vboResult.value;
     // Vertex-only mesh: skip the index buffer entirely. The indexed path below
     // is unchanged byte-for-byte when `indices` is present.
-    let ibo: unknown = null;
+    let ibo: Buffer | null = null;
     if (indices !== undefined) {
-      const iboRet = device.createBuffer({
+      const iboResult = device.createBuffer({
         label: `mesh-${id}-ibo`,
         size: indexBytes,
         usage: renderData.indexUsage,
         mappedAtCreation: false,
       });
-      ibo = unwrapBuffer(iboRet);
-      if (ibo === undefined) {
-        return err(
-          new RhiError({
-            code: 'webgpu-runtime-error',
-            expected: `device.createBuffer mesh-${id}-ibo to return a valid buffer`,
-            hint: 'mesh index buffer allocation returned undefined',
-          }),
-        );
-      }
+      if (!iboResult.ok) return iboResult;
+      ibo = iboResult.value;
     }
 
-    const vboWriteRet = device.queue.writeBuffer(vbo, 0, mesh.vertices);
-    if (!writeOk(vboWriteRet)) {
-      return err(
-        new RhiError({
-          code: 'webgpu-runtime-error',
-          expected: `queue.writeBuffer mesh-${id}-vbo to succeed`,
-          hint: 'mesh vertex buffer write failed',
-        }),
-      );
-    }
+    const vboWriteResult = device.queue.writeBuffer(vbo, 0, mesh.vertices);
+    if (!vboWriteResult.ok) return err(vboWriteResult.error);
 
     if (indices !== undefined) {
       const indexSrc = new Uint8Array(indexBytes);
       indexSrc.set(new Uint8Array(indices.buffer, indices.byteOffset, indexBytesUnpadded));
-      const iboWriteRet = device.queue.writeBuffer(ibo, 0, indexSrc);
-      if (!writeOk(iboWriteRet)) {
+      if (ibo === null)
         return err(
           new RhiError({
             code: 'webgpu-runtime-error',
-            expected: `queue.writeBuffer mesh-${id}-ibo to succeed`,
-            hint: 'mesh index buffer write failed',
+            expected: `mesh-${id} index buffer to be allocated before its upload`,
+            hint: 'the indexed mesh upload lost its RHI index-buffer owner',
           }),
         );
-      }
+      const iboWriteResult = device.queue.writeBuffer(ibo, 0, indexSrc);
+      if (!iboWriteResult.ok) return err(iboWriteResult.error);
     }
 
-    const layoutProjection = renderData.layoutProjection;
-    const strideBytes = meshStrideBytes(layoutProjection);
-    const entry: MeshGpuEntry = {
-      vertexBuffer: this.wrapBuf(vbo as Buffer),
-      indexBuffer: ibo === null ? null : this.wrapBuf(ibo as Buffer),
+    // The geometry projection already contains every packed attribute,
+    // including skin and additional UV sets. Dividing by a second
+    // attribute-derived count would double-count those fields and produce a
+    // fractional vertex count for otherwise valid meshes.
+    const extraUvSets = countExtraUvSets(mesh.attributes);
+    const entry: MeshGpuHandles = {
+      vertexBuffer: this.wrapBuf(vbo),
+      indexBuffer: ibo === null ? null : this.wrapBuf(ibo),
       vboBytes: renderData.vertexByteLength,
       iboBytes: indices === undefined ? 0 : indexBytes,
       indexCount: renderData.indexCount,
       indexFormat: renderData.indexFormat,
-      vertexCount: mesh.vertices.byteLength / strideBytes,
+      layout: renderData.layoutProjection.attributes.some(
+        (attribute) => attribute.key === 'skinIndex' || attribute.key === 'skinWeight',
+      )
+        ? '18F'
+        : '12F',
+      layoutProjection: renderData.layoutProjection,
+      uvSetCount: 1 + extraUvSets,
+      vertexCount: mesh.vertices.byteLength / renderData.layoutProjection.arrayStride,
       indexed: indices !== undefined,
       topology: renderData.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: renderData.submeshes,
-      layoutProjection,
     };
     this.meshGpuHandles.set(id, entry);
     this.meshResidencyEpoch += 1;
@@ -1578,220 +1674,114 @@ export class GpuResourceStore {
   }
 
   /**
-   * Update an existing resident mesh without changing its shape or metadata.
-   * A shape change must use a new asset handle; this method never reallocates
-   * or silently changes the draw contract.
+   * Update an existing mesh's GPU buffer data in-place (or expand). The handle
+   * must already be resident. Mirrors the pre-extraction `updateMeshById`.
    */
   private updateMeshById(
-    id: number,
+    id: string | number,
     newVertices: Float32Array,
-    newIndices: Uint16Array | Uint32Array | undefined,
+    newIndices: Uint16Array,
     submeshes?: readonly Submesh[],
-  ): Result<void, MeshUpdateErrorType | RhiError> {
-    const device = this.gpuDevice as MipmapBlitDeviceWithBuffer | undefined;
-    if (device === undefined) {
-      return err(
-        new RhiError({
-          code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before mesh update',
-          hint: 'configure the renderer GPU device before updating a mesh',
-        }),
-      );
-    }
+  ): void {
+    const device = this.gpuDevice;
+    if (device === undefined) return;
     const entry = this.meshGpuHandles.get(id);
-    if (entry === undefined) {
-      return err(
-        new MeshUpdateError({
-          code: 'mesh-not-resident',
-          detail: { handle: id },
-        }),
-      );
-    }
+    if (entry === undefined) return;
 
-    const strideBytes = meshStrideBytes(entry.layoutProjection);
-    const expectedVertexBytes = entry.vertexCount * strideBytes;
-    const shapeMismatch = (expected: string, actual: string) =>
-      err(
-        new MeshUpdateError({
-          code: 'mesh-shape-mismatch',
-          detail: { handle: id, expected, actual },
-        }),
-      );
+    const newVertexBytes = newVertices.byteLength;
+    const indexBytesUnpadded = newIndices.byteLength;
+    const newIndexBytes = ((indexBytesUnpadded + 3) >> 2) << 2;
+
+    // M-3 / w11: read allocation bytes from the entry's vboBytes / iboBytes
+    // (tracked at upload time) instead of reaching into the opaque RHI Buffer
+    // for a `.size` property -- the RHI Buffer interface is spec-aligned and
+    // does NOT expose `.size`; allocation bytes remain derived cache facts.
+    const existingIbo = entry.indexBuffer;
+    const nextSubmeshes = submeshes ?? entry.submeshes;
     if (
-      newVertices.byteLength !== expectedVertexBytes ||
-      newVertices.byteLength % strideBytes !== 0
+      existingIbo !== null &&
+      newVertexBytes <= entry.vboBytes &&
+      newIndexBytes <= entry.iboBytes
     ) {
-      return shapeMismatch(
-        `${expectedVertexBytes} vertex bytes at ${strideBytes}-byte stride`,
-        `${newVertices.byteLength} vertex bytes`,
-      );
-    }
+      const vboWriteRet = device.queue.writeBuffer(entry.vertexBuffer.handle, 0, newVertices);
+      if (!vboWriteRet.ok) return;
 
-    if (entry.indexed !== (newIndices !== undefined)) {
-      return shapeMismatch(
-        entry.indexed ? 'indexed mesh data' : 'vertex-only mesh data',
-        newIndices === undefined ? 'vertex-only mesh data' : 'indexed mesh data',
-      );
-    }
-    if (newIndices !== undefined) {
-      const indexFormat = newIndices instanceof Uint32Array ? 'uint32' : 'uint16';
-      const indexBytes = ((newIndices.byteLength + 3) >> 2) << 2;
-      if (
-        entry.indexBuffer === null ||
-        indexFormat !== entry.indexFormat ||
-        newIndices.length !== entry.indexCount ||
-        indexBytes !== entry.iboBytes
-      ) {
-        return shapeMismatch(
-          `${entry.indexFormat} index format with ${entry.indexCount} indices`,
-          `${indexFormat} index format with ${newIndices.length} indices`,
-        );
-      }
-    } else if (entry.indexBuffer !== null) {
-      return shapeMismatch('indexed mesh data', 'vertex-only mesh data');
+      const indexSrc = new Uint8Array(newIndexBytes);
+      indexSrc.set(new Uint8Array(newIndices.buffer, newIndices.byteOffset, indexBytesUnpadded));
+      const iboWriteRet = device.queue.writeBuffer(existingIbo.handle, 0, indexSrc);
+      if (!iboWriteRet.ok) return;
+
+      this.meshGpuHandles.set(id, {
+        vertexBuffer: entry.vertexBuffer,
+        indexBuffer: existingIbo,
+        vboBytes: entry.vboBytes,
+        iboBytes: entry.iboBytes,
+        indexCount: newIndices.length,
+        indexFormat: 'uint16',
+        layout: '12F',
+        layoutProjection: entry.layoutProjection,
+        uvSetCount: entry.uvSetCount,
+        vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+        indexed: true,
+        topology: entry.topology,
+        submeshes: nextSubmeshes,
+      });
+      this.meshResidencyEpoch += 1;
+      return;
     }
 
-    const nextSubmeshes = submeshes ?? entry.submeshes;
-    if (!submeshesEqual(entry.submeshes, nextSubmeshes)) {
-      return shapeMismatch('unchanged submesh descriptors', 'different submesh descriptors');
-    }
+    const vboResult = device.createBuffer({
+      label: `mesh-${id}-vbo`,
+      size: newVertexBytes,
+      usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!vboResult.ok) return;
+    const vbo = vboResult.value;
+    const iboResult = device.createBuffer({
+      label: `mesh-${id}-ibo`,
+      size: newIndexBytes,
+      usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!iboResult.ok) return;
+    const ibo = iboResult.value;
 
-    const vertexWrite = device.queue.writeBuffer(entry.vertexBuffer.handle, 0, newVertices);
-    if (!vertexWrite.ok) return err(vertexWrite.error);
-    if (newIndices !== undefined && entry.indexBuffer !== null) {
-      const indexSrc = new Uint8Array(entry.iboBytes);
-      indexSrc.set(new Uint8Array(newIndices.buffer, newIndices.byteOffset, newIndices.byteLength));
-      const indexWrite = device.queue.writeBuffer(entry.indexBuffer.handle, 0, indexSrc);
-      if (!indexWrite.ok) return err(indexWrite.error);
-    }
-    this.meshResidencyEpoch += 1;
-    return ok(undefined);
-  }
+    const vboWriteResult = device.queue.writeBuffer(vbo, 0, newVertices);
+    if (!vboWriteResult.ok) return;
 
-  /**
-   * Internal explicit rebuild path used when an owner has deliberately
-   * replaced a mesh shape. Public callers should register a new MeshAsset
-   * handle so CPU recovery data and GPU residency remain one authority.
-   */
-  private replaceMeshById(
-    id: number,
-    newVertices: Float32Array,
-    newIndices: Uint16Array | Uint32Array | undefined,
-    submeshes?: readonly Submesh[],
-  ): Result<void, MeshUpdateErrorType | RhiError> {
-    const device = this.gpuDevice as MipmapBlitDeviceWithBuffer | undefined;
-    const entry = this.meshGpuHandles.get(id);
-    if (device === undefined) {
-      return err(
-        new RhiError({
-          code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before mesh replacement',
-          hint: 'configure the renderer GPU device before replacing a mesh',
-        }),
-      );
-    }
-    if (entry === undefined) {
-      return err(new MeshUpdateError({ code: 'mesh-not-resident', detail: { handle: id } }));
-    }
-    const strideBytes = meshStrideBytes(entry.layoutProjection);
-    if (newVertices.byteLength === 0 || newVertices.byteLength % strideBytes !== 0) {
-      return err(
-        new MeshUpdateError({
-          code: 'mesh-shape-mismatch',
-          detail: {
-            handle: id,
-            expected: `vertex bytes divisible by ${strideBytes}`,
-            actual: `${newVertices.byteLength} vertex bytes`,
-          },
-        }),
-      );
-    }
-    const newVertexBytes = newVertices.byteLength;
-    const newIndexBytes = newIndices === undefined ? 0 : ((newIndices.byteLength + 3) >> 2) << 2;
-    const unwrapBuffer = (r: unknown): unknown => {
-      if (r === null || r === undefined) return undefined;
-      if (typeof r === 'object' && 'ok' in r) {
-        return (r as { ok: boolean; value?: unknown }).ok
-          ? (r as unknown as { value: unknown }).value
-          : undefined;
-      }
-      return r;
-    };
-    const vbo = unwrapBuffer(
-      device.createBuffer({
-        label: `mesh-${id}-vbo`,
-        size: newVertexBytes,
-        usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
-        mappedAtCreation: false,
-      }),
-    );
-    if (vbo === undefined) {
-      return err(
-        new RhiError({
-          code: 'webgpu-runtime-error',
-          expected: `device.createBuffer mesh-${id}-vbo to return a valid buffer`,
-          hint: 'mesh replacement vertex buffer allocation failed',
-        }),
-      );
-    }
-    const ibo =
-      newIndices === undefined
-        ? null
-        : unwrapBuffer(
-            device.createBuffer({
-              label: `mesh-${id}-ibo`,
-              size: newIndexBytes,
-              usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
-              mappedAtCreation: false,
-            }),
-          );
-    if (newIndices !== undefined && ibo === undefined) {
-      this.destroyMeshBuffer(this.wrapBuf(vbo as Buffer));
-      return err(
-        new RhiError({
-          code: 'webgpu-runtime-error',
-          expected: `device.createBuffer mesh-${id}-ibo to return a valid buffer`,
-          hint: 'mesh replacement index buffer allocation failed',
-        }),
-      );
-    }
-    const vertexBuffer = this.wrapBuf(vbo as Buffer);
-    const indexBuffer = ibo === null ? null : this.wrapBuf(ibo as Buffer);
-    const vertexWrite = device.queue.writeBuffer(vertexBuffer.handle, 0, newVertices);
-    if (!vertexWrite.ok) {
-      this.destroyMeshBuffer(vertexBuffer);
-      if (indexBuffer !== null) this.destroyMeshBuffer(indexBuffer);
-      return err(vertexWrite.error);
-    }
-    if (newIndices !== undefined && indexBuffer !== null) {
-      const indexSrc = new Uint8Array(newIndexBytes);
-      indexSrc.set(new Uint8Array(newIndices.buffer, newIndices.byteOffset, newIndices.byteLength));
-      const indexWrite = device.queue.writeBuffer(indexBuffer.handle, 0, indexSrc);
-      if (!indexWrite.ok) {
-        this.destroyMeshBuffer(vertexBuffer);
-        this.destroyMeshBuffer(indexBuffer);
-        return err(indexWrite.error);
-      }
-    }
-    const nextSubmeshes = submeshes ?? entry.submeshes;
-    const nextEntry: MeshGpuEntry = {
-      vertexBuffer,
-      indexBuffer,
+    const indexSrc = new Uint8Array(newIndexBytes);
+    indexSrc.set(new Uint8Array(newIndices.buffer, newIndices.byteOffset, indexBytesUnpadded));
+    const iboWriteResult = device.queue.writeBuffer(ibo, 0, indexSrc);
+    if (!iboWriteResult.ok) return;
+
+    this.meshGpuHandles.set(id, {
+      vertexBuffer: this.wrapBuf(vbo),
+      indexBuffer: this.wrapBuf(ibo),
       vboBytes: newVertexBytes,
       iboBytes: newIndexBytes,
-      indexCount: newIndices?.length ?? 0,
-      indexFormat: newIndices instanceof Uint32Array ? 'uint32' : 'uint16',
+      indexCount: newIndices.length,
+      indexFormat: 'uint16',
+      layout: '12F',
       layoutProjection: entry.layoutProjection,
-      vertexCount: newVertexBytes / strideBytes,
-      indexed: newIndices !== undefined,
-      topology: nextSubmeshes[0]?.topology ?? entry.topology,
+      uvSetCount: entry.uvSetCount,
+      vertexCount: newVertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+      indexed: true,
+      topology: entry.topology,
       submeshes: nextSubmeshes,
-    };
-    this.meshGpuHandles.set(id, nextEntry);
+    });
     this.meshResidencyEpoch += 1;
-    this.destroyMeshBuffer(entry.vertexBuffer);
-    if (entry.indexBuffer !== null) this.destroyMeshBuffer(entry.indexBuffer);
-    return ok(undefined);
+
+    // M-3 / w11: release the replaced buffers through their structured
+    // GpuBuffer owner rather than reaching into opaque handles with a
+    // backend-specific property.
+    // `GpuBuffer.destroy()` routes through
+    // `device.destroyBuffer(handle)` (RHI shim is the lifecycle SSOT;
+    // architecture-principles §1 / charter §F1). Errors are swallowed here:
+    // updateMeshById is the in-place reallocation path; the structured fail
+    // surfaces on subsequent buffer use rather than blocking the resize.
+    entry.vertexBuffer.destroy();
+    if (existingIbo !== null) existingIbo.destroy();
   }
 
   /**
@@ -1801,101 +1791,12 @@ export class GpuResourceStore {
   updateMesh(
     handle: Handle<'MeshAsset', 'shared'>,
     newVertices: Float32Array,
-    newIndices: Uint16Array | Uint32Array | undefined,
-    worldId: number = 0,
+    newIndices: Uint16Array,
+    worldId: World | number = 0,
     submeshes?: readonly Submesh[],
-  ): Result<void, MeshUpdateErrorType | RhiError> {
-    const id = this.worldKey(handleSlot(handle), worldId);
-    return this.updateMeshById(id, newVertices, newIndices, submeshes);
-  }
-
-  /** Explicit internal rebuild path; public callers should use a new asset handle. */
-  replaceMesh(
-    handle: Handle<'MeshAsset', 'shared'>,
-    newVertices: Float32Array,
-    newIndices: Uint16Array | Uint32Array | undefined,
-    worldId: number = 0,
-    submeshes?: readonly Submesh[],
-  ): Result<void, MeshUpdateErrorType | RhiError> {
-    const id = this.worldKey(handleSlot(handle), worldId);
-    return this.replaceMeshById(id, newVertices, newIndices, submeshes);
-  }
-
-  /** Upload a contiguous vertex range using the resident mesh stride. */
-  updateMeshVertexRange(
-    handle: Handle<'MeshAsset', 'shared'>,
-    vertices: Float32Array,
-    firstVertex: number,
-    vertexCount: number,
-    worldId: number = 0,
-  ): Result<void, MeshUpdateErrorType | RhiError> {
+  ): void {
     const id = this.worldKey(handleSlot(handle), worldId);
-    const device = this.gpuDevice as MipmapBlitDeviceWithBuffer | undefined;
-    if (device === undefined) {
-      return err(
-        new RhiError({
-          code: 'rhi-not-available',
-          expected: 'GpuResourceStore.configureGpuDevice wired before mesh range update',
-          hint: 'configure the renderer GPU device before updating a mesh range',
-        }),
-      );
-    }
-    const entry = this.meshGpuHandles.get(id);
-    if (entry === undefined) {
-      return err(new MeshUpdateError({ code: 'mesh-not-resident', detail: { handle: id } }));
-    }
-    const strideBytes = meshStrideBytes(entry.layoutProjection);
-    const invalidLocation = (
-      reason: Exclude<MeshRangeInvalidReason, 'stride-mismatch'>,
-    ): Result<void, MeshUpdateErrorType | RhiError> =>
-      err(
-        new MeshUpdateError({
-          code: 'mesh-range-invalid',
-          detail: {
-            handle: id,
-            firstVertex,
-            vertexCount,
-            residentVertexCount: entry.vertexCount,
-            reason,
-          },
-        }),
-      );
-    const invalidStride = (
-      expectedByteLength: number,
-      actualByteLength: number,
-    ): Result<void, MeshUpdateErrorType | RhiError> =>
-      err(
-        new MeshUpdateError({
-          code: 'mesh-range-invalid',
-          detail: {
-            handle: id,
-            firstVertex,
-            vertexCount,
-            residentVertexCount: entry.vertexCount,
-            reason: 'stride-mismatch',
-            expectedByteLength,
-            actualByteLength,
-          },
-        }),
-      );
-    if (!Number.isInteger(firstVertex) || !Number.isInteger(vertexCount)) {
-      return invalidLocation('non-integer');
-    }
-    if (firstVertex < 0 || vertexCount < 0) return invalidLocation('negative');
-    if (vertexCount === 0) return invalidLocation('empty');
-    if (firstVertex + vertexCount > entry.vertexCount) return invalidLocation('out-of-bounds');
-    const expectedByteLength = vertexCount * strideBytes;
-    if (vertices.byteLength !== expectedByteLength) {
-      return invalidStride(expectedByteLength, vertices.byteLength);
-    }
-    const result = device.queue.writeBuffer(
-      entry.vertexBuffer.handle,
-      firstVertex * strideBytes,
-      vertices,
-    );
-    if (!result.ok) return err(result.error);
-    this.meshResidencyEpoch += 1;
-    return ok(undefined);
+    this.updateMeshById(id, newVertices, newIndices, submeshes);
   }
 }