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

package/src/__tests__/meta-schema-optional.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { validateMeta } from '../schema-compiled.js';
+import { SCRIPTABLE_PACK_ASSET_KINDS } from '../scriptable-pack.js';
+
+describe('meta.schema.json source optional (w8 / AC-4)', () => {
+  const minimalMeta = {
+    schemaVersion: '1.0.0',
+    kind: 'external-asset-package',
+    importer: 'image',
+    importSettings: {},
+    subAssets: [{ guid: '00000000-0000-4000-8000-000000000001', sourceIndex: 0, kind: 'texture' }],
+  };
+
+  it('meta without source key passes ajv validation (AC-4)', () => {
+    const valid = validateMeta(minimalMeta);
+    expect(valid).toBe(true);
+  });
+
+  it('meta with explicit source passes ajv validation (AC-1 back-compat)', () => {
+    const metaWithSource = { ...minimalMeta, source: 'foo.png' };
+    const valid = validateMeta(metaWithSource);
+    expect(valid).toBe(true);
+  });
+
+  it('meta missing required field importer fails validation', () => {
+    const { importer: _, ...withoutImporter } = minimalMeta;
+    const valid = validateMeta(withoutImporter);
+    expect(valid).toBe(false);
+  });
+
+  it('ajv reinstantiation idempotent — same validator returns same result', () => {
+    const valid1 = validateMeta(minimalMeta);
+    const valid2 = validateMeta(minimalMeta);
+    expect(valid1).toBe(valid2);
+  });
+});
+
+describe('meta.schema.json subAssets[].kind open-string (w6 / D-1 scheme A)', () => {
+  const metaWithSubKind = (kind: string) => ({
+    schemaVersion: '1.0.0',
+    kind: 'external-asset-package',
+    importer: 'image',
+    importSettings: {},
+    subAssets: [{ guid: '00000000-0000-4000-8000-000000000001', sourceIndex: 0, kind }],
+  });
+
+  // (a) Host custom kind passes validation — RED against current closed enum,
+  //     GREEN after schema enum is dropped to open string with minLength: 1.
+  //     When this test is red it proves the enum wall exists; when it turns
+  //     green it proves D-1 scheme A is effective.
+  it('(a) host custom kind passes validation (red→green)', () => {
+    const valid = validateMeta(metaWithSubKind('reel-game-blob'));
+    expect(valid).toBe(true);
+  });
+
+  // (b) Zero-regression: all 12 known kind values from the prior closed enum
+  //     still pass validation.  'image' is included here because the schema
+  //     layer does NOT decommission it — the fold layer (M4) handles that.
+  const knownKinds = [
+    'mesh',
+    'material',
+    'scene',
+    'texture',
+    'image',
+    'cube-texture',
+    'material-shader',
+    'skeleton',
+    'skin',
+    'animation-clip',
+    'audio',
+    'font',
+  ];
+
+  for (const kind of knownKinds) {
+    it(`(b) known kind '${kind}' passes validation (zero-regression)`, () => {
+      const valid = validateMeta(metaWithSubKind(kind));
+      expect(valid).toBe(true);
+    });
+  }
+
+  for (const kind of SCRIPTABLE_PACK_ASSET_KINDS) {
+    it(`published durable kind '${kind}' remains valid in open Meta schema`, () => {
+      expect(validateMeta(metaWithSubKind(kind))).toBe(true);
+    });
+  }
+
+  // (c) Empty string rejected by minLength: 1 (schema layer gate).
+  it('(c) empty-string kind fails validation (minLength: 1)', () => {
+    const valid = validateMeta(metaWithSubKind(''));
+    expect(valid).toBe(false);
+  });
+
+  // (d) subAssets[].kind field still exists in the schema and is typed as
+  //     string (AC-06 + OOS-2: field not deleted, only enum removed).
+  it('(d) subAssets[].kind field is string-typed and required', () => {
+    // Verify kind field is required — missing it fails.
+    const withoutKind = {
+      schemaVersion: '1.0.0',
+      kind: 'external-asset-package',
+      importer: 'image',
+      importSettings: {},
+      subAssets: [{ guid: '00000000-0000-4000-8000-000000000001', sourceIndex: 0 }],
+    };
+    expect(validateMeta(withoutKind)).toBe(false);
+
+    // Verify kind with non-string value (number) fails type check.
+    const numberKind = {
+      schemaVersion: '1.0.0',
+      kind: 'external-asset-package',
+      importer: 'image',
+      importSettings: {},
+      subAssets: [{ guid: '00000000-0000-4000-8000-000000000001', sourceIndex: 0, kind: 42 }],
+    };
+    expect(validateMeta(numberKind)).toBe(false);
+  });
+});

