@forgeax/engine-pack 0.1.24 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-pack",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -131,7 +131,7 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine-types": "0.1.24",
+    "@forgeax/engine-types": "0.1.26",
     "@noble/hashes": "^2.2.0",
     "fast-glob": "^3.3.3",
     "typescript": "^5.8.3",

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

@@ -10,7 +10,7 @@ const artifactDigest = 'sha256:output';
 
 function receipt(overrides: Record<string, unknown> = {}): MaterialCookReceipt {
   return {
-    schemaVersion: 'material-cook/3',
+    schemaVersion: 'material-cook/4',
     sourceClosure: ['b.wgsl', 'a.material.json'],
     profile: 'webgpu/v1',
     compilerVersion: 'compiler/1',
@@ -40,9 +40,9 @@ function receipt(overrides: Record<string, unknown> = {}): MaterialCookReceipt {
 }
 
 describe('material cook receipt', () => {
-  it('requires the v3 identity and provenance tuple', () => {
-    const v3 = {
-      schemaVersion: 'material-cook/3',
+  it('requires the v4 identity and provenance tuple', () => {
+    const v4 = {
+      schemaVersion: 'material-cook/4',
       sourceClosure: ['materials/mat.material.json', 'shaders/pbr.wgsl'],
       profile: 'webgpu/v1',
       compilerVersion: 'compiler/1',
@@ -68,12 +68,12 @@ describe('material cook receipt', () => {
       },
       derivedInterface: { layoutIdentity },
     };
-    expect(validateMaterialCookReceipt(v3)).toMatchObject({ ok: true, value: v3 });
+    expect(validateMaterialCookReceipt(v4)).toMatchObject({ ok: true, value: v4 });
     expect(validateMaterialCookReceipt(receipt())).toMatchObject({ ok: true });
     expect(
       validateMaterialCookReceipt({
-        ...v3,
-        identity: { ...v3.identity, compilerFingerprint: undefined },
+        ...v4,
+        identity: { ...v4.identity, compilerFingerprint: undefined },
       }),
     ).toMatchObject({
       ok: false,
@@ -81,14 +81,14 @@ describe('material cook receipt', () => {
     });
   });
 
-  it('serializes a material-cook/3 receipt stably for equivalent cooks', () => {
+  it('serializes a material-cook/4 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',
+      schemaVersion: 'material-cook/4',
       identity: { layoutIdentity },
       derivedInterface: { layoutIdentity },
     });

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

@@ -5,13 +5,15 @@ import { describe, expect, it } from 'vitest';
 import {
   type CookedMaterialRecord,
   createMaterialArtifactDigest,
+  createMaterialProgramSetDigest,
+  type MaterialCookProgram,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   validateCookedMaterialRecord,
 } from '../evidence/material-cook.js';
 
 const record: CookedMaterialRecord = {
-  schemaVersion: 'material-cook/3',
+  schemaVersion: 'material-cook/4',
   guid: 'mat-root',
   authored: {
     kind: 'material',
@@ -25,14 +27,34 @@ const record: CookedMaterialRecord = {
     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'),
-  },
+  programs: [
+    {
+      specializationKey: 'sha256:program',
+      selections: [
+        {
+          pass: 'forward',
+          context: {
+            backend: 'webgpu',
+            capability: 'storage-buffer',
+            pipeline: 'forward',
+            geometry: 'mesh',
+            pass: 'forward',
+            profile: 'forgeax-material-wgsl-v1',
+            toolchain: 'naga-oil',
+            instrumentation: 'none',
+          },
+        },
+      ],
+      artifact: {
+        mediaType: 'text/wgsl',
+        path: 'materials/mat-root/forward.wgsl',
+        digest: 'sha256:artifact',
+        bytes: new TextEncoder().encode('shader'),
+      },
+    },
+  ],
   receipt: {
-    schemaVersion: 'material-cook/3',
+    schemaVersion: 'material-cook/4',
     sourceClosure: ['materials/mat-root.material.json'],
     profile: 'webgpu/v1',
     compilerVersion: 'compiler/1',
@@ -60,8 +82,21 @@ const record: CookedMaterialRecord = {
   },
 };
 
+function seal(value: CookedMaterialRecord): CookedMaterialRecord {
+  return {
+    ...value,
+    receipt: {
+      ...value.receipt,
+      identity: {
+        ...value.receipt.identity,
+        artifactDigest: createMaterialProgramSetDigest(value.programs, value.resolved.passes),
+      },
+    },
+  };
+}
+
 describe('cooked material schema', () => {
-  it('requires material-cook/3 identity and derived interface association', () => {
+  it('requires material-cook/4 identity and derived interface association', () => {
     const schema = JSON.parse(
       readFileSync(
         fileURLToPath(new URL('../schema/material-cook.schema.json', import.meta.url)),
@@ -74,14 +109,14 @@ describe('cooked material schema', () => {
       >;
       required: string[];
     };
-    expect(schema.properties.schemaVersion?.const).toBe('material-cook/3');
+    expect(schema.properties.schemaVersion?.const).toBe('material-cook/4');
     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', () => {
+  it('defines the v4 identity, provenance, and generation contract', () => {
     const schema = JSON.parse(
       readFileSync(
         fileURLToPath(new URL('../schema/material-cook.schema.json', import.meta.url)),
@@ -93,7 +128,7 @@ describe('cooked material schema', () => {
         { const?: string; required?: string[]; properties?: Record<string, unknown> }
       >;
     };
-    expect(schema.properties.schemaVersion?.const).toBe('material-cook/3');
+    expect(schema.properties.schemaVersion?.const).toBe('material-cook/4');
     expect(schema.properties.receipt?.properties?.identity).toMatchObject({
       type: 'object',
       required: expect.arrayContaining([
@@ -119,25 +154,141 @@ describe('cooked material schema', () => {
   });
 
   it('serializes a stable cooked DTO and derives an artifact digest', () => {
-    const first = serializeCookedMaterialRecord(record);
-    const second = serializeCookedMaterialRecord({ ...record });
+    const first = serializeCookedMaterialRecord(seal(record));
+    const second = serializeCookedMaterialRecord(seal({ ...record }));
 
     expect(first).toBe(second);
-    expect(createMaterialArtifactDigest(record.artifact.bytes)).toBe(
+    expect(createMaterialArtifactDigest(new TextEncoder().encode('shader'))).toBe(
       'sha256:e137e75a5e0e7a623ca39de480667a55b43e0eedec58767634ebaef07c33383a',
     );
-    expect(validateCookedMaterialRecord(JSON.parse(first))).toEqual({ ok: true, value: record });
+    expect(validateCookedMaterialRecord(JSON.parse(first))).toEqual({
+      ok: true,
+      value: seal(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.programs[0]?.artifact.digest).toBe('sha256:artifact');
     expect(projection).not.toHaveProperty('guid');
     expect(projection).not.toHaveProperty('authored');
   });
 
+  it('admits different programs with equal entry names and shared programs with multiple selections', () => {
+    const primary = record.programs[0] as MaterialCookProgram;
+    const passes = [
+      ...record.resolved.passes,
+      {
+        name: 'second',
+        program: { module: 'other', vertexEntry: 'vs_main', fragmentEntry: 'fs_main' },
+      },
+    ];
+    const selection = {
+      ...primary.selections[0],
+      pass: 'second',
+    } as MaterialCookProgram['selections'][number];
+    const distinct = seal({
+      ...record,
+      resolved: { ...record.resolved, passes },
+      programs: [
+        primary,
+        {
+          ...primary,
+          specializationKey: 'second',
+          artifact: {
+            ...primary.artifact,
+            path: 'second.wgsl',
+            digest: 'sha256:second',
+            bytes: new TextEncoder().encode('other'),
+          },
+          selections: [selection],
+        },
+      ],
+    });
+    expect(validateCookedMaterialRecord(distinct)).toMatchObject({ ok: true });
+    const shared = seal({
+      ...distinct,
+      programs: [{ ...primary, selections: [...primary.selections, selection] }],
+    });
+    expect(validateCookedMaterialRecord(shared)).toMatchObject({ ok: true });
+  });
+
+  it('rejects ambiguous selections, unpublished passes and unknown context axes', () => {
+    const primary = record.programs[0] as MaterialCookProgram;
+    expect(
+      validateCookedMaterialRecord({
+        ...record,
+        programs: [primary, { ...primary, specializationKey: 'duplicate' }],
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { detail: { actual: 'ambiguous Pass/context selection' } },
+    });
+    expect(
+      validateCookedMaterialRecord({
+        ...record,
+        resolved: {
+          ...record.resolved,
+          passes: [...record.resolved.passes, { name: 'missing', program: { module: 'other' } }],
+        },
+      }),
+    ).toMatchObject({ ok: false, error: { detail: { actual: 'unpublished Pass' } } });
+    expect(
+      validateCookedMaterialRecord({
+        ...record,
+        programs: [
+          {
+            ...primary,
+            selections: [
+              { pass: 'forward', context: { ...primary.selections[0]?.context, arbitrary: true } },
+            ],
+          },
+        ],
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { detail: { field: 'programs[0].selections[0].context.arbitrary' } },
+    });
+  });
+
+  it('rejects stale manifests after entry or context changes and rejects legacy publication fields', () => {
+    const sealed = seal(record);
+    expect(
+      validateCookedMaterialRecord({
+        ...sealed,
+        resolved: {
+          ...sealed.resolved,
+          passes: [{ name: 'forward', program: { module: 'core/pbr', fragmentEntry: 'fs_other' } }],
+        },
+      }),
+    ).toMatchObject({ ok: false, error: { detail: { field: 'receipt.identity.artifactDigest' } } });
+    const primary = record.programs[0] as MaterialCookProgram;
+    expect(
+      validateCookedMaterialRecord({
+        ...sealed,
+        programs: [
+          {
+            ...primary,
+            selections: [
+              {
+                pass: 'forward',
+                context: { ...primary.selections[0]?.context, geometry: 'skinned' },
+              },
+            ],
+          },
+        ],
+      }),
+    ).toMatchObject({ ok: false, error: { detail: { field: 'receipt.identity.artifactDigest' } } });
+    expect(
+      validateCookedMaterialRecord({ ...sealed, schemaVersion: 'material-cook/3' }),
+    ).toMatchObject({ ok: false });
+    expect(validateCookedMaterialRecord({ ...sealed, artifact: primary.artifact })).toMatchObject({
+      ok: false,
+    });
+  });
+
   it('rejects missing fields and unsupported schema versions', () => {
     expect(validateCookedMaterialRecord({ ...record, refs: undefined })).toMatchObject({
       ok: false,
@@ -154,7 +305,7 @@ describe('cooked material schema', () => {
   it('rejects a Standard record whose receipt layer plan is stale', () => {
     const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
     const standardPlan = deriveStandardLayerPlan(record.resolved.parameters, [standardPass]);
-    const standardRecord = {
+    const standardRecord = seal({
       ...record,
       resolved: { ...record.resolved, passes: [standardPass] },
       receipt: {
@@ -164,7 +315,7 @@ describe('cooked material schema', () => {
           layerPlanIdentity: standardPlan.identity,
         },
       },
-    };
+    });
     expect(validateCookedMaterialRecord(standardRecord)).toMatchObject({ ok: true });
     expect(
       validateCookedMaterialRecord({
@@ -185,7 +336,7 @@ describe('cooked material schema', () => {
   it('rejects a Standard record whose receipt omits the layer plan identity', () => {
     const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
     const standardPlan = deriveStandardLayerPlan(record.resolved.parameters, [standardPass]);
-    const standardRecord = {
+    const standardRecord = seal({
       ...record,
       resolved: { ...record.resolved, passes: [standardPass] },
       receipt: {
@@ -195,7 +346,7 @@ describe('cooked material schema', () => {
           layerPlanIdentity: standardPlan.identity,
         },
       },
-    };
+    });
     expect(
       validateCookedMaterialRecord({
         ...standardRecord,

package/src/__tests__/material-declaration-boundary.unit.test.ts

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../');
+const CONFIG_PATH = resolve(REPO_ROOT, 'packages/pack/tsconfig.json');
+
+async function declarationProjectInputs(): Promise<readonly string[]> {
+  const source = await readFile(CONFIG_PATH, 'utf8');
+  const parsed = ts.parseJsonConfigFileContent(
+    JSON.parse(source),
+    ts.sys,
+    dirname(CONFIG_PATH),
+    undefined,
+    CONFIG_PATH,
+  );
+  return parsed.fileNames.map((fileName) => relative(REPO_ROOT, fileName));
+}
+
+describe('Pack declaration project boundary', () => {
+  it('keeps tests and emitted declarations out of production inputs', async () => {
+    const inputs = await declarationProjectInputs();
+    const config = JSON.parse(await readFile(CONFIG_PATH, 'utf8')) as {
+      readonly exclude?: readonly string[];
+    };
+
+    expect(config.exclude).toEqual(expect.arrayContaining(['src/**/__tests__/**', 'dist/**']));
+    expect(inputs.some((fileName) => fileName.startsWith('packages/pack/src/__tests__/'))).toBe(
+      false,
+    );
+    expect(inputs.some((fileName) => fileName.startsWith('packages/pack/dist/'))).toBe(false);
+  });
+});

package/src/__tests__/material-surface-consumer-census.test.ts

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const packageRoots = ['packages/pack/src', 'packages/vite-plugin-pack/src', 'packages/render/src'];
+
+describe('Surface consumer census', () => {
+  it('keeps the runtime and Pack consumers on the existing MaterialAsset wire', async () => {
+    const sources = await Promise.all(
+      packageRoots.map(async (root) => {
+        const path = resolve(process.cwd(), root, 'index.ts');
+        try {
+          return await readFile(path, 'utf8');
+        } catch {
+          return '';
+        }
+      }),
+    );
+    const source = sources.join('\n');
+    expect(source).not.toContain('SurfaceAsset');
+    expect(source).not.toContain('surfaceModule');
+    expect(source).not.toContain('shadingModel');
+  });
+});

package/src/__tests__/material-surface-publication.unit.test.ts

@@ -0,0 +1,162 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Materials } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { validateCookedMaterialRecord } from '../material-cook.js';
+import { NativeCookerRegistry } from '../native-cooker-registry.js';
+
+const compilerModule = pathToFileURL(
+  resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    '../../../../packages/shader-compiler/dist/index.mjs',
+  ),
+).href;
+
+const GUID = '11111111-1111-4111-8111-111111111111';
+const ROOT_GUID = '22222222-2222-4222-8222-222222222222';
+const CHILD_GUID = '33333333-3333-4333-8333-333333333333';
+const SURFACE = `#define_import_path game_3d::rusted_iron_surface
+#import forgeax_material::surface_v1::{SurfaceData, SurfaceInput}
+fn evaluate_surface(input: SurfaceInput) -> SurfaceData {
+  return SurfaceData(vec3<f32>(0.4, 0.45, 0.47), input.geometricNormalWS, 0.0, 0.5, vec3<f32>(0.0), 1.0, 1.0, 0.0);
+}`;
+
+describe('Surface Pack publication', () => {
+  it('publishes one complete cooked record with source closure and artifact', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-surface-publication-'));
+    try {
+      const sourcePath = join(root, 'rusted-iron-surface.wgsl');
+      await writeFile(sourcePath, SURFACE);
+      const material = Materials.standard({
+        surfaceModule: 'game_3d::rusted_iron_surface',
+        parameters: [],
+        values: {},
+      });
+      const { createMaterialPackCooker } = await import(compilerModule);
+      const draft = await createMaterialPackCooker([root]).cook({
+        guid: GUID,
+        source: material,
+        sourcePath,
+      });
+      const cooked = validateCookedMaterialRecord(draft.payload.cooked).unwrap();
+      expect(cooked.receipt.sourceClosure).toContain(sourcePath);
+      expect(cooked.programs.length).toBeGreaterThan(0);
+      for (const program of cooked.programs) {
+        const artifact = draft.artifacts[program.artifact.path];
+        expect(artifact?.bytes.byteLength).toBeGreaterThan(0);
+        expect(artifact?.bytes).toEqual(new Uint8Array(program.artifact.bytes));
+      }
+      expect(
+        cooked.resolved.passes?.find((pass) => pass.name === 'shadow-caster')?.program,
+      ).toMatchObject({ module: 'forgeax::default-shadow-caster', fragmentEntry: 'fs_shadow' });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps the accepted generation as last known good after cook failure', async () => {
+    const registry = new NativeCookerRegistry();
+    registry.register({
+      key: 'material',
+      cook: async (input: { readonly fail?: boolean }) => {
+        if (input.fail) throw new Error('surface compose failed');
+        return {
+          guid: GUID,
+          payload: { generation: 1 },
+          refs: [],
+          artifacts: {},
+          inputFingerprint: 'sha256:surface-input',
+        };
+      },
+    });
+    const first = await registry.runTransaction({ key: 'material', input: {} });
+    expect(first).toMatchObject({ ok: true, value: { generation: 1, status: 'committed' } });
+    if (!first.ok) return;
+    const failed = await registry.runTransaction({
+      key: 'material',
+      input: { fail: true },
+      previous: { draft: first.value.draft, generation: first.value.generation },
+    });
+    expect(failed).toMatchObject({
+      ok: true,
+      value: {
+        status: 'recovered',
+        lastKnownGood: { payload: { generation: 1 } },
+        lastKnownGoodGeneration: 1,
+      },
+    });
+  });
+
+  it('cold-cooks a child through the Pack-owned root table and publishes its parent ref', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-surface-root-child-'));
+    try {
+      const rootMaterial = Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        metallic: 0,
+        roughness: 0.5,
+      });
+      const child = {
+        kind: 'material' as const,
+        parent: ROOT_GUID as never,
+        values: { baseColor: [0.4, 0.45, 0.47, 1] },
+      };
+      const { createMaterialPackCooker } = await import(compilerModule);
+      const draft = await createMaterialPackCooker([root]).cook({
+        guid: CHILD_GUID,
+        source: child,
+        table: { [ROOT_GUID]: rootMaterial, [CHILD_GUID]: child },
+      });
+      const cooked = draft.payload.cooked as {
+        readonly authored: { readonly parent?: string };
+        readonly resolved: {
+          readonly parameters: readonly { readonly name: string }[];
+          readonly values: Readonly<Record<string, unknown>>;
+        };
+        readonly refs: { readonly parent: readonly string[] };
+      };
+      expect(cooked.authored.parent).toBe(ROOT_GUID);
+      expect(cooked.refs.parent).toEqual([ROOT_GUID]);
+      expect(cooked.resolved.parameters.map((parameter) => parameter.name)).toContain('baseColor');
+      expect(cooked.resolved.values.baseColor).toEqual([0.4, 0.45, 0.47, 1]);
+      expect(draft.refs).toContain(ROOT_GUID);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('does not publish an artifact when a physical material requests Deferred', async () => {
+    const { createMaterialPackCooker } = await import(compilerModule);
+    const material = {
+      kind: 'material' as const,
+      passes: [
+        {
+          name: 'forward',
+          program: {
+            module: 'forgeax_material::standard',
+            moduleSlots: { surface: 'forgeax_material::default_standard_surface' },
+          },
+        },
+        {
+          name: 'deferred',
+          program: {
+            module: 'forgeax_material::standard',
+            moduleSlots: { surface: 'forgeax_material::default_standard_surface' },
+          },
+        },
+      ],
+      parameters: [
+        { name: 'clearcoat', type: 'f32' as const },
+        { name: 'clearcoatRoughness', type: 'f32' as const },
+      ],
+      values: { clearcoat: 0, clearcoatRoughness: 0.5 },
+    };
+    await expect(
+      createMaterialPackCooker().cook({
+        guid: GUID,
+        source: material,
+      }),
+    ).rejects.toMatchObject({ code: 'material-physical-contract-invalid' });
+  });
+});

package/src/__tests__/material-surface-wire.unit.test.ts

@@ -0,0 +1,30 @@
+import { Materials } from '@forgeax/engine-render';
+import { assertMaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const customOptions = {
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  parameters: [{ name: 'ironColor', type: 'color' as const }],
+  values: { ironColor: [0.4, 0.45, 0.47, 1] },
+};
+
+describe('custom Surface MaterialAsset wire projection', () => {
+  it('uses Standard modules plus the default shadow caster and the existing Surface slot wire', () => {
+    const material = Materials.standard(customOptions as never);
+    expect(material.passes?.map((pass) => pass.program.module)).toEqual([
+      'forgeax_material::standard',
+      'forgeax_material::standard',
+      'forgeax::default-shadow-caster',
+    ]);
+    expect(
+      material.passes?.every(
+        (pass) => pass.program.moduleSlots?.surface === customOptions.surfaceModule,
+      ),
+    ).toBe(true);
+    const wire = JSON.parse(JSON.stringify(material)) as Record<string, unknown>;
+    assertMaterialAsset(wire);
+    expect(wire).not.toHaveProperty('surfaceModule');
+    expect(wire).not.toHaveProperty('shadingModel');
+    expect(wire).not.toHaveProperty('surface');
+  });
+});

package/src/build.ts

@@ -57,6 +57,8 @@ export {
   createMaterialArtifactDigest,
   type MaterialCookArtifact,
   type MaterialCookIdentityExpectation,
+  type MaterialCookProgram,
+  type MaterialCookProgramContext,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,