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

package/src/__tests__/loadbyguid-payload.unit.test.ts

@@ -0,0 +1,117 @@
+// M8 w58 (round 5 D-18): atomic read+write flip integration TDD.
+//
+// D-18 atomic cut: the M8 milestone flips read-side (material-walk source,
+// loadByGuid public return) and write-side (user-tier mint) together in one
+// breaking PR. This file asserts the three end-to-end contracts that go GREEN
+// only after w59 (runtime atomic flip) + w60 (AssetRegistry public delete) +
+// w61-w65 (the ~120-file sweep) co-land:
+//
+//   (1) material-walk over world.sharedRefs payloads -- a material payload
+//       whose `parent` is a user-tier handle walks the parent chain by
+//       resolving each ancestor via world.sharedRefs.resolve (no by-handle
+//       AssetRegistry Map lookup). D-15 point 5.
+//   (2) loadByGuid(GUID) returns the asset PAYLOAD (not a Handle) -- the
+//       AssetRegistry holds no World so it cannot mint a column handle (D-17).
+//   (3) mint+resolve consistency -- world.allocSharedRef(tag, payload) lands
+//       the payload in a user-tier slot (>= BUILTIN_BASE) and
+//       world.sharedRefs.resolve(handle) === payload; AssetRegistry no longer
+//       holds a parallel handle->payload Map (w31 AC-25 gate; this file is the
+//       positive end-to-end shape).
+//
+// TDD: RED before the M8 impl (w59) + delete (w60) land; GREEN once they +
+// the sweep batches co-land. M8 is the ATOMIC milestone -- this test is not
+// green-keepable in isolation.
+
+import { AssetRegistry, walkMaterialPassesOverSharedRefs } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function mesh(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(12 * 3),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {},
+    materialSlots: [{ slotName: 'Default' }],
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 36,
+        materialSlot: 0,
+        topology: 'triangle-list',
+      },
+    ],
+  } as unknown as MeshAsset;
+}
+
+describe('M8 mint+resolve consistency (AC-24 positive end-to-end)', () => {
+  it('world.allocSharedRef lands payload in a user-tier slot resolvable by world.sharedRefs', () => {
+    const world = new World();
+    const payload = mesh();
+    const handle = world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', payload);
+    expect(handle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+    const res = world.sharedRefs.resolve<'MeshAsset', MeshAsset>(handle);
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toBe(payload);
+  });
+});
+
+describe('M8 material-walk: handle root via sharedRefs, parent chain via catalogue GUID (D-19)', () => {
+  it('resolves the parent chain by following material.parent GUID through the AssetRegistry catalogue', () => {
+    const world = new World();
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    // Parent material: catalogued by GUID, declares the base pass + a base param.
+    const parentGuidStr = '22222222-2222-5222-8222-222222222222';
+    const parentGuid = reg.parseGuid(parentGuidStr);
+    const parentPayload: MaterialAsset = {
+      kind: 'material',
+      passes: [{ name: 'forward', program: { module: 'forgeax_material::unlit' } }],
+      values: { baseColor: [0.2, 0.4, 0.6] },
+    } as unknown as MaterialAsset;
+    reg.catalog(parentGuid, parentPayload);
+    // Child material: no passes (inherits parent), parent stored as a GUID
+    // (D-19 embedded ref). The child gets a user-tier column handle.
+    const childPayload: MaterialAsset = {
+      kind: 'material',
+      values: { metallic: 1 },
+      parent: parentGuid,
+    } as unknown as MaterialAsset;
+    const childHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>(
+      'MaterialAsset',
+      childPayload,
+    );
+
+    const walk = walkMaterialPassesOverSharedRefs(world, childHandle, reg);
+    expect(walk.ok).toBe(true);
+    if (!walk.ok) return;
+    // Passes inherited from parent (W-5 full inheritance).
+    expect(walk.value.passes.length).toBe(1);
+    expect(walk.value.passes[0]?.program.module).toBe('forgeax_material::unlit');
+    // values shallow-merged: parent baseColor + child metallic (W-4).
+    expect(walk.value.values.metallic).toBe(1);
+    expect(walk.value.values.baseColor).toEqual([0.2, 0.4, 0.6]);
+  });
+});
+
+describe('M8 loadByGuid returns payload, not a Handle (D-17)', () => {
+  it('dev/fallback loadByGuid resolves to the registered payload object', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const payload = mesh();
+    // After the M8 cut AssetRegistry catalogues GUID->payload; loadByGuid
+    // returns the PAYLOAD (assignable to MeshAsset, not Handle<...>).
+    const guid = '11111111-1111-5111-8111-111111111111';
+    reg.catalog(guid, payload);
+    const res = await reg.loadByGuid<MeshAsset>(reg.parseGuid(guid));
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    // The returned value is the payload object itself (kind === 'mesh'),
+    // never a numeric Handle.
+    expect(typeof res.value).toBe('object');
+    expect((res.value as MeshAsset).kind).toBe('mesh');
+    expect(res.value).toBe(payload);
+  });
+});

