@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/glyph-tilemap-worldid.test.ts

@@ -12,8 +12,8 @@
 //   plan-strategy D-1a #6/#7
 //   requirements AC-07
 
-import { worldEntityKey } from '@forgeax/engine-render/internal';
 import { describe, expect, it } from 'vitest';
+import { worldEntityKey } from '../../../render/src/record/frame-snapshot';
 
 // ─── Glyph bakeCache: worldEntityKey key compositing ────────────────────────
 

package/src/__tests__/gpu-resource-cow-survivor.test.ts

@@ -11,12 +11,13 @@
 // Architecture (plan-strategy D-7): epsilon=0.1 permits WebGPU deferred-destroy
 // in-flight double-buffer float, while forbidding monotonic growth.
 
-import { cleanPerEntityCache, GpuResourceStore } from '@forgeax/engine-render/internal';
 import type { Result, RhiCaps, RhiError } from '@forgeax/engine-rhi';
 import { err, ok } from '@forgeax/engine-rhi';
 import type { EquirectAsset, Handle, MeshAsset, TextureAsset } from '@forgeax/engine-types';
 import { toShared, unwrapHandle } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import { cleanPerEntityCache } from '../../../render/src/record/mesh-ssbo';
 
 // ── Mock device (same shape as gpu-resource.test.ts makeStoreMockDevice) ──
 
