@forgeax/engine-import 0.1.23 → 0.1.24

package/src/build-production.ts

@@ -11,11 +11,11 @@ import type { NativeCooker } from '@forgeax/engine-pack/native-cooker';
 import type { LegacyPackInventoryDocument } from '@forgeax/engine-pack/scanner';
 import {
   PackageId,
-  parseParameterizedPackJson,
+  parsePackSourceJson,
   projectDirectPackJson,
   resolvePackParameterInheritance,
 } from '@forgeax/engine-pack/source';
-import { loadParameterizedScriptablePack } from '@forgeax/engine-pack/source-node';
+import { loadScriptablePack } from '@forgeax/engine-pack/source-node';
 import type {
   AssetPublicationEnvelope,
   AssetPublicationOutput,
@@ -30,11 +30,11 @@ import { projectImportProductForBuild } from './pack-projection.js';
 import {
   canonicalScriptableSourcePath,
   declaredPackExternalOutputs,
-  type ParameterizedScriptablePackInput,
-  type PreparedParameterizedScriptablePack,
+  type PreparedScriptablePack,
   prepareDirectPackTransport,
   prepareLegacyPackTransport,
-  produceParameterizedScriptablePackProducts,
+  produceScriptablePackProducts,
+  type ScriptablePackInput,
 } from './scriptable-pack-host.js';
 import {
   finalizeSourcePackage,
@@ -133,21 +133,21 @@ function sourceKeysFor(
   );
 }
 
-interface ParameterizedBuildBundle {
-  readonly input: ParameterizedScriptablePackInput;
-  readonly prepared: PreparedParameterizedScriptablePack;
+interface PackBuildBundle {
+  readonly input: ScriptablePackInput;
+  readonly prepared: PreparedScriptablePack;
   readonly entries: readonly PackIndexEntry[];
 }
 
-type ParameterizedSourceSubject = {
+type PackSourceSubject = {
   readonly kind: 'source';
   readonly packageId: PackageId;
   readonly sourcePath: string;
-  readonly definition: import('@forgeax/engine-pack/source').AnyParameterizedPackDefinition;
+  readonly definition: import('@forgeax/engine-pack/source').AnyScriptablePackDefinition;
   readonly sourceClosure: readonly import('@forgeax/engine-pack/source').ScriptablePackSourceClosureEntry[];
 };
 
-type ParameterizedInstanceSubject = {
+type PackInstanceSubject = {
   readonly kind: 'instance';
   readonly packageId: PackageId;
   readonly parent: PackageId;
@@ -155,16 +155,13 @@ type ParameterizedInstanceSubject = {
   readonly sourcePath: string;
 };
 
-type ParameterizedDirectSubject = {
+type PackDirectSubject = {
   readonly kind: 'direct';
   readonly packageId: PackageId;
   readonly sourcePath: string;
 };
 
-type ParameterizedSourceIndexSubject =
-  | ParameterizedSourceSubject
-  | ParameterizedInstanceSubject
-  | ParameterizedDirectSubject;
+type PackSourceIndexSubject = PackSourceSubject | PackInstanceSubject | PackDirectSubject;
 
 function dynamicFailure(context: BuildProductionOptions, value: unknown): never {
   const candidate = value !== null && typeof value === 'object' ? value : {};
@@ -175,23 +172,20 @@ function dynamicFailure(context: BuildProductionOptions, value: unknown): never
     readonly detail?: unknown;
   };
   throw context.fail({
-    code: typeof error.code === 'string' ? error.code : 'parameterized-pack-build-failed',
+    code: typeof error.code === 'string' ? error.code : 'pack-build-failed',
     expected:
       typeof error.expected === 'string'
         ? error.expected
-        : 'the parameterized Pack generation to produce a valid terminal result',
+        : 'the Pack source generation to produce a valid terminal result',
     hint:
       typeof error.hint === 'string'
         ? error.hint
-        : 'inspect the parameterized Pack subject and rebuild the current generation',
+        : 'inspect the Pack source subject and rebuild the current generation',
     ...(error.detail === undefined ? {} : { detail: error.detail }),
   });
 }
 
-function parameterizedCatalogSourcePath(
-  context: BuildProductionOptions,
-  sourcePath: string,
-): string {
+function packCatalogSourcePath(context: BuildProductionOptions, sourcePath: string): string {
   const projected = context.fsForImport.sourceIdentityFor?.(sourcePath);
   const logical =
     projected === undefined || isAbsolute(projected)
@@ -200,13 +194,13 @@ function parameterizedCatalogSourcePath(
   return canonicalScriptableSourcePath(logical).replaceAll('\\', '/');
 }
 
-/** Build parameterized roots and JSON instances before normal Build emission. */
-async function buildParameterizedPackages(
+/** Build ScriptablePack roots and Pack JSON instances before normal emission. */
+async function buildPackSources(
   context: BuildProductionOptions,
-): Promise<readonly ParameterizedBuildBundle[]> {
-  const subjects = new Map<string, ParameterizedSourceIndexSubject>();
+): Promise<readonly PackBuildBundle[]> {
+  const subjects = new Map<string, PackSourceIndexSubject>();
   for (const [sourcePath, declaration] of context.inventory.sourceDeclarations) {
-    if (declaration.format === 'pack.ts-parameterized') {
+    if (declaration.format === 'pack.ts') {
       const key = PackageId.format(declaration.definition.packageId).toLowerCase();
       subjects.set(key, {
         kind: 'source',
@@ -220,7 +214,7 @@ async function buildParameterizedPackages(
     if (declaration.format !== 'pack.json' || declaration.value.schemaVersion !== '3.0.0') {
       continue;
     }
-    const parsed = parseParameterizedPackJson(declaration.value);
+    const parsed = parsePackSourceJson(declaration.value);
     if (!parsed.ok) dynamicFailure(context, parsed.error);
     if (parsed.value.format === 'direct') {
       subjects.set(PackageId.format(parsed.value.packageId).toLowerCase(), {
@@ -238,7 +232,7 @@ async function buildParameterizedPackages(
       });
     }
   }
-  const sourceSubject = (packageId: PackageId): ParameterizedSourceSubject | undefined => {
+  const sourceSubject = (packageId: PackageId): PackSourceSubject | undefined => {
     const subject = subjects.get(PackageId.format(packageId).toLowerCase());
     return subject?.kind === 'source' ? subject : undefined;
   };
@@ -269,16 +263,16 @@ async function buildParameterizedPackages(
   const orderedSubjects = [...subjects.values()].sort((left, right) =>
     left.sourcePath.localeCompare(right.sourcePath),
   );
-  const inputs: ParameterizedScriptablePackInput[] = [];
+  const inputs: ScriptablePackInput[] = [];
   for (const subject of orderedSubjects) {
     if (subject.kind === 'source') {
       const packageId = PackageId.format(subject.packageId);
-      const loaded = await loadParameterizedScriptablePack(subject.sourcePath);
+      const loaded = await loadScriptablePack(subject.sourcePath);
       if (!loaded.ok) dynamicFailure(context, loaded.error);
       if (PackageId.format(loaded.value.packageId) !== packageId) {
         dynamicFailure(context, {
           code: 'pack-source-revision-conflict',
-          expected: 'the parameterized source packageId to remain fixed during production',
+          expected: 'the ScriptablePack source packageId to remain fixed during production',
           hint: 'retry after source writes settle and rebuild the current generation',
           detail: {
             sourcePath: subject.sourcePath,
@@ -289,7 +283,7 @@ async function buildParameterizedPackages(
       }
       inputs.push({
         sourcePath: subject.sourcePath,
-        displaySourcePath: parameterizedCatalogSourcePath(context, subject.sourcePath),
+        displaySourcePath: packCatalogSourcePath(context, subject.sourcePath),
         definition: loaded.value,
         sourceClosure: subject.sourceClosure,
         publicationGeneration: context.generation,
@@ -316,18 +310,18 @@ async function buildParameterizedPackages(
     const root = sourceSubject(resolved.value.rootPackageId);
     if (root === undefined) {
       dynamicFailure(context, {
-        code: 'pack-parent-not-parameterized',
-        expected: 'the instance parent chain to terminate at a parameterized source',
-        hint: 'point the instance at a parameterized pack.ts source',
+        code: 'pack-parent-has-no-parameters',
+        expected: 'the instance parent chain to terminate at a ScriptablePack source',
+        hint: 'point the instance at a ScriptablePack *.pack.ts source with parameters',
         detail: { packageId: PackageId.format(subject.packageId) },
       });
     }
-    const loaded = await loadParameterizedScriptablePack(root.sourcePath);
+    const loaded = await loadScriptablePack(root.sourcePath);
     if (!loaded.ok) dynamicFailure(context, loaded.error);
     if (PackageId.format(loaded.value.packageId) !== PackageId.format(root.packageId)) {
       dynamicFailure(context, {
         code: 'pack-source-revision-conflict',
-        expected: 'the parameterized parent packageId to remain fixed during production',
+        expected: 'the ScriptablePack parent packageId to remain fixed during production',
         hint: 'retry after source writes settle and rebuild the current generation',
         detail: {
           sourcePath: root.sourcePath,
@@ -339,7 +333,7 @@ async function buildParameterizedPackages(
     const packageId = PackageId.format(subject.packageId);
     inputs.push({
       sourcePath: subject.sourcePath,
-      displaySourcePath: parameterizedCatalogSourcePath(context, subject.sourcePath),
+      displaySourcePath: packCatalogSourcePath(context, subject.sourcePath),
       definition: loaded.value,
       sourceClosure: root.sourceClosure,
       subjectPackageId: subject.packageId,
@@ -369,21 +363,21 @@ async function buildParameterizedPackages(
     },
   );
   const availableGuids = new Set(requiredGuids.map((guid) => AssetGuid.format(guid).toLowerCase()));
-  const built = await produceParameterizedScriptablePackProducts({
+  const built = await produceScriptablePackProducts({
     sources: inputs,
     declaredExternalOutputs: externalOutputs,
     availableGuids,
   });
   if (!built.ok) dynamicFailure(context, built.error);
 
-  const bundles: ParameterizedBuildBundle[] = [];
+  const bundles: PackBuildBundle[] = [];
   for (const input of inputs) {
     const prepared = built.value.get(input.displaySourcePath);
     if (prepared === undefined) {
       dynamicFailure(context, {
-        code: 'parameterized-pack-build-failed',
+        code: 'pack-build-failed',
         expected: 'the worklist to return one prepared result per source subject',
-        hint: 'rerun the parameterized Pack generation from a clean inventory',
+        hint: 'rerun Pack source generation from a clean inventory',
         detail: { sourcePath: input.sourcePath },
       });
     }
@@ -544,13 +538,13 @@ async function emitAuthoredPack(
     });
   }
   if (declaration.value.schemaVersion === '3.0.0') {
-    const parsed = parseParameterizedPackJson(declaration.value);
+    const parsed = parsePackSourceJson(declaration.value);
     if (!parsed.ok) dynamicFailure(work.context, parsed.error);
     if (parsed.value.format !== 'direct') {
       dynamicFailure(work.context, {
         code: 'catalog-declaration-missing',
         expected: 'a direct v3 Pack declaration for an indexed authored output',
-        hint: 'instances are built from their parameterized parent and do not have direct Catalog rows',
+        hint: 'instances are built from their ScriptablePack parent and do not have direct Catalog rows',
         detail: { stage: 'scan', sourcePath: packPath },
       });
     }
@@ -659,10 +653,10 @@ async function emitAuthoredPack(
   }
 }
 
-async function emitParameterizedPack(
+async function emitScriptablePack(
   work: BuildEmissionWork,
   guidSeen: Set<string>,
-  bundle: ParameterizedBuildBundle,
+  bundle: PackBuildBundle,
 ): Promise<void> {
   const { input, prepared } = bundle;
   const packageId = PackageId.format(input.subjectPackageId ?? input.definition.packageId);
@@ -854,7 +848,7 @@ async function emitBuildEntry(
 export async function produceBuildAssets(
   context: BuildProductionOptions,
 ): Promise<PackIndexEntry[]> {
-  const dynamicBundles = await buildParameterizedPackages(context);
+  const dynamicBundles = await buildPackSources(context);
   const entries = [
     ...context.inventory.entries,
     ...dynamicBundles.flatMap((bundle) => bundle.entries),
@@ -864,7 +858,7 @@ export async function produceBuildAssets(
   const guidSeen = new Set<string>();
   const work: BuildEmissionWork = { importedEntries, context };
   for (const bundle of dynamicBundles) {
-    await emitParameterizedPack(work, guidSeen, bundle);
+    await emitScriptablePack(work, guidSeen, bundle);
   }
   for (const entry of importedEntries) {
     if (!guidSeen.has(entry.guid.toLowerCase()))

package/src/index.ts

@@ -106,31 +106,31 @@ export {
   validateMeshLodContract,
 } from './mesh-lod.js';
 export { projectImportProductForBuild } from './pack-projection.js';
-export {
-  buildParameterizedScriptablePack,
-  buildParameterizedScriptablePackWorklist,
-  type ParameterizedScriptablePackBuildOptions,
-  type ParameterizedScriptablePackBuildProduct,
-  type ParameterizedScriptablePackBuildResult,
-  type ParameterizedScriptablePackWorkItem,
-  type ParameterizedScriptablePackWorklistOptions,
-  type ParameterizedScriptablePackWorklistProduct,
-} from './parameterized-scriptable-pack.js';
 export {
   type AssetOutputInput,
   type AssetOutputPayload,
   type AssetOutputProducer,
   AssetOutputProducerRegistry,
   type AssetOutputProduct,
+  type PackBuildProduct,
   type ScriptablePackAssetSnapshot,
   type ScriptablePackAssetSnapshotSource,
-  type ScriptablePackBuildProduct,
   type ScriptablePackDomainError,
   type ScriptablePackExternalEvidence,
   type ScriptablePackExternalUsage,
   type ScriptablePackSourceClosureEntry,
   type ScriptablePackStagedOutput,
 } from './scriptable-pack.js';
+export {
+  buildScriptablePack,
+  buildScriptablePackWorklist,
+  type ScriptablePackBuildOptions,
+  type ScriptablePackBuildProduct,
+  type ScriptablePackBuildResult,
+  type ScriptablePackBuildWorkItem,
+  type ScriptablePackBuildWorklistOptions,
+  type ScriptablePackBuildWorklistProduct,
+} from './scriptable-pack-build.js';
 export {
   createScriptablePackFileAssetSnapshotSource,
   type ScriptablePackFileAssetSnapshotError,
@@ -142,15 +142,15 @@ export {
   type DirectPackTransportInput,
   declaredPackExternalOutputs,
   type LegacyPackTransport,
-  materializePreparedParameterizedScriptablePack,
-  type ParameterizedScriptablePackInput,
-  type ParameterizedScriptablePackProductionOptions,
-  type PreparedParameterizedScriptablePack,
+  materializePreparedScriptablePack,
+  type PreparedScriptablePack,
   prepareDirectPackTransport,
   prepareLegacyPackTransport,
-  produceParameterizedScriptablePackProducts,
+  produceScriptablePackProducts,
   readCookedAuthoredPack,
   type ScriptablePackExternalImportOptions,
+  type ScriptablePackInput,
+  type ScriptablePackProductionOptions,
   type ScriptablePackPublicationFacts,
   type ScriptablePackTransportPaths,
   type ScriptablePackTransportSink,
@@ -196,6 +196,7 @@ export {
 export {
   commitImportPublication,
   discardImportPublication,
+  type ImportPublicationArtifact,
   type ImportPublicationError,
   type ImportPublicationInput,
   type ImportPublicationResult,

package/src/{parameterized-scriptable-pack.ts → scriptable-pack-build.ts}

@@ -1,6 +1,6 @@
 import { BUILTIN_MESH_ASSETS } from '@forgeax/engine-pack/builtin';
 import {
-  type AnyParameterizedPackDefinition,
+  type AnyScriptablePackDefinition,
   AssetGuid,
   isScriptablePackAssetKind,
   isValidPackSourceKey,
@@ -28,16 +28,16 @@ import {
 import type {
   AssetOutputProducer,
   AssetOutputProducerRegistry,
+  PackBuildProduct,
   ScriptablePackAssetSnapshotSource,
-  ScriptablePackBuildProduct,
   ScriptablePackDomainError,
   ScriptablePackExternalEvidence,
   ScriptablePackSourceClosureEntry,
   ScriptablePackStagedOutput,
 } from './scriptable-pack.js';
 
-export interface ParameterizedScriptablePackBuildOptions {
-  readonly definition: AnyParameterizedPackDefinition;
+export interface ScriptablePackBuildOptions {
+  readonly definition: AnyScriptablePackDefinition;
   readonly sourcePath: string;
   /** Instance identity. Omitted for a root source and defaults to definition.packageId. */
   readonly subjectPackageId?: PackageId;
@@ -56,12 +56,12 @@ export interface ParameterizedScriptablePackBuildOptions {
   readonly publication?: AssetPublicationEnvelope;
 }
 
-export interface ParameterizedScriptablePackBuildProduct extends ScriptablePackBuildProduct {
+export interface ScriptablePackBuildProduct extends PackBuildProduct {
   readonly publication?: AssetPublicationEnvelope;
 }
 
-export type ParameterizedScriptablePackBuildResult = Result<
-  ParameterizedScriptablePackBuildProduct,
+export type ScriptablePackBuildResult = Result<
+  ScriptablePackBuildProduct,
   | PackAuthoringError
   | ScriptablePackDomainError
   | AssetError
@@ -289,9 +289,9 @@ function normalizedGuidSet(value: ReadonlySet<string> | undefined): Set<string>
  * Execute a v2 Pack source and project its dynamic output map through the
  * existing importer producers. No output GUID or output manifest is read.
  */
-export async function buildParameterizedScriptablePack(
-  options: ParameterizedScriptablePackBuildOptions,
-): Promise<ParameterizedScriptablePackBuildResult> {
+export async function buildScriptablePack(
+  options: ScriptablePackBuildOptions,
+): Promise<ScriptablePackBuildResult> {
   const subjectPackageId = options.subjectPackageId ?? options.definition.packageId;
   const availableGuids = normalizedGuidSet(options.availableGuids);
   const observed = observedReader(options.assetSource);
@@ -319,8 +319,8 @@ export async function buildParameterizedScriptablePack(
       PackageId.format(options.definition.packageId).toLowerCase()
   ) {
     return err({
-      code: 'pack-parent-not-parameterized',
-      expected: 'a parameterized Pack source for an independent instance packageId',
+      code: 'pack-parent-has-no-parameters',
+      expected: 'a ScriptablePack source with parameters for an independent instance packageId',
       hint: 'use clone for a zero-parameter Pack instead of building it as an instance',
       detail: {
         sourcePath: options.sourcePath,
@@ -509,7 +509,7 @@ export async function buildParameterizedScriptablePack(
       usage,
       digest: evidenceDigest,
     })),
-    authoringContractVersion: options.authoringContractVersion ?? 'parameterized-pack/1',
+    authoringContractVersion: options.authoringContractVersion ?? 'scriptable-pack/1',
     producerVersions: options.outputs.versions(),
   });
   const refs = imported.flatMap((asset) => asset.refs);
@@ -543,8 +543,8 @@ export async function buildParameterizedScriptablePack(
   });
 }
 
-export interface ParameterizedScriptablePackWorkItem {
-  readonly definition: AnyParameterizedPackDefinition;
+export interface ScriptablePackBuildWorkItem {
+  readonly definition: AnyScriptablePackDefinition;
   readonly sourcePath: string;
   readonly subjectPackageId?: PackageId;
   readonly values?: Readonly<Record<string, unknown>>;
@@ -552,8 +552,8 @@ export interface ParameterizedScriptablePackWorkItem {
   readonly sourceClosure?: readonly ScriptablePackSourceClosureEntry[];
 }
 
-export interface ParameterizedScriptablePackWorklistOptions {
-  readonly subjects: readonly ParameterizedScriptablePackWorkItem[];
+export interface ScriptablePackBuildWorklistOptions {
+  readonly subjects: readonly ScriptablePackBuildWorkItem[];
   readonly outputs: AssetOutputProducerRegistry;
   readonly assetSource?: ScriptablePackAssetSnapshotSource;
   readonly availableGuids?: ReadonlySet<string>;
@@ -561,9 +561,9 @@ export interface ParameterizedScriptablePackWorklistOptions {
   readonly maxPasses?: number;
 }
 
-export interface ParameterizedScriptablePackWorklistProduct {
+export interface ScriptablePackBuildWorklistProduct {
   readonly products: readonly TerminalImportProduct<unknown>[];
-  readonly buildProducts: readonly ParameterizedScriptablePackBuildProduct[];
+  readonly buildProducts: readonly ScriptablePackBuildProduct[];
   readonly stagedOutputs: readonly ScriptablePackStagedOutput[];
   readonly iterations: number;
 }
@@ -597,11 +597,11 @@ function stagedSource(
 }
 
 /** Build subjects in stable passes; content reads may wait for a later subject. */
-export async function buildParameterizedScriptablePackWorklist(
-  options: ParameterizedScriptablePackWorklistOptions,
+export async function buildScriptablePackWorklist(
+  options: ScriptablePackBuildWorklistOptions,
 ): Promise<
   Result<
-    ParameterizedScriptablePackWorklistProduct,
+    ScriptablePackBuildWorklistProduct,
     | PackAuthoringError
     | ScriptablePackDomainError
     | AssetError
@@ -621,7 +621,7 @@ export async function buildParameterizedScriptablePackWorklist(
     orderedSubjects.map((subject, index) => [`${index}:${subject.sourcePath}`, subject]),
   );
   const staged = new Map<string, ScriptablePackStagedOutput>();
-  const results = new Map<string, ParameterizedScriptablePackBuildProduct>();
+  const results = new Map<string, ScriptablePackBuildProduct>();
   const availableGuids = new Set([
     ...(normalizedGuidSet(options.availableGuids) ?? []),
     ...BUILTIN_MESH_ASSETS.map((asset) => asset.guid.toLowerCase()),
@@ -632,7 +632,7 @@ export async function buildParameterizedScriptablePackWorklist(
     let progress = false;
     const waiting = new Set<string>();
     for (const [key, subject] of pending) {
-      const result = await buildParameterizedScriptablePack({
+      const result = await buildScriptablePack({
         definition: subject.definition,
         sourcePath: subject.sourcePath,
         ...(subject.subjectPackageId === undefined