@forgeax/engine-pack 0.1.24 → 0.1.26

package/src/evidence/material-cook.ts

@@ -25,6 +25,28 @@ export interface MaterialCookArtifact {
   readonly bytes: Uint8Array;
 }
 
+/** 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';
+}
+
+/** 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 {
   readonly sourceContentKey: string;
   readonly artifactSha256: string;
@@ -51,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;
@@ -69,12 +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;
+  readonly programs: readonly MaterialCookProgram[];
+  /** Digest of the complete program/Pass/context manifest. */
   readonly artifactDigest?: string;
   readonly sourceClosure?: readonly string[];
   readonly parameterContract?: MaterialParameterContract;
@@ -84,7 +108,6 @@ export interface CookedMaterialRecord {
     readonly values: Readonly<Record<string, MaterialValue | null>>;
   };
   readonly refs: MaterialCookRefs;
-  readonly artifact: MaterialCookArtifact;
   readonly receipt: MaterialCookReceipt;
 }
 
@@ -248,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,
@@ -258,6 +281,17 @@ function invalid(field: string, actual?: unknown): Result<never, MaterialCookRec
   });
 }
 
+function normalizeArtifactBytes(value: unknown): Uint8Array | undefined {
+  if (Array.isArray(value)) {
+    return value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255)
+      ? Uint8Array.from(value)
+      : undefined;
+  }
+  if (!ArrayBuffer.isView(value)) return undefined;
+  const view = value as ArrayBufferView;
+  return new Uint8Array(view.buffer, view.byteOffset, view.byteLength).slice();
+}
+
 const IDENTITY_FIELDS = [
   'materialContractDigest',
   'sourceRevision',
@@ -308,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;
@@ -359,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,
@@ -378,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')
@@ -390,6 +424,8 @@ export function validateCookedMaterialRecord(
     return invalid('publicationGeneration', candidate.publicationGeneration);
   if (candidate.specializationKey !== undefined && typeof candidate.specializationKey !== 'string')
     return invalid('specializationKey');
+  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 (
@@ -414,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))
@@ -439,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({
@@ -456,24 +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: ArrayBuffer.isView(artifact.bytes)
-        ? Uint8Array.from(artifact.bytes as Uint8Array)
-        : Uint8Array.from(artifact.bytes as number[]),
-    },
+    programs,
     receipt: receiptResult.value,
-  } as CookedMaterialRecord;
-  return ok(normalized);
+  } as unknown as CookedMaterialRecord);
 }
 
 export function projectCookedMaterialRecord(
@@ -482,8 +577,65 @@ export function projectCookedMaterialRecord(
   return {
     resolved: record.resolved,
     refs: record.refs,
-    artifact: record.artifact,
+    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,21 +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 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,14 +3,19 @@ export {
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
   createMaterialCookIdentity,
+  createMaterialProgramSetDigest,
   type MaterialCookArtifact,
+  type MaterialCookProgram,
+  type MaterialCookProgramContext,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
   type MaterialCookWasmProvenance,
   materialLayerPlanIdentity,
+  materialProgramContextKey,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,
   validateCookedMaterialRecord,
+  validateMaterialCookProgramContext,
 } from './evidence/material-cook.js';

package/src/scanner.ts

@@ -62,9 +62,13 @@ export interface ScriptablePackScanOptions {
 }
 
 /** Stable default policy shared by inventory and production owners. */
-export const STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS = Object.freeze(
-  {},
-) satisfies ScriptablePackScanOptions;
+export const STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS = Object.freeze({
+  // Scriptable Packs execute in an isolated worker.  A cold worker must
+  // compile the authored source closure before it can return metadata;
+  // heavy procedural packs otherwise make the shared catalog fall back to
+  // an empty degraded projection at the old 15-second budget.
+  timeoutMs: 60_000,
+}) satisfies ScriptablePackScanOptions;
 
 export interface InventoryDeclaration {
   readonly guid: string;