@forgeax/engine-render 0.1.23 → 0.1.25

package/src/record/main-pass-geometry.ts

@@ -10,7 +10,7 @@ import {
   RhiError,
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
-import type { PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+import type { ParamSchemaEntry, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
@@ -19,11 +19,20 @@ import {
 } from '../gpu-usage';
 import { createHdrpSkinUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import {
+  type InstanceCollectionFailureCode,
+  recordInstanceFailure,
+  recordInstanceResidency,
+} from '../instances';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   createPbrSkinMeshBindGroupEntries,
+  isCanonicalStandardPbrMaterialShader,
   isStandardPbrMaterialShader,
+  isStandardPbrSkinMaterialShader,
+  materialBindGroupLayoutIdentity,
   pbrSkinMeshDynamicOffsets,
+  physicalTextureFields,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
 import {
@@ -35,13 +44,17 @@ import {
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
-import type { MaterialSnapshot } from '../render-system-extract';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import {
   PROBE_BLEND_RECORD_BYTE_SIZE,
   PROBE_BLEND_RECORD_STRIDE,
   probeBlendRecordOffset,
 } from '../scene/probe-blend-record';
-import { worldEntityKey } from './frame-snapshot';
+import {
+  getOpaqueResourceIdentity,
+  instanceCollectionCacheKey,
+  worldEntityKey,
+} from './frame-snapshot';
 import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
@@ -50,6 +63,7 @@ import {
 } from './main-pass-material';
 import {
   getOrCreateFromChain,
+  INSTANCE_STORAGE_STRIDE_FLOATS,
   INSTANCE_UBO_FULL_ARRAY_BYTES,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
@@ -69,12 +83,36 @@ type GeometryInstanceDraw = {
   readonly instanceCount: number;
 };
 
+type InstanceUploadResult =
+  | {
+      readonly ok: true;
+      readonly ranges: readonly { readonly start: number; readonly end: number }[];
+      readonly bytes: number;
+    }
+  | {
+      readonly ok: false;
+      readonly ranges: readonly { readonly start: number; readonly end: number }[];
+      readonly bytes: number;
+    };
+
 type GeometryBindingState = {
   pipeline: RenderPipeline | null;
   instancesBuffer: Buffer | null;
   probeOffset: number;
 };
 
+function materialDiagnosticsEnabled(): boolean {
+  if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
+    return false;
+  }
+  const processValue = (
+    globalThis as {
+      readonly process?: { readonly env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return processValue?.env?.FORGEAX_MATERIAL_DIAGNOSTICS === '1';
+}
+
 type MaterialPipelineLookup = {
   readonly materialShaderId: string;
   readonly isHdrTarget: boolean;
@@ -94,6 +132,121 @@ type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection
 
 type GeometryRenderState = ReturnType<typeof geometryRenderStateForTopology>;
 
+/**
+ * Select the transmission shader axis from authored material data, not the
+ * canonical boot schema.  The latter reserves transmission fields for the
+ * shared Standard ABI even when a material remains base-only.
+ */
+export function requestsStandardTransmissionVariant(
+  material: Pick<MaterialSnapshot, 'materialShaderId' | 'paramSnapshot'>,
+): boolean {
+  return (
+    material.materialShaderId === 'forgeax::default-standard-pbr' &&
+    material.paramSnapshot?.transmission !== undefined
+  );
+}
+
+function recordIblPipelineBinding(
+  c: _InternalRenderPipelineContext,
+  material: MaterialSnapshot,
+  pipeline: RenderPipeline,
+  materialGroup: BindGroup,
+): void {
+  const receipt = c.frameState.iblBindingInspection;
+  if (receipt === undefined || !isStandardPbrMaterialShader(material.materialShaderId)) return;
+  const materialBgl =
+    c.runtime.getMaterialBindGroupLayout?.(
+      material.materialShaderId ?? 'forgeax::default-standard-pbr',
+    ) ?? c.pipelineState.materialBindGroupLayout;
+  c.frameState.iblBindingInspection = {
+    ...receipt,
+    pipeline: {
+      pipelineIdentity: getOpaqueResourceIdentity(pipeline as object),
+      effectiveMaterialLayoutIdentity: effectiveMaterialLayoutIdentity(
+        material.materialShaderId ?? 'forgeax::default-standard-pbr',
+        material.materialParamSchema,
+      ),
+      materialBglIdentity: getOpaqueResourceIdentity(materialBgl as object),
+      bindGroupIdentity: getOpaqueResourceIdentity(materialGroup as object),
+      drawFrameId: c.frameState.frameNumber,
+    },
+  };
+  const materialReceipt = c.frameState.iblBindingInspection.material;
+  const errors: string[] = [];
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.materialBglIdentity !== getOpaqueResourceIdentity(materialBgl as object)
+  ) {
+    errors.push('material-pipeline-bgl-identity-mismatch');
+  }
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.bindGroupIdentity !== getOpaqueResourceIdentity(materialGroup as object)
+  ) {
+    errors.push('material-bind-group-identity-mismatch');
+  }
+  if (materialReceipt !== undefined) {
+    const expectedResourceIdentities = [
+      receipt.resources.irradiance.viewIdentity,
+      receipt.resources.irradiance.samplerIdentity,
+      receipt.resources.prefilter.viewIdentity,
+      receipt.resources.prefilter.samplerIdentity,
+      receipt.resources.brdfLut.viewIdentity,
+      receipt.resources.brdfLut.samplerIdentity,
+      receipt.resources.intensityBufferIdentity,
+    ];
+    const actualResourceIdentities = materialReceipt.entries
+      .filter((entry) => entry.binding >= materialReceipt.skylightBindingStart)
+      .slice(0, expectedResourceIdentities.length)
+      .map((entry) => entry.resourceIdentity);
+    if (
+      actualResourceIdentities.length !== expectedResourceIdentities.length ||
+      actualResourceIdentities.some(
+        (identity, index) => identity !== expectedResourceIdentities[index],
+      )
+    ) {
+      errors.push('material-ibl-resource-identity-mismatch');
+    }
+  }
+  c.frameState.iblBindingInspection = {
+    ...c.frameState.iblBindingInspection,
+    status: errors.length === 0 ? 'binding-chain-consistent' : 'binding-chain-mismatch',
+    errors,
+  };
+}
+
+const SHARED_BOOT_MATERIAL_SHADER_IDS = new Set([
+  'forgeax::default-unlit',
+  'forgeax::default-shadow-caster',
+  'forgeax::sprite',
+  'forgeax::sprite-lit',
+  'forgeax::default-sprite',
+  'forgeax::msdf-text',
+  'forgeax::default-standard-pbr',
+  'forgeax::pbr-skin',
+  'forgeax::default-standard-pbr-skin',
+]);
+
+/**
+ * Returns the layout identity that can distinguish a material PSO in the
+ * record cache. Shared boot shaders keep the boot layout identity even when a
+ * manifest exposes a schema; Standard PBR only opts into a schema-derived
+ * identity when authored clearcoat texture bindings extend that layout.
+ */
+export function effectiveMaterialLayoutIdentity(
+  materialShaderId: string,
+  materialParamSchema?: readonly ParamSchemaEntry[],
+): string | undefined {
+  if (materialParamSchema === undefined) return undefined;
+  const hasStandardPhysicalMaps =
+    isStandardPbrMaterialShader(materialShaderId) &&
+    physicalTextureFields(materialParamSchema).length > 0;
+  if (SHARED_BOOT_MATERIAL_SHADER_IDS.has(materialShaderId) && !hasStandardPhysicalMaps) {
+    return undefined;
+  }
+  return materialBindGroupLayoutIdentity(materialShaderId, materialParamSchema);
+}
+
 /**
  * Resolve the depth contract for a geometry pass without changing the base
  * material state. Temporal scene-data shares the main pass depth attachment:
@@ -228,6 +381,7 @@ export function recordGeometryDraws(
     viewBindGroup,
     viewBindGroupDynamicOffset = 0,
   } = c;
+  const diagnosticsEnabled = materialDiagnosticsEnabled();
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
   // The prepared Standard topology is the frame authority. A bind-group
   // identity is only a resource result; using it to infer the shader lane
@@ -587,7 +741,22 @@ export function recordGeometryDraws(
     // and walks 0, 1536, 3072, ... on the storage path.
     const skinAllocator = pipelineState.skinPaletteAllocator;
     const skinSlice = entry.source.skin;
-    const clusteredSkin = clusteredLighting;
+    // Authored Standard skin aliases deliberately publish the physical root
+    // with only their STORAGE_BUFFER capability axis. Their composed WGSL is
+    // the direct-lighting/palette (`skin`) ABI, even when the frame's
+    // canonical Standard lane uses clustered lighting. Only the canonical
+    // engine skin artifact can consume the HDRP unified skin group(2) layout;
+    // selecting it from the frame topology alone would bind
+    // `hdrp-skin-unified-bg-group2` to a three-entry URP skin PSO.
+    const clusteredSkin =
+      clusteredLighting &&
+      entry.source.materials.every((material) => {
+        const shaderId = material.materialShaderId;
+        return (
+          !isStandardPbrSkinMaterialShader(shaderId) ||
+          isCanonicalStandardPbrMaterialShader(shaderId)
+        );
+      });
     const skinMeshBindGroupLayout = clusteredSkin
       ? pipelineState.hdrpSkinMeshBindGroupLayout
       : pipelineState.pbrSkinMeshBindGroupLayout;
@@ -734,6 +903,19 @@ export function recordGeometryDraws(
       // the async PSO compile resolves the cache hits and the next frame
       // routes the skin BG + skin pipeline together. Mirrors the uniform
       // null skip-draw shape (M6-T1, charter P3 explicit failure).
+      if (diagnosticsEnabled) {
+        console.error(
+          `[render-material] skin draw skipped: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: entry.source.material.materialHandle,
+            reason: 'skin-pipeline-unavailable',
+            skinResourcesReady: skinResources !== null,
+            skinPsoReady: skinPsoProbe !== null,
+            paletteBufferReady: skinSlice?.buffer !== undefined,
+            paletteByteOffset: skinSlice?.byteOffset,
+          })}`,
+        );
+      }
       continue;
     }
     // feat-20260520-2d-sprite-layer-mvp M-3 / w25 (@fallback sprite
@@ -828,6 +1010,26 @@ export function recordGeometryDraws(
       // injection, and Skylight merge; deduped cross-entity via the
       // shaderId-outer `materialBgShared` cache.
       const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
+      const processValue = (
+        globalThis as {
+          process?: { env?: Record<string, string | undefined> };
+        }
+      ).process;
+      if (
+        processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
+        (submeshMaterial.materialShaderId === 'forgeax::default-standard-pbr' ||
+          submeshMaterial.materialShaderId === 'forgeax::pbr-skin')
+      ) {
+        console.error(
+          `[render-material] draw receipt: ${JSON.stringify({
+            entityIndex: entry.renderableIndex,
+            materialSlot,
+            materialHandle: submeshMaterial.materialHandle,
+            clearcoat: submeshMaterial.paramSnapshot?.clearcoat,
+            shader: submeshMaterial.materialShaderId,
+          })}`,
+        );
+      }
       perSubmeshBg =
         profilePhase === undefined
           ? resolveMaterialBindGroup(
@@ -849,7 +1051,9 @@ export function recordGeometryDraws(
       const smTopology = sm.topology;
       const smMaterialShaderId =
         entry.source.skin !== undefined
-          ? SKIN_MATERIAL_SHADER_ID
+          ? isStandardPbrSkinMaterialShader(submeshMaterial.materialShaderId)
+            ? submeshMaterial.materialShaderId
+            : SKIN_MATERIAL_SHADER_ID
           : submeshMaterial.materialShaderId;
       const probeBlendAvailable =
         probeBlendRecordAvailable && isStandardPbrMaterialShader(smMaterialShaderId);
@@ -930,6 +1134,11 @@ export function recordGeometryDraws(
           hasVertexColor,
           probeBlendAvailable,
         );
+        const transmissionAvailable = requestsStandardTransmissionVariant(submeshMaterial);
+        const materialCapabilityVariantSet =
+          transmissionAvailable && !capabilityVariantSet.includes('TRANSMISSION_AVAILABLE=')
+            ? `${capabilityVariantSet === '' ? '' : `${capabilityVariantSet}+`}TRANSMISSION_AVAILABLE=true`
+            : capabilityVariantSet;
         // Sprite's base request must retain the boot-selected artifact. Only
         // SpriteInstances uses the explicit empty key for the
         // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
@@ -940,7 +1149,7 @@ export function recordGeometryDraws(
             ? ''
             : undefined
           : entry.variantSet === undefined
-            ? capabilityVariantSet
+            ? materialCapabilityVariantSet
             : capabilityVariantSet === ''
               ? entry.variantSet
               : `${capabilityVariantSet}+${entry.variantSet}`;
@@ -973,6 +1182,16 @@ export function recordGeometryDraws(
       }
 
       if (smPipelineHandle === null) {
+        if (diagnosticsEnabled) {
+          console.error(
+            `[render-material] draw skipped: ${JSON.stringify({
+              entityKey: entry.source.entityKey,
+              materialHandle: submeshMaterial.materialHandle,
+              shader: smMaterialShaderId,
+              reason: 'pipeline-unavailable',
+            })}`,
+          );
+        }
         continue;
       }
       // The probe record is an ABI extension of the built-in Standard PBR
@@ -1003,6 +1222,31 @@ export function recordGeometryDraws(
         if (selectedGroup === null) continue;
         group2BindGroup = selectedGroup;
       }
+      if (diagnosticsEnabled && submeshMaterial.textureHandles !== undefined) {
+        console.error(
+          `[render-material] draw submitted: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: submeshMaterial.materialHandle,
+            shader: smMaterialShaderId,
+            textureHandles: [...submeshMaterial.textureHandles.entries()].map(
+              ([field, handle]) => ({
+                field,
+                handle,
+              }),
+            ),
+            skin: isSkinEntry
+              ? {
+                  resourcesReady: skinResources !== null,
+                  psoReady: skinPsoProbe !== null,
+                  paletteBufferReady: skinSlice?.buffer !== undefined,
+                  paletteByteOffset: skinSlice?.byteOffset,
+                  dynamicOffsets: [...group2DynamicOffsets],
+                }
+              : undefined,
+            pipelineReady: true,
+          })}`,
+        );
+      }
       pass.setBindGroup(2, group2BindGroup, group2DynamicOffsets);
 
       if (profilePhase === undefined) {
@@ -1034,6 +1278,9 @@ export function recordGeometryDraws(
           ),
         );
       }
+      if (diagnosticsEnabled && perSubmeshBg !== null) {
+        recordIblPipelineBinding(c, submeshMaterial, smPipelineHandle, perSubmeshBg);
+      }
     }
   }
 }
@@ -1043,8 +1290,285 @@ export function recordGeometryDraws(
  *
  * @internal
  */
-function resolveGeometryInstanceBuffer(
-  c: _InternalRenderPipelineContext,
+function uploadInstanceRanges(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  buffer: Buffer,
+  ranges: readonly { readonly start: number; readonly end: number }[],
+  storageBacked: boolean,
+  sourceOffsetInstances = 0,
+): InstanceUploadResult {
+  const strideBytes =
+    (storageBacked ? INSTANCE_STORAGE_STRIDE_FLOATS : 16) * Float32Array.BYTES_PER_ELEMENT;
+  const uploadedRanges: { start: number; end: number }[] = [];
+  let uploadedBytes = 0;
+  for (const range of ranges) {
+    const start = Math.max(0, Math.min(inst.instanceCount, range.start));
+    const end = Math.max(start, Math.min(inst.instanceCount, range.end));
+    if (end <= start) continue;
+    const source = inst.transforms.subarray(
+      (sourceOffsetInstances + start) * 16,
+      (sourceOffsetInstances + end) * 16,
+    );
+    const payload = storageBacked ? packInstanceStorageBuffer(source) : source;
+    const written = c.runtime.device.queue.writeBuffer(buffer, start * strideBytes, payload);
+    if (!written.ok) {
+      c.runtime.errorRegistry.fire(written.error);
+      return { ok: false, ranges: uploadedRanges, bytes: uploadedBytes };
+    }
+    uploadedRanges.push({ start, end });
+    uploadedBytes += payload.byteLength;
+  }
+  return { ok: true, ranges: uploadedRanges, bytes: uploadedBytes };
+}
+
+export function reportInstanceResidency(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  input: {
+    readonly lane: 'direct-storage' | 'chunked-storage' | 'direct-uniform' | 'chunked-uniform';
+    readonly requestedBytes: number;
+    readonly supportedBytes: number | undefined;
+    readonly uploadRanges: readonly { readonly start: number; readonly end: number }[];
+    readonly uploadedBytes: number;
+  },
+): void {
+  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
+  recordInstanceResidency(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    frameNumber: c.frameState.frameNumber,
+    residentGeneration: c.runtime.deviceScope.generation,
+    lane: input.lane,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    uploadRanges: input.uploadRanges,
+    uploadedBytes: input.uploadedBytes,
+    backend: c.runtime.device.caps.backendKind,
+  });
+}
+
+function reportInstanceFailure(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  error: {
+    readonly code: InstanceCollectionFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+  },
+  requestedBytes: number,
+  supportedBytes: number | undefined,
+): void {
+  if (inst.collectionId === undefined || c.frameState.instanceResidency === undefined) return;
+  recordInstanceFailure(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    code: error.code,
+    expected: error.expected,
+    hint: error.hint,
+    facts: {
+      requestedBytes,
+      supportedBytes,
+      backend: c.runtime.device.caps.backendKind,
+      owner: 'renderer.instances',
+      cause: error.code,
+      recovery: error.hint,
+    },
+  });
+}
+
+function clearInstanceChunksForOwner(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  ownerKey: number,
+): void {
+  const chunks = c.frameState.instanceBufferChunks;
+  if (chunks === undefined) return;
+  const prefix = `${ownerKey}:`;
+  for (const [key, entry] of chunks.entries()) {
+    if (!key.startsWith(prefix)) continue;
+    if (!entry.buffer.isDestroyed) {
+      const destroyed = entry.buffer.destroy();
+      if (!destroyed.ok) c.runtime.errorRegistry.fire(destroyed.error);
+    }
+    chunks.delete(key);
+  }
+}
+
+export function resolveStorageInstanceChunks(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
+  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
+  inst: NonNullable<RenderableSnapshot['instances']>,
+  cap: number,
+  probeBuffer: Buffer | undefined,
+  probeOffset: number,
+): readonly GeometryInstanceDraw[] | null {
+  const { runtime, frameState } = c;
+  const strideBytes = INSTANCE_STORAGE_STRIDE_FLOATS * Float32Array.BYTES_PER_ELEMENT;
+  const chunkCapacity = Math.floor(cap / strideBytes);
+  if (chunkCapacity < 1) {
+    reportInstanceFailure(
+      c,
+      inst,
+      {
+        code: 'limit-exceeded',
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: 'use a backend with storage-buffer bindings large enough for one InstanceData record',
+      },
+      inst.instanceCount * strideBytes,
+      cap,
+    );
+    runtime.errorRegistry.fire(
+      new RhiError({
+        code: 'limit-exceeded',
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: 'use a backend with storage-buffer bindings large enough for one InstanceData record',
+        detail: { maxStorageBufferBindingSize: cap, requestedBytes: strideBytes },
+      }),
+    );
+    return null;
+  }
+  const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const chunks = frameState.instanceBufferChunks;
+  const activeKeys = new Set<string>();
+  const draws: GeometryInstanceDraw[] = [];
+  const uploadedRanges: { start: number; end: number }[] = [];
+  let uploadedBytes = 0;
+  for (let start = 0; start < inst.instanceCount; start += chunkCapacity) {
+    const end = Math.min(inst.instanceCount, start + chunkCapacity);
+    const count = end - start;
+    const chunkKey = `${ownerKey}:${start}`;
+    activeKeys.add(chunkKey);
+    // Keep stable-resident checks arithmetic-only; packing is deferred to the
+    // upload path below, where a new or dirty range actually needs payload.
+    const payloadBytes = count * strideBytes;
+    const previous = chunks?.get(chunkKey);
+    let active =
+      previous !== undefined &&
+      previous.uploadedArchVersion === inst.archVersion &&
+      previous.uploadedByteLength === payloadBytes
+        ? previous
+        : undefined;
+    let activeIsNew = false;
+    if (active === undefined) {
+      const created = runtime.device.createBuffer({
+        size: payloadBytes,
+        usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+        mappedAtCreation: false,
+      });
+      if (!created.ok) {
+        runtime.errorRegistry.fire(created.error);
+        reportInstanceFailure(c, inst, created.error, inst.instanceCount * strideBytes, cap);
+        return null;
+      }
+      if (previous !== undefined && !previous.buffer.isDestroyed) {
+        const destroyed = previous.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      active = {
+        buffer: new GpuBuffer(runtime.device, created.value),
+        uploadedArchVersion: inst.archVersion,
+        uploadedByteLength: payloadBytes,
+      };
+      activeIsNew = true;
+      chunks?.set(chunkKey, active);
+      if (chunks === undefined) frameState.transientInstanceBuffers.push(active);
+    }
+    if (active === undefined) return null;
+    const needsUpload =
+      activeIsNew || active.uploadedRevision !== (inst.revision ?? inst.archVersion);
+    const rangesToUpload = [
+      {
+        start: 0,
+        end: count,
+      },
+    ];
+    if (needsUpload && rangesToUpload.length > 0) {
+      const upload = uploadInstanceRanges(
+        c,
+        inst,
+        active.buffer.handle,
+        rangesToUpload,
+        true,
+        start,
+      );
+      for (const range of upload.ranges) {
+        uploadedRanges.push({ start: range.start + start, end: range.end + start });
+      }
+      uploadedBytes += upload.bytes;
+      if (!upload.ok) {
+        reportInstanceFailure(
+          c,
+          inst,
+          {
+            code: 'queue-write-buffer-failed',
+            expected:
+              'the renderer-owned instance storage buffer accepts the complete instance payload',
+            hint: 'retry after the active device is healthy or recover the renderer',
+          },
+          inst.instanceCount * strideBytes,
+          cap,
+        );
+        return null;
+      }
+    }
+    if (needsUpload) {
+      {
+        const published = { ...active, uploadedRevision: inst.revision ?? inst.archVersion };
+        active = published;
+        chunks?.set(chunkKey, published);
+      }
+    }
+    const activeBuffer = active;
+    draws.push({
+      instanceBuffer: activeBuffer.buffer.handle,
+      instanceBindGroup: resolveGeometryInstancesBindGroup(
+        c,
+        activeBuffer.buffer.handle,
+        probeBuffer,
+      ),
+      probeOffset,
+      instanceCount: count,
+    });
+  }
+  if (chunks !== undefined) {
+    const prefix = `${ownerKey}:`;
+    for (const [key, stale] of chunks.entries()) {
+      if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+      if (!stale.buffer.isDestroyed) {
+        const destroyed = stale.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      chunks.delete(key);
+    }
+  }
+  reportInstanceResidency(c, inst, {
+    lane: 'chunked-storage',
+    requestedBytes: inst.instanceCount * strideBytes,
+    supportedBytes: cap,
+    uploadRanges: uploadedRanges,
+    uploadedBytes,
+  });
+  return draws;
+}
+
+export function resolveGeometryInstanceBuffer(
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   identityInstanceDraws: readonly GeometryInstanceDraw[],
   useProbeBlend: boolean,
@@ -1079,6 +1603,11 @@ function resolveGeometryInstanceBuffer(
   // A present, empty Instances array means zero draws. Do not fall back to
   // the shared identity buffer, which would silently render one instance.
   if (inst.instanceCount === 0) return [];
+  const entityCacheKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const revision = inst.revision ?? inst.archVersion;
+  const sameRevision = (cached: InstanceBufferCacheEntry): boolean =>
+    cached.uploadedRevision === revision;
+  const fullRange = [{ start: 0, end: inst.instanceCount }] as const;
   let instanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
   {
@@ -1090,41 +1619,126 @@ function resolveGeometryInstanceBuffer(
     let instanceBufferUsage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
 
     if (uniformFallback && inst.instanceCount > MAX_UNIFORM_INSTANCES) {
+      const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+      const chunks = frameState.instanceBufferChunks;
+      const activeKeys = new Set<string>();
       const draws: GeometryInstanceDraw[] = [];
+      const uniformStrideBytes = 16 * Float32Array.BYTES_PER_ELEMENT;
+      const uploadedRanges: { start: number; end: number }[] = [];
+      let uploadedBytes = 0;
       for (let start = 0; start < inst.instanceCount; start += MAX_UNIFORM_INSTANCES) {
         const count = Math.min(MAX_UNIFORM_INSTANCES, inst.instanceCount - start);
-        const chunk = inst.transforms.subarray(start * 16, (start + count) * 16);
-        const bufRes = runtime.device.createBuffer({
-          size: INSTANCE_UBO_FULL_ARRAY_BYTES,
-          usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-          return null;
+        const chunkKey = `${ownerKey}:${start}`;
+        activeKeys.add(chunkKey);
+        const payloadBytes = count * uniformStrideBytes;
+        const previous = chunks?.get(chunkKey);
+        let active =
+          previous !== undefined &&
+          previous.uploadedArchVersion === inst.archVersion &&
+          previous.uploadedByteLength === payloadBytes
+            ? previous
+            : undefined;
+        let activeIsNew = false;
+        if (active === undefined) {
+          const created = runtime.device.createBuffer({
+            size: INSTANCE_UBO_FULL_ARRAY_BYTES,
+            usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!created.ok) {
+            runtime.errorRegistry.fire(created.error);
+            reportInstanceFailure(
+              c,
+              inst,
+              created.error,
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+            );
+            return null;
+          }
+          if (previous !== undefined && !previous.buffer.isDestroyed) {
+            const destroyed = previous.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          active = {
+            buffer: new GpuBuffer(runtime.device, created.value),
+            uploadedArchVersion: inst.archVersion,
+            uploadedByteLength: payloadBytes,
+          };
+          activeIsNew = true;
+          chunks?.set(chunkKey, active);
+          if (chunks === undefined) frameState.transientInstanceBuffers.push(active);
         }
-        const buffer = new GpuBuffer(runtime.device, bufRes.value);
-        frameState.transientInstanceBuffers.push({
-          buffer,
-          uploadedArchVersion: inst.archVersion,
-          uploadedByteLength: chunk.byteLength,
-        });
-        const writeRes = runtime.device.queue.writeBuffer(buffer.handle, 0, chunk);
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-          return null;
+        const needsUpload = activeIsNew || !sameRevision(active);
+        const rangesToUpload = [
+          {
+            start: 0,
+            end: count,
+          },
+        ];
+        if (needsUpload && rangesToUpload.length > 0) {
+          const upload = uploadInstanceRanges(
+            c,
+            inst,
+            active.buffer.handle,
+            rangesToUpload,
+            false,
+            start,
+          );
+          for (const range of upload.ranges) {
+            uploadedRanges.push({ start: range.start + start, end: range.end + start });
+          }
+          uploadedBytes += upload.bytes;
+          if (!upload.ok) {
+            reportInstanceFailure(
+              c,
+              inst,
+              {
+                code: 'queue-write-buffer-failed',
+                expected:
+                  'the renderer-owned instance uniform buffer accepts the complete instance payload',
+                hint: 'retry after the active device is healthy or recover the renderer',
+              },
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+            );
+            return null;
+          }
+        }
+        if (needsUpload) {
+          const published = { ...active, uploadedRevision: revision };
+          active = published;
+          chunks?.set(chunkKey, published);
         }
         draws.push({
-          instanceBuffer: buffer.handle,
+          instanceBuffer: active.buffer.handle,
           instanceBindGroup: resolveGeometryInstancesBindGroup(
             c,
-            buffer.handle,
+            active.buffer.handle,
             probeBinding?.buffer,
           ),
           probeOffset: probeBinding?.offset ?? -1,
           instanceCount: count,
         });
       }
+      if (chunks !== undefined) {
+        const prefix = `${ownerKey}:`;
+        for (const [key, stale] of chunks.entries()) {
+          if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+          if (!stale.buffer.isDestroyed) {
+            const destroyed = stale.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          chunks.delete(key);
+        }
+      }
+      reportInstanceResidency(c, inst, {
+        lane: 'chunked-uniform',
+        requestedBytes: inst.instanceCount * uniformStrideBytes,
+        supportedBytes: MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+        uploadRanges: uploadedRanges,
+        uploadedBytes,
+      });
       return draws;
     }
     if (uniformFallback) {
@@ -1134,31 +1748,30 @@ function resolveGeometryInstanceBuffer(
     {
       // Cap-gate (LimitExceededDetail single emit point — feat-20260514
       // M3 / w15 anchor): `requestedBytes <= maxStorageBufferBindingSize`.
-      const instancePayload = uniformFallback
-        ? inst.transforms
-        : packInstanceStorageBuffer(inst.transforms);
-      const requestedBytes = instancePayload.byteLength;
+      // Derive the size from the authoring count; storage packing is deferred
+      // until uploadInstanceRanges confirms a new or dirty resident.
+      const requestedBytes =
+        inst.instanceCount *
+        (uniformFallback ? 16 : INSTANCE_STORAGE_STRIDE_FLOATS) *
+        Float32Array.BYTES_PER_ELEMENT;
       const cap = runtime.device.limits.maxStorageBufferBindingSize;
       if (!uniformFallback && typeof cap === 'number' && cap > 0 && requestedBytes > cap) {
-        runtime.errorRegistry.fire(
-          new RhiError({
-            code: 'limit-exceeded',
-            expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-            hint: 'reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries',
-            detail: {
-              maxStorageBufferBindingSize: cap,
-              requestedBytes,
-            },
-          }),
+        const chunked = resolveStorageInstanceChunks(
+          c,
+          entry,
+          inst,
+          cap,
+          probeBinding?.buffer,
+          probeBinding?.offset ?? -1,
         );
-        return null;
+        return chunked;
       } else {
         // Look up the cached GPU buffer or create a fresh one when the
         // archetype version bumped or the byte length changed.
-        const cached = frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, inst.cacheKey),
-        );
+        // entityCacheKey is the worldEntityKey + collectionId namespace.
+        const cached = frameState.instanceBuffers.get(entityCacheKey);
         let active: InstanceBufferCacheEntry | null = null;
+        let activeIsNew = false;
         if (
           cached !== undefined &&
           cached.uploadedArchVersion === inst.archVersion &&
@@ -1173,6 +1786,8 @@ function resolveGeometryInstanceBuffer(
           });
           if (!bufRes.ok) {
             runtime.errorRegistry.fire(bufRes.error);
+            reportInstanceFailure(c, inst, bufRes.error, requestedBytes, cap);
+            return null;
           } else {
             // feat-20260619 M4 / F12: destroy the old cached buffer
             // before replacing it with the new one (D-6).
@@ -1186,24 +1801,67 @@ function resolveGeometryInstanceBuffer(
               uploadedArchVersion: inst.archVersion,
               uploadedByteLength: requestedBytes,
             };
-            frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, inst.cacheKey),
-              active,
-            );
+            activeIsNew = true;
+            if (active !== null) {
+              // Keep the collection identity in the worldEntityKey namespace.
+              frameState.instanceBuffers.set(entityCacheKey, active);
+            }
           }
         }
         if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload,
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            instanceBuffer = active.buffer.handle;
-            instanceCount = Math.max(1, inst.instanceCount);
+          const needsUpload = activeIsNew || !sameRevision(active);
+          const ranges = [fullRange[0]];
+          let uploadRanges: readonly { readonly start: number; readonly end: number }[] = [];
+          let uploadedBytes = 0;
+          if (needsUpload && ranges.length > 0) {
+            const upload = uploadInstanceRanges(
+              c,
+              inst,
+              active.buffer.handle,
+              ranges,
+              !uniformFallback,
+            );
+            uploadRanges = upload.ranges;
+            uploadedBytes = upload.bytes;
+            if (!upload.ok) {
+              reportInstanceFailure(
+                c,
+                inst,
+                {
+                  code: 'queue-write-buffer-failed',
+                  expected:
+                    'the renderer-owned instance buffer accepts the complete instance payloads',
+                  hint: 'retry after the active device is healthy or recover the renderer',
+                },
+                requestedBytes,
+                uniformFallback
+                  ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16
+                  : typeof cap === 'number'
+                    ? cap
+                    : undefined,
+              );
+              return null;
+            }
           }
+          if (needsUpload) {
+            const published = { ...active, uploadedRevision: revision };
+            frameState.instanceBuffers.set(entityCacheKey, published);
+            active = published;
+          }
+          instanceBuffer = active.buffer.handle;
+          instanceCount = Math.max(1, inst.instanceCount);
+          reportInstanceResidency(c, inst, {
+            lane: uniformFallback ? 'direct-uniform' : 'direct-storage',
+            requestedBytes,
+            supportedBytes: uniformFallback
+              ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16
+              : typeof cap === 'number'
+                ? cap
+                : undefined,
+            uploadRanges,
+            uploadedBytes,
+          });
+          clearInstanceChunksForOwner(c, entityCacheKey);
         }
       }
       // The cache write above is keyed by worldEntityKey(worldId, cacheKey)
@@ -1221,7 +1879,10 @@ function resolveGeometryInstanceBuffer(
 }
 
 export function resolveProbeBlendBuffer(
-  c: _InternalRenderPipelineContext,
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   record: import('../scene/probe-blend-record').ProbeBlendRecord | undefined,
   entityKey?: number,
 ): { readonly buffer: Buffer; readonly offset: number } {
@@ -1269,7 +1930,10 @@ export function resolveProbeBlendBuffer(
 }
 
 export function resolveGeometryInstancesBindGroup(
-  c: _InternalRenderPipelineContext,
+  c: Pick<
+    _InternalRenderPipelineContext,
+    'runtime' | 'pipelineState' | 'frameState' | 'bindGroupCounts'
+  >,
   instanceBuffer: Buffer,
   probeBuffer?: Buffer,
 ): BindGroup {