@@ -39,6 +40,7 @@ function makeMockDevice(probe: CowProbe): any {
   const destroyedBufs = new WeakSet<object>();
   const destroyedTexs = new WeakSet<object>();
   return {
+    limits: { maxTextureDimension2D: 16384 },
     createShaderModule: () => okShim({ __mock: 'shader' }),
     createSampler: () => okShim({ __mock: 'sampler' }),
     createBindGroupLayout: () => okShim({ __mock: 'bgl' }),
@@ -126,8 +128,8 @@ function makeRegisterCube(): (
 const shaderFactory = async (_d: any, desc: { code: string; label?: string }) =>
   ok({ __mock: 'shader', label: desc.label ?? '' }) as never;
 
-function configuredStore(probe: CowProbe): GpuResourceStore {
-  const store = new GpuResourceStore();
+function configuredStore(probe: CowProbe): GpuResidencyCache {
+  const store = new GpuResidencyCache();
   store.configureGpuDevice(
     makeMockDevice(probe),
     shaderFactory,
@@ -184,7 +186,7 @@ function median(sorted: number[]): number {
   return sorted[mid] ?? 0;
 }
 
-function aFamilyStoreSize(store: GpuResourceStore): number {
+function aFamilyStoreSize(store: GpuResidencyCache): number {
   // biome-ignore lint/suspicious/noExplicitAny: access private store maps for size tracking
   const s = store as any;
   return (

package/src/__tests__/guid-for-asset.unit.test.ts

@@ -0,0 +1,102 @@
+// M1 test — guidForAsset SSOT (AC-13).
+//
+// Verifies the new AssetRegistry.guidForAsset @internal method:
+//   (a) catalogued asset returns correct GUID string
+//   (b) uncatalogued asset returns undefined
+//   (c) multiple distinct assets each return their correct GUID
+//
+// TDD phase "red": guidForAsset does not exist yet.
+
+import { type Asset, AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+// Minimal payloads keyed by GUID to build the catalog.
+// Use kinds that bypass catalog() validation (skeleton / scene / equirect
+// have no mandatory fields like mesh vertices).
+function makePayload(kind: Asset['kind']): Asset {
+  return { kind } as Asset;
+}
+
+describe('guidForAsset — AC-13 SSOT', () => {
+  it('returns the correct GUID string for a single catalogued asset', () => {
+    const reg = makeRegistry();
+    const asset = makePayload('skeleton');
+    const guid = AssetGuid.parse('a0000000-a000-0000-0000-000000000001');
+    if (!guid.ok) throw new Error('guid parse failed');
+    reg.catalog(guid.value, asset);
+
+    const result = reg._guidForAsset(asset);
+    expect(result).toBe(AssetGuid.format(guid.value));
+  });
+
+  it('returns undefined for an uncatalogued asset', () => {
+    const reg = makeRegistry();
+    const asset = makePayload('equirect');
+
+    const result = reg._guidForAsset(asset);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns the correct GUID for each of multiple distinct assets', () => {
+    const reg = makeRegistry();
+    const assetA = makePayload('skeleton');
+    const assetB = makePayload('scene');
+    const assetC = makePayload('equirect');
+
+    const guidA = AssetGuid.parse('a0000000-a000-0000-0000-000000000001');
+    const guidB = AssetGuid.parse('b0000000-b000-0000-0000-000000000002');
+    const guidC = AssetGuid.parse('c0000000-c000-0000-0000-000000000003');
+    if (!guidA.ok || !guidB.ok || !guidC.ok) throw new Error('guid parse failed');
+
+    reg.catalog(guidA.value, assetA);
+    reg.catalog(guidB.value, assetB);
+    reg.catalog(guidC.value, assetC);
+
+    expect(reg._guidForAsset(assetA)).toBe(AssetGuid.format(guidA.value));
+    expect(reg._guidForAsset(assetB)).toBe(AssetGuid.format(guidB.value));
+    expect(reg._guidForAsset(assetC)).toBe(AssetGuid.format(guidC.value));
+  });
+
+  it('returns undefined when the registry is empty', () => {
+    const reg = makeRegistry();
+    const asset = makePayload('skeleton');
+    expect(reg._guidForAsset(asset)).toBeUndefined();
+  });
+
+  it('uses payload identity (===), not structural equality', () => {
+    const reg = makeRegistry();
+    // Two distinct objects with the same shape — only the catalogued one matches
+    const catalogued = makePayload('skeleton');
+    const lookalike = makePayload('skeleton');
+
+    const guid = AssetGuid.parse('a0000000-a000-0000-0000-000000000001');
+    if (!guid.ok) throw new Error('guid parse failed');
+    reg.catalog(guid.value, catalogued);
+
+    expect(reg._guidForAsset(catalogued)).toBe(AssetGuid.format(guid.value));
+    // lookalike is a different object — should not match
+    expect(reg._guidForAsset(lookalike)).toBeUndefined();
+  });
+
+  it('finds the correct GUID when multiple assets of the same kind are catalogued', () => {
+    const reg = makeRegistry();
+    const asset1 = makePayload('skeleton');
+    const asset2 = makePayload('skeleton');
+
+    const guid1 = AssetGuid.parse('a0000000-a000-0000-0000-000000000001');
+    const guid2 = AssetGuid.parse('b0000000-b000-0000-0000-000000000002');
+    if (!guid1.ok || !guid2.ok) throw new Error('guid parse failed');
+
+    reg.catalog(guid1.value, asset1);
+    reg.catalog(guid2.value, asset2);
+
+    expect(reg._guidForAsset(asset1)).toBe(AssetGuid.format(guid1.value));
+    expect(reg._guidForAsset(asset2)).toBe(AssetGuid.format(guid2.value));
+  });
+});

package/src/__tests__/handle-migration.test.ts

@@ -0,0 +1,136 @@
+// M5 w18: unit tests verifying M5 site migration correctness.
+// - GPU store Map key uses handleSlot (not unwrapHandle) — AC-09.
+// - Tier judgment: gen>0 user handles route to world.sharedRefs.resolve,
+//   not BuiltinAssetRegistry.
+// - Builtin handles (gen=0) still route to BuiltinAssetRegistry.resolve.
+//
+// biome-ignore-all lint/suspicious/noExplicitAny: test seams accessing
+// private store fields + raw Handle casts via pack().
+
+import {
+  BuiltinAssetRegistry,
+  HANDLE_CUBE,
+  resolveAssetHandle,
+} from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { handleSlot, pack } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+
+describe('M5 handle-migration', () => {
+  describe('GPU store Map key uses handleSlot (AC-09)', () => {
+    it('textureGpuHandles: slot-based key — gen>0 and gen=0 for same slot hit same entry', () => {
+      const store = new GpuResidencyCache();
+      const slot = 1050;
+      const mockGpuTexture = { isDestroyed: false, destroy: () => ({ ok: true }) } as any;
+      const mockEntry = { texture: mockGpuTexture, view: undefined };
+      (store as any).textureGpuHandles.set(slot, mockEntry);
+
+      const h0 = pack(slot, 0) as any;
+      const h5 = pack(slot, 5) as any;
+
+      expect((store as any).textureGpuHandles.get(handleSlot(h0))).toBe(mockEntry);
+      expect((store as any).textureGpuHandles.get(handleSlot(h5))).toBe(mockEntry);
+    });
+
+    it('meshGpuHandles: slot-based key — different gen handles hit same entry', () => {
+      const store = new GpuResidencyCache();
+      const slot = 1055;
+      const mockEntry = {
+        vertexBuffer: { isDestroyed: false, destroy: () => ({ ok: true }) },
+        indexBuffer: null,
+        vboBytes: 0,
+        iboBytes: 0,
+        indexCount: 0,
+        indexFormat: 'uint16' as const,
+        layout: '12F' as const,
+        vertexCount: 0,
+        indexed: false,
+        topology: 'triangle-list' as const,
+        submeshes: [],
+      };
+      (store as any).meshGpuHandles.set(slot, mockEntry);
+
+      const h0 = pack(slot, 0) as any;
+      const h7 = pack(slot, 7) as any;
+
+      expect((store as any).meshGpuHandles.get(handleSlot(h0))).toBe(mockEntry);
+      expect((store as any).meshGpuHandles.get(handleSlot(h7))).toBe(mockEntry);
+    });
+
+    it('cubemapGpuHandles: slot-based key — different gen handles hit same cubemap entry', () => {
+      const store = new GpuResidencyCache();
+      const slot = 1060;
+      const mockEntry = {
+        texture: { isDestroyed: false, destroy: () => ({ ok: true }) },
+        view: undefined,
+        faceViews: undefined,
+      };
+      (store as any).cubemapGpuHandles.set(slot, mockEntry);
+
+      const h0 = pack(slot, 0) as any;
+      const h3 = pack(slot, 3) as any;
+
+      expect((store as any).cubemapGpuHandles.get(handleSlot(h0))).toBe(mockEntry);
+      expect((store as any).cubemapGpuHandles.get(handleSlot(h3))).toBe(mockEntry);
+    });
+
+    it('delete path uses handleSlot — gen>0 eviction removes entry stored under slot key', () => {
+      const store = new GpuResidencyCache();
+      const slot = 1070;
+      const mockGpuTexture = { isDestroyed: false, destroy: () => ({ ok: true }) } as any;
+      const mockEntry = { texture: mockGpuTexture, view: undefined };
+      (store as any).textureGpuHandles.set(slot, mockEntry);
+
+      const h = pack(slot, 9) as any;
+      store.evictTexture(h);
+      expect((store as any).textureGpuHandles.get(slot)).toBeUndefined();
+    });
+  });
+
+  describe('tier judgment: resolveAssetHandle routes correctly', () => {
+    it('gen=0 builtin handle routes to BuiltinAssetRegistry.resolve', () => {
+      const result = resolveAssetHandle(new World(), HANDLE_CUBE as any);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.value).toBeDefined();
+        expect(BuiltinAssetRegistry.resolve(HANDLE_CUBE as any)).toBe(result.value);
+      }
+    });
+
+    it('gen>0 user handle routes to world.sharedRefs.resolve', () => {
+      const world = new World();
+      const h = world.allocSharedRef('MeshAsset', {
+        kind: 'mesh',
+        vertices: new Float32Array([0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0]),
+        indices: new Uint16Array([0, 1, 2]),
+        submeshes: [{ indexOffset: 0, indexCount: 3, topology: 'triangle-list' }],
+      } as any);
+      const result = resolveAssetHandle(world, h as any);
+      expect(result.ok).toBe(true);
+    });
+
+    it('gen>0 builtin-slot handle routed via BuiltinAssetRegistry (slot < BUILTIN_BASE)', () => {
+      const h = pack(1, 5) as any;
+      const builtin = BuiltinAssetRegistry.resolve(h);
+      expect(builtin).toBeDefined();
+    });
+
+    it('stale gen>0 handle returns shared-ref-stale error from resolveAssetHandle (AC-10)', () => {
+      const world = new World();
+      const fresh = world.allocSharedRef('MeshAsset', {
+        kind: 'mesh',
+        vertices: new Float32Array([0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0]),
+        indices: new Uint16Array([0, 1, 2]),
+        submeshes: [{ indexOffset: 0, indexCount: 3, topology: 'triangle-list' }],
+      } as any);
+      const slot = handleSlot(fresh as any);
+      const stale = pack(slot, 7) as any;
+      const result = resolveAssetHandle(world, stale);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('shared-ref-stale');
+      }
+    });
+  });
+});

package/src/__tests__/helpers/register-runtime-components.ts

@@ -15,13 +15,15 @@ import {
   Skylight,
   SortKey,
   SpotLight,
+  Visibility,
+} from '@forgeax/engine-render';
+import {
   SpriteAnimation,
   SpriteInstances,
   SpriteRegionOverride,
   TileLayer,
   Tilemap,
-  Visibility,
-} from '@forgeax/engine-render/internal';
+} from '@forgeax/engine-render/authoring';
 import { ChildOf, Children, MorphWeights, Name, Transform } from '@forgeax/engine-scene';
 
 const RUNTIME_COMPONENTS: readonly Component[] = [

package/src/__tests__/helpers/register-scene-components.ts

@@ -1,5 +1,5 @@
 import type { Component, World } from '@forgeax/engine-ecs';
-import { SceneInstance } from '@forgeax/engine-render/internal';
+import { SceneInstance } from '@forgeax/engine-render';
 import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
 
 /** Register the scene vocabulary explicitly for an isolated test World. */

package/src/__tests__/host-custom-kind-contract.test-d.ts

@@ -0,0 +1,47 @@
+// feat-20260623 M4 / w15 -- AC-08 type-level evidence: host custom kind
+// loadByGuid<MyPayload> returns the exact payload type (not Asset, not unknown).
+// This is type-level auxiliary evidence only; the real AC-08 gate is the
+// consumption path in w13/w14 contract tests (no `as` casts on the returned
+// value after unwrapping). Simulator will verify in step-verify.
+//
+// Charter: proposition 4 (explicit failure over silent) -- Result<T, E> shape.
+
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+// ── host-defined custom payload type (NOT in Asset union) ────────────
+
+interface MyGameConfig {
+  kind: string;
+  title: string;
+  resolution: { width: number; height: number };
+  players: number;
+}
+
+// ── AC-08 type-level assertions ──────────────────────────────────────
+
+describe('AC-08 -- loadByGuid<MyPayload> type narrowing', () => {
+  it('Result<MyGameConfig, E>.value on success is exactly MyGameConfig', () => {
+    // The success arm of Result<MyGameConfig, ...> carries MyGameConfig,
+    // not Asset or unknown. The contract test (w13/w14) consumes this
+    // signature without `as` casts.
+    type SuccessValue = Extract<Result<MyGameConfig, { code: string }>, { ok: true }>['value'];
+    expectTypeOf<SuccessValue>().toEqualTypeOf<MyGameConfig>();
+  });
+
+  it('MyGameConfig is structurally distinct from Asset members', () => {
+    // MyGameConfig has 'title' / 'resolution' / 'players' fields --
+    // none of the 14 engine Asset union members carry these. The type
+    // checker enforces structural distinctness automatically.
+    const cfg: MyGameConfig = {
+      kind: 'my-game-config',
+      title: 'Test',
+      resolution: { width: 800, height: 600 },
+      players: 2,
+    };
+    // Compile-time: if MyGameConfig were a member of Asset, this
+    // assignment would have a wider type. The test-d existence alone
+    // proves MyGameConfig is NOT in the union -- see typecheck gate.
+    void cfg;
+  });
+});