@forgeax/engine-pack 0.1.23 → 0.1.25

package/src/evidence/material-cook.ts

@@ -7,7 +7,7 @@ import type {
   MaterialValue,
   Result,
 } from '@forgeax/engine-types';
-import { err, MATERIAL_TEXTURE_SLOTS, ok } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan, err, MATERIAL_TEXTURE_SLOTS, ok } from '@forgeax/engine-types';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { bytesToHex } from '@noble/hashes/utils.js';
 
@@ -25,6 +25,19 @@ export interface MaterialCookArtifact {
   readonly bytes: Uint8Array;
 }
 
+/** Backend capability projection for one immutable cooked material artifact. */
+export interface MaterialCookVariantContext {
+  readonly backend: 'webgpu' | 'webgl2' | 'wgpu-native';
+  readonly capability: 'storage-buffer' | 'uniform-fallback';
+}
+
+/** Additional backend artifact published with one material generation. */
+export interface MaterialCookVariant {
+  readonly context: MaterialCookVariantContext;
+  readonly specializationKey: string;
+  readonly artifact: MaterialCookArtifact;
+}
+
 export interface MaterialCookWasmProvenance {
   readonly sourceContentKey: string;
   readonly artifactSha256: string;
@@ -56,7 +69,11 @@ export interface MaterialCookReceipt {
   readonly profile: string;
   readonly compilerVersion: string;
   readonly identity: MaterialCookIdentity;
-  readonly derivedInterface: { readonly layoutIdentity: string };
+  readonly derivedInterface: {
+    readonly layoutIdentity: string;
+    /** Build-time Standard physical lowering identity, when the root is Standard. */
+    readonly layerPlanIdentity?: string;
+  };
 }
 
 export interface MaterialParameterContract {
@@ -71,6 +88,10 @@ export interface CookedMaterialRecord {
   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 artifactDigest?: string;
   readonly sourceClosure?: readonly string[];
   readonly parameterContract?: MaterialParameterContract;
@@ -101,6 +122,37 @@ export interface MaterialCookIdentityExpectation {
   readonly inputDigest?: string;
 }
 
+const STANDARD_ROOT_MODULES = new Set([
+  'forgeax::default-standard-pbr',
+  'forgeax::pbr-skin',
+  'forgeax_material::standard',
+  'forgeax_material::pbr-skin',
+  'forgeax::default-shadow-caster',
+]);
+
+/** Shared ownership predicate for the built-in Standard material root. */
+export function isStandardRootModule(module: string): boolean {
+  return STANDARD_ROOT_MODULES.has(module);
+}
+
+export function isStandardMaterialRecord(record: Pick<CookedMaterialRecord, 'resolved'>): boolean {
+  return record.resolved.passes.some((pass) => isStandardRootModule(pass.program.module));
+}
+
+/**
+ * Recompute the Standard layer identity from the admitted resolved root.
+ * Material admission and runtime loading share this owner so a stale receipt
+ * cannot select a different physical layer plan after cooking.
+ */
+export function materialLayerPlanIdentity(
+  record: Pick<CookedMaterialRecord, 'resolved'>,
+): string | undefined {
+  if (!isStandardMaterialRecord(record)) {
+    return undefined;
+  }
+  return deriveStandardLayerPlan(record.resolved.parameters, record.resolved.passes).identity;
+}
+
 function unique(values: readonly string[]): readonly string[] {
   return [...new Set(values)].sort();
 }
@@ -224,6 +276,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',
@@ -286,6 +349,16 @@ export function validateMaterialCookReceipt(
   if (derivedInterface.layoutIdentity !== identity.layoutIdentity) {
     return invalid('receipt.derivedInterface.layoutIdentity', derivedInterface.layoutIdentity);
   }
+  if (
+    derivedInterface.layerPlanIdentity !== undefined &&
+    (typeof derivedInterface.layerPlanIdentity !== 'string' ||
+      derivedInterface.layerPlanIdentity.length === 0)
+  ) {
+    return invalid(
+      'receipt.derivedInterface.layerPlanIdentity',
+      derivedInterface.layerPlanIdentity,
+    );
+  }
   for (const field of ['sourceClosure', 'profile', 'compilerVersion']) {
     const fieldValue = candidate[field];
     if (
@@ -320,7 +393,12 @@ export function validateMaterialCookReceipt(
     profile: candidate.profile as string,
     compilerVersion: candidate.compilerVersion as string,
     identity,
-    derivedInterface: { layoutIdentity: derivedInterface.layoutIdentity as string },
+    derivedInterface: {
+      layoutIdentity: derivedInterface.layoutIdentity as string,
+      ...(derivedInterface.layerPlanIdentity === undefined
+        ? {}
+        : { layerPlanIdentity: derivedInterface.layerPlanIdentity as string }),
+    },
   });
 }
 
@@ -341,6 +419,49 @@ 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 (candidate.artifactDigest !== undefined && typeof candidate.artifactDigest !== 'string')
     return invalid('artifactDigest');
   if (
@@ -380,6 +501,33 @@ export function validateCookedMaterialRecord(
     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))
+    return invalid('resolved.parameters', resolved.parameters);
+  if (
+    resolved.values === null ||
+    typeof resolved.values !== 'object' ||
+    Array.isArray(resolved.values)
+  )
+    return invalid('resolved.values', resolved.values);
+  let expectedLayerPlanIdentity: string | undefined;
+  try {
+    expectedLayerPlanIdentity = materialLayerPlanIdentity({
+      resolved: resolved as unknown as CookedMaterialRecord['resolved'],
+    });
+  } catch (error) {
+    return invalid('resolved.layerPlanIdentity', error instanceof Error ? error.message : error);
+  }
+  if (
+    expectedLayerPlanIdentity !== undefined &&
+    receiptResult.value.derivedInterface.layerPlanIdentity !== expectedLayerPlanIdentity
+  ) {
+    return invalid(
+      'receipt.derivedInterface.layerPlanIdentity',
+      receiptResult.value.derivedInterface.layerPlanIdentity,
+    );
+  }
   if (candidate.artifactDigest !== undefined && candidate.artifactDigest !== artifact.digest)
     return invalid('artifactDigest', candidate.artifactDigest);
   if (
@@ -391,12 +539,25 @@ export function validateCookedMaterialRecord(
     ...candidate,
     artifact: {
       ...artifact,
-      bytes: ArrayBuffer.isView(artifact.bytes)
-        ? Uint8Array.from(artifact.bytes as Uint8Array)
-        : Uint8Array.from(artifact.bytes as number[]),
+      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,
+              },
+            };
+          }),
+        }
+      : {}),
     receipt: receiptResult.value,
-  } as CookedMaterialRecord;
+  } as unknown as CookedMaterialRecord;
   return ok(normalized);
 }
 
