@forgeax/engine-pack 0.1.6 → 0.1.19

package/src/evidence/material-cook.ts

@@ -25,16 +25,38 @@ export interface MaterialCookArtifact {
   readonly bytes: Uint8Array;
 }
 
+export interface MaterialCookWasmProvenance {
+  readonly sourceContentKey: string;
+  readonly artifactSha256: string;
+  readonly glueSha256: string;
+}
+
+export interface MaterialCookIdentity {
+  readonly materialContractDigest: string;
+  readonly sourceRevision: string;
+  readonly sourceClosureDigest: string;
+  readonly layoutIdentity: string;
+  readonly programIdentity: string;
+  readonly pipelineIdentity: string;
+  readonly materialPublicationIdentity: string;
+  readonly cookIdentity: string;
+  readonly compilerFingerprint: string;
+  readonly wasm: MaterialCookWasmProvenance;
+  readonly artifactDigest: string;
+  readonly valueGeneration: number;
+  readonly dependencyGeneration: number;
+  readonly cookGeneration: number;
+}
+
+export type MaterialCookIdentityInput = Omit<MaterialCookIdentity, 'cookIdentity'>;
+
 export interface MaterialCookReceipt {
-  readonly schemaVersion: 'material-cook/2';
+  readonly schemaVersion: 'material-cook/3';
   readonly sourceClosure: readonly string[];
   readonly profile: string;
   readonly compilerVersion: string;
-  readonly inputDigest: string;
-  readonly outputDigest: string;
-  readonly layoutIdentity: string;
+  readonly identity: MaterialCookIdentity;
   readonly derivedInterface: { readonly layoutIdentity: string };
-  readonly publicationGeneration?: number;
 }
 
 export interface MaterialParameterContract {
@@ -43,7 +65,7 @@ export interface MaterialParameterContract {
 }
 
 export interface CookedMaterialRecord {
-  readonly schemaVersion: 'material-cook/2';
+  readonly schemaVersion: 'material-cook/3';
   readonly guid: string;
   readonly authored?: MaterialAsset;
   readonly materialGuid?: string;
@@ -66,7 +88,11 @@ export interface MaterialCookRecordError {
   readonly code: 'material-cook-record-invalid';
   readonly expected: string;
   readonly hint: string;
-  readonly detail: { readonly field: string };
+  readonly detail: {
+    readonly field: string;
+    readonly actual?: unknown;
+    readonly action: string;
+  };
 }
 
 export interface MaterialCookIdentityExpectation {
@@ -154,6 +180,27 @@ function jsonValue(value: unknown): unknown {
   return value;
 }
 
+export function createMaterialCookIdentity(input: MaterialCookIdentityInput): MaterialCookIdentity {
+  const cookIdentity = createMaterialArtifactDigest(
+    new TextEncoder().encode(
+      JSON.stringify(
+        jsonValue({
+          materialContractDigest: input.materialContractDigest,
+          sourceRevision: input.sourceRevision,
+          sourceClosureDigest: input.sourceClosureDigest,
+          layoutIdentity: input.layoutIdentity,
+          programIdentity: input.programIdentity,
+          pipelineIdentity: input.pipelineIdentity,
+          compilerFingerprint: input.compilerFingerprint,
+          wasm: input.wasm,
+          artifactDigest: input.artifactDigest,
+        }),
+      ),
+    ),
+  );
+  return { ...input, cookIdentity };
+}
+
 export function serializeCookedMaterialRecord(record: CookedMaterialRecord): string {
   return JSON.stringify(jsonValue(record));
 }
@@ -162,83 +209,116 @@ export function serializeMaterialCookReceipt(receipt: MaterialCookReceipt): stri
   return JSON.stringify(jsonValue({ ...receipt, sourceClosure: unique(receipt.sourceClosure) }));
 }
 
-function invalid(field: string): Result<never, MaterialCookRecordError> {
+function invalid(field: string, actual?: unknown): Result<never, MaterialCookRecordError> {
   return err({
     code: 'material-cook-record-invalid',
-    expected: 'a complete material-cook/2 record with derived layout identity',
+    expected: 'a complete material-cook/3 record with layered identity and provenance',
     hint: 're-cook the material and publish its record, artifact, references, and receipt together',
-    detail: { field },
+    detail: {
+      field,
+      ...(actual === undefined ? {} : { actual }),
+      action: 'inspect the named field and recook the material generation',
+    },
   });
 }
 
+const IDENTITY_FIELDS = [
+  'materialContractDigest',
+  'sourceRevision',
+  'sourceClosureDigest',
+  'layoutIdentity',
+  'programIdentity',
+  'pipelineIdentity',
+  'materialPublicationIdentity',
+  'cookIdentity',
+  'compilerFingerprint',
+  'artifactDigest',
+] as const;
+
+function isGeneration(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
+}
+
+function validateIdentity(value: unknown): Result<MaterialCookIdentity, MaterialCookRecordError> {
+  if (value === null || typeof value !== 'object') return invalid('receipt.identity', value);
+  const candidate = value as Record<string, unknown>;
+  for (const field of IDENTITY_FIELDS) {
+    if (typeof candidate[field] !== 'string' || candidate[field].length === 0) {
+      return invalid(`receipt.identity.${field}`, candidate[field]);
+    }
+  }
+  if (candidate.wasm === null || typeof candidate.wasm !== 'object') {
+    return invalid('receipt.identity.wasm', candidate.wasm);
+  }
+  const wasm = candidate.wasm as Record<string, unknown>;
+  for (const field of ['sourceContentKey', 'artifactSha256', 'glueSha256']) {
+    if (typeof wasm[field] !== 'string' || wasm[field].length === 0) {
+      return invalid(`receipt.identity.wasm.${field}`, wasm[field]);
+    }
+  }
+  for (const field of ['valueGeneration', 'dependencyGeneration', 'cookGeneration']) {
+    if (!isGeneration(candidate[field]))
+      return invalid(`receipt.identity.${field}`, candidate[field]);
+  }
+  return ok({
+    ...candidate,
+    wasm: wasm as unknown as MaterialCookWasmProvenance,
+  } as MaterialCookIdentity);
+}
+
 export function validateMaterialCookReceipt(
   value: unknown,
   expected: MaterialCookIdentityExpectation = {},
 ): Result<MaterialCookReceipt, MaterialCookRecordError> {
   if (value === null || typeof value !== 'object') return invalid('receipt');
   const candidate = value as Record<string, unknown>;
-  if (candidate.schemaVersion !== 'material-cook/2') return invalid('receipt.schemaVersion');
-  if (typeof candidate.layoutIdentity !== 'string' || candidate.layoutIdentity.length === 0) {
-    return invalid('receipt.layoutIdentity');
-  }
+  if (candidate.schemaVersion !== 'material-cook/3')
+    return invalid('receipt.schemaVersion', candidate.schemaVersion);
+  const identityResult = validateIdentity(candidate.identity);
+  if (!identityResult.ok) return identityResult;
+  const identity = identityResult.value;
   if (candidate.derivedInterface === null || typeof candidate.derivedInterface !== 'object') {
-    return invalid('receipt.derivedInterface');
+    return invalid('receipt.derivedInterface', candidate.derivedInterface);
   }
   const derivedInterface = candidate.derivedInterface as Record<string, unknown>;
-  if (derivedInterface.layoutIdentity !== candidate.layoutIdentity) {
-    return invalid('receipt.derivedInterface.layoutIdentity');
+  if (derivedInterface.layoutIdentity !== identity.layoutIdentity) {
+    return invalid('receipt.derivedInterface.layoutIdentity', derivedInterface.layoutIdentity);
   }
-  for (const field of [
-    'sourceClosure',
-    'profile',
-    'compilerVersion',
-    'inputDigest',
-    'outputDigest',
-  ]) {
+  for (const field of ['sourceClosure', 'profile', 'compilerVersion']) {
     const fieldValue = candidate[field];
     if (
       (field === 'sourceClosure' && !Array.isArray(fieldValue)) ||
       (field !== 'sourceClosure' && typeof fieldValue !== 'string')
     ) {
-      return invalid(`receipt.${field}`);
+      return invalid(`receipt.${field}`, fieldValue);
     }
   }
   const sourceClosure = candidate.sourceClosure;
   if (Array.isArray(sourceClosure) && sourceClosure.some((path) => typeof path !== 'string')) {
-    return invalid('receipt.sourceClosure');
+    return invalid('receipt.sourceClosure', sourceClosure);
   }
   if (
     expected.layoutIdentity !== undefined &&
-    candidate.layoutIdentity !== expected.layoutIdentity
+    identity.layoutIdentity !== expected.layoutIdentity
   ) {
-    return invalid('receipt.layoutIdentity');
-  }
-  if (expected.artifactDigest !== undefined && candidate.outputDigest !== expected.artifactDigest) {
-    return invalid('receipt.outputDigest');
-  }
-  if (expected.inputDigest !== undefined && candidate.inputDigest !== expected.inputDigest) {
-    return invalid('receipt.inputDigest');
+    return invalid('receipt.identity.layoutIdentity', identity.layoutIdentity);
   }
   if (
-    candidate.publicationGeneration !== undefined &&
-    (typeof candidate.publicationGeneration !== 'number' ||
-      !Number.isSafeInteger(candidate.publicationGeneration) ||
-      candidate.publicationGeneration < 1)
+    expected.artifactDigest !== undefined &&
+    identity.artifactDigest !== expected.artifactDigest
   ) {
-    return invalid('receipt.publicationGeneration');
+    return invalid('receipt.identity.artifactDigest', identity.artifactDigest);
+  }
+  if (expected.inputDigest !== undefined && identity.cookIdentity !== expected.inputDigest) {
+    return invalid('receipt.identity.cookIdentity', identity.cookIdentity);
   }
   return ok({
-    schemaVersion: 'material-cook/2',
+    schemaVersion: 'material-cook/3',
     sourceClosure: candidate.sourceClosure as string[],
     profile: candidate.profile as string,
     compilerVersion: candidate.compilerVersion as string,
-    inputDigest: candidate.inputDigest as string,
-    outputDigest: candidate.outputDigest as string,
-    layoutIdentity: candidate.layoutIdentity,
+    identity,
     derivedInterface: { layoutIdentity: derivedInterface.layoutIdentity as string },
-    ...(candidate.publicationGeneration === undefined
-      ? {}
-      : { publicationGeneration: candidate.publicationGeneration as number }),
   });
 }
 
@@ -247,17 +327,16 @@ 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/2') return invalid('schemaVersion');
+  if (candidate.schemaVersion !== 'material-cook/3')
+    return invalid('schemaVersion', candidate.schemaVersion);
   if (typeof candidate.guid !== 'string' || !candidate.guid) return invalid('guid');
   if (candidate.materialGuid !== undefined && typeof candidate.materialGuid !== 'string')
     return invalid('materialGuid');
   if (
     candidate.publicationGeneration !== undefined &&
-    (typeof candidate.publicationGeneration !== 'number' ||
-      !Number.isSafeInteger(candidate.publicationGeneration) ||
-      candidate.publicationGeneration < 1)
+    !isGeneration(candidate.publicationGeneration)
   )
-    return invalid('publicationGeneration');
+    return invalid('publicationGeneration', candidate.publicationGeneration);
   if (candidate.specializationKey !== undefined && typeof candidate.specializationKey !== 'string')
     return invalid('specializationKey');
   if (candidate.artifactDigest !== undefined && typeof candidate.artifactDigest !== 'string')
@@ -300,12 +379,12 @@ export function validateCookedMaterialRecord(
   });
   if (!receiptResult.ok) return receiptResult;
   if (candidate.artifactDigest !== undefined && candidate.artifactDigest !== artifact.digest)
-    return invalid('artifactDigest');
+    return invalid('artifactDigest', candidate.artifactDigest);
   if (
     candidate.publicationGeneration !== undefined &&
-    receiptResult.value.publicationGeneration !== candidate.publicationGeneration
+    receiptResult.value.identity.cookGeneration !== candidate.publicationGeneration
   )
-    return invalid('receipt.publicationGeneration');
+    return invalid('receipt.identity.cookGeneration', receiptResult.value.identity.cookGeneration);
   const normalized = {
     ...candidate,
     artifact: {

package/src/index.ts

@@ -6,11 +6,15 @@ export {
   type CookedMaterialRecord,
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
+  createMaterialCookIdentity,
   type MaterialCookArtifact,
+  type MaterialCookIdentity,
   type MaterialCookIdentityExpectation,
+  type MaterialCookIdentityInput,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
+  type MaterialCookWasmProvenance,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,

package/src/material-cook.ts

@@ -2,10 +2,12 @@ export {
   type CookedMaterialRecord,
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
+  createMaterialCookIdentity,
   type MaterialCookArtifact,
   type MaterialCookReceipt,
   type MaterialCookRecordError,
   type MaterialCookRefs,
+  type MaterialCookWasmProvenance,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,

package/src/schema/material-cook.schema.json

@@ -4,7 +4,7 @@
   "type": "object",
   "required": ["schemaVersion", "guid", "resolved", "refs", "artifact", "receipt"],
   "properties": {
-    "schemaVersion": { "const": "material-cook/2" },
+    "schemaVersion": { "const": "material-cook/3" },
     "guid": { "type": "string", "minLength": 1 },
     "materialGuid": { "type": "string", "minLength": 1 },
     "publicationGeneration": { "type": "integer", "minimum": 1 },
@@ -51,19 +51,59 @@
         "sourceClosure",
         "profile",
         "compilerVersion",
-        "inputDigest",
-        "outputDigest",
-        "layoutIdentity",
+        "identity",
         "derivedInterface"
       ],
       "properties": {
-        "schemaVersion": { "const": "material-cook/2" },
+        "schemaVersion": { "const": "material-cook/3" },
         "sourceClosure": { "type": "array", "items": { "type": "string" } },
         "profile": { "type": "string" },
         "compilerVersion": { "type": "string" },
-        "inputDigest": { "type": "string" },
-        "outputDigest": { "type": "string" },
-        "layoutIdentity": { "type": "string", "minLength": 1 },
+        "identity": {
+          "type": "object",
+          "required": [
+            "materialContractDigest",
+            "sourceRevision",
+            "sourceClosureDigest",
+            "layoutIdentity",
+            "programIdentity",
+            "pipelineIdentity",
+            "materialPublicationIdentity",
+            "cookIdentity",
+            "compilerFingerprint",
+            "wasm",
+            "artifactDigest",
+            "valueGeneration",
+            "dependencyGeneration",
+            "cookGeneration"
+          ],
+          "properties": {
+            "materialContractDigest": { "type": "string", "minLength": 1 },
+            "sourceRevision": { "type": "string", "minLength": 1 },
+            "sourceClosureDigest": { "type": "string", "minLength": 1 },
+            "layoutIdentity": { "type": "string", "minLength": 1 },
+            "programIdentity": { "type": "string", "minLength": 1 },
+            "pipelineIdentity": { "type": "string", "minLength": 1 },
+            "materialPublicationIdentity": { "type": "string", "minLength": 1 },
+            "cookIdentity": { "type": "string", "minLength": 1 },
+            "compilerFingerprint": { "type": "string", "minLength": 1 },
+            "wasm": {
+              "type": "object",
+              "required": ["sourceContentKey", "artifactSha256", "glueSha256"],
+              "properties": {
+                "sourceContentKey": { "type": "string", "minLength": 1 },
+                "artifactSha256": { "type": "string", "minLength": 1 },
+                "glueSha256": { "type": "string", "minLength": 1 }
+              },
+              "additionalProperties": false
+            },
+            "artifactDigest": { "type": "string", "minLength": 1 },
+            "valueGeneration": { "type": "integer", "minimum": 1 },
+            "dependencyGeneration": { "type": "integer", "minimum": 1 },
+            "cookGeneration": { "type": "integer", "minimum": 1 }
+          },
+          "additionalProperties": false
+        },
         "derivedInterface": {
           "type": "object",
           "required": ["layoutIdentity"],

package/src/scriptable-pack-node.ts

@@ -670,7 +670,10 @@ export async function loadScriptablePack(
   sourcePath: string,
   options: LoadScriptablePackOptions = {},
 ): Promise<Result<Readonly<ScriptablePackDefinition>, ScriptablePackError>> {
-  const timeoutMs = options.timeoutMs ?? 5_000;
+  // Module initialization includes transpiling the trusted TypeScript source
+  // closure in a fresh Worker. A cold SDK workspace can legitimately exceed
+  // the build execution budget before any authored build() code has run.
+  const timeoutMs = options.timeoutMs ?? 15_000;
   const buildTimeoutMs = options.buildTimeoutMs ?? 5_000;
   const executor = options.executor ?? new WorkerScriptablePackExecutor();
   let disposeReason: 'complete' | 'timeout' | 'failure' | undefined;