ai-workflow-logic 0.2.0 → 0.2.2

package/src/run-checkpoint.ts

@@ -92,6 +92,15 @@ export function normalizeFlowRunCheckpoint(value: unknown): AIWorkflowFlowRunChe
     ? normalizeRunStepExtensions(dataField(record, 'stepExtensions', 'checkpoint.stepExtensions'))
     : undefined;
   const profile = normalizeProfile(dataField(record, 'profile', 'checkpoint.profile'), runId);
+  if (profile.kind !== 'WorkCtrlFlow') {
+    for (const [key, record] of Object.entries(profile.ai.delegationsByKey ?? {})) {
+      for (const attempt of record.attempts) {
+        if (attempt.request.lineage.instanceId !== instanceId || attempt.request.lineage.runId !== runId) {
+          invalid('DELEGATION_CHECKPOINT_SCOPE_MISMATCH', `checkpoint.profile.ai.delegationsByKey.${key}`, 'Delegation lineage must belong to the canonical instance and run.');
+        }
+      }
+    }
+  }
   validateProfileProjection(profile, { input, state, output, controllerSidecars, nodeSidecars });
   return Object.freeze({
     schemaVersion,
@@ -471,7 +480,7 @@ function normalizeWorkCtrlNestedFacts(snapshot: Record<string, unknown>, locatio
     if (kind === 'Branch' && !hasBranchKey) invalid('WORK_CTRL_BRANCH_KEY_MISSING', `${factLocation}.branchKey`, 'Branch decisions require a branch key.');
     if (hasBranchKey) {
       canonicalIdentity(dataField(fact, 'branchKey', `${factLocation}.branchKey`), `${factLocation}.branchKey`);
-      if (kind !== 'Branch') invalid('WORK_CTRL_BRANCH_KEY_INVALID', `${factLocation}.branchKey`, 'Only Branch decisions can retain a branch key.');
+      if (kind === 'NoMatch') invalid('WORK_CTRL_BRANCH_KEY_INVALID', `${factLocation}.branchKey`, 'NoMatch decisions cannot retain a branch key.');
     }
   }
 
@@ -501,7 +510,7 @@ function normalizeWorkCtrlNestedFacts(snapshot: Record<string, unknown>, locatio
   normalizeWorkCtrlAttempts(dataField(orchestration, 'attempts', `${orchestrationLocation}.attempts`), `${orchestrationLocation}.attempts`);
   normalizeWorkCtrlDeadlines(dataField(orchestration, 'deadlines', `${orchestrationLocation}.deadlines`), `${orchestrationLocation}.deadlines`);
   const lanes = normalizeWorkCtrlLanes(dataField(orchestration, 'lanes', `${orchestrationLocation}.lanes`), `${orchestrationLocation}.lanes`);
-  normalizeWorkCtrlComposites(dataField(orchestration, 'composites', `${orchestrationLocation}.composites`), `${orchestrationLocation}.composites`);
+  normalizeWorkCtrlComposites(dataField(orchestration, 'composites', `${orchestrationLocation}.composites`), `${orchestrationLocation}.composites`, lanes);
   normalizeWorkCtrlWinners(dataField(orchestration, 'winners', `${orchestrationLocation}.winners`), lanes, `${orchestrationLocation}.winners`);
   normalizeWorkCtrlCancellations(dataField(orchestration, 'cancellations', `${orchestrationLocation}.cancellations`), `${orchestrationLocation}.cancellations`);
 }
@@ -542,7 +551,8 @@ function normalizeWorkCtrlDeadlines(value: unknown, location: string): void {
 function normalizeWorkCtrlLanes(value: unknown, location: string): Map<string, { invocationKey: string; laneId: string; status: string }> {
   const output = new Map<string, { invocationKey: string; laneId: string; status: string }>();
   for (const [key, item, itemLocation] of closedRecordEntries(value, location)) {
-    const fact = exactRecord(item, ['invocationKey', 'laneId', 'status', 'bodyId'], ['item', 'flowState', 'output'], itemLocation);
+    const fact = exactRecord(item, ['invocationKey', 'laneId', 'status', 'bodyId'], ['item', 'flowState', 'output', 'started'], itemLocation);
+    if (Object.hasOwn(fact, 'started') && typeof dataField(fact, 'started', `${itemLocation}.started`) !== 'boolean') invalid('WORK_CTRL_LANE_STARTED_INVALID', `${itemLocation}.started`, 'Lane slot claim must be boolean.');
     const invocationKey = canonicalIdentity(dataField(fact, 'invocationKey', `${itemLocation}.invocationKey`), `${itemLocation}.invocationKey`);
     const laneId = canonicalIdentity(dataField(fact, 'laneId', `${itemLocation}.laneId`), `${itemLocation}.laneId`);
     if (key !== `${invocationKey}/${laneId}`) invalid('WORK_CTRL_LANE_IDENTITY_MISMATCH', itemLocation, 'Lane map key must equal invocationKey/laneId.');
@@ -583,12 +593,22 @@ function normalizeWorkCtrlCancellations(value: unknown, location: string): void
   }
 }
 
-function normalizeWorkCtrlComposites(value: unknown, location: string): void {
+function normalizeWorkCtrlComposites(value: unknown, location: string, lanes: Map<string, { invocationKey: string; laneId: string; status: string }>): void {
   for (const [key, item, itemLocation] of closedRecordEntries(value, location)) {
-    const fact = exactRecord(item, ['invocationKey', 'primitive', 'bodyId', 'status', 'updatedAtMs'], ['input', 'cursor', 'childTreeId'], itemLocation);
+    const fact = exactRecord(item, ['invocationKey', 'primitive', 'bodyId', 'status', 'updatedAtMs'], ['input', 'cursor', 'childTreeId', 'expansion'], itemLocation);
     assertFactKey(fact, key, itemLocation);
     const primitive = dataField(fact, 'primitive', `${itemLocation}.primitive`);
     if (!['Retry', 'Timeout', 'ForEach', 'Parallel', 'Race', 'CallFlow'].includes(String(primitive))) invalid('WORK_CTRL_COMPOSITE_PRIMITIVE_INVALID', `${itemLocation}.primitive`, 'Composite primitive is invalid.');
+    if (Object.hasOwn(fact, 'expansion')) {
+      const location = `${itemLocation}.expansion`;
+      const expansion = exactRecord(dataField(fact, 'expansion', location), ['itemCount', 'concurrency'], ['maxItems'], location);
+      const itemCount = nonNegativeSafeInteger(dataField(expansion, 'itemCount', `${location}.itemCount`), `${location}.itemCount`);
+      const concurrency = nonNegativeSafeInteger(dataField(expansion, 'concurrency', `${location}.concurrency`), `${location}.concurrency`);
+      const maxItems = Object.hasOwn(expansion, 'maxItems') ? nonNegativeSafeInteger(dataField(expansion, 'maxItems', `${location}.maxItems`), `${location}.maxItems`) : undefined;
+      if (primitive !== 'ForEach' || concurrency < 1 || concurrency > Math.min(32, maxItems ?? 1000) || (maxItems !== undefined && (maxItems < 1 || maxItems > 1000 || itemCount > maxItems))) invalid('WORK_CTRL_EXPANSION_INVALID', location, 'Frozen ForEach expansion exceeds its budget.');
+      const expanded = [...lanes.values()].filter(lane => lane.invocationKey === key);
+      if (expanded.length !== itemCount || Array.from({ length: itemCount }, (_, index) => `${key}/${index}`).some(id => !lanes.has(id))) invalid('WORK_CTRL_EXPANSION_INCOMPLETE', location, 'Frozen ForEach lanes must cover the exact input order.');
+    }
     canonicalIdentity(dataField(fact, 'bodyId', `${itemLocation}.bodyId`), `${itemLocation}.bodyId`);
     if (!['Open', 'Waiting', 'Completed', 'Failed', 'Cancelled'].includes(String(dataField(fact, 'status', `${itemLocation}.status`)))) invalid('WORK_CTRL_COMPOSITE_STATUS_INVALID', `${itemLocation}.status`, 'Composite status is invalid.');
     nonNegativeSafeInteger(dataField(fact, 'updatedAtMs', `${itemLocation}.updatedAtMs`), `${itemLocation}.updatedAtMs`);
@@ -1412,7 +1432,7 @@ function normalizeAIDataNodeResult(
   const result = exactRecord(
     value,
     ['nodeId', 'generation', 'status'],
-    ['output', 'semanticFingerprint', 'reusedFrom'],
+    ['output', 'semanticFingerprint', 'reusedFrom', 'waitContext'],
     location,
   );
   if (canonicalIdentity(dataField(result, 'nodeId', `${location}.nodeId`), `${location}.nodeId`) !== nodeId) {
@@ -1422,6 +1442,10 @@ function normalizeAIDataNodeResult(
     invalid('AI_DATA_RESULT_GENERATION_INVALID', `${location}.generation`, 'Result generation must equal its run node generation.');
   }
   const resultStatus = String(dataField(result, 'status', `${location}.status`));
+  if(Object.hasOwn(result,'waitContext')){
+    const context=normalizeFlowClosedObject(dataField(result,'waitContext',`${location}.waitContext`),`${location}.waitContext`);
+    if(new TextEncoder().encode(JSON.stringify(context)).length>16384)invalid('AI_DATA_WAIT_CONTEXT_BUDGET',`${location}.waitContext`,'Native wait context exceeds 16KiB.');
+  }
   if (!['Pending', 'Running', 'Waiting', 'Succeeded', 'Failed', 'Cancelled', 'Invalidated', 'Reused'].includes(resultStatus)) {
     invalid('AI_DATA_RESULT_STATUS_INVALID', `${location}.status`, 'Result status is not part of the public contract.');
   }

package/src/run-freeze.ts

@@ -7,6 +7,8 @@ import type {
   AIWorkflowRunResourceFreezeReceipt,
   MaterialBindingProjection,
   MaterialPortProjection,
+  CompiledAIAgentCodeExecution,
+  AIAgentCodeExecutionIdentity,
 } from 'ai-workflow-contract';
 import {
   normalizeHolonTaskTarget,
@@ -19,18 +21,24 @@ import {
   composeLayeredResourceRegistry,
   loadResourceTree,
   sha256Digest,
+  digestCanonical,
   type EffectiveResourceRegistry,
   type ResourceContentIdentity,
   type ResourceDependencyEdge,
+  type Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
 import { projectAIWorkflowAgentResources } from './agent-resources.js';
 import { sourceRegistryForAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+import { authorityForAIAgentCodeExecution } from './agent-code-brand.js';
+import { assertAIAgentExecutionResources, assertAIAgentFreezeRegistry, type AIAgentExecutionResourceObservation } from './agent-execution-resources.js';
 import {
   createResolvedAIWorkflowContentIdentityIndex,
   resolveAIWorkflowResourceTree,
 } from './resource-resolution.js';
 
 export interface FreezeAIWorkflowRunResourcesInput {
+  readonly executionResources?: AIAgentExecutionResourceObservation;
+  readonly codeExecutions?: readonly CompiledAIAgentCodeExecution[];
   readonly registry: EffectiveResourceRegistry;
   readonly projection: AIWorkflowAgentResourceProjection;
   readonly task: AIWorkflowAgentTaskRef;
@@ -63,6 +71,7 @@ export class AIWorkflowRunResourceFreezeError extends Error {
 
 const authenticFreezeReceipts = new WeakSet<object>();
 const authenticTaskBindings = new WeakSet<object>();
+const receiptByTaskBinding = new WeakMap<object, AIWorkflowRunResourceFreezeReceipt>();
 const authenticHolonTargetFreezeReceipts = new WeakSet<object>();
 const authenticFrozenHolonTargets = new WeakSet<object>();
 
@@ -185,6 +194,7 @@ export function assertFrozenHolonTaskTarget(value: FrozenHolonTaskTarget): Froze
 export function freezeAIWorkflowRunResources(
   input: FreezeAIWorkflowRunResourcesInput,
 ): AIWorkflowRunResourceFreezeReceipt {
+  assertAIAgentFreezeRegistry(input.registry);
   const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
   if (sourceRegistryForAIWorkflowAgentResourceProjection(input.projection) !== input.registry) {
     diagnostics.push(diagnostic(
@@ -194,6 +204,19 @@ export function freezeAIWorkflowRunResources(
     ));
     throwFreezeError(diagnostics);
   }
+  const executionResources = input.executionResources === undefined ? undefined
+    : assertAIAgentExecutionResources(input.executionResources, input.registry);
+  if (executionResources) {
+    if (input.contentIdentities.size !== executionResources.contentIdentities.size
+      || [...executionResources.contentIdentities].some(([id, identity]) =>
+        digestCanonical(input.contentIdentities.get(id) ?? null) !== digestCanonical(identity))) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_EXECUTION_CONTENT_IDENTITY_MISMATCH', 'run-freeze:identities', 'Execution observation requires its exact authored content identity facts.'),
+      ]));
+    }
+    input = { ...input, registry: executionResources.registry, projection: executionResources.projection,
+      contentIdentities: executionResources.contentIdentities };
+  }
   const task = normalizeTask(input.task, diagnostics);
   if (!task) throwFreezeError(diagnostics);
   const workflowId = resourceIdFromRef(task.workflowRef)!;
@@ -230,19 +253,34 @@ export function freezeAIWorkflowRunResources(
     agentDefinitionRef: task.agentDefinitionRef,
   });
   const bindingResourceIds = Object.freeze(orderedBindings.map((binding) => binding.resource.resourceId));
-  const semanticFingerprint = semanticResourceFingerprint(
+  const resourceFingerprint = semanticResourceFingerprint(
     frozenTask,
     agent,
     orderedBindings,
     dependencySnapshot.closure,
     dependencySnapshot.edges,
   );
+  const codeExecutions = selectedCodeExecutions(input, dependencySnapshot.closure.map(item => item.resourceId));
+  const resourceResolutions = executionResources && Object.freeze(dependencySnapshot.closure
+    .map(item => {
+      const resolution = executionResources.resolutionIdentities.get(item.resourceId);
+      if (!resolution) throw new Error(`AI_RUN_RESOURCE_RESOLUTION_MISSING: ${item.resourceId}`);
+      return resolution;
+    }).sort((a, b) => a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0));
+  const codeFingerprint = codeExecutions.length
+    ? sha256Digest(JSON.stringify({ schemaVersion: 'ai-workflow.code-bound-semantic/v1', resourceFingerprint, codeExecutions }))
+    : resourceFingerprint;
+  const semanticFingerprint = resourceResolutions
+    ? sha256Digest(JSON.stringify({ schemaVersion: 'ai-workflow.reader-bound-semantic/v1', resourceFingerprint: codeFingerprint, resourceResolutions }))
+    : codeFingerprint;
   const receipt = Object.freeze({
     schemaVersion: 'ai-workflow.run-resource-freeze/v1',
     task: frozenTask,
     bindingResourceIds,
     dependencySnapshot,
     semanticFingerprint,
+    ...(codeExecutions.length ? { codeExecutions } : {}),
+    ...(resourceResolutions ? { resourceResolutions } : {}),
   });
   authenticFreezeReceipts.add(receipt);
   return receipt;
@@ -263,11 +301,52 @@ export function projectFrozenAIAgentTaskBinding(
     semanticFingerprint: receipt.semanticFingerprint,
     snapshotRevision: receipt.dependencySnapshot.snapshotRevision,
     closureResourceIds: Object.freeze(receipt.dependencySnapshot.closure.map((item) => item.resourceId)),
+    ...(receipt.codeExecutions ? { codeExecutions: receipt.codeExecutions } : {}),
+    ...(receipt.resourceResolutions ? { resourceResolutions: receipt.resourceResolutions } : {}),
   });
   authenticTaskBindings.add(binding);
+  receiptByTaskBinding.set(binding, receipt);
   return binding;
 }
 
+/** Retrieves the old Agent identity from the authentic freeze, not caller feedback. */
+export function frozenAIAgentTaskAgentContentDigest(binding: FrozenAIAgentTaskBinding): Sha256Digest {
+  assertFrozenAIAgentTaskBinding(binding);
+  const receipt = receiptByTaskBinding.get(binding)!;
+  const agentId = resourceIdFromRef(receipt.task.agentDefinitionRef)!;
+  const identity = receipt.dependencySnapshot.closure.find(({ resourceId }) => resourceId === agentId);
+  if (!identity) throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+    diagnostic('AI_RUN_AGENT_IDENTITY_MISSING', binding.task.agentDefinitionRef, 'Frozen Agent identity is absent.'),
+  ]));
+  if (!/^sha256:[a-f0-9]{64}$/.test(identity.contentDigest)) throw new Error('Invalid frozen Agent content digest');
+  return identity.contentDigest as Sha256Digest;
+}
+
+function selectedCodeExecutions(input: FreezeAIWorkflowRunResourcesInput, closureIds: readonly string[]): readonly AIAgentCodeExecutionIdentity[] {
+  const selected = new Set(closureIds);
+  const identities = new Map<string, AIAgentCodeExecutionIdentity>();
+  for (const execution of input.codeExecutions ?? []) {
+    const authority = authorityForAIAgentCodeExecution(execution);
+    if (!authority || !selected.has(authority.identity.resourceId)
+      || input.registry.byId.get(authority.identity.resourceId)?.resource !== authority.projection.resource
+      || !(input.projection.codeResources ?? []).includes(authority.projection)
+      || identities.has(authority.identity.resourceId)) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_CODE_EXECUTION_UNTRUSTED', 'run-freeze:code', 'Code execution must be authentic, selected and belong to the exact registry projection.'),
+      ]));
+    }
+    identities.set(authority.identity.resourceId, authority.identity);
+  }
+  for (const code of input.projection.codeResources ?? []) {
+    if (code.mode === 'native' && selected.has(code.resource.resourceId) && !identities.has(code.resource.resourceId)) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_CODE_EXECUTION_MISSING', `resource://${code.resource.resourceId}`, 'Native code must be compiled or restored before task freeze.'),
+      ]));
+    }
+  }
+  return Object.freeze([...identities.values()].sort((a, b) => a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0));
+}
+
 /** Runtime assertion; a structurally similar literal is not an admitted authority. */
 export function assertFrozenAIAgentTaskBinding(value: FrozenAIAgentTaskBinding): FrozenAIAgentTaskBinding {
   if (!authenticTaskBindings.has(value as object)) {