@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/bind-group-cache-keying.test.ts

@@ -0,0 +1,295 @@
+// feat-20260622-handle-to-id-allocator-elimination M2 / w4 + w5:
+// TDD tests for WeakMap chain determinism, cleanup new shape, AC-08 export,
+// and AC-06 two-helper existence. Replaces the old string-key dedup +
+// sentinel-survival tests (buildBindGroupCacheKey / Number.isNaN / D-6 rescue).
+//
+// w4: chain determinism (getOrCreateFromChain — red until w7 implements it).
+// w5: cleanup eviction (cleanPerEntityCache — red until w8 rewrites it)
+//     + getOrCreatePerEntity existence (red until w8 implements it).
+
+import type { BindGroup } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type { BindGroupCounts } from '../../../render/src/record/frame-snapshot';
+import {
+  cleanPerEntityCache,
+  getOrCreateFromChain,
+  getOrCreatePerEntity,
+} from '../../../render/src/record/mesh-ssbo';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function h(): object {
+  return {};
+}
+
+function stubBindGroup(): BindGroup {
+  return {} as unknown as BindGroup;
+}
+
+function stubCounts(): BindGroupCounts {
+  return { createBindGroup: 0, keys: [] };
+}
+
+function factory(): BindGroup {
+  return stubBindGroup();
+}
+
+// ─── w4: WeakMap chain determinism (no id allocator, no NaN, no string key) ──
+//
+// The old buildBindGroupCacheKey walked a WeakMap<object,number> counter to
+// produce string keys for a flat Map<string,BG>. The new design uses handle
+// objects directly as WeakMap chain nodes — same object identity → same leaf,
+// different objects → different leaf. No Number.isNaN rescue branch exists
+// because there is no string parsing.
+//
+// These tests are RED until w7 implements getOrCreateFromChain (D-2 / AC-06).
+
+describe('w4 — WeakMap chain determinism', () => {
+  it('same handles + same variant produces the same BG leaf (deterministic)', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    const bg2 = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    expect(bg1).toBe(bg2);
+  });
+
+  it('different handle set produces a different BG leaf', () => {
+    const root = new WeakMap<object, unknown>();
+    const handlesA = [h(), h()];
+    const handlesB = [h(), h()];
+    const counts = stubCounts();
+    const bgA = getOrCreateFromChain(root, handlesA, 'view-main', factory, counts);
+    const bgB = getOrCreateFromChain(root, handlesB, 'view-main', factory, counts);
+    expect(bgA).not.toBe(bgB);
+  });
+
+  it('same handles + different variant produces different BG leaf', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bgMain = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+    const bgShadow = getOrCreateFromChain(root, handles, 'view-shadow', factory, counts);
+    expect(bgMain).not.toBe(bgShadow);
+  });
+
+  it('chain lookup is idempotent — createBindGroup stays at 1 across N calls', () => {
+    const root = new WeakMap<object, unknown>();
+    const handles = [h(), h(), h(), h(), h(), h(), h()]; // 7 deep like view-main
+    const counts = stubCounts();
+    for (let i = 0; i < 100; i++) {
+      const bg = getOrCreateFromChain(root, handles, 'view-main', factory, counts);
+      expect(bg).toBeDefined();
+    }
+    expect(counts.createBindGroup).toBe(1);
+  });
+});
+
+// ─── w5a: cleanPerEntityCache new shape (AC-02 / AC-08) ─────────────────────
+//
+// The old cleanPerEntityCache parsed entityKey from string keys via
+// indexOf('-') + Number(slice) and used Number.isNaN(ek) to rescue
+// sentinel / material-shared keys. The new design uses Map<number, WeakMap>
+// where entityKey is already a number — eviction is a simple delete loop:
+//   for (const ek of cache.keys())
+//     if (!validatedEntityKeys.has(ek)) cache.delete(ek)
+//
+// No string parsing, no Number.isNaN, no indexOf / Number calls.
+// cleanPerEntityCache remains an @internal export (AC-08).
+//
+// These tests are RED until w8 rewrites cleanPerEntityCache (RD4 / AC-02).
+
+describe('w5a — cleanPerEntityCache new shape (AC-02, AC-08)', () => {
+  it('deletes entityKeys not in the validated set', () => {
+    const bg1 = stubBindGroup();
+    const bg2 = stubBindGroup();
+    const inner1 = new WeakMap<object, BindGroup>();
+    inner1.set(h(), bg1);
+    const inner2 = new WeakMap<object, BindGroup>();
+    inner2.set(h(), bg2);
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(123, inner1);
+    cache.set(456, inner2);
+
+    const validated = new Set<number>([123]);
+
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(123)).toBe(true); // validated -> kept
+    expect(cache.has(456)).toBe(false); // stale -> deleted
+  });
+
+  it('deletes all entityKeys when validated set is empty', () => {
+    const inner = new WeakMap<object, BindGroup>();
+    inner.set(h(), stubBindGroup());
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(42, inner);
+
+    cleanPerEntityCache(cache, new Set());
+
+    expect(cache.size).toBe(0);
+  });
+
+  it('keeps all entityKeys when all are validated', () => {
+    const inner1 = new WeakMap<object, BindGroup>();
+    inner1.set(h(), stubBindGroup());
+    const inner2 = new WeakMap<object, BindGroup>();
+    inner2.set(h(), stubBindGroup());
+    const cache = new Map<number, WeakMap<object, BindGroup>>();
+    cache.set(1, inner1);
+    cache.set(2, inner2);
+
+    const validated = new Set<number>([1, 2]);
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.size).toBe(2);
+    expect(cache.has(1)).toBe(true);
+    expect(cache.has(2)).toBe(true);
+  });
+
+  it('has no string parsing, no Number.isNaN, no Number calls in function body', () => {
+    // AC-02: the function body must not contain indexOf, Number, or Number.isNaN.
+    const fnSrc = cleanPerEntityCache.toString();
+    expect(fnSrc).not.toContain('indexOf');
+    expect(fnSrc).not.toContain('Number.isNaN');
+    expect(fnSrc).not.toContain('Number(');
+  });
+});
+
+// ─── w5b: getOrCreatePerEntity existence (AC-06) ────────────────────────────
+//
+// The new per-entity helper `getOrCreatePerEntity` takes an outer
+// Map<string|number, WeakMap<...>> and an outerKey, then walks the
+// inner WeakMap chain. No branch-on-cache-type inside a single generic
+// helper (AC-06: two distinct helpers exist, no unified one).
+//
+// These tests are RED until w8 implements getOrCreatePerEntity (D-2 / AC-06).
+
+describe('w5b — getOrCreatePerEntity existence and behavior (AC-06)', () => {
+  it('getOrCreatePerEntity is a distinct named export (no branch-on-cache-type)', () => {
+    // AC-06: Two named helpers exist, no unified generic helper with
+    // branch-on-cache-type. These imports would fail at load time if either
+    // symbol is missing (the file-level import already validates this).
+    expect(typeof getOrCreateFromChain).toBe('function');
+    expect(typeof getOrCreatePerEntity).toBe('function');
+  });
+
+  it('getOrCreatePerEntity with outerKey=number hits same leaf on second call', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreatePerEntity(outer, 42, handles, 'material', factory, counts);
+    const bg2 = getOrCreatePerEntity(outer, 42, handles, 'material', factory, counts);
+    expect(bg1).toBe(bg2);
+    expect(counts.createBindGroup).toBe(1);
+  });
+
+  it('getOrCreatePerEntity with outerKey=string hits same leaf on second call', () => {
+    // material-shared uses string outerKey (shaderId) — OQ-1 / D-1.
+    const outer = new Map<string, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bg1 = getOrCreatePerEntity(
+      outer,
+      'pbr-standard',
+      handles,
+      'material-shared',
+      factory,
+      counts,
+    );
+    const bg2 = getOrCreatePerEntity(
+      outer,
+      'pbr-standard',
+      handles,
+      'material-shared',
+      factory,
+      counts,
+    );
+    expect(bg1).toBe(bg2);
+    expect(counts.createBindGroup).toBe(1);
+  });
+
+  it('getOrCreatePerEntity: different outerKey produces different leaf', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const handles = [h(), h()];
+    const counts = stubCounts();
+    const bgA = getOrCreatePerEntity(outer, 1, handles, 'material', factory, counts);
+    const bgB = getOrCreatePerEntity(outer, 2, handles, 'material', factory, counts);
+    expect(bgA).not.toBe(bgB);
+  });
+});
+
+// ─── w20: HDRP shadow-instances cross-function producer/consumer pair (D-4) ──
+//
+// recordShadowPass writes the shadow-instances BG at render-system-record.ts
+// :3438 via getOrCreatePerEntity(instancesBgPerEntity, entityKey,
+// [instBuffer], 'shadow-instances', ...). The HDRP main pass reads it back at
+// :3825 NOT through the helper, but with a manual two-step lookup:
+//   instancesBgPerEntity.get(entityKey)?.get(instBuffer) as Map<string, BG>
+//   leaf?.get('shadow-instances')
+// If the read end used a different outerKey or handle than the write end, the
+// lookup would miss, the main pass would `continue`, and instanced shadows
+// would silently vanish. HDRP shadow pass has no dawn smoke and the HDRP
+// browser tests only assert BGL slots / gbuffer formats (not shadow-instance
+// draws), so this invariant is otherwise untested (research OQ-2). These tests
+// fixate the D-4 contract: the manual read shape must find the helper write.
+
+describe('w20 — HDRP shadow-instances cross-function read finds helper write (D-4)', () => {
+  const SHADOW_INSTANCES_VARIANT = 'shadow-instances';
+
+  // Mirrors the :3825 read end: two WeakMap hops + variant leaf lookup.
+  function readShadowInstancesBg(
+    outer: Map<number, WeakMap<object, unknown>>,
+    entityKey: number,
+    instBuffer: object,
+  ): BindGroup | undefined {
+    const leaf = outer.get(entityKey)?.get(instBuffer) as Map<string, BindGroup> | undefined;
+    return leaf?.get(SHADOW_INSTANCES_VARIANT);
+  }
+
+  it('read end finds the leaf the write end stored under the same (entityKey, instBuffer)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const entityKey = 7;
+    const instBuffer = h(); // the shared instance buffer handle (single-handle chain)
+    const counts = stubCounts();
+
+    // Write end (:3438): recordShadowPass populates the per-entity leaf.
+    const written = getOrCreatePerEntity(
+      outer,
+      entityKey,
+      [instBuffer],
+      SHADOW_INSTANCES_VARIANT,
+      factory,
+      counts,
+    );
+
+    // Read end (:3825): HDRP main pass resolves it with the same pair.
+    const read = readShadowInstancesBg(outer, entityKey, instBuffer);
+
+    expect(read).toBeDefined();
+    expect(read).toBe(written);
+    expect(counts.createBindGroup).toBe(1); // single create, then a hit on read
+  });
+
+  it('read end misses when the entityKey differs (per-entity isolation)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const instBuffer = h();
+    const counts = stubCounts();
+
+    getOrCreatePerEntity(outer, 7, [instBuffer], SHADOW_INSTANCES_VARIANT, factory, counts);
+
+    // Different entity, same buffer handle -> no outer-Map entry -> miss.
+    expect(readShadowInstancesBg(outer, 8, instBuffer)).toBeUndefined();
+  });
+
+  it('read end misses when the instance buffer handle differs (chain identity)', () => {
+    const outer = new Map<number, WeakMap<object, unknown>>();
+    const entityKey = 7;
+    const counts = stubCounts();
+
+    getOrCreatePerEntity(outer, entityKey, [h()], SHADOW_INSTANCES_VARIANT, factory, counts);
+
+    // Same entity, a fresh (grown) instance buffer object -> inner WeakMap miss.
+    expect(readShadowInstancesBg(outer, entityKey, h())).toBeUndefined();
+  });
+});

