@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/renderer-result.test-d.ts

@@ -7,20 +7,30 @@
 // Anchors: requirements AC-13 (Renderer.draw/ready Result form);
 //          plan-strategy D-P7 break-point #4; w23 test SSOT.
 
-import type { Renderer, RenderResult } from '@forgeax/engine-render/internal';
-import type { RhiError } from '@forgeax/engine-rhi';
+import type {
+  FrameReceipt,
+  RenderError,
+  Renderer,
+  RenderFrameInput,
+  RenderResult,
+  RenderWorldLease,
+} from '@forgeax/engine-render';
 import { describe, expectTypeOf, it } from 'vitest';
 
-describe('AC-13 — Renderer.draw returns Result<void, RhiError>', () => {
-  it('Renderer.draw(world) return type is Result<void, RhiError>', () => {
+describe('M6 — Renderer.draw returns Result<FrameReceipt, RenderError>', () => {
+  it('Renderer.draw(request) return type is Result<FrameReceipt, RenderError>', () => {
     type RetType = ReturnType<Renderer['draw']>;
-    expectTypeOf<RetType>().toEqualTypeOf<RenderResult<void, RhiError>>();
+    expectTypeOf<RetType>().toEqualTypeOf<RenderResult<FrameReceipt, RenderError>>();
   });
 });
 
-describe('AC-13 — Renderer.ready is Promise<Result<void, RhiError>>', () => {
-  it('Renderer.ready type is Promise<Result<void, RhiError>>', () => {
-    type ReadyType = Renderer['ready'];
-    expectTypeOf<ReadyType>().toEqualTypeOf<Promise<RenderResult<void, RhiError>>>();
+describe('M6 — Renderer.attach returns a lease and draw consumes it', () => {
+  it('Renderer.attach returns RenderWorldLease and draw consumes RenderFrameInput', () => {
+    type AttachType = Renderer['attach'];
+    type DrawArg = Parameters<Renderer['draw']>[0];
+    expectTypeOf<AttachType>().returns.toEqualTypeOf<
+      RenderResult<RenderWorldLease, import('@forgeax/engine-render').RenderError>
+    >();
+    expectTypeOf<DrawArg>().toEqualTypeOf<RenderFrameInput>();
   });
 });

package/src/__tests__/renderer-surface.unit.test.ts

@@ -6,14 +6,15 @@
 //
 // Tests drive recordFrame() directly with mock internals. All mock objects
 // are typed through `any` to avoid constructing full RhiDevice / PipelineState /
-// AssetRegistry / GpuResourceStore objects (each is ~50+ fields with branded
+// AssetRegistry / GpuResidencyCache objects (each is ~50+ fields with branded
 // opaque types). The test surface is the recordFrame function — verify that
 // getCurrentTexture failure triggers reconfigure+retry and that consecutive
 // failures escalate to health internal-fault.
 
-import { acquireSwapChainTarget, HealthListenerRegistry } from '@forgeax/engine-render/internal';
 import { RhiError } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
+import { HealthListenerRegistry } from '../../../render/src/lifecycle';
+import { acquireSwapChainTarget } from '../../../render/src/record/frame-targets';
 
 // biome-ignore lint/suspicious/noExplicitAny: mock objects are intentionally opaque in test code
 type MockObj = Record<string, any>;
@@ -24,9 +25,6 @@ function makePipelineState(): MockObj {
     format: 'bgra8unorm',
     colorAttachmentFormat: 'bgra8unorm-srgb',
     standardPipeline: { __brand: 'RP' },
-    standardPipelineHdr: { __brand: 'RP' },
-    standardPipelineMsaa: { __brand: 'RP' },
-    standardPipelineHdrMsaa: { __brand: 'RP' },
     unlitPipeline: { __brand: 'RP' },
     unlitPipelineHdr: { __brand: 'RP' },
     unlitPipelineMsaa: { __brand: 'RP' },

package/src/__tests__/renderer-test-utils.ts

@@ -0,0 +1,56 @@
+import type { World } from '@forgeax/engine-ecs';
+import type {
+  FrameReceipt,
+  RenderError,
+  Renderer,
+  RenderResult,
+  RenderWorldLease,
+} from '@forgeax/engine-render';
+import { createRenderer } from '../createRenderer';
+
+export async function requireRenderer(
+  ...args: Parameters<typeof createRenderer>
+): Promise<Renderer> {
+  const result = await createRenderer(...args);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+const leasesByRenderer = new WeakMap<Renderer, Map<World, RenderWorldLease>>();
+
+/** Adapt pre-lease multi-world fixtures to the public frame input contract. */
+export function drawWithOwners(
+  renderer: Renderer,
+  worldsOrWorld: World | readonly World[],
+  options: { readonly cameraOwner?: number; readonly resourceOwner?: number } = {},
+): RenderResult<FrameReceipt, RenderError> {
+  const worlds = Array.isArray(worldsOrWorld) ? worldsOrWorld : [worldsOrWorld];
+  let leases = leasesByRenderer.get(renderer);
+  if (leases === undefined) {
+    leases = new Map();
+    leasesByRenderer.set(renderer, leases);
+  }
+  const attached = worlds.map((world) => {
+    const existing = leases.get(world);
+    if (existing !== undefined) return existing;
+    const result = renderer.attach(world);
+    if (!result.ok) throw result.error;
+    leases.set(world, result.value);
+    return result.value;
+  });
+  const camera = worlds[options.cameraOwner ?? 0];
+  const environment = worlds[options.resourceOwner ?? 0];
+  if (camera === undefined || environment === undefined) {
+    throw new Error('drawWithOwners requires cameraOwner/resourceOwner worlds');
+  }
+  const cameraLease = leases.get(camera);
+  const environmentLease = leases.get(environment);
+  if (cameraLease === undefined || environmentLease === undefined) {
+    throw new Error('drawWithOwners failed to attach owner worlds');
+  }
+  return renderer.draw({
+    leases: attached,
+    camera: { lease: cameraLease },
+    environment: { lease: environmentLease },
+  });
+}

package/src/__tests__/renderer.test-d.ts

@@ -0,0 +1,59 @@
+// Renderer public-surface and event-contract type assertions.
+
+import type { RenderError, Renderer, RendererEvent } from '@forgeax/engine-render';
+
+type RendererEventListener = (event: RendererEvent) => void;
+
+import type {
+  // @ts-expect-error - BundlerOptions is an internal construct seam
+  BundlerOptions as _BundlerOptionsRemoved,
+  // @ts-expect-error - ConsoleHandle must not be exported from @forgeax/engine-runtime
+  ConsoleHandle as _ConsoleHandleRemoved,
+  // @ts-expect-error - StartConsoleOptions must not be exported from @forgeax/engine-runtime
+  StartConsoleOptions as _StartConsoleOptionsRemoved,
+} from '@forgeax/engine-runtime';
+import { describe, expectTypeOf, it } from 'vitest';
+
+type _UnusedSink = _StartConsoleOptionsRemoved | _ConsoleHandleRemoved | _BundlerOptionsRemoved;
+
+describe('Renderer public surface', () => {
+  it('does not expose removed console or legacy listener members', () => {
+    // @ts-expect-error - startConsole is internal to the runtime host
+    type _StartConsoleAbsent = Renderer['startConsole'];
+    // @ts-expect-error - onLost was replaced by subscribe(RendererEventListener)
+    type _OnLostAbsent = Renderer['onLost'];
+    // @ts-expect-error - onError was replaced by subscribe(RendererEventListener)
+    type _OnErrorAbsent = Renderer['onError'];
+    void (undefined as unknown as _StartConsoleAbsent | _OnLostAbsent | _OnErrorAbsent);
+
+    type RendererKey = keyof Renderer;
+    expectTypeOf<'attach'>().toExtend<RendererKey>();
+    expectTypeOf<'draw'>().toExtend<RendererKey>();
+    expectTypeOf<'dispose'>().toExtend<RendererKey>();
+    expectTypeOf<'subscribe'>().toExtend<RendererKey>();
+    expectTypeOf<'observe'>().toExtend<RendererKey>();
+  });
+});
+
+describe('subscribe projects the discriminated Renderer event contract', () => {
+  it('passes RendererEvent and exposes RenderError on the error arm', () => {
+    expectTypeOf<RendererEventListener>().parameter(0).toEqualTypeOf<RendererEvent>();
+    type ErrorEvent = Extract<RendererEvent, { readonly kind: 'error' }>;
+    expectTypeOf<ErrorEvent['error']>().toEqualTypeOf<RenderError>();
+  });
+
+  it('keeps state changes and errors exhaustively distinguishable', () => {
+    const describeEvent = (event: RendererEvent): string => {
+      switch (event.kind) {
+        case 'state-changed':
+          return `${event.previous}->${event.current}`;
+        case 'error':
+          return event.error.code;
+      }
+    };
+    expectTypeOf(describeEvent).returns.toEqualTypeOf<string>();
+  });
+});
+
+declare const __sink: _UnusedSink | undefined;
+void __sink;

package/src/__tests__/resolve-asset-handle-err.test.ts

@@ -0,0 +1,111 @@
+// M5 w19: Type-level verification that resolveAssetHandle return type
+// includes stale error codes and supports exhaustive switch.
+//
+// AC-10: adding a new stale error code reachable from resolve-asset-handle.ts
+// will cause tsc to fail, serving as a regression guard.
+//
+// Note: uses `shared-ref-stale` as an instanceof-tested guard in a switch
+// that must handle all AssetErrorCode members WITHOUT a default case.
+// Because vitest typecheck.enabled is not set in runtime, we verify the
+// structural type inclusion via instanceof narrowing paths.
+//
+// biome-ignore-all lint/suspicious/noExplicitAny: type-level extract + test seams
+
+// Type-level re-export to verify stale error codes appear in resolveAssetHandle
+// return type. The return type is `Result<T, AssetErrorType | SharedRefStaleError | UniqueRefStaleError>`.
+// This test verifies structural narrowing works.
+import type { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { describe, expect, it } from 'vitest';
+
+// Extract the Error union from resolveAssetHandle return type at the
+// type level — this is a compile-time assertion.
+type ResolveErrCode =
+  Extract<ReturnType<typeof resolveAssetHandle<any>>, { ok: false }> extends {
+    error: infer E extends { code: string };
+  }
+    ? E['code']
+    : never;
+
+describe('resolveAssetHandle AC-10 stale error forwarding type gate', () => {
+  it('return type error union includes shared-ref-stale (compile-time)', () => {
+    // If shared-ref-stale is NOT in the union, the assignment below fails at tsc.
+    const _c1: ResolveErrCode = 'shared-ref-stale' as const;
+    void _c1;
+    expect(true).toBe(true);
+  });
+
+  it('return type error union includes unique-ref-stale (compile-time)', () => {
+    const _c2: ResolveErrCode = 'unique-ref-stale' as const;
+    void _c2;
+    expect(true).toBe(true);
+  });
+
+  it('return type error union includes asset-not-found (compile-time)', () => {
+    const _c3: ResolveErrCode = 'asset-not-found' as const;
+    void _c3;
+    expect(true).toBe(true);
+  });
+
+  it('exhaustive switch over AssetErrorCode (runtime guard for AC-10)', () => {
+    // A real consumer pattern: switch over all AssetErrorCode members plus
+    // the stale codes forwarded by resolveAssetHandle. This is a runtime
+    // test that the switch compiles — if a code is missing, tsc errors.
+    function mapErrorCode(code: string): string {
+      switch (code) {
+        case 'asset-not-found':
+          return 'NOT_FOUND';
+        case 'asset-parse-failed':
+          return 'PARSE';
+        case 'asset-format-unsupported':
+          return 'FORMAT';
+        case 'asset-fetch-failed':
+          return 'FETCH';
+        case 'asset-invalid-value':
+          return 'INVALID';
+        case 'cubemap-handle-missing':
+          return 'CUBEMAP';
+        case 'invalid-source-format':
+          return 'SRC_FORMAT';
+        case 'load-failed':
+          return 'LOAD';
+        case 'device-unsupported':
+          return 'DEVICE';
+        case 'ibl-precompute-not-dispatched':
+          return 'IBL';
+        case 'mesh-vertex-stride-mismatch':
+          return 'STRIDE';
+        case 'material-shader-ref-broken':
+          return 'SHADER_REF';
+        case 'material-circular-inheritance':
+          return 'CIRCULAR';
+        case 'loader-not-registered':
+          return 'LOADER';
+        case 'asset-not-imported':
+          return 'NOT_IMPORTED';
+        case 'texture-source-not-imported':
+          return 'TEX_NOT_IMPORTED';
+        case 'mesh-renderer-material-count-mismatch':
+          return 'MAT_COUNT';
+        case 'mesh-asset-submeshes-empty':
+          return 'SUBMESH_EMPTY';
+        case 'mesh-submesh-index-range-out-of-bounds':
+          return 'SUBMESH_OOB';
+        case 'tileset-region-index-out-of-range':
+          return 'TILESET_OOB';
+        case 'tileset-tile-entry-malformed':
+          return 'TILESET_MALFORMED';
+        case 'asset-invalidated':
+          return 'INVALIDATED';
+        // AC-10: stale error codes forwarded by resolveAssetHandle.
+        case 'shared-ref-stale':
+          return 'STALE_SHARED';
+        case 'unique-ref-stale':
+          return 'STALE_UNIQUE';
+      }
+      throw new Error(`Unhandled error code: ${code}`);
+    }
+    expect(mapErrorCode('shared-ref-stale')).toBe('STALE_SHARED');
+    expect(mapErrorCode('unique-ref-stale')).toBe('STALE_UNIQUE');
+    expect(mapErrorCode('asset-not-found')).toBe('NOT_FOUND');
+  });
+});

package/src/__tests__/resolve-asset-handle.unit.test.ts

@@ -0,0 +1,64 @@
+// M7 w55 / M8 w59: resolveAssetHandle two-tier dispatch unit test.
+//
+// D-15 two-tier asset resolution: resolveAssetHandle(world, handle) dispatches
+// by slot range — builtin slots (< BUILTIN_BASE) resolve through
+// BuiltinAssetRegistry.resolve (process-static, no World needed); user-tier
+// slots (>= BUILTIN_BASE) resolve through world.sharedRefs (minted via
+// world.allocSharedRef). The AssetRegistry holds no handle->payload map.
+
+import { BUILTIN_CUBE, HANDLE_CUBE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function mesh(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array([0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1]),
+    indices: new Uint16Array([0]),
+    attributes: {},
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 1,
+        vertexCount: 12,
+        topology: 'triangle-list' as const,
+      },
+    ],
+  } as unknown as MeshAsset;
+}
+
+describe('resolveAssetHandle two-tier slot-range dispatch (AC-31)', () => {
+  it('builtin slot (< BUILTIN_BASE): resolves through BuiltinAssetRegistry', () => {
+    // HANDLE_CUBE has slot=1 < BUILTIN_BASE=1024.
+    // Builtins are process-static — the World is unused for this path.
+    const world = new World();
+    const res = resolveAssetHandle(world, HANDLE_CUBE);
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toBe(BUILTIN_CUBE);
+  });
+
+  it('user-tier slot (>= BUILTIN_BASE): resolves through world.sharedRefs', () => {
+    // User-tier payloads live in the per-World SharedRefStore, minted via
+    // world.allocSharedRef. resolveAssetHandle routes user-tier slots there.
+    const world = new World();
+    const payload = mesh();
+    const handle = world.allocSharedRef('MeshAsset', payload);
+    expect(handle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+    const res = resolveAssetHandle<MeshAsset>(world, handle);
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toBe(payload);
+  });
+
+  it('user-tier handle not in this World returns asset-not-found', () => {
+    // A handle minted in a DIFFERENT world is absent from this world's
+    // SharedRefStore — resolveAssetHandle must return err(asset-not-found).
+    const world = new World();
+    const foreign = new World();
+    const foreignHandle = foreign.allocSharedRef('MeshAsset', mesh());
+    const res = resolveAssetHandle(world, foreignHandle);
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.error.code).toBe('asset-not-found');
+  });
+});

package/src/__tests__/resolve-depth-only-view.test.ts

@@ -31,7 +31,7 @@ await vi.hoisted(async () => {
 
 // Import the render-graph-primitives module to extract the functions under test.
 // We can reach them through the resolved module namespace.
-const mod = await import('@forgeax/engine-render/internal');
+const mod = await import('../../../render/src/render-graph-primitives');
 // resolveDepthOnlyView is exported; resolveHdrDepthDepthOnlyView is not.
 // We can test the delegate equivalence by calling resolveDepthOnlyView with
 // the SSAO label, which is the exact body of the delegate.

package/src/__tests__/resolveName-fallback.test.ts

@@ -0,0 +1,64 @@
+// AC-15 deterministic name fallback — runtime integration (feat-20260618 w19).
+//
+// deriveAssetName's branch logic is unit-tested in @forgeax/engine-pack (w8);
+// this test exercises the runtime wiring (resolveName passing the right args).
+//
+// Coverage:
+//   AC-15.1 — multi-asset package entry with no stored name -> basename(path),
+//             no throw (old add-only packs are a reachable state).
+//   AC-15.2 — null package with no stored name -> '' (the detectable
+//             "genuinely no name" signal), no throw.
+//   D-5     — builtin meshes resolve to '' (null package, no name).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const MULTI_A = 'e0000000-0000-4000-e000-000000000001';
+const MULTI_B = 'e0000000-0000-4000-e000-000000000002';
+const NO_PKG = 'e0000000-0000-4000-e000-000000000003';
+// Builtin cube GUID -- the constructor registers it with a null package (D-5).
+const BUILTIN_CUBE_GUID = 'cbe42beb-8975-5096-b3a1-3dda4cb4c077';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('resolveName deterministic fallback (AC-15)', () => {
+  it('AC-15.1 multi-asset entry with no stored name falls back to basename', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A), sampler);
+    reg.catalog(parseGuid(MULTI_B), sampler);
+    // Only MULTI_A carries a name; MULTI_B has none (old add-only pack).
+    reg._registerPackage('assets/world.glb', [MULTI_A, MULTI_B], new Map([[MULTI_A, 'Ground']]));
+
+    expect(() => reg.resolveName(MULTI_B)).not.toThrow();
+    expect(reg.resolveName(MULTI_B)).toBe('world.glb');
+    expect(reg.resolveName(MULTI_A)).toBe('Ground');
+  });
+
+  it('AC-15.2 null package with no name resolves to empty string', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(NO_PKG), sampler);
+    reg._registerPackage(null, [NO_PKG]);
+
+    expect(() => reg.resolveName(NO_PKG)).not.toThrow();
+    expect(reg.resolveName(NO_PKG)).toBe('');
+  });
+
+  it('D-5 builtin mesh resolves to empty string (null package, no name)', () => {
+    const reg = makeRegistry();
+    expect(reg.packageOf(BUILTIN_CUBE_GUID)).toBe(null);
+    expect(reg.resolveName(BUILTIN_CUBE_GUID)).toBe('');
+  });
+});

package/src/__tests__/resolveName-null-package.test.ts

@@ -0,0 +1,38 @@
+// resolveName null package — AC-03 (feat-20260618 w17).
+//
+// Red-first: written before w10 implements resolveName.
+//
+// Coverage:
+//   AC-03 — no-package asset: packageOf(guid) === null, resolveName returns the
+//           stored self name, and no synthetic guid path is minted (OOS-3).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const NO_PKG_GUID = 'b0000000-0000-4000-b000-000000000001';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('resolveName null package (AC-03)', () => {
+  it('packageOf is null, resolveName returns the stored name, no synthetic path', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(NO_PKG_GUID), sampler);
+    reg._registerPackage(null, [NO_PKG_GUID], new Map([[NO_PKG_GUID, 'myProcMesh']]));
+
+    expect(reg.packageOf(NO_PKG_GUID)).toBe(null);
+    expect(reg.resolveName(NO_PKG_GUID)).toBe('myProcMesh');
+  });
+});

package/src/__tests__/resolveName-unified-entry.test.ts

@@ -0,0 +1,65 @@
+// AC-04 unified name resolution — single source of truth, no bypass (feat-20260618 w18).
+//
+// resolveName is the one runtime name-truth function and it delegates to the
+// stateless deriveAssetName pure function (D-6). Every other name consumer reads
+// resolveName or that same deriveAssetName -- none re-implements the XOR rule.
+//
+// This is a grep/fixture test, not a pure runtime assertion: it reads the source
+// trees and asserts structural unification.
+//
+// M4 (w24/w22) wiring completed: inspect() now calls resolveName; the catalog
+// builder now calls deriveAssetName. The grep assertions below confirm both
+// paths route through the SSOT, no bypass.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const registrySrc = readFileSync(`${here}../../../assets-runtime/src/asset-registry.ts`, 'utf8');
+const deriveSrc = readFileSync(
+  fileURLToPath(new URL('../../../pack/src/deriveAssetName.ts', import.meta.url)),
+  'utf8',
+);
+const buildCatalogSrc = readFileSync(
+  fileURLToPath(new URL('../../../pack/src/catalog-builder.ts', import.meta.url)),
+  'utf8',
+);
+
+describe('unified name resolution (AC-04)', () => {
+  it('deriveAssetName is the single XOR rule definition', () => {
+    expect(deriveSrc).toContain('export function deriveAssetName');
+  });
+
+  it('resolveName delegates to deriveAssetName (no inline XOR re-implementation)', () => {
+    expect(registrySrc).toContain("import { deriveAssetName } from '@forgeax/engine-pack/name'");
+    // resolveName returns the result of deriveAssetName, not a hand-rolled rule.
+    const body = registrySrc.slice(
+      registrySrc.indexOf('resolveName(guid: AssetGuid | string): string'),
+    );
+    const fnBody = body.slice(0, body.indexOf('\n  }'));
+    expect(fnBody).toContain('return deriveAssetName(');
+  });
+
+  it('resolveName is the only public name accessor on the registry (no sibling getName)', () => {
+    expect(registrySrc).not.toMatch(/\n {2}getName\(/);
+    expect(registrySrc).not.toMatch(/\n {2}displayName\(/);
+  });
+
+  // M4 expansion (w24 landed): inspect() routes through resolveName
+  it('inspect() calls resolveName per entry (M4 w24 wiring)', () => {
+    // inspect() pushes { name: this.resolveName(guid) } -- no inline basename
+    expect(registrySrc).toContain('name: this.resolveName(guid)');
+    // No hardcoded '' placeholder left from M1/w3
+    expect(registrySrc).not.toContain("name: ''");
+  });
+
+  // M4 expansion (w22 landed): catalog-builder routes through deriveAssetName
+  it('catalog-builder imports and calls deriveAssetName (no inline XOR)', () => {
+    expect(buildCatalogSrc).toContain("import { deriveAssetName } from './deriveAssetName.js'");
+    expect(buildCatalogSrc).toContain('deriveAssetName(');
+    // No inline re-implementation of the XOR rule (no hand-rolled basename)
+    // The single deriveAssetName pure function handles all branches.
+    expect(buildCatalogSrc.match(/deriveAssetName\(/g)?.length ?? 0).toBeGreaterThanOrEqual(2);
+  });
+});

package/src/__tests__/resolveName.test.ts

@@ -0,0 +1,64 @@
+// resolveName single / multi asset package — AC-01 + AC-02 (feat-20260618 w16).
+//
+// Red-first: written before w10 implements resolveName. Constructs the package
+// state directly through registerPackage (Risk-2: no pack-index fetch needed).
+//
+// Coverage:
+//   AC-01 — single-asset package: resolveName === basename(path); the stored
+//           Asset POD carries no `name` property (name is never on the payload).
+//   AC-02 — multi-asset package: resolveName returns each entry's stored name.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const SINGLE_GUID = 'a0000000-0000-4000-a000-000000000001';
+const MULTI_A_GUID = 'a0000000-0000-4000-a000-000000000002';
+const MULTI_B_GUID = 'a0000000-0000-4000-a000-000000000003';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('resolveName single-asset package (AC-01)', () => {
+  it('returns basename(path) and the POD has no name property', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(SINGLE_GUID), sampler);
+    reg._registerPackage('assets/hero.glb', [SINGLE_GUID]);
+
+    expect(reg.resolveName(SINGLE_GUID)).toBe('hero.glb');
+
+    const stored = reg.lookup(SINGLE_GUID);
+    expect(stored).toBeDefined();
+    expect(Object.hasOwn(stored as object, 'name')).toBe(false);
+  });
+});
+
+describe('resolveName multi-asset package (AC-02)', () => {
+  it('returns each entry stored name', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A_GUID), sampler);
+    reg.catalog(parseGuid(MULTI_B_GUID), sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [MULTI_A_GUID, MULTI_B_GUID],
+      new Map([
+        [MULTI_A_GUID, 'Body'],
+        [MULTI_B_GUID, 'Head'],
+      ]),
+    );
+
+    expect(reg.resolveName(MULTI_A_GUID)).toBe('Body');
+    expect(reg.resolveName(MULTI_B_GUID)).toBe('Head');
+  });
+});