package/src/__tests__/loadbyguid-texture-intern.unit.test.ts

@@ -0,0 +1,213 @@
+// tweak-20260627-model-loading-smoke-build-perf M4: regression test for the
+// loadByGuid per-frame texture re-upload bug.
+//
+// SYMPTOM: a MaterialAsset loaded via loadByGuid keeps its texture/sampler
+// values as embedded GUID strings (dash-form). The extract stage
+// (render-system-extract.ts) re-resolved each GUID to a column handle EVERY
+// frame by calling `world.allocSharedRef`, which mints a NEW monotonically-
+// increasing slot id per call. The GPU residency cache
+// (GpuResidencyCache.textureGpuHandles) is keyed on handleSlot(handle), so a
+// fresh slot every frame meant the residency check ALWAYS missed -> all
+// textures re-uploaded to the GPU every frame, GPU memory unbounded, per-frame
+// draw time grew linearly until SIGKILL.
+//
+// FIX: the GUID-string -> column-handle resolution is interned per World, so a
+// given (world, guid, brand) mints EXACTLY ONE stable handle reused across
+// frames (architecture-principle §6 idempotency). This file asserts that
+// invariant directly: resolving the same texture GUID across two extract
+// frames yields the SAME handle, and `world.allocSharedRef` is NOT called again
+// on the second frame's resolution.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { Handle, MaterialAsset, MeshAsset, TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function identityTx() {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+function registerQuadMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices: new Float32Array([
+      0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+      1, 0, 0, 0, 0,
+    ]),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: { position: positions },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 1]),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 36,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  });
+}
+
+function textureAsset(red = 255): TextureAsset {
+  return {
+    kind: 'texture',
+    width: 1,
+    height: 1,
+    format: 'rgba8unorm',
+    data: new Uint8Array([red, 255, 255, 255]),
+    colorSpace: 'linear',
+    mipmap: false,
+  } as unknown as TextureAsset;
+}
+
+// Build a loadByGuid-shaped scene: the material's baseColorTexture paramValue is
+// an embedded GUID STRING (not a pre-minted numeric handle), catalogued to a
+// texture payload. This is exactly the shape Sponza materials have after
+// loadByGuid, and the shape that triggered the per-frame re-upload bug.
+function spawnTexturedRenderable(world: World, assets: AssetRegistry): { textureGuidStr: string } {
+  const mesh = registerQuadMesh(world);
+
+  // Catalog the texture under a GUID; the material references it by GUID string.
+  // The embedded ref must be the EXACT dash-form string that
+  // AssetRegistry.lookup keys on (AssetGuid.format, lowercased) -- the same
+  // shape loadByGuid leaves in a MaterialAsset's values (D-19).
+  const textureGuid = AssetGuid.random();
+  const textureGuidStr = AssetGuid.format(textureGuid);
+  assets.catalog(textureGuid, textureAsset());
+
+  const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [{ name: 'Forward', program: { module: 'forgeax::default-unlit' } }],
+    values: {
+      baseColor: [1, 1, 1],
+      // Embedded GUID string -- the loadByGuid texture-ref shape (D-19).
+      baseColorTexture: textureGuidStr,
+    },
+  } as unknown as MaterialAsset);
+
+  world
+    .spawn(
+      { component: Transform, data: { ...identityTx(), pos: [0, 0, 5] } },
+      {
+        component: Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          projection: 0,
+          left: -1,
+          right: 1,
+          bottom: -1,
+          top: 1,
+        },
+      },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: identityTx() },
+      { component: MeshFilter, data: { assetHandle: mesh } },
+      { component: MeshRenderer, data: { materials: [matHandle] } },
+    )
+    .unwrap();
+  propagateTransforms(world);
+
+  return { textureGuidStr };
+}
+
+function baseColorHandleFromFrame(world: World, assets: AssetRegistry): number | undefined {
+  const frame = extractFrame(world, prepareExtractContext(world, { assets, pipelineState: null }));
+  const renderable = frame.renderables.find(
+    (r) => r.material.materialShaderId === 'forgeax::default-unlit',
+  );
+  const snap = renderable?.material as
+    | { readonly baseColorTexture?: Handle<'TextureAsset', 'shared'> }
+    | undefined;
+  return snap?.baseColorTexture as unknown as number | undefined;
+}
+
+describe('M4 loadByGuid texture handle interning (per-frame re-upload regression)', () => {
+  it('resolves the same texture GUID to the SAME column handle across two extract frames', () => {
+    const world = new World();
+    const assets = new AssetRegistry(makeMockShaderRegistry());
+    spawnTexturedRenderable(world, assets);
+
+    const handleFrame1 = baseColorHandleFromFrame(world, assets);
+    const handleFrame2 = baseColorHandleFromFrame(world, assets);
+
+    expect(handleFrame1).toBeDefined();
+    expect(handleFrame2).toBeDefined();
+    // The whole fix: a stable handle across frames so handleSlot(handle) is
+    // stable and the GPU residency cache hits instead of re-uploading.
+    expect(handleFrame2).toBe(handleFrame1);
+  });
+
+  it('does NOT call world.allocSharedRef again when re-resolving the same GUID on a later frame', () => {
+    const world = new World();
+    const assets = new AssetRegistry(makeMockShaderRegistry());
+    spawnTexturedRenderable(world, assets);
+
+    // Warm the intern cache (frame 1 mints the texture handle exactly once).
+    baseColorHandleFromFrame(world, assets);
+
+    // Frame 2: spy on allocSharedRef and confirm the GUID resolution is served
+    // from the intern cache -- zero new allocations for the cached texture GUID.
+    const allocSpy = vi.spyOn(world, 'allocSharedRef');
+    const handleFrame2 = baseColorHandleFromFrame(world, assets);
+    expect(handleFrame2).toBeDefined();
+
+    const textureAllocCalls = allocSpy.mock.calls.filter((c) => c[0] === 'TextureAsset');
+    expect(textureAllocCalls.length).toBe(0);
+    allocSpy.mockRestore();
+  });
+
+  it('retires the cached allocation grant when the GUID is re-catalogued', () => {
+    const world = new World();
+    const assets = new AssetRegistry(makeMockShaderRegistry());
+    const { textureGuidStr } = spawnTexturedRenderable(world, assets);
+
+    const oldHandle = baseColorHandleFromFrame(world, assets);
+    expect(oldHandle).toBeDefined();
+    const replacement = textureAsset(127);
+    assets.catalog(textureGuidStr, replacement);
+
+    const newHandle = baseColorHandleFromFrame(world, assets);
+    expect(newHandle).toBeDefined();
+    expect(newHandle).not.toBe(oldHandle);
+    expect(
+      world.sharedRefs.resolve(newHandle as unknown as Handle<'TextureAsset', 'shared'>),
+    ).toMatchObject({ ok: true, value: replacement });
+    expect(
+      world.sharedRefs.refcount(oldHandle as unknown as Handle<'TextureAsset', 'shared'>),
+    ).toBe(0);
+  });
+
+  it('drops the cached allocation grant when the GUID is invalidated', () => {
+    const world = new World();
+    const assets = new AssetRegistry(makeMockShaderRegistry());
+    const { textureGuidStr } = spawnTexturedRenderable(world, assets);
+
+    const handle = baseColorHandleFromFrame(world, assets);
+    expect(handle).toBeDefined();
+    assets.invalidate(textureGuidStr);
+
+    expect(baseColorHandleFromFrame(world, assets)).toBeUndefined();
+    expect(world.sharedRefs.refcount(handle as unknown as Handle<'TextureAsset', 'shared'>)).toBe(
+      0,
+    );
+  });
+});

