@forgeax/engine-pack 0.1.20 → 0.1.23

package/src/resolve-asset-source.ts

@@ -1,88 +1,16 @@
-import { dirname, posix, resolve } from 'node:path';
-import type { Result } from '@forgeax/engine-types';
-import { PACK_ERROR_HINTS, err as resultErr, ok as resultOk } from '@forgeax/engine-types';
+import { dirname, resolve } from 'node:path';
 import { deriveAssetName } from './deriveAssetName.js';
-import { PackError } from './errors.js';
 
 function deriveSourceName(metaFileName: string): string {
   return metaFileName.replace(/\.meta\.json$/, '');
 }
 
-const PATH_REF_RE = /^@([^/]+)\/(.+)$/;
-
-function isPathEscape(pathDir: string, resolved: string): boolean {
-  const rel = posix.relative(pathDir, resolved);
-  return rel.startsWith('..') || posix.isAbsolute(rel);
-}
-
-export function resolveAssetSource(
-  metaPath: string,
-  source: string | undefined,
-  paths: Record<string, string>,
-): Result<string, PackError> {
+export function resolveAssetSource(metaPath: string, source: string | undefined): string {
   if (source === undefined) {
     const metaDir = dirname(metaPath);
     const metaName = deriveAssetName(metaPath, 1);
     const derived = deriveSourceName(metaName);
-    return resultOk(resolve(metaDir, derived));
+    return resolve(metaDir, derived);
   }
-
-  if (source.startsWith('@')) {
-    const match = source.match(PATH_REF_RE);
-    if (!match) {
-      return resultErr(
-        new PackError({
-          code: 'pack-malformed-path-ref',
-          expected: 'source in format @<name>/<rest>',
-          hint: PACK_ERROR_HINTS['pack-malformed-path-ref'],
-          detail: {
-            code: 'pack-malformed-path-ref',
-            reason: 'format',
-            rawSource: source,
-            expectedFormat: '@<name>/<rest>',
-          },
-        }),
-      );
-    }
-
-    const [, name, rest] = match as [string, string, string];
-    const pathDir = paths[name];
-
-    if (pathDir === undefined) {
-      return resultErr(
-        new PackError({
-          code: 'pack-unknown-path',
-          expected: 'path name found in package.json#forgeax.assets.paths',
-          hint: PACK_ERROR_HINTS['pack-unknown-path'],
-          detail: {
-            code: 'pack-unknown-path',
-            pathName: name,
-            knownNames: Object.keys(paths),
-          },
-        }),
-      );
-    }
-
-    const resolved = resolve(pathDir, rest);
-
-    if (isPathEscape(pathDir, resolved)) {
-      return resultErr(
-        new PackError({
-          code: 'pack-malformed-path-ref',
-          expected: 'rest path must not escape the declared path directory',
-          hint: PACK_ERROR_HINTS['pack-malformed-path-ref'],
-          detail: {
-            code: 'pack-malformed-path-ref',
-            reason: 'escape',
-            rawSource: source,
-            expectedFormat: '@<name>/<rest>',
-          },
-        }),
-      );
-    }
-
-    return resultOk(resolved);
-  }
-
-  return resultOk(resolve(dirname(metaPath), source));
+  return resolve(dirname(metaPath), source);
 }

package/src/scanner.ts

@@ -9,21 +9,22 @@ import type {
   SourceOverrideDescriptor,
 } from '@forgeax/engine-types';
 import { PACK_ERROR_HINTS } from '@forgeax/engine-types';
-import { loadAssetConfig } from './config.js';
 import { PackError } from './errors.js';
-import { isValidAssetGuidString } from './guid.js';
+import { isValidAssetGuidString, PackageId } from './guid.js';
+import {
+  type AnyParameterizedPackDefinition,
+  type ParameterizedPackSourceMeta,
+  parseParameterizedPackJson,
+  projectDirectPackJson,
+  projectParameterizedPackMeta,
+} from './parameterized-pack.js';
 import { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 import { resolveAssetSource } from './resolve-asset-source.js';
 import { validateMeta, validatePack } from './schema-compiled.js';
-import {
-  projectScriptablePackMeta,
-  type ScriptablePackDefinition,
-  type ScriptablePackMetaJson,
-  type ScriptablePackSourceClosureEntry,
-} from './scriptable-pack.js';
+import type { ScriptablePackSourceClosureEntry } from './scriptable-pack.js';
 import {
   inventoryScriptablePackSource,
-  loadScriptablePack,
+  loadParameterizedScriptablePack,
   type ScriptablePackModuleExecutor,
 } from './scriptable-pack-node.js';
 
@@ -41,6 +42,10 @@ function packErr<E>(error: E): ScanResult<never, E> {
   return { ok: false, error };
 }
 
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /** Host-owned source paths that should not enter the Pack catalog. */
 export interface ScanOptions {
   readonly ignorePath?: (path: string) => boolean;
@@ -80,8 +85,8 @@ export interface ScanInventory {
 export interface ScriptablePackInventoryDeclaration {
   readonly sourcePath: string;
   readonly sourceRevision: string;
-  readonly meta: ScriptablePackMetaJson;
-  readonly definition: Readonly<ScriptablePackDefinition>;
+  readonly meta: ParameterizedPackSourceMeta;
+  readonly definition: Readonly<AnyParameterizedPackDefinition>;
   readonly sourceClosure: readonly ScriptablePackSourceClosureEntry[];
 }
 
@@ -110,7 +115,7 @@ export interface MetaInventorySubAsset {
   readonly kind: string;
 }
 
-export interface PackInventoryDocument {
+export interface LegacyPackInventoryDocument {
   readonly schemaVersion: '1.0.0' | '2.0.0';
   readonly kind: 'internal-text-package';
   readonly packageId?: string;
@@ -120,6 +125,18 @@ export interface PackInventoryDocument {
   readonly assets: readonly PackInventoryAsset[];
 }
 
+export interface ParameterizedPackInventoryDocument {
+  readonly schemaVersion: '3.0.0';
+  readonly packageId: string;
+  readonly assets?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly parent?: string;
+  readonly values?: Readonly<Record<string, unknown>>;
+}
+
+export type PackInventoryDocument =
+  | LegacyPackInventoryDocument
+  | ParameterizedPackInventoryDocument;
+
 export interface PackInventoryAsset {
   readonly guid: string;
   readonly kind: string;
@@ -146,12 +163,14 @@ export type ScanSourceDeclaration =
       readonly sourceText: string;
       readonly value: PackInventoryDocument;
     }
-  | ({
-      readonly format: 'pack.ts';
+  | {
+      readonly format: 'pack.ts-parameterized';
       readonly sourcePath: string;
       readonly sourceRevision: string;
-      readonly value: ScriptablePackMetaJson;
-    } & ScriptablePackInventoryDeclaration);
+      readonly value: ParameterizedPackSourceMeta;
+      readonly definition: AnyParameterizedPackDefinition;
+      readonly sourceClosure: readonly ScriptablePackSourceClosureEntry[];
+    };
 
 interface ScanCapture {
   readonly declarations: Map<string, ScanSourceDeclaration>;
@@ -169,6 +188,7 @@ interface ScanCapture {
  */
 const BLACKLIST = new Set([
   'node_modules',
+  '__tests__',
   '.forgeax-harness',
   '.forgeax',
   '.git',
@@ -349,12 +369,99 @@ async function scanValidated(
   // kind stays in the path/detail evidence; identity is the normalized GUID.
   const guidToPath = new Map<string, string>();
   const packRefs = new Map<string, string[]>(); // guid -> refs[]
+  const packageIdToPath = new Map<string, string>();
+  const packageKind = new Map<string, 'legacy' | 'direct' | 'instance' | 'parameterized'>();
+  const instanceParents: {
+    readonly path: string;
+    readonly packageId: string;
+    readonly parent: string;
+  }[] = [];
+
+  function registerPackage(
+    packageId: string | undefined,
+    path: string,
+    kind: 'legacy' | 'direct' | 'instance' | 'parameterized',
+  ): PackError | undefined {
+    if (packageId === undefined) return undefined;
+    const normalized = packageId.toLowerCase();
+    const existing = packageIdToPath.get(normalized);
+    if (existing !== undefined) {
+      return makePackError('pack-guid-collision', {
+        paths: [existing, path],
+        guid: normalized,
+      });
+    }
+    packageIdToPath.set(normalized, path);
+    packageKind.set(normalized, kind);
+    return undefined;
+  }
 
   for (const packPath of packPaths) {
     const loaded = await readValidatedJson(packPath, 'pack-malformed-pack', validatePack);
     if (!loaded.ok) return loaded;
     const { raw, parsed } = loaded.value;
 
+    if (record(parsed) && parsed.schemaVersion === '3.0.0') {
+      const authoring = parseParameterizedPackJson(parsed);
+      if (!authoring.ok) {
+        return packErr(
+          makePackError('pack-malformed-pack', {
+            path: packPath,
+            ajvErrors: [{ instancePath: '', message: authoring.error.code }],
+          }),
+        );
+      }
+      const packageId = authoring.value.packageId;
+      const packageCollision = registerPackage(
+        PackageId.format(packageId),
+        packPath,
+        authoring.value.format,
+      );
+      if (packageCollision !== undefined) return packErr(packageCollision);
+      if (authoring.value.format === 'instance') {
+        instanceParents.push({
+          path: packPath,
+          packageId: PackageId.format(authoring.value.packageId),
+          parent: PackageId.format(authoring.value.parent),
+        });
+      } else {
+        const projected = projectDirectPackJson(authoring.value);
+        if (!projected.ok) {
+          return packErr(
+            makePackError('pack-malformed-pack', {
+              path: packPath,
+              ajvErrors: [{ instancePath: '/assets', message: projected.error.code }],
+            }),
+          );
+        }
+        for (const asset of projected.value.assets) {
+          const normalizedGuid = asset.guid.toLowerCase();
+          const existing = guidToPath.get(normalizedGuid);
+          if (existing !== undefined) {
+            return packErr(
+              makePackError('pack-guid-collision', {
+                paths: [existing, packPath],
+                guid: normalizedGuid,
+              }),
+            );
+          }
+          guidToPath.set(normalizedGuid, packPath);
+          packRefs.set(normalizedGuid, [
+            ...asset.refs.map((ref) => ref.toLowerCase()),
+            ...extractMountSourceGuids(asset),
+          ]);
+        }
+      }
+      capture?.declarations.set(packPath, {
+        format: 'pack.json',
+        sourcePath: packPath,
+        sourceRevision: `sha256:${createHash('sha256').update(raw).digest('hex')}`,
+        sourceText: raw,
+        value: parsed as unknown as ParameterizedPackInventoryDocument,
+      });
+      continue;
+    }
+
     const packageContract = validateProducerContract(parsed);
     if (!packageContract.ok) {
       return packErr(
@@ -366,7 +473,9 @@ async function scanValidated(
     }
 
     // Step 3: validate GUIDs in pack
-    const packObj = parsed as unknown as PackInventoryDocument;
+    const packObj = parsed as unknown as LegacyPackInventoryDocument;
+    const packageCollision = registerPackage(packObj.packageId, packPath, 'legacy');
+    if (packageCollision !== undefined) return packErr(packageCollision);
     for (const asset of packObj.assets) {
       if (
         asset.kind === 'particle-effect' &&
@@ -477,8 +586,9 @@ async function scanValidated(
     });
   }
 
-  // Step 2 + 3 + 5: parse + schema validate + GUID format validate + orphan check for meta files
-  const { paths: assetPaths } = loadAssetConfig(process.cwd());
+  // Step 2 + 3 + 5: parse + schema validate + GUID format validate + orphan check for meta files.
+  // Meta source paths are local to their sidecar: an omitted source names the
+  // companion file and an explicit source is resolved relative to the sidecar.
   for (const metaPath of metaPaths) {
     const loaded = await readValidatedJson(metaPath, 'pack-malformed-meta', validateMeta);
     if (!loaded.ok) return loaded;
@@ -496,6 +606,8 @@ async function scanValidated(
 
     // Step 3: validate GUIDs in meta subAssets
     const metaObj = parsed as unknown as MetaInventoryDocument;
+    const packageCollision = registerPackage(metaObj.packageId, metaPath, 'legacy');
+    if (packageCollision !== undefined) return packErr(packageCollision);
     capture?.declarations.set(metaPath, {
       format: 'meta.json',
       sourcePath: metaPath,
@@ -537,13 +649,7 @@ async function scanValidated(
     }
 
     // Step 5: orphan .meta.json check — the source file declared in meta.source must exist.
-    // Uses resolveAssetSource for three-mode dispatch (undefined derivation / @name/ path table /
-    // relative path), replacing the former hardcoded join(metaDir, metaObj.source).
-    const sourceResolved = resolveAssetSource(metaPath, metaObj.source, assetPaths);
-    if (!sourceResolved.ok) {
-      return packErr(sourceResolved.error);
-    }
-    const expectedSourcePath = sourceResolved.value;
+    const expectedSourcePath = resolveAssetSource(metaPath, metaObj.source);
     try {
       await stat(expectedSourcePath);
     } catch {
@@ -556,7 +662,8 @@ async function scanValidated(
     }
   }
 
-  // ScriptablePack identity enters the same topology and collision authority as JSON declarations.
+  // Parameterized source identity enters the package registry. Its outputs are
+  // intentionally absent until the dynamic build worklist evaluates it.
   for (const sourcePath of scriptablePaths) {
     let source: string;
     try {
@@ -565,17 +672,17 @@ async function scanValidated(
       return packErr(
         makePackError('pack-malformed-meta', {
           path: sourcePath,
-          ajvErrors: [{ instancePath: '', message: 'ScriptablePack source read failed' }],
+          ajvErrors: [{ instancePath: '', message: 'Pack source read failed' }],
         }),
       );
     }
-    const loaded = await loadScriptablePack(sourcePath, {
+    const loaderOptions = {
       ...(opts.scriptablePack ?? {}),
       ...(capture === undefined ? { metadataOnly: true } : {}),
-    });
+    };
+    const loaded = await loadParameterizedScriptablePack(sourcePath, loaderOptions);
     if (!loaded.ok) {
-      const diagnostic =
-        'diagnostic' in loaded.error.detail ? loaded.error.detail.diagnostic : undefined;
+      const diagnostic = loaded.error.detail.diagnostic;
       return packErr(
         makePackError('pack-malformed-meta', {
           path: sourcePath,
@@ -583,9 +690,9 @@ async function scanValidated(
             {
               instancePath: '',
               message:
-                diagnostic === undefined
-                  ? loaded.error.code
-                  : `${loaded.error.code}: ${diagnostic}`,
+                typeof diagnostic === 'string'
+                  ? `${loaded.error.code}: ${diagnostic}`
+                  : loaded.error.code,
             },
           ],
         }),
@@ -598,41 +705,84 @@ async function scanValidated(
       return packErr(
         makePackError('pack-malformed-meta', {
           path: sourcePath,
-          ajvErrors: [{ instancePath: '', message: 'ScriptablePack source closure read failed' }],
+          ajvErrors: [{ instancePath: '', message: 'Pack source closure read failed' }],
         }),
       );
     }
-    const meta = projectScriptablePackMeta(loaded.value, sourcePath);
-    const topology = validateProducerOutputs(meta.subAssets);
-    if (!topology.ok) {
-      return packErr(
-        makePackError('pack-malformed-meta', {
-          path: sourcePath,
-          ajvErrors: [{ instancePath: '/subAssets', message: topology.error.code }],
-        }),
-      );
-    }
-    const declaration = {
+    const packageCollision = registerPackage(
+      PackageId.format(loaded.value.packageId),
+      sourcePath,
+      'parameterized',
+    );
+    if (packageCollision !== undefined) return packErr(packageCollision);
+    const meta = projectParameterizedPackMeta(loaded.value, sourcePath);
+    capture?.declarations.set(sourcePath, {
+      format: 'pack.ts-parameterized',
       sourcePath,
       sourceRevision: `sha256:${createHash('sha256').update(source).digest('hex')}`,
-      meta,
+      value: meta,
       definition: loaded.value,
       sourceClosure,
-    } satisfies ScriptablePackInventoryDeclaration;
-    capture?.declarations.set(sourcePath, {
-      format: 'pack.ts',
-      ...declaration,
-      value: meta,
     });
-    for (const sub of meta.subAssets) {
-      const guid = sub.guid.toLowerCase();
-      const existing = guidToPath.get(guid);
-      if (existing !== undefined) {
+  }
+
+  // v3 instance parent validation happens after all declarations have been
+  // registered, so scan order cannot change missing-parent or cycle results.
+  const parentByPackageId = new Map(
+    instanceParents.map((instance) => [instance.packageId.toLowerCase(), instance]),
+  );
+  for (const instance of instanceParents) {
+    const parentId = instance.parent.toLowerCase();
+    const parentPath = packageIdToPath.get(parentId);
+    if (parentPath === undefined) {
+      return packErr(
+        makePackError('pack-malformed-pack', {
+          path: instance.path,
+          reason: 'pack-parent-not-found',
+          ajvErrors: [
+            {
+              instancePath: '/parent',
+              message: `parent packageId ${instance.parent} was not found`,
+            },
+          ],
+        }),
+      );
+    }
+    const kind = packageKind.get(parentId);
+    if (kind !== 'parameterized' && kind !== 'instance') {
+      return packErr(
+        makePackError('pack-malformed-pack', {
+          path: instance.path,
+          reason: 'pack-parent-not-parameterized',
+          ajvErrors: [
+            {
+              instancePath: '/parent',
+              message: `parent ${instance.parent} is not a parameterized Pack`,
+            },
+          ],
+        }),
+      );
+    }
+  }
+  for (const instance of instanceParents) {
+    const chain = new Set<string>();
+    let current = instance.packageId.toLowerCase();
+    while (true) {
+      if (chain.has(current)) {
         return packErr(
-          makePackError('pack-guid-collision', { paths: [existing, sourcePath], guid }),
+          makePackError('pack-malformed-pack', {
+            path: instance.path,
+            reason: 'pack-parent-cycle',
+            ajvErrors: [
+              { instancePath: '/parent', message: `parent chain repeats packageId ${current}` },
+            ],
+          }),
         );
       }
-      guidToPath.set(guid, sourcePath);
+      chain.add(current);
+      const next = parentByPackageId.get(current);
+      if (next === undefined) break;
+      current = next.parent.toLowerCase();
     }
   }
 
@@ -698,6 +848,38 @@ export async function scanInventory(
   for (const sourcePath of scanned.value) {
     const declaration = declarations.get(sourcePath);
     if (declaration?.format !== 'pack.json') continue;
+    if (declaration.value.schemaVersion === '3.0.0') {
+      const parsed = parseParameterizedPackJson(declaration.value);
+      if (!parsed.ok) {
+        return packErr(
+          makePackError('pack-malformed-pack', {
+            path: sourcePath,
+            ajvErrors: [{ instancePath: '', message: parsed.error.code }],
+          }),
+        );
+      }
+      if (parsed.value.format !== 'direct') continue;
+      const projected = projectDirectPackJson(parsed.value);
+      if (!projected.ok) {
+        return packErr(
+          makePackError('pack-malformed-pack', {
+            path: sourcePath,
+            ajvErrors: [{ instancePath: '/assets', message: projected.error.code }],
+          }),
+        );
+      }
+      for (const [index, asset] of projected.value.assets.entries()) {
+        inventory.push({
+          guid: asset.guid,
+          kind: asset.kind,
+          sourcePath,
+          sourceRevision: declaration.sourceRevision,
+          sourceKey: asset.sourceKey,
+          sourceIndex: index,
+        });
+      }
+      continue;
+    }
     for (const [index, asset] of declaration.value.assets.entries()) {
       inventory.push({
         guid: asset.guid,

package/src/schema-compiled.ts

@@ -152,6 +152,7 @@ export function buildSceneAssetValidator(
     required: ['kind', 'entities'],
     properties: {
       kind: { type: 'string', const: 'scene' },
+      sourceKey: { type: 'string', minLength: 1 },
       entities: {
         type: 'array',
         items: {
@@ -160,6 +161,7 @@ export function buildSceneAssetValidator(
           required: ['localId', 'components'],
           properties: {
             localId: { type: 'integer', minimum: 0 },
+            bindingKey: { type: 'string', minLength: 1 },
             components: {
               type: 'object',
               additionalProperties: false,