@forgeax/engine-pack 0.1.3 → 0.1.4

package/src/catalog-projection.ts

@@ -0,0 +1,344 @@
+import type {
+  AssetAuthoringCapability,
+  AssetPublicationEnvelope,
+  AssetRelation,
+  CatalogDiagnostic,
+  CatalogEntryV2,
+  CatalogLifecycle,
+  CatalogSubject,
+  CookExecution,
+  PackIndexEntry,
+  ProducerContractDiagnostic,
+  ProducerContractResult,
+  ProviderProvenance,
+  ResourceRevision,
+  SourceOverrideDescriptor,
+} from '@forgeax/engine-types';
+import { authoringCapabilityForAssetKind, catalogOperationsFor } from '@forgeax/engine-types';
+import { isScriptablePackAssetKind } from './scriptable-pack.js';
+
+export function catalogProjectionFor(
+  subject: 'internal-asset' | 'imported-output',
+  execution: 'direct' | 'cooked',
+  lifecycle: 'missing' | 'cooking' | 'current' | 'stale' | 'failed',
+) {
+  return {
+    subject,
+    execution,
+    lifecycle,
+    operations: catalogOperationsFor({ subject, execution, lifecycle }),
+  } as const;
+}
+
+export function currentProjectionFor(
+  subject: 'internal-asset' | 'imported-output',
+  execution: 'direct' | 'cooked',
+) {
+  return catalogRowProjectionFor(subject, execution, 'current');
+}
+
+function catalogRowProjectionFor(
+  subject: 'internal-asset' | 'imported-output',
+  execution: 'direct' | 'cooked',
+  lifecycle: 'missing' | 'cooking' | 'current' | 'stale' | 'failed',
+) {
+  const projection = catalogProjectionFor(subject, execution, lifecycle);
+  return { ...projection, projection } as const;
+}
+
+export interface CatalogProducerMeta {
+  readonly schemaVersion: string | number;
+  readonly packageId?: string;
+  readonly provenance?: ProviderProvenance;
+  readonly revision?: ResourceRevision;
+  readonly diagnostics?: readonly CatalogDiagnostic[];
+  readonly provider?: string;
+  readonly importer?: string;
+  readonly sourceOverrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly sourceOverrideDescriptors?: readonly SourceOverrideDescriptor[];
+}
+
+export interface CatalogOutputDeclaration {
+  readonly guid: string;
+  readonly kind: string;
+  readonly sourceKey?: string;
+  readonly sourceIndex?: number;
+  readonly relations?: PackIndexEntry['relations'];
+  readonly authoring?: AssetAuthoringCapability;
+  readonly refs?: readonly string[];
+  readonly name?: string;
+}
+
+function referenceRelations(
+  guid: string,
+  refs: readonly string[] | undefined,
+  provenance: ProviderProvenance,
+): readonly AssetRelation[] | undefined {
+  if (refs === undefined || refs.length === 0) return undefined;
+  return refs.map((ref) => ({
+    from: { type: 'asset', id: guid } as const,
+    to: { type: 'asset', id: ref } as const,
+    type: 'references' as const,
+    policy: { strength: 'required' as const },
+    provenance,
+  }));
+}
+
+function producerFields(
+  producer: CatalogProducerMeta,
+  output: CatalogOutputDeclaration,
+): Pick<
+  PackIndexEntry,
+  | 'packageId'
+  | 'provenance'
+  | 'revision'
+  | 'sourceKey'
+  | 'sourceIndex'
+  | 'sourceOverrides'
+  | 'sourceOverrideDescriptors'
+  | 'relations'
+  | 'diagnostics'
+  | 'subject'
+  | 'execution'
+  | 'lifecycle'
+  | 'projection'
+  | 'authoring'
+> {
+  const provenance =
+    producer.provenance ??
+    ({
+      provider: producer.provider ?? producer.importer ?? 'engine',
+      version: String(producer.schemaVersion),
+    } satisfies ProviderProvenance);
+  const relations = output.relations ?? referenceRelations(output.guid, output.refs, provenance);
+  const inferred = authoringCapabilityForAssetKind(output.kind);
+  return {
+    provenance,
+    ...(producer.packageId === undefined ? {} : { packageId: producer.packageId }),
+    ...(producer.revision === undefined ? {} : { revision: producer.revision }),
+    ...(output.sourceKey === undefined ? {} : { sourceKey: output.sourceKey }),
+    ...(output.sourceIndex === undefined ? {} : { sourceIndex: output.sourceIndex }),
+    ...(producer.sourceOverrides === undefined
+      ? {}
+      : { sourceOverrides: producer.sourceOverrides }),
+    ...(producer.sourceOverrideDescriptors === undefined || output.sourceKey === undefined
+      ? {}
+      : {
+          sourceOverrideDescriptors: producer.sourceOverrideDescriptors.filter(
+            (descriptor) => descriptor.sourceKey === output.sourceKey,
+          ),
+        }),
+    ...(relations === undefined ? {} : { relations }),
+    ...(producer.diagnostics === undefined ? {} : { diagnostics: producer.diagnostics }),
+    ...(output.authoring === undefined && inferred.ui === undefined
+      ? {}
+      : { authoring: output.authoring ?? inferred }),
+    ...catalogRowProjectionFor('imported-output', 'cooked', 'missing'),
+  };
+}
+
+/** Project producer declarations without interpreting a provider's kind vocabulary. */
+export function projectExternalCatalogEntries(
+  producer: CatalogProducerMeta,
+  sourcePath: string,
+  packageUrl: string,
+  outputs: readonly CatalogOutputDeclaration[],
+  nameFor?: (output: CatalogOutputDeclaration, index: number) => string | undefined,
+): PackIndexEntry[] {
+  return outputs.map((output, index) => ({
+    guid: output.guid,
+    packageUrl,
+    kind: output.kind,
+    sourcePath,
+    ...producerFields(producer, output),
+    ...((nameFor?.(output, index) ?? output.name) === undefined
+      ? {}
+      : { name: nameFor?.(output, index) ?? output.name }),
+  }));
+}
+
+/** Return the first declaration that would shadow an engine-owned Pack kind. */
+export function findReservedAssetKindConflict(
+  outputs: readonly Pick<CatalogOutputDeclaration, 'kind'>[],
+): Pick<CatalogOutputDeclaration, 'kind'> | undefined {
+  return outputs.find((output) => isScriptablePackAssetKind(output.kind));
+}
+
+export interface PackageCatalogInput {
+  readonly guid: string;
+  readonly kind: string;
+  readonly sourcePath: string;
+  readonly name?: string;
+  readonly refs?: readonly string[];
+  readonly authoring?: AssetAuthoringCapability;
+  readonly execution?: 'direct' | 'cooked';
+  readonly packageId?: string;
+  readonly provenance?: ProviderProvenance;
+  readonly revision?: ResourceRevision;
+  readonly sourceKey?: string;
+  readonly sourceIndex?: number;
+  readonly sourceOverrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly sourceOverrideDescriptors?: readonly SourceOverrideDescriptor[];
+  readonly relations?: PackIndexEntry['relations'];
+  readonly diagnostics?: readonly CatalogDiagnostic[];
+  readonly cookReceiptUrl?: string;
+}
+
+/** Project self-contained Pack rows into the same Catalog contract as producer output. */
+export function projectPackageCatalog(
+  entries: readonly PackageCatalogInput[],
+  packageUrl: string,
+): PackIndexEntry[] {
+  return entries.map((entry) => {
+    const execution = entry.execution ?? 'direct';
+    const lifecycle = execution === 'cooked' ? 'missing' : 'current';
+    const inferred = authoringCapabilityForAssetKind(entry.kind);
+    const provenance =
+      entry.provenance ?? ({ provider: 'pack', version: 'unknown' } satisfies ProviderProvenance);
+    const relations = entry.relations ?? referenceRelations(entry.guid, entry.refs, provenance);
+    return {
+      guid: entry.guid,
+      kind: entry.kind,
+      sourcePath: entry.sourcePath,
+      packageUrl,
+      ...(entry.name === undefined ? {} : { name: entry.name }),
+      ...(entry.refs === undefined ? {} : { refs: entry.refs }),
+      ...(entry.packageId === undefined ? {} : { packageId: entry.packageId }),
+      ...(entry.provenance === undefined ? {} : { provenance: entry.provenance }),
+      ...(entry.revision === undefined ? {} : { revision: entry.revision }),
+      ...(entry.sourceKey === undefined ? {} : { sourceKey: entry.sourceKey }),
+      ...(entry.sourceIndex === undefined ? {} : { sourceIndex: entry.sourceIndex }),
+      ...(entry.sourceOverrides === undefined ? {} : { sourceOverrides: entry.sourceOverrides }),
+      ...(entry.sourceOverrideDescriptors === undefined
+        ? {}
+        : { sourceOverrideDescriptors: entry.sourceOverrideDescriptors }),
+      ...(relations === undefined ? {} : { relations }),
+      ...(entry.diagnostics === undefined ? {} : { diagnostics: entry.diagnostics }),
+      ...(entry.cookReceiptUrl === undefined ? {} : { cookReceiptUrl: entry.cookReceiptUrl }),
+      ...(entry.authoring === undefined && inferred.ui === undefined
+        ? {}
+        : { authoring: entry.authoring ?? inferred }),
+      ...catalogRowProjectionFor('internal-asset', execution, lifecycle),
+    };
+  });
+}
+
+export interface CookedPackageProjection {
+  readonly packageUrl: string;
+  readonly revision: ResourceRevision;
+  readonly refs: readonly string[];
+  readonly cookReceiptUrl?: string;
+  readonly publication?: AssetPublicationEnvelope;
+}
+
+/** Project one complete cooked package; navigation facts stay in the Pack owner. */
+export function projectCookedPackageEntry(
+  entry: PackIndexEntry,
+  projection: CookedPackageProjection,
+): PackIndexEntry {
+  return {
+    ...entry,
+    ...(projection.publication === undefined
+      ? {}
+      : { sourcePath: projection.publication.sourcePath }),
+    packageUrl: projection.packageUrl,
+    ...(projection.cookReceiptUrl === undefined
+      ? {}
+      : { cookReceiptUrl: projection.cookReceiptUrl }),
+    revision: projection.revision,
+    ...(projection.publication === undefined ? {} : { publication: projection.publication }),
+    ...currentProjectionFor('imported-output', 'cooked'),
+    refs: projection.refs,
+  };
+}
+
+export interface RuntimeCatalogRowInput {
+  readonly scopeId: string;
+  readonly generation: number;
+  readonly digest: string;
+  readonly outputSetDigest: string;
+  readonly guid: string;
+  readonly kind: string;
+  readonly packageUrl: string;
+  readonly sourcePath?: string;
+  readonly subject?: CatalogSubject;
+  readonly execution?: CookExecution;
+  readonly lifecycle?: CatalogLifecycle;
+  readonly publication?: unknown;
+}
+
+function runtimeCatalogRowError(
+  subjectId: string,
+  expected: string,
+): ProducerContractResult<never> {
+  const diagnostic: ProducerContractDiagnostic = {
+    code: 'invalid-producer-fact',
+    subject: { type: 'asset', id: subjectId },
+    expected,
+    hint: 'recook the source and publish one current runtime Catalog row',
+    authority: 'producer',
+  };
+  return { ok: false, error: diagnostic };
+}
+
+function projectRuntimeCatalogRowValue(
+  input: RuntimeCatalogRowInput,
+): ProducerContractResult<CatalogEntryV2> {
+  if (
+    input.publication !== undefined ||
+    input.guid.length === 0 ||
+    input.kind.length === 0 ||
+    input.packageUrl.length === 0 ||
+    input.scopeId.length === 0 ||
+    !Number.isInteger(input.generation) ||
+    input.generation < 1 ||
+    input.digest.length === 0 ||
+    input.outputSetDigest.length === 0
+  ) {
+    return runtimeCatalogRowError(
+      input.guid,
+      'one flat publication tuple and no legacy publication object',
+    );
+  }
+
+  const subject = input.subject ?? 'imported-output';
+  const execution = input.execution ?? 'cooked';
+  const lifecycle = input.lifecycle ?? 'current';
+  return {
+    ok: true,
+    value: {
+      scopeId: input.scopeId,
+      generation: input.generation,
+      digest: input.digest,
+      outputSetDigest: input.outputSetDigest,
+      guid: input.guid,
+      kind: input.kind,
+      packageUrl: input.packageUrl,
+      sourcePath: input.sourcePath ?? input.packageUrl,
+      subject,
+      execution,
+      lifecycle,
+      projection: {
+        subject,
+        execution,
+        lifecycle,
+        operations: catalogOperationsFor({ subject, execution, lifecycle }),
+      },
+    },
+  };
+}
+
+/** Project one row; an array is accepted only to fail closed on double rows. */
+export function projectRuntimeCatalogRow(
+  input: RuntimeCatalogRowInput | readonly RuntimeCatalogRowInput[],
+): ProducerContractResult<CatalogEntryV2> {
+  if (Array.isArray(input)) {
+    if (input.length !== 1) {
+      return runtimeCatalogRowError(input[0]?.guid ?? 'unknown', 'exactly one runtime row');
+    }
+    const [row] = input;
+    if (row === undefined) return runtimeCatalogRowError('unknown', 'exactly one runtime row');
+    return projectRuntimeCatalogRowValue(row);
+  }
+  return projectRuntimeCatalogRowValue(input as RuntimeCatalogRowInput);
+}

