@forgeax/engine-pack 0.1.21 → 0.1.23

package/src/__tests__/parameterized-pack-scanner.unit.test.ts

@@ -0,0 +1,123 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { scanEntries } from '../cli-asset.js';
+import { scanInventory } from '../scanner.js';
+
+const SOURCE_PACKAGE = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+const INSTANCE_PACKAGE = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+const DIRECT_PACKAGE = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc';
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  const root = roots.pop();
+  if (root !== undefined) await rm(root, { recursive: true, force: true });
+});
+
+describe('parameterized Pack scanner', () => {
+  it('indexes direct v3 output keys as derived GUIDs without requiring entry GUIDs', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-parameterized-scan-'));
+    roots.push(root);
+    const path = join(root, 'direct.pack.json');
+    await writeFile(
+      path,
+      JSON.stringify({
+        schemaVersion: '3.0.0',
+        packageId: DIRECT_PACKAGE,
+        assets: {
+          'scene/main': {
+            kind: 'scene',
+            payload: { kind: 'scene', nodes: [] },
+            refs: [],
+          },
+        },
+      }),
+    );
+
+    const result = await scanInventory([root]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.inventory).toMatchObject([
+      {
+        kind: 'scene',
+        sourcePath: path,
+        sourceKey: 'scene/main',
+        sourceIndex: 0,
+      },
+    ]);
+    expect(result.value.inventory[0]?.guid).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const listed = await scanEntries([root], {
+      stdoutWrite: (line) => stdout.push(line),
+      stderrWrite: (line) => stderr.push(line),
+    });
+    expect(listed).toMatchObject({
+      ok: true,
+      value: [{ guid: result.value.inventory[0]?.guid, name: 'scene/main' }],
+    });
+    expect(stderr).toEqual([]);
+  });
+
+  it('captures a parameterized source as metadata and resolves an instance parent', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-parameterized-source-scan-'));
+    roots.push(root);
+    await writeFile(
+      join(root, 'source.pack.ts'),
+      [
+        'const packageId = new Uint8Array(16);',
+        'packageId.set([170, 170, 170, 170, 170, 170, 74, 170, 138, 170, 170, 170, 170, 170, 170, 170]);',
+        'export default {',
+        "  schemaVersion: '2.0.0',",
+        '  packageId,',
+        "  parameters: [{ name: 'count', type: 'u32', default: 1 }],",
+        "  build: ({ values }) => ({ ok: true, value: { ['mesh/' + values.count]: { kind: 'mesh', materialSlots: [] } } }),",
+        '};',
+      ].join('\n'),
+    );
+    await writeFile(
+      join(root, 'instance.pack.json'),
+      JSON.stringify({
+        schemaVersion: '3.0.0',
+        packageId: INSTANCE_PACKAGE,
+        parent: SOURCE_PACKAGE,
+        values: { count: 2 },
+      }),
+    );
+
+    const result = await scanInventory([root]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const declaration = result.value.declarations.get(join(root, 'source.pack.ts'));
+    expect(declaration?.format).toBe('pack.ts-parameterized');
+    expect(result.value.inventory).toEqual([]);
+  });
+
+  it('fails closed when an instance parent is missing', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-parameterized-parent-scan-'));
+    roots.push(root);
+    await writeFile(
+      join(root, 'missing.pack.json'),
+      JSON.stringify({
+        schemaVersion: '3.0.0',
+        packageId: INSTANCE_PACKAGE,
+        parent: SOURCE_PACKAGE,
+        values: { count: 2 },
+      }),
+    );
+
+    const result = await scanInventory([root]);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('pack-malformed-pack');
+    expect(result.error.detail).toMatchObject({ reason: 'pack-parent-not-found' });
+  });
+});

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

