@forgeax/engine-import 0.1.23 → 0.1.25

package/src/__tests__/source-package-publication.integration.test.ts

@@ -1,6 +1,8 @@
+import { createHash } from 'node:crypto';
 import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { DdcEntryStore } from '@forgeax/engine-ddc';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
   commitImportPublication,
@@ -11,6 +13,40 @@ import {
 
 const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
 const KEY = 'a'.repeat(64);
+const ARTIFACT_PATH = `${GUID}/body.bin`;
+const ARTIFACT_BYTES = new Uint8Array([9, 8, 7]);
+const ARTIFACT_DIGEST = `sha256:${createHash('sha256').update(ARTIFACT_BYTES).digest('hex')}`;
+
+const validArtifact = {
+  path: ARTIFACT_PATH,
+  mediaType: 'application/octet-stream',
+  bytes: ARTIFACT_BYTES,
+};
+
+const validDescriptor = {
+  path: ARTIFACT_PATH,
+  mediaType: validArtifact.mediaType,
+  byteLength: ARTIFACT_BYTES.byteLength,
+  integrity: { algorithm: 'sha256' as const, digest: ARTIFACT_DIGEST },
+};
+
+function closurePack(
+  artifacts: Readonly<Record<string, unknown>> = { body: validDescriptor },
+): Record<string, unknown> {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: [
+      {
+        guid: GUID,
+        kind: 'fixture',
+        payload: { value: 'same' },
+        refs: [],
+        artifacts,
+      },
+    ],
+  };
+}
 
 function input(root: string, desiredKey = KEY): ImportPublicationInput {
   return {
@@ -97,4 +133,109 @@ describe('source package publication concurrency', () => {
       false,
     );
   });
+
+  it('publishes the complete transport artifact closure into the DDC entry', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-source-publication-'));
+    roots.push(root);
+    const pack = closurePack();
+    const publicationInput = {
+      ...input(root),
+      pack,
+      transport: {
+        path: join(root, 'runtime', `${GUID}.pack.json`),
+        body: JSON.stringify(pack),
+        artifacts: [validArtifact],
+      },
+    };
+
+    const staged = await stageImportPublication(publicationInput);
+    expect(staged.ok).toBe(true);
+    if (!staged.ok) return;
+    await expect(commitImportPublication(staged.candidate)).resolves.toMatchObject({ ok: true });
+
+    const entry = await new DdcEntryStore(root).read(KEY);
+    expect(entry?.artifacts[ARTIFACT_PATH]).toMatchObject({
+      mediaType: validArtifact.mediaType,
+      bytes: validArtifact.bytes,
+    });
+  });
+
+  it.each([
+    {
+      label: 'missing body',
+      pack: closurePack(),
+      artifacts: [],
+    },
+    {
+      label: 'media type mismatch',
+      pack: closurePack(),
+      artifacts: [{ ...validArtifact, mediaType: 'application/x-wrong' }],
+    },
+    {
+      label: 'byte length mismatch',
+      pack: closurePack(),
+      artifacts: [{ ...validArtifact, bytes: new Uint8Array([9, 8]) }],
+    },
+    {
+      label: 'sha256 mismatch',
+      pack: closurePack({
+        body: {
+          ...validDescriptor,
+          integrity: { algorithm: 'sha256' as const, digest: 'sha256:bad' },
+        },
+      }),
+      artifacts: [validArtifact],
+    },
+    {
+      label: 'duplicate transport path',
+      pack: closurePack(),
+      artifacts: [validArtifact, validArtifact],
+    },
+    {
+      label: 'duplicate descriptor path',
+      pack: closurePack({ body: validDescriptor, alias: { ...validDescriptor } }),
+      artifacts: [validArtifact],
+    },
+    {
+      label: 'unexpected transport body',
+      pack: closurePack(),
+      artifacts: [
+        validArtifact,
+        {
+          path: `${GUID}/extra.bin`,
+          mediaType: 'application/octet-stream',
+          bytes: new Uint8Array([1]),
+        },
+      ],
+    },
+    {
+      label: 'transport body mismatch',
+      pack: closurePack(),
+      body: JSON.stringify({ schemaVersion: '2.0.0', kind: 'internal-text-package', assets: [] }),
+      artifacts: [validArtifact],
+    },
+  ] as const)('rejects $label before advancing the DDC head', async ({ pack, artifacts, body }) => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-source-publication-'));
+    roots.push(root);
+    const publicationInput: ImportPublicationInput = {
+      ...input(root),
+      pack,
+      transport: {
+        path: join(root, 'runtime', `${GUID}.pack.json`),
+        body: body ?? JSON.stringify(pack),
+        artifacts,
+      },
+    };
+
+    const staged = await stageImportPublication(publicationInput);
+
+    expect(staged).toMatchObject({
+      ok: false,
+      error: {
+        code: 'source-package-publication-invalid',
+      },
+      head: { state: 'missing' },
+    });
+    expect(await new DdcEntryStore(root).listKeys()).toEqual([]);
+  });
 });

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,22 @@ 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,
+    cookers: context.cookers,
     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 +539,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 +654,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 +849,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 +859,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,