package/src/__tests__/loader-extract-graceful.test.ts

@@ -0,0 +1,146 @@
+// loader-extract-graceful.test.ts -- M4 / w24 integration test for the
+// paramSchema-driven loader/extract handoff.
+//
+// feat-20260613-material-paramschema-driven-binding M4 / w24.
+//
+// Decision anchors (plan-strategy section 2 + section 5.3):
+//   - D-5  loader does not pre-filter texture fields by hardcoded name; the
+//          paramSchema-derived textureFieldNames is the SSOT. Cross-worktree
+//          shader-late-register falls back to "try every int paramValue"
+//          gracefully; the extract layer's paramSchema validation catches
+//          misclassifications and routes through MISSING_TEXTURE_HANDLE.
+//   - R-4  shader-late-register risk: material loaded before its shader is
+//          registered. The graceful fallback keeps the load path live.
+//
+// Four scenarios (plan-strategy section 5.3 acceptance), updated for
+// feat-20260614 M8 (D-19): the loader no longer resolves a texture-typed
+// paramValue to a runtime handle. It maps the refs[] index to the embedded
+// sub-asset GUID string; the ECS/render side resolves GUID -> column handle
+// at use time (world.allocSharedRef). `LoadContext.resolveRefSync` is gone.
+//   (1) shader registered + texture-typed paramValue + valid refs[] index
+//       -> loader rewrites the field to the refs[] GUID string.
+//   (2) shader registered + texture-typed paramValue + index out of range
+//       -> loader drops the field; record stage falls back to MISSING_TEXTURE_HANDLE.
+//   (3) shader NOT registered yet (cross-worktree R-4) + int paramValue
+//       -> graceful fallback resolves every in-range int to its refs[] GUID.
+//   (4) shader registered + scalar-typed paramValue (metallic = 0) whose
+//       value happens to land in [0, refs.length) -> paramSchema-aware path
+//       skips it; the field stays as the original int.
+
+import { materialLoader } from '@forgeax/engine-assets-runtime';
+import type { LoadContext, ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeCtx(opts: {
+  shaderTextureFieldNames?: (shaderId: string) => ReadonlySet<string> | undefined;
+}): LoadContext {
+  const ctx: LoadContext = {
+    fetchBinary: async () => ({ ok: false as const, error: new Error('no binary') }),
+    resolveRef: async () => ({ ok: false as const, error: new Error('no ref') }),
+    transcodeCaps: { bc: false, etc2: false, astc: false },
+    device: undefined,
+  };
+  if (opts.shaderTextureFieldNames) {
+    ctx.getMaterialShaderTextureFieldNames = opts.shaderTextureFieldNames;
+  }
+  return ctx;
+}
+
+const standardPbrSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+describe('loader-extract graceful handoff (M4 w24)', () => {
+  it('(1) shader registered + valid texture refs[] index resolves to a structured texture value', () => {
+    const textureFields = derive(standardPbrSchema).textureFieldNames;
+    const ctx = makeCtx({
+      shaderTextureFieldNames: (id) =>
+        id === 'forgeax::default-standard-pbr' ? textureFields : undefined,
+    });
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::default-standard-pbr' } }],
+        values: { baseColorTexture: 0, metallic: 0.5 },
+      },
+      ['tex-bc-guid'],
+      ctx,
+    );
+    expect(out).toMatchObject({ kind: 'material' });
+    const pv = (out as { values: Record<string, unknown> }).values;
+    // D-19: texture field rewritten to the structured asset value (not a handle).
+    expect(pv.baseColorTexture).toEqual({ texture: 'tex-bc-guid' });
+    // Scalar field unchanged.
+    expect(pv.metallic).toBe(0.5);
+  });
+
+  it('(2) shader registered + texture refs[] index out of range -> field dropped', () => {
+    const textureFields = derive(standardPbrSchema).textureFieldNames;
+    const ctx = makeCtx({
+      shaderTextureFieldNames: (id) =>
+        id === 'forgeax::default-standard-pbr' ? textureFields : undefined,
+    });
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::default-standard-pbr' } }],
+        // index 5 is out of range for refs.length=1 -> dropped.
+        values: { baseColorTexture: 5 },
+      },
+      ['tex-bc-guid'],
+      ctx,
+    );
+    expect(out).toMatchObject({ kind: 'material' });
+    const pv = (out as { values: Record<string, unknown> }).values;
+    // Loader drops the field; record stage falls back to MISSING_TEXTURE_HANDLE.
+    expect('baseColorTexture' in pv).toBe(false);
+  });
+
+  it('(3) shader NOT registered (R-4 cross-worktree) -> graceful "try every int" fallback', () => {
+    // No paramSchema lookup available -> getMaterialShaderTextureFieldNames
+    // returns undefined for every shader id.
+    const ctx = makeCtx({
+      shaderTextureFieldNames: () => undefined,
+    });
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::user-defined' } }],
+        values: { customTexture: 0 },
+      },
+      ['tex-guid'],
+      ctx,
+    );
+    expect(out).toMatchObject({ kind: 'material' });
+    const pv = (out as { values: Record<string, unknown> }).values;
+    // Graceful fallback resolves any in-range int to its refs[] GUID string.
+    expect(pv.customTexture).toBe('tex-guid');
+  });
+
+  it('(4) shader registered + scalar paramValue with refs[] index in range -> NOT misclassified', () => {
+    const textureFields = derive(standardPbrSchema).textureFieldNames;
+    const ctx = makeCtx({
+      shaderTextureFieldNames: (id) =>
+        id === 'forgeax::default-standard-pbr' ? textureFields : undefined,
+    });
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::default-standard-pbr' } }],
+        // metallic = 0 is an int in [0, refs.length=1) — would misclassify
+        // under a naive "try every int" loader. paramSchema-aware path
+        // declares metallic as 'f32', so it skips resolution.
+        values: { baseColorTexture: 0, metallic: 0 },
+      },
+      ['tex-bc-guid'],
+      ctx,
+    );
+    expect(out).toMatchObject({ kind: 'material' });
+    const pv = (out as { values: Record<string, unknown> }).values;
+    // Texture field still resolves to the structured asset value.
+    expect(pv.baseColorTexture).toEqual({ texture: 'tex-bc-guid' });
+    // Scalar field unchanged: metallic stays 0.
+    expect(pv.metallic).toBe(0);
+  });
+});

