@forgeax/engine-pack 0.1.20 → 0.1.23

package/src/__tests__/inventory-schema.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { type AuthorInventory, validateAuthorInventory } from '../inventory/declaration.js';
+
+const guid = '00000000-0000-0000-0000-000000000010';
+
+describe('author inventory declaration contract', () => {
+  it('requires one semantic sourceKey for every author row', () => {
+    const result = validateAuthorInventory({
+      declarations: [{ guid, kind: 'mesh', payload: {}, refs: [] }],
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('inventory-source-key-missing');
+      expect(result.error.detail.sourceKey).toBeUndefined();
+      expect(result.error.expected).toContain('sourceKey');
+    }
+  });
+
+  it('rejects duplicate GUID and sourceKey before projection', () => {
+    const rows: AuthorInventory = {
+      declarations: [
+        { guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] },
+        { guid, sourceKey: 'hero/body', kind: 'material', payload: {}, refs: [] },
+      ],
+    };
+    const result = validateAuthorInventory(rows);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(['inventory-guid-duplicate', 'inventory-source-key-duplicate']).toContain(
+        result.error.code,
+      );
+      expect(result.error.detail).toHaveProperty('guid');
+      expect(result.error.hint).toContain('rename');
+    }
+  });
+
+  it('rejects GUID duplicates regardless of hex casing and padded source keys', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        { guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] },
+        {
+          guid: guid.toUpperCase(),
+          sourceKey: 'hero/other',
+          kind: 'mesh',
+          payload: {},
+          refs: [],
+        },
+      ],
+    });
+    expect(result).toMatchObject({ ok: false, error: { code: 'inventory-guid-duplicate' } });
+
+    const padded = validateAuthorInventory({
+      declarations: [{ guid, sourceKey: ' hero/body', kind: 'mesh', payload: {}, refs: [] }],
+    });
+    expect(padded).toMatchObject({ ok: false, error: { code: 'inventory-source-key-missing' } });
+  });
+
+  it('projects declared scene binding keys without using display names', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        {
+          guid,
+          sourceKey: 'world/main',
+          kind: 'scene',
+          payload: {
+            kind: 'scene',
+            entities: [
+              { localId: 0, bindingKey: 'player', components: { Name: { value: 'Renamed' } } },
+              { localId: 1, bindingKey: 'camera', components: {} },
+            ],
+          },
+          refs: [],
+        },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: { declarations: [{ sceneBindings: ['player', 'camera'] }] },
+    });
+  });
+
+  it('allows decorative scene entities without a gameplay binding', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        {
+          guid,
+          sourceKey: 'world/decorative',
+          kind: 'scene',
+          payload: {
+            kind: 'scene',
+            entities: [
+              { localId: 0, components: { Transform: { position: [0, 0, 0] } } },
+              { localId: 1, bindingKey: 'player', components: {} },
+            ],
+          },
+          refs: [],
+        },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: { declarations: [{ sceneBindings: ['player'] }] },
+    });
+  });
+});

package/src/__tests__/pack.unit.test.ts

@@ -1970,7 +1970,7 @@ const V1_WHITELIST = new Set([
       expect(result.ok).toBe(true);
     });
 
