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

package/src/__tests__/load-asset-config.test.ts

@@ -0,0 +1,121 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { loadAssetConfig } from '../config.js';
+
+describe('loadAssetConfig SSOT (w8 / AC-13)', () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'forgeax-test-loadAssetConfig-'));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('missing package.json returns default roots + empty paths', () => {
+    const result = loadAssetConfig(join(tmpDir, 'nonexistent'));
+    expect(result.roots).toEqual([join(join(tmpDir, 'nonexistent'), 'assets')]);
+    expect(result.paths).toEqual({});
+  });
+
+  it('package.json without forgeax.assets returns default', async () => {
+    const dir = join(tmpDir, 'no-forgeax');
+    await mkdir(dir);
+    await writeFile(join(dir, 'package.json'), JSON.stringify({ name: 'test' }));
+    const result = loadAssetConfig(dir);
+    expect(result.roots).toEqual([join(dir, 'assets')]);
+    expect(result.paths).toEqual({});
+  });
+
+  it('reads forgeax.assets.roots from package.json', async () => {
+    const dir = join(tmpDir, 'with-roots');
+    await mkdir(dir);
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        forgeax: { assets: { roots: ['my-assets', 'more'] } },
+      }),
+    );
+    const result = loadAssetConfig(dir);
+    expect(result.roots).toEqual([join(dir, 'my-assets'), join(dir, 'more')]);
+    expect(result.paths).toEqual({});
+  });
+
+  it('empty forgeax.assets.roots array falls back to default', async () => {
+    const dir = join(tmpDir, 'empty-roots');
+    await mkdir(dir);
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        forgeax: { assets: { roots: [] } },
+      }),
+    );
+    const result = loadAssetConfig(dir);
+    expect(result.roots).toEqual([join(dir, 'assets')]);
+  });
+
+  it('reads forgeax.assets.paths with cwd-relative resolution', async () => {
+    const dir = join(tmpDir, 'with-paths');
+    await mkdir(dir);
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        forgeax: {
+          assets: {
+            paths: {
+              shared: 'lib/assets',
+              vendor: '../vendor-assets',
+            },
+          },
+        },
+      }),
+    );
+    const result = loadAssetConfig(dir);
+    expect(result.paths).toEqual({
+      shared: join(dir, 'lib/assets'),
+      vendor: join(dir, '../vendor-assets'),
+    });
+  });
+
+  it('paths absent defaults to empty object', async () => {
+    const dir = join(tmpDir, 'roots-only');
+    await mkdir(dir);
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        forgeax: { assets: { roots: ['a'] } },
+      }),
+    );
+    const result = loadAssetConfig(dir);
+    expect(result.paths).toEqual({});
+  });
+
+  it('non-string path values are skipped', async () => {
+    const dir = join(tmpDir, 'bad-paths');
+    await mkdir(dir);
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        forgeax: {
+          assets: {
+            paths: {
+              good: 'lib/a',
+              badNum: 42,
+              badBool: true,
+            },
+          },
+        },
+      }),
+    );
+    const result = loadAssetConfig(dir);
+    expect(result.paths).toEqual({ good: join(dir, 'lib/a') });
+  });
+});

package/src/__tests__/material-cook-dependencies.unit.test.ts

