@forgeax/engine-pack 0.1.6 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-pack",
-  "version": "0.1.6",
+  "version": "0.1.19",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -108,7 +108,7 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "tsup": "^8.3.5",
-    "vitest": "4.1.5"
+    "vitest": "4.1.11"
   },
   "forgeax": {
     "metrics": {
@@ -136,7 +136,7 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine-types": "0.1.6",
+    "@forgeax/engine-types": "0.1.19",
     "@noble/hashes": "^2.2.0",
     "fast-glob": "^3.3.3",
     "typescript": "^5.8.3",

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

@@ -1,6 +1,8 @@
 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', () => {
@@ -23,6 +25,50 @@ describe('material cook dependency closure', () => {
     });
   });
 
+  it('collects transmission and thickness texture dependencies', () => {
+    expect(
+      collectMaterialCookRefs({
+        parameters: [
+          { name: 'transmissionTexture', type: 'texture' },
+          { name: 'thicknessTexture', type: 'texture' },
+        ],
+        values: {
+          transmissionTexture: { texture: 'texture/transmission', sampler: 'sampler/linear' },
+          thicknessTexture: { texture: 'texture/thickness', sampler: 'sampler/linear' },
+        },
+      }),
+    ).toEqual({
+      parent: [],
+      textures: ['texture/thickness', 'texture/transmission'],
+      samplers: ['sampler/linear'],
+      modules: [],
+    });
+  });
+
+  it('keeps authored Standard values with both texture dependency edges', () => {
+    const refs = collectMaterialCookRefs({
+      passes: [{ name: 'Forward', program: { module: 'forgeax::default-standard-pbr' } }],
+      parameters: [
+        { name: 'transmissionTexture', type: 'texture' },
+        { name: 'thicknessTexture', type: 'texture' },
+      ],
+      values: {
+        transmission: 0.8,
+        ior: 1.45,
+        thickness: 0.25,
+        transmissionTexture: { texture: 'texture/transmission', sampler: 'sampler/linear' },
+        thicknessTexture: { texture: 'texture/thickness', sampler: 'sampler/linear' },
+      },
+    });
+
+    expect(refs).toEqual({
+      parent: [],
+      textures: ['texture/thickness', 'texture/transmission'],
+      samplers: ['sampler/linear'],
+      modules: ['forgeax::default-standard-pbr'],
+    });
+  });
+
   it('collects string shorthands only from declared texture parameters', () => {
     expect(
       collectMaterialCookRefs({
@@ -42,4 +88,69 @@ describe('material cook dependency closure', () => {
       }),
     ).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

@@ -10,28 +10,86 @@ const artifactDigest = 'sha256:output';
 
 function receipt(overrides: Record<string, unknown> = {}): MaterialCookReceipt {
   return {
-    schemaVersion: 'material-cook/2',
+    schemaVersion: 'material-cook/3',
     sourceClosure: ['b.wgsl', 'a.material.json'],
     profile: 'webgpu/v1',
     compilerVersion: 'compiler/1',
-    inputDigest: 'sha256:input',
-    outputDigest: artifactDigest,
-    layoutIdentity,
+    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('serializes a material-cook/2 receipt stably for equivalent cooks', () => {
+  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/2',
-      layoutIdentity,
+      schemaVersion: 'material-cook/3',
+      identity: { layoutIdentity },
       derivedInterface: { layoutIdentity },
     });
   });
@@ -43,7 +101,10 @@ describe('material cook receipt', () => {
       value: receipt(),
     });
     expect(
-      validateMaterialCookReceipt(receipt({ layoutIdentity: 'sha256:changed-layout' }), expected),
+      validateMaterialCookReceipt(
+        receipt({ identity: { ...receipt().identity, layoutIdentity: 'sha256:changed-layout' } }),
+        expected,
+      ),
     ).toMatchObject({ ok: false, error: { code: 'material-cook-record-invalid' } });
     expect(
       validateMaterialCookReceipt(
@@ -56,15 +117,14 @@ describe('material cook receipt', () => {
   it('rejects missing, stale, mismatched, and material-cook/1 receipts fail-fast', () => {
     const expected = { layoutIdentity, artifactDigest, inputDigest: 'sha256:input' };
     for (const value of [
-      receipt({ layoutIdentity: undefined }),
-      receipt({ outputDigest: 'sha256:stale-artifact' }),
-      receipt({ inputDigest: 'sha256:stale-input' }),
+      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',
-        inputDigest: 'sha256:input',
-        outputDigest: artifactDigest,
+        identity: receipt().identity,
       },
     ]) {
       expect(validateMaterialCookReceipt(value as MaterialCookReceipt, expected)).toMatchObject({
@@ -75,17 +135,14 @@ describe('material cook receipt', () => {
   });
 
   it('records the coordinator-owned publication generation', () => {
-    const receipt = {
+    const generationReceipt = {
       sourceClosure: ['materials/mat-root.material.json'],
       profile: 'webgpu/v1',
       compilerVersion: 'compiler/1',
-      inputDigest: 'sha256:input',
-      outputDigest: 'sha256:artifact',
-      publicationGeneration: 11,
+      identity: { ...receipt().identity, cookGeneration: 11 },
     };
-    expect(receipt).toMatchObject({
-      publicationGeneration: 11,
-      outputDigest: 'sha256:artifact',
+    expect(generationReceipt).toMatchObject({
+      identity: { cookGeneration: 11 },
     });
   });
 });

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

@@ -10,17 +10,17 @@ import {
 } from '../evidence/material-cook.js';
 
 const record: CookedMaterialRecord = {
-  schemaVersion: 'material-cook/2',
+  schemaVersion: 'material-cook/3',
   guid: 'mat-root',
   authored: {
     kind: 'material',
     passes: [{ name: 'forward', program: { module: 'core/pbr' } }],
-    parameters: [{ name: 'roughness', type: 'f32', static: true }],
+    parameters: [{ name: 'roughness', type: 'f32' }],
     values: { roughness: 0.5 },
   },
   resolved: {
     passes: [{ name: 'forward', program: { module: 'core/pbr' } }],
-    parameters: [{ name: 'roughness', type: 'f32', static: true }],
+    parameters: [{ name: 'roughness', type: 'f32' }],
     values: { roughness: 0.5 },
   },
   refs: { parent: [], textures: [], samplers: [], modules: ['core/pbr'] },
@@ -31,19 +31,36 @@ const record: CookedMaterialRecord = {
     bytes: new TextEncoder().encode('shader'),
   },
   receipt: {
-    schemaVersion: 'material-cook/2',
+    schemaVersion: 'material-cook/3',
     sourceClosure: ['materials/mat-root.material.json'],
     profile: 'webgpu/v1',
     compilerVersion: 'compiler/1',
-    inputDigest: 'sha256:input',
-    outputDigest: 'sha256:artifact',
-    layoutIdentity: 'sha256:layout',
+    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/2 identity and derived interface association', () => {
+  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)),
@@ -56,13 +73,50 @@ describe('cooked material schema', () => {
       >;
       required: string[];
     };
-    expect(schema.properties.schemaVersion?.const).toBe('material-cook/2');
+    expect(schema.properties.schemaVersion?.const).toBe('material-cook/3');
     expect(schema.properties.receipt?.required).toEqual(
-      expect.arrayContaining(['layoutIdentity', 'derivedInterface']),
+      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 });

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

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { parsePackV2 } from '../index.js';
+import { parsePackV2, validateCookedMaterialRecord } from '../index.js';
 
 const root = resolve(import.meta.dirname, '../../../../');
 
@@ -61,4 +61,27 @@ describe('Pack v2 fixture migration', () => {
       }).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' } });
+  });
 });

package/src/build.ts

@@ -33,6 +33,7 @@ export {
   type CatalogBuildResult,
   type CatalogImporterPolicy,
   type CatalogProducerVisibility,
+  catalogSourcePathFor,
   metaPathForGuid,
 } from './catalog-builder.js';
 export { calculateCatalogDelta } from './catalog-delta.js';

package/src/catalog-builder.ts

@@ -1,4 +1,4 @@
-import { relative } from 'node:path';
+import { isAbsolute, relative } from 'node:path';
 import type { PackIndexEntry, ProviderProvenance } from '@forgeax/engine-types';
 import {
   findReservedAssetKindConflict,
@@ -75,12 +75,38 @@ export interface CatalogBuildProjectionOptions {
   readonly scanOptions?: ScanOptions;
   readonly importerPolicy: (importer: string) => CatalogImporterPolicy;
   readonly visibility?: CatalogProducerVisibility;
+  /**
+   * Project physical source paths into a stable host-owned logical identity.
+   * Scanner/declaration maps retain physical paths for I/O; only Catalog rows
+   * use this projection so symlink farms cannot change publication identity.
+   */
+  readonly sourceIdentityFor?: (sourcePath: string) => string;
 }
 
 function sourcePathFor(cwd: string, path: string): string {
   return relative(cwd, path).replace(/\\/g, '/');
 }
 
+/**
+ * Project one physical source path into the catalog's browser-safe logical
+ * locator. Physical paths remain the scanner/declaration keys; only catalog
+ * rows use this projection.
+ */
+export function catalogSourcePathFor(
+  cwd: string,
+  path: string,
+  sourceIdentityFor: CatalogBuildProjectionOptions['sourceIdentityFor'],
+): string {
+  const projected = sourceIdentityFor?.(path);
+  // A host may intentionally leave paths outside its logical roots untouched.
+  // Keep the catalog's existing cwd-relative URL contract for that fallback;
+  // an absolute physical path is a valid dependency identity, but not a
+  // browser-served catalog locator.
+  const catalogPath =
+    projected === undefined || isAbsolute(projected) ? sourcePathFor(cwd, path) : projected;
+  return catalogPath.replaceAll('\\', '/').replace(/^\.\//, '');
+}
+
 export function metaPathForGuid(
   declarations: ReadonlyMap<string, CatalogImportMeta>,
   guid: string,
@@ -115,6 +141,7 @@ function projectMeta(
   assetPaths: Record<string, string>,
   importerPolicy: (importer: string) => CatalogImporterPolicy,
   sourceDeclaration: Extract<ScanSourceDeclaration, { readonly format: 'meta.json' }>,
+  sourceIdentityFor: CatalogBuildProjectionOptions['sourceIdentityFor'],
 ): {
   readonly entries: PackIndexEntry[];
   readonly declaration?: CatalogImportMeta;
@@ -136,7 +163,7 @@ function projectMeta(
       },
     };
   }
-  const sourcePath = sourcePathFor(cwd, resolved.value);
+  const sourcePath = catalogSourcePathFor(cwd, resolved.value, sourceIdentityFor);
   const packageUrl = `${base}/__forgeax-ddc/${meta.subAssets[0]?.guid?.toLowerCase() ?? 'pack'}.pack.json`;
   const declaration: CatalogImportMeta = {
     importer: meta.importer,
@@ -184,6 +211,7 @@ function projectSource(
   visibility: CatalogBuildProjectionOptions['visibility'],
   sourceDeclaration: ScanSourceDeclaration,
   declarations: Map<string, CatalogImportMeta>,
+  sourceIdentityFor: CatalogBuildProjectionOptions['sourceIdentityFor'],
 ): { readonly entries: PackIndexEntry[]; readonly error?: CatalogBuildError } {
   if (sourceDeclaration.format === 'pack.ts') {
     const meta = { ...sourceDeclaration.meta, source: sourcePathFor(cwd, path) };
@@ -193,7 +221,7 @@ function projectSource(
       : {
           entries: projectExternalCatalogEntries(
             meta,
-            sourcePathFor(cwd, path),
+            catalogSourcePathFor(cwd, path, sourceIdentityFor),
             `${base}/__forgeax-ddc/${anchorGuid}.pack.json`,
             meta.subAssets,
             (output) => deriveAssetName(path, meta.subAssets.length, output.name),
@@ -212,12 +240,20 @@ function projectSource(
     ) {
       return { entries: [] };
     }
-    const projected = projectMeta(path, cwd, base, assetPaths, importerPolicy, sourceDeclaration);
+    const projected = projectMeta(
+      path,
+      cwd,
+      base,
+      assetPaths,
+      importerPolicy,
+      sourceDeclaration,
+      sourceIdentityFor,
+    );
     if (projected.declaration !== undefined) declarations.set(path, projected.declaration);
     return projected;
   }
   const parsed = sourceDeclaration.value;
-  const sourcePath = sourcePathFor(cwd, path);
+  const sourcePath = catalogSourcePathFor(cwd, path, sourceIdentityFor);
   const provenance =
     parsed.provenance ??
     ({ provider: 'pack', version: parsed.schemaVersion } satisfies ProviderProvenance);
@@ -297,6 +333,7 @@ export async function buildCatalogProjection(
       options.visibility,
       sourceDeclaration,
       declarations,
+      options.sourceIdentityFor,
     );
     entries.push(...projected.entries);
     if (projected.error !== undefined) errors.push(projected.error);