-    it('AC-17: explicit source=hero.png + companion file → scan passes (backward compat)', async () => {
+    it('AC-17: explicit source=hero.png + companion file → scan passes', async () => {
       await writeFile(join(tmpDir, 'hero.png.meta.json'), makeMeta({ source: 'hero.png' }));
       await writeFile(join(tmpDir, 'hero.png'), Buffer.from('fake png'));
 
@@ -1978,241 +1978,4 @@ const V1_WHITELIST = new Set([
       expect(result.ok).toBe(true);
     });
   });
-
-  describe('w15-scanner-path-integration.test.ts — AC-5+AC-10', () => {
-    let tmpDir: string;
-
-    beforeEach(async () => {
-      tmpDir = await mkdtemp(join(tmpdir(), 'forgeax-ac5-'));
-    });
-    afterEach(async () => {
-      await rm(tmpDir, { recursive: true, force: true });
-    });
-
-    it('AC-5: @name/ path resolves correctly when file exists', async () => {
-      const libDir = join(tmpDir, 'lib');
-      await mkdir(libDir);
-      await writeFile(join(libDir, 'shared.png'), Buffer.from('fake png'));
-      const metaContent = JSON.stringify({
-        schemaVersion: '1.0.0',
-        kind: 'external-asset-package',
-        importer: 'image',
-        source: '@shared/shared.png',
-        importSettings: {},
-        subAssets: [
-          { guid: 'aaaaaaaa-bbbb-4000-8000-000000000001', sourceIndex: 0, kind: 'texture' },
-        ],
-      });
-      await writeFile(join(tmpDir, 'ref.meta.json'), metaContent);
-
-      // The scan runs inside its own process.cwd() — paths table resolution uses cwd
-      // The tmpDir is not the cwd, so @shared/ will report pack-unknown-path.
-      // AC-5: we need the path table to be configured at the scan's cwd.
-      // For a unit test, we verify instead via resolveAssetSource directly:
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const paths = { shared: libDir };
-      const result = resolveAS(join(tmpDir, 'ref.meta.json'), '@shared/shared.png', paths);
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(join(libDir, 'shared.png'));
-      }
-    });
-
-    it('AC-10: path configured but file missing → pack-orphan-meta', async () => {
-      const libDir = join(tmpDir, 'lib');
-      await mkdir(libDir);
-      // Do NOT create missing.png in libDir
-      const metaContent = JSON.stringify({
-        schemaVersion: '1.0.0',
-        kind: 'external-asset-package',
-        importer: 'image',
-        source: '@shared/missing.png',
-        importSettings: {},
-        subAssets: [
-          { guid: 'aaaaaaaa-bbbb-4000-8000-000000000001', sourceIndex: 0, kind: 'texture' },
-        ],
-      });
-      await writeFile(join(tmpDir, 'ref.meta.json'), metaContent);
-
-      // resolveAssetSource resolves the path but does not stat — the resolved path will be returned ok
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const paths = { shared: libDir };
-      const result = resolveAS(join(tmpDir, 'ref.meta.json'), '@shared/missing.png', paths);
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(join(libDir, 'missing.png'));
-        // The actual orphan check (stat) is done by the scanner caller
-      }
-    });
-
-    it('AC-10: scanner reports pack-orphan-meta when resolved path file does not exist', async () => {
-      const metaContent = makeMeta({ source: 'nowhere.png' });
-      await writeFile(join(tmpDir, 'orphan.meta.json'), metaContent);
-      // Do NOT create nowhere.png
-
-      const result = await scan([tmpDir]);
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('pack-orphan-meta');
-        if (result.error.code === 'pack-orphan-meta') {
-          expect(result.error.detail.expectedFile).toContain('nowhere.png');
-        }
-      }
-    });
-  });
-
-  describe('scanner @name/ end-to-end via cwd package.json — AC-5/AC-8', () => {
-    let tmpDir: string;
-    let originalCwd: string;
-
-    beforeEach(async () => {
-      originalCwd = process.cwd();
-      tmpDir = await mkdtemp(join(tmpdir(), 'forgeax-ac5e2e-'));
-      process.chdir(tmpDir);
-    });
-    afterEach(async () => {
-      process.chdir(originalCwd);
-      await rm(tmpDir, { recursive: true, force: true });
-    });
-
-    it('AC-5: scan() passes orphan check for @name/ meta when cwd package.json path table resolves to an existing file', async () => {
-      const sharedDir = join(tmpDir, 'shared-lib', 'assets');
-      await mkdir(sharedDir, { recursive: true });
-      await writeFile(join(sharedDir, 'cross.png'), Buffer.from('fake png'));
-      await writeFile(
-        join(tmpDir, 'package.json'),
-        JSON.stringify({
-          name: 'ac5-e2e-tmp',
-          forgeax: { assets: { paths: { shared: 'shared-lib/assets' } } },
-        }),
-      );
-      const scanRoot = join(tmpDir, 'metas');
-      await mkdir(scanRoot, { recursive: true });
-      await writeFile(
-        join(scanRoot, 'cross.png.meta.json'),
-        JSON.stringify({
-          schemaVersion: '1.0.0',
-          kind: 'external-asset-package',
-          importer: 'image',
-          source: '@shared/cross.png',
-          importSettings: {},
-          subAssets: [
-            { guid: 'aaaaaaaa-bbbb-4000-8000-000000000001', sourceIndex: 0, kind: 'texture' },
-          ],
-        }),
-      );
-
-      const result = await scan([scanRoot]);
-      expect(result.ok).toBe(true);
-    });
-
-    it('AC-8: scan() reports pack-unknown-path when @name/ references an undeclared path name', async () => {
-      await writeFile(
-        join(tmpDir, 'package.json'),
-        JSON.stringify({ name: 'ac8-e2e-tmp', forgeax: { assets: { paths: {} } } }),
-      );
-      const scanRoot = join(tmpDir, 'metas');
-      await mkdir(scanRoot, { recursive: true });
-      await writeFile(
-        join(scanRoot, 'x.png.meta.json'),
-        JSON.stringify({
-          schemaVersion: '1.0.0',
-          kind: 'external-asset-package',
-          importer: 'image',
-          source: '@nope/x.png',
-          importSettings: {},
-          subAssets: [
-            { guid: 'aaaaaaaa-bbbb-4000-8000-000000000001', sourceIndex: 0, kind: 'texture' },
-          ],
-        }),
-      );
-
-      const result = await scan([scanRoot]);
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('pack-unknown-path');
-      }
-    });
-  });
-}
-
-{
-  // ─── AC-1 regression w15 — resolveAssetSource explicit source backwards compat ───
-
-  describe('w15-AC-1-regression.test.ts', () => {
-    it('AC-1: explicit source=foo.png with resolveAssetSource == resolve(metaDir, foo.png)', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const { resolve } = await import('node:path');
-      const metaPath = '/home/user/assets/foo.png.meta.json';
-      const result = resolveAS(metaPath, 'foo.png', {});
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve('/home/user/assets', 'foo.png'));
-      }
-    });
-
-    it('AC-1: explicit source=sub/deep.png with resolveAssetSource == resolve(metaDir, sub/deep.png)', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const { resolve } = await import('node:path');
-      const metaPath = '/home/user/assets/main.meta.json';
-      const result = resolveAS(metaPath, 'sub/deep.png', {});
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve('/home/user/assets', 'sub/deep.png'));
-      }
-    });
-
-    it('AC-1: omitted source derives from meta filename', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const { resolve } = await import('node:path');
-      const metaPath = '/home/user/assets/foo.png.meta.json';
-      const result = resolveAS(metaPath, undefined, {});
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve('/home/user/assets', 'foo.png'));
-      }
-    });
-  });
-
-  // ─── AC-5/AC-10 source path table scanner integration (w15) ───
-
-  describe('w15-AC-5-AC-10-path-table.test.ts', () => {
-    it('AC-5: @shared/ resource resolves correctly when path table configured', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const { resolve } = await import('node:path');
-      const metaPath = '/project/assets/ref.meta.json';
-      const paths = { shared: '/project/lib' };
-      const result = resolveAS(metaPath, '@shared/tex.png', paths);
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve('/project/lib', 'tex.png'));
-      }
-    });
-
-    it('AC-5: @shared/ with nested rest path', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const { resolve } = await import('node:path');
-      const metaPath = '/project/assets/ref.meta.json';
-      const paths = { shared: '/project/lib' };
-      const result = resolveAS(metaPath, '@shared/sub/dir/tex.png', paths);
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve('/project/lib', 'sub/dir/tex.png'));
-      }
-    });
-
-    it('AC-10: @unknown/ path name → pack-unknown-path error', async () => {
-      const { resolveAssetSource: resolveAS } = await import('../resolve-asset-source.js');
-      const metaPath = '/project/assets/ref.meta.json';
-      const result = resolveAS(metaPath, '@nope/tex.png', {});
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('pack-unknown-path');
-        if (result.error.code === 'pack-unknown-path') {
-          expect(result.error.detail.pathName).toBe('nope');
-          expect(result.error.detail.knownNames).toEqual([]);
-        }
-      }
-    });
-  });
 }

