@forgeax/engine-import 0.1.3 → 0.1.6

package/src/import-product.ts

@@ -2,92 +2,58 @@ import type {
   ArtifactDescriptor,
   AssetRef,
   CookProduct,
+  CookReceipt,
   ImportedArtifactBody,
   ImportedAsset,
   ImportProduct,
-  MaterialAsset,
   Result,
 } from '@forgeax/engine-types';
 import { err, ok } from '@forgeax/engine-types';
 
-export interface MaterialImportRefs {
-  readonly parent: readonly string[];
-  readonly textures: readonly string[];
-  readonly samplers: readonly string[];
-  readonly modules: readonly string[];
+export interface TerminalImportProduct<P = unknown> extends ImportProduct<P> {
+  readonly refs: readonly AssetRef[];
+  readonly artifacts: Readonly<Record<string, ImportedArtifactBody>>;
+  readonly receipts: readonly CookReceipt[];
+  readonly diagnostics: readonly unknown[];
+  readonly sourceRevision: string;
+  readonly sourceKey?: string;
 }
 
-export interface MaterialSourceEvidence {
-  readonly inputFingerprint: string;
-  readonly importerVersion: string;
+export interface ImportAssetProduct<P = unknown> {
+  readonly payload: P;
+  readonly refs: readonly AssetRef[];
+  readonly artifacts: Readonly<Record<string, ImportedArtifactBody>>;
 }
 
-export interface MaterialImportProductInput {
-  readonly guid: string;
-  readonly sourcePath: string;
-  readonly material: MaterialAsset;
-  readonly refs: MaterialImportRefs;
-  readonly sourceEvidence: MaterialSourceEvidence;
-}
-
-export interface MaterialImportProduct {
-  readonly asset: ImportedAsset<MaterialAsset>;
-  readonly sourcePath: string;
-  readonly sourceEvidence: MaterialSourceEvidence;
-}
-
-export interface MaterialImportProductError {
-  readonly code: 'material-import-product-invalid';
+export interface ImportProductContractError {
+  readonly code: 'import-product-invalid';
   readonly expected: string;
   readonly hint: string;
   readonly detail: { readonly field: string };
 }
 
-function invalid(field: string): Result<never, MaterialImportProductError> {
+function invalidProduct(field: string): Result<never, ImportProductContractError> {
   return err({
-    code: 'material-import-product-invalid',
-    expected: 'an authored MaterialAsset with complete dependency references',
-    hint: 'declare every material dependency before the product enters the cook pipeline',
+    code: 'import-product-invalid',
+    expected: 'a complete terminal import product with source identity',
+    hint: 'preserve refs, artifacts, receipts, diagnostics, and source revision at the product boundary',
     detail: { field },
   });
 }
 
-function distinct(values: readonly string[]): readonly string[] {
-  return [...new Set(values)];
-}
-
-export function createMaterialImportProduct(
-  input: MaterialImportProductInput,
-): Result<MaterialImportProduct, MaterialImportProductError> {
-  if (!input.guid || !input.sourcePath) return invalid('guid/sourcePath');
-  if (input.material.kind !== 'material') return invalid('material.kind');
-  if (!input.sourceEvidence.inputFingerprint || !input.sourceEvidence.importerVersion) {
-    return invalid('sourceEvidence');
+export function createImportProduct<P = unknown>(
+  input: TerminalImportProduct<P>,
+): Result<TerminalImportProduct<P>, ImportProductContractError> {
+  if (!Array.isArray(input.assets)) return invalidProduct('assets');
+  if (!Array.isArray(input.sourceDependencies)) return invalidProduct('sourceDependencies');
+  if (input.sourceRevision.trim().length === 0) return invalidProduct('sourceRevision');
+  if (!Array.isArray(input.refs)) return invalidProduct('refs');
+  if (input.artifacts === null || typeof input.artifacts !== 'object') {
+    return invalidProduct('artifacts');
   }
-  const refs = distinct([
-    ...input.refs.parent,
-    ...input.refs.textures,
-    ...input.refs.samplers,
-    ...input.refs.modules,
-  ]);
-  return ok({
-    sourcePath: input.sourcePath,
-    sourceEvidence: input.sourceEvidence,
-    asset: {
-      guid: input.guid,
-      kind: 'material',
-      payload: input.material,
-      refs: refs.map((guid): AssetRef => ({ guid })),
-      artifacts: {},
-    },
-  });
-}
-
-export function materialImportProductReady(
-  product: MaterialImportProduct,
-  availableRefs: ReadonlySet<string>,
-): boolean {
-  return product.asset.refs.every((reference) => availableRefs.has(reference.guid));
+  if (!Array.isArray(input.receipts)) return invalidProduct('receipts');
+  if (!Array.isArray(input.diagnostics)) return invalidProduct('diagnostics');
+  return ok({ ...input });
 }
 
 async function sha256Hex(bytes: Uint8Array): Promise<string> {
@@ -123,7 +89,7 @@ async function productDigest(
   artifacts: Readonly<Record<string, ArtifactDescriptor>>,
 ): Promise<string> {
   const chunks: (Uint8Array | string)[] = [
-    JSON.stringify(digestPayload(asset)),
+    JSON.stringify(projectImportedAssetPayload(asset)),
     JSON.stringify(asset.refs.map((ref) => ref.guid)),
     JSON.stringify(artifacts),
   ];
@@ -154,15 +120,17 @@ async function artifactDescriptors(
   return Object.fromEntries(entries);
 }
 
-function digestPayload(asset: ImportedAsset<unknown>): unknown {
-  if (Object.keys(asset.artifacts).length === 0) return asset.payload;
+export function projectImportedAssetPayload(
+  asset: ImportedAsset<unknown>,
+): Record<string, unknown> {
+  const payload = asset.payload as Record<string, unknown>;
+  if (Object.keys(asset.artifacts).length === 0) return payload;
   if (asset.kind === 'mesh') return { kind: 'mesh' };
   if (asset.kind === 'texture' || asset.kind === 'equirect') {
-    const payload = asset.payload as Record<string, unknown>;
     const { data: _runtimeBytes, ...metadata } = payload;
     return metadata;
   }
-  return asset.payload;
+  return payload;
 }
 
 /** Convert each importer asset into the shared completed producer product. */

package/src/import-runner.ts

@@ -40,7 +40,11 @@ import {
   ImportError,
   validateSourceOverrideMap,
 } from '@forgeax/engine-types';
-import { finalizeImportProducts } from './import-product.js';
+import {
+  createImportProduct,
+  finalizeImportProducts,
+  type TerminalImportProduct,
+} from './import-product.js';
 import type { ImporterRegistry } from './importer-registry.js';
 
 /** Reserved `meta.importer` key consumed by vite-plugin-shader, not the import runner. */
@@ -122,7 +126,7 @@ export type RunImportProductResult =
       readonly value:
         | { readonly skipped: 'shader' }
         | {
-            readonly product: ImportProduct;
+            readonly product: TerminalImportProduct;
             readonly cookProducts: readonly CookProduct[];
           };
     }
@@ -136,7 +140,7 @@ export type RunImportProductResult =
 export type RunImportOk =
   | { readonly skipped: 'shader' }
   | {
-      readonly product: ImportProduct;
+      readonly product: TerminalImportProduct;
       readonly cookProducts: readonly CookProduct[];
       readonly pack: DdcPack;
     };
@@ -166,6 +170,8 @@ export interface DdcPack {
 export interface RunImportMeta {
   readonly importer: string;
   readonly source: string;
+  /** Scanner-owned source declaration revision; avoids reopening validated Meta. */
+  readonly sourceRevision?: string;
   readonly packageId?: string;
   readonly provenance?: ProviderProvenance;
   readonly revision?: ResourceRevision;
@@ -669,10 +675,35 @@ export async function runImport(
       }),
     );
   }
+  const terminalProduct = createImportProduct({
+    ...productWithDependencies,
+    refs: productWithDependencies.assets.flatMap((asset) => asset.refs),
+    artifacts: Object.fromEntries(
+      productWithDependencies.assets.flatMap((asset) =>
+        Object.entries(asset.artifacts).map(([key, artifact]) => [
+          `${asset.guid}/${key}`,
+          artifact,
+        ]),
+      ),
+    ),
+    receipts: cookProducts.map((product) => product.receipt),
+    diagnostics: meta.diagnostics ?? [],
+    sourceRevision: inputFingerprint,
+  });
+  if (!terminalProduct.ok) {
+    return errResult(
+      new ImportError({
+        code: 'import-internal-error',
+        expected: 'the import product to retain complete terminal producer facts',
+        hint: 'preserve source identity and producer evidence when returning the import product',
+        detail: { reason: terminalProduct.error.detail.field },
+      }),
+    );
+  }
   if (meta.buildPack === false) {
     return {
       ok: true,
-      value: { product: productWithDependencies, cookProducts },
+      value: { product: terminalProduct.value, cookProducts },
     };
   }
 
@@ -710,9 +741,7 @@ export async function runImport(
   return {
     ok: true,
     value: {
-      product: {
-        ...productWithDependencies,
-      },
+      product: terminalProduct.value,
       cookProducts,
       pack,
     },

package/src/importer-registry.ts

@@ -19,7 +19,7 @@
 // idempotent on a repeated key (last write wins, no throw) so re-wiring a
 // registry across build invocations is safe.
 
-import type { Importer } from '@forgeax/engine-types';
+import type { Importer, ImporterCapabilities, ImportSubAsset } from '@forgeax/engine-types';
 
 /**
  * Injectable `meta.importer` -> {@link Importer} table held by the import
@@ -77,4 +77,27 @@ export class ImporterRegistry {
   registeredImporters(): readonly string[] {
     return [...this.importers.keys()];
   }
+
+  /** Project the first registered producer capability into the runner context. */
+  contextCapabilities(): ImporterCapabilities {
+    for (const importer of this.importers.values()) {
+      const decoder = importer.capabilities?.decodeImage;
+      if (decoder !== undefined) return { decodeImage: decoder };
+    }
+    return {};
+  }
+
+  /** Ask the registered producer whether a declaration has a Catalog product. */
+  shouldPublishCatalog(input: {
+    readonly importer: string;
+    readonly importSettings: Readonly<Record<string, unknown>>;
+    readonly subAssets: readonly ImportSubAsset[];
+  }): boolean {
+    return (
+      this.get(input.importer)?.capabilities?.catalog?.publish?.({
+        importSettings: input.importSettings,
+        subAssets: input.subAssets,
+      }) ?? true
+    );
+  }
 }

package/src/index.ts

@@ -46,14 +46,26 @@ export {
   type ImportTransport,
 } from '@forgeax/engine-types';
 export {
-  createMaterialImportProduct,
+  type BuildProductionFailure,
+  type BuildProductionFile,
+  type BuildProductionOptions,
+  type BuildProductionSink,
+  produceBuildAssets,
+  type ScriptableBuildPackage,
+} from './build-production.js';
+export {
+  type CatalogImporterDisposition,
+  type CatalogImporterPolicy,
+  catalogImporterPolicy,
+  DEFAULT_CATALOG_IMPORTER_KEYS,
+} from './catalog-importer-policy.js';
+export { buildCatalogResult } from './catalog-inventory.js';
+export {
+  createImportProduct,
   finalizeImportProducts,
-  type MaterialImportProduct,
-  type MaterialImportProductError,
-  type MaterialImportProductInput,
-  type MaterialImportRefs,
-  type MaterialSourceEvidence,
-  materialImportProductReady,
+  type ImportAssetProduct,
+  type ImportProductContractError,
+  type TerminalImportProduct,
 } from './import-product.js';
 export {
   type DdcPack,
@@ -71,6 +83,7 @@ export {
   type MeshBinEncodeError,
   packMeshBinV4,
 } from './mesh-bin.js';
+export { projectImportProductForBuild } from './pack-projection.js';
 export {
   type AssetOutputInput,
   type AssetOutputPayload,
@@ -90,10 +103,29 @@ export {
   type ScriptablePackStagedOutput,
 } from './scriptable-pack.js';
 export {
+  type AuthoredPackTransport,
+  type CookedAuthoredPack,
+  canonicalScriptableSourcePath,
+  declaredPackExternalOutputs,
+  materializePreparedScriptablePack,
+  type PreparedScriptablePack,
+  prepareAuthoredPackTransport,
+  produceScriptablePackProducts,
+  projectScriptablePackPublication,
+  readCookedAuthoredPack,
+  type ScriptablePackExternalImportOptions,
+  type ScriptablePackInput,
+  type ScriptablePackPublicationFacts,
+  type ScriptablePackTransportPaths,
+  type ScriptablePackTransportPolicy,
+  type ScriptablePackTransportSink,
+  scriptablePackInputs,
+} from './scriptable-pack-host.js';
+export {
+  createSceneAssetOutputProducer,
   createStandardAssetOutputProducerRegistry,
   materialAssetOutputProducer,
   meshAssetOutputProducer,
-  sceneAssetOutputProducer,
 } from './scriptable-pack-output-producers.js';
 export {
   createScriptablePackStagedAssetSnapshotSource,
@@ -101,3 +133,43 @@ export {
   type ScriptablePackStagedOwner,
   type ScriptablePackStagedSnapshotOptions,
 } from './scriptable-pack-staged-snapshot.js';
+export {
+  produceScriptableSourcePackage,
+  type ScriptableSourcePackageProduct,
+  type ScriptableSourcePackageResult,
+} from './scriptable-source-package.js';
+export {
+  finalizeSourcePackage,
+  type ProducerReadiness,
+  type ProducerReadinessError,
+  type ProducerReadinessResult,
+  parseProducerReadiness,
+  produceSourcePackage,
+  type SourcePackageClosureDetail,
+  type SourcePackageClosureError,
+  type SourcePackageProducerInput,
+  type SourcePackageProducerResult,
+  type SourcePackageProduct,
+  sourcePackageAssetsByGuid,
+} from './source-package.js';
+export {
+  normalizeSourcePackageError,
+  type SourcePackageError,
+  type SourcePackageErrorCode,
+  type SourcePackageErrorContext,
+  type SourcePackageErrorDetail,
+  type SourcePackageErrorStage,
+  sourcePackageError,
+} from './source-package-errors.js';
+export {
+  commitImportPublication,
+  discardImportPublication,
+  type ImportPublicationError,
+  type ImportPublicationInput,
+  type ImportPublicationResult,
+  publishImportPublication,
+  restoreImportPublication,
+  type StagedImportPublication,
+  type StagedImportPublicationResult,
+  stageImportPublication,
+} from './source-package-publication.js';

package/src/mesh-bin.ts

@@ -1,11 +1,11 @@
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   MESH_BIN_HEADER_V4_BYTES,
   type MeshBinContractError,
   type MeshBinHeaderV4,
   writeMeshBinHeader,
-} from '@forgeax/engine-pack';
-import { AssetGuid } from '@forgeax/engine-pack/guid';
+} from '@forgeax/engine-pack/mesh-bin-contract';
 import {
   err,
   type MeshAsset,

package/src/pack-projection.ts

@@ -0,0 +1,21 @@
+import type { ImportProduct } from '@forgeax/engine-types';
+import { projectImportedAssetPayload } from './import-product.js';
+import { type DdcPack, normaliseForPack } from './import-runner.js';
+
+/** Project one validated import product into the canonical Pack v2 payload. */
+export function projectImportProductForBuild(
+  product: Pick<ImportProduct<unknown>, 'assets'>,
+): DdcPack {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: product.assets.map((asset) => ({
+      guid: asset.guid,
+      kind: asset.kind,
+      ...(asset.name === undefined ? {} : { name: asset.name }),
+      payload: normaliseForPack(projectImportedAssetPayload(asset)) as Record<string, unknown>,
+      refs: asset.refs.map((reference) => reference.guid),
+      artifacts: asset.artifacts,
+    })),
+  };
+}