@forgeax/engine-pack 0.1.23 → 0.1.24

package/src/{parameterized-pack.ts → pack-authoring.ts}

@@ -100,7 +100,7 @@ export type PackAuthoringErrorCode =
   | 'pack-guid-collision'
   | 'pack-parent-not-found'
   | 'pack-parent-cycle'
-  | 'pack-parent-not-parameterized'
+  | 'pack-parent-has-no-parameters'
   | 'pack-parameter-invalid'
   | 'pack-content-dependency-stalled'
   | 'pack-output-reference-missing'
@@ -601,7 +601,7 @@ interface PackDefinitionBase {
   readonly sceneComponents?: readonly ScriptablePackSceneComponentInput[];
 }
 
-export type ParameterizedPackDefinition<
+export type ScriptablePackDefinition<
   TParameters extends readonly PackParameterDefinition[] | undefined = undefined,
 > = PackDefinitionBase &
   (TParameters extends readonly PackParameterDefinition[]
@@ -613,17 +613,13 @@ export type ParameterizedPackDefinition<
         readonly build: (context: PackBuildContextWithoutParameters) => PackBuildResult;
       });
 
-export type PackDefinition =
-  | ParameterizedPackDefinition<undefined>
-  | ParameterizedPackDefinition<readonly [PackParameterDefinition, ...PackParameterDefinition[]]>;
-
 export type PackParameterList = readonly [PackParameterDefinition, ...PackParameterDefinition[]];
 type NonEmptyParameters = PackParameterList;
 type NoParameterPackInput = PackDefinitionBase & {
   readonly parameters?: never;
   readonly build: (context: PackBuildContextWithoutParameters) => PackBuildResult;
 };
-type ParameterizedPackInput<TParameters extends NonEmptyParameters> = PackDefinitionBase & {
+type ScriptablePackDefinitionInput<TParameters extends NonEmptyParameters> = PackDefinitionBase & {
   readonly parameters: TParameters;
   readonly build: (context: PackBuildContextWithParameters<TParameters>) => PackBuildResult;
 };
@@ -646,10 +642,8 @@ export function definePackageId(value: string | PackageId): PackageId {
 }
 
 function cloneDefinition(
-  definition:
-    | ParameterizedPackDefinition<NonEmptyParameters>
-    | ParameterizedPackDefinition<undefined>,
-): ParameterizedPackDefinition<NonEmptyParameters> | ParameterizedPackDefinition<undefined> {
+  definition: ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined>,
+): ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined> {
   const parameters =
     'parameters' in definition
       ? Object.freeze(
@@ -680,52 +674,50 @@ function cloneDefinition(
     packageId: definition.packageId.slice() as PackageId,
     ...(parameters === undefined ? {} : { parameters }),
     ...(sceneComponents === undefined ? {} : { sceneComponents }),
-  }) as ParameterizedPackDefinition<NonEmptyParameters> | ParameterizedPackDefinition<undefined>;
+  }) as ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined>;
 }
 
 /**
  * Define the only executable authoring shape. A missing `parameters` property
  * is meaningful: its build context has no `values` member.
  */
-export function definePack(
-  definition: NoParameterPackInput,
-): ParameterizedPackDefinition<undefined>;
+export function definePack(definition: NoParameterPackInput): ScriptablePackDefinition<undefined>;
 export function definePack<const TParameters extends NonEmptyParameters>(
-  definition: ParameterizedPackInput<TParameters>,
-): ParameterizedPackDefinition<TParameters>;
+  definition: ScriptablePackDefinitionInput<TParameters>,
+): ScriptablePackDefinition<TParameters>;
 export function definePack(
-  definition: NoParameterPackInput | ParameterizedPackInput<NonEmptyParameters>,
-): ParameterizedPackDefinition<NonEmptyParameters> | ParameterizedPackDefinition<undefined> {
+  definition: NoParameterPackInput | ScriptablePackDefinitionInput<NonEmptyParameters>,
+): ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined> {
   const validated = validatePackDefinition(definition);
   if (!validated.ok) throw Object.assign(new TypeError(validated.error.hint), validated.error);
   return cloneDefinition(
     validated.value as
-      | ParameterizedPackDefinition<NonEmptyParameters>
-      | ParameterizedPackDefinition<undefined>,
+      | ScriptablePackDefinition<NonEmptyParameters>
+      | ScriptablePackDefinition<undefined>,
   );
 }
 
 /** Union used only at orchestration boundaries that accept either source form. */
