@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/src/native-cooker-registry.ts

@@ -0,0 +1,235 @@
+import { createHash } from 'node:crypto';
+import type {
+  ArtifactDescriptor,
+  AssetCodec,
+  AssetStageError,
+  CookProduct,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface NativeCookArtifact {
+  readonly mediaType: string;
+  readonly assetCodec?: AssetCodec;
+  readonly bytes: Uint8Array;
+}
+
+export interface NativeCookDraft<P = unknown> {
+  readonly guid: string;
+  readonly payload: P;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, NativeCookArtifact>>;
+  readonly inputFingerprint: string;
+}
+
+export interface NativeCooker<P = unknown, I = unknown> {
+  readonly key: string;
+  readonly discover?: (input: unknown) => I | Promise<I>;
+  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);
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nested]) => [key, canonicalize(nested)]),
+  );
+}
+
+function digestDraft<P>(draft: NativeCookDraft<P>): string {
+  const bytes = JSON.stringify(
+    canonicalize({
+      guid: draft.guid,
+      payload: draft.payload,
+      refs: draft.refs,
+      artifacts: draft.artifacts,
+    }),
+  );
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+type NativeCookErrorDetail = Extract<
+  AssetStageError['detail'],
+  { readonly guid: string; readonly producer: string }
+>;
+
+function failure(key: string, detail: NativeCookErrorDetail): Result<never, AssetStageError> {
+  return err({
+    stage: 'native-cook',
+    code: 'native-cook-failed',
+    expected: 'a registered native cooker to produce a complete draft',
+    hint: 'register the cooker or repair its draft, then rerun recovery',
+    detail,
+    recovery: { action: `rerun native cooker ${key}`, retryable: true },
+  });
+}
+
+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>();
+
+  register(cooker: NativeCooker): void {
+    if (typeof cooker.key !== 'string' || cooker.key.length === 0) {
+      throw new TypeError('NativeCookerRegistry.register: key must be a non-empty string');
+    }
+    if (typeof cooker.cook !== 'function') {
+      throw new TypeError(`NativeCookerRegistry.register: cooker ${cooker.key} must expose cook`);
+    }
+    this.cookers.set(cooker.key, cooker);
+  }
+
+  get(key: string): NativeCooker | undefined {
+    return this.cookers.get(key);
+  }
+
+  registeredCookers(): readonly string[] {
+    return [...this.cookers.keys()];
+  }
+
+  async runDraft<P = unknown, I = unknown>(
+    key: string,
+    input: I,
+  ): Promise<Result<NativeCookDraft<P>, AssetStageError>> {
+    const cooker = this.cookers.get(key) as NativeCooker<P, I> | undefined;
+    if (cooker === undefined) {
+      return failure(key, { guid: 'unknown', producer: key });
+    }
+    let draft: NativeCookDraft<P>;
+    try {
+      const typedInput = cooker.discover === undefined ? input : await cooker.discover(input);
+      draft = await cooker.cook(typedInput);
+    } catch (error) {
+      return failure(key, { guid: 'unknown', producer: String(error) });
+    }
+    if (
+      draft.guid.length === 0 ||
+      draft.inputFingerprint.length === 0 ||
+      !Array.isArray(draft.refs) ||
+      typeof draft.payload !== 'object' ||
+      draft.payload === null ||
+      typeof draft.artifacts !== 'object' ||
+      draft.artifacts === null ||
+      Object.entries(draft.artifacts).some(
+        ([, artifact]) =>
+          artifact === null ||
+          typeof artifact !== 'object' ||
+          typeof artifact.mediaType !== 'string' ||
+          artifact.mediaType.length === 0 ||
+          !(artifact.bytes instanceof Uint8Array),
+      )
+    ) {
+      return failure(key, { guid: draft.guid || 'unknown', producer: key });
+    }
+    return ok(draft);
+  }
+
+  async run<P = unknown, I = unknown>(
+    key: string,
+    input: I,
+  ): Promise<Result<CookProduct<P>, AssetStageError>> {
+    const draftResult = await this.runDraft<P, I>(key, input);
+    if (!draftResult.ok) return draftResult;
+    const draft = draftResult.value;
+    const digest = digestDraft(draft);
+    const artifacts: Record<string, ArtifactDescriptor> = {};
+    for (const [path, artifact] of Object.entries(draft.artifacts)) {
+      artifacts[path] = {
+        path,
+        mediaType: artifact.mediaType,
+        ...(artifact.assetCodec === undefined ? {} : { assetCodec: artifact.assetCodec }),
+        byteLength: artifact.bytes.byteLength,
+      };
+    }
+    const receipt = {
+      guid: draft.guid,
+      origin: 'authoredPack' as const,
+      status: 'succeeded' as const,
+      inputFingerprint: draft.inputFingerprint,
+      outputDigest: digest,
+    };
+    const product: CookProduct<P> = {
+      guid: draft.guid,
+      payload: draft.payload,
+      refs: draft.refs,
+      artifacts,
+      digest,
+      receipt,
+    };
+    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,
+    });
+  }
+}

