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

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

@@ -0,0 +1,414 @@
+// @forgeax/engine-runtime — surface retry unit tests
+//
+// Covers:
+//   w5 — F2 surface retry: reconfigure + retry once, frame continues (AC-03)
+//   w6 — F2 surface consecutive failure -> internal-fault (AC-04)
+//
+// Tests drive recordFrame() directly with mock internals. All mock objects
+// are typed through `any` to avoid constructing full RhiDevice / PipelineState /
+// 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 { 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>;
+
+function makePipelineState(): MockObj {
+  return {
+    meshes: new Map(),
+    format: 'bgra8unorm',
+    colorAttachmentFormat: 'bgra8unorm-srgb',
+    standardPipeline: { __brand: 'RP' },
+    unlitPipeline: { __brand: 'RP' },
+    unlitPipelineHdr: { __brand: 'RP' },
+    unlitPipelineMsaa: { __brand: 'RP' },
+    unlitPipelineHdrMsaa: { __brand: 'RP' },
+    spritePipeline: { __brand: 'RP' },
+    spritePipelineHdr: { __brand: 'RP' },
+    spritePipelineMsaa: { __brand: 'RP' },
+    spritePipelineHdrMsaa: { __brand: 'RP' },
+    perPassResources: { configured: true },
+    cameraUniformBuffer: { __brand: 'Buf' },
+    lightsUniformBuffer: { __brand: 'Buf' },
+    skyIBLBuffer: { __brand: 'Buf' },
+    meshStorageBuffer: { buffer: { __brand: 'Buf' }, writeBuffer: () => ({ ok: true }) },
+    materialUBOBuffer: { __brand: 'Buf' },
+    shadowParamsBuffer: { __brand: 'Buf' },
+    defaultWhiteTextureView: { __brand: 'TV' },
+    defaultNormalTextureView: { __brand: 'TV' },
+    fallbackTextureView: { __brand: 'TV' },
+    materialBindGroupLayout: { __brand: 'BGL' },
+    meshBindGroupLayout: { __brand: 'BGL' },
+    viewBindGroupLayout: { __brand: 'BGL' },
+    instancesBindGroupLayout: { __brand: 'BGL' },
+    shadowViewBindGroupLayout: { __brand: 'BGL' },
+    standardBindGroup: { __brand: 'BG' },
+    skyboxRenderPipeline: { __brand: 'RP' },
+    skyboxBindGroupLayout: { __brand: 'BGL' },
+    depthStencilState: { format: 'depth24plus-stencil8' },
+    _skinBgCacheStats: { total: 0, capacity: 0 },
+    device: { limits: { maxStorageBuffersPerShaderStage: 0 } },
+    formatBgra8Unorm: 'bgra8unorm',
+    shadowViewBindGroup: { __brand: 'BG' },
+    shadowSampler: { __brand: 'S' },
+    shadowViewTexture: { __brand: 'TV' },
+  };
+}
+
+function makeMockDevice(_ps: MockObj): MockObj {
+  return {
+    __brand: 'Dev',
+    lost: new Promise(() => {}),
+    features: new Set<string>(),
+    // biome-ignore lint/suspicious/noExplicitAny: test mock
+    limits: { maxStorageBuffersPerShaderStage: 0 } as any,
+    queue: { submit: () => undefined, writeBuffer: () => ({ ok: true }) },
+    createBuffer: () => ({ ok: true, value: { __brand: 'Buf' } }),
+    createTexture: () => ({ ok: true, value: { __brand: 'Tex' } }),
+    createBindGroupLayout: () => ({ ok: true, value: { __brand: 'BGL' } }),
+    createBindGroup: () => ({ ok: true, value: { __brand: 'BG' } }),
+    createPipelineLayout: () => ({ ok: true, value: { __brand: 'PL' } }),
+    createRenderPipeline: () => ({ ok: true, value: { __brand: 'RP' } }),
+    createSampler: () => ({ ok: true, value: { __brand: 'S' } }),
+    createShaderModule: () => ({ ok: true, value: { __brand: 'SM' } }),
+    createTextureView: () => ({ ok: true, value: { __brand: 'TV' } }),
+    createCommandEncoder: () => ({
+      ok: true,
+      value: {
+        beginRenderPass: () => ({
+          setPipeline: () => undefined,
+          setBindGroup: () => undefined,
+          setVertexBuffer: () => undefined,
+          setIndexBuffer: () => undefined,
+          draw: () => undefined,
+          drawIndexed: () => undefined,
+          end: () => undefined,
+          setViewport: () => undefined,
+          setScissorRect: () => undefined,
+          setBlendConstant: () => undefined,
+          setStencilReference: () => undefined,
+        }),
+        finish: () => ({ __brand: 'CB' }),
+      },
+    }),
+  };
+}
+
+function makeSurfaceCtx(
+  cfgCalls: { n: number },
+  ctxCalls: { n: number },
+  failCount: number,
+): MockObj {
+  return {
+    configure: () => {
+      cfgCalls.n++;
+      return { ok: true };
+    },
+    unconfigure: () => undefined,
+    getCurrentTexture: () => {
+      ctxCalls.n++;
+      if (ctxCalls.n <= failCount) {
+        return {
+          ok: false,
+          error: new RhiError({ code: 'webgpu-runtime-error', expected: 'failed', hint: 'retry' }),
+        };
+      }
+      return { ok: true, value: { __brand: 'Tex' } };
+    },
+  };
+}
+
+function makeCameras(): MockObj[] {
+  return [
+    {
+      fov: 1,
+      aspect: 1,
+      near: 0.1,
+      far: 100,
+      posX: 0,
+      posY: 0,
+      posZ: 10,
+      quatX: 0,
+      quatY: 0,
+      quatZ: 0,
+      quatW: 1,
+      viewMatrix: new Float32Array(16),
+      projMatrix: new Float32Array(16),
+      clearColor: [0, 0, 0, 1],
+    },
+  ];
+}
+
+function makeLights(): MockObj {
+  return {
+    directional: undefined,
+    directionalCount: 0,
+    point: [],
+    spot: [],
+    lightViewProj: undefined,
+    splitPlanes: undefined,
+    cascadeCount: undefined,
+    cascadeBlendWidth: undefined,
+    cascadeBlend: undefined,
+    csmShadowMapView: undefined,
+    csmShadowAtlasSlot: undefined,
+    csmShadowSplitCount: undefined,
+    csmShadowCascadeCount: undefined,
+    csmActive: false,
+    shadowMapSize: 0,
+    depthBias: 0,
+    normalBias: 0,
+    pcfKernelSize: 0,
+    pointShadow: [],
+  };
+}
+
+function makeFrameState(): MockObj {
+  return {
+    frameNumber: 1,
+    compiledFrameGraph: null,
+    compiledFrameGraphTopologyKey: null,
+    retiredCompiledFrameGraphs: new Set(),
+    instanceBuffers: new Map(),
+    transientInstanceBuffers: [],
+    warnedZeroLightStandard: false,
+    warnedMultiLightDirectional: false,
+    warnedMultiLightPoint: false,
+    warnedMultiLightSpot: false,
+    warnedSkyboxTonemapNone: false,
+    warnedMissingBaseColorTextureHandles: new Set<number>(),
+    warnedNineSliceScaleEntities: new Set<number>(),
+    viewBindGroupCache: new Map(),
+    meshBindGroupCache: new Map(),
+    materialBgCache: new Map(),
+    instancesBgCache: new Map(),
+    handleToId: new WeakMap<object, number>(),
+    nextHandleId: 0,
+    installedPipelineHandle: 0,
+    activePipeline: { buildGraph: () => null, execute: () => undefined },
+    installedPipelineConfig: undefined,
+    isHdrpActive: false,
+    hdrpOncePerFrameFired: new Set(),
+    pointShadowAtlas: null,
+    pointShadowSnapshots: [],
+    lastFoldBucketCount: 0,
+  };
+}
+
+function makeDispatchCounts(): MockObj {
+  return { mainForward: 0, shadowCaster: 0, transparent: 0, skybox: 0, postProcess: 0, unlit: 0 };
+}
+
+function makeBindGroupCounts(): MockObj {
+  return { createBindGroup: 0, keys: [] };
+}
+
+function callRecordFrame(
+  // biome-ignore lint/suspicious/noExplicitAny: mock internals
+  internals: any,
+  // biome-ignore lint/suspicious/noExplicitAny: mock cameras
+  cameras: any,
+  // biome-ignore lint/suspicious/noExplicitAny: mock lights
+  lights: any,
+  // biome-ignore lint/suspicious/noExplicitAny: mock frameState
+  frameState: any,
+  // biome-ignore lint/suspicious/noExplicitAny: mock dispatchCounts
+  dispatchCounts: any,
+  // biome-ignore lint/suspicious/noExplicitAny: mock bindGroupCounts
+  bindGroupCounts: any,
+): void {
+  void cameras;
+  void lights;
+  void frameState;
+  void dispatchCounts;
+  void bindGroupCounts;
+  acquireSwapChainTarget(internals, internals.getPipelineState());
+}
+
+// ── w5: surface retry — reconfigure + retry once (AC-03) ─────────────────────
+
+describe('Surface retry (w5)', () => {
+  it('w5: getCurrentTexture fail-once -> reconfigure -> retry succeeds', () => {
+    const cfgCalls = { n: 0 };
+    const ctxCalls = { n: 0 };
+    const ps = makePipelineState();
+    const reg = new HealthListenerRegistry();
+    const mockCtx = makeSurfaceCtx(cfgCalls, ctxCalls, 1);
+    const dev = makeMockDevice(ps);
+
+    // biome-ignore lint/suspicious/noExplicitAny: test internals
+    const internals: any = {
+      canvas: { width: 800, height: 600 },
+      device: dev,
+      context: mockCtx,
+      getPipelineState: () => ps,
+      assets: { register: () => ({ ok: true }), instantiate: () => ({ ok: true }) },
+      gpuStore: {
+        destroyAll: () => undefined,
+        ensureResident: () => ({ ok: true }),
+        getMeshGpuHandles: () => ({
+          ok: true,
+          value: {
+            indexBuffer: { __brand: 'Buf' },
+            vertexBuffer: { __brand: 'Buf' },
+            indexFormat: 'uint32',
+            indexCount: 0,
+            vertexCount: 0,
+          },
+        }),
+        getTextureView: () => ({ ok: true, value: { __brand: 'TV' } }),
+        resolveHandleId: () => 0,
+      },
+      errorRegistry: { add: () => () => {}, fire: (_e: unknown) => {}, clear: () => {} },
+      getMaterialShaderPipeline: undefined,
+      getParamSchema: undefined,
+      getMaterialBindGroupLayout: undefined,
+      metrics: { increment: () => undefined, counter: () => 0 },
+      growMeshSsbo: undefined,
+      meshSsboState: undefined,
+      buildPostProcessPipeline: undefined,
+      healthRegistry: reg,
+    };
+
+    callRecordFrame(
+      internals,
+      makeCameras(),
+      makeLights(),
+      makeFrameState(),
+      makeDispatchCounts(),
+      makeBindGroupCounts(),
+    );
+
+    // AC-03: getCurrentTexture called twice (fail + retry)
+    expect(ctxCalls.n).toBe(2);
+    // AC-03: context configured (retry reconfigure)
+    expect(cfgCalls.n).toBe(1);
+  });
+
+  it('w5(b): normal hot path — zero reconfigure calls (AC-05)', () => {
+    const cfgCalls = { n: 0 };
+    const ctxCalls = { n: 0 };
+    const ps = makePipelineState();
+    const mockCtx = makeSurfaceCtx(cfgCalls, ctxCalls, 0);
+    const dev = makeMockDevice(ps);
+
+    // biome-ignore lint/suspicious/noExplicitAny: test internals
+    const internals: any = {
+      canvas: { width: 800, height: 600 },
+      device: dev,
+      context: mockCtx,
+      getPipelineState: () => ps,
+      assets: { register: () => ({ ok: true }), instantiate: () => ({ ok: true }) },
+      gpuStore: {
+        destroyAll: () => undefined,
+        ensureResident: () => ({ ok: true }),
+        getMeshGpuHandles: () => ({
+          ok: true,
+          value: {
+            indexBuffer: { __brand: 'Buf' },
+            vertexBuffer: { __brand: 'Buf' },
+            indexFormat: 'uint32',
+            indexCount: 0,
+            vertexCount: 0,
+          },
+        }),
+        getTextureView: () => ({ ok: true, value: { __brand: 'TV' } }),
+        resolveHandleId: () => 0,
+      },
+      errorRegistry: { add: () => () => {}, fire: (_e: unknown) => {}, clear: () => {} },
+      getMaterialShaderPipeline: undefined,
+      getParamSchema: undefined,
+      getMaterialBindGroupLayout: undefined,
+      metrics: { increment: () => undefined, counter: () => 0 },
+      growMeshSsbo: undefined,
+      meshSsboState: undefined,
+      buildPostProcessPipeline: undefined,
+      healthRegistry: new HealthListenerRegistry(),
+    };
+
+    callRecordFrame(
+      internals,
+      makeCameras(),
+      makeLights(),
+      makeFrameState(),
+      makeDispatchCounts(),
+      makeBindGroupCounts(),
+    );
+
+    // AC-05: normal hot path — getCurrentTexture once, reconfigure zero
+    expect(ctxCalls.n).toBe(1);
+    expect(cfgCalls.n).toBe(0);
+  });
+});
+
+// ── w6: consecutive surface failure -> internal-fault (AC-04) ────────────────
+
+describe('Surface consecutive failure (w6)', () => {
+  it('w6: both attempts fail -> health().reason is internal-fault with surface detail', () => {
+    const cfgCalls = { n: 0 };
+    const ctxCalls = { n: 0 };
+    const ps = makePipelineState();
+    const reg = new HealthListenerRegistry();
+    const mockCtx = makeSurfaceCtx(cfgCalls, ctxCalls, 999);
+    const dev = makeMockDevice(ps);
+
+    // biome-ignore lint/suspicious/noExplicitAny: test internals
+    const internals: any = {
+      canvas: { width: 800, height: 600 },
+      device: dev,
+      context: mockCtx,
+      getPipelineState: () => ps,
+      assets: { register: () => ({ ok: true }), instantiate: () => ({ ok: true }) },
+      gpuStore: {
+        destroyAll: () => undefined,
+        ensureResident: () => ({ ok: true }),
+        getMeshGpuHandles: () => ({
+          ok: true,
+          value: {
+            indexBuffer: { __brand: 'Buf' },
+            vertexBuffer: { __brand: 'Buf' },
+            indexFormat: 'uint32',
+            indexCount: 0,
+            vertexCount: 0,
+          },
+        }),
+        getTextureView: () => ({ ok: true, value: { __brand: 'TV' } }),
+        resolveHandleId: () => 0,
+      },
+      errorRegistry: { add: () => () => {}, fire: (_e: unknown) => {}, clear: () => {} },
+      getMaterialShaderPipeline: undefined,
+      getParamSchema: undefined,
+      getMaterialBindGroupLayout: undefined,
+      metrics: { increment: () => undefined, counter: () => 0 },
+      growMeshSsbo: undefined,
+      meshSsboState: undefined,
+      buildPostProcessPipeline: undefined,
+      healthRegistry: reg,
+    };
+
+    // Baseline: alive
+    expect(reg.getLastSnapshot().reason).toBe('alive');
+
+    callRecordFrame(
+      internals,
+      makeCameras(),
+      makeLights(),
+      makeFrameState(),
+      makeDispatchCounts(),
+      makeBindGroupCounts(),
+    );
+
+    // AC-04: health reason is internal-fault
+    const snap = reg.getLastSnapshot();
+    expect(snap.reason).toBe('internal-fault');
+    if (snap.reason === 'internal-fault') {
+      expect(snap.detail.message).toMatch(/surface/i);
+    }
+  });
+});

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,61 @@
+// 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;
+        case 'frame-submitted':
+          return `frame:${event.frameId}@${event.deviceGeneration}`;
+      }
+    };
+    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');
+  });
+});