@forgeax/engine-pack 0.1.21 → 0.1.23

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'),
@@ -46,11 +44,13 @@ describe('AssetInventory', () => {
     const { inventory, sourcePath } = getFixture();
     const declaration = inventory.declarations.get(sourcePath);
     expect(declaration).toMatchObject({
-      format: 'pack.ts',
+      format: 'pack.ts-parameterized',
       sourcePath,
-      meta: {
-        importer: 'pack-ts',
-        subAssets: [{ guid, sourceKey: 'mesh', kind: 'mesh' }],
+      value: {
+        schemaVersion: '2.0.0',
+        kind: 'parameterized-pack-source',
+        packageId: '00000000-0000-0000-0000-000000000001',
+        source: sourcePath,
       },
     });
   });
@@ -59,7 +59,7 @@ describe('AssetInventory', () => {
     const { inventory, sourcePath } = getFixture();
     const declaration = inventory.declarations.get(sourcePath);
     expect(
-      declaration?.format === 'pack.ts'
+      declaration?.format === 'pack.ts-parameterized'
         ? declaration.sourceClosure.map((entry) => entry.path)
         : undefined,
     ).toEqual([await realpath(sourcePath)]);
@@ -69,8 +69,20 @@ 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-parameterized' ? 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: 'parameterized-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,
@@ -80,8 +95,6 @@ export {
   writeMeshBinHeader,
 } from './mesh-bin-contract.js';
 export {
-  type AuthoredPackAssetInput,
-  type AuthoredPackInput,
   type FinalizedPackageProduct,
   finalizePackageProduct,
   finalizePackageTransportSource,
@@ -92,8 +105,14 @@ export {
   type PackageProduct,
   type PackageProductAsset,
   packageTransportRevision,
-  upgradeLegacyAuthoredPack,
 } from './package-finalizer.js';
+export * from './parameterized-pack.js';
+export {
+  createFileSystemParameterizedPackAuthoringGateway,
+  createFileSystemParameterizedPackAuthoringPort,
+  type FileSystemParameterizedPackAuthoringOptions,
+  type ParameterizedPackMaterializedAsset,
+} from './parameterized-pack-node.js';
 export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 export { resolveAssetSource } from './resolve-asset-source.js';
 export { parsePackV2, validateMeta, validatePack, validatePackV2 } from './runtime.js';
@@ -107,8 +126,13 @@ export {
 } from './runtime-publication.js';
 export {
   type InventoryDeclaration,
+  type LegacyPackInventoryDocument,
+  type PackInventoryAsset,
+  type PackInventoryDocument,
+  type ParameterizedPackInventoryDocument,
   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';

package/src/catalog-builder.ts

@@ -5,8 +5,8 @@ import {
   projectExternalCatalogEntries,
   projectPackageCatalog,
 } from './catalog-projection.js';
-import { loadAssetConfig } from './config.js';
 import { deriveAssetName } from './deriveAssetName.js';
+import { parseParameterizedPackJson, projectDirectPackJson } from './parameterized-pack.js';
 import { resolveAssetSource } from './resolve-asset-source.js';
 import {
   type MetaInventoryDocument,
@@ -138,7 +138,6 @@ function projectMeta(
   rawPath: string,
   cwd: string,
   base: string,
-  assetPaths: Record<string, string>,
   importerPolicy: (importer: string) => CatalogImporterPolicy,
   sourceDeclaration: Extract<ScanSourceDeclaration, { readonly format: 'meta.json' }>,
   sourceIdentityFor: CatalogBuildProjectionOptions['sourceIdentityFor'],
@@ -152,22 +151,12 @@ function projectMeta(
   if (policy.disposition !== 'publish') {
     return { entries: [], error: unsupportedPolicyError(rawPath, meta.importer, policy) };
   }
-  const resolved = resolveAssetSource(rawPath, meta.source, assetPaths);
-  if (!resolved.ok) {
-    return {
-      entries: [],
-      error: {
-        code: 'catalog-meta-schema-invalid',
-        path: rawPath,
-        message: `source resolution failed: ${resolved.error.code} - ${resolved.error.hint}`,
-      },
-    };
-  }
-  const sourcePath = catalogSourcePathFor(cwd, resolved.value, sourceIdentityFor);
+  const resolved = resolveAssetSource(rawPath, meta.source);
+  const sourcePath = catalogSourcePathFor(cwd, resolved, sourceIdentityFor);
   const packageUrl = `${base}/__forgeax-ddc/${meta.subAssets[0]?.guid?.toLowerCase() ?? 'pack'}.pack.json`;
   const declaration: CatalogImportMeta = {
     importer: meta.importer,
-    source: resolved.value,
+    source: resolved,
     sourceRevision: sourceDeclaration.sourceRevision,
     ...(meta.packageId === undefined ? {} : { packageId: meta.packageId }),
     ...(meta.provenance === undefined ? {} : { provenance: meta.provenance }),
@@ -197,7 +186,7 @@ function projectMeta(
   return {
     declaration,
     entries: projectExternalCatalogEntries(meta, sourcePath, packageUrl, meta.subAssets, (output) =>
-      deriveAssetName(resolved.value, meta.subAssets.length, output.name),
+      deriveAssetName(resolved, meta.subAssets.length, output.name),
     ),
   };
 }
@@ -206,27 +195,17 @@ function projectSource(
   path: string,
   cwd: string,
   base: string,
-  assetPaths: Record<string, string>,
   importerPolicy: (importer: string) => CatalogImporterPolicy,
   visibility: CatalogBuildProjectionOptions['visibility'],
   sourceDeclaration: ScanSourceDeclaration,
   declarations: Map<string, CatalogImportMeta>,
   sourceIdentityFor: CatalogBuildProjectionOptions['sourceIdentityFor'],
 ): { readonly entries: PackIndexEntry[]; readonly error?: CatalogBuildError } {
-  if (sourceDeclaration.format === 'pack.ts') {
-    const meta = { ...sourceDeclaration.meta, source: sourcePathFor(cwd, path) };
-    const anchorGuid = meta.subAssets.map((asset) => asset.guid.toLowerCase()).sort()[0];
-    return anchorGuid === undefined
-      ? { entries: [] }
-      : {
-          entries: projectExternalCatalogEntries(
-            meta,
-            catalogSourcePathFor(cwd, path, sourceIdentityFor),
-            `${base}/__forgeax-ddc/${anchorGuid}.pack.json`,
-            meta.subAssets,
-            (output) => deriveAssetName(path, meta.subAssets.length, output.name),
-          ),
-        };
+  if (sourceDeclaration.format === 'pack.ts-parameterized') {
+    // A source declaration is an authoring identity and parameter contract,
+    // not a materialized output set. Dynamic build owns publication after its
+    // fixed-point worklist converges; Catalog scanning must not invent rows.
+    return { entries: [] };
   }
   if (sourceDeclaration.format === 'meta.json') {
     const policy = importerPolicy(sourceDeclaration.value.importer);
@@ -244,7 +223,6 @@ function projectSource(
       path,
       cwd,
       base,
-      assetPaths,
       importerPolicy,
       sourceDeclaration,
       sourceIdentityFor,
@@ -254,6 +232,57 @@ function projectSource(
   }
   const parsed = sourceDeclaration.value;
   const sourcePath = catalogSourcePathFor(cwd, path, sourceIdentityFor);
+  if (parsed.schemaVersion === '3.0.0') {
+    const authoring = parseParameterizedPackJson(parsed);
+    if (!authoring.ok) {
+      return {
+        entries: [],
+        error: {
+          code: 'catalog-meta-schema-invalid',
+          path,
+          message: `v3 Pack parse failed: ${authoring.error.code}`,
+          expected: 'a valid direct or instance v3 Pack document',
+          actual: authoring.error.code,
+          hint: authoring.error.hint,
+          subjects: [path],
+        },
+      };
+    }
+    if (authoring.value.format !== 'direct') return { entries: [] };
+    const projected = projectDirectPackJson(authoring.value);
+    if (!projected.ok) {
+      return {
+        entries: [],
+        error: {
+          code: 'catalog-meta-schema-invalid',
+          path,
+          message: `v3 Pack projection failed: ${projected.error.code}`,
+          expected: 'direct v3 assets to derive stable AssetGuids',
+          actual: projected.error.code,
+          hint: projected.error.hint,
+          subjects: [path],
+        },
+      };
+    }
+    const provenance = { provider: 'pack', version: '3.0.0' } satisfies ProviderProvenance;
+    return {
+      entries: projectPackageCatalog(
+        projected.value.assets.map((asset, sourceIndex) => ({
+          guid: asset.guid,
+          kind: asset.kind,
+          sourcePath,
+          sourceIndex,
+          sourceKey: asset.sourceKey,
+          refs: asset.refs,
+          execution: 'direct' as const,
+          packageId: projected.value.packageId,
+          provenance,
+          name: deriveAssetName(path, projected.value.assets.length, asset.name),
+        })),
+        `${base}/${sourcePath}`,
+      ),
+    };
+  }
   const provenance =
     parsed.provenance ??
     ({ provider: 'pack', version: parsed.schemaVersion } satisfies ProviderProvenance);
@@ -317,7 +346,6 @@ export async function buildCatalogProjection(
     return empty('degraded', [error]);
   }
   const { paths, declarations: sourceDeclarations } = scanned.value;
-  const { paths: assetPaths } = loadAssetConfig(cwd);
   const entries: PackIndexEntry[] = [];
   const errors: CatalogBuildError[] = [];
   const declarations = new Map<string, CatalogImportMeta>();
@@ -328,7 +356,6 @@ export async function buildCatalogProjection(
       path,
       cwd,
       base,
-      assetPaths,
       options.importerPolicy,
       options.visibility,
       sourceDeclaration,

package/src/cli-asset.ts

@@ -26,9 +26,9 @@ import {
 import { readSourceInventory } from './evidence/source-inventory.js';
 import { isValidAssetGuidString } from './guid.js';
 import { parsePackV2 } from './index.js';
-import { scan } from './scanner.js';
-import { isRecord, projectScriptablePackMeta } from './scriptable-pack.js';
-import { loadScriptablePack } from './scriptable-pack-node.js';
+import { projectParameterizedPackMeta } from './parameterized-pack.js';
+import { type ScanSourceDeclaration, scanInventory } from './scanner.js';
+import { loadParameterizedScriptablePack } from './scriptable-pack-node.js';
 
 export interface PackEntry {
   readonly guid: string;
@@ -51,6 +51,10 @@ interface ScanErrShape {
   detail?: unknown;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 function emitError(ctx: AssetCtx, err: ScanErrShape): number {
   const payload: Record<string, unknown> = {
     code: err.code,
@@ -66,7 +70,7 @@ export async function scanEntries(
   roots: readonly string[],
   ctx: AssetCtx,
 ): Promise<{ ok: true; value: PackEntry[] } | { ok: false }> {
-  const result = await scan(roots);
+  const result = await scanInventory(roots);
   if (!result.ok) {
     emitError(ctx, {
       code: result.error.code,
@@ -77,94 +81,73 @@ export async function scanEntries(
     return { ok: false };
   }
   const entries: PackEntry[] = [];
-  // Two file kinds carry GUID-addressed entries (disk schema SSOT, AGENTS.md
-  // §Disk schema): `.pack.json` (`internal-text-package`) holds top-level
-  // `assets[]`, while every `*.meta.json` sidecar (including
-  // any `*.meta.json` regardless of source extension (top-level `importer`), all of
-  // kind `external-asset-package`) holds `subAssets[]`. The CLI surface
-  // must enumerate both so that `scan` / `lookup` mirror what the
-  // build-time catalog builder folds into `pack-index.json` (otherwise
-  // the same disk schema yields different entity counts on the two
-  // surfaces — observed regression in feat-20260517 sandbox T-2.B1).
-  const packPaths = result.value.filter((p) => p.endsWith('.pack.json'));
-  const metaPaths = result.value.filter((p) => p.endsWith('.meta.json'));
-  for (const packPath of packPaths) {
-    let parsed: unknown;
-    try {
-      const raw = await readFile(packPath, 'utf-8');
-      parsed = JSON.parse(raw);
-    } catch {
-      continue;
-    }
-    const packObj = parsed as { assets?: { guid?: unknown; kind?: unknown; name?: unknown }[] };
-    if (!Array.isArray(packObj.assets)) continue;
-    for (const asset of packObj.assets) {
-      if (typeof asset.guid === 'string' && typeof asset.kind === 'string') {
-        entries.push({
-          guid: asset.guid,
-          kind: asset.kind,
-          sourcePath: packPath,
-          ...(typeof asset.name === 'string' ? { name: asset.name } : {}),
-        });
+  // The scanner is the single identity projection for Pack JSON. Parameterized
+  // source modules deliberately contribute no rows until a build generation.
+  for (const declaration of result.value.declarations.values()) {
+    if (declaration.format !== 'meta.json') continue;
+    const sourcePath = declaration.sourcePath;
+    const assets = declaration.value.subAssets;
+    for (const asset of assets) {
+      if (!isRecord(asset) || typeof asset.guid !== 'string' || typeof asset.kind !== 'string') {
+        continue;
       }
+      const name =
+        typeof asset.name === 'string'
+          ? asset.name
+          : typeof asset.sourceKey === 'string'
+            ? asset.sourceKey
+            : undefined;
+      entries.push({
+        guid: asset.guid,
+        kind: asset.kind,
+        sourcePath,
+        ...(name === undefined ? {} : { name }),
+      });
     }
   }
-  for (const metaPath of metaPaths) {
-    let parsed: unknown;
-    try {
-      const raw = await readFile(metaPath, 'utf-8');
-      parsed = JSON.parse(raw);
-    } catch {
+  const names = new Map<string, string>();
+  for (const declaration of result.value.declarations.values()) {
+    if (declaration.format !== 'pack.json') continue;
+    if (declaration.value.schemaVersion === '3.0.0') {
+      for (const [sourceKey, asset] of Object.entries(declaration.value.assets ?? {})) {
+        if (isRecord(asset) && typeof asset.name === 'string') {
+          names.set(`${declaration.sourcePath}:${sourceKey}`, asset.name);
+        }
+      }
       continue;
     }
-    const metaObj = parsed as {
-      subAssets?: { guid?: unknown; kind?: unknown; name?: unknown; sourceKey?: unknown }[];
-    };
-    if (!Array.isArray(metaObj.subAssets)) continue;
-    for (const sub of metaObj.subAssets) {
-      if (typeof sub.guid === 'string' && typeof sub.kind === 'string') {
-        const name =
-          typeof sub.name === 'string'
-            ? sub.name
-            : typeof sub.sourceKey === 'string'
-              ? sub.sourceKey
-              : undefined;
-        entries.push({
-          guid: sub.guid,
-          kind: sub.kind,
-          sourcePath: metaPath,
-          ...(name === undefined ? {} : { name }),
-        });
+    for (const asset of declaration.value.assets) {
+      if (typeof asset.name === 'string') {
+        names.set(`${declaration.sourcePath}:${asset.guid.toLowerCase()}`, asset.name);
       }
     }
   }
-  for (const sourcePath of result.value.filter((path) => path.endsWith('.pack.ts'))) {
-    const loaded = await loadScriptablePack(sourcePath, { metadataOnly: true });
-    if (!loaded.ok) {
-      emitError(ctx, loaded.error);
-      return { ok: false };
-    }
-    const meta = projectScriptablePackMeta(loaded.value, sourcePath);
-    for (const sub of meta.subAssets) {
-      entries.push({ guid: sub.guid, kind: sub.kind, sourcePath });
-    }
-  }
-  const firstByGuid = new Map<string, PackEntry>();
-  for (const entry of entries) {
-    const guid = entry.guid.toLowerCase();
-    const first = firstByGuid.get(guid);
-    if (first !== undefined) {
-      emitError(ctx, {
-        code: 'pack-guid-collision',
-        expected:
-          'one author declaration per GUID across Meta, Pack v2, and ScriptablePack sources',
-        hint: 'allocate a new durable GUID through the asset authoring gateway, then rerun verify',
-        detail: { guid, paths: [first.sourcePath, entry.sourcePath] },
-      });
-      return { ok: false };
-    }
-    firstByGuid.set(guid, entry);
+  for (const inventoryEntry of result.value.inventory) {
+    const declaration = result.value.declarations.get(inventoryEntry.sourcePath) as
+      | ScanSourceDeclaration
+      | undefined;
+    const namedByKey =
+      inventoryEntry.sourceKey === undefined
+        ? names.get(`${inventoryEntry.sourcePath}:${inventoryEntry.guid.toLowerCase()}`)
+        : names.get(`${inventoryEntry.sourcePath}:${inventoryEntry.sourceKey}`);
+    const name =
+      namedByKey ?? names.get(`${inventoryEntry.sourcePath}:${inventoryEntry.guid.toLowerCase()}`);
+    entries.push({
+      guid: inventoryEntry.guid,
+      kind: inventoryEntry.kind,
+      sourcePath: inventoryEntry.sourcePath,
+      ...(name === undefined ? {} : { name }),
+      ...(declaration?.format === 'pack.json' &&
+      declaration.value.schemaVersion === '3.0.0' &&
+      inventoryEntry.sourceKey !== undefined &&
+      name === undefined
+        ? { name: inventoryEntry.sourceKey }
+        : {}),
+    });
   }
+  entries.sort((left, right) =>
+    `${left.sourcePath}:${left.guid}`.localeCompare(`${right.sourcePath}:${right.guid}`),
+  );
   return { ok: true, value: entries };
 }
 
@@ -250,9 +233,11 @@ async function runMeta(rest: string[], ctx: AssetCtx): Promise<number> {
     });
   }
   const cwd = ctx.cwd ?? process.cwd();
-  const loaded = await loadScriptablePack(absolutePath(source, cwd), { metadataOnly: true });
+  const loaded = await loadParameterizedScriptablePack(absolutePath(source, cwd), {
+    metadataOnly: true,
+  });
   if (!loaded.ok) return emitError(ctx, loaded.error);
-  ctx.stdoutWrite(JSON.stringify(projectScriptablePackMeta(loaded.value, source)));
+  ctx.stdoutWrite(JSON.stringify(projectParameterizedPackMeta(loaded.value, source)));
   return 0;
 }
 

package/src/deriveAssetName.ts

@@ -16,27 +16,28 @@ function baseName(p: string): string {
  *
  * Pure function -- zero IO, zero side effects, browser-safe. Build-time
  * (build-catalog) and runtime (resolveName) share this single source of truth
- * for the XOR name-resolution rules (plan-strategy D-6).
+ * for deterministic asset display-name resolution.
  *
- * Branches:
- *   1. single-asset package (assetCount === 1)      -> baseName(packagePath)
- *   2. multi-asset package + storedName              -> storedName
- *   3. multi-asset package + no storedName (AC-15.1) -> baseName(packagePath)
- *   4. null packagePath + no storedName  (AC-15.2)   -> ''
+ * Resolution contract:
+ *   - an explicit storedName is authoritative;
+ *   - a package path is the fallback when no storedName is present;
+ *   - an asset without a package and without a storedName resolves to ''.
+ *
+ * `assetCount` remains in the signature because callers derive it from their
+ * package model, but it must not erase an explicitly authored name. In
+ * particular, a single authored entry in `Materials.pack.json` resolves to its
+ * entry name rather than temporarily appearing as the package basename.
  */
 export function deriveAssetName(
   packagePath: string | null,
-  assetCount: number,
+  _assetCount: number,
   storedName?: string,
 ): string {
-  if (packagePath === null) {
-    return storedName ?? '';
-  }
-  if (assetCount === 1) {
-    return baseName(packagePath);
-  }
   if (storedName !== undefined) {
     return storedName;
   }
+  if (packagePath === null) {
+    return '';
+  }
   return baseName(packagePath);
 }