package/src/__tests__/block-upload-math.unit.test.ts

@@ -0,0 +1,192 @@
+// w29 -- block-aware upload math unit tests (AC-08).
+//
+// Table-driven coverage of `deriveMipUploadLayout` (render-data.ts, landed by
+// w35): the per-mip GPU-upload layout for block-compressed textures. Each mip
+// level's `bytesPerRow` pads the pixel width up to a full block
+// (`ceil(width / blockW) * bytesPerBlock`) and `rowsPerImage` counts block rows
+// (`ceil(height / blockH)`); `byteOffset` accumulates the prior levels' byte
+// lengths (mip-major layout). The GPU samples only the valid texel region, so
+// non-4-multiple sizes and the 1x1 / 2x2 mip tails pad up to a block without
+// corrupting the image (t5).
+//
+// This is TDD-RED before w35 -- `deriveMipUploadLayout` does not exist yet.
+//
+// Constraints (plan-tasks w29):
+//   - no real GPU writeTexture call (browser e2e AC-15 owns that)
+//   - no re-test of the block table contents (codec w9 owns that)
+//   - pure node unit, no browser / dawn dependency
+
+import { describe, expect, it } from 'vitest';
+import {
+  deriveMipUploadLayout,
+  deriveTextureExtent,
+  type MipUploadLevel,
+} from '../../../render/src/render-data';
+
+/** Sum of every level's byte length -- the total block-byte buffer size. */
+function totalBytes(layout: readonly MipUploadLevel[]): number {
+  return layout.reduce((acc, l) => acc + l.byteLength, 0);
+}
+
+describe('deriveMipUploadLayout -- single-level block sizing (w29)', () => {
+  // BC7 = 4x4 block, 16 bytes/block. bytesPerRow = ceil(w/4)*16.
+  it.each([
+    // [width, height, expectedBytesPerRow, expectedRowsPerImage]
+    [4, 4, 16, 1], // exact single block
+    [8, 8, 32, 2], // 2x2 blocks
+    [7, 7, 32, 2], // non-4-multiple: ceil(7/4)=2 both axes
+    [1, 1, 16, 1], // 1x1 tail pads to a full block
+    [2, 2, 16, 1], // 2x2 tail pads to a full block
+    [5, 3, 32, 1], // ceil(5/4)=2 -> 32 wide, ceil(3/4)=1 tall
+    [16, 1, 64, 1], // wide sliver
+  ])('bc7 %ix%i -> bytesPerRow=%i rowsPerImage=%i', (w, h, bpr, rpi) => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', w, h, 1);
+    expect(layout).toHaveLength(1);
+    const l = layout[0] as MipUploadLevel;
+    expect(l.level).toBe(0);
+    expect(l.width).toBe(w);
+    expect(l.height).toBe(h);
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+    expect(l.byteOffset).toBe(0);
+    expect(l.byteLength).toBe(bpr * rpi);
+  });
+
+  // BC1 / BC4 / ETC2-rgb8 / EAC-r11 = 4x4 block, 8 bytes/block (0.5 bpp).
+  it.each([
+    ['bc1-rgba-unorm', 8, 8, 16, 2],
+    ['bc4-r-unorm', 4, 4, 8, 1],
+    ['etc2-rgb8unorm', 16, 16, 32, 4],
+    ['eac-r11unorm', 7, 5, 16, 2],
+  ] as const)('%s %ix%i -> bytesPerRow=%i rowsPerImage=%i', (fmt, w, h, bpr, rpi) => {
+    const l = deriveMipUploadLayout(fmt, w, h, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+  });
+
+  // ASTC block dims come from the format name; all 16 bytes/block.
+  it.each([
+    ['astc-4x4-unorm', 8, 8, 32, 2],
+    ['astc-6x6-unorm', 12, 12, 32, 2], // ceil(12/6)=2 -> 32, ceil(12/6)=2
+    ['astc-8x8-unorm', 9, 9, 32, 2], // ceil(9/8)=2 both axes
+    ['astc-5x4-unorm', 5, 4, 16, 1], // one 5-wide x 4-tall block
+  ] as const)('%s %ix%i -> bytesPerRow=%i rowsPerImage=%i', (fmt, w, h, bpr, rpi) => {
+    const l = deriveMipUploadLayout(fmt, w, h, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(bpr);
+    expect(l.rowsPerImage).toBe(rpi);
+  });
+
+  // BC6H (HDR) = 4x4 block, 16 bytes/block -- the equirect HDR upload path.
+  it('bc6h-rgb-ufloat 4x4 -> one 16-byte block', () => {
+    const l = deriveMipUploadLayout('bc6h-rgb-ufloat', 4, 4, 1)[0] as MipUploadLevel;
+    expect(l.bytesPerRow).toBe(16);
+    expect(l.rowsPerImage).toBe(1);
+    expect(l.byteLength).toBe(16);
+  });
+});
+
+describe('deriveMipUploadLayout -- mip-major offset accumulation (w29)', () => {
+  it('bc7 8x8 4-level chain accumulates offsets with block-padded tails', () => {
+    // levels: 8x8, 4x4, 2x2, 1x1 (2x2 and 1x1 pad up to a full 4x4 block)
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 8, 8, 4);
+    expect(layout).toHaveLength(4);
+
+    const expected: readonly Pick<
+      MipUploadLevel,
+      'width' | 'height' | 'bytesPerRow' | 'rowsPerImage' | 'byteOffset' | 'byteLength'
+    >[] = [
+      { width: 8, height: 8, bytesPerRow: 32, rowsPerImage: 2, byteOffset: 0, byteLength: 64 },
+      { width: 4, height: 4, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 64, byteLength: 16 },
+      { width: 2, height: 2, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 80, byteLength: 16 },
+      { width: 1, height: 1, bytesPerRow: 16, rowsPerImage: 1, byteOffset: 96, byteLength: 16 },
+    ];
+    for (let i = 0; i < expected.length; i++) {
+      const l = layout[i] as MipUploadLevel;
+      expect(l.level).toBe(i);
+      expect({
+        width: l.width,
+        height: l.height,
+        bytesPerRow: l.bytesPerRow,
+        rowsPerImage: l.rowsPerImage,
+        byteOffset: l.byteOffset,
+        byteLength: l.byteLength,
+      }).toEqual(expected[i]);
+    }
+    expect(totalBytes(layout)).toBe(112);
+  });
+
+  it('bc1 non-square 12x6 3-level chain (0.5bpp) offsets are contiguous', () => {
+    // 12x6 -> 6x3 -> 3x1  (bc1 = 8 bytes/block, 4x4)
+    const layout = deriveMipUploadLayout('bc1-rgba-unorm', 12, 6, 3);
+    // level0 12x6: bpr=ceil(12/4)*8=24, rpi=ceil(6/4)=2, len=48, off=0
+    // level1 6x3:  bpr=ceil(6/4)*8=16, rpi=ceil(3/4)=1, len=16, off=48
+    // level2 3x1:  bpr=ceil(3/4)*8=8,  rpi=1,           len=8,  off=64
+    expect(layout.map((l) => l.byteOffset)).toEqual([0, 48, 64]);
+    expect(layout.map((l) => l.byteLength)).toEqual([48, 16, 8]);
+    expect(totalBytes(layout)).toBe(72);
+  });
+
+  it('single-level (no mip chain) returns one entry at offset 0', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 256, 256, 1);
+    expect(layout).toHaveLength(1);
+    expect(layout[0]?.byteOffset).toBe(0);
+  });
+});
+
+describe('deriveMipUploadLayout -- physical full-subresource copy extents', () => {
+  it('aligns non-block-aligned BC7 copies to physical storage', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 7, 5, 1);
+    expect(layout[0]?.copyWidth).toBe(8);
+    expect(layout[0]?.copyHeight).toBe(8);
+  });
+
+  it('aligns sub-block tail mip copies independently', () => {
+    const layout = deriveMipUploadLayout('bc7-rgba-unorm', 8, 8, 4);
+    expect(layout[2]?.width).toBe(2);
+    expect(layout[2]?.copyWidth).toBe(4);
+    expect(layout[2]?.copyHeight).toBe(4);
+    expect(layout[3]?.width).toBe(1);
+    expect(layout[3]?.copyWidth).toBe(4);
+    expect(layout[3]?.copyHeight).toBe(4);
+  });
+
+  it('aligns non-square ASTC copies with its own block dimensions', () => {
+    const layout = deriveMipUploadLayout('astc-8x5-unorm', 5, 3, 1);
+    expect(layout[0]?.copyWidth).toBe(8);
+    expect(layout[0]?.copyHeight).toBe(5);
+  });
+});
+
+describe('deriveTextureExtent -- logical asset extent to physical storage extent (w35)', () => {
+  it('derives BC7 physical storage and a logical UV scale without changing logical metadata', () => {
+    expect(deriveTextureExtent('bc7-rgba-unorm', 2085, 1573)).toEqual({
+      logicalExtent: { width: 2085, height: 1573 },
+      physicalExtent: { width: 2088, height: 1576 },
+      uvScale: [2085 / 2088, 1573 / 1576],
+    });
+  });
+
+  it('derives each 4x4 tail mip independently', () => {
+    expect(deriveTextureExtent('bc7-rgba-unorm', 2, 1)).toEqual({
+      logicalExtent: { width: 2, height: 1 },
+      physicalExtent: { width: 4, height: 4 },
+      uvScale: [0.5, 0.25],
+    });
+  });
+
+  it('uses the codec block-format table for a non-4x4 format', () => {
+    expect(deriveTextureExtent('astc-6x6-unorm', 7, 8)).toEqual({
+      logicalExtent: { width: 7, height: 8 },
+      physicalExtent: { width: 12, height: 12 },
+      uvScale: [7 / 12, 8 / 12],
+    });
+  });
+
+  it('keeps uncompressed textures at identity extent and scale', () => {
+    expect(deriveTextureExtent('rgba8unorm', 17, 9)).toEqual({
+      logicalExtent: { width: 17, height: 9 },
+      physicalExtent: { width: 17, height: 9 },
+      uvScale: [1, 1],
+    });
+  });
+});