@@ -0,0 +1,266 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { AssetGuid, PackageId } from '../guid.js';
+import {
+  definePack,
+  definePackageId,
+  type PackParameterInheritanceSubject,
+  parseParameterizedPackJson,
+  projectDirectPackJson,
+  resolvePackParameterInheritance,
+  resolvePackParameterValues,
+  validatePackDefinition,
+} from '../parameterized-pack.js';
+
+const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+
+function packageId(value: string) {
+  const result = PackageId.parse(value);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('parameterized Pack authoring', () => {
+  it('derives the RFC 4122 UUIDv5 vector and keeps PackageId branded separately', () => {
+    const namespace = packageId(NAMESPACE);
+    expect(AssetGuid.format(AssetGuid.derive(namespace, 'www.widgets.com'))).toBe(
+      '21f7f8de-8051-5b89-8680-0195ef798b6a',
+    );
+    expect(PackageId.format(namespace)).toBe(NAMESPACE);
+    expect(AssetGuid.derive(namespace, 'mesh/a')).not.toBe(namespace);
+  });
+
+  it('derives an explicit context shape for zero-parameter and parameterized Packs', async () => {
+    const zero = definePack({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000001'),
+      build: ({ packageId: subjectId }) =>
+        ok({
+          'scene/main': {
+            kind: 'scene',
+            entities: [],
+            mounts: [],
+            source: AssetGuid.format(AssetGuid.derive(subjectId, 'mesh/main')),
+          },
+        }),
+    });
+    expect('parameters' in zero).toBe(false);
+    const zeroResult = await zero.build({
+      packageId: zero.packageId,
+      readByGuid: async () => ok(null as never),
+    });
+    expect(zeroResult.ok).toBe(true);
+
+    const parameterized = definePack({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000002'),
+      parameters: [
+        { name: 'segments', type: 'u32', default: 12, minimum: 3, maximum: 128 },
+        { name: 'style', type: 'enum', values: ['oak', 'pine'], default: 'oak' },
+      ] as const,
+      build: ({ values }) =>
+        ok({
+          'scene/main': {
+            kind: 'scene',
+            entities: values.segments >= 0 ? [] : [],
+            mounts: [],
+          },
+        }),
+    });
+    const values = resolvePackParameterValues(parameterized, { segments: 24 });
+    expect(values).toMatchObject({ ok: true, value: { segments: 24, style: 'oak' } });
+    expect(resolvePackParameterValues(parameterized, { unknown: true })).toMatchObject({
+      ok: false,
+      error: { code: 'pack-parameter-invalid' },
+    });
+
+    const bounded = definePack({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000003'),
+      parameters: [
+        { name: 'unsigned', type: 'u32', default: 0 },
+        { name: 'signed', type: 'i32', default: 0 },
+        { name: 'float', type: 'f32', default: 0 },
+      ] as const,
+      build: () => ok({}),
+    });
+    expect(resolvePackParameterValues(bounded, { unsigned: 0x1_0000_0000 })).toMatchObject({
+      ok: false,
+      error: { code: 'pack-parameter-invalid' },
+    });
+    expect(resolvePackParameterValues(bounded, { signed: 0x8000_0000 })).toMatchObject({
+      ok: false,
+      error: { code: 'pack-parameter-invalid' },
+    });
+    expect(resolvePackParameterValues(bounded, { float: Number.MAX_VALUE })).toMatchObject({
+      ok: false,
+      error: { code: 'pack-parameter-invalid' },
+    });
+  });
+
+  it('validates and preserves optional scene component schemas without exposing output identity', () => {
+    const definition = definePack({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000004'),
+      sceneComponents: [
+        { name: 'Transform', fields: { pos: { type: 'vec3' }, quat: 'quat' } },
+        { name: 'Name', fields: { value: 'string' } },
+      ],
+      build: () => ok({}),
+    });
+    expect(definition.sceneComponents).toEqual([
+      { name: 'Transform', fields: { pos: { type: 'vec3' }, quat: 'quat' } },
+      { name: 'Name', fields: { value: 'string' } },
+    ]);
+    expect(Object.isFrozen(definition.sceneComponents)).toBe(true);
+    expect(Object.isFrozen(definition.sceneComponents?.[0])).toBe(true);
+    expect(Object.isFrozen(definition.sceneComponents?.[0]?.fields)).toBe(true);
+
+    const duplicate = validatePackDefinition({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000005'),
+      sceneComponents: [
+        { name: 'Transform', fields: {} },
+        { name: 'Transform', fields: {} },
+      ],
+      build: () => ok({}),
+    });
+    expect(duplicate).toMatchObject({
+      ok: false,
+      error: {
+        code: 'pack-parameter-invalid',
+        detail: { reason: 'scene component names must be unique' },
+      },
+    });
+    const malformed = validatePackDefinition({
+      schemaVersion: '2.0.0',
+      packageId: definePackageId('01900000-0000-7000-8000-000000000006'),
+      sceneComponents: [{ name: 'Transform', fields: { pos: { type: '' } } }],
+      build: () => ok({}),
+    });
+    expect(malformed).toMatchObject({
+      ok: false,
+      error: {
+        code: 'pack-parameter-invalid',
+        detail: { reason: 'scene component field schema is malformed' },
+      },
+    });
+  });
+
+  it('parses direct and instance JSON without accepting GUID fields', () => {
+    const direct = parseParameterizedPackJson({
+      schemaVersion: '3.0.0',
+      packageId: '01900000-0000-7000-8000-000000000010',
+      assets: {
+        'scene/main': { kind: 'scene', payload: {}, refs: [] },
+      },
+    });
+    expect(direct.ok).toBe(true);
+    if (direct.ok && direct.value.format === 'direct') {
+      const projected = projectDirectPackJson(direct.value);
+      expect(projected).toMatchObject({
+        ok: true,
+        value: {
+          packageId: '01900000-0000-7000-8000-000000000010',
+          assets: [{ sourceKey: 'scene/main', guid: expect.any(String) }],
+        },
+      });
+    }
+    expect(
+      parseParameterizedPackJson({
+        schemaVersion: '3.0.0',
+        packageId: '01900000-0000-7000-8000-000000000010',
+        assets: { 'scene/main': { guid: NAMESPACE, kind: 'scene', payload: {}, refs: [] } },
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'pack-parameter-invalid' } });
+    expect(
+      parseParameterizedPackJson({
+        schemaVersion: '3.0.0',
+        packageId: '01900000-0000-7000-8000-000000000020',
+        parent: '01900000-0000-7000-8000-000000000002',
+        values: { segments: 24 },
+      }),
+    ).toMatchObject({ ok: true, value: { format: 'instance' } });
+  });
+
+  it('rejects legacy static output fields in the v2 source definition', () => {
+    expect(() =>
+      definePack({
+        schemaVersion: '2.0.0',
+        packageId: definePackageId('01900000-0000-7000-8000-000000000021'),
+        assets: [],
+        build: () => ok({}),
+      } as never),
+    ).toThrow(/repair the parameter declaration|authoring/);
+    expect(() =>
+      definePack({
+        schemaVersion: '2.0.0',
+        packageId: definePackageId('01900000-0000-7000-8000-000000000022'),
+        externalAssets: [],
+        build: () => ok({}),
+      } as never),
+    ).toThrow();
+  });
+
+  it('rejects unknown parameter descriptor fields instead of carrying a second schema', () => {
+    expect(() =>
+      definePack({
+        schemaVersion: '2.0.0',
+        packageId: definePackageId('01900000-0000-7000-8000-000000000023'),
+        parameters: [{ name: 'count', type: 'u32', default: 1, editor: 'slider' }] as never,
+        build: () => ok({}),
+      }),
+    ).toThrow();
+  });
+
+  it('resolves finite shallow inheritance and reports missing parent and cycle', async () => {
+    const rootId = packageId('01900000-0000-7000-8000-000000000030');
+    const middleId = packageId('01900000-0000-7000-8000-000000000031');
+    const leafId = packageId('01900000-0000-7000-8000-000000000032');
+    const root: PackParameterInheritanceSubject = {
+      format: 'source',
+      packageId: rootId,
+      parameters: [{ name: 'segments', type: 'u32', default: 12, minimum: 3 }],
+    };
+    const middle: PackParameterInheritanceSubject = {
+      format: 'instance',
+      packageId: middleId,
+      parent: rootId,
+      values: { segments: 24 },
+    };
+    const leaf: PackParameterInheritanceSubject = {
+      format: 'instance',
+      packageId: leafId,
+      parent: middleId,
+      values: {},
+    };
+    const subjects = new Map<string, PackParameterInheritanceSubject>([
+      [PackageId.format(rootId), root],
+      [PackageId.format(middleId), middle],
+    ]);
+    const resolved = await resolvePackParameterInheritance(leaf, (id) =>
+      subjects.get(PackageId.format(id)),
+    );
+    expect(resolved).toMatchObject({
+      ok: true,
+      value: {
+        values: { segments: 24 },
+        parentChain: [PackageId.format(middleId), PackageId.format(rootId)],
+      },
+    });
+
+    const missing = await resolvePackParameterInheritance(leaf, () => undefined);
+    expect(missing).toMatchObject({ ok: false, error: { code: 'pack-parent-not-found' } });
+
+    const cycleA: PackParameterInheritanceSubject = {
+      format: 'instance',
+      packageId: middleId,
+      parent: leafId,
+      values: {},
+    };
+    const cycle = await resolvePackParameterInheritance(cycleA, (id) =>
+      PackageId.format(id) === PackageId.format(leafId) ? leaf : cycleA,
+    );
+    expect(cycle).toMatchObject({ ok: false, error: { code: 'pack-parent-cycle' } });
+  });
+});

package/src/__tests__/resolve-asset-source.test.ts

@@ -1,31 +1,16 @@
-// @ts-nocheck — PackErrorDetail is a discriminated union narrowed by runtime .code
-// checks; TS cannot follow the narrowing through PackError.detail.
 import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { resolveAssetSource } from '../resolve-asset-source.js';
 
-describe('resolveAssetSource — omit derivation (w4)', () => {
+describe('resolveAssetSource — companion and sidecar-relative sources', () => {
   const metaDir = '/project/assets';
 
-  it('omitted source derives companion file from meta filename (AC-2)', () => {
+  it('derives an omitted source from the companion filename', () => {
     const metaPath = resolve(metaDir, 'foo.png.meta.json');
-    const result = resolveAssetSource(metaPath, undefined, {});
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toBe(resolve(metaDir, 'foo.png'));
-    }
-  });
-
-  it('renamed audio meta derives correct companion (AC-3)', () => {
-    const metaPath = resolve(metaDir, 'bleep.wav.meta.json');
-    const result = resolveAssetSource(metaPath, undefined, {});
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toBe(resolve(metaDir, 'bleep.wav'));
-    }
+    expect(resolveAssetSource(metaPath, undefined)).toBe(resolve(metaDir, 'foo.png'));
   });
 
-  it('derivation is a single rule: strip .meta.json suffix only', () => {
+  it('supports every ordinary companion extension without a special table', () => {
     const cases = [
       { meta: 'model.glb.meta.json', expected: 'model.glb' },
       { meta: 'sprite.png.meta.json', expected: 'sprite.png' },
@@ -33,89 +18,21 @@ describe('resolveAssetSource — omit derivation (w4)', () => {
       { meta: 'bgm.mp3.meta.json', expected: 'bgm.mp3' },
     ];
     for (const { meta, expected } of cases) {
-      const metaPath = resolve(metaDir, meta);
-      const result = resolveAssetSource(metaPath, undefined, {});
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value).toBe(resolve(metaDir, expected));
-      }
-    }
-  });
-});
-
-describe('resolveAssetSource — @name/ path + boundary + legacy (w5)', () => {
-  const metaDir = '/project/assets';
-  const metaPath = resolve(metaDir, 'foo.png.meta.json');
-
-  it('resolves @name/rest to absolute path via paths table (AC-5)', () => {
-    const paths = { shared: '/lib/assets' };
-    const result = resolveAssetSource(metaPath, '@shared/foo.png', paths);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toBe(resolve('/lib/assets', 'foo.png'));
-    }
-  });
-
-  it('returns pack-unknown-path for undeclared @name (AC-8)', () => {
-    const paths = { shared: '/lib/assets' };
-    const result = resolveAssetSource(metaPath, '@nope/x.png', paths);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('pack-unknown-path');
-      expect(result.error.detail.pathName).toBe('nope');
-      expect(result.error.detail.knownNames).toEqual(['shared']);
+      expect(resolveAssetSource(resolve(metaDir, meta), undefined)).toBe(
+        resolve(metaDir, expected),
+      );
     }
   });
 
-  it('returns pack-malformed-path-ref for bare @ with no name or rest (AC-9)', () => {
-    const result = resolveAssetSource(metaPath, '@', { shared: '/lib/assets' });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('pack-malformed-path-ref');
-      expect(result.error.detail.rawSource).toBe('@');
-      if (result.error.detail.code === 'pack-malformed-path-ref') {
-        expect(result.error.detail.reason).toBe('format');
-      }
-    }
-  });
-
-  it('returns pack-malformed-path-ref for @onlyname with no /rest (AC-9)', () => {
-    const result = resolveAssetSource(metaPath, '@onlyname', { shared: '/lib/assets' });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('pack-malformed-path-ref');
-      expect(result.error.detail.rawSource).toBe('@onlyname');
-    }
-  });
-
-  it('returns pack-malformed-path-ref for ../ escape (AC-11)', () => {
-    const paths = { shared: '/data/shared' };
-    const result = resolveAssetSource(metaPath, '@shared/../escape.png', paths);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('pack-malformed-path-ref');
-      expect(result.error.detail.rawSource).toBe('@shared/../escape.png');
-      if (result.error.detail.code === 'pack-malformed-path-ref') {
-        expect(result.error.detail.reason).toBe('escape');
-      }
-    }
-  });
-
-  it('resolves legacy relative path unchanged', () => {
-    const result = resolveAssetSource(metaPath, 'sub/foo.png', {});
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toBe(resolve(metaDir, 'sub/foo.png'));
-    }
+  it('resolves an explicit source relative to its sidecar', () => {
+    const metaPath = resolve(metaDir, 'foo.png.meta.json');
+    expect(resolveAssetSource(metaPath, 'sub/foo.png')).toBe(resolve(metaDir, 'sub/foo.png'));
   });
 
-  it('returns pack-unknown-path for @name/ when paths is empty', () => {
-    const result = resolveAssetSource(metaPath, '@any/x.png', {});
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('pack-unknown-path');
-      expect(result.error.detail.pathName).toBe('any');
-      expect(result.error.detail.knownNames).toEqual([]);
-    }
+  it('keeps source resolution independent of package.json and path aliases', () => {
+    const metaPath = resolve(metaDir, 'foo.png.meta.json');
+    expect(resolveAssetSource(metaPath, '@shared/foo.png')).toBe(
+      resolve(metaDir, '@shared/foo.png'),
+    );
   });
 });

package/src/__tests__/scanner-blacklist.test.ts

@@ -0,0 +1,55 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { scan } from '../scanner.js';
+
+const EMPTY_PACK = JSON.stringify({
+  schemaVersion: '1.0.0',
+  kind: 'internal-text-package',
+  assets: [],
+});
+
+describe('asset scanner test-directory boundary', () => {
+  const temporaryRoots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      temporaryRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+    );
+  });
+
+  it('skips arbitrarily nested __tests__ declarations while keeping normal assets', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-scanner-tests-'));
+    temporaryRoots.push(root);
+    const visible = join(root, 'world', 'scene.pack.json');
+    const nestedFixture = join(root, 'world', '__tests__', 'fixture.pack.json');
+    const rootFixture = join(root, '__tests__', 'nested', 'fixture.pack.json');
+
+    await mkdir(join(root, 'world', '__tests__'), { recursive: true });
+    await mkdir(join(root, '__tests__', 'nested'), { recursive: true });
+    await writeFile(visible, EMPTY_PACK);
+    // Deliberately malformed: a test fixture must not be able to degrade the
+    // production scan simply because it lives below the asset root.
+    await writeFile(nestedFixture, '{}');
+    await writeFile(rootFixture, '{}');
+
+    const result = await scan([root]);
+
+    expect(result).toMatchObject({ ok: true, value: [visible] });
+  });
+
+  it('allows an explicit __tests__ root when a test intentionally opts in', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-scanner-tests-'));
+    temporaryRoots.push(root);
+    const testRoot = join(root, '__tests__');
+    const fixture = join(testRoot, 'fixture.pack.json');
+
+    await mkdir(testRoot, { recursive: true });
+    await writeFile(fixture, EMPTY_PACK);
+
+    const result = await scan([testRoot]);
+
+    expect(result).toMatchObject({ ok: true, value: [fixture] });
+  });
+});

