@forgeax/engine-import 0.1.3 → 0.1.6

package/src/scriptable-pack-output-producers.ts

@@ -1,9 +1,8 @@
-import { componentSchema } from '@forgeax/engine-ecs/internal';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { ScriptablePackSceneComponent } from '@forgeax/engine-pack/source';
 import { externalizeSceneAsset } from '@forgeax/engine-scene';
 import type {
   AnimationGraph,
-  Asset,
   AssetGuid as AssetGuidType,
   AssetRef,
   AudioClipAsset,
@@ -16,7 +15,6 @@ import type {
   MeshAsset,
   ParticleEffectAsset,
   RenderPipelineAsset,
-  Result,
   SamplerAsset,
   SceneAsset,
   SkeletonAsset,
@@ -154,18 +152,6 @@ function materialProduct(input: AssetOutputInput): AssetOutputProduct {
   };
 }
 
-export const materialAssetOutputProducer: AssetOutputProducer = {
-  kind: 'material',
-  version: 'material-pack/1',
-  produce(input): Result<AssetOutputProduct, ImportError> {
-    try {
-      return ok(materialProduct(input));
-    } catch (error) {
-      return err(producerError(input, error));
-    }
-  },
-};
-
 function meshProduct(input: AssetOutputInput): AssetOutputProduct {
   if (input.asset.kind !== 'mesh') throw new TypeError('expected MeshAsset');
   const mesh = input.asset as MeshAsset;
@@ -201,23 +187,19 @@ function meshProduct(input: AssetOutputInput): AssetOutputProduct {
   };
 }
 
-export const meshAssetOutputProducer: AssetOutputProducer = {
-  kind: 'mesh',
-  version: 'mesh-binary/4',
-  produce(input): Result<AssetOutputProduct, ImportError> {
-    try {
-      return ok(meshProduct(input));
-    } catch (error) {
-      return err(producerError(input, error));
-    }
-  },
-};
-
-function sceneProduct(input: AssetOutputInput): AssetOutputProduct {
+function sceneProduct(
+  input: AssetOutputInput,
+  components: ReadonlyMap<string, Readonly<Record<string, string>>>,
+): AssetOutputProduct {
   if (input.asset.kind !== 'scene') throw new TypeError('expected SceneAsset');
   const externalized = externalizeSceneAsset(input.asset as SceneAsset, (componentName) => {
-    const component = input.components?.get(componentName);
-    return component === undefined ? undefined : componentSchema(component);
+    const schema = components.get(componentName);
+    if (schema === undefined) {
+      throw new TypeError(
+        `ScriptablePack scene component ${componentName} is missing from sceneComponents`,
+      );
+    }
+    return schema;
   });
   if (!externalized.ok) throw new TypeError(`scene field ${externalized.error.field} is invalid`);
   return {
@@ -227,6 +209,24 @@ function sceneProduct(input: AssetOutputInput): AssetOutputProduct {
   };
 }
 
+function createSafeProducer(
+  kind: AssetOutputProducer['kind'],
+  version: string,
+  product: (input: AssetOutputInput) => AssetOutputProduct,
+): AssetOutputProducer {
+  return {
+    kind,
+    version,
+    produce(input) {
+      try {
+        return ok(product(input));
+      } catch (error) {
+        return err(producerError(input, error));
+      }
+    },
+  };
+}
+
 function jsonArtifact(value: unknown): ImportedArtifactBody {
   return {
     mediaType: 'application/json',
@@ -412,39 +412,29 @@ function ordinaryPodProduct(input: AssetOutputInput): AssetOutputProduct {
   }
 }
 
-const ordinaryAssetOutputProducer: AssetOutputProducer = {
-  kind: 'texture',
-  version: 'ordinary-pod/1',
-  produce(input) {
-    try {
-      return ok(ordinaryPodProduct(input));
-    } catch (error) {
-      return err(producerError(input, error));
-    }
-  },
-};
+export const materialAssetOutputProducer = createSafeProducer(
+  'material',
+  'material-pack/1',
+  materialProduct,
+);
+export const meshAssetOutputProducer = createSafeProducer('mesh', 'mesh-binary/4', meshProduct);
 
-function createOrdinaryAssetOutputProducer(kind: Asset['kind']): AssetOutputProducer {
-  return { ...ordinaryAssetOutputProducer, kind };
+export function createSceneAssetOutputProducer(
+  sceneComponents: readonly ScriptablePackSceneComponent[] = [],
+): AssetOutputProducer {
+  const schemas = new Map(
+    sceneComponents.map((component) => [component.name, component.fields] as const),
+  );
+  return createSafeProducer('scene', 'scene-pack/3', (input) => sceneProduct(input, schemas));
 }
 
-export const sceneAssetOutputProducer: AssetOutputProducer = {
-  kind: 'scene',
-  version: 'scene-pack/2',
-  produce(input): Result<AssetOutputProduct, ImportError> {
-    try {
-      return ok(sceneProduct(input));
-    } catch (error) {
-      return err(producerError(input, error));
-    }
-  },
-};
-
-export function createStandardAssetOutputProducerRegistry(): AssetOutputProducerRegistry {
+export function createStandardAssetOutputProducerRegistry(
+  sceneComponents: readonly ScriptablePackSceneComponent[] = [],
+): AssetOutputProducerRegistry {
   const registry = new AssetOutputProducerRegistry();
   registry.register(materialAssetOutputProducer);
   registry.register(meshAssetOutputProducer);
-  registry.register(sceneAssetOutputProducer);
+  registry.register(createSceneAssetOutputProducer(sceneComponents));
   for (const kind of [
     'texture',
     'equirect',
@@ -460,7 +450,7 @@ export function createStandardAssetOutputProducerRegistry(): AssetOutputProducer
     'audio',
     'particle-effect',
   ] as const) {
-    registry.register(createOrdinaryAssetOutputProducer(kind));
+    registry.register(createSafeProducer(kind, 'ordinary-pod/1', ordinaryPodProduct));
   }
   return registry;
 }

package/src/scriptable-pack-staged-snapshot.ts

@@ -26,8 +26,7 @@ export interface ScriptablePackStagedOwner {
 export interface ScriptablePackStagedSnapshotOptions {
   readonly generation: number;
   readonly owners: readonly ScriptablePackStagedOwner[];
-  /** A prebuilt authority only. Local source ownership always wins. */
-  readonly fallback?: ScriptablePackAssetSnapshotSource;
+  readonly declaredExternalOutputs?: readonly ScriptablePackStagedOutput[];
 }
 
 function stable(value: unknown): string {
@@ -81,8 +80,21 @@ function missingOutputError(owner: string, guid: string): ScriptablePackError {
 export function createScriptablePackStagedAssetSnapshotSource(
   options: ScriptablePackStagedSnapshotOptions,
 ): ScriptablePackAssetSnapshotSource {
+  const owners =
+    options.declaredExternalOutputs === undefined || options.declaredExternalOutputs.length === 0
+      ? options.owners
+      : [
+          {
+            id: '<declared-pack-external>',
+            guids: options.declaredExternalOutputs.map((output) => output.guid),
+            async build() {
+              return ok(options.declaredExternalOutputs ?? []);
+            },
+          } satisfies ScriptablePackStagedOwner,
+          ...options.owners,
+        ];
   const ownerByGuid = new Map<string, ScriptablePackStagedOwner>();
-  for (const owner of options.owners) {
+  for (const owner of owners) {
     if (owner.id.trim().length === 0) throw new TypeError('staged owner id must be non-empty');
     for (const guid of owner.guids) {
       const key = AssetGuid.format(guid).toLowerCase();
@@ -104,12 +116,11 @@ export function createScriptablePackStagedAssetSnapshotSource(
       if (cached !== undefined) return ok(structuredClone(cached));
       const owner = ownerByGuid.get(key);
       if (owner === undefined) {
-        if (options.fallback !== undefined) return options.fallback.readByGuid(guid);
         return err(
           new AssetError({
             code: 'asset-not-imported',
-            expected: 'a staged local owner or explicit prebuilt fallback for the requested GUID',
-            hint: 'declare the local ScriptablePack output or configure a prebuilt asset authority',
+            expected: 'a staged local owner for the requested GUID',
+            hint: 'declare the local ScriptablePack output before rebuilding the generation',
           }),
         );
       }

package/src/scriptable-pack.ts

@@ -1,29 +1,35 @@
-import type { Component } from '@forgeax/engine-ecs';
 import { isScriptablePackAssetKind, type ScriptablePackAssetKind } from '@forgeax/engine-pack';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   type AssetReader,
   projectScriptablePackMeta,
+  projectScriptablePackSceneComponents,
   type ScriptablePackDefinition,
   type ScriptablePackError,
   type ScriptablePackReadError,
+  type ScriptablePackSourceClosureEntry,
 } from '@forgeax/engine-pack/source';
 import type {
   AnimationGraph,
   Asset,
   AssetGuid as AssetGuidType,
   AssetPublicationEnvelope,
-  AssetRef,
   FontAsset,
-  ImportedArtifactBody,
   ImportedAsset,
-  ImportProduct,
   MaterialAsset,
   MeshAsset,
   Result,
   TilesetAsset,
 } from '@forgeax/engine-types';
+
+export type { ScriptablePackSourceClosureEntry } from '@forgeax/engine-pack/source';
+
 import { AssetError, err, ImportError, ok } from '@forgeax/engine-types';
+import {
+  createImportProduct,
+  type ImportAssetProduct,
+  type TerminalImportProduct,
+} from './import-product.js';
 
 function commonPathPrefix(paths: readonly string[]): string {
   const first = paths[0];
@@ -83,8 +89,6 @@ export interface AssetOutputInput {
   readonly guid: string;
   readonly sourceKey: string;
   readonly asset: Asset;
-  /** World-local schema projection for scene ref externalization. */
-  readonly components?: ReadonlyMap<string, Component>;
 }
 
 type MaterialPackPayload = Omit<MaterialAsset, 'parent' | 'values'> & {
@@ -132,11 +136,7 @@ export type AssetOutputPayloadByKind = {
 
 export type AssetOutputPayload = AssetOutputPayloadByKind[ScriptablePackAssetKind];
 
-export interface AssetOutputProduct {
-  readonly payload: AssetOutputPayload;
-  readonly refs: readonly AssetRef[];
-  readonly artifacts: Readonly<Record<string, ImportedArtifactBody>>;
-}
+export type AssetOutputProduct = ImportAssetProduct<AssetOutputPayload>;
 
 export interface AssetOutputProducer {
   readonly kind: string;
@@ -181,13 +181,8 @@ export interface ScriptablePackExternalEvidence {
   readonly digest?: string;
 }
 
-export interface ScriptablePackSourceClosureEntry {
-  readonly path: string;
-  readonly digest: string;
-}
-
 export interface ScriptablePackBuildProduct {
-  readonly product: ImportProduct<unknown>;
+  readonly product: TerminalImportProduct<unknown>;
   /** Raw private outputs for the current staged build generation, never a runtime publication path. */
   readonly stagedOutputs: readonly ScriptablePackStagedOutput[];
   readonly externalEvidence: readonly ScriptablePackExternalEvidence[];
@@ -269,7 +264,7 @@ function observedAssetReader(source?: ScriptablePackAssetSnapshotSource): {
           new AssetError({
             code: 'asset-not-found',
             expected: `a host Asset snapshot source for ScriptablePack content read ${key}`,
-            hint: 'configure pluginPack({ scriptablePack: { assetSource, ... } }) or remove the content read',
+            hint: 'configure the standard ScriptablePack asset source or remove the content read',
           }),
         );
       }
@@ -435,8 +430,6 @@ export interface BuildScriptablePackOptions {
   readonly outputs: AssetOutputProducerRegistry;
   readonly sourceClosure: readonly ScriptablePackSourceClosureEntry[];
   readonly authoringContractVersion: string;
-  /** Optional owner-provided component schema projection for scene output. */
-  readonly components?: ReadonlyMap<string, Component>;
 }
 
 /**
@@ -527,7 +520,6 @@ export async function buildScriptablePack(
       guid: AssetGuid.format(descriptor.guid),
       sourceKey,
       asset,
-      ...(options.components === undefined ? {} : { components: options.components }),
     });
     if (!product.ok) return err(product.error);
     const productError = productContractError(sourceKey, descriptor.kind, product.value);
@@ -579,19 +571,38 @@ export async function buildScriptablePack(
     usage,
     ...(digest === undefined ? {} : { digest }),
   }));
-  const product: ImportProduct<unknown> = {
-    assets,
-    sourceDependencies: options.sourceClosure.map((entry) => entry.path),
-  };
   const inputFingerprint = await fingerprint({
     meta: projectScriptablePackMeta(options.definition, options.sourcePath),
+    sceneComponents: projectScriptablePackSceneComponents(options.definition.sceneComponents),
     sourceClosure: stableSourceClosure(options.sourceClosure),
     externalEvidence: fingerprintEvidence,
     authoringContractVersion: options.authoringContractVersion,
     producerVersions: options.outputs.versions(),
   });
+  const refs = assets.flatMap((asset) => asset.refs);
+  const artifacts = Object.fromEntries(
+    assets.flatMap((asset) =>
+      Object.entries(asset.artifacts).map(([key, artifact]) => [`${asset.guid}/${key}`, artifact]),
+    ),
+  );
+  const product = createImportProduct({
+    assets,
+    sourceDependencies: options.sourceClosure.map((entry) => entry.path),
+    refs,
+    artifacts,
+    receipts: assets.map((asset) => ({
+      guid: asset.guid,
+      origin: 'sourceMeta' as const,
+      status: 'succeeded' as const,
+      inputFingerprint,
+    })),
+    diagnostics: [],
+    sourceRevision: inputFingerprint,
+    sourceKey: options.sourcePath,
+  });
+  if (!product.ok) return err(product.error);
   return ok({
-    product,
+    product: product.value,
     stagedOutputs: await Promise.all(
       Object.keys(options.definition.assets)
         .sort()

package/src/scriptable-source-package.ts

@@ -0,0 +1,88 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { projectScriptablePackMeta, type ScriptablePackError } from '@forgeax/engine-pack/source';
+import type {
+  AssetError,
+  ImportError,
+  ImportedAsset,
+  ImportProduct,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import {
+  type BuildScriptablePackOptions,
+  buildScriptablePack,
+  type ScriptablePackDomainError,
+  type ScriptablePackExternalEvidence,
+  type ScriptablePackStagedOutput,
+} from './scriptable-pack.js';
+
+const META_ARTIFACT_KEY = 'scriptable-pack.meta.json';
+
+export interface ScriptableSourcePackageProduct {
+  readonly anchorGuid: string;
+  readonly declaredGuids: readonly string[];
+  readonly product: ImportProduct<unknown>;
+  readonly inputFingerprint: string;
+  readonly externalEvidence: readonly ScriptablePackExternalEvidence[];
+  readonly stagedOutputs: readonly ScriptablePackStagedOutput[];
+}
+
+export type ScriptableSourcePackageResult = Result<
+  ScriptableSourcePackageProduct,
+  ScriptablePackError | AssetError | ImportError | ScriptablePackDomainError
+>;
+
+function withPrebuiltMeta<P>(
+  product: ImportProduct<P>,
+  anchorGuid: string,
+  meta: unknown,
+): ImportProduct<P> {
+  const bytes = new TextEncoder().encode(`${JSON.stringify(meta)}\n`);
+  return {
+    ...product,
+    assets: product.assets.map(
+      (asset): ImportedAsset<P> =>
+        asset.guid.toLowerCase() === anchorGuid
+          ? {
+              ...asset,
+              artifacts: {
+                ...asset.artifacts,
+                [META_ARTIFACT_KEY]: { mediaType: 'application/json', bytes },
+              },
+            }
+          : asset,
+    ),
+  };
+}
+
+export async function produceScriptableSourcePackage(
+  options: BuildScriptablePackOptions,
+): Promise<ScriptableSourcePackageResult> {
+  const built = await buildScriptablePack(options);
+  if (!built.ok) return err(built.error);
+  const declaredGuids = Object.values(options.definition.assets)
+    .map((descriptor) => AssetGuid.format(descriptor.guid).toLowerCase())
+    .sort();
+  const anchorGuid = declaredGuids[0];
+  if (anchorGuid === undefined) {
+    return err({
+      code: 'pack-source-output-invalid',
+      expected: 'at least one declared ScriptablePack output',
+      hint: 'add an output descriptor before building the package',
+      detail: { missingGuids: [], unexpectedSourceKeys: [], kindMismatches: [] },
+    });
+  }
+  const product = withPrebuiltMeta(
+    built.value.product,
+    anchorGuid,
+    projectScriptablePackMeta(options.definition, options.sourcePath),
+  );
+  return ok({
+    anchorGuid,
+    declaredGuids,
+    product,
+    stagedOutputs: built.value.stagedOutputs,
+    inputFingerprint: built.value.inputFingerprint,
+    externalEvidence: built.value.externalEvidence,
+  });
+}

package/src/source-package-errors.ts

@@ -0,0 +1,201 @@
+import type { ImportError } from '@forgeax/engine-types';
+
+const SOURCE_PACKAGE_ERROR_POLICY = {
+  'source-package-meta-invalid': {
+    expected: 'a valid source Meta declaration with complete GUID topology',
+    hint: 'repair the Meta declaration, then rebuild or cold-cook the source package',
+  },
+  'source-package-importer-missing': {
+    expected: 'a registered importer for the source Meta importer key',
+    hint: 'register the named importer, then rebuild or cold-cook the source package',
+  },
+  'source-package-conversion-failed': {
+    expected: 'the configured importer to convert the source successfully',
+    hint: 'repair the source or importer, then rebuild or cold-cook the source package',
+  },
+  'source-package-ddc-failed': {
+    expected: 'a readable persistent DDC entry with matching integrity evidence',
+    hint: 'discard the invalid derived entry, then rebuild or cold-cook the source package',
+  },
+  'source-package-publication-invalid': {
+    expected: 'a complete Pack body, refs, artifacts, and route integrity',
+    hint: 'repair the missing product bytes, then rebuild or cold-cook the source package',
+  },
+  'source-package-guid-closure-mismatch': {
+    expected: 'exactly one produced asset for every declared GUID',
+    hint: 'repair the Meta topology or importer output, then rebuild the whole source package',
+  },
+} as const;
+
+export type SourcePackageErrorCode = keyof typeof SOURCE_PACKAGE_ERROR_POLICY;
+
+export type SourcePackageErrorStage =
+  | 'meta'
+  | 'importer'
+  | 'conversion'
+  | 'closure'
+  | 'ddc'
+  | 'route-integrity';
+
+export interface SourcePackageErrorContext {
+  readonly sourceMeta: string;
+  readonly anchorGuid: string;
+  readonly affectedGuids: readonly string[];
+  readonly producer: string;
+  readonly importer: string;
+}
+
+export interface SourcePackageErrorDetail extends SourcePackageErrorContext {
+  readonly stage: SourcePackageErrorStage;
+  readonly reason?: string;
+  readonly missing?: readonly string[];
+  readonly unexpected?: readonly string[];
+  readonly registeredImporters?: readonly string[];
+}
+
+export interface SourcePackageError {
+  readonly code: SourcePackageErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SourcePackageErrorDetail;
+}
+
+export function sourcePackageError(
+  code: SourcePackageErrorCode,
+  context: SourcePackageErrorContext,
+  detail: Omit<SourcePackageErrorDetail, keyof SourcePackageErrorContext>,
+): SourcePackageError {
+  const policy = SOURCE_PACKAGE_ERROR_POLICY[code];
+  return {
+    code,
+    expected: policy?.expected as string,
+    hint: policy?.hint as string,
+    detail: { ...context, ...detail },
+  };
+}
+
+function unknownReason(error: unknown): string {
+  if (error !== null && typeof error === 'object') {
+    const value = error as Record<string, unknown>;
+    if (typeof value.code === 'string') {
+      const detail = value.detail;
+      const reason =
+        detail !== null && typeof detail === 'object' && 'reason' in detail
+          ? (detail as { readonly reason?: unknown }).reason
+          : undefined;
+      const diagnostic =
+        detail !== null && typeof detail === 'object' && 'diagnostic' in detail
+          ? (detail as { readonly diagnostic?: unknown }).diagnostic
+          : undefined;
+      return `${value.code}: ${
+        typeof diagnostic === 'string'
+          ? diagnostic
+          : typeof reason === 'string'
+            ? reason
+            : String(value.expected ?? 'producer failure')
+      }`;
+    }
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function importFailureCode(error: ImportError): SourcePackageErrorCode {
+  switch (error.code) {
+    case 'importer-not-registered':
+      return 'source-package-importer-missing';
+    case 'import-produced-no-assets':
+    case 'guid-mismatch':
+    case 'source-validation-failed':
+      return 'source-package-guid-closure-mismatch';
+    case 'source-read-failed':
+    case 'import-internal-error':
+    case 'mesh-material-slot-topology-change':
+    case 'unknown-source-key':
+    case 'duplicate-source-key':
+    case 'invalid-source-overrides':
+    case 'invalid-source-override-payload':
+      return 'source-package-conversion-failed';
+  }
+}
+
+export function normalizeSourcePackageError(
+  error: unknown,
+  context: SourcePackageErrorContext,
+): SourcePackageError {
+  if (isSourcePackageError(error)) return error;
+  if (isScriptablePackFailure(error)) {
+    return sourcePackageError('source-package-conversion-failed', context, {
+      stage: 'conversion',
+      reason: unknownReason(error),
+    });
+  }
+  if (isImportError(error)) {
+    const code = importFailureCode(error);
+    const detail: Omit<SourcePackageErrorDetail, keyof SourcePackageErrorContext> = {
+      stage: code === 'source-package-importer-missing' ? 'importer' : 'conversion',
+      reason: unknownReason(error),
+      ...(code === 'source-package-importer-missing' && 'registeredImporters' in error.detail
+        ? { registeredImporters: error.detail.registeredImporters }
+        : {}),
+    };
+    return sourcePackageError(code, context, detail);
+  }
+  return sourcePackageError(contextErrorStage(error), context, {
+    stage: 'conversion',
+    reason: unknownReason(error),
+  });
+}
+
+function isSourcePackageError(error: unknown): error is SourcePackageError {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    error.code in SOURCE_PACKAGE_ERROR_POLICY &&
+    'expected' in error &&
+    typeof error.expected === 'string' &&
+    'hint' in error &&
+    typeof error.hint === 'string' &&
+    'detail' in error &&
+    error.detail !== null &&
+    typeof error.detail === 'object'
+  );
+}
+
+function contextErrorStage(error: unknown): SourcePackageErrorCode {
+  return error instanceof SyntaxError
+    ? 'source-package-meta-invalid'
+    : 'source-package-conversion-failed';
+}
+
+function isImportError(error: unknown): error is ImportError {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    'expected' in error &&
+    'hint' in error &&
+    'detail' in error
+  );
+}
+
+function isScriptablePackFailure(error: unknown): error is {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: unknown;
+} {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    error.code.startsWith('pack-source-') &&
+    'expected' in error &&
+    typeof error.expected === 'string' &&
+    'hint' in error &&
+    typeof error.hint === 'string' &&
+    'detail' in error
+  );
+}