@forgeax/engine-pack 0.1.21 → 0.1.24

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__/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: [] } } }),
             },
           }),
         },
@@ -123,14 +120,12 @@ describe('engine-pack scanner inventory contract', () => {
       format: 'pack.ts',
       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' ? scriptableDeclaration.value : undefined,
+    ).not.toHaveProperty('subAssets');
   });
 
   it('releases the ScriptablePack loader for the path-only scan contract', async () => {
@@ -140,18 +135,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 +156,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');
+  });
 });

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

@@ -2,6 +2,7 @@ import { mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { inventoryDigest } from '../inventory/sync.js';
 import { scanInventory } from '../scanner.js';
 
 describe('AssetInventory', () => {
@@ -18,11 +19,8 @@ describe('AssetInventory', () => {
       [
         'const packageId = new Uint8Array(16);',
         'packageId[15] = 1;',
-        'const meshGuid = new Uint8Array(16);',
-        'meshGuid[15] = 2;',
         'export default {',
-        "schemaVersion: '1.0.0', packageId,",
-        "assets: { mesh: { guid: meshGuid, kind: 'mesh' } }, externalAssets: {},",
+        "schemaVersion: '2.0.0', packageId,",
         "build: () => ({ ok: true, value: { mesh: { kind: 'mesh' } } }),",
         '};',
       ].join('\n'),
@@ -48,9 +46,11 @@ describe('AssetInventory', () => {
     expect(declaration).toMatchObject({
       format: 'pack.ts',
       sourcePath,
-      meta: {
-        importer: 'pack-ts',
-        subAssets: [{ guid, sourceKey: 'mesh', kind: 'mesh' }],
+      value: {
+        schemaVersion: '2.0.0',
+        kind: 'scriptable-pack-source',
+        packageId: '00000000-0000-0000-0000-000000000001',
+        source: sourcePath,
       },
     });
   });
@@ -69,8 +69,21 @@ describe('AssetInventory', () => {
     const { inventory, sourcePath } = getFixture();
     const declaration = inventory.declarations.get(sourcePath);
     expect(inventory.inventory).toEqual([]);
-    expect(declaration?.format === 'pack.ts' ? declaration.meta.subAssets : undefined).toEqual([
-      { guid, sourceIndex: 0, sourceKey: 'mesh', kind: 'mesh' },
-    ]);
+    expect(declaration?.format === 'pack.ts' ? declaration.definition : undefined).toMatchObject({
+      packageId: expect.any(Uint8Array),
+      schemaVersion: '2.0.0',
+    });
+  });
+
+  it('keeps semantic identity stable when the source path is renamed', () => {
+    const before = inventoryDigest({
+      declarations: [{ guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] }],
+    });
+    const after = inventoryDigest({
+      declarations: [{ guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] }],
+    });
+
+    expect(after).toBe(before);
+    expect(after).not.toContain('generated.pack.ts');
   });
 });

package/src/__tests__/scriptable-pack-cli.integration.test.ts

@@ -14,14 +14,9 @@ describe('ScriptablePack CLI Meta inspection', () => {
       await writeFile(
         source,
         `
-        const guid = (hex) => new Uint8Array(hex.match(/../g).map((byte) => Number.parseInt(byte, 16)));
         export default {
-          schemaVersion: '1.0.0',
-          packageId: guid('019ffa978b397ad284cc273268591ab4'),
-          assets: {
-            wall: { guid: guid('019ffa97a5ee7645b613043323952808'), kind: 'mesh' }
-          },
-          externalAssets: {},
+          schemaVersion: '2.0.0',
+          packageId: new Uint8Array([1, 159, 250, 151, 139, 57, 122, 210, 132, 204, 39, 50, 104, 89, 26, 180]),
           build() { throw new Error('META_MUST_NOT_BUILD'); }
         };
       `,
@@ -36,9 +31,9 @@ describe('ScriptablePack CLI Meta inspection', () => {
       expect(code).toBe(0);
       expect(stderr).toEqual([]);
       expect(JSON.parse(stdout[0] ?? '{}')).toMatchObject({
-        importer: 'pack-ts',
+        kind: 'scriptable-pack-source',
         source,
-        subAssets: [{ sourceKey: 'wall', kind: 'mesh' }],
+        packageId: '019ffa97-8b39-7ad2-84cc-273268591ab4',
       });
     } finally {
       await rm(root, { recursive: true, force: true });

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

@@ -82,4 +82,27 @@ describe('diffTopology', () => {
     expect(result.preserved).toEqual([]);
     expect(result.ambiguous).toMatchObject([{ reason: 'duplicate-source-key' }]);
   });
+
+  it('keeps LOD source keys prefix-stable while allowing a suffix level', () => {
+    const result = diffTopology(
+      [
+        { guid: 'root', sourceKey: 'mesh/root', sourceIndex: 0, kind: 'mesh' },
+        { guid: 'lod1', sourceKey: 'mesh/lod1', sourceIndex: 1, kind: 'mesh' },
+      ],
+      [
+        { guid: 'root-next', sourceKey: 'mesh/root', sourceIndex: 0, kind: 'mesh' },
+        { guid: 'lod1-next', sourceKey: 'mesh/lod1', sourceIndex: 1, kind: 'mesh' },
+        { guid: 'lod2-next', sourceKey: 'mesh/lod2', sourceIndex: 2, kind: 'mesh' },
+      ],
+    );
+    expect(result.preserved).toEqual([
+      { guid: 'root', oldKey: 'mesh/root', newKey: 'mesh/root' },
+      { guid: 'lod1', oldKey: 'mesh/lod1', newKey: 'mesh/lod1' },
+    ]);
+    expect(result.added).toEqual([
+      { guid: 'lod2-next', sourceKey: 'mesh/lod2', sourceIndex: 2, kind: 'mesh' },
+    ]);
+    expect(result.removed).toEqual([]);
+    expect(result.ambiguous).toEqual([]);
+  });
 });

package/src/build.ts

@@ -51,7 +51,6 @@ export {
   projectRuntimeCatalogRow,
   type RuntimeCatalogRowInput,
 } from './catalog-projection.js';
-export { type LoadAssetConfigResult, loadAssetConfig } from './config.js';
 export {
   type CookedMaterialRecord,
   collectMaterialCookRefs,
@@ -68,6 +67,22 @@ export {
   validateMaterialCookReceipt,
 } from './evidence/material-cook.js';
 export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';
+export {
+  AssetGuid,
+  isValidAssetGuidString,
+  isValidPackSourceKey,
+  PACK_SOURCE_KEY_RE,
+  PackageId,
+} from './guid.js';
+export { projectAssetRefs, projectSceneEntityRefs } from './inventory/binding.js';
+export {
+  type AuthorInventory,
+  type AuthorInventoryRow,
+  type InventoryError,
+  type InventoryErrorCode,
+  validateAuthorInventory,
+} from './inventory/declaration.js';
+export { inventoryDigest, syncAuthorInventory } from './inventory/sync.js';
 export {
   decodeMeshBinHeader,
   MESH_BIN_DIGEST_BYTES,
@@ -79,9 +94,14 @@ export {
   type MeshBinHeaderV4,
   writeMeshBinHeader,
 } from './mesh-bin-contract.js';
+export * from './pack-authoring.js';
+export {
+  createFileSystemPackAuthoringGateway,
+  createFileSystemPackAuthoringPort,
+  type FileSystemPackAuthoringOptions,
+  type PackAuthoringMaterializedAsset,
+} from './pack-authoring-node.js';
 export {
-  type AuthoredPackAssetInput,
-  type AuthoredPackInput,
   type FinalizedPackageProduct,
   finalizePackageProduct,
   finalizePackageTransportSource,
@@ -92,7 +112,6 @@ export {
   type PackageProduct,
   type PackageProductAsset,
   packageTransportRevision,
-  upgradeLegacyAuthoredPack,
 } from './package-finalizer.js';
 export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 export { resolveAssetSource } from './resolve-asset-source.js';
@@ -107,8 +126,13 @@ export {
 } from './runtime-publication.js';
 export {
   type InventoryDeclaration,
+  type LegacyPackInventoryDocument,
+  type PackInventoryAsset,
+  type PackInventoryDocument,
+  type PackSourceInventoryDocument,
   type ScanInventory,
   type ScanOptions,
+  type ScanSourceDeclaration,
   type ScriptablePackInventoryDeclaration,
   type ScriptablePackScanOptions,
   STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS,
@@ -117,24 +141,10 @@ export {
 export {
   type AssetReader,
   isScriptablePackAssetKind,
-  projectScriptablePackMeta,
   projectScriptablePackSceneComponents,
   SCRIPTABLE_PACK_ASSET_KINDS,
-  SCRIPTABLE_PACK_CAPABILITY_MANIFEST,
-  type ScriptablePackAssetDeclaration,
-  type ScriptablePackAssetDeclarations,
-  type ScriptablePackAssetFor,
   type ScriptablePackAssetKind,
-  type ScriptablePackDefinition,
-  type ScriptablePackError,
-  type ScriptablePackExternalAssets,
-  type ScriptablePackMetaJson,
-  type ScriptablePackOutputs,
-  type ScriptablePackPublicationEnvelope,
   type ScriptablePackReadError,
-  type ScriptablePackSceneComponent,
-  type ScriptablePackSceneComponentInput,
   type ScriptablePackSourceClosureEntry,
-  validateScriptablePackDefinition,
 } from './scriptable-pack.js';
 export { calculateTopologyDiff, diffTopology } from './topology.js';