package/src/cli-asset.ts

@@ -27,7 +27,7 @@ import { readSourceInventory } from './evidence/source-inventory.js';
 import { isValidAssetGuidString } from './guid.js';
 import { parsePackV2 } from './index.js';
 import { scan } from './scanner.js';
-import { projectScriptablePackMeta } from './scriptable-pack.js';
+import { isRecord, projectScriptablePackMeta } from './scriptable-pack.js';
 import { loadScriptablePack } from './scriptable-pack-node.js';
 
 export interface PackEntry {
@@ -453,10 +453,6 @@ function catalogRows(value: unknown): readonly Record<string, unknown>[] | undef
   return value.entries.filter(isRecord);
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 function packagePath(projectRoot: string, packageUrl: string): string {
   const relative = packageUrl.replace(/^\/+/, '');
   return resolve(projectRoot, relative);

package/src/index.ts

@@ -1,6 +1,6 @@
 // @forgeax/engine-pack
-// Disk schema, GUID tools, scanner, fail-fast error chain, and CLI bin.
-// Entry subpaths: . / schema / guid / errors / bridge / scanner
+// Disk schema, GUID tools, and browser-safe asset contracts.
+// Node-only catalog/build APIs live under @forgeax/engine-pack/build.
 
 export {
   type CookedMaterialRecord,

package/src/material-cook.ts

@@ -0,0 +1,13 @@
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  type MaterialCookArtifact,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  serializeMaterialCookReceipt,
+  validateCookedMaterialRecord,
+} from './evidence/material-cook.js';

package/src/native-cooker-registry.ts

@@ -28,6 +28,27 @@ export interface NativeCooker<P = unknown, I = unknown> {
   cook(input: I): NativeCookDraft<P> | Promise<NativeCookDraft<P>>;
 }
 
+export interface NativeCookTransactionSnapshot<P = unknown> {
+  readonly draft: NativeCookDraft<P>;
+  readonly generation: number;
+}
+
+export interface NativeCookTransactionOptions<P = unknown, I = unknown> {
+  readonly key: string;
+  readonly input: I;
+  readonly previous?: NativeCookTransactionSnapshot<P>;
+  readonly validate?: (draft: NativeCookDraft<P>) => string | undefined;
+  readonly publish?: (draft: NativeCookDraft<P>, generation: number) => void | Promise<void>;
+}
+
+export interface NativeCookTransactionResult<P = unknown> extends NativeCookTransactionSnapshot<P> {
+  readonly status: 'committed' | 'recovered';
+  readonly lastKnownGood: NativeCookDraft<P>;
+  readonly candidateGeneration: number;
+  readonly lastKnownGoodGeneration: number;
+  readonly recoveryHint?: string;
+}
+
 function canonicalize(value: unknown): unknown {
   if (value instanceof Uint8Array) return Buffer.from(value).toString('base64');
   if (Array.isArray(value)) return value.map(canonicalize);
@@ -67,6 +88,24 @@ function failure(key: string, detail: NativeCookErrorDetail): Result<never, Asse
   });
 }
 