package/src/__tests__/meta-source-overrides.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { validateProducerContract } from '../producer-contract.js';
+import { validateMeta } from '../schema-compiled.js';
+
+const baseMeta = () => ({
+  schemaVersion: '1.0.0',
+  kind: 'external-asset-package',
+  importer: 'fixture',
+  importSettings: {},
+  subAssets: [
+    {
+      guid: '11111111-1111-4111-8111-111111111111',
+      sourceIndex: 0,
+      sourceKey: 'mesh/main',
+      kind: 'mesh',
+    },
+  ],
+});
+
+describe('Meta sourceOverrides', () => {
+  it('accepts a legal optional override without narrowing its payload', () => {
+    const meta = {
+      ...baseMeta(),
+      sourceOverrides: { 'mesh/main': { lod: 2, customProducerField: true } },
+    };
+    expect(validateMeta(meta)).toBe(true);
+    expect(validateProducerContract(meta)).toMatchObject({ ok: true });
+  });
+
+  it('rejects unknown or duplicate source keys before publication', () => {
+    const unknown = {
+      ...baseMeta(),
+      sourceOverrides: { 'mesh/other': { lod: 1 } },
+    };
+    const unknownResult = validateProducerContract(unknown);
+    expect(unknownResult).toMatchObject({
+      ok: false,
+      error: {
+        code: 'unknown-source-key',
+        authority: 'pack',
+      },
+    });
+
+    const duplicate = {
+      ...baseMeta(),
+      subAssets: [
+        ...baseMeta().subAssets,
+        {
+          guid: '22222222-2222-4222-8222-222222222222',
+          sourceIndex: 1,
+          sourceKey: 'mesh/main',
+          kind: 'mesh',
+        },
+      ],
+      sourceOverrides: { 'mesh/main': { lod: 1 } },
+    };
+    expect(validateProducerContract(duplicate)).toMatchObject({
+      ok: false,
+      error: { code: 'duplicate-source-key' },
+    });
+  });
+
+  it('keeps omitted and empty overrides equivalent to legacy Meta', () => {
+    const legacy = baseMeta();
+    const empty = { ...legacy, sourceOverrides: {} };
+    expect(validateMeta(legacy)).toBe(true);
+    expect(validateMeta(empty)).toBe(true);
+    expect(validateProducerContract(legacy)).toMatchObject({ ok: true });
+    expect(validateProducerContract(empty)).toMatchObject({ ok: true });
+  });
+});