package/src/__tests__/builtin-asset-registry.unit.test.ts

@@ -0,0 +1,112 @@
+// M6 w46 (AC-30): BuiltinAssetRegistry process-static resolution TDD.
+//
+// D-15 two-tier asset resolution: builtin payloads live in a process-static
+// const keyed by fixed slot u32 (1..6), resolved without any World. Slots
+// >= BUILTIN_BASE belong to the user tier (World.sharedRefs) and resolve to
+// null here. R-13: module init order — importing BuiltinAssetRegistry then
+// immediately resolving all 6 handles must not throw / return undefined.
+// M6 w46 (AC-30): BuiltinAssetRegistry process-static resolution TDD.
+//
+// D-15 two-tier asset resolution: builtin payloads live in a process-static
+// const keyed by fixed slot u32 (1..6), resolved without any World. Slots
+// >= BUILTIN_BASE belong to the user tier (World.sharedRefs) and resolve to
+// null here. R-13: module init order — importing BuiltinAssetRegistry then
+// immediately resolving all 6 handles must not throw / return undefined.
+import {
+  BUILTIN_BASE,
+  BUILTIN_CUBE,
+  BUILTIN_CYLINDER,
+  BUILTIN_NINESLICE_QUAD,
+  BUILTIN_QUAD,
+  BUILTIN_SPHERE,
+  BUILTIN_TRIANGLE,
+  BuiltinAssetRegistry,
+  HANDLE_CUBE,
+  HANDLE_CYLINDER,
+  HANDLE_NINESLICE_QUAD,
+  HANDLE_QUAD,
+  HANDLE_SPHERE,
+  HANDLE_TRIANGLE,
+} from '@forgeax/engine-assets-runtime';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('BuiltinAssetRegistry.resolve (AC-30)', () => {
+  it('resolves each builtin slot 1..6 to its frozen payload', () => {
+    expect(BuiltinAssetRegistry.resolve(HANDLE_CUBE)).toBe(BUILTIN_CUBE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_TRIANGLE)).toBe(BUILTIN_TRIANGLE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_QUAD)).toBe(BUILTIN_QUAD);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_SPHERE)).toBe(BUILTIN_SPHERE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_NINESLICE_QUAD)).toBe(BUILTIN_NINESLICE_QUAD);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_CYLINDER)).toBe(BUILTIN_CYLINDER);
+  });
+
+  it('returns frozen payloads (Object.isFrozen)', () => {
+    expect(Object.isFrozen(BUILTIN_CUBE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_TRIANGLE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_QUAD)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_SPHERE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_NINESLICE_QUAD)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_CYLINDER)).toBe(true);
+  });
+
+  it('returns null for user-tier slots (slot >= BUILTIN_BASE)', () => {
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(BUILTIN_BASE))).toBeNull();
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(BUILTIN_BASE + 1))).toBeNull();
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(99999))).toBeNull();
+  });
+
+  it('returns null for slot 0 (no builtin reserves slot 0)', () => {
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(0))).toBeNull();
+  });
+
+  it('R-13: module-first-import probe resolves all 6 handles without throwing or undefined', () => {
+    // Importing BuiltinAssetRegistry then resolving must observe fully
+    // constructed frozen payloads — no init-order hazard (synchronous,
+    // module-level, no side effect).
+    for (const handle of [
+      HANDLE_CUBE,
+      HANDLE_TRIANGLE,
+      HANDLE_QUAD,
+      HANDLE_SPHERE,
+      HANDLE_NINESLICE_QUAD,
+      HANDLE_CYLINDER,
+    ]) {
+      const payload = BuiltinAssetRegistry.resolve(handle);
+      expect(payload).not.toBeUndefined();
+      expect(payload).not.toBeNull();
+    }
+  });
+});
+
+// bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu M2 / AC-02.
+//
+// Flat aabb layout is `Float32Array` of length 6 [minX, minY, minZ,
+// maxX, maxY, maxZ] per `packages/types/src/index.ts:308` — the requirements
+// wording "min/max both length-3 arrays with min[i] <= max[i]" reads as
+// index [0..2] vs [3..5] within that flat array (no {min,max} object wrap).
+describe('builtin payloads carry finite local-space AABBs (AC-02)', () => {
+  it.each([
+    ['HANDLE_CUBE', HANDLE_CUBE, BUILTIN_CUBE],
+    ['HANDLE_TRIANGLE', HANDLE_TRIANGLE, BUILTIN_TRIANGLE],
+    ['HANDLE_QUAD', HANDLE_QUAD, BUILTIN_QUAD],
+    ['HANDLE_SPHERE', HANDLE_SPHERE, BUILTIN_SPHERE],
+    ['HANDLE_NINESLICE_QUAD', HANDLE_NINESLICE_QUAD, BUILTIN_NINESLICE_QUAD],
+    ['HANDLE_CYLINDER', HANDLE_CYLINDER, BUILTIN_CYLINDER],
+  ])('%s exposes the same valid local AABB through registry and export', (_name, handle, exportedConst) => {
+    const payload = BuiltinAssetRegistry.resolve(handle);
+    expect(payload).not.toBeNull();
+    expect(payload).toBe(exportedConst);
+    const aabb = payload?.aabb;
+    expect(aabb).toBeInstanceOf(Float32Array);
+    expect(aabb).toHaveLength(6);
+    if (aabb === undefined) return;
+    for (let axis = 0; axis < 3; axis++) {
+      const minV = aabb[axis];
+      const maxV = aabb[axis + 3];
+      expect(Number.isFinite(minV)).toBe(true);
+      expect(Number.isFinite(maxV)).toBe(true);
+      expect(minV as number).toBeLessThanOrEqual(maxV as number);
+    }
+  });
+});