@@ -0,0 +1,112 @@
+import type { AssetGuid } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { collectMaterialCookRefs } from '../evidence/material-cook.js';
+import { NativeCookerRegistry } from '../native-cooker-registry.js';
+import { createRuntimePackPublication } from '../runtime-publication.js';
+
+describe('material cook dependency closure', () => {
+  it('collects parent, texture, sampler, and module references', () => {
+    expect(
+      collectMaterialCookRefs({
+        parent: 'mat-parent' as unknown as AssetGuid,
+        passes: [{ name: 'forward', program: { module: 'module/pbr' } }],
+        values: {
+          baseColor: {
+            texture: 'texture/albedo' as unknown as AssetGuid,
+            sampler: 'sampler/linear' as unknown as AssetGuid,
+          },
+        },
+      }),
+    ).toEqual({
+      parent: ['mat-parent'],
+      textures: ['texture/albedo'],
+      samplers: ['sampler/linear'],
+      modules: ['module/pbr'],
+    });
+  });
+
+  it('collects string shorthands only from declared texture parameters', () => {
+    expect(
+      collectMaterialCookRefs({
+        parameters: [
+          { name: 'surface', type: 'texture' },
+          { name: 'label', type: 'f32' },
+        ],
+        values: { surface: 'texture/albedo', label: 'not-a-texture-ref' },
+      }),
+    ).toEqual({ parent: [], textures: ['texture/albedo'], samplers: [], modules: [] });
+  });
+
+  it('treats a string value as a texture shorthand when parameters are omitted', () => {
+    expect(
+      collectMaterialCookRefs({
+        values: { baseColorTexture: 'texture/albedo' },
+      }),
+    ).toEqual({ parent: [], textures: ['texture/albedo'], samplers: [], modules: [] });
+  });
+
+  it('keeps the last known good candidate when a generation fails before publication', async () => {
+    const registry = new NativeCookerRegistry();
+    let fail = false;
+    registry.register({
+      key: 'material',
+      cook: () => {
+        if (fail) throw new Error('candidate rejected');
+        return {
+          guid: 'material-child',
+          payload: { kind: 'material' },
+          refs: ['texture/albedo'],
+          artifacts: {
+            'material-child/shader.wgsl': {
+              mediaType: 'text/wgsl',
+              bytes: new TextEncoder().encode('shader'),
+            },
+          },
+          inputFingerprint: 'sha256:material-candidate',
+        };
+      },
+    });
+
+    const committed = await registry.runTransaction({ key: 'material', input: {} });
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) throw new Error(committed.error.hint);
+    fail = true;
+    const recovered = await registry.runTransaction({
+      key: 'material',
+      input: {},
+      previous: committed.value,
+    });
+
+    expect(recovered).toMatchObject({
+      ok: true,
+      value: {
+        status: 'recovered',
+        generation: 1,
+        candidateGeneration: 2,
+        lastKnownGoodGeneration: 1,
+        lastKnownGood: committed.value.draft,
+      },
+    });
+  });
+
+  it('keeps runtime publication identity independent from source-path diagnostics', () => {
+    const input = {
+      pack: {
+        assets: [{ guid: 'material-child', kind: 'material', payload: { roughness: 0.5 } }],
+      },
+      scopeId: 'project',
+      sourceRevision: 'rev-1',
+      packageUrl: '/packs/materials.json',
+    };
+    const first = createRuntimePackPublication({ ...input, sourcePath: '/src/materials.json' });
+    const moved = createRuntimePackPublication({ ...input, sourcePath: '/moved/materials.json' });
+
+    expect(moved.pack.digest).toBe(first.pack.digest);
+    expect(moved.publication.digest).toBe(first.publication.digest);
+    expect(moved.publication.outputSetDigest).toBe(first.publication.outputSetDigest);
+    expect(moved.publication.receipt.inputFingerprint).toBe(
+      first.publication.receipt.inputFingerprint,
+    );
+    expect(moved.publication.sourcePath).toBe('/moved/materials.json');
+  });
+});