package/src/__tests__/native-cooker-registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { NativeCookerRegistry } from '../native-cooker-registry.js';
+
+describe('NativeCookerRegistry artifact boundary', () => {
+  it('keeps native artifact bytes available before converting to CookProduct descriptors', async () => {
+    const bytes = new TextEncoder().encode('{"program":true}');
+    const registry = new NativeCookerRegistry();
+    registry.register({
+      key: 'test-effect',
+      cook: () => ({
+        guid: '019e9c00-0000-7000-8000-000000000000',
+        payload: { kind: 'test-effect' },
+        refs: ['019e9c00-0000-7000-8000-000000000001'],
+        artifacts: {
+          'test-effect/program.json': { mediaType: 'application/json', bytes },
+        },
+        inputFingerprint: 'sha256:test-input',
+      }),
+    });
+
+    const draft = await registry.runDraft('test-effect', {});
+    expect(draft.ok).toBe(true);
+    if (!draft.ok) throw new Error(draft.error.hint);
+    expect(draft.value.artifacts['test-effect/program.json']?.bytes).toEqual(bytes);
+
+    const product = await registry.run('test-effect', {});
+    expect(product.ok).toBe(true);
+    if (!product.ok) throw new Error(product.error.hint);
+    expect(product.value.artifacts['test-effect/program.json']).toMatchObject({
+      path: 'test-effect/program.json',
+      mediaType: 'application/json',
+      byteLength: bytes.byteLength,
+    });
+  });
+
+  it('discovers a typed producer input before cooking and preserves the typed output contract', async () => {
+    const registry = new NativeCookerRegistry();
+    registry.register({
+      key: 'typed-effect',
+      discover: (input) => {
+        if (typeof input !== 'object' || input === null || !('source' in input)) {
+          throw new Error('source is required');
+        }
+        return { source: String(input.source), revision: 3 };
+      },
+      cook: (input: { readonly source: string; readonly revision: number }) => ({
+        guid: '019e9c00-0000-7000-8000-000000000010',
+        payload: { source: input.source, revision: input.revision },
+        refs: [],
+        artifacts: {
+          'typed-effect/program.json': {
+            mediaType: 'application/json',
+            bytes: new TextEncoder().encode(JSON.stringify(input)),
+          },
+        },
+        inputFingerprint: `sha256:${input.source}`,
+      }),
+    });
+
+    const result = await registry.runDraft('typed-effect', { source: 'module.wgsl' });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.payload).toEqual({ source: 'module.wgsl', revision: 3 });
+  });
+});

package/src/__tests__/offline-evidence-artifact-verification-owner.test-d.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import type {
+  ArtifactDescriptor,
+  ArtifactVerificationStatus,
+  AssetEvidenceArtifact,
+  AssetEvidencePackageInput,
+} from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { OfflineArtifactInput, OfflinePackageInput } from '../evidence/offline-evidence.js';
+import type { buildOfflineAssetEvidence } from '../index.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+const projectionSource = readFileSync(
+  new URL('../evidence/offline-evidence.ts', import.meta.url),
+  'utf8',
+);
+
+type SharedOptionalVerification = AssetEvidencePackageInput['artifacts'][string]['verification'];
+type PublicOfflineArtifact = NonNullable<
+  Parameters<typeof buildOfflineAssetEvidence>[0]['package']
+>['artifacts'][string];
+
+describe('offline artifact verification owner', () => {
+  it('derives the optional offline projection from the shared status owner', () => {
+    expectTypeOf<ArtifactVerificationStatus>().toEqualTypeOf<'notChecked' | 'passed' | 'failed'>();
+    expectTypeOf<OfflineArtifactInput['verification']>().toEqualTypeOf<
+      ArtifactVerificationStatus | undefined
+    >();
+    expectTypeOf<
+      OfflineArtifactInput['verification']
+    >().toEqualTypeOf<SharedOptionalVerification>();
+    expectTypeOf<
+      AssetEvidenceArtifact['verification']
+    >().toEqualTypeOf<ArtifactVerificationStatus>();
+    expectTypeOf<PublicOfflineArtifact['verification']>().toEqualTypeOf<
+      ArtifactVerificationStatus | undefined
+    >();
+    expectTypeOf<'unknown'>().not.toExtend<ArtifactVerificationStatus>();
+  });
+
+  it('keeps artifact verification optional at the offline input boundary', () => {
+    const descriptor = {
+      path: 'artifacts/data.bin',
+      mediaType: 'application/octet-stream',
+    } satisfies ArtifactDescriptor;
+    const input = {
+      guid,
+      artifacts: { data: descriptor },
+    } satisfies OfflinePackageInput;
+    const publicInput = {
+      guid,
+      package: input,
+    } satisfies Parameters<typeof buildOfflineAssetEvidence>[0];
+    void publicInput;
+  });
+
+  it('keeps the source projection tied to the shared type instead of a second ledger', () => {
+    expect(projectionSource).toContain('ArtifactVerificationStatus');
+    expect(projectionSource).toContain('readonly verification?: ArtifactVerificationStatus;');
+    expect(projectionSource).not.toContain(
+      "readonly verification?: 'notChecked' | 'passed' | 'failed';",
+    );
+  });
+});

