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

package/dist/source-package-publication.d.ts

@@ -0,0 +1,63 @@
+import { type DdcGenerationEntryCandidate, DdcGenerationSession, type DdcHead } from '@forgeax/engine-ddc';
+import { type CatalogEntry, type ResourceRevision } from '@forgeax/engine-types';
+import { type SourcePackageError, type SourcePackageErrorContext } from './source-package-errors.js';
+interface StagedSourcePackageDdc extends DdcGenerationEntryCandidate {
+    readonly root: string;
+    readonly session: DdcGenerationSession;
+    readonly context: SourcePackageErrorContext;
+}
+export interface ImportPublicationInput {
+    readonly root: string;
+    readonly guid: string;
+    readonly desiredKey: string;
+    readonly pack: unknown;
+    readonly previousCatalog: readonly CatalogEntry[];
+    readonly nextCatalog: readonly CatalogEntry[];
+    readonly publishedGuids: readonly string[];
+    readonly transport?: {
+        readonly path: string;
+        readonly body: string;
+    };
+}
+export interface ImportPublicationError {
+    readonly code: SourcePackageError['code'];
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: string;
+    readonly diagnostic: SourcePackageError;
+}
+export type ImportPublicationResult = {
+    readonly ok: true;
+    readonly key: string;
+    readonly head: DdcHead;
+    readonly catalog: readonly CatalogEntry[];
+    readonly revision: ResourceRevision;
+    readonly transportPersisted: boolean;
+} | {
+    readonly ok: false;
+    readonly error: ImportPublicationError;
+    readonly head: DdcHead;
+};
+export interface StagedImportPublication {
+    readonly input: ImportPublicationInput;
+    readonly ddc: StagedSourcePackageDdc;
+    readonly key: string;
+    readonly head: DdcHead;
+    readonly catalog: readonly CatalogEntry[];
+    readonly revision: ResourceRevision;
+}
+export type StagedImportPublicationResult = {
+    readonly ok: true;
+    readonly candidate: StagedImportPublication;
+} | {
+    readonly ok: false;
+    readonly error: ImportPublicationError;
+    readonly head: DdcHead;
+};
+export declare function publishImportPublication(input: ImportPublicationInput): Promise<ImportPublicationResult>;
+export declare function stageImportPublication(input: ImportPublicationInput): Promise<StagedImportPublicationResult>;
+export declare function commitImportPublication(candidate: StagedImportPublication): Promise<ImportPublicationResult>;
+export declare function discardImportPublication(candidate: StagedImportPublication): Promise<void>;
+export declare function restoreImportPublication(candidate: StagedImportPublication): Promise<void>;
+export {};
+//# sourceMappingURL=source-package-publication.d.ts.map

package/dist/source-package-publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-package-publication.d.ts","sourceRoot":"","sources":["../src/source-package-publication.ts"],"names":[],"mappings":"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"}

package/dist/source-package.d.ts

@@ -0,0 +1,60 @@
+import type { ImportedAsset, ImportProduct, ImportProductFinalizeOptions, ImportProductFinalizeResult, Result } from '@forgeax/engine-types';
+import type { ImportRunnerFs, RunImportMeta } from './import-runner.js';
+import type { ImporterRegistry } from './importer-registry.js';
+export type ProducerReadiness = 'before-consume' | 'on-demand';
+export interface ProducerReadinessError {
+    readonly code: 'producer-readiness-invalid';
+    readonly expected: "'before-consume' or 'on-demand'";
+    readonly hint: 'set producerReadiness to before-consume or on-demand';
+    readonly detail: {
+        readonly value: unknown;
+    };
+}
+export type ProducerReadinessResult = {
+    readonly ok: true;
+    readonly value: ProducerReadiness;
+} | {
+    readonly ok: false;
+    readonly error: ProducerReadinessError;
+};
+export declare function parseProducerReadiness(value: unknown): ProducerReadinessResult;
+export interface SourcePackageProducerInput {
+    readonly meta: RunImportMeta;
+    readonly registry: ImporterRegistry;
+    readonly fs: ImportRunnerFs;
+}
+export interface SourcePackageClosureDetail {
+    readonly stage: 'closure';
+    readonly declaredGuids: readonly string[];
+    readonly producedGuids: readonly string[];
+    readonly missingGuids: readonly string[];
+    readonly unexpectedGuids: readonly string[];
+    readonly duplicateGuids: readonly string[];
+}
+export interface SourcePackageClosureError {
+    readonly code: 'source-package-guid-closure-mismatch';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SourcePackageClosureDetail;
+}
+export interface SourcePackageProduct {
+    readonly anchorGuid: string;
+    readonly declaredGuids: readonly string[];
+    readonly product: ImportProduct<unknown>;
+}
+type SourcePackageFinalizeError = Extract<ImportProductFinalizeResult, {
+    readonly ok: false;
+}>['error'];
+/** Apply an importer-owned transport finalizer without teaching the adapter its kind. */
+export declare function finalizeSourcePackage(product: ImportProduct<unknown>, finalizer: ((product: ImportProduct<unknown>, options: ImportProductFinalizeOptions) => ImportProductFinalizeResult) | undefined, artifactUrl: ImportProductFinalizeOptions['artifactUrl']): Result<ImportProduct<unknown>, SourcePackageFinalizeError>;
+export type SourcePackageProducerResult = {
+    readonly ok: true;
+    readonly value: SourcePackageProduct;
+} | {
+    readonly ok: false;
+    readonly error: SourcePackageClosureError;
+};
+export declare function produceSourcePackage(input: SourcePackageProducerInput): Promise<SourcePackageProducerResult>;
+export declare function sourcePackageAssetsByGuid(source: SourcePackageProduct): ReadonlyMap<string, ImportedAsset<unknown>>;
+export {};
+//# sourceMappingURL=source-package.d.ts.map

