ai-workflow-logic 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-logic",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
   "description": "AI workflow domain projections and pure runtime helpers with an explicit Halfcode filesystem adapter",
   "type": "module",
@@ -11,19 +11,20 @@
     "./checkpoint-filesystem": "./src/checkpoint-filesystem.ts",
     "./filesystem": "./src/filesystem.ts",
     "./run-freeze": "./src/run-freeze.ts",
-    "./agent-code-execution": "./src/agent-code-execution.ts"
+    "./agent-code-execution": "./src/agent-code-execution.ts",
+    "./definitions": "./src/definitions.ts"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.2.1",
+    "ai-workflow-contract": "0.2.2",
     "ajv": "8.20.0",
     "flow-step-space-contract": "0.1.1",
-    "flow-step-space-logic": "0.1.1",
-    "halfcode-compiler.xnl": "0.3.1",
+    "flow-step-space-logic": "0.1.2",
+    "halfcode-compiler.xnl": "0.3.2",
     "holarchy-core-contract": "0.2.0",
-    "task-manager-contract": "0.1.3",
-    "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-contract": "0.1.3",
-    "work-ctrl-flow-logic": "0.1.5"
+    "task-manager-contract": "0.1.4",
+    "task-manager-logic": "0.1.7",
+    "work-ctrl-flow-contract": "0.1.4",
+    "work-ctrl-flow-logic": "0.1.6"
   },
   "files": [
     "src"

package/src/agent-invocation.ts

@@ -8,9 +8,11 @@ import type {
   AIAgentRunResult,
   AIAgentSelector,
   AIWorkflowAuthoredEffects,
+  AIWorkflowNodeTasks,
   AIWorkflowFlowRunCheckpoint,
   AIWorkflowProfileDurableState,
   FlowClosedValue,
+  FlowClosedObject,
 } from 'ai-workflow-contract';
 import {
   AIAgentInvocationError,
@@ -58,6 +60,37 @@ function same(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function assertNoTaskSourceOverride(checkpoint: AIWorkflowFlowRunCheckpoint, nodeId: string): void {
+  const object = (value: FlowClosedValue): value is FlowClosedObject => value !== null && typeof value === 'object' && !Array.isArray(value);
+  const bindings = object(checkpoint.config) ? checkpoint.config.workflowDelegations : undefined;
+  if (bindings && typeof bindings === 'object' && !Array.isArray(bindings) && Object.hasOwn(bindings, nodeId)) {
+    fail('AI_AGENT_TASK_DELEGATION_REQUIRED', 'checkpoint.config.workflowDelegations.' + nodeId,
+      'This node has an explicit task source. Use ai.delegation.delegateTask so its admitted owner and context cannot be silently ignored.');
+  }
+}
+
+/** The canonical instance index owns context reuse; the Host still owns the Actor. */
+function frozenAgentContext(checkpoint:AIWorkflowFlowRunCheckpoint,runtime:AIAgentProcessorRuntime,config:AIAgentEffectConfig):{name?:string;generation:number}|undefined {
+  const object=(value:FlowClosedValue|undefined):value is FlowClosedObject=>value!==undefined&&value!==null&&typeof value==='object'&&!Array.isArray(value);
+  const bindings=normalizeFlowClosedObject(checkpoint.config).workflowAgentContexts;
+  if(bindings===undefined)return;
+  if(!object(bindings))fail('AI_AGENT_CONTEXT_INVALID','checkpoint.config.workflowAgentContexts','Frozen Agent contexts must be an object.');
+  if(!Object.hasOwn(bindings,runtime.nodeId))return;
+  const choice=bindings[runtime.nodeId];
+  if(!object(choice)||choice.schemaVersion!=='workflow.agent-context/v1'
+    ||choice.agentDefinitionRef!==config.agentDefinitionRef||!['authored','shared','independent-per-generation'].includes(String(choice.sessionPolicy))
+    ||choice.nodeIdentity!==undefined&&choice.nodeIdentity!==true
+    ||Object.keys(choice).some(key=>!['schemaVersion','agentDefinitionRef','sessionPolicy','nodeIdentity'].includes(key)))
+    fail('AI_AGENT_CONTEXT_INVALID','checkpoint.config.workflowAgentContexts.'+runtime.nodeId,'Frozen Agent context must match the exact node task definition and supported policy.');
+  const generation=runtime.nodeContext?.generation??runtime.generation,scope=runtime.nodeContext?.scope??'';
+  if(generation===undefined||!Number.isSafeInteger(generation)||generation<0||typeof scope!=='string'||scope.normalize('NFC')!==scope)
+    fail('AI_AGENT_CONTEXT_IDENTITY_REQUIRED','runtime.nodeContext','A frozen Agent context requires its actual native generation and scope.');
+  if(choice.sessionPolicy==='authored')return {generation};
+  const name='workflow-agent-context:'+JSON.stringify([runtime.nodeId,scope,choice.sessionPolicy==='shared'?null:generation]);
+  if(config.instanceName!==undefined&&config.instanceName!==name)fail('AI_AGENT_CONTEXT_NAME_CONFLICT','config.instanceName','An explicit instance name cannot replace the frozen node context identity.');
+  return {name,generation};
+}
+
 function semanticFacts(config: AIAgentEffectConfig, invocationMetadata?: Readonly<Record<string, FlowClosedValue>>): Readonly<Record<string, FlowClosedValue>> {
   return normalizeFlowClosedObject({
     materialRefs: config.materialRefs ?? [],
@@ -201,11 +234,16 @@ async function complete(runtime: AIAgentProcessorRuntime, checkpoint: AIWorkflow
 
 export async function runAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(runtime: AIAgentProcessorRuntime, input: Input, configInput: AIAgentEffectConfig): Promise<AIAgentRunResult<Output>> {
   const inputValue = normalizeFlowClosedValue(input, 'input') as Input;
-  const config = normalizeAIAgentEffectConfig(configInput);
+  let config = normalizeAIAgentEffectConfig(configInput);
   assertTaskAuthority(runtime, config);
   let checkpoint = await loadCheckpoint(runtime);
+  assertNoTaskSourceOverride(checkpoint, runtime.nodeId);
+  const context=frozenAgentContext(checkpoint,runtime,config);
+  if(context){runtime={...runtime,generation:context.generation};if(context.name!==undefined)config={...config,instanceName:context.name}}
   let ai = profileAI(checkpoint);
   let receipt = ai.invocationsByKey[runtime.invocationKey];
+  if(context?.name!==undefined&&(receipt?.mode==='targeted'||!receipt&&ai.instanceIdByName[context.name]!==undefined))
+    return runTargetedAgent<Input,Output>(runtime,{byName:context.name},{kind:'ai.agent',payload:inputValue},config);
   if (receipt) {
     assertSameInvocation(receipt, runtime, 'new', inputValue, config);
     if (receipt.status === 'completed') return resultFromReceipt(ai, receipt) as AIAgentRunResult<Output>;
@@ -238,11 +276,15 @@ export async function runAgent<Input extends FlowClosedValue = FlowClosedValue,
 export async function runTargetedAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(runtime: AIAgentProcessorRuntime, selectorInput: AIAgentSelector, invocationInput: AIAgentInvocation<Input>, configInput: AIAgentEffectConfig): Promise<AIAgentRunResult<Output>> {
   const selector = normalizeAIAgentSelector(selectorInput);
   const invocation = normalizeAIAgentInvocation<Input>(invocationInput);
-  const config = normalizeAIAgentEffectConfig(configInput);
+  let config = normalizeAIAgentEffectConfig(configInput);
   assertTaskAuthority(runtime, config);
   let checkpoint = await loadCheckpoint(runtime);
+  assertNoTaskSourceOverride(checkpoint, runtime.nodeId);
+  const context=frozenAgentContext(checkpoint,runtime,config);
+  if(context){runtime={...runtime,generation:context.generation};if(context.name!==undefined)config={...config,instanceName:context.name}}
   let ai = profileAI(checkpoint);
   const instance = resolveSelector(ai, selector, config);
+  if(context?.name!==undefined&&instance.instanceName!==context.name)fail('AI_AGENT_CONTEXT_TARGET_CONFLICT','selector','Target must be the original instance for this frozen node generation and scope.');
   let receipt = ai.invocationsByKey[runtime.invocationKey];
   if (receipt) {
     assertSameInvocation(receipt, runtime, 'targeted', invocation.payload, config, invocation.metadata);
@@ -280,3 +322,21 @@ export function bindAIAgentProcessors(runtime: AIAgentProcessorRuntime): AIWorkf
     runTargetedAgent: <Input extends FlowClosedValue, Output extends FlowClosedValue>(selector: AIAgentSelector, invocation: AIAgentInvocation<Input>, config: AIAgentEffectConfig) => runTargetedAgent<Input, Output>(runtime, selector, invocation, config),
   });
 }
+
+/** Source selection is an immutable admission fact; authored input cannot select another owner. */
+export function bindWorkflowNodeTasks(runtime: AIAgentProcessorRuntime, delegation?: { delegateTask(input: FlowClosedValue): Promise<FlowClosedValue> }): AIWorkflowNodeTasks {
+  return Object.freeze({ async invoke(input: FlowClosedValue, configInput: AIAgentEffectConfig): Promise<FlowClosedValue> {
+    const config=normalizeAIAgentEffectConfig(configInput),value=normalizeFlowClosedValue(input);
+    assertTaskAuthority(runtime,config);
+    const checkpoint=await loadCheckpoint(runtime),closed=normalizeFlowClosedObject(checkpoint.config),bindings=closed.workflowDelegations;
+    if(bindings!==undefined&&(bindings===null||typeof bindings!=='object'||Array.isArray(bindings)))
+      fail('AI_AGENT_TASK_SOURCES_INVALID','checkpoint.config.workflowDelegations','Frozen node task sources must be an object.');
+    if(bindings&&Object.hasOwn(bindings,runtime.nodeId)){
+      if(Object.keys(config).some(key=>key!=='agentDefinitionRef'))
+        fail('AI_AGENT_TASK_EFFECT_OVERRIDE_UNSUPPORTED','config','Delegated tasks use their frozen materials, model and context; Agent instance or effect overrides cannot be ignored.');
+      if(!delegation)fail('AI_AGENT_TASK_OWNER_REQUIRED','runtime.delegation','The admitted node task owner is unavailable.');
+      return delegation.delegateTask(value);
+    }
+    return (await runAgent(runtime,value,config)).output;
+  }});
+}

package/src/agent-state.ts

@@ -12,6 +12,7 @@ import type {
   LegacyAIWorkflowProfileDurableState,
 } from 'ai-workflow-contract';
 import { normalizeFlowClosedObject, normalizeFlowClosedValue } from './run-checkpoint.js';
+import { normalizeWorkflowDelegations } from './delegation.js';
 
 export class AIAgentInvocationError extends Error {
   constructor(public readonly code: string, public readonly location: string, message: string) {
@@ -231,7 +232,7 @@ function normalizeReceipt(value: unknown, key: string, instances: Readonly<Recor
 }
 
 export function normalizeCanonicalAIAgentState(value: unknown, location = 'ai'): AIWorkflowProfileDurableState {
-  const input = record(value, ['schemaVersion', 'instancesById', 'instanceIdByName', 'invocationsByKey'], [], location);
+  const input = record(value, ['schemaVersion', 'instancesById', 'instanceIdByName', 'invocationsByKey'], ['delegationsByKey'], location);
   if (input.schemaVersion !== 'depa.ai-agent-state/v1') fail('AI_AGENT_STATE_SCHEMA_UNSUPPORTED', `${location}.schemaVersion`, 'Unsupported Agent state schema.');
   const instanceValues = objectMap(input.instancesById, `${location}.instancesById`);
   const instancesById: Record<string, AIAgentInstanceReference> = {};
@@ -259,7 +260,7 @@ export function normalizeCanonicalAIAgentState(value: unknown, location = 'ai'):
     }
     invocationsByKey[key] = receipt;
   }
-  return Object.freeze({ schemaVersion: 'depa.ai-agent-state/v1', instancesById: Object.freeze(instancesById), instanceIdByName: Object.freeze(instanceIdByName), invocationsByKey: Object.freeze(invocationsByKey) });
+  return Object.freeze({ schemaVersion: 'depa.ai-agent-state/v1', instancesById: Object.freeze(instancesById), instanceIdByName: Object.freeze(instanceIdByName), invocationsByKey: Object.freeze(invocationsByKey), ...(input.delegationsByKey === undefined ? {} : { delegationsByKey: normalizeWorkflowDelegations(input.delegationsByKey) }) });
 }
 
 export function upgradeLegacyAIWorkflowProfileDurableState(value: LegacyAIWorkflowProfileDurableState, agentDefinitionRefs: Readonly<Record<string, `resource://${string}`>>, location = 'legacyAI'): AIWorkflowProfileDurableState {

package/src/checkpoint-filesystem.ts

@@ -16,6 +16,7 @@ import type { WorkCtrlFlowSnapshot } from 'work-ctrl-flow-contract';
 import {
   createMaterializedWorkCtrlFlowEngineFromDirectory,
   loadFrozenCtrlDefinitionStepIds,
+  loadFrozenCtrlDefinitionMembership,
   loadMaterializedFlowInstance,
   materializeFlowInstance,
   type MaterializedWorkCtrlFlowDirectoryOptions,
@@ -293,7 +294,7 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
     if (!fs.existsSync(locations.runDir)) return undefined;
     assertExistingDirectory(locations.runDir, this.#realStoreRoot, 'flow-run-symlink-boundary');
     if (!fs.existsSync(locations.checkpointFile)) return undefined;
-    const checkpoint = readCheckpointFile(locations.checkpointFile, this.#realStoreRoot);
+    const checkpoint = this.#readStorage(locations.checkpointFile).checkpoint;
     this.#assertCheckpointIdentity(checkpoint, key, descriptor.definition);
     this.#validateFrozenProfile(checkpoint);
     return checkpoint;
@@ -317,7 +318,7 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
       this.#assertRunPhysicalBoundary(locations);
       removeUncommittedStaging(locations.stagingFile, locations.runDir, this.#realStoreRoot);
       const currentStorage = fs.existsSync(locations.checkpointFile)
-        ? readCheckpointStorage(locations.checkpointFile, this.#realStoreRoot)
+        ? this.#readStorage(locations.checkpointFile)
         : undefined;
       const current = currentStorage?.checkpoint;
       if (current) {
@@ -338,13 +339,15 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
           ));
       const encoded = encodeCheckpointSidecars(checkpoint, currentStorage?.tree, {
         definitionStepIds,
+        ...(checkpoint.profile.kind === 'AIDataWorkflow' ? {} : { definitionInvocationOwners: frozenAuthority?.definitionInvocationOwners
+          ?? loadFrozenCtrlDefinitionMembership(path.join(locations.instanceDir, 'definition'), checkpoint.profile.kind, this.#extensionCodecs).invocationOwners }),
         previousMaterialRecordDigests: currentStorage?.materialRecordDigests,
       });
       removeUnacceptedSidecarReceipt(locations.runDir, checkpoint.version, this.#realStoreRoot);
       persistCheckpointSidecars(locations.runDir, encoded, this.#durability);
       assertSidecarDirectories(locations.runDir, this.#realStoreRoot);
       writeCheckpointCandidate(locations.stagingFile, encoded.head, this.#realStoreRoot, this.#durability);
-      const staged = readCheckpointFile(locations.stagingFile, this.#realStoreRoot);
+      const staged = this.#readStorage(locations.stagingFile).checkpoint;
       this.#assertCheckpointIdentity(staged, key, descriptor.definition);
       this.#validateFrozenProfile(staged);
       if (stableJson(staged) !== stableJson(checkpoint)) {
@@ -359,7 +362,7 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
         assertRegularFile(locations.checkpointFile, this.#realStoreRoot, 'flow-run-checkpoint-invalid');
       }
       renameDurably(locations.stagingFile, locations.checkpointFile, 'head', this.#durability);
-      const accepted = readCheckpointFile(locations.checkpointFile, this.#realStoreRoot);
+      const accepted = this.#readStorage(locations.checkpointFile).checkpoint;
       this.#assertCheckpointIdentity(accepted, key, descriptor.definition);
       this.#validateFrozenProfile(accepted);
       if (stableJson(accepted) !== stableJson(checkpoint)) {
@@ -452,7 +455,7 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
     try {
       this.#assertRunPhysicalBoundary(locations);
       const checkpoint = fs.existsSync(locations.checkpointFile)
-        ? readCheckpointFile(locations.checkpointFile, this.#realStoreRoot)
+        ? this.#readStorage(locations.checkpointFile).checkpoint
         : undefined;
       if (!checkpoint) {
         throw new LegacyWorkCtrlImportError(
@@ -574,6 +577,13 @@ export class FilesystemFlowRunCheckpointStore implements FlowRunCheckpointStore<
     }, { requireAIDataAuthority: true });
   }
 
+  #readStorage(file: string) {
+    return readCheckpointStorage(file, this.#realStoreRoot, {
+      profileAuthority: this.#profileAuthority,
+      extensionCodecs: this.#extensionCodecs,
+    });
+  }
+
   #ensureRunDirectory(locations: FlowRunFilesystemLocations): void {
     ensureChildDirectory(locations.instanceDir, locations.runsDir, this.#realStoreRoot, this.#durability, 'head');
     ensureChildDirectory(locations.runsDir, locations.runDir, this.#realStoreRoot, this.#durability, 'head');
@@ -1018,13 +1028,10 @@ function ensureChildDirectory(
   assertExistingDirectory(child, realRoot, 'flow-run-boundary-invalid');
 }
 
-function readCheckpointFile(file: string, realRoot: string): AIWorkflowFlowRunCheckpoint {
-  return readCheckpointStorage(file, realRoot).checkpoint;
-}
-
 function readCheckpointStorage(
   file: string,
   realRoot: string,
+  runtime: { readonly profileAuthority?: import('./checkpoint-profile.js').FlowRunProfileAuthorityPort; readonly extensionCodecs: import('flow-step-space-contract').DefinitionStepExtensionCodecRegistryPort },
 ): {
   readonly checkpoint: AIWorkflowFlowRunCheckpoint;
   readonly tree?: StepMerkleTree;
@@ -1034,7 +1041,13 @@ function readCheckpointStorage(
   try {
     if (isCheckpointHead(value)) {
       assertSidecarDirectories(path.dirname(file), realRoot);
-      const loaded = readCheckpointHeadAndLogical(file);
+      const loaded = readCheckpointHeadAndLogical(file,{ctrlMembership(head,kind){
+        assertSafeSegment(head.instanceId);
+        const authority=runtime.profileAuthority?.load({instanceId:head.instanceId,definition:head.definition,profileKind:kind});
+        return authority?.definitionInvocationOwners
+          ? {definitionStepIds:authority.definitionStepIds,invocationOwners:authority.definitionInvocationOwners}
+          : loadFrozenCtrlDefinitionMembership(path.join(realRoot,'instances',head.instanceId,'definition'),kind,runtime.extensionCodecs);
+      }});
       return {
         checkpoint: loaded.checkpoint,
         tree: loaded.tree,

package/src/checkpoint-profile.ts

@@ -18,6 +18,7 @@ export interface FrozenRunStepExtensionDefinition {
 export interface FrozenFlowRunProfileAuthority {
   readonly profileKind: FlowRunProfileState['kind'];
   readonly definitionStepIds: readonly string[];
+  readonly definitionInvocationOwners?: Readonly<Record<string, string>>;
   readonly binding?: FlowClosedObject;
   readonly extensionsByStepId: Readonly<
     Record<string, Readonly<Record<string, FrozenRunStepExtensionDefinition>>>
@@ -103,6 +104,8 @@ export function validateCheckpointAgainstFrozenProfile(
   if (ids.some((id) => typeof id !== 'string' || !id || id !== id.trim()) || new Set(ids).size !== ids.length) {
     throw new FlowRunCheckpointTransitionError('Frozen profile step membership is invalid.');
   }
+  if (Object.entries(authority.definitionInvocationOwners ?? {}).some(([key, owner]) => !key || !ids.includes(owner)))
+    throw new FlowRunCheckpointTransitionError('Frozen compiled action ownership is invalid.');
   for (const stepId of Object.keys(authority.extensionsByStepId)) {
     if (!ids.includes(stepId)) {
       throw new FlowRunCheckpointTransitionError(`Frozen extension step ${stepId} is not a definition member.`);

package/src/checkpoint-sidecar.ts

@@ -42,8 +42,15 @@ export interface FlowRunCheckpointSidecarReceipt {
 }
 export interface CheckpointSidecarEncodeConfig {
   readonly definitionStepIds?: readonly string[];
+  readonly definitionInvocationOwners?: Readonly<Record<string, string>>;
   readonly previousMaterialRecordDigests?: readonly DefinitionStepDigest[];
 }
+export interface CheckpointSidecarReadConfig {
+  readonly ctrlMembership?: (head: FlowRunCheckpointHead, kind: 'WorkCtrlFlow' | 'AICtrlWorkflow') => {
+    readonly definitionStepIds: readonly string[];
+    readonly invocationOwners: Readonly<Record<string, string>>;
+  };
+}
 type EncodedCheckpoint = {
   readonly head: FlowRunCheckpointHead;
   readonly controlRecords: readonly ImmutableStepRecord[];
@@ -123,12 +130,12 @@ function dataMembership(
 const ORCHESTRATION_FIELDS = ['attempts', 'deadlines', 'lanes', 'winners', 'cancellations', 'composites'] as const;
 type OrchestrationField = typeof ORCHESTRATION_FIELDS[number];
 
-function runtimeCtrlMembers(orchestrationValue: unknown, definitionStepIds: readonly string[]): readonly string[] {
+function runtimeCtrlMembers(orchestrationValue: unknown, definitionStepIds: readonly string[], invocationOwners: Readonly<Record<string, string>> = {}, waitOwners:ReadonlyMap<string,string>=new Map()): readonly string[] {
   const orchestration = object(orchestrationValue, 'ctrl orchestration');
   const members = new Set<string>();
   for (const field of ORCHESTRATION_FIELDS) {
     for (const [identity] of entries(orchestration[field], `ctrl orchestration.${field}`)) {
-      if (!definitionOwner(identity, definitionStepIds)) members.add(identity);
+      if (!definitionOwner(identity, definitionStepIds, invocationOwners)&&!waitOwners.has(identity)) members.add(identity);
     }
   }
   return [...members].sort(compare);
@@ -161,22 +168,55 @@ function createRunStepLeaf(
   });
   return { leaf, materialRecords: [coreRecord, ...extensionRecords.map(({ record }) => record)] as readonly ImmutableStepRecord[] };
 }
-function definitionOwner(invocationKey: string, definitionStepIds: readonly string[]): string | undefined {
+function definitionOwner(invocationKey: string, definitionStepIds: readonly string[], invocationOwners: Readonly<Record<string, string>> = {}): string | undefined {
   const visit = invocationKey.lastIndexOf('#');
   const stablePath = visit >= 0 ? invocationKey.slice(0, visit) : invocationKey;
   const id = stablePath.slice(stablePath.lastIndexOf('/') + 1);
-  return definitionStepIds.includes(id) ? id : undefined;
+  const owner = invocationOwners[id];
+  return definitionStepIds.includes(id) ? id : owner && definitionStepIds.includes(owner) ? owner : undefined;
 }
 
-function partitionCtrl(checkpoint: AIWorkflowFlowRunCheckpoint, idsValue?: readonly string[]) {
+/** Dynamic waits belong to the exact compiled action that created their native handle, never a prefix wildcard. */
+function delegationWaitOwners(snapshotValue:unknown,definitionStepIds:readonly string[],invocationOwners:Readonly<Record<string,string>>,aiValue?:unknown):ReadonlyMap<string,string>{
+  const snapshot=object(snapshotValue,'ctrl snapshot'),owners=new Map<string,string>();
+  for(const field of ['closedWaitHandles','openWaitHandles']){
+    const handles=snapshot[field];if(!Array.isArray(handles))throw Error('Ctrl wait handles must be an array.');
+    for(const value of handles){
+      const handle=object(value,'ctrl wait handle');
+      if(!handle.metadata||typeof handle.metadata!=='object'||Array.isArray(handle.metadata))continue;
+      const metadata=object(handle.metadata,'ctrl wait metadata');
+      if(metadata.workflowDelegation===undefined)continue;
+      const delegated=object(metadata.workflowDelegation,'ctrl delegation wait');
+      const action=delegated.actionInvocationKey,invocation=delegated.invocationKey;
+      if(delegated.kind!=='workflow.task-delegation/v1'||typeof action!=='string'||typeof invocation!=='string'||typeof handle.invocationKey!=='string'||typeof handle.nodeKey!=='string'||handle.waitKind!=='external-job'||handle.signalKind!=='workflow.delegation.observe'||handle.signalKey!==action)throw Error('Ctrl delegation wait identity is invalid.');
+      const owner=definitionOwner(action,definitionStepIds,invocationOwners);
+      const actionPath=action.slice(0,action.lastIndexOf('#')),scope=actionPath.slice(0,actionPath.lastIndexOf('/')+1),node=actionPath.slice(actionPath.lastIndexOf('/')+1);
+      const prefix=`${node}:delegation:`;
+      if(!owner||definitionOwner(invocation,definitionStepIds,invocationOwners)!==owner||!handle.nodeKey.startsWith(prefix)||!/^(0|[1-9][0-9]*)$/.test(handle.nodeKey.slice(prefix.length))||!handle.invocationKey.startsWith(`${scope}${handle.nodeKey}#`)||!/^(0|[1-9][0-9]*)$/.test(handle.invocationKey.slice(`${scope}${handle.nodeKey}#`.length)))throw Error('Ctrl delegation wait is not owned by its frozen action.');
+      if(aiValue!==undefined){
+        const ai=object(aiValue,'ctrl AI state'),records=object(ai.delegationsByKey??{},'ctrl delegations'),record=object(records[invocation],'ctrl delegation record');
+        if(!Array.isArray(record.attempts)||record.attempts.length===0)throw Error('Ctrl delegation wait has no accepted invocation.');
+        const attempt=object(record.attempts.at(-1),'ctrl delegation attempt'),request=object(attempt.request,'ctrl delegation request'),lineage=object(request.lineage,'ctrl delegation lineage');
+        if(attempt.dispatchClaimed!==true||lineage.invocationKey!==invocation||lineage.nodeId!==owner)throw Error('Ctrl delegation wait receipt does not match its frozen action.');
+      }
+      if(owners.has(handle.invocationKey))throw Error('Ctrl delegation wait identity is duplicated.');
+      owners.set(handle.invocationKey,owner);
+    }
+  }
+  return owners;
+}
+
+function partitionCtrl(checkpoint: AIWorkflowFlowRunCheckpoint, idsValue?: readonly string[], invocationOwners: Readonly<Record<string, string>> = {}) {
   if (!idsValue?.length || idsValue.some((id) => typeof id !== 'string' || !id) || new Set(idsValue).size !== idsValue.length) {
     throw new Error('Ctrl sidecar requires unique frozen definition step identities.');
   }
   if (checkpoint.profile.kind !== 'WorkCtrlFlow' && checkpoint.profile.kind !== 'AICtrlWorkflow') throw new Error('Ctrl profile expected.');
   const definitionStepIds = [...idsValue];
+  if (Object.entries(invocationOwners).some(([key, owner]) => !key || !definitionStepIds.includes(owner))) throw new Error('Ctrl compiled action ownership is invalid.');
   const snapshot = checkpoint.profile.snapshot as FlowClosedObject;
   const { branchDecisions, nodeResults, waitResults, orchestration, ...snapshotControl } = snapshot;
-  const runtimeMembers = runtimeCtrlMembers(orchestration, definitionStepIds);
+  const waitOwners=delegationWaitOwners(snapshot,definitionStepIds,invocationOwners,checkpoint.profile.kind==='AICtrlWorkflow'?checkpoint.profile.ai:undefined);
+  const runtimeMembers = runtimeCtrlMembers(orchestration, definitionStepIds, invocationOwners,waitOwners);
   const memberIds = [...definitionStepIds.map((id) => `definition:${id}`), ...runtimeMembers.map((id) => `runtime:${id}`)].sort(compare);
   const facts = new Map(memberIds.map((id) => [id, {
     branchDecisions: {},
@@ -186,7 +226,7 @@ function partitionCtrl(checkpoint: AIWorkflowFlowRunCheckpoint, idsValue?: reado
   }]));
   const runtimeSet = new Set(runtimeMembers);
   const ownerOf = (identity: string) => {
-    const owner = definitionOwner(identity, definitionStepIds);
+    const owner = definitionOwner(identity, definitionStepIds, invocationOwners)??waitOwners.get(identity);
     return owner ? `definition:${owner}` : runtimeSet.has(identity) ? `runtime:${identity}` : undefined;
   };
   const place = (field: 'branchDecisions' | 'nodeResults' | 'waitResults', value: unknown) => {
@@ -223,6 +263,7 @@ function partitionCtrl(checkpoint: AIWorkflowFlowRunCheckpoint, idsValue?: reado
       profile: {
         kind: checkpoint.profile.kind,
         definitionStepIds,
+        ...(Object.keys(invocationOwners).length ? { definitionInvocationOwners: invocationOwners } : {}),
         snapshot: {
           ...snapshotControl,
           orchestration: Object.fromEntries(ORCHESTRATION_FIELDS.map((field) => [field, {}])),
@@ -269,6 +310,7 @@ function reconstruct(
   records: readonly ImmutableStepRecord[],
   controlRecords: ReadonlyMap<DefinitionStepDigest, ImmutableStepRecord>,
   readMaterial: (digest: DefinitionStepDigest) => ImmutableStepRecord,
+  config: CheckpointSidecarReadConfig,
 ): AIWorkflowFlowRunCheckpoint {
   const control = object(head.control, 'checkpoint control');
   if (control.schemaVersion !== 'depa.flow-run-checkpoint-control/v1') throw new Error('Checkpoint control schema is invalid.');
@@ -339,7 +381,15 @@ function reconstruct(
     if (!Array.isArray(profileControl.definitionStepIds) || profileControl.definitionStepIds.some((id) => typeof id !== 'string' || !id)) throw new Error('Ctrl definition membership is invalid.');
     const definitionStepIds = profileControl.definitionStepIds as readonly string[];
     if (new Set(definitionStepIds).size !== definitionStepIds.length) throw new Error('Ctrl definition membership is duplicated.');
+    const savedOwners = object(profileControl.definitionInvocationOwners ?? {}, 'ctrl compiled action owners');
+    if (Object.values(savedOwners).some(owner => typeof owner !== 'string' || !definitionStepIds.includes(owner))) throw new Error('Ctrl compiled action owner is invalid.');
+    const membership = config.ctrlMembership?.(head, profileControl.kind);
+    if (membership && (canonicalJson([...definitionStepIds].sort(compare)) !== canonicalJson([...membership.definitionStepIds].sort(compare))
+      || profileControl.definitionInvocationOwners !== undefined && canonicalJson(savedOwners) !== canonicalJson(membership.invocationOwners)))
+      throw new Error('Ctrl sidecar ownership differs from the frozen compiled definition.');
+    const invocationOwners = membership?.invocationOwners ?? savedOwners as Readonly<Record<string, string>>;
     const snapshotControl = object(profileControl.snapshot, 'ctrl snapshot control');
+    const waitOwners=delegationWaitOwners(snapshotControl,definitionStepIds,invocationOwners,profileControl.kind==='AICtrlWorkflow'?profileControl.ai:undefined);
     const orchestrationOutput = Object.fromEntries(
       ORCHESTRATION_FIELDS.map((field) => [field, {}]),
     ) as Record<OrchestrationField, Record<string, FlowClosedValue>>;
@@ -365,7 +415,7 @@ function reconstruct(
       actual.push(value.memberId);
       for (const field of ['branchDecisions', 'nodeResults', 'waitResults'] as const) {
         for (const [key, fact] of entries(value[field], `ctrl ${field}`)) {
-          const owner = definitionOwner(key, definitionStepIds);
+          const owner = definitionOwner(key, definitionStepIds, invocationOwners)??waitOwners.get(key);
           if (projectedDefinition !== null ? owner !== projectedDefinition : value.memberId !== `runtime:${key}`) throw new Error(`Ctrl ${field} member is invalid.`);
           if (Object.prototype.hasOwnProperty.call(output[field], key)) throw new Error(`Ctrl ${field} member is duplicated.`);
           output[field][key] = fact;
@@ -374,14 +424,14 @@ function reconstruct(
       const recordOrchestration = object(value.orchestration, 'ctrl record orchestration');
       for (const field of ORCHESTRATION_FIELDS) {
         for (const [key, fact] of entries(recordOrchestration[field], `ctrl orchestration.${field}`)) {
-          const owner = definitionOwner(key, definitionStepIds);
+          const owner = definitionOwner(key, definitionStepIds, invocationOwners)??waitOwners.get(key);
           if (projectedDefinition !== null ? owner !== projectedDefinition : value.memberId !== `runtime:${key}`) throw new Error(`Ctrl orchestration.${field} member is invalid.`);
           if (Object.prototype.hasOwnProperty.call(orchestrationOutput[field], key)) throw new Error(`Ctrl orchestration.${field} member is duplicated.`);
           orchestrationOutput[field][key] = fact;
         }
       }
     }
-    const runtimeMembers = runtimeCtrlMembers(orchestrationOutput, definitionStepIds);
+    const runtimeMembers = runtimeCtrlMembers(orchestrationOutput, definitionStepIds, invocationOwners,waitOwners);
     const expected = [...definitionStepIds.map((id) => `definition:${id}`), ...runtimeMembers.map((id) => `runtime:${id}`)].sort(compare);
     if (canonicalJson(expected) !== canonicalJson(actual.sort(compare))) throw new Error('Ctrl sidecar membership is invalid.');
     const snapshot: FlowClosedObject = { ...snapshotControl, ...output };
@@ -469,9 +519,20 @@ function runEvent(runtime: CheckpointDurabilityRuntime | undefined, event: Check
   runtime?.beforeEvent?.(event); operation(); runtime?.onEvent?.(event);
 }
 function syncDirectory(directory: string, role: CheckpointDurabilityRole, runtime?: CheckpointDurabilityRuntime): void {
-  let fd: number | undefined;
-  try { fd = fs.openSync(directory, fs.constants.O_RDONLY); runEvent(runtime, { operation: 'directory-fsync', role, path: directory }, () => fs.fsyncSync(fd!)); }
-  finally { if (fd !== undefined) fs.closeSync(fd); }
+  runEvent(runtime, { operation: 'directory-fsync', role, path: directory }, () => {
+    let fd: number | undefined;
+    try {
+      fd = fs.openSync(directory, fs.constants.O_RDONLY);
+      fs.fsyncSync(fd);
+    } catch (error) {
+      // Windows may reject either opening or syncing a directory. File-data
+      // fsync and durability observers retain their original failure behavior.
+      const code = (error as NodeJS.ErrnoException).code;
+      if (process.platform !== 'win32' || !code || !['EPERM', 'EINVAL', 'ENOTSUP', 'EISDIR'].includes(code)) throw error;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  });
 }
 export function createDirectoryDurably(directory: string, role: CheckpointDurabilityRole, runtime?: CheckpointDurabilityRuntime): void {
   runEvent(runtime, { operation: 'directory-create', role, path: directory }, () => fs.mkdirSync(directory));
@@ -500,7 +561,7 @@ function writeImmutable(file: string, value: unknown, role: 'record' | 'tree' |
 
 export function encodeCheckpointSidecars(checkpointValue: AIWorkflowFlowRunCheckpoint, previousTree: StepMerkleTree | undefined, config: CheckpointSidecarEncodeConfig = {}): EncodedCheckpoint {
   const checkpoint = normalizeFlowRunCheckpoint(checkpointValue);
-  const partitioned = checkpoint.profile.kind === 'AIDataWorkflow' ? partitionData(checkpoint, config.definitionStepIds) : partitionCtrl(checkpoint, config.definitionStepIds);
+  const partitioned = checkpoint.profile.kind === 'AIDataWorkflow' ? partitionData(checkpoint, config.definitionStepIds) : partitionCtrl(checkpoint, config.definitionStepIds, config.definitionInvocationOwners);
   const tree = buildStepMerkleTree(partitioned.records); const treeDiff = diffStepMerkleTrees(previousTree, tree);
   const previousRecords = new Set<string>(); Object.values(previousTree?.nodes ?? {}).forEach((node) => { if (node.kind === 'leaf') previousRecords.add(node.recordDigest); });
   const addedRecordDigests = partitioned.records.map((record) => record.digest).filter((value) => !previousRecords.has(value)).sort(compare);
@@ -525,7 +586,7 @@ function assertReceipt(root: string, head: FlowRunCheckpointHead): Record<string
   if (value.schemaVersion !== 'depa.flow-run-checkpoint-sidecar-receipt/v1' || value.version !== head.version || value.rootDigest !== head.runStepStateRootDigest || value.logicalDigest !== head.logicalDigest || (value.previousRootDigest !== null && (typeof value.previousRootDigest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(value.previousRootDigest)))) throw new Error('Receipt does not bind head.');
   return value;
 }
-export function readCheckpointHeadAndLogical(file: string) {
+export function readCheckpointHeadAndLogical(file: string, config: CheckpointSidecarReadConfig = {}) {
   const head = normalizeHead(readJson(file)); const root = path.join(path.dirname(file), 'step-space'); const receipt = assertReceipt(root, head);
   const controlRecords = new Map<DefinitionStepDigest, ImmutableStepRecord>();
   for (const value of receipt.controlRecordDigests as readonly DefinitionStepDigest[]) {
@@ -536,7 +597,7 @@ export function readCheckpointHeadAndLogical(file: string) {
     materialDigests.add(value);
     return readRecord(path.join(root, 'records'), value);
   };
-  const checkpoint = reconstruct(head, collectRecords(root, head.runStepStateRootDigest), controlRecords, readMaterial);
+  const checkpoint = reconstruct(head, collectRecords(root, head.runStepStateRootDigest), controlRecords, readMaterial, config);
   if (digest(checkpoint) !== head.logicalDigest || checkpoint.instanceId !== head.instanceId || checkpoint.runId !== head.runId || checkpoint.version !== head.version || canonicalJson(checkpoint.definition) !== canonicalJson(head.definition)) throw new Error('Head and logical checkpoint differ.');
   const nodes: Record<string, StepMerkleNode> = {}; const leafByKey: Record<string, DefinitionStepDigest> = {}; const keyOrder: string[] = [];
   const visit = (value: DefinitionStepDigest): void => { if (nodes[value]) return; const node = readNode(path.join(root, 'trees'), value); nodes[value] = node; if (node.kind === 'leaf') { leafByKey[node.key] = value; keyOrder.push(node.key); } else { visit(node.leftDigest); visit(node.rightDigest); } };

package/src/checkpoint-store.ts

@@ -34,22 +34,38 @@ export interface WorkCtrlFlowCheckpointStoreOptions {
   readonly projectOutput?: (snapshot: WorkCtrlFlowSnapshot) => FlowClosedValue;
 }
 
-/** Removes optional undefined object fields without relaxing the closed-data validator. */
+/** Projects engine-owned faults and optional fields; business values remain subject to closed-data validation. */
 export function projectWorkCtrlSnapshotToCheckpointData(
   snapshot: WorkCtrlFlowSnapshot,
 ): WorkCtrlFlowSnapshot {
+  const projectState = (state: unknown): unknown => {
+    if (!state || typeof state !== 'object') return state;
+    const fault: unknown = Object.getOwnPropertyDescriptor(state,'fault')?.value;
+    if(!(fault instanceof Error))return state;
+    const code: unknown = Object.getOwnPropertyDescriptor(fault, 'code')?.value;
+    return { ...state, fault: { name: fault.name, message: fault.message, ...(typeof code === 'string' ? { code } : {}) } };
+  };
   const visit = (value: unknown): unknown => {
-    if (Array.isArray(value)) return value.map(visit);
+    if (Array.isArray(value)) {
+      if(Reflect.ownKeys(value).length!==value.length+1)return value;
+      const items:unknown[]=[];
+      for(let index=0;index<value.length;index++){
+        const descriptor=Object.getOwnPropertyDescriptor(value,String(index));
+        if(!descriptor||!('value'in descriptor))return value;
+        items.push(visit(descriptor.value));
+      }
+      return items;
+    }
     if (value === null || typeof value !== 'object') return value;
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null) return value;
-    return Object.fromEntries(
-      Object.entries(value)
-        .filter(([, nested]) => nested !== undefined)
-        .map(([key, nested]) => [key, visit(nested)]),
-    );
+    const descriptors=Object.getOwnPropertyDescriptors(value);
+    if(Reflect.ownKeys(value).some(key=>typeof key!=='string'||!('value'in descriptors[key]!)))return value;
+    return Object.fromEntries(Object.entries(descriptors).filter(([,descriptor])=>descriptor.value!==undefined).map(([key,descriptor])=>[key,visit(descriptor.value)]));
   };
-  return visit(snapshot) as WorkCtrlFlowSnapshot;
+  return visit({ ...snapshot, vars: { ...snapshot.vars, __flow_execution__: projectState(snapshot.vars.__flow_execution__) }, ...(snapshot.orchestration ? { orchestration: { ...snapshot.orchestration,
+    lanes: Object.fromEntries(Object.entries(snapshot.orchestration.lanes).map(([key, lane]) => [key, { ...lane, ...(lane.flowState === undefined ? {} : { flowState: projectState(lane.flowState) }) }])),
+  } } : {}) }) as WorkCtrlFlowSnapshot;
 }
 
 function workCtrlControllerSidecars(snapshot: WorkCtrlFlowSnapshot): FlowClosedObject {
@@ -283,6 +299,9 @@ function validateAIDataProfileTransition(
         `AI Data node ${nodeId} generation cannot decrease from ${node.generation} to ${candidate.generation}.`,
       );
     }
+    const waitContext=node.result&&typeof node.result==='object'?Object.getOwnPropertyDescriptor(node.result,'waitContext')?.value:undefined;
+    const nextContext=candidate.result&&typeof candidate.result==='object'?Object.getOwnPropertyDescriptor(candidate.result,'waitContext')?.value:undefined;
+    if(node.generation===candidate.generation&&waitContext!==undefined&&!sameClosedValue(waitContext,nextContext))throw new FlowRunCheckpointTransitionError(`AI Data native wait context ${nodeId}@${node.generation} is immutable.`);
   }
   const appendedPatches = after.patchHistory.slice(before.patchHistory.length);
   const appendedInvalidations = after.invalidations.filter((fact) =>
@@ -469,6 +488,7 @@ function validateAgentStateTransition(
     || (next.profile.kind !== 'AICtrlWorkflow' && next.profile.kind !== 'AIDataWorkflow')) return;
   const before = current.profile.ai;
   const after = next.profile.ai;
+  validateWorkflowDelegationTransition(before.delegationsByKey ?? {}, after.delegationsByKey ?? {});
   for (const [instanceId, instance] of Object.entries(before.instancesById)) {
     if (!sameClosedValue(instance, after.instancesById[instanceId])) {
       throw new FlowRunCheckpointTransitionError(`Accepted Agent instance ${instanceId} is immutable and cannot disappear.`);
@@ -553,9 +573,38 @@ export function validateFlowRunCheckpointTransition(
     );
   }
   validateStepExtensionTransition(current, next);
+  validateFrozenCtrlExpansion(current, next);
   validateAgentStateTransition(current, next);
 }
 
+function validateFrozenCtrlExpansion(current: AIWorkflowFlowRunCheckpoint, next: AIWorkflowFlowRunCheckpoint): void {
+  if (current.profile.kind === 'AIDataWorkflow' || next.profile.kind === 'AIDataWorkflow') return;
+  function object(value: FlowClosedValue | undefined): FlowClosedObject {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new FlowRunCheckpointTransitionError('Ctrl orchestration facts are missing.');
+    return value as FlowClosedObject;
+  }
+  const before = object(current.profile.snapshot.orchestration);
+  const after = object(next.profile.snapshot.orchestration);
+  const composites = object(before.composites);
+  const nextComposites = object(after.composites);
+  const lanes = object(before.lanes), nextLanes = object(after.lanes);
+  for (const [key, value] of Object.entries(composites)) {
+    const fact = object(value);
+    if (!fact.expansion) continue;
+    const candidate = object(nextComposites[key]);
+    if (!sameClosedValue(fact.expansion, candidate.expansion)) throw new FlowRunCheckpointTransitionError(`ForEach ${key} cannot rewrite frozen expansion.`);
+    for (const [laneKey, value] of Object.entries(lanes)) {
+      const lane = object(value);
+      if (lane.invocationKey !== key) continue;
+      const candidateLane = object(nextLanes[laneKey]);
+      for (const field of ['invocationKey', 'laneId', 'bodyId', 'item']) {
+        if (!sameClosedValue(lane[field], candidateLane[field])) throw new FlowRunCheckpointTransitionError(`ForEach ${key} cannot rewrite frozen lane ${laneKey}.${field}.`);
+      }
+      if (lane.started === true && candidateLane.started !== true) throw new FlowRunCheckpointTransitionError(`ForEach ${key} cannot release an unsettled lane slot by rewriting its claim.`);
+    }
+  }
+}
+
 function validateStepExtensionTransition(
   current: AIWorkflowFlowRunCheckpoint,
   next: AIWorkflowFlowRunCheckpoint,
@@ -656,3 +705,4 @@ export async function projectFlowRunCheckpoint(
   const checkpoint = await loadFlowRunCheckpoint(runtime, input);
   return checkpoint === undefined ? undefined : normalizeFlowRunCheckpoint(checkpoint);
 }
+import { validateWorkflowDelegationTransition } from './delegation.js';

package/src/core.ts

@@ -47,6 +47,7 @@ export {
 export {
   AIAgentInvocationError,
   bindAIAgentProcessors,
+  bindWorkflowNodeTasks,
   normalizeAIAgentEffectConfig,
   normalizeAIAgentInvocation,
   normalizeAIAgentSelector,
@@ -122,27 +123,7 @@ export function assertAIWorkflowSubstrate(
   }
 }
 
-export function defineAICtrlWorkflow(
-  definition: AICtrlWorkflowDefinitionBinding['definition'],
-): AICtrlWorkflowDefinitionBinding {
-  return Object.freeze({
-    kind: 'AICtrlWorkflow',
-    substrate: 'WorkCtrlFlow',
-    descriptor: AI_CTRL_WORKFLOW_DESCRIPTOR,
-    definition,
-  });
-}
-
-export function defineAIDataWorkflow(
-  definition: AIDataWorkflowDefinitionBinding['definition'],
-): AIDataWorkflowDefinitionBinding {
-  return Object.freeze({
-    kind: 'AIDataWorkflow',
-    substrate: 'EagerDataFlow',
-    descriptor: AI_DATA_WORKFLOW_DESCRIPTOR,
-    definition,
-  });
-}
+export { defineAICtrlWorkflow, defineAIDataWorkflow } from './definitions.js';
 
 export function projectAIWorkflowAppBundles(
   registry: AIWorkflowResourceRegistryView,

package/src/definitions.ts

@@ -0,0 +1,30 @@
+import type {
+  AICtrlWorkflowDefinitionBinding,
+  AIDataWorkflowDefinitionBinding,
+} from "ai-workflow-contract";
+import {
+  AI_CTRL_WORKFLOW_DESCRIPTOR,
+  AI_DATA_WORKFLOW_DESCRIPTOR,
+} from "ai-workflow-contract/profiles";
+
+export function defineAICtrlWorkflow(
+  definition: AICtrlWorkflowDefinitionBinding["definition"],
+): AICtrlWorkflowDefinitionBinding {
+  return Object.freeze({
+    kind: "AICtrlWorkflow",
+    substrate: "WorkCtrlFlow",
+    descriptor: AI_CTRL_WORKFLOW_DESCRIPTOR,
+    definition,
+  });
+}
+
+export function defineAIDataWorkflow(
+  definition: AIDataWorkflowDefinitionBinding["definition"],
+): AIDataWorkflowDefinitionBinding {
+  return Object.freeze({
+    kind: "AIDataWorkflow",
+    substrate: "EagerDataFlow",
+    descriptor: AI_DATA_WORKFLOW_DESCRIPTOR,
+    definition,
+  });
+}

package/src/delegation.ts

@@ -0,0 +1,387 @@
+import type {
+  AIAgentProcessorRuntime, AIWorkflowFlowRunCheckpoint, FlowClosedValue,
+  WorkflowTaskDelegation, WorkflowDelegationRequest, WorkflowDelegationObservation,
+  WorkflowDelegationRecord, WorkflowDelegationEffectPort, WorkflowDelegationOwnerTarget,
+} from 'ai-workflow-contract';
+import { normalizeFlowClosedValue } from './run-checkpoint.js';
+import { assertAIAgentNodeTaskBinding } from './agent-state.js';
+
+export class WorkflowDelegationError extends Error {
+  constructor(readonly code: string) { super(code); this.name = 'WorkflowDelegationError'; }
+}
+
+export class WorkflowDelegationSuspendedError extends Error {
+  constructor(readonly invocationKey: string, readonly status: string, readonly cause?: unknown) {
+    super(`Workflow delegation ${invocationKey} is ${status}; observe the original invocation.`);
+    this.name = 'WorkflowDelegationSuspendedError';
+  }
+}
+
+function assert(condition: unknown, code: string): asserts condition {
+  if (!condition) throw new WorkflowDelegationError(code);
+}
+function dataRecord(value: unknown): Record<string, FlowClosedValue> {
+  // Normalize before accessing properties: getters, symbols and non-data values are rejected.
+  const data = normalizeFlowClosedValue(value, 'delegation');
+  assert(data !== null && typeof data === 'object' && !Array.isArray(data), 'DELEGATION_OBJECT_REQUIRED');
+  return data as Record<string, FlowClosedValue>;
+}
+function object(value: unknown, required: string[], optional: string[] = []): Record<string, FlowClosedValue> {
+  const row = dataRecord(value);
+  assert(required.every(key => Object.hasOwn(row, key)) && Object.keys(row).every(key => [...required, ...optional].includes(key)), 'DELEGATION_FIELDS_INVALID');
+  return row;
+}
+function identity(value: unknown): asserts value is string {
+  assert(typeof value === 'string' && value.length > 0 && value.trim() === value && value.normalize('NFC') === value, 'DELEGATION_IDENTITY_INVALID');
+}
+function identityValue(value: unknown): string { identity(value); return value; }
+function integer(value: unknown): asserts value is number {
+  assert(Number.isSafeInteger(value) && (value as number) >= 0, 'DELEGATION_INTEGER_INVALID');
+}
+function same(a: unknown, b: unknown): boolean {
+  function sorted(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(sorted);
+    if (!value || typeof value !== 'object') return value;
+    const row = value as Record<string, unknown>;
+    return Object.fromEntries(Object.keys(row).sort().map(key => [key, sorted(row[key])]));
+  }
+  return JSON.stringify(sorted(a)) === JSON.stringify(sorted(b));
+}
+function target(value: unknown): WorkflowDelegationOwnerTarget {
+  const row = object(value, ['owner', 'providerScope', 'targetId']);
+  return Object.freeze({ owner: identityValue(row.owner), providerScope: identityValue(row.providerScope), targetId: identityValue(row.targetId) });
+}
+
+export function normalizeWorkflowDelegation(value: unknown): WorkflowTaskDelegation {
+  const row = object(value, ['kind', 'task', 'context', 'sessionPolicy', 'materials'], ['execution']);
+  assert(row.kind === 'workflow.task-delegation/v1', 'DELEGATION_KIND_INVALID');
+  const task = object(row.task, ['nodeId', 'agentDefinitionRef', 'input']);
+  identity(task.nodeId); identity(task.agentDefinitionRef);
+  assert(task.agentDefinitionRef.startsWith('resource://') && task.agentDefinitionRef.length > 11, 'DELEGATION_TASK_REF_INVALID');
+  const contextInput = object(row.context, ['mode'], ['owner', 'providerScope', 'targetId', 'nodeId']);
+  let context: WorkflowTaskDelegation['context'];
+  if (contextInput.mode === 'fresh') {
+    object(contextInput, ['mode', 'owner', 'providerScope']);
+    context = { mode: 'fresh', owner: identityValue(contextInput.owner), providerScope: identityValue(contextInput.providerScope) };
+  } else if (contextInput.mode === 'reuse') {
+    object(contextInput, ['mode', 'owner', 'providerScope', 'targetId']);
+    context = { mode: 'reuse', ...target({ owner: contextInput.owner, providerScope: contextInput.providerScope, targetId: contextInput.targetId }) };
+  } else {
+    object(contextInput, ['mode', 'nodeId']); assert(contextInput.mode === 'from-node', 'DELEGATION_CONTEXT_INVALID');
+    context = { mode: 'from-node', nodeId: identityValue(contextInput.nodeId) };
+  }
+  assert(row.sessionPolicy === 'shared' || row.sessionPolicy === 'independent-per-generation', 'DELEGATION_SESSION_POLICY_INVALID');
+  assert(row.sessionPolicy !== 'independent-per-generation' || context.mode === 'fresh', 'DELEGATION_INDEPENDENCE_REQUIRED');
+  assert(Array.isArray(row.materials) && row.materials.length <= 17, 'DELEGATION_MATERIALS_INVALID');
+  let total = 0;
+  const ids = new Set<string>();
+  let instructions = 0;
+  const materials = row.materials.map((item: unknown) => {
+    const material = object(item, ['id', 'role', 'ref', 'sha256', 'bytes']);
+    identity(material.id); identity(material.ref); identity(material.sha256); integer(material.bytes);
+    assert((material.role === 'instruction' || material.role === 'auxiliary') && /^[a-f0-9]{64}$/.test(material.sha256), 'DELEGATION_MATERIAL_INVALID');
+    assert(!ids.has(material.id) && material.bytes <= 1048576, 'DELEGATION_MATERIAL_LIMIT');
+    ids.add(material.id); total += material.bytes;
+    if (material.role === 'instruction') instructions++;
+    return Object.freeze({ id: material.id, ref: material.ref, sha256: material.sha256, bytes: material.bytes, role: material.role });
+  });
+  assert(instructions <= 1 && materials.length - instructions <= 16 && total <= 8388608, 'DELEGATION_MATERIAL_LIMIT');
+  const execution=Object.hasOwn(row,'execution')?normalizeFlowClosedValue(row.execution,'delegation.execution'):undefined;
+  if(execution!==undefined)assert(new TextEncoder().encode(JSON.stringify(execution)).length<=16384,'DELEGATION_EXECUTION_LIMIT');
+  return Object.freeze({ kind: row.kind, task: Object.freeze({ nodeId: task.nodeId, agentDefinitionRef: task.agentDefinitionRef as `resource://${string}`, input: task.input }), context: Object.freeze(context), sessionPolicy: row.sessionPolicy, materials: Object.freeze(materials),...(execution===undefined?{}:{execution}) });
+}
+
+function normalizeRequest(value: unknown): WorkflowDelegationRequest {
+  const row = object(value, ['delegation', 'lineage', 'attempt'], ['target']);
+  const lineage = object(row.lineage, ['instanceId', 'runId', 'nodeId', 'invocationKey', 'visit', 'generation'], ['sourceInvocationKey']);
+  for (const [key, value] of Object.entries(lineage)) key === 'generation' ? integer(value) : identity(value);
+  integer(lineage.generation);
+  integer(row.attempt);
+  const delegation = normalizeWorkflowDelegation(row.delegation);
+  assert(delegation.task.nodeId === lineage.nodeId, 'DELEGATION_LINEAGE_MISMATCH');
+  assert((delegation.context.mode === 'from-node') === Object.hasOwn(lineage, 'sourceInvocationKey'), 'DELEGATION_SOURCE_MISMATCH');
+  assert((delegation.context.mode !== 'fresh') === Object.hasOwn(row, 'target'), 'DELEGATION_TARGET_MISMATCH');
+  return { delegation, lineage: Object.freeze({
+    instanceId: identityValue(lineage.instanceId), runId: identityValue(lineage.runId), nodeId: identityValue(lineage.nodeId),
+    invocationKey: identityValue(lineage.invocationKey), visit: identityValue(lineage.visit), generation: lineage.generation,
+    ...(lineage.sourceInvocationKey === undefined ? {} : { sourceInvocationKey: identityValue(lineage.sourceInvocationKey) }),
+  }), attempt: row.attempt, ...(row.target === undefined ? {} : { target: target(row.target) }) };
+}
+
+export function normalizeWorkflowDelegationObservation(value: unknown, request: WorkflowDelegationRequest): WorkflowDelegationObservation {
+  const row = object(value, ['invocationKey', 'attempt', 'receiptId', 'status'], ['target', 'output', 'settled', 'reason']);
+  identity(row.receiptId);
+  assert(row.invocationKey === request.lineage.invocationKey && row.attempt === request.attempt, 'DELEGATION_RECEIPT_IDENTITY_MISMATCH');
+  if (row.status === 'completed') {
+    object(row, ['invocationKey', 'attempt', 'receiptId', 'status', 'target', 'output']);
+    const actual = target(row.target);
+    assertObservationTarget(actual, request);
+  } else if (row.status === 'failed') {
+    object(row, ['invocationKey', 'attempt', 'receiptId', 'status', 'target', 'settled', 'reason']);
+    assert(row.settled === true, 'DELEGATION_FAILURE_UNSETTLED'); identity(row.reason);
+    assertObservationTarget(target(row.target), request);
+  } else if (row.status === 'rejected' || row.status === 'not-dispatched') {
+    object(row, ['invocationKey', 'attempt', 'receiptId', 'status', 'settled', 'reason']);
+    assert(row.settled === true, 'DELEGATION_REJECTION_UNSETTLED'); identity(row.reason);
+  } else {
+    object(row, ['invocationKey', 'attempt', 'receiptId', 'status'], ['target']);
+    assert(['pending', 'busy', 'awaiting-user', 'unknown'].includes(identityValue(row.status)), 'DELEGATION_STATUS_INVALID');
+    if (row.target !== undefined) assertObservationTarget(target(row.target), request);
+  }
+  return Object.freeze(row) as WorkflowDelegationObservation;
+}
+
+function assertObservationTarget(actual: WorkflowDelegationOwnerTarget, request: WorkflowDelegationRequest): void {
+  if (request.target) assert(same(actual, request.target), 'DELEGATION_OWNER_TARGET_MISMATCH');
+  const context = request.delegation.context;
+  if (context.mode === 'fresh') assert(actual.owner === context.owner && actual.providerScope === context.providerScope, 'DELEGATION_OWNER_TARGET_MISMATCH');
+}
+
+export function normalizeWorkflowDelegations(value: unknown): Readonly<Record<string, WorkflowDelegationRecord>> {
+  const normalized = normalizeFlowClosedValue(value, 'delegationsByKey');
+  assert(normalized && typeof normalized === 'object' && !Array.isArray(normalized), 'DELEGATION_INDEX_INVALID');
+  const result: Record<string, WorkflowDelegationRecord> = {};
+  for (const key of Object.keys(normalized).sort()) {
+    identity(key);
+    const row = object(dataRecord(normalized)[key], ['attempts']);
+    assert(Array.isArray(row.attempts) && row.attempts.length > 0, 'DELEGATION_ATTEMPTS_REQUIRED');
+    const attempts = row.attempts.map((item: unknown, index: number) => {
+      const attempt = object(item, ['request', 'dispatchClaimed'], ['observation']);
+      assert(typeof attempt.dispatchClaimed === 'boolean' && (attempt.observation === undefined || attempt.dispatchClaimed), 'DELEGATION_DISPATCH_CLAIM_INVALID');
+      const request = normalizeRequest(attempt.request);
+      assert(request.attempt === index && request.lineage.invocationKey === key, 'DELEGATION_ATTEMPT_IDENTITY_MISMATCH');
+      return Object.freeze({ request, dispatchClaimed: attempt.dispatchClaimed, ...(attempt.observation === undefined ? {} : { observation: normalizeWorkflowDelegationObservation(attempt.observation, request) }) });
+    });
+    for (let index = 1; index < attempts.length; index++) {
+      const previous = attempts[index - 1];
+      assert(previous.observation?.status === 'rejected' || previous.observation?.status === 'not-dispatched', 'DELEGATION_RETRY_FORBIDDEN');
+      assert(same({ ...previous.request, attempt: index }, attempts[index].request), 'DELEGATION_RETRY_INTENT_CHANGED');
+    }
+    result[key] = Object.freeze({ attempts: Object.freeze(attempts) });
+  }
+  return Object.freeze(result);
+}
+
+export function validateWorkflowDelegationTransition(before: Readonly<Record<string, WorkflowDelegationRecord>>, after: Readonly<Record<string, WorkflowDelegationRecord>>): void {
+  for (const [key, record] of Object.entries(before)) {
+    const next = after[key];
+    assert(next && next.attempts.length >= record.attempts.length && next.attempts.length <= record.attempts.length + 1, 'DELEGATION_HISTORY_IMMUTABLE');
+    record.attempts.forEach((attempt, index) => {
+      const candidate = next.attempts[index]!;
+      assert(same(attempt.request, candidate.request), 'DELEGATION_RESERVATION_IMMUTABLE');
+      assert(!attempt.dispatchClaimed || candidate.dispatchClaimed, 'DELEGATION_DISPATCH_CLAIM_IMMUTABLE');
+      if (attempt.observation && ['completed', 'failed', 'rejected', 'not-dispatched'].includes(attempt.observation.status)) {
+        assert(same(attempt, candidate), 'DELEGATION_TERMINAL_IMMUTABLE');
+      }
+    });
+    if (next.attempts.length > record.attempts.length) assert(!next.attempts.at(-1)!.observation, 'DELEGATION_RESERVATION_REQUIRED');
+  }
+  for (const [key, record] of Object.entries(after)) if (!before[key]) {
+    assert(record.attempts.length === 1 && !record.attempts[0]!.observation, 'DELEGATION_RESERVATION_REQUIRED');
+  }
+}
+
+export interface WorkflowDelegationRuntime extends Omit<AIAgentProcessorRuntime, 'effects'> {
+  readonly effects: WorkflowDelegationEffectPort;
+  readonly visit: string;
+  readonly generation: number;
+  /** Native scheduler/admission projection, never supplied by authored task input. */
+  readonly dependencyInvocations: Readonly<Record<string, string>>;
+}
+
+async function load(runtime: WorkflowDelegationRuntime): Promise<AIWorkflowFlowRunCheckpoint> {
+  const checkpoint = await runtime.checkpointRuntime.checkpointStore.load(runtime.checkpointKey);
+  assert(checkpoint && checkpoint.instanceId === runtime.checkpointKey.instanceId && checkpoint.runId === runtime.checkpointKey.runId, 'DELEGATION_CHECKPOINT_MISSING');
+  assert(checkpoint.profile.kind === runtime.workflowKind && ['AICtrlWorkflow', 'AIDataWorkflow'].includes(checkpoint.profile.kind), 'DELEGATION_PROFILE_MISMATCH');
+  return checkpoint as AIWorkflowFlowRunCheckpoint;
+}
+function records(checkpoint: AIWorkflowFlowRunCheckpoint): Readonly<Record<string, WorkflowDelegationRecord>> {
+  assert(checkpoint.profile.kind === 'AICtrlWorkflow' || checkpoint.profile.kind === 'AIDataWorkflow', 'DELEGATION_PROFILE_MISMATCH');
+  return checkpoint.profile.ai.delegationsByKey ?? {};
+}
+
+/** Native loop frames and accepted data revisions establish serial order across visits.
+ * These identities come from the scheduler/checkpoint, never the authored task input.
+ * Same-visit sharing still requires the ordinary explicit predecessor relation.
+ */
+function isNativeSerialPredecessor(runtime: WorkflowDelegationRuntime, checkpoint: AIWorkflowFlowRunCheckpoint, previous: WorkflowDelegationRequest): boolean {
+  const before = previous.lineage;
+  if (before.instanceId !== checkpoint.instanceId || before.runId !== checkpoint.runId) return false;
+  if (checkpoint.profile.kind === 'AICtrlWorkflow') {
+    const frames = (visit: string, generation: number): { scope: string; loops: { key: string; iteration: number }[] } | undefined => {
+      let value: unknown;
+      try { value = JSON.parse(visit); } catch { return; }
+      if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== 'string' || !Array.isArray(value[1]) || !value[1].length) return;
+      const loops: { key: string; iteration: number }[] = [];
+      for (const item of value[1]) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) return;
+        const row = dataRecord(item);
+        if (Object.keys(row).length !== 2 || typeof row.key !== 'string' || !row.key || typeof row.iteration !== 'number' || !Number.isSafeInteger(row.iteration) || row.iteration < 0) return;
+        loops.push({ key: row.key, iteration: row.iteration });
+      }
+      if (loops.at(-1)!.iteration !== generation) return;
+      return { scope: value[0], loops };
+    };
+    const oldVisit = frames(before.visit, before.generation), currentVisit = frames(runtime.visit, runtime.generation);
+    if (!oldVisit || !currentVisit || oldVisit.scope !== currentVisit.scope || oldVisit.loops.length !== currentVisit.loops.length) return false;
+    if (oldVisit.loops.some((frame, index) => frame.key !== currentVisit.loops[index]!.key)) return false;
+    // An outer iteration also orders all of its inner iterations, even after an inner reset.
+    const changed = oldVisit.loops.findIndex((frame, index) => frame.iteration !== currentVisit.loops[index]!.iteration);
+    return changed >= 0 && oldVisit.loops[changed]!.iteration < currentVisit.loops[changed]!.iteration;
+  }
+  if (checkpoint.profile.kind === 'AIDataWorkflow') {
+    if (before.nodeId !== runtime.nodeId || before.generation >= runtime.generation || before.visit !== `generation:${before.generation}` || runtime.visit !== `generation:${runtime.generation}`) return false;
+    const graph = dataRecord(checkpoint.profile.runGraph), nodes = dataRecord(graph.nodes), node = dataRecord(nodes[runtime.nodeId]);
+    if (graph.currentGeneration !== runtime.generation || node.generation !== runtime.generation) return false;
+    // A number supplied by a caller is insufficient: require the persisted native revision
+    // which actually reopened this node, or its still-active reciprocal invalidation fact.
+    const invalidations = Array.isArray(graph.invalidations) ? graph.invalidations : [];
+    if (invalidations.some(value => { const fact = dataRecord(value); return fact.nodeId === runtime.nodeId && fact.generation === runtime.generation; })) return true;
+    const patches = Array.isArray(graph.patchHistory) ? graph.patchHistory : [];
+    return patches.some(value => {
+      const patch = dataRecord(value);
+      return patch.generation === runtime.generation && Array.isArray(patch.operations) && patch.operations.some(value => {
+        const operation = dataRecord(value);
+        return operation.op === 'update-node' && operation.nodeId === runtime.nodeId;
+      });
+    });
+  }
+  return false;
+}
+async function commit(runtime: WorkflowDelegationRuntime, checkpoint: AIWorkflowFlowRunCheckpoint, key: string, record: WorkflowDelegationRecord): Promise<void> {
+  assert(checkpoint.profile.kind === 'AICtrlWorkflow' || checkpoint.profile.kind === 'AIDataWorkflow', 'DELEGATION_PROFILE_MISMATCH');
+  await runtime.checkpointRuntime.checkpointStore.commit({ expectedVersion: checkpoint.version, checkpoint: {
+    ...checkpoint, version: checkpoint.version + 1,
+    profile: { ...checkpoint.profile, ai: { ...checkpoint.profile.ai, delegationsByKey: { ...records(checkpoint), [key]: record } } },
+  } });
+}
+
+/** A typed result is returned while pending; native adapters suspend rather than inventing output. */
+export async function delegateWorkflowTask(runtime: WorkflowDelegationRuntime, input: WorkflowTaskDelegation): Promise<WorkflowDelegationObservation> {
+  const delegation = normalizeWorkflowDelegation(input);
+  assert(delegation.task.nodeId === runtime.nodeId, 'DELEGATION_NODE_MISMATCH');
+  assertAIAgentNodeTaskBinding(runtime.taskBinding, { workflowKind: runtime.workflowKind, workflowRef: runtime.workflowRef, nodeId: runtime.nodeId }, { agentDefinitionRef: delegation.task.agentDefinitionRef });
+  identity(runtime.visit); integer(runtime.generation);
+  let checkpoint = await load(runtime);
+  // Target, policy, and materials are admitted with the immutable run config, not task input.
+  const binding = { ...delegation, task: { ...delegation.task, input: null } };
+  const bindings = dataRecord(dataRecord(checkpoint.config).workflowDelegations);
+  assert(same(bindings[runtime.nodeId], binding), 'DELEGATION_FROZEN_BINDING_MISMATCH');
+  const key = runtime.invocationKey;
+  let record = records(checkpoint)[key];
+  let request: WorkflowDelegationRequest;
+  let winner = false;
+  if (record) {
+    request = record.attempts.at(-1)!.request;
+    assert(same(request.delegation, delegation) && request.lineage.visit === runtime.visit && request.lineage.generation === runtime.generation && request.lineage.instanceId === checkpoint.instanceId && request.lineage.runId === checkpoint.runId && request.lineage.nodeId === runtime.nodeId, 'DELEGATION_INVOCATION_CONFLICT');
+  } else {
+    let sourceInvocationKey: string | undefined;
+    let selected: WorkflowDelegationOwnerTarget | undefined;
+    const context = delegation.context;
+    if (context.mode === 'reuse') selected = target({ owner: context.owner, providerScope: context.providerScope, targetId: context.targetId });
+    if (context.mode === 'from-node') {
+      sourceInvocationKey = runtime.dependencyInvocations[context.nodeId];
+      assert(sourceInvocationKey && context.nodeId !== runtime.nodeId, 'DELEGATION_DEPENDENCY_REQUIRED');
+      const source = records(checkpoint)[sourceInvocationKey]?.attempts.at(-1);
+      assert(source?.observation?.status === 'completed' && source.request.lineage.nodeId === context.nodeId, 'DELEGATION_SOURCE_UNFINISHED');
+      assert(source.request.lineage.instanceId === checkpoint.instanceId && source.request.lineage.runId === checkpoint.runId, 'DELEGATION_SOURCE_SCOPE_MISMATCH');
+      assert(source.request.lineage.generation === runtime.generation && source.request.lineage.visit === runtime.visit, 'DELEGATION_SOURCE_STALE');
+      assert(source.request.delegation.sessionPolicy !== 'independent-per-generation', 'DELEGATION_INDEPENDENCE_REQUIRED');
+      selected = source.observation.target;
+    }
+    for (const existing of Object.values(records(checkpoint))) {
+      const last = existing.attempts.at(-1)!;
+      const terminal = last.observation && ['completed', 'failed', 'rejected', 'not-dispatched'].includes(last.observation.status);
+      const actual = last.observation && 'target' in last.observation ? last.observation.target ?? last.request.target : last.request.target;
+      if (selected && actual && same(selected, actual)) {
+        assert(terminal && (Object.values(runtime.dependencyInvocations).includes(last.request.lineage.invocationKey) || isNativeSerialPredecessor(runtime, checkpoint, last.request)), 'DELEGATION_SHARED_TARGET_CONCURRENT');
+      }
+    }
+    request = normalizeRequest({ delegation, lineage: { ...runtime.checkpointKey, nodeId: runtime.nodeId, invocationKey: key, visit: runtime.visit, generation: runtime.generation, ...(sourceInvocationKey ? { sourceInvocationKey } : {}) }, attempt: 0, ...(selected ? { target: selected } : {}) });
+    record = { attempts: [{ request, dispatchClaimed: false }] };
+    await runtime.effects.verifyMaterials(delegation.materials);
+    try { await commit(runtime, checkpoint, key, record); }
+    catch (error) {
+      const latest = await load(runtime);
+      const accepted = records(latest)[key];
+      if (!accepted || !same(accepted.attempts.at(-1)!.request, request)) throw error;
+      record = accepted;
+    }
+  }
+  const last = record.attempts.at(-1)!;
+  if (last.observation && ['completed', 'failed', 'rejected', 'not-dispatched'].includes(last.observation.status)) return last.observation;
+  await runtime.effects.verifyMaterials(delegation.materials);
+  if (!last.dispatchClaimed) {
+    checkpoint = await load(runtime);
+    record = records(checkpoint)[key]!;
+    if (!record.attempts.at(-1)!.dispatchClaimed) {
+      const claimed = { attempts: [...record.attempts.slice(0, -1), { ...record.attempts.at(-1)!, dispatchClaimed: true }] };
+      try { await commit(runtime, checkpoint, key, claimed); winner = true; }
+      catch (error) {
+        const accepted = records(await load(runtime))[key]?.attempts.at(-1);
+        if (!accepted?.dispatchClaimed || !same(accepted.request, request)) throw error;
+      }
+    }
+  }
+  // A lost submit receipt is uncertain. Never call submit again on recovery.
+  let response: WorkflowDelegationObservation;
+  try { response = await (winner ? runtime.effects.submit(request) : runtime.effects.observe(request)); }
+  catch (cause) { throw new WorkflowDelegationSuspendedError(key, 'unknown', cause); }
+  const observation = normalizeWorkflowDelegationObservation(response, request);
+  checkpoint = await load(runtime);
+  record = records(checkpoint)[key]!;
+  const latest = record.attempts.at(-1)!;
+  if (latest.observation && ['completed', 'failed', 'rejected', 'not-dispatched'].includes(latest.observation.status)) return latest.observation;
+  assert(same(latest.request, request), 'DELEGATION_ATTEMPT_CHANGED');
+  if (observation.status === 'completed' && delegation.context.mode === 'fresh') {
+    for (const [otherKey, other] of Object.entries(records(checkpoint))) {
+      if (otherKey === key) continue;
+      for (const attempt of other.attempts) {
+        assert(attempt.observation?.status !== 'completed' || !same(attempt.observation.target, observation.target), 'DELEGATION_FRESH_CONTEXT_REUSED');
+      }
+    }
+  }
+  const updated = { attempts: [...record.attempts.slice(0, -1), { request, dispatchClaimed: true, observation }] };
+  try { await commit(runtime, checkpoint, key, updated); }
+  catch (error) {
+    const accepted = records(await load(runtime))[key]?.attempts.at(-1)?.observation;
+    if (!accepted || !same(accepted, observation)) throw error;
+  }
+  return observation;
+}
+
+/** Explicit audited retry reservation. It never dispatches and never rewrites the failed attempt. */
+export async function prepareWorkflowDelegationRetry(runtime: WorkflowDelegationRuntime, input: { expectedVersion: number; invocationKey: string; receiptId: string }): Promise<void> {
+  const checkpoint = await load(runtime);
+  assert(checkpoint.version === input.expectedVersion && input.invocationKey === runtime.invocationKey, 'DELEGATION_RETRY_CAS_MISMATCH');
+  const record = records(checkpoint)[input.invocationKey];
+  const last = record?.attempts.at(-1);
+  assert(last && last.observation && ['rejected', 'not-dispatched'].includes(last.observation.status) && last.observation.receiptId === input.receiptId, 'DELEGATION_RETRY_FORBIDDEN');
+  await commit(runtime, checkpoint, input.invocationKey, { attempts: [...record!.attempts, { request: { ...last.request, attempt: last.request.attempt + 1 }, dispatchClaimed: false }] });
+}
+
+/** Bound by native node adapters. Authored code supplies only this task's business input. */
+export function bindWorkflowTaskDelegation(runtime: Omit<WorkflowDelegationRuntime, 'dependencyInvocations'>): { delegateTask(input: FlowClosedValue): Promise<FlowClosedValue> } {
+  return Object.freeze({ async delegateTask(input: FlowClosedValue): Promise<FlowClosedValue> {
+    const checkpoint = await load({ ...runtime, dependencyInvocations: {} });
+    const config = dataRecord(checkpoint.config);
+    const binding = dataRecord(config.workflowDelegations)[runtime.nodeId];
+    assert(binding, 'DELEGATION_FROZEN_BINDING_MISSING');
+    const dependencies = (config.workflowDelegationDependencies === undefined ? {} : dataRecord(config.workflowDelegationDependencies))[runtime.nodeId] ?? [];
+    assert(Array.isArray(dependencies) && dependencies.every((id: unknown) => typeof id === 'string'), 'DELEGATION_DEPENDENCIES_INVALID');
+    const dependencyInvocations: Record<string, string> = {};
+    for (const nodeId of dependencies.map((id: unknown) => identityValue(id))) {
+      const matches = Object.values(records(checkpoint)).map(record => record.attempts.at(-1)!).filter(attempt => attempt.request.lineage.nodeId === nodeId && attempt.request.lineage.generation === runtime.generation && attempt.request.lineage.visit === runtime.visit);
+      assert(matches.length <= 1, 'DELEGATION_SOURCE_AMBIGUOUS');
+      if (matches.length === 1) dependencyInvocations[nodeId] = matches[0]!.request.lineage.invocationKey;
+    }
+    const normalizedBinding = normalizeWorkflowDelegation(binding);
+    // 已存在的调用沿保存的原lineage观察；新的循环寻址不能改写旧恢复身份。
+    const original = records(checkpoint)[runtime.invocationKey]?.attempts.at(-1)?.request;
+    const admittedRuntime = original ? { ...runtime, visit: original.lineage.visit, generation: original.lineage.generation } : runtime;
+    const observation = await delegateWorkflowTask({ ...admittedRuntime, dependencyInvocations }, { ...normalizedBinding, task: { ...normalizedBinding.task, input } });
+    if(observation.status==='failed')throw new WorkflowDelegationError(`DELEGATION_OWNER_FAILED:${observation.reason}`);
+    if (observation.status !== 'completed') throw new WorkflowDelegationSuspendedError(runtime.invocationKey, observation.status);
+    return observation.output;
+  } });
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './core.js';
+export * from './delegation.js';
 export { resolveAIAgentExecutionResources } from './agent-execution-resources.js';
 export type { AIAgentExecutionResourceObservation, ResolveAIAgentExecutionResourcesRuntime, ResolveAIAgentExecutionResourcesInput } from './agent-execution-resources.js';
 export {

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.');
   }