package/src/__tests__/offline-evidence.integration.test.ts

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+import { buildOfflineAssetEvidence } from '../evidence/offline-evidence.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('offline evidence adapter', () => {
+  it('joins source inventory, catalog, receipt, and package verification', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', inputFingerprint: 'fp-1' },
+      locator: { packageUrl: '/assets/config.pack.json', cookReceiptUrl: '/receipts/config.json' },
+      receipt: {
+        guid,
+        origin: 'sourceMeta',
+        status: 'succeeded',
+        inputFingerprint: 'fp-1',
+        outputDigest: 'digest-1',
+      },
+      package: {
+        guid,
+        digest: 'digest-1',
+        artifacts: {
+          data: {
+            path: 'artifacts/data.bin',
+            mediaType: 'application/octet-stream',
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.packageUrl).toBe('/assets/config.pack.json');
+    expect(result.value.cook.freshness).toBe('current');
+    expect(result.value.package?.status).toBe('passed');
+  });
+
+  it('keeps runtime and WS outside the offline adapter boundary', () => {
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('assets.load');
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('WebSocket');
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('AssetRegistry');
+  });
+
+  it('keeps the static Pack boundary gate live for runtime package imports', async () => {
+    const gate = await readFile(
+      new URL('../../../../packages/pack/scripts/check-no-assets-load.mjs', import.meta.url),
+      'utf8',
+    );
+
+    expect(gate).toContain('@forgeax/engine-(assets-runtime|runtime)');
+    expect(gate).toContain(String.raw`engine\\.assets\\.load(`);
+    expect(gate).not.toContain("registry.load('");
+  });
+
+  it('projects a verified cook product without requiring DDC storage', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      product: {
+        guid,
+        payload: { kind: 'direct-asset' },
+        refs: [],
+        artifacts: {
+          data: { path: 'assets/data.bin', mediaType: 'application/octet-stream' },
+        },
+        digest: 'digest-direct',
+        receipt: {
+          guid,
+          origin: 'authoredPack',
+          status: 'succeeded',
+          inputFingerprint: 'direct-input',
+          outputDigest: 'digest-direct',
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.cook.freshness).toBe('notApplicable');
+    expect(result.value.package?.status).toBe('passed');
+  });
+
+  it('keeps a failed artifact in the offline evidence boundary', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', inputFingerprint: 'fp-failed' },
+      locator: { packageUrl: '/assets/failed.pack.json' },
+      package: {
+        guid,
+        digest: 'digest-failed',
+        artifacts: {
+          data: {
+            path: 'assets/data.bin',
+            mediaType: 'application/octet-stream',
+            verification: 'failed',
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.package?.status).toBe('failed');
+    expect(result.value.cook.freshness).toBe('unknown');
+  });
+});

package/src/__tests__/owner-chain.integration.test.ts

@@ -0,0 +1,78 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { finalizePackageProduct } from '../package-finalizer.js';
+import { scanInventory } from '../scanner.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+
+describe('Pack owner chain', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('scans source identity and finalizes the terminal package product', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-owner-chain-'));
+    roots.push(root);
+    await writeFile(
+      join(root, 'hero.pack.json'),
+      JSON.stringify({
+        schemaVersion: '2.0.0',
+        kind: 'internal-text-package',
+        assets: [
+          {
+            guid: GUID,
+            kind: 'texture',
+            sourceKey: 'hero/albedo',
+            sourceIndex: 0,
+            payload: {},
+            refs: [],
+            artifacts: {},
+          },
+        ],
+      }),
+    );
+    const inventory = await scanInventory([root]);
+    expect(inventory.ok).toBe(true);
+    if (!inventory.ok) return;
+    const writes: string[] = [];
+    const result = await finalizePackageProduct(
+      {
+        assets: [
+          {
+            guid: GUID,
+            kind: 'texture',
+            payload: { kind: 'texture' },
+            refs: [],
+            artifacts: {
+              body: { mediaType: 'application/octet-stream', bytes: new Uint8Array([1]) },
+            },
+          },
+        ],
+        receipts: [
+          {
+            guid: GUID,
+            origin: 'sourceMeta',
+            status: 'succeeded',
+            inputFingerprint: inventory.value.inventory[0]?.sourceRevision ?? 'missing',
+          },
+        ],
+        diagnostics: [],
+        sourceRevision: inventory.value.inventory[0]?.sourceRevision ?? 'missing',
+      },
+      {
+        base: '/assets',
+        packagePath: 'hero.pack.json',
+        artifactPath: (guid, key) => `${guid}/${key}.bin`,
+        sink: (path) => {
+          writes.push(path);
+        },
+      },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(writes).toEqual([`${GUID}/body.bin`, 'hero.pack.json']);
+  });
+});