package/src/__tests__/scanner-inventory.contract.test.ts

@@ -88,17 +88,14 @@ describe('engine-pack scanner inventory contract', () => {
     await writeFile(scriptablePath, '// scanner fixture');
 
     const scriptablePackageId = guid('019e3969-1d48-7c3b-ac24-6d68f4570662');
-    const scriptableAssetGuid = guid('019e3969-1d48-7c3b-ac24-6d68f4570663');
     const result = await scanInventory([root], {
       scriptablePack: {
         executor: {
           load: async () => ({
             default: {
-              schemaVersion: '1.0.0',
+              schemaVersion: '2.0.0',
               packageId: scriptablePackageId,
-              assets: { effect: { guid: scriptableAssetGuid, kind: 'scene' } },
-              externalAssets: {},
-              build: () => ({ ok: true, value: {} }),
+              build: () => ({ ok: true, value: { effect: { kind: 'scene', entities: [] } } }),
             },
           }),
         },
@@ -120,17 +117,17 @@ describe('engine-pack scanner inventory contract', () => {
     });
     const scriptableDeclaration = result.value.declarations.get(scriptablePath);
     expect(scriptableDeclaration).toMatchObject({
-      format: 'pack.ts',
+      format: 'pack.ts-parameterized',
       sourcePath: scriptablePath,
       value: {
-        importer: 'pack-ts',
         packageId: '019e3969-1d48-7c3b-ac24-6d68f4570662',
-        subAssets: [{ sourceKey: 'effect', kind: 'scene' }],
       },
     });
     expect(
-      scriptableDeclaration?.format === 'pack.ts' ? scriptableDeclaration.meta : undefined,
-    ).toBe(scriptableDeclaration?.format === 'pack.ts' ? scriptableDeclaration.value : undefined);
+      scriptableDeclaration?.format === 'pack.ts-parameterized'
+        ? scriptableDeclaration.value
+        : undefined,
+    ).not.toHaveProperty('subAssets');
   });
 
   it('releases the ScriptablePack loader for the path-only scan contract', async () => {
@@ -140,18 +137,15 @@ describe('engine-pack scanner inventory contract', () => {
     await writeFile(scriptablePath, '// scanner fixture');
 
     const packageId = guid('019e3969-1d48-7c3b-ac24-6d68f4570664');
-    const assetGuid = guid('019e3969-1d48-7c3b-ac24-6d68f4570665');
     let disposals = 0;
     const result = await scan([root], {
       scriptablePack: {
         executor: {
           load: async () => ({
             default: {
-              schemaVersion: '1.0.0',
+              schemaVersion: '2.0.0',
               packageId,
-              assets: { effect: { guid: assetGuid, kind: 'scene' } },
-              externalAssets: {},
-              build: () => ({ ok: true, value: {} }),
+              build: () => ({ ok: true, value: { effect: { kind: 'scene', entities: [] } } }),
             },
           }),
           dispose: async () => {
@@ -164,4 +158,9 @@ describe('engine-pack scanner inventory contract', () => {
     expect(result.ok).toBe(true);
     expect(disposals).toBe(1);
   });
+
+  it('characterizes the public scanner inventory vocabulary', () => {
+    expect(typeof scan).toBe('function');
+    expect(typeof scanInventory).toBe('function');
+  });
 });