package/src/__tests__/material-cook-receipt.unit.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type MaterialCookReceipt,
+  serializeMaterialCookReceipt,
+  validateMaterialCookReceipt,
+} from '../evidence/material-cook.js';
+
+const layoutIdentity = 'sha256:layout-identity';
+const artifactDigest = 'sha256:output';
+
+function receipt(overrides: Record<string, unknown> = {}): MaterialCookReceipt {
+  return {
+    schemaVersion: 'material-cook/3',
+    sourceClosure: ['b.wgsl', 'a.material.json'],
+    profile: 'webgpu/v1',
+    compilerVersion: 'compiler/1',
+    identity: {
+      materialContractDigest: 'sha256:material-contract',
+      sourceRevision: 'sha256:source-revision',
+      sourceClosureDigest: 'sha256:source-closure',
+      layoutIdentity,
+      programIdentity: 'sha256:program',
+      pipelineIdentity: 'sha256:pipeline',
+      materialPublicationIdentity: 'sha256:publication',
+      cookIdentity: 'sha256:input',
+      compilerFingerprint: 'sha256:compiler',
+      wasm: {
+        sourceContentKey: 'sha256:wasm-source',
+        artifactSha256: 'sha256:wasm-artifact',
+        glueSha256: 'sha256:wasm-glue',
+      },
+      artifactDigest,
+      valueGeneration: 1,
+      dependencyGeneration: 1,
+      cookGeneration: 1,
+    },
+    derivedInterface: { layoutIdentity },
+    ...overrides,
+  } as unknown as MaterialCookReceipt;
+}
+
+describe('material cook receipt', () => {
+  it('requires the v3 identity and provenance tuple', () => {
+    const v3 = {
+      schemaVersion: 'material-cook/3',
+      sourceClosure: ['materials/mat.material.json', 'shaders/pbr.wgsl'],
+      profile: 'webgpu/v1',
+      compilerVersion: 'compiler/1',
+      identity: {
+        materialContractDigest: 'sha256:material-contract',
+        sourceRevision: 'sha256:source-revision',
+        sourceClosureDigest: 'sha256:source-closure',
+        layoutIdentity,
+        programIdentity: 'sha256:program',
+        pipelineIdentity: 'sha256:pipeline',
+        materialPublicationIdentity: 'sha256:publication',
+        cookIdentity: 'sha256:cook',
+        compilerFingerprint: 'sha256:compiler',
+        wasm: {
+          sourceContentKey: 'sha256:wasm-source',
+          artifactSha256: 'sha256:wasm-artifact',
+          glueSha256: 'sha256:wasm-glue',
+        },
+        artifactDigest,
+        valueGeneration: 3,
+        dependencyGeneration: 2,
+        cookGeneration: 7,
+      },
+      derivedInterface: { layoutIdentity },
+    };
+    expect(validateMaterialCookReceipt(v3)).toMatchObject({ ok: true, value: v3 });
+    expect(validateMaterialCookReceipt(receipt())).toMatchObject({ ok: true });
+    expect(
+      validateMaterialCookReceipt({
+        ...v3,
+        identity: { ...v3.identity, compilerFingerprint: undefined },
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'material-cook-record-invalid' },
+    });
+  });
+
+  it('serializes a material-cook/3 receipt stably for equivalent cooks', () => {
+    const first = serializeMaterialCookReceipt(receipt());
+    const second = serializeMaterialCookReceipt(
+      receipt({ sourceClosure: ['a.material.json', 'b.wgsl'] }),
+    );
+    expect(first).toBe(second);
+    expect(JSON.parse(first)).toMatchObject({
+      schemaVersion: 'material-cook/3',
+      identity: { layoutIdentity },
+      derivedInterface: { layoutIdentity },
+    });
+  });
+
+  it('accepts the expected identity and rejects schema or interface mutations', () => {
+    const expected = { layoutIdentity, artifactDigest, inputDigest: 'sha256:input' };
+    expect(validateMaterialCookReceipt(receipt(), expected)).toEqual({
+      ok: true,
+      value: receipt(),
+    });
+    expect(
+      validateMaterialCookReceipt(
+        receipt({ identity: { ...receipt().identity, layoutIdentity: 'sha256:changed-layout' } }),
+        expected,
+      ),
+    ).toMatchObject({ ok: false, error: { code: 'material-cook-record-invalid' } });
+    expect(
+      validateMaterialCookReceipt(
+        receipt({ derivedInterface: { layoutIdentity: 'sha256:changed-layout' } }),
+        expected,
+      ),
+    ).toMatchObject({ ok: false, error: { code: 'material-cook-record-invalid' } });
+  });
+
+  it('rejects missing, stale, mismatched, and material-cook/1 receipts fail-fast', () => {
+    const expected = { layoutIdentity, artifactDigest, inputDigest: 'sha256:input' };
+    for (const value of [
+      receipt({ identity: { ...receipt().identity, layoutIdentity: undefined } }),
+      receipt({ identity: { ...receipt().identity, artifactDigest: 'sha256:stale-artifact' } }),
+      receipt({ identity: { ...receipt().identity, cookIdentity: 'sha256:stale-input' } }),
+      {
+        sourceClosure: [],
+        profile: 'webgpu/v1',
+        compilerVersion: 'compiler/1',
+        identity: receipt().identity,
+      },
+    ]) {
+      expect(validateMaterialCookReceipt(value as MaterialCookReceipt, expected)).toMatchObject({
+        ok: false,
+        error: { code: 'material-cook-record-invalid' },
+      });
+    }
+  });
+
+  it('records the coordinator-owned publication generation', () => {
+    const generationReceipt = {
+      sourceClosure: ['materials/mat-root.material.json'],
+      profile: 'webgpu/v1',
+      compilerVersion: 'compiler/1',
+      identity: { ...receipt().identity, cookGeneration: 11 },
+    };
+    expect(generationReceipt).toMatchObject({
+      identity: { cookGeneration: 11 },
+    });
+  });
+});