-export type AnyParameterizedPackDefinition =
-  | ParameterizedPackDefinition<PackParameterList>
-  | ParameterizedPackDefinition<undefined>;
+export type AnyScriptablePackDefinition =
+  | ScriptablePackDefinition<PackParameterList>
+  | ScriptablePackDefinition<undefined>;
 
-export interface ParameterizedPackSourceMeta {
+export interface ScriptablePackSourceMeta {
   readonly schemaVersion: '2.0.0';
-  readonly kind: 'parameterized-pack-source';
+  readonly kind: 'scriptable-pack-source';
   readonly packageId: string;
   readonly source: string;
   readonly parameters?: readonly Readonly<Record<string, unknown>>[];
 }
 
 /** Ephemeral scan evidence; it intentionally contains no output GUID table. */
-export function projectParameterizedPackMeta(
-  definition: AnyParameterizedPackDefinition,
+export function projectScriptablePackMeta(
+  definition: AnyScriptablePackDefinition,
   sourcePath: string,
-): ParameterizedPackSourceMeta {
+): ScriptablePackSourceMeta {
   return {
     schemaVersion: '2.0.0',
-    kind: 'parameterized-pack-source',
+    kind: 'scriptable-pack-source',
     packageId: PackageId.format(definition.packageId),
     source: sourcePath,
     ...('parameters' in definition
@@ -753,7 +745,7 @@ export function validatePackDefinition(
   value: unknown,
   sourcePath?: string,
 ): Result<
-  ParameterizedPackDefinition<NonEmptyParameters> | ParameterizedPackDefinition<undefined>,
+  ScriptablePackDefinition<NonEmptyParameters> | ScriptablePackDefinition<undefined>,
   PackAuthoringError
 > {
   if (!isRecord(value))
@@ -818,7 +810,7 @@ export function validatePackDefinition(
         ...(value.name === undefined ? {} : { name: value.name }),
         ...(sceneComponents.value === undefined ? {} : { sceneComponents: sceneComponents.value }),
         build: value.build,
-      }) as ParameterizedPackDefinition<undefined>,
+      }) as ScriptablePackDefinition<undefined>,
     );
   }
   const parameters = validateParameterDefinitions(value.parameters);
@@ -831,19 +823,19 @@ export function validatePackDefinition(
       ...(sceneComponents.value === undefined ? {} : { sceneComponents: sceneComponents.value }),
       parameters: parameters.value,
       build: value.build,
-    }) as ParameterizedPackDefinition<NonEmptyParameters>,
+    }) as ScriptablePackDefinition<NonEmptyParameters>,
   );
 }
 