package/src/__tests__/package-finalizer.contract.test.ts

@@ -102,4 +102,59 @@ describe('engine-pack terminal product and finalizer contract', () => {
     expect(published.assets[0]?.artifacts.body.byteLength).toBe(body.byteLength);
     expect(writes.get(`${GUID}/body.bin`)).toBe(body);
   });
+
+  it('publishes a mesh LOD relation and keeps the lower mesh in the closure', async () => {
+    const lodGuid = '019e3969-1d48-7c3b-ac24-6d68f4570660';
+    const root = product().assets[0];
+    if (root === undefined) throw new Error('test product asset is missing');
+    const result = await finalizePackageProduct(
+      product({
+        assets: [
+          {
+            ...root,
+            kind: 'mesh',
+            payload: {
+              kind: 'mesh',
+              lods: [{ mesh: lodGuid, screenCoverage: 0.5 }],
+            },
+            refs: [lodGuid],
+          },
+          {
+            ...root,
+            guid: lodGuid,
+            kind: 'mesh',
+            payload: { kind: 'mesh' },
+            refs: [],
+          },
+        ],
+        receipts: [
+          {
+            guid: GUID,
+            origin: 'sourceMeta',
+            status: 'succeeded',
+            inputFingerprint: 'sha256:source',
+          },
+          {
+            guid: lodGuid,
+            origin: 'sourceMeta',
+            status: 'succeeded',
+            inputFingerprint: 'sha256:source',
+          },
+        ],
+      }),
+      {
+        base: '/',
+        packagePath: 'mesh.pack.json',
+        artifactPath: (guid, key) => `${guid}/${key}.bin`,
+      },
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const publishedRoot = result.value.pack.assets.find((asset) => asset.guid === GUID);
+    expect(publishedRoot?.refs).toEqual([lodGuid]);
+    expect(publishedRoot?.payload).toMatchObject({
+      lods: [{ mesh: lodGuid, screenCoverage: 0.5 }],
+    });
+    expect(result.value.pack.assets.map((asset) => asset.guid)).toContain(lodGuid);
+  });
 });