package/src/__tests__/material-cook-schema.unit.test.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  type CookedMaterialRecord,
+  createMaterialArtifactDigest,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  validateCookedMaterialRecord,
+} from '../evidence/material-cook.js';
+
+const record: CookedMaterialRecord = {
+  schemaVersion: 'material-cook/3',
+  guid: 'mat-root',
+  authored: {
+    kind: 'material',
+    passes: [{ name: 'forward', program: { module: 'core/pbr' } }],
+    parameters: [{ name: 'roughness', type: 'f32' }],
+    values: { roughness: 0.5 },
+  },
+  resolved: {
+    passes: [{ name: 'forward', program: { module: 'core/pbr' } }],
+    parameters: [{ name: 'roughness', type: 'f32' }],
+    values: { roughness: 0.5 },
+  },
+  refs: { parent: [], textures: [], samplers: [], modules: ['core/pbr'] },
+  artifact: {
+    mediaType: 'text/wgsl',
+    path: 'materials/mat-root/forward.wgsl',
+    digest: 'sha256:artifact',
+    bytes: new TextEncoder().encode('shader'),
+  },
+  receipt: {
+    schemaVersion: 'material-cook/3',
+    sourceClosure: ['materials/mat-root.material.json'],
+    profile: 'webgpu/v1',
+    compilerVersion: 'compiler/1',
+    identity: {
+      materialContractDigest: 'sha256:material-contract',
+      sourceRevision: 'sha256:source-revision',
+      sourceClosureDigest: 'sha256:source-closure',
+      layoutIdentity: 'sha256:layout',
+      programIdentity: 'sha256:program',
+      pipelineIdentity: 'sha256:pipeline',
+      materialPublicationIdentity: 'sha256:publication',
+      cookIdentity: 'sha256:input',
+      compilerFingerprint: 'sha256:compiler',
+      wasm: {
+        sourceContentKey: 'sha256:wasm-source',
+        artifactSha256: 'sha256:wasm-artifact',
+        glueSha256: 'sha256:wasm-glue',
+      },
+      artifactDigest: 'sha256:artifact',
+      valueGeneration: 1,
+      dependencyGeneration: 1,
+      cookGeneration: 1,
+    },
+    derivedInterface: { layoutIdentity: 'sha256:layout' },
+  },
+};
+
+describe('cooked material schema', () => {
+  it('requires material-cook/3 identity and derived interface association', () => {
+    const schema = JSON.parse(
+      readFileSync(
+        fileURLToPath(new URL('../schema/material-cook.schema.json', import.meta.url)),
+        'utf8',
+      ),
+    ) as {
+      properties: Record<
+        string,
+        { const?: string; required?: string[]; properties?: Record<string, unknown> }
+      >;
+      required: string[];
+    };
+    expect(schema.properties.schemaVersion?.const).toBe('material-cook/3');
+    expect(schema.properties.receipt?.required).toEqual(
+      expect.arrayContaining(['identity', 'derivedInterface']),
+    );
+    expect(schema.properties.receipt?.properties?.derivedInterface).toBeDefined();
+  });
+
+  it('defines the v3 identity, provenance, and generation contract', () => {
+    const schema = JSON.parse(
+      readFileSync(
+        fileURLToPath(new URL('../schema/material-cook.schema.json', import.meta.url)),
+        'utf8',
+      ),
+    ) as {
+      properties: Record<
+        string,
+        { const?: string; required?: string[]; properties?: Record<string, unknown> }
+      >;
+    };
+    expect(schema.properties.schemaVersion?.const).toBe('material-cook/3');
+    expect(schema.properties.receipt?.properties?.identity).toMatchObject({
+      type: 'object',
+      required: expect.arrayContaining([
+        'materialContractDigest',
+        'sourceRevision',
+        'sourceClosureDigest',
+        'layoutIdentity',
+        'programIdentity',
+        'pipelineIdentity',
+        'materialPublicationIdentity',
+        'cookIdentity',
+        'compilerFingerprint',
+        'wasm',
+        'artifactDigest',
+        'valueGeneration',
+        'dependencyGeneration',
+        'cookGeneration',
+      ]),
+    });
+    expect(schema.properties.receipt?.required).toEqual(
+      expect.arrayContaining(['identity', 'derivedInterface']),
+    );
+  });
+
+  it('serializes a stable cooked DTO and derives an artifact digest', () => {
+    const first = serializeCookedMaterialRecord(record);
+    const second = serializeCookedMaterialRecord({ ...record });
+
+    expect(first).toBe(second);
+    expect(createMaterialArtifactDigest(record.artifact.bytes)).toBe(
+      'sha256:e137e75a5e0e7a623ca39de480667a55b43e0eedec58767634ebaef07c33383a',
+    );
+    expect(validateCookedMaterialRecord(JSON.parse(first))).toEqual({ ok: true, value: record });
+  });
+
+  it('projects cooked data without exposing an authored GUID entry', () => {
+    const projection = projectCookedMaterialRecord(record);
+
+    expect(projection.resolved.values).toEqual({ roughness: 0.5 });
+    expect(projection.artifact.digest).toBe('sha256:artifact');
+    expect(projection).not.toHaveProperty('guid');
+    expect(projection).not.toHaveProperty('authored');
+  });
+
+  it('rejects missing fields and unsupported schema versions', () => {
+    expect(validateCookedMaterialRecord({ ...record, refs: undefined })).toMatchObject({
+      ok: false,
+      error: { code: 'material-cook-record-invalid' },
+    });
+    expect(
+      validateCookedMaterialRecord({ ...record, schemaVersion: 'material-cook/1' }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'material-cook-record-invalid' },
+    });
+  });
+});