-export function isParameterizedPack(
-  value: ParameterizedPackDefinition | unknown,
-): value is ParameterizedPackDefinition<NonEmptyParameters> {
+export function hasPackParameters(
+  value: ScriptablePackDefinition | unknown,
+): value is ScriptablePackDefinition<NonEmptyParameters> {
   return isRecord(value) && Array.isArray(value.parameters) && value.parameters.length > 0;
 }
 
 /** Resolve defaults plus a sparse instance override with shallow replacement. */
 export function resolvePackParameterValues(
-  definition: ParameterizedPackDefinition<NonEmptyParameters>,
+  definition: ScriptablePackDefinition<NonEmptyParameters>,
   overrides: unknown = {},
   inheritedValues?: Readonly<Record<string, PackParameterValue>>,
 ): Result<PackParameterValues<NonEmptyParameters>, PackAuthoringError> {
@@ -1045,9 +1037,7 @@ function parsePackJsonAsset(
 }
 
 /** Parse the two mutually exclusive v3 pack.json branches. */
-export function parseParameterizedPackJson(
-  value: unknown,
-): Result<ParsedPackJson, PackAuthoringError> {
+export function parsePackSourceJson(value: unknown): Result<ParsedPackJson, PackAuthoringError> {
   if (!isRecord(value))
     return jsonError('$', 'a v3 pack.json object', value, 'document is not an object');
   if (value.schemaVersion !== '3.0.0')
@@ -1127,9 +1117,6 @@ export function parseParameterizedPackJson(
   });
 }
 
-export const parsePackJson = parseParameterizedPackJson;
-export const parsePackAuthoringJson = parseParameterizedPackJson;
-
 export interface DirectPackAssetProjection extends DirectPackJsonAsset {
   readonly guid: string;
   readonly sourceKey: string;
@@ -1144,7 +1131,7 @@ export interface DirectPackProjection {
 export function projectDirectPackJson(
   value: ParsedDirectPackJson | DirectPackJson,
 ): Result<DirectPackProjection, PackAuthoringError> {
-  const parsed = 'format' in value ? ok(value) : parseParameterizedPackJson(value);
+  const parsed = 'format' in value ? ok(value) : parsePackSourceJson(value);
   if (!parsed.ok) return parsed;
   if (parsed.value.format !== 'direct') {
     return failure(
@@ -1238,9 +1225,9 @@ export async function resolvePackParameterInheritance(
     if (current.format === 'direct') {
       return failure(
         authoringError(
-          'pack-parent-not-parameterized',
-          'a parameterized Pack source as the parent',
-          'direct packs cannot be instance parents; point the instance at a parameterized source',
+          'pack-parent-has-no-parameters',
+          'a ScriptablePack source with parameters as the parent',
+          'direct packs cannot be instance parents; point the instance at a ScriptablePack source with parameters',
           { packageId: currentId },
         ),
       );
@@ -1251,7 +1238,7 @@ export async function resolvePackParameterInheritance(
       if (descriptors.value.length === 0) {
         return failure(
           authoringError(
-            'pack-parent-not-parameterized',
+            'pack-parent-has-no-parameters',
             'the parent source to declare a non-empty parameter list',
             'use clone for an independent zero-parameter Pack instead of creating an empty instance',
             { packageId: currentId },
@@ -1263,7 +1250,7 @@ export async function resolvePackParameterInheritance(
         packageId: current.packageId,
         parameters: descriptors.value as NonEmptyParameters,
         build: () => ok({}),
-      } as ParameterizedPackDefinition<NonEmptyParameters>;
+      } as ScriptablePackDefinition<NonEmptyParameters>;
       const values = resolvePackParameterValues(definition);
       if (!values.ok) return values;
       return ok({
@@ -1280,7 +1267,7 @@ export async function resolvePackParameterInheritance(
         authoringError(
           'pack-parent-not-found',
           'the parent packageId to resolve in the source index',
-          'inspect the parent locator or recreate the instance from a live parameterized Pack',
+          'inspect the parent locator or recreate the instance from a live ScriptablePack with parameters',
           { packageId: currentId, parent: PackageId.format(current.parent) },
         ),
       );
@@ -1310,7 +1297,7 @@ export async function resolvePackParameterInheritance(
       packageId: resolvedParent.value.rootPackageId,
       parameters: descriptors as NonEmptyParameters,
       build: () => ok({}),
-    } as ParameterizedPackDefinition<NonEmptyParameters>;
+    } as ScriptablePackDefinition<NonEmptyParameters>;
     const values = resolvePackParameterValues(
       definition,
       current.values,
@@ -1331,7 +1318,7 @@ export async function resolvePackParameterInheritance(
 
 export const resolvePackInheritance = resolvePackParameterInheritance;
 
-export const PARAMETERIZED_PACK_OPERATION_IDS = [
+export const PACK_AUTHORING_OPERATION_IDS = [
   'asset.list',
   'asset.inspect',
   'asset.resolve',
@@ -1344,12 +1331,12 @@ export const PARAMETERIZED_PACK_OPERATION_IDS = [
   'asset-source.cold-cook',
 ] as const;
 
-export type ParameterizedPackOperationId = (typeof PARAMETERIZED_PACK_OPERATION_IDS)[number];
+export type PackAuthoringOperationId = (typeof PACK_AUTHORING_OPERATION_IDS)[number];
 
-export interface ParameterizedPackOperation {
+export interface PackAuthoringOperation {
   readonly requestId: string;
   readonly expectedRevision?: string;
-  readonly operation: ParameterizedPackOperationId;
+  readonly operation: PackAuthoringOperationId;
   readonly subject?: string;
   readonly sourcePath?: string;
   readonly targetPath?: string;
@@ -1370,10 +1357,10 @@ export interface ParameterizedPackOperation {
   readonly require?: 'identity' | 'present' | 'ready';
 }
 
-export type ParameterizedPackResolutionStatus = 'identity' | 'present' | 'ready';
+export type PackAuthoringResolutionStatus = 'identity' | 'present' | 'ready';
 
-export interface ParameterizedPackOperationResult {
-  readonly operation: ParameterizedPackOperationId;
+export interface PackAuthoringOperationResult {
+  readonly operation: PackAuthoringOperationId;
   readonly requestId: string;
   readonly sourcePath?: string;
   readonly targetPath?: string;
@@ -1383,7 +1370,7 @@ export interface ParameterizedPackOperationResult {
   readonly sourceKey?: string;
   readonly guid?: string;
   readonly format?: 'pack.ts' | 'pack.json' | 'direct' | 'instance';
-  readonly status?: ParameterizedPackResolutionStatus;
+  readonly status?: PackAuthoringResolutionStatus;
   readonly kind?: string;
   readonly parameters?: readonly Readonly<Record<string, unknown>>[];
   readonly values?: Readonly<Record<string, unknown>>;
@@ -1391,21 +1378,21 @@ export interface ParameterizedPackOperationResult {
   readonly parentChain?: readonly string[];
   readonly assets?: readonly Readonly<Record<string, unknown>>[];
   readonly sources?: readonly Readonly<Record<string, unknown>>[];
-  readonly capabilities?: readonly ParameterizedPackOperationId[];
+  readonly capabilities?: readonly PackAuthoringOperationId[];
   readonly snapshot?: {
     readonly sourceCount: number;
     readonly assetCount: number;
   };
 }
 
-export interface ParameterizedPackGatewayPort<TResult = unknown> {
-  execute(operation: ParameterizedPackOperation): Promise<Result<TResult, PackAuthoringError>>;
+export interface PackAuthoringGatewayPort<TResult = unknown> {
+  execute(operation: PackAuthoringOperation): Promise<Result<TResult, PackAuthoringError>>;
 }
 
 /** One idempotent gateway wrapper shared by Editor and CLI adapters. */
-export function createParameterizedPackAuthoringGateway<TResult = unknown>(
-  port: ParameterizedPackGatewayPort<TResult>,
-): ParameterizedPackGatewayPort<TResult> {
+export function createPackAuthoringGateway<TResult = unknown>(
+  port: PackAuthoringGatewayPort<TResult>,
+): PackAuthoringGatewayPort<TResult> {
   const requests = new Map<
     string,
     { fingerprint: string; result: Promise<Result<TResult, PackAuthoringError>> }
@@ -1478,15 +1465,13 @@ export function createParameterizedPackAuthoringGateway<TResult = unknown>(
   };
 }
 
-export const PARAMETERIZED_PACK_OPERATION_DESCRIPTORS = PARAMETERIZED_PACK_OPERATION_IDS.map(
-  (id) => ({
-    id,
-    domain: id.startsWith('asset-source.') ? 'session' : 'asset',
-    readOnly: id.startsWith('asset.'),
-    requiresRevision: !id.startsWith('asset.') && id !== 'asset-source.create',
-  }),
-) as readonly {
-  id: ParameterizedPackOperationId;
+export const PACK_AUTHORING_OPERATION_DESCRIPTORS = PACK_AUTHORING_OPERATION_IDS.map((id) => ({
+  id,
+  domain: id.startsWith('asset-source.') ? 'session' : 'asset',
+  readOnly: id.startsWith('asset.'),
+  requiresRevision: !id.startsWith('asset.') && id !== 'asset-source.create',
+})) as readonly {
+  id: PackAuthoringOperationId;
   domain: 'asset' | 'session';
   readOnly: boolean;
   requiresRevision: boolean;

package/src/scanner.ts

@@ -12,19 +12,19 @@ import { PACK_ERROR_HINTS } from '@forgeax/engine-types';
 import { PackError } from './errors.js';
 import { isValidAssetGuidString, PackageId } from './guid.js';
 import {
-  type AnyParameterizedPackDefinition,
-  type ParameterizedPackSourceMeta,
-  parseParameterizedPackJson,
+  type AnyScriptablePackDefinition,
+  parsePackSourceJson,
   projectDirectPackJson,
-  projectParameterizedPackMeta,
-} from './parameterized-pack.js';
+  projectScriptablePackMeta,
+  type ScriptablePackSourceMeta,
+} from './pack-authoring.js';
 import { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 import { resolveAssetSource } from './resolve-asset-source.js';
 import { validateMeta, validatePack } from './schema-compiled.js';
 import type { ScriptablePackSourceClosureEntry } from './scriptable-pack.js';
 import {
   inventoryScriptablePackSource,
-  loadParameterizedScriptablePack,
+  loadScriptablePack,
   type ScriptablePackModuleExecutor,
 } from './scriptable-pack-node.js';
 
@@ -85,8 +85,8 @@ export interface ScanInventory {
 export interface ScriptablePackInventoryDeclaration {
   readonly sourcePath: string;
   readonly sourceRevision: string;
-  readonly meta: ParameterizedPackSourceMeta;
-  readonly definition: Readonly<AnyParameterizedPackDefinition>;
+  readonly meta: ScriptablePackSourceMeta;
+  readonly definition: Readonly<AnyScriptablePackDefinition>;
   readonly sourceClosure: readonly ScriptablePackSourceClosureEntry[];
 }
 
@@ -125,7 +125,7 @@ export interface LegacyPackInventoryDocument {
   readonly assets: readonly PackInventoryAsset[];
 }
 
-export interface ParameterizedPackInventoryDocument {
+export interface PackSourceInventoryDocument {
   readonly schemaVersion: '3.0.0';
   readonly packageId: string;
   readonly assets?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
@@ -133,9 +133,7 @@ export interface ParameterizedPackInventoryDocument {
   readonly values?: Readonly<Record<string, unknown>>;
 }
 
-export type PackInventoryDocument =
-  | LegacyPackInventoryDocument
-  | ParameterizedPackInventoryDocument;
+export type PackInventoryDocument = LegacyPackInventoryDocument | PackSourceInventoryDocument;
 
 export interface PackInventoryAsset {
   readonly guid: string;
@@ -164,11 +162,11 @@ export type ScanSourceDeclaration =
       readonly value: PackInventoryDocument;
     }
   | {
-      readonly format: 'pack.ts-parameterized';
+      readonly format: 'pack.ts';
       readonly sourcePath: string;
       readonly sourceRevision: string;
-      readonly value: ParameterizedPackSourceMeta;
-      readonly definition: AnyParameterizedPackDefinition;
+      readonly value: ScriptablePackSourceMeta;
+      readonly definition: AnyScriptablePackDefinition;
       readonly sourceClosure: readonly ScriptablePackSourceClosureEntry[];
     };
 
@@ -370,7 +368,7 @@ async function scanValidated(
   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 packageKind = new Map<string, 'legacy' | 'direct' | 'instance' | 'scriptable'>();
   const instanceParents: {
     readonly path: string;
     readonly packageId: string;
@@ -380,7 +378,7 @@ async function scanValidated(
   function registerPackage(
     packageId: string | undefined,
     path: string,
-    kind: 'legacy' | 'direct' | 'instance' | 'parameterized',
+    kind: 'legacy' | 'direct' | 'instance' | 'scriptable',
   ): PackError | undefined {
     if (packageId === undefined) return undefined;
     const normalized = packageId.toLowerCase();
@@ -402,7 +400,7 @@ async function scanValidated(
     const { raw, parsed } = loaded.value;
 
     if (record(parsed) && parsed.schemaVersion === '3.0.0') {
-      const authoring = parseParameterizedPackJson(parsed);
+      const authoring = parsePackSourceJson(parsed);
       if (!authoring.ok) {
         return packErr(
           makePackError('pack-malformed-pack', {
@@ -457,7 +455,7 @@ async function scanValidated(
         sourcePath: packPath,
         sourceRevision: `sha256:${createHash('sha256').update(raw).digest('hex')}`,
         sourceText: raw,
-        value: parsed as unknown as ParameterizedPackInventoryDocument,
+        value: parsed as unknown as PackSourceInventoryDocument,
       });
       continue;
     }
@@ -662,7 +660,7 @@ async function scanValidated(
     }
   }
 
-  // Parameterized source identity enters the package registry. Its outputs are
+  // ScriptablePack 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;
@@ -680,7 +678,7 @@ async function scanValidated(
       ...(opts.scriptablePack ?? {}),
       ...(capture === undefined ? { metadataOnly: true } : {}),
     };
-    const loaded = await loadParameterizedScriptablePack(sourcePath, loaderOptions);
+    const loaded = await loadScriptablePack(sourcePath, loaderOptions);
     if (!loaded.ok) {
       const diagnostic = loaded.error.detail.diagnostic;
       return packErr(
@@ -712,12 +710,12 @@ async function scanValidated(
     const packageCollision = registerPackage(
       PackageId.format(loaded.value.packageId),
       sourcePath,
-      'parameterized',
+      'scriptable',
     );
     if (packageCollision !== undefined) return packErr(packageCollision);
-    const meta = projectParameterizedPackMeta(loaded.value, sourcePath);
+    const meta = projectScriptablePackMeta(loaded.value, sourcePath);
     capture?.declarations.set(sourcePath, {
-      format: 'pack.ts-parameterized',
+      format: 'pack.ts',
       sourcePath,
       sourceRevision: `sha256:${createHash('sha256').update(source).digest('hex')}`,
       value: meta,
@@ -749,15 +747,15 @@ async function scanValidated(
       );
     }
     const kind = packageKind.get(parentId);
-    if (kind !== 'parameterized' && kind !== 'instance') {
+    if (kind !== 'scriptable' && kind !== 'instance') {
       return packErr(
         makePackError('pack-malformed-pack', {
           path: instance.path,
-          reason: 'pack-parent-not-parameterized',
+          reason: 'pack-parent-has-no-parameters',
           ajvErrors: [
             {
               instancePath: '/parent',
-              message: `parent ${instance.parent} is not a parameterized Pack`,
+              message: `parent ${instance.parent} is not a ScriptablePack source with parameters`,
             },
           ],
         }),
@@ -849,7 +847,7 @@ export async function scanInventory(
     const declaration = declarations.get(sourcePath);
     if (declaration?.format !== 'pack.json') continue;
     if (declaration.value.schemaVersion === '3.0.0') {
-      const parsed = parseParameterizedPackJson(declaration.value);
+      const parsed = parsePackSourceJson(declaration.value);
       if (!parsed.ok) {
         return packErr(
           makePackError('pack-malformed-pack', {

package/src/schema/material-cook.schema.json

@@ -107,7 +107,10 @@
         "derivedInterface": {
           "type": "object",
           "required": ["layoutIdentity"],
-          "properties": { "layoutIdentity": { "type": "string", "minLength": 1 } },
+          "properties": {
+            "layoutIdentity": { "type": "string", "minLength": 1 },
+            "layerPlanIdentity": { "type": "string", "minLength": 1 }
+          },
           "additionalProperties": false
         },
         "publicationGeneration": { "type": "integer", "minimum": 1 }