@forgeax/engine-pack 0.1.25 → 0.1.26

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-surface-publication.unit.test.ts

@@ -4,6 +4,7 @@ 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(
@@ -39,15 +40,17 @@ describe('Surface Pack publication', () => {
         source: material,
         sourcePath,
       });
-      const cooked = draft.payload.cooked as {
-        readonly receipt: { readonly sourceClosure: readonly string[] };
-        readonly artifact: { readonly path: string; readonly bytes: Uint8Array };
-      };
+      const cooked = validateCookedMaterialRecord(draft.payload.cooked).unwrap();
       expect(cooked.receipt.sourceClosure).toContain(sourcePath);
-      expect(cooked.artifact.path).toContain(GUID);
-      const artifact = draft.artifacts[cooked.artifact.path];
-      expect(artifact?.bytes.byteLength).toBeGreaterThan(0);
-      expect(Object.keys(draft.artifacts)).toContain(cooked.artifact.path);
+      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 });
     }
@@ -154,6 +157,6 @@ describe('Surface Pack publication', () => {
         guid: GUID,
         source: material,
       }),
-    ).rejects.toThrow('material-physical-contract-invalid');
+    ).rejects.toMatchObject({ code: 'material-physical-contract-invalid' });
   });
 });

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

@@ -9,12 +9,12 @@ const customOptions = {
 };
 
 describe('custom Surface MaterialAsset wire projection', () => {
-  it('uses Standard module and the existing Surface slot wire', () => {
+  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_material::standard',
+      'forgeax::default-shadow-caster',
     ]);
     expect(
       material.passes?.every(

package/src/build.ts

@@ -57,11 +57,11 @@ export {
   createMaterialArtifactDigest,
   type MaterialCookArtifact,
   type MaterialCookIdentityExpectation,
+  type MaterialCookProgram,
+  type MaterialCookProgramContext,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
-  type MaterialCookVariant,
-  type MaterialCookVariantContext,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,