@forgeax/engine-pack 0.1.25 → 0.1.27

package/src/evidence/material-cook.ts

@@ -25,17 +25,26 @@ export interface MaterialCookArtifact {
   readonly bytes: Uint8Array;
 }
 
-/** Backend capability projection for one immutable cooked material artifact. */
-export interface MaterialCookVariantContext {
+/** Domain-owned inputs used to compile and select a material program. */
+export interface MaterialCookProgramContext {
   readonly backend: 'webgpu' | 'webgl2' | 'wgpu-native';
   readonly capability: 'storage-buffer' | 'uniform-fallback';
+  readonly pipeline: 'forward' | 'deferred';
+  readonly geometry: 'mesh' | 'skinned' | 'sprite';
+  readonly pass: 'forward' | 'shadow' | 'depth';
+  readonly profile: 'forgeax-material-wgsl-v1';
+  readonly toolchain: 'naga-oil';
+  readonly instrumentation: 'none' | 'validation';
 }
 
-/** Additional backend artifact published with one material generation. */
-export interface MaterialCookVariant {
-  readonly context: MaterialCookVariantContext;
+/** Programs are derived artifacts, never independently authored assets. */
+export interface MaterialCookProgram {
   readonly specializationKey: string;
   readonly artifact: MaterialCookArtifact;
+  readonly selections: readonly {
+    readonly pass: string;
+    readonly context: MaterialCookProgramContext;
+  }[];
 }
 
 export interface MaterialCookWasmProvenance {
@@ -64,7 +73,7 @@ export interface MaterialCookIdentity {
 export type MaterialCookIdentityInput = Omit<MaterialCookIdentity, 'cookIdentity'>;
 
 export interface MaterialCookReceipt {
-  readonly schemaVersion: 'material-cook/3';
+  readonly schemaVersion: 'material-cook/4';
   readonly sourceClosure: readonly string[];
   readonly profile: string;
   readonly compilerVersion: string;
@@ -82,16 +91,14 @@ export interface MaterialParameterContract {
 }
 
 export interface CookedMaterialRecord {
-  readonly schemaVersion: 'material-cook/3';
+  readonly schemaVersion: 'material-cook/4';
   readonly guid: string;
   readonly authored?: MaterialAsset;
   readonly materialGuid?: string;
   readonly publicationGeneration?: number;
   readonly specializationKey?: string;
-  /** Compiler context used by the primary `artifact` entry. */
-  readonly variantContext?: MaterialCookVariantContext;
-  /** Additional immutable artifacts for other backend capability lanes. */
-  readonly variants?: readonly MaterialCookVariant[];
+  readonly programs: readonly MaterialCookProgram[];
+  /** Digest of the complete program/Pass/context manifest. */
   readonly artifactDigest?: string;
   readonly sourceClosure?: readonly string[];
   readonly parameterContract?: MaterialParameterContract;
@@ -101,7 +108,6 @@ export interface CookedMaterialRecord {
     readonly values: Readonly<Record<string, MaterialValue | null>>;
   };
   readonly refs: MaterialCookRefs;
-  readonly artifact: MaterialCookArtifact;
   readonly receipt: MaterialCookReceipt;
 }
 
@@ -127,7 +133,6 @@ const STANDARD_ROOT_MODULES = new Set([
   'forgeax::pbr-skin',
   'forgeax_material::standard',
   'forgeax_material::pbr-skin',
-  'forgeax::default-shadow-caster',
 ]);
 
 /** Shared ownership predicate for the built-in Standard material root. */
@@ -266,7 +271,7 @@ export function serializeMaterialCookReceipt(receipt: MaterialCookReceipt): stri
 function invalid(field: string, actual?: unknown): Result<never, MaterialCookRecordError> {
   return err({
     code: 'material-cook-record-invalid',
-    expected: 'a complete material-cook/3 record with layered identity and provenance',
+    expected: 'a complete material-cook/4 record with layered identity and provenance',
     hint: 're-cook the material and publish its record, artifact, references, and receipt together',
     detail: {
       field,
@@ -337,7 +342,7 @@ export function validateMaterialCookReceipt(
 ): Result<MaterialCookReceipt, MaterialCookRecordError> {
   if (value === null || typeof value !== 'object') return invalid('receipt');
   const candidate = value as Record<string, unknown>;
-  if (candidate.schemaVersion !== 'material-cook/3')
+  if (candidate.schemaVersion !== 'material-cook/4')
     return invalid('receipt.schemaVersion', candidate.schemaVersion);
   const identityResult = validateIdentity(candidate.identity);
   if (!identityResult.ok) return identityResult;
@@ -388,7 +393,7 @@ export function validateMaterialCookReceipt(
     return invalid('receipt.identity.cookIdentity', identity.cookIdentity);
   }
   return ok({
-    schemaVersion: 'material-cook/3',
+    schemaVersion: 'material-cook/4',
     sourceClosure: candidate.sourceClosure as string[],
     profile: candidate.profile as string,
     compilerVersion: candidate.compilerVersion as string,
@@ -407,7 +412,7 @@ export function validateCookedMaterialRecord(
 ): Result<CookedMaterialRecord, MaterialCookRecordError> {
   if (value === null || typeof value !== 'object') return invalid('record');
   const candidate = value as Record<string, unknown>;
-  if (candidate.schemaVersion !== 'material-cook/3')
+  if (candidate.schemaVersion !== 'material-cook/4')
     return invalid('schemaVersion', candidate.schemaVersion);
   if (typeof candidate.guid !== 'string' || !candidate.guid) return invalid('guid');
   if (candidate.materialGuid !== undefined && typeof candidate.materialGuid !== 'string')
@@ -419,49 +424,8 @@ export function validateCookedMaterialRecord(
     return invalid('publicationGeneration', candidate.publicationGeneration);
   if (candidate.specializationKey !== undefined && typeof candidate.specializationKey !== 'string')
     return invalid('specializationKey');
-  if (candidate.variantContext !== undefined) {
-    if (candidate.variantContext === null || typeof candidate.variantContext !== 'object')
-      return invalid('variantContext');
-    const context = candidate.variantContext as Record<string, unknown>;
-    if (
-      (context.backend !== 'webgpu' &&
-        context.backend !== 'webgl2' &&
-        context.backend !== 'wgpu-native') ||
-      (context.capability !== 'storage-buffer' && context.capability !== 'uniform-fallback')
-    )
-      return invalid('variantContext', candidate.variantContext);
-  }
-  if (candidate.variants !== undefined) {
-    if (!Array.isArray(candidate.variants)) return invalid('variants');
-    for (const [index, value] of candidate.variants.entries()) {
-      if (value === null || typeof value !== 'object') return invalid(`variants[${index}]`);
-      const variant = value as Record<string, unknown>;
-      const context = variant.context;
-      if (context === null || typeof context !== 'object')
-        return invalid(`variants[${index}].context`);
-      const contextRecord = context as Record<string, unknown>;
-      if (
-        (contextRecord.backend !== 'webgpu' &&
-          contextRecord.backend !== 'webgl2' &&
-          contextRecord.backend !== 'wgpu-native') ||
-        (contextRecord.capability !== 'storage-buffer' &&
-          contextRecord.capability !== 'uniform-fallback')
-      )
-        return invalid(`variants[${index}].context`, context);
-      if (typeof variant.specializationKey !== 'string' || variant.specializationKey.length === 0)
-        return invalid(`variants[${index}].specializationKey`);
-      if (variant.artifact === null || typeof variant.artifact !== 'object')
-        return invalid(`variants[${index}].artifact`);
-      const variantArtifact = variant.artifact as Record<string, unknown>;
-      if (
-        typeof variantArtifact.mediaType !== 'string' ||
-        typeof variantArtifact.path !== 'string' ||
-        typeof variantArtifact.digest !== 'string' ||
-        normalizeArtifactBytes(variantArtifact.bytes) === undefined
-      )
-        return invalid(`variants[${index}].artifact`);
-    }
-  }
+  if ('artifact' in candidate || 'variants' in candidate || 'variantContext' in candidate)
+    return invalid('programs', 'legacy single-artifact publication');
   if (candidate.artifactDigest !== undefined && typeof candidate.artifactDigest !== 'string')
     return invalid('artifactDigest');
   if (
@@ -486,21 +450,8 @@ export function validateCookedMaterialRecord(
   if (candidate.resolved === null || typeof candidate.resolved !== 'object')
     return invalid('resolved');
   if (candidate.refs === null || typeof candidate.refs !== 'object') return invalid('refs');
-  if (candidate.artifact === null || typeof candidate.artifact !== 'object')
-    return invalid('artifact');
   if (candidate.receipt === null || typeof candidate.receipt !== 'object')
     return invalid('receipt');
-  const artifact = candidate.artifact as Record<string, unknown>;
-  if (
-    typeof artifact.digest !== 'string' ||
-    (!Array.isArray(artifact.bytes) && !ArrayBuffer.isView(artifact.bytes))
-  ) {
-    return invalid('artifact');
-  }
-  const receiptResult = validateMaterialCookReceipt(candidate.receipt, {
-    artifactDigest: artifact.digest as string,
-  });
-  if (!receiptResult.ok) return receiptResult;
   const resolved = candidate.resolved as Record<string, unknown>;
   if (!Array.isArray(resolved.passes)) return invalid('resolved.passes', resolved.passes);
   if (!Array.isArray(resolved.parameters))
@@ -511,6 +462,84 @@ export function validateCookedMaterialRecord(
     Array.isArray(resolved.values)
   )
     return invalid('resolved.values', resolved.values);
+  const passes = resolved.passes as MaterialPass[];
+  const passNames = new Set<string>();
+  for (const [index, pass] of passes.entries()) {
+    if (
+      pass === null ||
+      typeof pass !== 'object' ||
+      typeof pass.name !== 'string' ||
+      !pass.name ||
+      passNames.has(pass.name) ||
+      pass.program === null ||
+      typeof pass.program !== 'object' ||
+      typeof pass.program.module !== 'string'
+    )
+      return invalid(`resolved.passes[${index}]`);
+    passNames.add(pass.name);
+  }
+  if (!Array.isArray(candidate.programs) || candidate.programs.length === 0)
+    return invalid('programs');
+  const programs: MaterialCookProgram[] = [];
+  const programKeys = new Set<string>();
+  const selections = new Set<string>();
+  const selectedPasses = new Set<string>();
+  for (const [index, entry] of candidate.programs.entries()) {
+    const field = `programs[${index}]`;
+    if (entry === null || typeof entry !== 'object') return invalid(field);
+    const program = entry as Record<string, unknown>;
+    if (
+      typeof program.specializationKey !== 'string' ||
+      !program.specializationKey ||
+      programKeys.has(program.specializationKey)
+    )
+      return invalid(`${field}.specializationKey`);
+    programKeys.add(program.specializationKey);
+    if (program.artifact === null || typeof program.artifact !== 'object')
+      return invalid(`${field}.artifact`);
+    const artifact = program.artifact as Record<string, unknown>;
+    const bytes = normalizeArtifactBytes(artifact.bytes);
+    if (
+      artifact.mediaType !== 'text/wgsl' ||
+      typeof artifact.path !== 'string' ||
+      !artifact.path ||
+      typeof artifact.digest !== 'string' ||
+      !artifact.digest ||
+      bytes === undefined
+    )
+      return invalid(`${field}.artifact`);
+    if (!Array.isArray(program.selections) || program.selections.length === 0)
+      return invalid(`${field}.selections`);
+    const programSelections: MaterialCookProgram['selections'][number][] = [];
+    for (const [selectionIndex, selection] of program.selections.entries()) {
+      const selectionField = `${field}.selections[${selectionIndex}]`;
+      if (selection === null || typeof selection !== 'object' || !passNames.has(selection.pass))
+        return invalid(selectionField);
+      const context = validateMaterialCookProgramContext(selection.context);
+      if (!context.ok)
+        return invalid(
+          `${selectionField}.${context.error.detail.field}`,
+          context.error.detail.actual,
+        );
+      const key = JSON.stringify([selection.pass, materialProgramContextKey(context.value)]);
+      if (selections.has(key)) return invalid(selectionField, 'ambiguous Pass/context selection');
+      selections.add(key);
+      selectedPasses.add(selection.pass);
+      programSelections.push({ pass: selection.pass, context: context.value });
+    }
+    programs.push({
+      specializationKey: program.specializationKey,
+      artifact: { mediaType: 'text/wgsl', path: artifact.path, digest: artifact.digest, bytes },
+      selections: programSelections,
+    });
+  }
+  if ([...passNames].some((pass) => !selectedPasses.has(pass)))
+    return invalid('programs.selections', 'unpublished Pass');
+  const manifestDigest = createMaterialProgramSetDigest(programs, passes);
+  const receiptResult = validateMaterialCookReceipt(candidate.receipt, {
+    artifactDigest: manifestDigest,
+  });
+  if (!receiptResult.ok) return receiptResult;
   let expectedLayerPlanIdentity: string | undefined;
   try {
     expectedLayerPlanIdentity = materialLayerPlanIdentity({
@@ -528,37 +557,18 @@ export function validateCookedMaterialRecord(
       receiptResult.value.derivedInterface.layerPlanIdentity,
     );
   }
-  if (candidate.artifactDigest !== undefined && candidate.artifactDigest !== artifact.digest)
+  if (candidate.artifactDigest !== undefined && candidate.artifactDigest !== manifestDigest)
     return invalid('artifactDigest', candidate.artifactDigest);
   if (
     candidate.publicationGeneration !== undefined &&
     receiptResult.value.identity.cookGeneration !== candidate.publicationGeneration
   )
     return invalid('receipt.identity.cookGeneration', receiptResult.value.identity.cookGeneration);
-  const normalized = {
+  return ok({
     ...candidate,
-    artifact: {
-      ...artifact,
-      bytes: normalizeArtifactBytes(artifact.bytes) as Uint8Array,
-    },
-    ...(Array.isArray(candidate.variants)
-      ? {
-          variants: candidate.variants.map((value) => {
-            const variant = value as Record<string, unknown>;
-            const variantArtifact = variant.artifact as Record<string, unknown>;
-            return {
-              ...variant,
-              artifact: {
-                ...variantArtifact,
-                bytes: normalizeArtifactBytes(variantArtifact.bytes) as Uint8Array,
-              },
-            };
-          }),
-        }
-      : {}),
+    programs,
     receipt: receiptResult.value,
-  } as unknown as CookedMaterialRecord;
-  return ok(normalized);
+  } as unknown as CookedMaterialRecord);
 }
 
 export function projectCookedMaterialRecord(
@@ -567,10 +577,65 @@ export function projectCookedMaterialRecord(
   return {
     resolved: record.resolved,
     refs: record.refs,
-    artifact: record.artifact,
-    ...(record.variantContext === undefined ? {} : { variantContext: record.variantContext }),
-    ...(record.variants === undefined ? {} : { variants: record.variants }),
+    programs: record.programs,
     receipt: record.receipt,
     schemaVersion: record.schemaVersion,
   };
 }
+
+/** Canonical context key shared by publication validation and runtime selection. */
+export function materialProgramContextKey(context: MaterialCookProgramContext): string {
+  return JSON.stringify(jsonValue(context));
+}
+
+export function validateMaterialCookProgramContext(
+  value: unknown,
+): Result<MaterialCookProgramContext, MaterialCookRecordError> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    return invalid('context', value);
+  const context = value as Record<string, unknown>;
+  const fields = {
+    backend: ['webgpu', 'webgl2', 'wgpu-native'],
+    capability: ['storage-buffer', 'uniform-fallback'],
+    pipeline: ['forward', 'deferred'],
+    geometry: ['mesh', 'skinned', 'sprite'],
+    pass: ['forward', 'shadow', 'depth'],
+    profile: ['forgeax-material-wgsl-v1'],
+    toolchain: ['naga-oil'],
+    instrumentation: ['none', 'validation'],
+  };
+  for (const field of Object.keys(context)) {
+    if (!(field in fields)) return invalid(`context.${field}`, context[field]);
+  }
+  for (const [field, allowed] of Object.entries(fields)) {
+    if (!allowed.includes(context[field] as string))
+      return invalid(`context.${field}`, context[field]);
+  }
+  return ok({ ...context } as unknown as MaterialCookProgramContext);
+}
+
+/** Covers every selection and artifact while excluding transport copies of the bytes. */
+export function createMaterialProgramSetDigest(
+  programs: readonly MaterialCookProgram[],
+  passes: readonly MaterialPass[],
+): string {
+  const manifest = {
+    passes,
+    programs: programs
+      .map((program) => ({
+        specializationKey: program.specializationKey,
+        artifact: {
+          path: program.artifact.path,
+          mediaType: program.artifact.mediaType,
+          digest: program.artifact.digest,
+        },
+        selections: [...program.selections].sort((a, b) =>
+          JSON.stringify(jsonValue(a)).localeCompare(JSON.stringify(jsonValue(b))),
+        ),
+      }))
+      .sort((a, b) => a.specializationKey.localeCompare(b.specializationKey)),
+  };
+  return createMaterialArtifactDigest(
+    new TextEncoder().encode(JSON.stringify(jsonValue(manifest))),
+  );
+}

package/src/index.ts

@@ -7,23 +7,26 @@ export {
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
   createMaterialCookIdentity,
+  createMaterialProgramSetDigest,
   isStandardMaterialRecord,
   isStandardRootModule,
   type MaterialCookArtifact,
   type MaterialCookIdentity,
   type MaterialCookIdentityExpectation,
   type MaterialCookIdentityInput,
+  type MaterialCookProgram,
+  type MaterialCookProgramContext,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
-  type MaterialCookVariant,
-  type MaterialCookVariantContext,
   type MaterialCookWasmProvenance,
   materialLayerPlanIdentity,
+  materialProgramContextKey,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,
   validateCookedMaterialRecord,
+  validateMaterialCookProgramContext,
   validateMaterialCookReceipt,
 } from './evidence/material-cook.js';
 export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';

package/src/material-cook.ts

@@ -3,16 +3,19 @@ export {
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
   createMaterialCookIdentity,
+  createMaterialProgramSetDigest,
   type MaterialCookArtifact,
+  type MaterialCookProgram,
+  type MaterialCookProgramContext,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
-  type MaterialCookVariant,
-  type MaterialCookVariantContext,
   type MaterialCookWasmProvenance,
   materialLayerPlanIdentity,
+  materialProgramContextKey,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,
   validateCookedMaterialRecord,
+  validateMaterialCookProgramContext,
 } from './evidence/material-cook.js';