package/dist/source-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-package.d.ts","sourceRoot":"","sources":["../src/source-package.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@forgeax/engine-import",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Build-time asset import runner + ImporterRegistry (the build-time half of the import/load split). Dispatches a *.meta.json sidecar by its top-level `importer` string key to a registered Importer, enforces the GUID import-stable iron law, and writes the DDC (.pack.json / .bin). Build-time only — never bundled into the player runtime (AC-06). Mirrors the LoaderRegistry (runtime) + Console Registry register/get/fail-fast injection shape.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.mjs",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./mesh-bin": {
+      "types": "./dist/mesh-bin.d.ts",
+      "import": "./dist/mesh-bin.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ddc": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-geometry": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@noble/hashes": "^2.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": false,
+        "reason": "build-time-only package (import runner + ImporterRegistry); never enters the player runtime bundle (AC-06), so no shipped-size budget applies"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "build-time package; no runtime canvas or frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "import runner is one-shot build-time work (not a hot path); no perf-critical bench in this package"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no standalone binary gate; package-level gates declared in CI yaml directly"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/decode-image-owner.test-d.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import type { ImportContext, ImportRunnerFs as PublicImportRunnerFs } from '@forgeax/engine-import';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ImportRunnerFs } from '../import-runner.js';
+
+type DecodeImage = ImportContext['decodeImage'];
+type RunnerDecodeImage = NonNullable<ImportRunnerFs['decodeImage']>;
+type DecodeImageMime = Parameters<DecodeImage>[1];
+type DecodeImageResult = Awaited<ReturnType<DecodeImage>>;
+
+const readSource: ImportRunnerFs['readSource'] = async () => ({
+  ok: true,
+  value: new Uint8Array(),
+});
+
+declare const hostDecodeImage: DecodeImage;
+
+const runnerSource = readFileSync(new URL('../import-runner.ts', import.meta.url), 'utf8');
+
+function assertOptionalHostInjection(): void {
+  const withoutHostDecoder = {
+    readSource,
+  } satisfies PublicImportRunnerFs;
+
+  const withHostDecoder = {
+    readSource,
+    decodeImage: hostDecodeImage,
+  } satisfies PublicImportRunnerFs;
+
+  void withoutHostDecoder;
+  void withHostDecoder;
+}
+
+void assertOptionalHostInjection;
+
+describe('ImportRunnerFs decodeImage owner', () => {
+  it('derives the public callback and result envelope from ImportContext', () => {
+    expectTypeOf<RunnerDecodeImage>().toEqualTypeOf<DecodeImage>();
+    expectTypeOf<PublicImportRunnerFs>().toEqualTypeOf<ImportRunnerFs>();
+    expectTypeOf<Awaited<ReturnType<RunnerDecodeImage>>>().toEqualTypeOf<DecodeImageResult>();
+  });
+
+  it('preserves the PNG/JPEG/TGA input contract and optional host injection', () => {
+    expectTypeOf<DecodeImageMime>().toEqualTypeOf<'image/png' | 'image/jpeg' | 'image/x-tga'>();
+    expectTypeOf<ImportRunnerFs['decodeImage']>().toEqualTypeOf<DecodeImage | undefined>();
+  });
+
+  it('keeps both runner views derived from the authority', () => {
+    expect(runnerSource).toContain("decodeImage?: ImportContext['decodeImage'];");
+    expect(runnerSource).toContain("const decodeImage: ImportContext['decodeImage'] =");
+    expect(runnerSource).not.toContain("mimeType: 'image/png' | 'image/jpeg'");
+  });
+});

