@forgeax/engine-import 0.1.2

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@forgeax/engine-import",
+  "version": "0.1.2",
+  "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",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-geometry": "0.1.2",
+    "@forgeax/engine-pack": "0.1.2",
+    "@forgeax/engine-scene": "0.1.2",
+    "@forgeax/engine-types": "0.1.2",
+    "@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,190 @@
+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 { 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'");
+  });
+});

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);
+  });
+});

package/src/__tests__/import-local-artifacts.test.ts

@@ -0,0 +1,100 @@
+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 MESH_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+const TEXTURE_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45d';
+
+const meta: RunImportMeta = {
+  importer: 'local-artifacts-fixture',
+  source: 'fixture.source',
+  subAssets: [
+    { guid: MESH_GUID, sourceIndex: 0, sourceKey: 'fixture:mesh', kind: 'mesh' },
+    { guid: TEXTURE_GUID, sourceIndex: 1, sourceKey: 'fixture:texture', kind: 'texture' },
+  ],
+};
+
+function registryFor(value: unknown): ImporterRegistry {
+  const registry = new ImporterRegistry();
+  registry.register({
+    key: meta.importer,
+    import: async (_ctx: ImportContext): Promise<ImportResult> =>
+      ({ ok: true, value }) as ImportResult,
+  });
+  return registry;
+}
+
+describe('asset-local ImportProduct contract', () => {
+  it('keeps artifact ownership on each asset and preserves same keys across assets', async () => {
+    const value = {
+      assets: [
+        {
+          guid: MESH_GUID,
+          kind: 'mesh',
+          payload: { kind: 'mesh', vertices: [] },
+          refs: [],
+          artifacts: {
+            body: {
+              mediaType: 'application/x-forgeax-mesh',
+              assetCodec: { name: 'mesh-binary', version: '4' },
+              bytes: new Uint8Array([1]),
+            },
+          },
+        },
+        {
+          guid: TEXTURE_GUID,
+          kind: 'texture',
+          payload: { kind: 'texture', width: 1, height: 1 },
+          refs: [],
+          artifacts: {
+            body: {
+              mediaType: 'image/ktx2',
+              assetCodec: { name: 'basis', profile: 'uastc' },
+              bytes: new Uint8Array([2]),
+            },
+          },
+        },
+      ],
+      sourceDependencies: ['fixture.source'],
+    };
+
+    const result = await runImport(meta, registryFor(value), {
+      readSource: async () => ({ ok: true as const, value: new Uint8Array([0]) }),
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && 'product' in result.value) {
+      expect(result.value).not.toHaveProperty('bins');
+      expect(result.value.product).not.toHaveProperty('artifacts');
+      expect(result.value.pack.assets[0]?.artifacts).toHaveProperty('body');
+      expect(result.value.pack.assets[1]?.artifacts).toHaveProperty('body');
+    }
+  });
+
+  it('rejects a package-global artifact list instead of accepting an ownerless body', async () => {
+    const firstSubAsset = meta.subAssets[0];
+    if (firstSubAsset === undefined) throw new Error('fixture must declare a sub-asset');
+    const result = await runImport(
+      { ...meta, subAssets: [firstSubAsset] },
+      registryFor({
+        assets: [
+          {
+            guid: MESH_GUID,
+            kind: 'mesh',
+            payload: { kind: 'mesh', vertices: [] },
+            refs: [],
+          },
+        ],
+        artifacts: [
+          { path: 'mesh.bin', mimeType: 'application/octet-stream', bytes: new Uint8Array([1]) },
+        ],
+        sourceDependencies: ['fixture.source'],
+      }),
+      { readSource: async () => ({ ok: true as const, value: new Uint8Array([0]) }) },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('import-internal-error');
+  });
+});