package/src/native-cooker.ts

@@ -0,0 +1,2 @@
+/** Node/build-time native cooker registry. The browser-safe pack root excludes this seam. */
+export * from './native-cooker-registry.js';

package/src/package-finalizer.ts

@@ -0,0 +1,394 @@
+import { createHash } from 'node:crypto';
+import type { AssetCodec, AssetRelation, CookReceipt } from '@forgeax/engine-types';
+
+export interface PackageArtifactBody {
+  readonly mediaType: string;
+  readonly assetCodec?: AssetCodec;
+  readonly bytes: Uint8Array;
+}
+
+export interface PackageProductAsset {
+  readonly guid: string;
+  readonly kind: string;
+  readonly name?: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, PackageArtifactBody>>;
+}
+
+export interface PackageProduct {
+  readonly assets: readonly PackageProductAsset[];
+  readonly receipts: readonly CookReceipt[];
+  readonly diagnostics: readonly unknown[];
+  readonly sourceRevision: string;
+  readonly sourceKey?: string;
+}
+
+/** Minimal authored Pack v1/v2 shape consumed by the file transport seam. */
+export interface AuthoredPackAssetInput {
+  readonly guid: string;
+  readonly kind: string;
+  readonly name?: string;
+  readonly execution?: 'direct' | 'cooked';
+  readonly sourceKey?: string;
+  readonly sourceIndex?: number;
+  readonly relations?: readonly AssetRelation[];
+  readonly payload: Record<string, unknown>;
+  readonly refs?: readonly string[];
+  readonly artifacts?: Readonly<Record<string, unknown>>;
+}
+
+export interface AuthoredPackInput {
+  readonly schemaVersion?: string;
+  readonly assets?: readonly AuthoredPackAssetInput[];
+}
+
+export interface PackageDocumentArtifact {
+  readonly path: string;
+  readonly mediaType: string;
+  readonly assetCodec?: AssetCodec;
+  readonly byteLength: number;
+  readonly integrity: { readonly algorithm: 'sha256'; readonly digest: string };
+}
+
+export interface PackageDocumentAsset {
+  readonly guid: string;
+  readonly kind: string;
+  readonly name?: string;
+  readonly payload: Record<string, unknown>;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, PackageDocumentArtifact>>;
+}
+
+export interface PackageDocument {
+  readonly schemaVersion: '2.0.0';
+  readonly kind: 'internal-text-package';
+  readonly assets: readonly PackageDocumentAsset[];
+}
+
+/** Upgrade the legacy authored Pack envelope at the Pack schema boundary. */
+export function upgradeLegacyAuthoredPack(pack: AuthoredPackInput): AuthoredPackInput {
+  if (pack.schemaVersion !== '1.0.0' || pack.assets === undefined) return pack;
+  return {
+    ...pack,
+    schemaVersion: '2.0.0',
+    assets: pack.assets.map((asset) => {
+      const fontRefs =
+        asset.kind === 'font'
+          ? [asset.payload.atlasGuid, asset.payload.samplerGuid].filter(
+              (guid): guid is string => typeof guid === 'string',
+            )
+          : [];
+      return {
+        ...asset,
+        refs: asset.refs ?? fontRefs,
+        artifacts: asset.artifacts ?? {},
+      };
+    }),
+  };
+}
+
+export interface PackageFinalizePolicy {
+  readonly base: string;
+  readonly packagePath: string;
+  readonly artifactPath: (guid: string, localKey: string) => string;
+  readonly sink?: (path: string, bytes: Uint8Array) => void | Promise<void>;
+}
+
+export interface FinalizedPackageProduct {
+  readonly pack: PackageDocument;
+  readonly packageUrl: string;
+  readonly digest: string;
+  readonly receipts: readonly CookReceipt[];
+  readonly diagnostics: readonly unknown[];
+  readonly sourceRevision: string;
+  readonly sourceKey?: string;
+}
+
+interface PackageTransportSource {
+  readonly assets: readonly PackageProduct['assets'][number][];
+  readonly receipts?: readonly CookReceipt[];
+  readonly diagnostics?: readonly unknown[];
+  readonly sourceKey?: string;
+}
+
+export interface PackageFinalizerError {
+  readonly code:
+    | 'duplicate-guid'
+    | 'missing-source-revision'
+    | 'missing-receipt'
+    | 'invalid-artifact';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly guid?: string; readonly key?: string };
+}
+
+export type PackageFinalizeResult =
+  | { readonly ok: true; readonly value: FinalizedPackageProduct }
+  | { readonly ok: false; readonly error: PackageFinalizerError };
+
+function failure(
+  code: PackageFinalizerError['code'],
+  expected: string,
+  hint: string,
+  detail: PackageFinalizerError['detail'],
+): PackageFinalizeResult {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+
+function sorted(value: unknown): unknown {
+  if (value instanceof Uint8Array) return Buffer.from(value).toString('base64');
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value !== null && typeof value === 'object') {
+    const output: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      output[key] = sorted((value as Record<string, unknown>)[key]);
+    }
+    return output;
+  }
+  return value;
+}
+
+function packageUrl(base: string, packagePath: string): string {
+  const prefix = base === '/' ? '' : `/${base.replace(/^\/+|\/+$/g, '')}`;
+  return `${prefix}/${packagePath.replace(/^\/+/, '')}`;
+}
+
+function safePath(path: string): boolean {
+  const normalized = path.replaceAll('\\', '/');
+  return (
+    normalized.length > 0 &&
+    !normalized.startsWith('/') &&
+    !/^[A-Za-z]:\//.test(normalized) &&
+    !normalized.split('/').includes('..')
+  );
+}
+
+function digest(assets: readonly PackageProductAsset[]): string {
+  const pack = { schemaVersion: '2.0.0', kind: 'internal-text-package', assets } as const;
+  const hash = createHash('sha256').update(
+    JSON.stringify(
+      sorted({
+        ...pack,
+        assets: pack.assets.map((asset) => ({
+          ...asset,
+          artifacts: Object.fromEntries(
+            Object.entries(asset.artifacts).map(([key, artifact]) => [
+              key,
+              {
+                mediaType: artifact.mediaType,
+                ...(artifact.assetCodec === undefined ? {} : { assetCodec: artifact.assetCodec }),
+                byteLength: artifact.bytes.byteLength,
+              },
+            ]),
+          ),
+        })),
+      }),
+    ),
+  );
+  for (const [key, artifact] of assets
+    .flatMap((asset) =>
+      Object.entries(asset.artifacts).map(
+        ([localKey, body]) => [`${asset.guid}/${localKey}`, body] as const,
+      ),
+    )
+    .sort(([left], [right]) => left.localeCompare(right))) {
+    hash.update(key).update(artifact.bytes);
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+function packageDocument(
+  assets: readonly PackageProductAsset[],
+  artifactPath: (guid: string, localKey: string) => string,
+): PackageDocument {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: assets.map((asset) => ({
+      guid: asset.guid,
+      kind: asset.kind,
+      ...(asset.name === undefined ? {} : { name: asset.name }),
+      payload: asset.payload,
+      refs: asset.refs,
+      artifacts: Object.fromEntries(
+        Object.entries(asset.artifacts).map(([key, artifact]) => [
+          key,
+          {
+            path: artifactPath(asset.guid, key),
+            mediaType: artifact.mediaType,
+            ...(artifact.assetCodec === undefined ? {} : { assetCodec: artifact.assetCodec }),
+            contentEncoding: 'identity' as const,
+            byteLength: artifact.bytes.byteLength,
+            integrity: {
+              algorithm: 'sha256' as const,
+              digest: `sha256:${createHash('sha256').update(artifact.bytes).digest('hex')}`,
+            },
+          },
+        ]),
+      ),
+    })),
+  };
+}
+
+function transportArtifacts(
+  assets: readonly PackageProductAsset[],
+  artifactPath: PackageFinalizePolicy['artifactPath'],
+) {
+  return assets.flatMap((asset) =>
+    Object.entries(asset.artifacts).flatMap(([localKey, artifact]) => [
+      {
+        guid: asset.guid,
+        localKey,
+        path: artifactPath(asset.guid, localKey),
+        mediaType: artifact.mediaType,
+        ...(artifact.assetCodec === undefined ? {} : { assetCodec: artifact.assetCodec }),
+        bytes: artifact.bytes,
+      },
+    ]),
+  );
+}
+
+/** Finalize a complete producer product without owning producer-specific policy. */
+export async function finalizePackageProduct(
+  product: PackageProduct,
+  policy: PackageFinalizePolicy,
+): Promise<PackageFinalizeResult> {
+  if (product.sourceRevision.trim().length === 0) {
+    return failure(
+      'missing-source-revision',
+      'a non-empty source revision',
+      'rebuild the inventory and provide the producer source revision',
+      {},
+    );
+  }
+  const seen = new Set<string>();
+  for (const asset of product.assets) {
+    const guid = asset.guid.toLowerCase();
+    if (seen.has(guid)) {
+      return failure(
+        'duplicate-guid',
+        'one terminal product row per GUID',
+        'repair the inventory or producer output before finalization',
+        { guid },
+      );
+    }
+    seen.add(guid);
+    for (const [key, artifact] of Object.entries(asset.artifacts)) {
+      if (!safePath(key) || !(artifact.bytes instanceof Uint8Array)) {
+        return failure(
+          'invalid-artifact',
+          'asset-local artifact keys and byte bodies',
+          'repair the producer artifact before finalization',
+          { guid, key },
+        );
+      }
+    }
+  }
+  for (const guid of seen) {
+    if (!product.receipts.some((receipt) => receipt.guid.toLowerCase() === guid)) {
+      return failure(
+        'missing-receipt',
+        'one receipt for every terminal product GUID',
+        'preserve the producer receipt when handing the product to engine-pack',
+        { guid },
+      );
+    }
+  }
+  const assets = [...product.assets].sort((left, right) => left.guid.localeCompare(right.guid));
+  const document = packageDocument(assets, policy.artifactPath);
+  const packageBytes = new TextEncoder().encode(JSON.stringify(sorted(document)));
+  if (policy.sink !== undefined) {
+    for (const asset of assets) {
+      for (const [key, artifact] of Object.entries(asset.artifacts)) {
+        const path = policy.artifactPath(asset.guid, key);
+        if (!safePath(path)) {
+          return failure(
+            'invalid-artifact',
+            'package-relative artifact output paths',
+            'repair the finalizer artifact path policy',
+            { guid: asset.guid, key },
+          );
+        }
+        await policy.sink(path, artifact.bytes);
+      }
+    }
+    if (!safePath(policy.packagePath)) {
+      return failure(
+        'invalid-artifact',
+        'a package-relative package path',
+        'repair the finalizer package path policy',
+        { key: policy.packagePath },
+      );
+    }
+    await policy.sink(policy.packagePath, packageBytes);
+  }
+  return {
+    ok: true,
+    value: {
+      pack: document,
+      packageUrl: packageUrl(policy.base, policy.packagePath),
+      digest: digest(product.assets),
+      receipts: product.receipts,
+      diagnostics: product.diagnostics,
+      sourceRevision: product.sourceRevision,
+      ...(product.sourceKey === undefined ? {} : { sourceKey: product.sourceKey }),
+    },
+  };
+}
+
+/** Finalize a product-shaped source with the deterministic transport revision. */
+export async function finalizePackageTransportSource(
+  input: PackageTransportSource,
+  policy: PackageFinalizePolicy,
+) {
+  const sourceRevision = packageTransportRevision(input);
+  const product: PackageProduct = {
+    assets: input.assets,
+    receipts:
+      input.receipts ??
+      input.assets.map((asset) => ({
+        guid: asset.guid,
+        origin: 'sourceMeta' as const,
+        status: 'succeeded' as const,
+        inputFingerprint: sourceRevision,
+      })),
+    diagnostics: input.diagnostics ?? [],
+    sourceRevision,
+    ...(input.sourceKey === undefined ? {} : { sourceKey: input.sourceKey }),
+  };
+  const finalized = await finalizePackageProduct(product, policy);
+  if (!finalized.ok) throw finalized.error;
+  return {
+    pack: finalized.value.pack,
+    packageUrl: finalized.value.packageUrl,
+    artifacts: transportArtifacts(product.assets, policy.artifactPath),
+    digest: finalized.value.digest,
+    sourceRevision,
+    semantic: JSON.stringify(sorted(finalized.value.pack)),
+  };
+}
+
+function revisionStable(value: unknown): unknown {
+  if (value instanceof Uint8Array) {
+    return {
+      byteLength: value.byteLength,
+      digest: createHash('sha256').update(value).digest('hex'),
+    };
+  }
+  if (Array.isArray(value)) return value.map(revisionStable);
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, revisionStable(item)]),
+    );
+  }
+  return value;
+}
+
+export function packageTransportRevision(value: unknown): string {
+  return createHash('sha256')
+    .update(JSON.stringify(revisionStable(value)))
+    .digest('hex');
+}