@forgeax/engine-render 0.1.28 → 0.1.30

package/src/inspection-types.ts

@@ -5,6 +5,10 @@
  */
 
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
+import type {
+  GpuDrivenPreparationErrorCode,
+  GpuDrivenPreparationErrorDetail,
+} from './errors/gpu-driven';
 import type { PointsLinesInspection } from './points-lines/inspection';
 import type { LodOcclusionInspection } from './scene/visibility/inspection';
 import type { SsrAdmissionIdentity } from './ssr/identity';
@@ -45,6 +49,12 @@ export type {
   SsrOwnerRecoveryAction,
 } from './ssr/errors';
 export type { SsrAdmissionIdentity } from './ssr/identity';
+export type {
+  SsrSpatialHistoryInspection,
+  SsrSpatialInspection,
+  SsrSpatialInspectionFailure,
+  SsrSpatialInspectionProjection,
+} from './ssr/inspection';
 
 export interface LightInspectionInput {
   readonly generation: number;
@@ -101,6 +111,80 @@ export interface BatchTopologyInspection {
   readonly rebuilds: number;
   readonly patches: number;
   readonly ineligible: number;
+  /** Payload-only candidate updates that preserved batch topology. */
+  readonly payloadPatches?: number;
+  /** Number of retained-slot descriptor comparisons. */
+  readonly membershipChecks?: number;
+  /** Candidate membership records materialized by the owner. */
+  readonly membershipAllocations?: number;
+  readonly candidateAdds?: number;
+  readonly candidateRemoves?: number;
+}
+
+/**
+ * Detached evidence for the declarative feature host and typed graph. These
+ * counters are diagnostic projections only; they do not alter graph admission
+ * or prepared-resource retirement semantics.
+ */
+export interface RenderFeatureHostInspection {
+  readonly signatures: readonly {
+    readonly featureIdentity: string;
+    readonly calls: number;
+    readonly typedArrayBytes: number;
+    readonly outputChars: number;
+    readonly cpuMs: number;
+    /** Number of exact structural comparisons that reused a detached snapshot. */
+    readonly cacheHits: number;
+    /** Number of structural changes that allocated a new signature revision. */
+    readonly cacheMisses: number;
+  }[];
+  readonly prepared: {
+    readonly retained: number;
+    readonly submitted: number;
+    readonly released: number;
+    readonly releaseFailures: number;
+  };
+}
+
+export interface RenderFeatureGraphInspection {
+  /** Monotonic revision of the last completely validated feature plan set. */
+  readonly planRevision: number;
+  readonly signatureValidationCalls: number;
+  readonly signatureValidationBytes: number;
+  readonly signatureValidationChars: number;
+  readonly signatureValidationCpuMs: number;
+  /** Number of plan validations satisfied by detached structural evidence. */
+  readonly signatureValidationCacheHits: number;
+  /** Number of plan validations that fell back to canonical serialization. */
+  readonly signatureValidationCacheMisses: number;
+  readonly ensureCalls: number;
+  readonly reuseHits: number;
+  readonly rebuildAttempts: number;
+  readonly compileAttempts: number;
+  readonly compileSuccesses: number;
+  readonly compileFailures: number;
+  readonly validationFailures: number;
+  readonly buildFailures: number;
+  readonly compileCpuMs: number;
+  readonly candidatesWithPreparedBatches: number;
+  readonly preparedKeyChanges: number;
+  readonly accepted: number;
+  readonly rejected: number;
+  readonly abandoned: number;
+  readonly last: {
+    readonly planSignature: string;
+    readonly topologyKey: string | undefined;
+    readonly preparedResourceKey: string | undefined;
+  };
+}
+
+/** Detached material texture-source probe accounting for the last extract. */
+export interface MaterialTextureSourceInspection {
+  readonly sourceFieldsVisited: number;
+  readonly numericSharedRefProbes: number;
+  readonly sourceCacheHits: number;
+  readonly sourceCacheMisses: number;
+  readonly producerRoutes: Readonly<Record<string, number>>;
 }
 
 export interface ProbeBlendRecordInspection {
@@ -177,7 +261,88 @@ export interface GpuSceneInspection {
   readonly noChangeFrames: number;
 }
 
+/**
+ * Closed GPU-driven execution lanes exposed by the detached inspection
+ * surface.  `cpu-semantic` keeps the existing material/authoring semantics,
+ * while `cpu-deformation` is reserved for skin data that cannot be safely
+ * represented by the GPU palette contract.  `blocked` means the renderer
+ * refused to promote an incomplete candidate instead of silently changing
+ * its meaning.
+ */
+export type GpuDrivenLane = 'gpu' | 'cpu-semantic' | 'cpu-deformation' | 'blocked';
+
+/** Closed, machine-readable reasons for a lane decision or recovery state. */
+export type GpuDrivenLaneReason =
+  | 'none'
+  | 'capability'
+  | 'unsupported'
+  | 'resource-not-ready'
+  | 'shadow-ownership'
+  | 'capacity'
+  | 'overflow'
+  | 'stale-generation'
+  | 'device-recovery'
+  | 'skin-bounds-missing'
+  | 'skin-address-missing';
+
+/**
+ * Detached producer failure facts carried by a blocked GPU lane. This keeps
+ * owner and recovery machine-readable at the same boundary as the lane
+ * decision; callers never need to parse an RhiError hint or shader name.
+ */
+export interface GpuDrivenPreparationFailureInspection {
+  readonly code: GpuDrivenPreparationErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GpuDrivenPreparationErrorDetail;
+}
+
+/**
+ * One bounded aggregate; never includes a per-draw/live renderer object.
+ * Every count uses the same concrete `(drawItem, view-pass)` key unit. `drawCount`
+ * is the count for this lane; the remaining fields make conservation explicit
+ * when a view mixes GPU-owned and CPU-residual work.
+ */
+export interface GpuDrivenLaneSummary {
+  readonly viewPass: 'main' | 'directional-shadow' | 'point-shadow' | 'spot-shadow';
+  readonly viewIndex: number;
+  readonly face?: number;
+  readonly lane: GpuDrivenLane;
+  readonly reason: GpuDrivenLaneReason;
+  readonly drawCount: number;
+  readonly totalDrawCount: number;
+  readonly claimedDrawCount: number;
+  readonly residualDrawCount: number;
+  /** First bounded producer failure for a blocked lane, when available. */
+  readonly failure?: GpuDrivenPreparationFailureInspection;
+}
+
+/**
+ * Per-submission structural work projected by the existing RenderScene/GPU
+ * Scene/palette owners. These are frame deltas, not lifetime totals, so a
+ * stable GPU-only frame is expected to report zero for every field.
+ */
+export interface GpuDrivenStructureMetrics {
+  readonly worldEntitiesScanned: number;
+  readonly sceneTableUploadBytes: number;
+  readonly paletteUploadBytes: number;
+}
+
 export interface GpuDrivenProductionInspection {
+  /** Lifetime count of successful producer-side residency validation scans. */
+  readonly residencyValidationScans: number;
+  /** Lifetime count of validation rows reused without a CPU residency walk. */
+  readonly residencyValidationCacheHits: number;
+  /** Lifetime count of CPU fallback telemetry traversals. */
+  readonly cpuValidationScans: number;
+  /** Lifetime count of CPU fallback telemetry cache hits. */
+  readonly cpuValidationCacheHits: number;
+  /** RenderScene candidate traversal performed for the last prepared frame. */
+  readonly worldEntitiesScanned: number;
+  /** GPU Scene table bytes uploaded for the last prepared frame. */
+  readonly sceneTableUploadBytes: number;
+  /** Skin palette bytes uploaded for the last prepared frame. */
+  readonly paletteUploadBytes: number;
   readonly gpuOwnedSnapshotsMaterialized: number;
   readonly filteredPlanBuilds: number;
   readonly gpuOwnedEntityCount: number;
@@ -199,6 +364,25 @@ export interface GpuDrivenProductionInspection {
   readonly batchCount: number;
   /** Number of non-zero-capacity indirect raster commands actually encoded. */
   readonly indirectDrawCount: number;
+  /** Legacy name retained for existing GPU-driven evidence consumers. */
+  readonly encodedIndirectDraws: number;
+  /** Bounded view-pass lane aggregates for AI-readable recovery. */
+  readonly channels: readonly GpuDrivenLaneSummary[];
+  /** GPU resource generation used by the last prepared view, when resident. */
+  readonly resourceGeneration: number | undefined;
+  readonly candidateCapacity: number;
+  readonly batchCapacity: number;
+  readonly indirectCapacity: number;
+  /** True when the last selector readback reported an incomplete result. */
+  readonly overflow: boolean;
+  /** Submission state for the current prepared candidate. */
+  readonly submitted: boolean;
+  /** Number of renderer-device recovery boundaries observed by this owner. */
+  readonly recoveryCount: number;
+  /** Number of staged candidates aborted before submit. */
+  readonly retryCount: number;
+  /** Generation of the last fully submitted GPU candidate, if any. */
+  readonly lastKnownGoodGeneration: number | undefined;
 }
 
 export type DirectionalShadowEffectiveProfile =
@@ -271,7 +455,9 @@ export interface ReflectionFallbackReceipt {
 }
 
 /**
- * One completed readback for the frame-owned fallback attachment.
+ * Completed fallback attachment proof, available only when the renderer opts
+ * into captureReflectionFallbackReadback. Normal rendering publishes source
+ * receipts after GPU completion without copying, mapping, or hashing pixels.
  *
  * This is an aggregate attachment fact, not a per-renderable row.  Row
  * receipts deliberately carry source/coverage identity only, so one pixel
@@ -318,6 +504,19 @@ export interface ReflectionFallbackInspection {
 }
 
 export interface ReflectionProbeInspection {
+  readonly workBudgetPerFrame?: number;
+  readonly updates?: readonly {
+    readonly worldId: number;
+    readonly entityKey: number;
+    readonly intent: 'once' | 'on-change' | 'continuous';
+    readonly activeGeneration: number;
+    readonly requestedRevision: number;
+    readonly capturedRevision: number;
+    readonly pending: boolean;
+    readonly captureStartedFrame: number;
+    readonly lastCompletedFrame: number;
+    readonly latencyFrames: number | undefined;
+  }[];
   readonly selection: ReflectionProbeSelectionInspection;
   readonly factCount: number;
   readonly acceptedCount: number;
@@ -385,6 +584,13 @@ export interface PersistentRenderSceneInspection {
   readonly transformUpdates: number;
   readonly lastResyncReason: RenderSceneResyncReason | undefined;
   readonly projectionRecords: number;
+  /** Allocation/cache evidence for instance bounds derivation. */
+  readonly instanceBoundsCache?: {
+    readonly hits: number;
+    readonly misses: number;
+    readonly derives: number;
+    readonly invalidations: number;
+  };
   /** Numeric probe ownership facts; no GPU handles or object graph references. */
   readonly probeBlend?: ProbeBlendInspection;
   readonly topology: BatchTopologyInspection;

package/src/instances-derived-bounds.ts

@@ -1,4 +1,10 @@
-import { box3, type Mat4Like, mat4 } from '@forgeax/engine-math';
+import type { Mat4Like } from '@forgeax/engine-math';
+
+// `fingerprintNumericArray` runs on every bounds-cache lookup. Keep the bit
+// reinterpretation scratch outside the hot path so a cache hit does not
+// allocate a pair of typed arrays for each retained render slot.
+const fingerprintScalar = new Float32Array(1);
+const fingerprintBits = new Uint32Array(fingerprintScalar.buffer);
 
 /**
  * Inputs owned by the render extract/persistent-scene boundary. Bounds are
@@ -34,11 +40,9 @@ export type InstanceBoundsCacheInput = InstanceBoundsCacheKey & DerivedInstances
  */
 export function fingerprintNumericArray(values: ArrayLike<number>): number {
   let hash = 0x811c9dc5;
-  const scalar = new Float32Array(1);
-  const bits = new Uint32Array(scalar.buffer);
   for (let index = 0; index < values.length; index += 1) {
-    scalar[0] = Number(values[index]);
-    hash = Math.imul(hash ^ (bits[0] ?? 0), 0x01000193) >>> 0;
+    fingerprintScalar[0] = Number(values[index]);
+    hash = Math.imul(hash ^ (fingerprintBits[0] ?? 0), 0x01000193) >>> 0;
   }
   return hash >>> 0;
 }
@@ -72,14 +76,218 @@ function finiteMatrix(matrix: ArrayLike<number>): matrix is Mat4Like {
   return true;
 }
 
-function includeBox(out: box3.Box3, candidate: box3.Box3Like): void {
-  for (const x of [candidate[0] as number, candidate[3] as number]) {
-    for (const y of [candidate[1] as number, candidate[4] as number]) {
-      for (const z of [candidate[2] as number, candidate[5] as number]) {
-        box3.expandByPoint(out, [x, y, z]);
-      }
+function multiplyMat4(
+  out: Float32Array,
+  left: ArrayLike<number>,
+  right: ArrayLike<number>,
+  rightOffset = 0,
+): void {
+  for (let column = 0; column < 4; column += 1) {
+    const rightColumn = rightOffset + column * 4;
+    const right0 = Number(right[rightColumn] ?? 0);
+    const right1 = Number(right[rightColumn + 1] ?? 0);
+    const right2 = Number(right[rightColumn + 2] ?? 0);
+    const right3 = Number(right[rightColumn + 3] ?? 0);
+    const outOffset = column * 4;
+    out[outOffset] =
+      Number(left[0] ?? 0) * right0 +
+      Number(left[4] ?? 0) * right1 +
+      Number(left[8] ?? 0) * right2 +
+      Number(left[12] ?? 0) * right3;
+    out[outOffset + 1] =
+      Number(left[1] ?? 0) * right0 +
+      Number(left[5] ?? 0) * right1 +
+      Number(left[9] ?? 0) * right2 +
+      Number(left[13] ?? 0) * right3;
+    out[outOffset + 2] =
+      Number(left[2] ?? 0) * right0 +
+      Number(left[6] ?? 0) * right1 +
+      Number(left[10] ?? 0) * right2 +
+      Number(left[14] ?? 0) * right3;
+    out[outOffset + 3] =
+      Number(left[3] ?? 0) * right0 +
+      Number(left[7] ?? 0) * right1 +
+      Number(left[11] ?? 0) * right2 +
+      Number(left[15] ?? 0) * right3;
+  }
+}
+
+function finiteMatrixAt(values: ArrayLike<number>, offset: number): boolean {
+  if (values.length - offset < 16) return false;
+  for (let index = 0; index < 16; index += 1) {
+    if (!Number.isFinite(values[offset + index] as number)) return false;
+  }
+  return true;
+}
+
+function isAffine(matrix: ArrayLike<number>): boolean {
+  return (
+    (matrix[3] as number) === 0 &&
+    (matrix[7] as number) === 0 &&
+    (matrix[11] as number) === 0 &&
+    (matrix[15] as number) === 1
+  );
+}
+
+function includeBox(
+  out: Float32Array,
+  candidate: ArrayLike<number>,
+  initialized: boolean,
+): boolean {
+  const minX = candidate[0] as number;
+  const minY = candidate[1] as number;
+  const minZ = candidate[2] as number;
+  const maxX = candidate[3] as number;
+  const maxY = candidate[4] as number;
+  const maxZ = candidate[5] as number;
+  if (!initialized) {
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = minZ;
+    out[3] = maxX;
+    out[4] = maxY;
+    out[5] = maxZ;
+    return true;
+  }
+  if (minX < (out[0] ?? Number.POSITIVE_INFINITY)) out[0] = minX;
+  if (minY < (out[1] ?? Number.POSITIVE_INFINITY)) out[1] = minY;
+  if (minZ < (out[2] ?? Number.POSITIVE_INFINITY)) out[2] = minZ;
+  if (maxX > (out[3] ?? Number.NEGATIVE_INFINITY)) out[3] = maxX;
+  if (maxY > (out[4] ?? Number.NEGATIVE_INFINITY)) out[4] = maxY;
+  if (maxZ > (out[5] ?? Number.NEGATIVE_INFINITY)) out[5] = maxZ;
+  return true;
+}
+
+/** Transform an AABB without per-instance arrays or corner tuples. */
+function transformAabb(
+  out: Float32Array,
+  local: ArrayLike<number>,
+  matrix: ArrayLike<number>,
+): boolean {
+  const minX = local[0] as number;
+  const minY = local[1] as number;
+  const minZ = local[2] as number;
+  const maxX = local[3] as number;
+  const maxY = local[4] as number;
+  const maxZ = local[5] as number;
+  const centerX = (minX + maxX) * 0.5;
+  const centerY = (minY + maxY) * 0.5;
+  const centerZ = (minZ + maxZ) * 0.5;
+  const extentX = (maxX - minX) * 0.5;
+  const extentY = (maxY - minY) * 0.5;
+  const extentZ = (maxZ - minZ) * 0.5;
+
+  if (isAffine(matrix)) {
+    const centerWorldX =
+      (matrix[0] as number) * centerX +
+      (matrix[4] as number) * centerY +
+      (matrix[8] as number) * centerZ +
+      (matrix[12] as number);
+    const centerWorldY =
+      (matrix[1] as number) * centerX +
+      (matrix[5] as number) * centerY +
+      (matrix[9] as number) * centerZ +
+      (matrix[13] as number);
+    const centerWorldZ =
+      (matrix[2] as number) * centerX +
+      (matrix[6] as number) * centerY +
+      (matrix[10] as number) * centerZ +
+      (matrix[14] as number);
+    const extentWorldX =
+      Math.abs(matrix[0] as number) * extentX +
+      Math.abs(matrix[4] as number) * extentY +
+      Math.abs(matrix[8] as number) * extentZ;
+    const extentWorldY =
+      Math.abs(matrix[1] as number) * extentX +
+      Math.abs(matrix[5] as number) * extentY +
+      Math.abs(matrix[9] as number) * extentZ;
+    const extentWorldZ =
+      Math.abs(matrix[2] as number) * extentX +
+      Math.abs(matrix[6] as number) * extentY +
+      Math.abs(matrix[10] as number) * extentZ;
+    out[0] = centerWorldX - extentWorldX;
+    out[1] = centerWorldY - extentWorldY;
+    out[2] = centerWorldZ - extentWorldZ;
+    out[3] = centerWorldX + extentWorldX;
+    out[4] = centerWorldY + extentWorldY;
+    out[5] = centerWorldZ + extentWorldZ;
+    return finiteAabb(out);
+  }
+
+  // Projective/non-affine matrices need the reference corner route. A w
+  // interval crossing zero is unbounded, so explicitly return no-cull rather
+  // than pretending the finite corner samples enclose the volume.
+  let minimumW = Number.POSITIVE_INFINITY;
+  let maximumW = Number.NEGATIVE_INFINITY;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const x = (corner & 1) === 0 ? minX : maxX;
+    const y = (corner & 2) === 0 ? minY : maxY;
+    const z = (corner & 4) === 0 ? minZ : maxZ;
+    const w =
+      (matrix[3] as number) * x +
+      (matrix[7] as number) * y +
+      (matrix[11] as number) * z +
+      (matrix[15] as number);
+    if (!Number.isFinite(w)) return false;
+    if (w < minimumW) minimumW = w;
+    if (w > maximumW) maximumW = w;
+  }
+  if (minimumW <= 0 && maximumW >= 0) return false;
+
+  let unionMinX = Number.POSITIVE_INFINITY;
+  let unionMinY = Number.POSITIVE_INFINITY;
+  let unionMinZ = Number.POSITIVE_INFINITY;
+  let unionMaxX = Number.NEGATIVE_INFINITY;
+  let unionMaxY = Number.NEGATIVE_INFINITY;
+  let unionMaxZ = Number.NEGATIVE_INFINITY;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const x = (corner & 1) === 0 ? minX : maxX;
+    const y = (corner & 2) === 0 ? minY : maxY;
+    const z = (corner & 4) === 0 ? minZ : maxZ;
+    const rawX =
+      (matrix[0] as number) * x +
+      (matrix[4] as number) * y +
+      (matrix[8] as number) * z +
+      (matrix[12] as number);
+    const rawY =
+      (matrix[1] as number) * x +
+      (matrix[5] as number) * y +
+      (matrix[9] as number) * z +
+      (matrix[13] as number);
+    const rawZ =
+      (matrix[2] as number) * x +
+      (matrix[6] as number) * y +
+      (matrix[10] as number) * z +
+      (matrix[14] as number);
+    const w =
+      (matrix[3] as number) * x +
+      (matrix[7] as number) * y +
+      (matrix[11] as number) * z +
+      (matrix[15] as number);
+    const projectedX = rawX / w;
+    const projectedY = rawY / w;
+    const projectedZ = rawZ / w;
+    if (
+      !Number.isFinite(projectedX) ||
+      !Number.isFinite(projectedY) ||
+      !Number.isFinite(projectedZ)
+    ) {
+      return false;
     }
+    if (projectedX < unionMinX) unionMinX = projectedX;
+    if (projectedY < unionMinY) unionMinY = projectedY;
+    if (projectedZ < unionMinZ) unionMinZ = projectedZ;
+    if (projectedX > unionMaxX) unionMaxX = projectedX;
+    if (projectedY > unionMaxY) unionMaxY = projectedY;
+    if (projectedZ > unionMaxZ) unionMaxZ = projectedZ;
   }
+  out[0] = unionMinX;
+  out[1] = unionMinY;
+  out[2] = unionMinZ;
+  out[3] = unionMaxX;
+  out[4] = unionMaxY;
+  out[5] = unionMaxZ;
+  return finiteAabb(out);
 }
 
 /**
@@ -97,36 +305,31 @@ export function deriveInstancesUnionBounds(
     return undefined;
   }
   if (transforms.length === 0 || transforms.length % 16 !== 0) return undefined;
-
-  const local = box3.create(
-    meshAabb[0] as number,
-    meshAabb[1] as number,
-    meshAabb[2] as number,
-    meshAabb[3] as number,
-    meshAabb[4] as number,
-    meshAabb[5] as number,
-  );
-  const union = box3.create();
-  const composed = mat4.create();
-  const transformed = box3.create();
+  const local = meshAabb;
+  const union = new Float32Array(6);
+  const composed = new Float32Array(16);
+  const transformed = new Float32Array(6);
+  let initialized = false;
   for (let offset = 0; offset < transforms.length; offset += 16) {
-    const instance = new Float32Array(16);
-    for (let lane = 0; lane < 16; lane += 1) {
-      instance[lane] = transforms[offset + lane] as number;
-    }
-    if (!finiteMatrix(instance)) return undefined;
-    mat4.multiply(composed, entityWorld, instance);
-    box3.transformBox3(transformed, local, composed);
-    if (!finiteAabb(transformed)) return undefined;
-    includeBox(union, transformed);
+    if (!finiteMatrixAt(transforms, offset)) return undefined;
+    multiplyMat4(composed, entityWorld, transforms, offset);
+    if (!finiteMatrix(composed) || !transformAabb(transformed, local, composed)) return undefined;
+    initialized = includeBox(union, transformed, initialized);
   }
-  return new Float32Array(union);
+  return initialized && finiteAabb(union) ? union : undefined;
 }
 
 interface InstanceBoundsCacheEntry extends InstanceBoundsCacheKey {
   readonly bounds: Float32Array | undefined;
 }
 
+export interface InstanceBoundsCacheInspection {
+  readonly hits: number;
+  readonly misses: number;
+  readonly derives: number;
+  readonly invalidations: number;
+}
+
 /**
  * Small renderer-owned per-entity cache. A changed generation replaces the
  * entry atomically; packed-id reuse is safe when its owner supplies a new
@@ -134,6 +337,10 @@ interface InstanceBoundsCacheEntry extends InstanceBoundsCacheKey {
  */
 export class InstanceBoundsCache {
   private readonly entries = new Map<string, InstanceBoundsCacheEntry>();
+  private hits = 0;
+  private misses = 0;
+  private derives = 0;
+  private invalidations = 0;
 
   private key(input: Pick<InstanceBoundsCacheKey, 'worldId' | 'entityKey'>): string {
     return `${input.worldId === undefined ? '' : `${input.worldId}:`}${input.entityKey}`;
@@ -147,8 +354,11 @@ export class InstanceBoundsCache {
       previous.transformGeneration === input.transformGeneration &&
       previous.matrixGeneration === input.matrixGeneration
     ) {
+      this.hits += 1;
       return previous.bounds;
     }
+    this.misses += 1;
+    this.derives += 1;
     const bounds = deriveInstancesUnionBounds(input);
     this.entries.set(this.key(input), {
       ...(input.worldId === undefined ? {} : { worldId: input.worldId }),
@@ -163,9 +373,23 @@ export class InstanceBoundsCache {
 
   invalidate(entityKey?: number, worldId?: number): void {
     if (entityKey === undefined) {
+      if (this.entries.size > 0) this.invalidations += this.entries.size;
       this.entries.clear();
     } else {
-      this.entries.delete(this.key({ entityKey, ...(worldId === undefined ? {} : { worldId }) }));
+      if (
+        this.entries.delete(this.key({ entityKey, ...(worldId === undefined ? {} : { worldId }) }))
+      ) {
+        this.invalidations += 1;
+      }
     }
   }
+
+  inspect(): InstanceBoundsCacheInspection {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      derives: this.derives,
+      invalidations: this.invalidations,
+    };
+  }
 }