@@ -407,6 +568,8 @@ export function projectCookedMaterialRecord(
     resolved: record.resolved,
     refs: record.refs,
     artifact: record.artifact,
+    ...(record.variantContext === undefined ? {} : { variantContext: record.variantContext }),
+    ...(record.variants === undefined ? {} : { variants: record.variants }),
     receipt: record.receipt,
     schemaVersion: record.schemaVersion,
   };

package/src/evidence/source-inventory.ts

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import type { SourceDeclarationEvidence } from '@forgeax/engine-types';
-import { parseParameterizedPackJson, projectDirectPackJson } from '../parameterized-pack.js';
+import { parsePackSourceJson, projectDirectPackJson } from '../pack-authoring.js';
 import { SCANNER_BLACKLIST, scan } from '../scanner.js';
 
 /** Project root and GUID used to locate an authoritative source declaration. */
@@ -149,7 +149,7 @@ export async function readSourceInventory(
   let authored: SourceDeclarationEvidence | undefined;
   for (const path of paths) {
     if (path.endsWith('.pack.ts')) {
-      // Parameterized source identity is a build result, not a declaration
+      // ScriptablePack source identity is a build result, not a declaration
       // table. The source index therefore records the source only after the
       // producer publishes its materialized Pack output.
       continue;
@@ -166,7 +166,7 @@ export async function readSourceInventory(
     }
     if (path.endsWith('.pack.json')) {
       if (parsed.schemaVersion === '3.0.0') {
-        const direct = parseParameterizedPackJson(parsed);
+        const direct = parsePackSourceJson(parsed);
         if (direct.ok && direct.value.format === 'direct') {
           const projected = projectDirectPackJson(direct.value);
           if (

package/src/index.ts

@@ -7,6 +7,8 @@ export {
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
   createMaterialCookIdentity,
+  isStandardMaterialRecord,
+  isStandardRootModule,
   type MaterialCookArtifact,
   type MaterialCookIdentity,
   type MaterialCookIdentityExpectation,
@@ -14,7 +16,10 @@ export {
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
+  type MaterialCookVariant,
+  type MaterialCookVariantContext,
   type MaterialCookWasmProvenance,
+  materialLayerPlanIdentity,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,
@@ -40,7 +45,7 @@ export {
   type MeshBinHeaderV4,
   writeMeshBinHeader,
 } from './mesh-bin-contract.js';
-export * from './parameterized-pack.js';
+export * from './pack-authoring.js';
 export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 export {
   type AssetReader,

package/src/material-cook.ts

@@ -7,7 +7,10 @@ export {
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
+  type MaterialCookVariant,
+  type MaterialCookVariantContext,
   type MaterialCookWasmProvenance,
+  materialLayerPlanIdentity,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,