package/src/__tests__/mesh-bin-consumer-surface.unit.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const encoderSource = readFileSync(
+  new URL('../../../import/src/mesh-bin.ts', import.meta.url),
+  'utf8',
+);
+const decoderSource = readFileSync(
+  new URL('../../../geometry/src/assets/mesh-binary.ts', import.meta.url),
+  'utf8',
+);
+
+describe('mesh-bin consumer owner surface', () => {
+  it('routes both production halves through Pack-owned facts', () => {
+    expect(encoderSource).toContain("from '@forgeax/engine-pack/mesh-bin-contract'");
+    expect(decoderSource).toContain("from '@forgeax/engine-pack'");
+    for (const source of [encoderSource, decoderSource]) {
+      expect(source).toContain('MESH_BIN_HEADER_V4_BYTES');
+      expect(source).not.toContain('const HEADER_V2_BYTES = 28');
+    }
+  });
+});

package/src/__tests__/mesh-bin-contract.unit.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decodeMeshBinHeader,
+  MESH_BIN_HEADER_V4_BYTES,
+  MESH_BIN_VERSION,
+} from '../mesh-bin-contract.js';
+
+describe('mesh-bin v4 wire contract', () => {
+  it('owns a fixed v4 header and rejects legacy versions at the contract boundary', () => {
+    expect(MESH_BIN_VERSION).toBe(4);
+    expect(MESH_BIN_HEADER_V4_BYTES).toBeGreaterThan(28);
+    expect(decodeMeshBinHeader(new Uint8Array(MESH_BIN_HEADER_V4_BYTES))).toMatchObject({
+      ok: false,
+      error: { code: 'mesh-bin-version-unsupported' },
+    });
+  });
+
+  it('reports truncated headers as structured failures with recovery context', () => {
+    const result = decodeMeshBinHeader(new Uint8Array(MESH_BIN_HEADER_V4_BYTES - 1), 'mesh/source');
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'mesh-bin-header-truncated',
+        subject: 'mesh-bin',
+        sourceKey: 'mesh/source',
+        expected: expect.any(String),
+        actual: expect.any(String),
+        recovery: expect.stringContaining('re-cook'),
+      },
+    });
+  });
+});