package/src/__tests__/loader-name-survival.test.ts

@@ -0,0 +1,213 @@
+// loader name survival through JSON roundtrip — AC-08 (feat-20260618 w20).
+//
+// Red-first: written before w15 wires entry.name -> registerPackage.
+//
+// dawn smoke walks the in-memory register path and skips the
+// JSON.stringify -> fetch -> JSON.parse pack-body path (AGENTS.md smoke gate +
+// memory typed-array-json-roundtrip-asymmetric-loader-contract). This test
+// drives the prod loadByGuid path with a JSON-roundtripped pack-index so a name
+// that does not survive the roundtrip is caught here.
+//
+// Coverage:
+//   AC-08 sync  — two meshes sharing a .pack.json, each with a pack-index name;
+//                 after loadByGuid (parseAssetPayload sync branch) resolveName
+//                 returns each stored name.
+//   AC-08 async — a texture in its own (single-asset) package; after loadByGuid
+//                 (texture upstream async branch) resolveName returns the
+//                 basename derived from its package path. Without the entry ->
+//                 Package wiring the texture would land in a null package and
+//                 resolveName would be '' -- so basename here still proves the
+//                 async load path registered the package post-roundtrip.
+//   FALSIFY     — the same pack with the entry name stripped degrades to
+//                 basename(path), proving the assertion is name-sensitive (not
+//                 a tautology). The FALSIFY block does not gate CI; it documents
+//                 discriminating power.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const MESH_A = '70000000-0000-4000-7000-000000000001';
+const MESH_B = '70000000-0000-4000-7000-000000000002';
+const TEX = '70000000-0000-4000-7000-0000000000aa';
+const SHARED_PACK_URL = '/packs/char.pack.json';
+const TEX_URL = '/assets/diffuse.pack.json';
+
+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 MESH_PAYLOAD_A = {
+  vertices: [
+    -0.5, 0, 0.5, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0.5, 0, 0.5, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0.5, 0, -0.5,
+    0, 1, 0, 1, 1, 1, 0, 0, 1,
+  ],
+  indices: [0, 1, 2],
+  attributes: {},
+  submeshes: [{ indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list' }],
+};
+const MESH_PAYLOAD_B = {
+  vertices: [
+    0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 1, 1, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1,
+    1, 1, 0, 0,
+  ],
+  indices: [1, 0, 2],
+  attributes: {},
+  submeshes: [{ indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list' }],
+};
+
+function makeSharedPack(): unknown {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: [
+      { guid: MESH_A, kind: 'mesh', payload: MESH_PAYLOAD_A, refs: [], artifacts: {} },
+      { guid: MESH_B, kind: 'mesh', payload: MESH_PAYLOAD_B, refs: [], artifacts: {} },
+    ],
+  };
+}
+
+const TEX_METADATA = {
+  kind: 'texture',
+  width: 1,
+  height: 1,
+  format: 'rgba8unorm',
+  colorSpace: 'srgb',
+  mipmap: false,
+};
+
+// `includeNames=false` is the FALSIFY variant (entry.name stripped).
+function makePackIndex(includeNames: boolean): unknown[] {
+  const named = (n: string) => (includeNames ? { name: n } : {});
+  return [
+    {
+      guid: MESH_A,
+      packageUrl: SHARED_PACK_URL,
+      kind: 'mesh',
+      sourcePath: 'char.glb',
+      ...named('Body'),
+    },
+    {
+      guid: MESH_B,
+      packageUrl: SHARED_PACK_URL,
+      kind: 'mesh',
+      sourcePath: 'char.glb',
+      ...named('Head'),
+    },
+    {
+      guid: TEX,
+      packageUrl: TEX_URL,
+      kind: 'texture',
+      sourcePath: 'diffuse.png',
+      ...named('Diffuse'),
+    },
+  ];
+}
+
+// Roundtrip every fetched body through JSON.stringify -> JSON.parse, mirroring
+// the dev-server pack-body transport that dawn smoke skips.
+function jsonRoundtrip(value: unknown): unknown {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function installFetch(includeNames: boolean): void {
+  const packIndex = jsonRoundtrip(makePackIndex(includeNames));
+  const sharedPack = jsonRoundtrip(makeSharedPack());
+  const texBytes = new Uint8Array(1 * 1 * 4).fill(200);
+  globalThis.fetch = vi.fn(async (url: string | URL) => {
+    const u = String(url);
+    if (u.includes('pack-index.json')) {
+      return new Response(JSON.stringify(packIndex), { status: 200 });
+    }
+    if (u === SHARED_PACK_URL) {
+      return new Response(JSON.stringify(sharedPack), { status: 200 });
+    }
+    if (u === TEX_URL) {
+      return new Response(
+        JSON.stringify({
+          schemaVersion: '2.0.0',
+          kind: 'internal-text-package',
+          assets: [
+            {
+              guid: TEX,
+              kind: 'texture',
+              payload: TEX_METADATA,
+              refs: [],
+              artifacts: {
+                body: { path: 'diffuse.bin', mediaType: 'application/x-forgeax-rgba8' },
+              },
+            },
+          ],
+        }),
+        { status: 200 },
+      );
+    }
+    if (u === '/assets/diffuse.bin') {
+      return new Response(texBytes, { status: 200 });
+    }
+    return new Response('', { status: 404 });
+  }) as unknown as typeof globalThis.fetch;
+}
+
+describe('loader name survival (AC-08)', () => {
+  let originalFetch: typeof globalThis.fetch | undefined;
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    if (originalFetch !== undefined) globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it('sync branch: multi-asset mesh names survive the JSON roundtrip', async () => {
+    installFetch(true);
+    const reg = makeRegistry();
+    reg.configurePackIndex('/pack-index.json');
+
+    const rA = await reg.loadByGuid<TypesMeshAsset>(parseGuid(MESH_A));
+    const rB = await reg.loadByGuid<TypesMeshAsset>(parseGuid(MESH_B));
+    expect(rA.ok).toBe(true);
+    expect(rB.ok).toBe(true);
+
+    expect(reg.resolveName(MESH_A)).toBe('Body');
+    expect(reg.resolveName(MESH_B)).toBe('Head');
+  });
+
+  it('async branch: texture package resolves via the async load path post-roundtrip', async () => {
+    installFetch(true);
+    const reg = makeRegistry();
+    reg.configurePackIndex('/pack-index.json');
+
+    const r = await reg.loadByGuid(parseGuid(TEX));
+    expect(r.ok).toBe(true);
+    // Single-asset texture package -> basename(path) (AC-01). The wiring is what
+    // makes this non-empty: without entry -> Package the texture lands in a null
+    // package and resolveName would be ''.
+    expect(reg.resolveName(TEX)).toBe('diffuse.pack.json');
+  });
+
+  it('FALSIFY: stripped entry.name degrades to basename, proving name-sensitivity', async () => {
+    installFetch(false);
+    const reg = makeRegistry();
+    reg.configurePackIndex('/pack-index.json');
+
+    const rA = await reg.loadByGuid<TypesMeshAsset>(parseGuid(MESH_A));
+    const rB = await reg.loadByGuid<TypesMeshAsset>(parseGuid(MESH_B));
+    expect(rA.ok).toBe(true);
+    expect(rB.ok).toBe(true);
+
+    // Multi-asset package with no stored names -> basename(cooked packageUrl),
+    // NOT the original 'Body' / 'Head'. If the assertion still
+    // saw 'Body', the name path would be a tautology.
+    expect(reg.resolveName(MESH_A)).toBe('char.pack.json');
+    expect(reg.resolveName(MESH_B)).toBe('char.pack.json');
+  });
+});