package/src/__tests__/import-contract-migration.test.ts

@@ -0,0 +1,223 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Asset, AssetRelation, ImportedAsset, ImportResult } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createImportProduct } from '../import-product.js';
+import { type RunImportMeta, runImport } from '../import-runner.js';
+import { ImporterRegistry } from '../importer-registry.js';
+
+const GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+const DEPENDENCY_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45d';
+const MESH = {
+  kind: 'mesh',
+  vertices: new Float32Array(),
+  indices: new Uint16Array(),
+  attributes: {},
+} as unknown as Asset;
+
+const relation: AssetRelation = {
+  from: { type: 'asset', id: GUID },
+  to: { type: 'asset', id: DEPENDENCY_GUID },
+  type: 'references',
+  provenance: { provider: 'fixture-producer', version: '2.0.0' },
+};
+
+function registry(): ImporterRegistry {
+  const registry = new ImporterRegistry();
+  registry.register({
+    key: 'fixture',
+    import: async (): Promise<ImportResult> => ({
+      ok: true,
+      value: {
+        assets: [
+          {
+            guid: GUID,
+            kind: 'mesh',
+            payload: MESH,
+            refs: [{ guid: DEPENDENCY_GUID }],
+            artifacts: {},
+          } satisfies ImportedAsset,
+        ],
+        sourceDependencies: [],
+      },
+    }),
+  });
+  return registry;
+}
+
+function readFs() {
+  return {
+    readSource: async () => ({ ok: true as const, value: new Uint8Array([1]) }),
+  };
+}
+
+function multiMeta(
+  overrides: readonly (Partial<RunImportMeta['subAssets'][number]> | undefined)[] = [],
+): RunImportMeta {
+  const entries = [
+    { guid: GUID, sourceKey: 'scene/main', sourceIndex: 0, kind: 'mesh' },
+    { guid: DEPENDENCY_GUID, sourceKey: 'scene/detail', sourceIndex: 1, kind: 'mesh' },
+  ];
+  return {
+    importer: 'fixture',
+    source: 'models/fixture.glb',
+    subAssets: entries.map((entry, index) => ({ ...entry, ...(overrides[index] ?? {}) })),
+  };
+}
+
+function meta(facts: Record<string, unknown> = {}): RunImportMeta {
+  return {
+    importer: 'fixture',
+    source: 'models/fixture.glb',
+    ...facts,
+    subAssets: [
+      {
+        guid: GUID,
+        sourceKey: 'scene/main',
+        sourceIndex: 0,
+        kind: 'mesh',
+        relations: [relation],
+      },
+    ],
+  } as unknown as RunImportMeta;
+}
+
+describe('import runner producer fact propagation', () => {
+  it('rejects sourceIndex-only declarations before reading source or invoking importer', async () => {
+    let reads = 0;
+    const keyedMeta = multiMeta();
+    const sourceIndexOnlyMeta: RunImportMeta = {
+      ...keyedMeta,
+      subAssets: keyedMeta.subAssets.map(
+        ({ sourceKey: _sourceKey, ...declaration }) => declaration,
+      ),
+    };
+    const result = await runImport(sourceIndexOnlyMeta, registry(), {
+      readSource: async () => {
+        reads += 1;
+        return { ok: true as const, value: new Uint8Array([1]) };
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('source-validation-failed');
+      expect(result.error.detail).toMatchObject({
+        diagnostics: expect.arrayContaining([
+          expect.objectContaining({ code: 'source-key-required' }),
+        ]),
+      });
+    }
+    expect(reads).toBe(0);
+  });
+
+  it('rejects duplicate, empty, and malformed sourceKey before Meta publication', async () => {
+    for (const override of [
+      { sourceKey: 'scene/main' },
+      { sourceKey: '   ' },
+      { sourceKey: 7 as unknown as string },
+    ]) {
+      const result = await runImport(multiMeta([undefined, override]), registry(), readFs());
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('source-validation-failed');
+    }
+  });
+
+  it('preserves complete producer facts on the DDC row matched by GUID', async () => {
+    const facts = {
+      packageId: 'package/fixture',
+      provenance: { provider: 'fixture-producer', version: '2.0.0', source: 'fixture.glb' },
+      revision: { digest: 'sha256:fixture', observedAt: 42, rootId: 'root-fixture' },
+      diagnostics: [
+        {
+          code: 'fixture-warning',
+          severity: 'warning',
+          hint: 'reimport the fixture when its source changes',
+        },
+      ],
+    };
+    const result = await runImport(meta(facts), registry(), readFs());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value) return;
+    expect(result.value.pack).toMatchObject(facts);
+    expect(result.value.pack.assets).toEqual([
+      expect.objectContaining({
+        guid: GUID,
+        sourceKey: 'scene/main',
+        sourceIndex: 0,
+        relations: [relation],
+      }),
+    ]);
+    expect(result.value.cookProducts).toEqual([
+      expect.objectContaining({
+        guid: GUID,
+        payload: MESH,
+        refs: [DEPENDENCY_GUID],
+        artifacts: {},
+        receipt: expect.objectContaining({
+          guid: GUID,
+          origin: 'sourceMeta',
+          status: 'succeeded',
+        }),
+      }),
+    ]);
+  });
+
+  it('keeps optional producer facts absent when the declaration has no evidence', async () => {
+    const result = await runImport(meta(), registry(), readFs());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value) return;
+    expect(result.value.pack).not.toHaveProperty('packageId');
+    expect(result.value.pack).not.toHaveProperty('provenance');
+    expect(result.value.pack).not.toHaveProperty('revision');
+    expect(result.value.pack).not.toHaveProperty('diagnostics');
+    expect(result.value.pack.assets[0]).toMatchObject({
+      guid: GUID,
+      sourceKey: 'scene/main',
+      sourceIndex: 0,
+      relations: [relation],
+    });
+  });
+
+  it('removes package-global artifact and kind-specific bin contracts from the runner', () => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', 'import-runner.ts'), 'utf8');
+    expect(source).not.toContain('RunImportOk.bins');
+    expect(source).not.toContain('readonly bins');
+    expect(source).not.toContain("a.kind === 'texture'");
+    expect(source).not.toContain("a.kind === 'mesh'");
+  });
+});
+
+describe('engine-import terminal product contract', () => {
+  it('projects refs, artifacts, receipts, diagnostics, and source identity together', () => {
+    const result = createImportProduct({
+      assets: [
+        {
+          guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+          kind: 'texture',
+          payload: { kind: 'texture', width: 1, height: 1 },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+      sourceDependencies: ['hero.png'],
+      refs: [],
+      artifacts: {},
+      receipts: [],
+      diagnostics: [],
+      sourceRevision: 'sha256:hero',
+      sourceKey: 'hero/albedo',
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.sourceRevision).toBe('sha256:hero');
+    expect(result.value.sourceKey).toBe('hero/albedo');
+    expect(result.value).toHaveProperty('refs');
+    expect(result.value).toHaveProperty('artifacts');
+    expect(result.value).toHaveProperty('receipts');
+    expect(result.value).toHaveProperty('diagnostics');
+  });
+});

package/src/__tests__/import-dependencies.test.ts

@@ -0,0 +1,65 @@
+import type { Asset, ImportContext, Importer, ImportResult } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { type RunImportMeta, runImport } from '../import-runner.js';
+import { ImporterRegistry } from '../importer-registry.js';
+
+const GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+const MESH = {
+  kind: 'mesh',
+  vertices: new Float32Array(),
+  indices: new Uint16Array(),
+  attributes: {},
+} as unknown as Asset;
+
+function meta(): RunImportMeta {
+  return {
+    importer: 'fixture',
+    source: 'ui/main.html',
+    subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'mesh' }],
+  };
+}
+
+describe('import runner dependency observation', () => {
+  it('records normalized source and sibling reads exactly once, including retries', async () => {
+    const reads: string[] = [];
+    const importer: Importer = {
+      key: 'fixture',
+      async import(ctx: ImportContext): Promise<ImportResult> {
+        await ctx.readSibling('./main.css');
+        const missing = await ctx.readSibling('icons/missing.svg');
+        expect(missing.ok).toBe(false);
+        await ctx.readSibling('icons/missing.svg');
+        return {
+          ok: true,
+          value: {
+            assets: [{ guid: GUID, kind: 'mesh', payload: MESH, refs: [], artifacts: {} }],
+            sourceDependencies: [],
+          },
+        };
+      },
+    };
+    const registry = new ImporterRegistry();
+    registry.register(importer);
+    const result = await runImport(meta(), registry, {
+      readSource: async (source) => {
+        reads.push(source);
+        if (source.endsWith('missing.svg')) return { ok: false, error: new Error('ENOENT') };
+        return { ok: true, value: new Uint8Array([1]) };
+      },
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok && 'product' in result.value) {
+      expect(result.value.product.sourceDependencies).toEqual([
+        'ui/main.html',
+        'ui/main.css',
+        'ui/icons/missing.svg',
+      ]);
+    }
+    expect(reads).toEqual([
+      'ui/main.html',
+      'ui/./main.css',
+      'ui/icons/missing.svg',
+      'ui/icons/missing.svg',
+    ]);
+  });
+});

package/src/__tests__/import-finalizer-digest-retry.test.ts

@@ -0,0 +1,113 @@
+import type { ImportContext, ImportResult } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { type RunImportMeta, runImport } from '../import-runner.js';
+import { ImporterRegistry } from '../importer-registry.js';
+
+const GUID = '019f0000-0000-7000-8000-000000000071';
+const SOURCE = 'assets/m71.fixture';
+
+const meta: RunImportMeta = {
+  importer: 'm71-fixture',
+  source: SOURCE,
+  subAssets: [{ guid: GUID, sourceIndex: 0, sourceKey: 'fixture:main', kind: 'reel-game-blob' }],
+  importSettings: { revision: 'm71' },
+};
+
+function createRegistry(): ImporterRegistry {
+  const registry = new ImporterRegistry();
+  registry.register({
+    key: meta.importer,
+    import: async (ctx: ImportContext): Promise<ImportResult<unknown>> => {
+      const source = await ctx.readSource();
+      if (!source.ok) throw new Error('fixture source was not readable');
+      return {
+        ok: true,
+        value: {
+          assets: [
+            {
+              guid: GUID,
+              kind: 'reel-game-blob',
+              payload: { kind: 'reel-game-blob', title: 'M71 digest fixture' },
+              refs: [],
+              artifacts: {
+                body: {
+                  mediaType: 'application/x-forgeax-m71',
+                  bytes: new Uint8Array([11, 71, 1, 9]),
+                },
+              },
+            },
+          ],
+          sourceDependencies: [],
+        },
+      };
+    },
+  });
+  return registry;
+}
+
+function createFs(reads: { count: number }) {
+  const sourceBytes = new Uint8Array([77, 55, 49, 0]);
+  return {
+    readSource: async (path: string) => {
+      reads.count += 1;
+      return path === SOURCE
+        ? { ok: true as const, value: sourceBytes }
+        : { ok: false as const, error: new Error(`unexpected source path ${path}`) };
+    },
+  };
+}
+
+describe('public import finalizer digest recovery', () => {
+  it('returns a structured finalization error and retries idempotently on the same registry', async () => {
+    const registry = createRegistry();
+    const reads = { count: 0 };
+    const fs = createFs(reads);
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) throw new Error('Web Crypto subtle is unavailable');
+    const originalDigest = subtle.digest;
+    const publishedDigests = new Set<string>();
+
+    subtle.digest = async () => {
+      throw new Error('M71 injected subtle.digest refusal');
+    };
+
+    let failed: Awaited<ReturnType<typeof runImport>>;
+    try {
+      failed = await runImport(meta, registry, fs);
+    } finally {
+      subtle.digest = originalDigest;
+    }
+
+    expect(failed.ok).toBe(false);
+    expect(failed).not.toHaveProperty('value');
+    if (!failed.ok) {
+      expect(failed.error.code).toBe('import-internal-error');
+      expect(failed.error.expected).toContain('finalization');
+      expect(failed.error.detail).toEqual({
+        reason: expect.stringMatching(/finalization.*digest.*M71 injected subtle\.digest refusal/),
+      });
+    }
+
+    const repaired = await runImport(meta, registry, fs);
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok || 'skipped' in repaired.value)
+      throw new Error('repair must publish a product');
+    expect(repaired.value.cookProducts).toHaveLength(1);
+    expect(repaired.value.pack.assets).toHaveLength(1);
+    const repairedDigest = repaired.value.cookProducts[0]?.digest;
+    if (repairedDigest === undefined) throw new Error('repair must produce a digest');
+    publishedDigests.add(repairedDigest);
+
+    const third = await runImport(meta, registry, fs);
+    expect(third.ok).toBe(true);
+    if (!third.ok || 'skipped' in third.value)
+      throw new Error('idempotent run must publish a product');
+    expect(third.value.cookProducts[0]?.digest).toBe(repairedDigest);
+    expect(third.value.pack).toEqual(repaired.value.pack);
+    publishedDigests.add(third.value.cookProducts[0]?.digest ?? '');
+
+    expect(publishedDigests.size).toBe(1);
+    expect(registry.registeredImporters()).toEqual([meta.importer]);
+    expect(reads.count).toBe(6);
+  });
+});