ai-workflow-logic 0.2.0 → 0.2.2

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-resources.ts

@@ -25,6 +25,7 @@ import type {
 } from 'halfcode-compiler.xnl/resource-core';
 import { markAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
 import { AIWorkflowResourceProjectionError } from './errors.js';
+import { projectAIAgentCodeResources } from './agent-code-projection.js';
 
 const AGENT_SUBDOMAINS = Object.freeze([
   'Messages',
@@ -43,6 +44,7 @@ export function projectAIWorkflowAgentResources(
   const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
   const resources = buildResourceIndex(registry, diagnostics);
   const edges: ResourceDependencyEdge[] = [];
+  const codeResources = projectAIAgentCodeResources(resources, edges);
 
   const materialPorts = recordsForKind(registry, 'MaterialPort')
     .map((resource) => projectMaterialPort(resource, resources, edges, diagnostics))
@@ -60,6 +62,7 @@ export function projectAIWorkflowAgentResources(
 
   if (diagnostics.length > 0) throwProjectionError(diagnostics);
   return markAIWorkflowAgentResourceProjection(Object.freeze({
+    codeResources,
     agentDefinitions: Object.freeze(agentDefinitions),
     materialPorts: Object.freeze(materialPorts),
     materialBindings: Object.freeze(materialBindings),

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/browser.ts

@@ -1 +1 @@
-export * from './index.js';
+export * from './core.js';

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';