package/src/__tests__/parameterized-pack-authoring-gateway.unit.test.ts

@@ -0,0 +1,249 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AssetGuid, PackageId } from '../guid.js';
+import { createFileSystemParameterizedPackAuthoringGateway } from '../parameterized-pack-node.js';
+
+const DIRECT_PACKAGE = '01900000-0000-7000-8000-000000000070';
+const CLONE_PACKAGE = '01900000-0000-7000-8000-000000000071';
+const SOURCE_PACKAGE = '01900000-0000-7000-8000-000000000072';
+const INSTANCE_PACKAGE = '01900000-0000-7000-8000-000000000073';
+
+const roots: string[] = [];
+
+function packageId(value: string) {
+  const parsed = PackageId.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+afterEach(async () => {
+  const root = roots.pop();
+  if (root !== undefined) await rm(root, { recursive: true, force: true });
+});
+
+describe('parameterized Pack authoring gateway', () => {
+  it('writes guid-less direct JSON, derives identity, and makes mutations idempotent', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-direct-'));
+    roots.push(root);
+    const gateway = createFileSystemParameterizedPackAuthoringGateway({ gameRoot: root });
+    const operation = {
+      operation: 'asset-source.create' as const,
+      requestId: 'create-direct',
+      targetPath: 'assets/direct.pack.json',
+      format: 'pack.json' as const,
+      packageId: DIRECT_PACKAGE,
+      initialAssets: {
+        'mesh/main': { kind: 'mesh', payload: { vertices: [] }, refs: [] },
+      },
+    };
+
+    const created = await gateway.execute(operation);
+    expect(created).toMatchObject({
+      ok: true,
+      value: { packageId: DIRECT_PACKAGE, format: 'pack.json', targetPath: operation.targetPath },
+    });
+    const raw = JSON.parse(await readFile(join(root, operation.targetPath), 'utf8')) as Record<
+      string,
+      unknown
+    >;
+    expect(raw).toEqual({
+      schemaVersion: '3.0.0',
+      packageId: DIRECT_PACKAGE,
+      assets: { 'mesh/main': { kind: 'mesh', payload: { vertices: [] }, refs: [] } },
+    });
+    expect(JSON.stringify(raw)).not.toContain('guid');
+
+    const replay = await gateway.execute(operation);
+    expect(replay).toEqual(created);
+    const conflictingReplay = await gateway.execute({ ...operation, initialAssets: {} });
+    expect(conflictingReplay).toMatchObject({
+      ok: false,
+      error: { code: 'pack-source-revision-conflict' },
+    });
+
+    const unresolved = await gateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-direct',
+      packageId: DIRECT_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'ready',
+    });
+    expect(unresolved).toMatchObject({ ok: false, error: { code: 'asset-not-ready' } });
+
+    const publishedGateway = createFileSystemParameterizedPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => [
+        {
+          packageId: DIRECT_PACKAGE,
+          sourceKey: 'mesh/main',
+          guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+          kind: 'mesh',
+          sourcePath: 'dist/pack.json',
+          ready: true,
+          artifactsReady: true,
+        },
+      ],
+    });
+    const resolved = await publishedGateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-direct-published',
+      packageId: DIRECT_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'ready',
+    });
+    expect(resolved).toMatchObject({
+      ok: true,
+      value: {
+        packageId: DIRECT_PACKAGE,
+        sourceKey: 'mesh/main',
+        status: 'ready',
+        guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+      },
+    });
+
+    const clone = await gateway.execute({
+      operation: 'asset-source.clone',
+      requestId: 'clone-direct',
+      sourcePath: operation.targetPath,
+      targetPath: 'assets/clone.pack.json',
+      packageId: CLONE_PACKAGE,
+    });
+    expect(clone).toMatchObject({ ok: true, value: { packageId: CLONE_PACKAGE } });
+    const cloneResolved = await gateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-clone',
+      packageId: CLONE_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'identity',
+    });
+    expect(cloneResolved).toMatchObject({ ok: true, value: { status: 'identity' } });
+  });
+
+  it('creates parameterized source and instance documents with CAS-protected value edits', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-instance-'));
+    roots.push(root);
+    const gateway = createFileSystemParameterizedPackAuthoringGateway({ gameRoot: root });
+    const source = await gateway.execute({
+      operation: 'asset-source.create',
+      requestId: 'create-source',
+      targetPath: 'assets/source.pack.ts',
+      format: 'pack.ts',
+      packageId: SOURCE_PACKAGE,
+      parameters: [{ name: 'count', type: 'u32', default: 1, minimum: 1 }],
+    });
+    expect(source).toMatchObject({
+      ok: true,
+      value: { packageId: SOURCE_PACKAGE, format: 'pack.ts' },
+    });
+    const sourceText = await readFile(join(root, 'assets/source.pack.ts'), 'utf8');
+    expect(sourceText).toContain(`definePackageId("${SOURCE_PACKAGE}")`);
+    expect(sourceText).not.toContain('assets:');
+
+    const listed = await gateway.execute({ operation: 'asset.list', requestId: 'list-source' });
+    expect(listed).toMatchObject({
+      ok: true,
+      value: { sources: [{ packageId: SOURCE_PACKAGE, sourcePath: 'assets/source.pack.ts' }] },
+    });
+
+    const instance = await gateway.execute({
+      operation: 'asset-source.create-instance',
+      requestId: 'create-instance',
+      targetPath: 'assets/instance.pack.json',
+      packageId: INSTANCE_PACKAGE,
+      parentPackageId: SOURCE_PACKAGE,
+      values: { count: 4 },
+    });
+    expect(instance).toMatchObject({
+      ok: true,
+      value: {
+        packageId: INSTANCE_PACKAGE,
+        parentPackageId: SOURCE_PACKAGE,
+        effectiveValues: { count: 4 },
+      },
+    });
+    if (!instance.ok) return;
+    const instanceRevision = instance.value.revision;
+    if (instanceRevision === undefined)
+      throw new Error('create-instance did not return a revision');
+    const applied = await gateway.execute({
+      operation: 'asset-source.apply-values',
+      requestId: 'apply-values',
+      sourcePath: 'assets/instance.pack.json',
+      expectedRevision: instanceRevision,
+      values: { count: 5 },
+    });
+    expect(applied).toMatchObject({ ok: true, value: { effectiveValues: { count: 5 } } });
+    const stale = await gateway.execute({
+      operation: 'asset-source.apply-values',
+      requestId: 'apply-stale',
+      sourcePath: 'assets/instance.pack.json',
+      expectedRevision: instanceRevision,
+      values: { count: 6 },
+    });
+    expect(stale).toMatchObject({ ok: false, error: { code: 'pack-source-revision-conflict' } });
+  });
+
+  it('fails closed when the current materialized projection violates derived identity', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-projection-'));
+    roots.push(root);
+    const gateway = createFileSystemParameterizedPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => [
+        {
+          packageId: DIRECT_PACKAGE,
+          sourceKey: 'mesh/main',
+          guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/other')),
+          kind: 'mesh',
+          ready: true,
+        },
+      ],
+    });
+
+    const result = await gateway.execute({ operation: 'asset.list', requestId: 'bad-projection' });
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'pack-guid-collision',
+        detail: {
+          expectedGuid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+        },
+      },
+    });
+  });
+
+  it('does not fall back from a missing sourcePath to another package locator', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-locator-'));
+    roots.push(root);
+    const gateway = createFileSystemParameterizedPackAuthoringGateway({ gameRoot: root });
+    await gateway.execute({
+      operation: 'asset-source.create',
+      requestId: 'create-locator-source',
+      targetPath: 'assets/direct.pack.json',
+      format: 'pack.json',
+      packageId: DIRECT_PACKAGE,
+      initialAssets: {},
+    });
+    const result = await gateway.execute({
+      operation: 'asset.inspect',
+      requestId: 'inspect-missing-locator',
+      sourcePath: 'assets/missing.pack.json',
+      packageId: DIRECT_PACKAGE,
+    });
+    expect(result).toMatchObject({ ok: false, error: { code: 'pack-source-not-found' } });
+  });
+
+  it('converts a broken materialized projection callback into a structured error', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-projection-callback-'));
+    roots.push(root);
+    const gateway = createFileSystemParameterizedPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => {
+        throw new Error('projection unavailable');
+      },
+    });
+    const result = await gateway.execute({ operation: 'asset.list', requestId: 'bad-callback' });
+    expect(result).toMatchObject({ ok: false, error: { code: 'pack-parameter-invalid' } });
+  });
+});