+function transactionFailure(key: string, reason: string): Result<never, AssetStageError> {
+  return failure(key, { guid: 'unknown', producer: reason });
+}
+
+function recovered<P>(
+  key: string,
+  previous: NativeCookTransactionSnapshot<P>,
+): NativeCookTransactionResult<P> {
+  return {
+    ...previous,
+    status: 'recovered',
+    lastKnownGood: previous.draft,
+    candidateGeneration: previous.generation + 1,
+    lastKnownGoodGeneration: previous.generation,
+    recoveryHint: `repair ${key} and submit a new candidate generation`,
+  };
+}
+
 /** Injectable build-time table for native authored Pack producers. */
 export class NativeCookerRegistry {
   private readonly cookers = new Map<string, NativeCooker>();
@@ -160,4 +199,37 @@ export class NativeCookerRegistry {
     };
     return ok(product);
   }
+
+  async runTransaction<P = unknown, I = unknown>(
+    options: NativeCookTransactionOptions<P, I>,
+  ): Promise<Result<NativeCookTransactionResult<P>, AssetStageError>> {
+    const candidate = await this.runDraft<P, I>(options.key, options.input);
+    if (!candidate.ok) {
+      return options.previous === undefined
+        ? candidate
+        : ok(recovered(options.key, options.previous));
+    }
+    const invalidReason = options.validate?.(candidate.value);
+    if (invalidReason !== undefined) {
+      return options.previous === undefined
+        ? transactionFailure(options.key, invalidReason)
+        : ok(recovered(options.key, options.previous));
+    }
+    const generation = (options.previous?.generation ?? 0) + 1;
+    try {
+      await options.publish?.(candidate.value, generation);
+    } catch {
+      return options.previous === undefined
+        ? transactionFailure(options.key, 'atomic producer publication failed')
+        : ok(recovered(options.key, options.previous));
+    }
+    return ok({
+      draft: candidate.value,
+      generation,
+      status: 'committed',
+      lastKnownGood: candidate.value,
+      candidateGeneration: generation,
+      lastKnownGoodGeneration: generation,
+    });
+  }
 }