package/src/__tests__/pack-v2-fixture-migration.test.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { parsePackV2, validateCookedMaterialRecord } from '../index.js';
+
+const root = resolve(import.meta.dirname, '../../../../');
+
+const fixtures = [
+  {
+    path: 'apps/hello/cube/assets/cube-mesh.pack.json',
+    assets: [{ guid: 'cbe42beb-8975-5096-b3a1-3dda4cb4c077', refs: [] }],
+  },
+  {
+    path: 'apps/hello/room/assets/room.pack.json',
+    assets: [
+      {
+        guid: '019e2808-d3ba-735f-811f-ae7bbb465392',
+        refs: [
+          'cbe42beb-8975-5096-b3a1-3dda4cb4c077',
+          'f6af7007-158f-4d92-9e47-93bf2f213e1f',
+          '008e4f75-e7a3-4715-b05b-b93a9ec12074',
+        ],
+      },
+    ],
+  },
+  {
+    path: 'apps/hello/scene-nesting/assets/outer-scene.pack.json',
+    assets: [
+      {
+        guid: 'd07a7b8e-9c12-4f6b-a8e1-3d4f5a6b7c8d',
+        refs: ['f47ac10b-58cc-4372-a567-0e02b2c3d479', '008e4f75-e7a3-4715-b05b-b93a9ec12074'],
+      },
+    ],
+  },
+];
+
+describe('Pack v2 fixture migration', () => {
+  it('preserves logical GUID and refs while requiring local artifact maps', () => {
+    for (const fixture of fixtures) {
+      const parsed = parsePackV2(JSON.parse(readFileSync(resolve(root, fixture.path), 'utf8')));
+      expect(parsed.ok, fixture.path).toBe(true);
+      if (!parsed.ok) continue;
+      expect(
+        parsed.value.assets.map(({ guid, refs, artifacts }) => ({ guid, refs, artifacts })),
+      ).toEqual(
+        fixture.assets.map((asset) => ({ guid: asset.guid, refs: asset.refs, artifacts: {} })),
+      );
+    }
+  });
+
+  it('rejects the empty legacy envelope and package-global payload arms', () => {
+    expect(
+      parsePackV2({ schemaVersion: '1.0.0', kind: 'internal-text-package', assets: [] }).ok,
+    ).toBe(false);
+    expect(
+      parsePackV2({
+        schemaVersion: '2.0.0',
+        kind: 'internal-text-package',
+        assets: [],
+        artifacts: [{ path: 'shared.bin', bytes: 'base64' }],
+      }).ok,
+    ).toBe(false);
+  });
+
+  it('rejects retired material cook records instead of retaining a cross-generation reader', () => {
+    const retiredSchema = ['material-cook', '2'].join('/');
+    expect(
+      validateCookedMaterialRecord({
+        schemaVersion: retiredSchema,
+        guid: 'mat-v2',
+        resolved: { passes: [], parameters: [], values: {} },
+        refs: { parent: [], textures: [], samplers: [], modules: [] },
+        artifact: { mediaType: 'text/wgsl', path: 'shader.wgsl', digest: 'sha256:a', bytes: [] },
+        receipt: {
+          schemaVersion: retiredSchema,
+          sourceClosure: [],
+          profile: 'webgpu/v1',
+          compilerVersion: 'compiler/1',
+          inputDigest: 'sha256:i',
+          outputDigest: 'sha256:a',
+          layoutIdentity: 'sha256:l',
+          derivedInterface: { layoutIdentity: 'sha256:l' },
+        },
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'material-cook-record-invalid' } });
+  });
+});