ai-data-workflow-logic 0.1.12 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-data-workflow-logic",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "private": false,
   "description": "EagerDataFlow-backed AI Data Workflow RunGraph helpers",
   "type": "module",
@@ -11,15 +11,15 @@
     "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "ai-data-workflow-contract": "0.1.6",
-    "ai-workflow-contract": "0.1.8",
-    "ai-workflow-logic": "0.1.9",
-    "eager-data-flow-contract": "0.1.3",
-    "eager-data-flow-logic": "0.1.5",
+    "ai-data-workflow-contract": "0.2.0",
+    "ai-workflow-contract": "0.2.0",
+    "ai-workflow-logic": "0.2.0",
+    "eager-data-flow-contract": "0.1.4",
+    "eager-data-flow-logic": "0.1.7",
     "flow-step-space-logic": "0.1.1",
     "task-manager-contract": "0.1.3",
     "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-logic": "0.1.4"
+    "work-ctrl-flow-logic": "0.1.5"
   },
   "files": [
     "src"

package/src/autonomous-control.ts

@@ -21,6 +21,7 @@ import {
   type AIDataWorkflowNodeInputs,
   type AIDataWorkflowRunGraph,
   type AIDataWorkflowRunNode,
+  type AIDataWorkflowSubFlowBinding,
 } from 'ai-data-workflow-contract';
 import type { EagerDataFlowValue } from 'eager-data-flow-contract';
 
@@ -239,13 +240,20 @@ function assertResourceRef(value: unknown, location: string): void {
   }
 }
 
+function assertEagerDataFlowRef(value: unknown, location: string): void {
+  assertNonEmptyString(value, location);
+  if (!value.startsWith('eager-data-flow://') || value.length === 'eager-data-flow://'.length) {
+    fail('AI_DATA_CONTROL_FLOW_REF', `${location} must be an exact eager-data-flow:// reference.`);
+  }
+}
+
 function assertCapability(capability: AIDataControlCapability, key: string): void {
   assertNonEmptyString(capability.capabilityId, `capabilities.${key}.capabilityId`);
   if (capability.capabilityId !== key) {
     fail('AI_DATA_CONTROL_CAPABILITY_ID', `Capability key ${key} must equal capabilityId ${capability.capabilityId}.`);
   }
-  if (capability.tag !== 'TransformNode' && capability.tag !== 'SinkNode') {
-    fail('AI_DATA_CONTROL_CAPABILITY_TAG', `Capability ${key} must use TransformNode or SinkNode.`);
+  if (capability.tag !== 'TransformNode' && capability.tag !== 'SinkNode' && capability.tag !== 'SubFlowNode') {
+    fail('AI_DATA_CONTROL_CAPABILITY_TAG', `Capability ${key} must use TransformNode, SinkNode or SubFlowNode.`);
   }
   assertNonEmptyString(capability.nodeType, `capabilities.${key}.nodeType`);
   assertSchemaMap(capability.inputSchemaRefs, `capabilities.${key}.inputSchemaRefs`);
@@ -260,10 +268,36 @@ function assertCapability(capability: AIDataControlCapability, key: string): voi
     fail('AI_DATA_CONTROL_CAPABILITY_CONFIG', `Capability ${key} fixedConfig uses reserved control keys.`);
   }
   if (capability.implementation.kind === 'code') {
+    if (capability.tag === 'SubFlowNode') {
+      fail('AI_DATA_CONTROL_CAPABILITY_IMPLEMENTATION', `SubFlow capability ${key} must use a subflow implementation.`);
+    }
     assertResourceRef(capability.implementation.codeRef, `capabilities.${key}.implementation.codeRef`);
   } else if (capability.implementation.kind === 'agent') {
+    if (capability.tag === 'SubFlowNode') {
+      fail('AI_DATA_CONTROL_CAPABILITY_IMPLEMENTATION', `SubFlow capability ${key} must use a subflow implementation.`);
+    }
     assertResourceRef(capability.implementation.agentDefinitionRef, `capabilities.${key}.implementation.agentDefinitionRef`);
     assertResourceRef(capability.implementation.taskProofRef, `capabilities.${key}.implementation.taskProofRef`);
+  } else if (capability.implementation.kind === 'subflow') {
+    if (capability.tag !== 'SubFlowNode' || capability.nodeType !== 'subflow') {
+      fail('AI_DATA_CONTROL_CAPABILITY_IMPLEMENTATION', `Subflow implementation ${key} requires SubFlowNode/subflow.`);
+    }
+    assertResourceRef(capability.implementation.definitionRef, `capabilities.${key}.implementation.definitionRef`);
+    assertEagerDataFlowRef(capability.implementation.flowRef, `capabilities.${key}.implementation.flowRef`);
+    assertNonEmptyString(capability.implementation.contractDigest, `capabilities.${key}.implementation.contractDigest`);
+    assertNonEmptyString(capability.implementation.callGraphDigest, `capabilities.${key}.implementation.callGraphDigest`);
+    if (!Array.isArray(capability.implementation.transitiveChildFlowRefs)) {
+      fail('AI_DATA_CONTROL_CALL_GRAPH', `capabilities.${key}.implementation.transitiveChildFlowRefs must be an array.`);
+    }
+    const childRefs = capability.implementation.transitiveChildFlowRefs;
+    childRefs.forEach((ref, index) => assertEagerDataFlowRef(
+      ref,
+      `capabilities.${key}.implementation.transitiveChildFlowRefs[${index}]`,
+    ));
+    if (new Set(childRefs).size !== childRefs.length
+      || childRefs.some((ref, index) => index > 0 && compareCodeUnits(childRefs[index - 1]!, ref) >= 0)) {
+      fail('AI_DATA_CONTROL_CALL_GRAPH', `capabilities.${key}.implementation.transitiveChildFlowRefs must be unique and sorted.`);
+    }
   } else {
     fail('AI_DATA_CONTROL_CAPABILITY_IMPLEMENTATION', `Capability ${key} has an unknown implementation kind.`);
   }
@@ -516,6 +550,17 @@ function normalizeRevisionOperation(
       ...(dependsOn === undefined ? {} : { dependsOn }),
     };
   }
+  if (value.op === 'add-subflow' || value.op === 'rewire-subflow') {
+    const record = exactRecord(value, ['op', 'nodeId', 'subflowCapabilityId', 'inputs'], ['dependsOn'], location);
+    const dependsOn = normalizeDependsOn(record.dependsOn, `${location}.dependsOn`);
+    return {
+      op: value.op,
+      nodeId: stringField(record, 'nodeId', location),
+      subflowCapabilityId: stringField(record, 'subflowCapabilityId', location),
+      inputs: normalizeInputs(runtime, record.inputs, `${location}.inputs`),
+      ...(dependsOn === undefined ? {} : { dependsOn }),
+    };
+  }
   fail('AI_DATA_CONTROL_DECISION_SHAPE', `${location}.op is unsupported.`);
 }
 
@@ -836,7 +881,7 @@ function nodeContracts(
 
 function validateInputs(
   runtime: AIDataControlRuntime,
-  operation: Extract<AIDataControlRevisionOperation, { op: 'add-capability' | 'rewire-capability' }>,
+  operation: Exclude<AIDataControlRevisionOperation, { op: 'remove-node' }>,
   capability: AIDataControlCapability,
   contracts: ReadonlyMap<string, MutableNodeContract>,
   operationIndex: number,
@@ -969,6 +1014,7 @@ function capabilityConfig(
   if (capability.implementation.kind === 'code') {
     return { ...base, src: capability.implementation.codeRef };
   }
+  if (capability.implementation.kind === 'subflow') return base;
   return {
     ...base,
     agent: {
@@ -978,8 +1024,24 @@ function capabilityConfig(
   };
 }
 
+function capabilitySubflowBinding(
+  capability: AIDataControlCapability,
+  catalog: AIDataControlCapabilityCatalog,
+): AIDataWorkflowSubFlowBinding | undefined {
+  if (capability.implementation.kind !== 'subflow') return undefined;
+  return {
+    kind: 'autonomous',
+    schemaVersion: 'depa.ai-data-subflow-binding/v1',
+    capabilityId: capability.capabilityId,
+    catalogDigest: catalog.digest,
+    definitionRef: capability.implementation.definitionRef,
+    flowRef: capability.implementation.flowRef,
+    contractDigest: capability.implementation.contractDigest,
+  };
+}
+
 function operationDependencies(
-  operation: Extract<AIDataControlRevisionOperation, { op: 'add-capability' | 'rewire-capability' }>,
+  operation: Exclude<AIDataControlRevisionOperation, { op: 'remove-node' }>,
 ): readonly string[] {
   return [...new Set([
     ...(operation.dependsOn ?? []),
@@ -998,6 +1060,7 @@ function sameNodeRevision(
     inputs: node.inputs,
     outputs: node.outputs,
     config: node.config,
+    subflow: node.subflow ?? null,
     dependsOn: node.dependsOn,
   }) === runtime.stableDigest({
     tag: operation.changes.tag ?? node.tag,
@@ -1005,6 +1068,9 @@ function sameNodeRevision(
     inputs: operation.changes.inputs ?? node.inputs,
     outputs: operation.changes.outputs ?? node.outputs,
     config: operation.changes.config ?? node.config,
+    subflow: (Object.prototype.hasOwnProperty.call(operation.changes, 'subflow')
+      ? operation.changes.subflow
+      : node.subflow) ?? null,
     dependsOn: operation.changes.dependsOn ?? node.dependsOn,
   });
 }
@@ -1160,7 +1226,7 @@ function admitNormalizedAIDataControlDecision(
 
   const targets = new Set<string>();
   for (let index = 0; index < input.decision.operations.length; index += 1) {
-    const operation = input.decision.operations[index]!;
+    const operation: AIDataControlRevisionOperation = input.decision.operations[index]!;
     if (targets.has(operation.nodeId)) {
       return rejected(runtime, input.decision, [
         feedback('DUPLICATE_TARGET', `Revision targets ${operation.nodeId} more than once.`, {
@@ -1181,7 +1247,7 @@ function admitNormalizedAIDataControlDecision(
   const removed = new Set<string>();
 
   for (let index = 0; index < input.decision.operations.length; index += 1) {
-    const operation = input.decision.operations[index]!;
+    const operation: AIDataControlRevisionOperation = input.decision.operations[index]!;
     const existingContract = contracts.get(operation.nodeId);
     if (operation.op === 'remove-node') {
       if (!existingContract || existingContract.removed) {
@@ -1202,13 +1268,15 @@ function admitNormalizedAIDataControlDecision(
       continue;
     }
 
-    if (operation.op === 'add-capability' && existingContract) {
+    const isAdd = operation.op === 'add-capability' || operation.op === 'add-subflow';
+    const isRewire = operation.op === 'rewire-capability' || operation.op === 'rewire-subflow';
+    if (isAdd && existingContract) {
       return rejected(runtime, input.decision, [feedback('INVALID_DECISION', `Node ${operation.nodeId} already exists.`, {
         operationIndex: index,
         nodeId: operation.nodeId,
       })]);
     }
-    if (operation.op === 'rewire-capability') {
+    if (isRewire) {
       if (!existingContract || existingContract.removed) {
         return rejected(runtime, input.decision, [feedback('UNKNOWN_NODE', `Node ${operation.nodeId} is not active.`, {
           operationIndex: index,
@@ -1223,15 +1291,37 @@ function admitNormalizedAIDataControlDecision(
       }
     }
 
-    const capability = input.catalog.capabilities[operation.capabilityId];
+    const capabilityId = operation.op === 'add-subflow' || operation.op === 'rewire-subflow'
+      ? operation.subflowCapabilityId
+      : operation.capabilityId;
+    const capability = input.catalog.capabilities[capabilityId];
     if (!capability) {
-      return rejected(runtime, input.decision, [feedback('UNKNOWN_CAPABILITY', `Capability ${operation.capabilityId} is not frozen.`, {
+      return rejected(runtime, input.decision, [feedback('UNKNOWN_CAPABILITY', `Capability ${capabilityId} is not frozen.`, {
         operationIndex: index,
         nodeId: operation.nodeId,
       })]);
     }
+    const expectsSubflow = operation.op === 'add-subflow' || operation.op === 'rewire-subflow';
+    if (expectsSubflow !== (capability.implementation.kind === 'subflow')) {
+      return rejected(runtime, input.decision, [feedback(
+        'INVALID_DECISION',
+        `Operation ${operation.op} does not match frozen capability ${capabilityId}.`,
+        { operationIndex: index, nodeId: operation.nodeId },
+      )]);
+    }
     const inputProblem = validateInputs(runtime, operation, capability, contracts, index);
     if (inputProblem) return rejected(runtime, input.decision, [inputProblem]);
+    if (capability.implementation.kind === 'subflow') {
+      const parentFlowRef = `eager-data-flow://${input.graph.binding.definition.fqn}` as `eager-data-flow://${string}`;
+      if (capability.implementation.flowRef === parentFlowRef
+        || capability.implementation.transitiveChildFlowRefs.includes(parentFlowRef)) {
+        return rejected(runtime, input.decision, [feedback(
+          'RECURSIVE_SUBFLOW',
+          `Subflow capability ${capability.capabilityId} would recurse into ${parentFlowRef}.`,
+          { operationIndex: index, nodeId: operation.nodeId },
+        )]);
+      }
+    }
     const dependsOn = operationDependencies(operation);
     for (const dependency of dependsOn) {
       const dependencyContract = contracts.get(dependency);
@@ -1242,6 +1332,7 @@ function admitNormalizedAIDataControlDecision(
         })]);
       }
     }
+    const subflow = capabilitySubflowBinding(capability, input.catalog);
     const nodeFacts = {
       tag: capability.tag,
       nodeType: capability.nodeType,
@@ -1250,16 +1341,16 @@ function admitNormalizedAIDataControlDecision(
       config: capabilityConfig(capability, input.catalog),
       dependsOn,
     };
-    if (operation.op === 'add-capability') {
+    if (isAdd) {
       patchOperations.push({
         op: 'add-node',
-        node: { id: operation.nodeId, ...nodeFacts },
+        node: { id: operation.nodeId, ...nodeFacts, ...(subflow ? { subflow } : {}) },
       });
     } else {
       patchOperations.push({
         op: 'update-node',
         nodeId: operation.nodeId,
-        changes: nodeFacts,
+        changes: { ...nodeFacts, subflow: subflow ?? null },
       });
     }
     contracts.set(operation.nodeId, {

package/src/child-invocation.ts

@@ -0,0 +1,376 @@
+import type {
+  AIDataWorkflowAutonomousSubFlowBinding,
+  AIDataWorkflowChildFreezeReceipt,
+  AIDataWorkflowChildInvocationIdentity,
+  AIDataWorkflowChildInvocationObservation,
+  AIDataWorkflowChildTerminalReceipt,
+  AIDataWorkflowRunGraph,
+} from 'ai-data-workflow-contract';
+import { AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION } from 'ai-data-workflow-contract';
+import { normalizeFlowClosedObject } from 'ai-workflow-logic';
+
+export class AIDataWorkflowChildInvocationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AIDataWorkflowChildInvocationError';
+  }
+}
+
+function fnv1a64(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= BigInt(value.charCodeAt(index));
+    hash = (hash * prime) & mask;
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+const compareCodeUnits = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
+
+function record(value: unknown, keys: readonly string[], location: string): Readonly<Record<string, unknown>> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new AIDataWorkflowChildInvocationError(`${location} must be an object.`);
+  }
+  const input = value as Readonly<Record<string, unknown>>;
+  const actual = Object.keys(input).sort(compareCodeUnits);
+  const expected = [...keys].sort(compareCodeUnits);
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new AIDataWorkflowChildInvocationError(`${location} fields are invalid.`);
+  }
+  return input;
+}
+
+function nonEmpty(value: unknown, location: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new AIDataWorkflowChildInvocationError(`${location} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function prefixed(value: unknown, prefix: string, location: string): string {
+  const normalized = nonEmpty(value, location);
+  if (!normalized.startsWith(prefix) || normalized.length === prefix.length) {
+    throw new AIDataWorkflowChildInvocationError(`${location} must start with ${prefix}.`);
+  }
+  return normalized;
+}
+
+function schema(value: unknown, location: string): void {
+  if (value !== AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION) {
+    throw new AIDataWorkflowChildInvocationError(`${location} uses an unsupported schema version.`);
+  }
+}
+
+function normalizeSubflow(value: unknown, location: string): AIDataWorkflowAutonomousSubFlowBinding {
+  const input = record(value, [
+    'kind', 'schemaVersion', 'capabilityId', 'catalogDigest', 'definitionRef', 'flowRef', 'contractDigest',
+  ], location);
+  if (input.kind !== 'autonomous' || input.schemaVersion !== 'depa.ai-data-subflow-binding/v1') {
+    throw new AIDataWorkflowChildInvocationError(`${location} must be an autonomous subflow binding.`);
+  }
+  return Object.freeze({
+    kind: 'autonomous',
+    schemaVersion: 'depa.ai-data-subflow-binding/v1',
+    capabilityId: nonEmpty(input.capabilityId, `${location}.capabilityId`),
+    catalogDigest: nonEmpty(input.catalogDigest, `${location}.catalogDigest`),
+    definitionRef: prefixed(input.definitionRef, 'resource://', `${location}.definitionRef`) as `resource://${string}`,
+    flowRef: prefixed(input.flowRef, 'eager-data-flow://', `${location}.flowRef`) as `eager-data-flow://${string}`,
+    contractDigest: nonEmpty(input.contractDigest, `${location}.contractDigest`),
+  });
+}
+
+function sameSubflow(
+  left: AIDataWorkflowAutonomousSubFlowBinding,
+  right: AIDataWorkflowAutonomousSubFlowBinding,
+): boolean {
+  return left.kind === right.kind
+    && left.schemaVersion === right.schemaVersion
+    && left.capabilityId === right.capabilityId
+    && left.catalogDigest === right.catalogDigest
+    && left.definitionRef === right.definitionRef
+    && left.flowRef === right.flowRef
+    && left.contractDigest === right.contractDigest;
+}
+
+export function createAIDataWorkflowChildInvocationIdentity(input: {
+  readonly graph: AIDataWorkflowRunGraph;
+  readonly parentInstanceId: string;
+  readonly nodeId: string;
+}): AIDataWorkflowChildInvocationIdentity {
+  const node = input.graph.nodes[input.nodeId];
+  if (!node || node.tag !== 'SubFlowNode' || node.subflow?.kind !== 'autonomous') {
+    throw new AIDataWorkflowChildInvocationError(
+      `AI Data Workflow node ${input.nodeId} is not an autonomous SubFlowNode.`,
+    );
+  }
+  const canonical = JSON.stringify([
+    input.parentInstanceId,
+    input.graph.runId,
+    node.id,
+    node.generation,
+    node.subflow.capabilityId,
+    node.subflow.catalogDigest,
+    node.subflow.definitionRef,
+    node.subflow.flowRef,
+    node.subflow.contractDigest,
+  ]);
+  const suffix = fnv1a64(canonical);
+  return normalizeAIDataWorkflowChildInvocationIdentity({
+    schemaVersion: AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION,
+    invocationKey: `ai-data-child:${suffix}`,
+    parentInstanceId: input.parentInstanceId,
+    parentRunId: input.graph.runId,
+    parentNodeId: node.id,
+    parentGeneration: node.generation,
+    childInstanceId: `${input.parentInstanceId}--child-${suffix}`,
+    childRunId: `${input.graph.runId}--child-${suffix}`,
+    subflow: node.subflow,
+  });
+}
+
+/** Pure parent-side reservation. A differing winner is rejected; an exact retry is idempotent. */
+export function reserveAIDataWorkflowChildInvocation(input: {
+  readonly graph: AIDataWorkflowRunGraph;
+  readonly identity: AIDataWorkflowChildInvocationIdentity;
+}): AIDataWorkflowRunGraph {
+  const identity = normalizeAIDataWorkflowChildInvocationIdentity(input.identity);
+  const node = input.graph.nodes[identity.parentNodeId];
+  if (!node || node.tag !== 'SubFlowNode' || node.subflow?.kind !== 'autonomous') {
+    throw new AIDataWorkflowChildInvocationError(
+      `AI Data Workflow node ${identity.parentNodeId} is not an autonomous SubFlowNode.`,
+    );
+  }
+  if (input.graph.runId !== identity.parentRunId || node.generation !== identity.parentGeneration
+    || !sameSubflow(node.subflow, identity.subflow)) {
+    throw new AIDataWorkflowChildInvocationError('Child invocation reservation does not match the current parent generation.');
+  }
+  if (node.status === 'Succeeded' || node.status === 'Failed' || node.status === 'Reused' || node.status === 'Removed') {
+    throw new AIDataWorkflowChildInvocationError(`Cannot reserve a child for terminal node ${node.id}.`);
+  }
+  if (node.childInvocation) {
+    const current = normalizeAIDataWorkflowChildInvocationIdentity(node.childInvocation);
+    if (JSON.stringify(current) !== JSON.stringify(identity)) {
+      throw new AIDataWorkflowChildInvocationError(`Node ${node.id} already reserved another child invocation.`);
+    }
+    return input.graph;
+  }
+  return Object.freeze({
+    ...input.graph,
+    nodes: Object.freeze({
+      ...input.graph.nodes,
+      [node.id]: Object.freeze({
+        ...node,
+        status: 'Running' as const,
+        childInvocation: identity,
+      }),
+    }),
+  });
+}
+
+export function recordAIDataWorkflowChildFreezeReceipt(input: {
+  readonly graph: AIDataWorkflowRunGraph;
+  readonly nodeId: string;
+  readonly receipt: AIDataWorkflowChildFreezeReceipt;
+}): AIDataWorkflowRunGraph {
+  const node = input.graph.nodes[input.nodeId];
+  if (!node?.childInvocation) {
+    throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} has no reserved child invocation.`);
+  }
+  const receipt = normalizeAIDataWorkflowChildFreezeReceipt(input.receipt, node.childInvocation);
+  if (node.childFreezeReceipt) {
+    if (JSON.stringify(node.childFreezeReceipt) === JSON.stringify(receipt)) return input.graph;
+    throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} already froze another child definition.`);
+  }
+  return Object.freeze({
+    ...input.graph,
+    nodes: Object.freeze({
+      ...input.graph.nodes,
+      [node.id]: Object.freeze({ ...node, childFreezeReceipt: receipt }),
+    }),
+  });
+}
+
+/** Accepts an immutable child terminal receipt as the exact parent node settlement. */
+export function acceptAIDataWorkflowChildTerminalReceipt(input: {
+  readonly graph: AIDataWorkflowRunGraph;
+  readonly nodeId: string;
+  readonly receipt: AIDataWorkflowChildTerminalReceipt;
+}): AIDataWorkflowRunGraph {
+  const node = input.graph.nodes[input.nodeId];
+  if (!node?.childInvocation || !node.childFreezeReceipt) {
+    throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} is not frozen for child settlement.`);
+  }
+  const receipt = normalizeAIDataWorkflowChildTerminalReceipt(input.receipt, node.childInvocation);
+  if (node.childTerminalReceipt) {
+    if (JSON.stringify(node.childTerminalReceipt) === JSON.stringify(receipt)) return input.graph;
+    throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} already accepted another child terminal receipt.`);
+  }
+  if (node.status !== 'Running') {
+    throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} must be Running before child settlement.`);
+  }
+  if (receipt.status === 'Succeeded') {
+    const expected = [...node.outputs].sort(compareCodeUnits);
+    const actual = Object.keys(receipt.output).sort(compareCodeUnits);
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+      throw new AIDataWorkflowChildInvocationError(`Node ${input.nodeId} child output does not match its FlowContract.`);
+    }
+  }
+  const result = receipt.status === 'Succeeded'
+    ? { nodeId: node.id, generation: node.generation, status: 'Succeeded' as const, output: receipt.output }
+    : { nodeId: node.id, generation: node.generation, status: 'Failed' as const };
+  return Object.freeze({
+    ...input.graph,
+    nodes: Object.freeze({
+      ...input.graph.nodes,
+      [node.id]: Object.freeze({
+        ...node,
+        status: receipt.status,
+        result: Object.freeze(result),
+        childTerminalReceipt: receipt,
+      }),
+    }),
+    invalidations: Object.freeze(input.graph.invalidations.filter((fact) => fact.nodeId !== node.id)),
+  });
+}
+
+export function normalizeAIDataWorkflowChildInvocationIdentity(
+  value: unknown,
+  location = 'childInvocation.identity',
+): AIDataWorkflowChildInvocationIdentity {
+  const input = record(value, [
+    'schemaVersion', 'invocationKey', 'parentInstanceId', 'parentRunId', 'parentNodeId', 'parentGeneration',
+    'childInstanceId', 'childRunId', 'subflow',
+  ], location);
+  schema(input.schemaVersion, `${location}.schemaVersion`);
+  if (!Number.isSafeInteger(input.parentGeneration) || Number(input.parentGeneration) < 0) {
+    throw new AIDataWorkflowChildInvocationError(`${location}.parentGeneration must be a non-negative safe integer.`);
+  }
+  return Object.freeze({
+    schemaVersion: AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION,
+    invocationKey: nonEmpty(input.invocationKey, `${location}.invocationKey`),
+    parentInstanceId: nonEmpty(input.parentInstanceId, `${location}.parentInstanceId`),
+    parentRunId: nonEmpty(input.parentRunId, `${location}.parentRunId`),
+    parentNodeId: nonEmpty(input.parentNodeId, `${location}.parentNodeId`),
+    parentGeneration: Number(input.parentGeneration),
+    childInstanceId: nonEmpty(input.childInstanceId, `${location}.childInstanceId`),
+    childRunId: nonEmpty(input.childRunId, `${location}.childRunId`),
+    subflow: normalizeSubflow(input.subflow, `${location}.subflow`),
+  });
+}
+
+export function normalizeAIDataWorkflowChildFreezeReceipt(
+  value: unknown,
+  identity: AIDataWorkflowChildInvocationIdentity,
+  location = 'childInvocation.freeze',
+): AIDataWorkflowChildFreezeReceipt {
+  const input = record(value, [
+    'schemaVersion', 'invocationKey', 'childInstanceId', 'childRunId', 'definitionRef', 'flowRef',
+    'contractDigest', 'definitionRevision', 'definitionDigest',
+  ], location);
+  schema(input.schemaVersion, `${location}.schemaVersion`);
+  const normalized = Object.freeze({
+    schemaVersion: AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION,
+    invocationKey: nonEmpty(input.invocationKey, `${location}.invocationKey`),
+    childInstanceId: nonEmpty(input.childInstanceId, `${location}.childInstanceId`),
+    childRunId: nonEmpty(input.childRunId, `${location}.childRunId`),
+    definitionRef: prefixed(input.definitionRef, 'resource://', `${location}.definitionRef`) as `resource://${string}`,
+    flowRef: prefixed(input.flowRef, 'eager-data-flow://', `${location}.flowRef`) as `eager-data-flow://${string}`,
+    contractDigest: nonEmpty(input.contractDigest, `${location}.contractDigest`),
+    definitionRevision: nonEmpty(input.definitionRevision, `${location}.definitionRevision`),
+    definitionDigest: nonEmpty(input.definitionDigest, `${location}.definitionDigest`),
+  });
+  assertChildIdentity(normalized, identity, location);
+  return normalized;
+}
+
+export function normalizeAIDataWorkflowChildInvocationObservation(
+  value: unknown,
+  identity: AIDataWorkflowChildInvocationIdentity,
+  location = 'childInvocation.observation',
+): AIDataWorkflowChildInvocationObservation {
+  const input = record(value, ['schemaVersion', 'invocationKey', 'childInstanceId', 'childRunId', 'status'], location);
+  schema(input.schemaVersion, `${location}.schemaVersion`);
+  if (input.status !== 'Reserved' && input.status !== 'Running'
+    && input.status !== 'Succeeded' && input.status !== 'Failed') {
+    throw new AIDataWorkflowChildInvocationError(`${location}.status is invalid.`);
+  }
+  const normalized = Object.freeze({
+    schemaVersion: AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION,
+    invocationKey: nonEmpty(input.invocationKey, `${location}.invocationKey`),
+    childInstanceId: nonEmpty(input.childInstanceId, `${location}.childInstanceId`),
+    childRunId: nonEmpty(input.childRunId, `${location}.childRunId`),
+    status: input.status,
+  });
+  assertChildIdentity(normalized, identity, location);
+  return normalized;
+}
+
+export function normalizeAIDataWorkflowChildTerminalReceipt(
+  value: unknown,
+  identity: AIDataWorkflowChildInvocationIdentity,
+  location = 'childInvocation.terminalReceipt',
+): AIDataWorkflowChildTerminalReceipt {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new AIDataWorkflowChildInvocationError(`${location} must be an object.`);
+  }
+  const status = (value as Readonly<Record<string, unknown>>).status;
+  const common = [
+    'schemaVersion', 'invocationKey', 'childInstanceId', 'childRunId', 'definitionRef', 'flowRef',
+    'contractDigest', 'status', 'receiptDigest',
+  ];
+  const input = record(value, status === 'Succeeded'
+    ? [...common, 'output']
+    : status === 'Failed'
+      ? [...common, 'failureCode', 'failureMessage']
+      : common, location);
+  schema(input.schemaVersion, `${location}.schemaVersion`);
+  if (status !== 'Succeeded' && status !== 'Failed') {
+    throw new AIDataWorkflowChildInvocationError(`${location}.status must be terminal.`);
+  }
+  const commonResult = {
+    schemaVersion: AI_DATA_CHILD_INVOCATION_SCHEMA_VERSION,
+    invocationKey: nonEmpty(input.invocationKey, `${location}.invocationKey`),
+    childInstanceId: nonEmpty(input.childInstanceId, `${location}.childInstanceId`),
+    childRunId: nonEmpty(input.childRunId, `${location}.childRunId`),
+    definitionRef: prefixed(input.definitionRef, 'resource://', `${location}.definitionRef`) as `resource://${string}`,
+    flowRef: prefixed(input.flowRef, 'eager-data-flow://', `${location}.flowRef`) as `eager-data-flow://${string}`,
+    contractDigest: nonEmpty(input.contractDigest, `${location}.contractDigest`),
+    receiptDigest: nonEmpty(input.receiptDigest, `${location}.receiptDigest`),
+  };
+  assertChildIdentity(commonResult, identity, location);
+  if (status === 'Succeeded') {
+    return Object.freeze({
+      ...commonResult,
+      status,
+      output: normalizeFlowClosedObject(input.output, `${location}.output`),
+    });
+  }
+  return Object.freeze({
+    ...commonResult,
+    status,
+    failureCode: nonEmpty(input.failureCode, `${location}.failureCode`),
+    failureMessage: nonEmpty(input.failureMessage, `${location}.failureMessage`),
+  });
+}
+
+function assertChildIdentity(
+  value: Readonly<Record<string, unknown>>,
+  identity: AIDataWorkflowChildInvocationIdentity,
+  location: string,
+): void {
+  const expected: Readonly<Record<string, unknown>> = {
+    invocationKey: identity.invocationKey,
+    childInstanceId: identity.childInstanceId,
+    childRunId: identity.childRunId,
+    definitionRef: identity.subflow.definitionRef,
+    flowRef: identity.subflow.flowRef,
+    contractDigest: identity.subflow.contractDigest,
+  };
+  for (const [field, expectedValue] of Object.entries(expected)) {
+    if (value[field] !== undefined && value[field] !== expectedValue) {
+      throw new AIDataWorkflowChildInvocationError(`${location}.${field} does not match the reserved child identity.`);
+    }
+  }
+}

package/src/filesystem.ts

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import type {
+  AIDataWorkflowChildInvocationIdentity,
+  AIDataWorkflowChildInvocationRuntimePort,
+  AIDataWorkflowChildTerminalReceipt,
   AIDataWorkflowRunCheckpoint,
   AIDataWorkflowRunGraph,
 } from 'ai-data-workflow-contract';
@@ -12,10 +15,13 @@ import type {
   AIWorkflowReusePolicy,
   FlowClosedValue,
 } from 'ai-workflow-contract';
+import type { EagerDataFlowModuleImporter } from 'eager-data-flow-logic';
 import type {
-  EagerDataFlowModuleImporter,
-} from 'eager-data-flow-logic';
-import type { EagerDataFlowDurableNodeState } from 'eager-data-flow-contract';
+  EagerDataFlowDurableNodeState,
+  EagerDataFlowExecutable,
+  EagerDataFlowExecutableRegistry,
+  EagerDataFlowRecord,
+} from 'eager-data-flow-contract';
 import {
   createFilesystemCodeResolver,
   materializeEagerDataFlowPlan,
@@ -30,6 +36,7 @@ import {
 } from 'ai-workflow-logic/checkpoint-filesystem';
 import {
   createInitialRunStepExtensions,
+  FlowRunCheckpointVersionConflictError,
   normalizeAIWorkflowProfileDurableState,
   normalizeFlowClosedObject,
   normalizeFlowClosedValue,
@@ -45,14 +52,27 @@ import {
 } from 'work-ctrl-flow-logic';
 import {
   commitAIDataWorkflowCheckpoint,
+  acceptAIDataWorkflowChildTerminalReceipt,
+  createAIDataWorkflowChildInvocationIdentity,
   createAIDataWorkflowCheckpoint,
   createAIDataWorkflowRunGraph,
   createAIDataWorkflowAgentNodeRuntimeBinder,
   loadAIDataWorkflowCheckpoint,
   loadAIDataWorkflowSources,
+  normalizeAIDataWorkflowChildInvocationObservation,
+  normalizeAIDataWorkflowChildTerminalReceipt,
+  projectAIDataWorkflowRunGraphPlan,
   recordAIDataWorkflowNodeResult,
+  recordAIDataWorkflowChildFreezeReceipt,
+  reserveAIDataWorkflowChildInvocation,
 } from './index.js';
 
+export interface MaterializedAIDataWorkflowChildFlow {
+  readonly definitionRef?: `resource://${string}`;
+  readonly contractDigest?: string;
+  readonly executable: EagerDataFlowExecutable<any>;
+}
+
 export interface MaterializedAIDataWorkflowRuntime {
   readonly supportRoot: string;
   readonly workflow: AIDataWorkflowRuntime;
@@ -60,6 +80,15 @@ export interface MaterializedAIDataWorkflowRuntime {
   readonly extensionCodecs?: DefinitionStepAssemblyRuntime['extensionCodecs'];
   readonly agentEffects?: AIAgentHostEffectPort;
   readonly agentTaskProofs?: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
+  /** Exact admitted child definitions keyed by their eager-data-flow id. */
+  readonly childFlows?: Readonly<Record<string, MaterializedAIDataWorkflowChildFlow>>;
+  readonly childInvocations?: AIDataWorkflowChildInvocationRuntimePort;
+  /** Read-only lifecycle observation/fault-injection seam; it owns no parent or child facts. */
+  readonly childInvocationObserver?: (event: {
+    readonly phase: 'settled-before-parent-accept';
+    readonly identity: AIDataWorkflowChildInvocationIdentity;
+    readonly receipt: AIDataWorkflowChildTerminalReceipt;
+  }) => void | Promise<void>;
   readonly checkpointObserver?: (event: {
     readonly checkpoint: AIDataWorkflowRunCheckpoint;
     readonly nodeId: string;
@@ -209,43 +238,56 @@ async function executeAIDataCheckpoint(
     nodeId: string,
     phase: 'before' | 'after' | 'failed',
   ): Promise<void> => transition(async () => {
-    const owner = await loadAIDataWorkflowCheckpoint(checkpointRuntime, {
-      instanceId: checkpoint.instanceId,
-      runId: checkpoint.runId,
-    });
-    if (!owner) throw new Error(`AI Data Workflow checkpoint ${checkpoint.runId} disappeared during node transition.`);
-    accepted = owner;
-    graph = { ...owner.profile.runGraph, binding };
-    const nextGraph = updateGraph(graph);
-    const nextStatus = graphCheckpointStatus(nextGraph);
-    accepted = await commitAIDataWorkflowCheckpoint(checkpointRuntime, {
-      expectedVersion: accepted.version,
-      checkpoint: {
-        ...accepted,
-        version: accepted.version + 1,
-        state: { status: nextStatus, generation: nextGraph.currentGeneration },
-        output: graphCheckpointOutput(nextGraph, nextStatus),
-        controllerSidecars: { status: nextStatus },
-        nodeSidecars: nodeStatuses(nextGraph),
-        profile: { ...accepted.profile, runGraph: durableGraph(nextGraph) },
-      },
-    });
-    graph = { ...accepted.profile.runGraph, binding };
-    if (runtime.checkpointObserver) {
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const owner = await loadAIDataWorkflowCheckpoint(checkpointRuntime, {
+        instanceId: checkpoint.instanceId,
+        runId: checkpoint.runId,
+      });
+      if (!owner) throw new Error(`AI Data Workflow checkpoint ${checkpoint.runId} disappeared during node transition.`);
+      accepted = owner;
+      graph = { ...owner.profile.runGraph, binding };
+      const nextGraph = updateGraph(graph);
+      if (nextGraph === graph) return;
+      const nextStatus = graphCheckpointStatus(nextGraph);
       try {
-        await runtime.checkpointObserver({ checkpoint: accepted, nodeId, phase });
+        accepted = await commitAIDataWorkflowCheckpoint(checkpointRuntime, {
+          expectedVersion: accepted.version,
+          checkpoint: {
+            ...accepted,
+            version: accepted.version + 1,
+            state: { status: nextStatus, generation: nextGraph.currentGeneration },
+            output: graphCheckpointOutput(nextGraph, nextStatus),
+            controllerSidecars: { status: nextStatus },
+            nodeSidecars: nodeStatuses(nextGraph),
+            profile: { ...accepted.profile, runGraph: durableGraph(nextGraph) },
+          },
+        });
       } catch (cause) {
-        throw new AIDataCheckpointObserverError(cause);
+        if (cause instanceof FlowRunCheckpointVersionConflictError) continue;
+        throw cause;
       }
+      graph = { ...accepted.profile.runGraph, binding };
+      if (runtime.checkpointObserver) {
+        try {
+          await runtime.checkpointObserver({ checkpoint: accepted, nodeId, phase });
+        } catch (cause) {
+          throw new AIDataCheckpointObserverError(cause);
+        }
+      }
+      return;
     }
+    throw new Error(`AI Data Workflow node ${nodeId} checkpoint CAS did not converge.`);
   });
   let output: unknown;
   try {
-    const executable = await materializeEagerDataFlowPlan(binding.definition, {
+    const executionPlan = projectAIDataWorkflowRunGraphPlan(graph);
+    const executable = await materializeEagerDataFlowPlan(executionPlan, {
       resolveCode: createFilesystemCodeResolver(runtime.importModule),
+      subflows: createMaterializedChildRegistry(runtime, () => graph),
     });
     output = await executable.invoke(runtime.workflow, invocationInput, {
       completedNodes: completedEagerNodes(graph),
+      invokeSubFlow: createMaterializedChildInvoker(runtime, () => graph, commitGraph),
       ...(runtime.agentEffects ? {
         bindNode: ((binder) => (nodeRuntime: unknown, identity: { readonly nodeId: string }) => binder(
           nodeRuntime as AIDataWorkflowRuntime,
@@ -264,6 +306,14 @@ async function executeAIDataCheckpoint(
         return commitGraph((current) => {
           const node = current.nodes[nodeId];
           if (!node) throw new Error(`AI Data Workflow node ${nodeId} does not exist in the durable graph.`);
+          if (node.tag === 'SubFlowNode' && node.subflow?.kind === 'autonomous') {
+            const identity = node.childInvocation ?? createAIDataWorkflowChildInvocationIdentity({
+              graph: current,
+              parentInstanceId: checkpoint.instanceId,
+              nodeId,
+            });
+            return reserveAIDataWorkflowChildInvocation({ graph: current, identity });
+          }
           return recordAIDataWorkflowNodeResult(current, nodeId, {
             nodeId,
             generation: node.generation,
@@ -275,6 +325,7 @@ async function executeAIDataCheckpoint(
         return commitGraph((current) => {
           const node = current.nodes[settlement.nodeId];
           if (!node) throw new Error(`AI Data Workflow node ${settlement.nodeId} does not exist in the durable graph.`);
+          if (node.tag === 'SubFlowNode' && node.childTerminalReceipt) return current;
           return recordAIDataWorkflowNodeResult(current, settlement.nodeId, {
             nodeId: settlement.nodeId,
             generation: node.generation,
@@ -284,10 +335,13 @@ async function executeAIDataCheckpoint(
           });
         }, settlement.nodeId, 'after');
       },
-      onNodeFailure: ({ nodeId }) => {
+      onNodeFailure: ({ nodeId, cause }) => {
         return commitGraph((current) => {
           const node = current.nodes[nodeId];
           if (!node) throw new Error(`AI Data Workflow node ${nodeId} does not exist in the durable graph.`);
+          if (cause instanceof AIDataChildInvocationSuspendedError
+            || cause instanceof AIDataChildInvocationTerminalFailure
+            || findCheckpointObserverError(cause)) return current;
           return recordAIDataWorkflowNodeResult(current, nodeId, {
             nodeId,
             generation: node.generation,
@@ -310,6 +364,125 @@ async function executeAIDataCheckpoint(
   return { checkpoint: accepted, graph };
 }
 
+class AIDataChildInvocationSuspendedError extends Error {
+  constructor(nodeId: string, status: string) {
+    super(`AI Data child invocation ${nodeId} is ${status}; continue the parent checkpoint to resume it.`);
+    this.name = 'AIDataChildInvocationSuspendedError';
+  }
+}
+
+class AIDataChildInvocationTerminalFailure extends Error {
+  constructor(nodeId: string, code: string, message: string) {
+    super(`AI Data child invocation ${nodeId} failed (${code}): ${message}`);
+    this.name = 'AIDataChildInvocationTerminalFailure';
+  }
+}
+
+function createMaterializedChildRegistry(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  currentGraph: () => AIDataWorkflowRunGraph,
+): EagerDataFlowExecutableRegistry<any> {
+  const registry: Record<string, EagerDataFlowExecutable<any>> = {};
+  for (const nodeId of currentGraph().declarationOrder) {
+    const node = currentGraph().nodes[nodeId];
+    if (!node || node.status === 'Removed' || node.tag !== 'SubFlowNode' || !node.subflow) continue;
+    const flowId = node.subflow.flowRef.slice('eager-data-flow://'.length);
+    const admitted = runtime.childFlows?.[flowId];
+    if (!admitted || admitted.executable.plan.fqn !== flowId) {
+      throw new Error(`AI Data child flow ${flowId} is not present in the admitted executable registry.`);
+    }
+    if (node.subflow.kind === 'autonomous' && (admitted.definitionRef !== node.subflow.definitionRef
+      || admitted.contractDigest !== node.subflow.contractDigest)) {
+      throw new Error(`AI Data child flow ${flowId} does not match its frozen definition and contract.`);
+    }
+    if (node.subflow.kind === 'autonomous' && !runtime.childInvocations) {
+      throw new Error(`AI Data autonomous child flow ${flowId} requires a child invocation runtime port.`);
+    }
+    registry[flowId] = admitted.executable;
+  }
+  return Object.freeze(registry);
+}
+
+function createMaterializedChildInvoker(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  currentGraph: () => AIDataWorkflowRunGraph,
+  commitGraph: (
+    updateGraph: (current: AIDataWorkflowRunGraph) => AIDataWorkflowRunGraph,
+    nodeId: string,
+    phase: 'before' | 'after' | 'failed',
+  ) => Promise<void>,
+) {
+  return async (
+    workflow: AIDataWorkflowRuntime,
+    invocation: { readonly nodeId: string; readonly flowRef: string },
+    input: Readonly<EagerDataFlowRecord>,
+    options: { readonly signal: AbortSignal },
+  ): Promise<EagerDataFlowRecord> => {
+    const node = currentGraph().nodes[invocation.nodeId];
+    if (!node || node.tag !== 'SubFlowNode' || node.subflow?.flowRef !== invocation.flowRef) {
+      throw new Error(`AI Data child dispatch ${invocation.nodeId} does not match the current RunGraph.`);
+    }
+    const flowId = invocation.flowRef.slice('eager-data-flow://'.length);
+    const admitted = runtime.childFlows?.[flowId];
+    if (!admitted) throw new Error(`AI Data child flow ${flowId} is not admitted.`);
+    if (node.subflow.kind === 'declared') {
+      return admitted.executable.invoke(workflow, input, { signal: options.signal });
+    }
+    if (!node.childInvocation || !runtime.childInvocations) {
+      throw new Error(`AI Data child node ${invocation.nodeId} was not reserved before dispatch.`);
+    }
+    const identity = node.childInvocation;
+    let freeze = node.childFreezeReceipt;
+    if (!freeze) {
+      freeze = await runtime.childInvocations.resolveAndFreeze({ identity });
+      await commitGraph(
+        (graph) => recordAIDataWorkflowChildFreezeReceipt({ graph, nodeId: node.id, receipt: freeze! }),
+        node.id,
+        'before',
+      );
+      freeze = currentGraph().nodes[node.id].childFreezeReceipt;
+    }
+    if (!freeze) throw new Error(`AI Data child node ${node.id} freeze receipt was not committed.`);
+    let observation = normalizeAIDataWorkflowChildInvocationObservation(
+      await runtime.childInvocations.startOrContinue({
+        identity,
+        freeze,
+        input: normalizeFlowClosedObject(input, `aiData.child.${node.id}.input`),
+      }),
+      identity,
+    );
+    if (observation.status === 'Reserved' || observation.status === 'Running') {
+      observation = normalizeAIDataWorkflowChildInvocationObservation(
+        await runtime.childInvocations.load({ identity, freeze }),
+        identity,
+      );
+    }
+    if (observation.status === 'Reserved' || observation.status === 'Running') {
+      throw new AIDataChildInvocationSuspendedError(node.id, observation.status);
+    }
+    const receipt = normalizeAIDataWorkflowChildTerminalReceipt(
+      await runtime.childInvocations.settle({ identity, freeze, terminalStatus: observation.status }),
+      identity,
+    );
+    if (runtime.childInvocationObserver) {
+      try {
+        await runtime.childInvocationObserver({ phase: 'settled-before-parent-accept', identity, receipt });
+      } catch (cause) {
+        throw new AIDataCheckpointObserverError(cause);
+      }
+    }
+    await commitGraph(
+      (graph) => acceptAIDataWorkflowChildTerminalReceipt({ graph, nodeId: node.id, receipt }),
+      node.id,
+      receipt.status === 'Succeeded' ? 'after' : 'failed',
+    );
+    if (receipt.status === 'Failed') {
+      throw new AIDataChildInvocationTerminalFailure(node.id, receipt.failureCode, receipt.failureMessage);
+    }
+    return receipt.output as EagerDataFlowRecord;
+  };
+}
+
 class AIDataCheckpointObserverError extends Error {
   constructor(public override readonly cause: unknown) {
     super('AI Data checkpoint observer interrupted execution.');

package/src/index.ts

@@ -11,6 +11,9 @@ import type {
   AIDataWorkflowRunNode,
   AIDataWorkflowRunNodeStatus,
   AIDataWorkflowSemanticInput,
+  AIDataWorkflowSubFlowBinding,
+  AIDataWorkflowChildInvocationIdentity,
+  AIDataWorkflowChildTerminalReceipt,
 } from 'ai-data-workflow-contract';
 import type {
   AIDataWorkflowDefinitionBinding,
@@ -63,6 +66,7 @@ import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 
 export * from './holon-task.js';
 export * from './autonomous-control.js';
+export * from './child-invocation.js';
 
 export interface CreateAIDataWorkflowCheckpointInput {
   readonly instanceId: string;
@@ -287,12 +291,20 @@ function cloneInvalidation(invalidation: AIDataWorkflowInvalidation): AIDataWork
   return { ...invalidation };
 }
 
+function cloneSubflow(binding: AIDataWorkflowSubFlowBinding): AIDataWorkflowSubFlowBinding {
+  return { ...binding };
+}
+
 function cloneNode(node: AIDataWorkflowRunNode): AIDataWorkflowRunNode {
   return {
     ...node,
     inputs: cloneRecord(node.inputs),
     outputs: [...node.outputs],
     config: cloneRecord(node.config),
+    ...(node.subflow ? { subflow: cloneSubflow(node.subflow) } : {}),
+    ...(node.childInvocation ? { childInvocation: cloneChildInvocation(node.childInvocation) } : {}),
+    ...(node.childFreezeReceipt ? { childFreezeReceipt: { ...node.childFreezeReceipt } } : {}),
+    ...(node.childTerminalReceipt ? { childTerminalReceipt: cloneChildTerminalReceipt(node.childTerminalReceipt) } : {}),
     dependsOn: [...node.dependsOn],
     dependents: [...node.dependents],
     reusePolicy: { ...node.reusePolicy },
@@ -302,6 +314,16 @@ function cloneNode(node: AIDataWorkflowRunNode): AIDataWorkflowRunNode {
   };
 }
 
+function cloneChildInvocation(identity: AIDataWorkflowChildInvocationIdentity): AIDataWorkflowChildInvocationIdentity {
+  return { ...identity, subflow: { ...identity.subflow } };
+}
+
+function cloneChildTerminalReceipt(receipt: AIDataWorkflowChildTerminalReceipt): AIDataWorkflowChildTerminalReceipt {
+  return receipt.status === 'Succeeded'
+    ? { ...receipt, output: { ...receipt.output } }
+    : { ...receipt };
+}
+
 function cloneNodeResult(result: AIWorkflowNodeResult): AIWorkflowNodeResult {
   return {
     ...result,
@@ -326,7 +348,27 @@ function cloneGraph(graph: AIDataWorkflowRunGraph): AIDataWorkflowRunGraph {
     declarationOrder: [...graph.declarationOrder],
     patchHistory: graph.patchHistory.map((record) => ({
       ...record,
-      operations: record.operations.map((operation) => ({ ...operation })),
+      operations: record.operations.map((operation) => {
+        if (operation.op === 'add-node') {
+          return {
+            ...operation,
+            node: {
+              ...operation.node,
+              ...(operation.node.subflow ? { subflow: cloneSubflow(operation.node.subflow) } : {}),
+            },
+          };
+        }
+        if (operation.op === 'update-node') {
+          return {
+            ...operation,
+            changes: {
+              ...operation.changes,
+              ...(operation.changes.subflow ? { subflow: cloneSubflow(operation.changes.subflow) } : {}),
+            },
+          };
+        }
+        return { ...operation };
+      }),
     })),
     invalidations: graph.invalidations.map(cloneInvalidation),
   };
@@ -354,6 +396,40 @@ function nodeConfig(node: EagerDataFlowNodePlan): AIDataWorkflowNodeConfig {
   return {};
 }
 
+function nodeSubflow(node: EagerDataFlowNodePlan): AIDataWorkflowSubFlowBinding | undefined {
+  if (node.tag !== 'SubFlowNode') return undefined;
+  return {
+    kind: 'declared',
+    flowRef: node.flow as `eager-data-flow://${string}`,
+  };
+}
+
+function assertSubflowBinding(
+  tag: AIDataWorkflowNodeTag,
+  binding: AIDataWorkflowSubFlowBinding | undefined,
+  nodeId: string,
+): void {
+  if (tag === 'SubFlowNode' && !binding) {
+    throw new AIDataWorkflowRunGraphError(`AI Data Workflow SubFlowNode ${nodeId} requires an exact subflow binding`);
+  }
+  if (tag !== 'SubFlowNode' && binding) {
+    throw new AIDataWorkflowRunGraphError(`AI Data Workflow node ${nodeId} cannot carry a subflow binding`);
+  }
+  if (!binding) return;
+  if (!binding.flowRef.startsWith('eager-data-flow://') || binding.flowRef.length === 'eager-data-flow://'.length) {
+    throw new AIDataWorkflowRunGraphError(`AI Data Workflow SubFlowNode ${nodeId} has an invalid flow reference`);
+  }
+  if (binding.kind === 'autonomous' && (
+    binding.schemaVersion !== 'depa.ai-data-subflow-binding/v1'
+    || !binding.capabilityId
+    || !binding.catalogDigest
+    || !binding.contractDigest
+    || !binding.definitionRef.startsWith('resource://')
+  )) {
+    throw new AIDataWorkflowRunGraphError(`AI Data Workflow SubFlowNode ${nodeId} has an invalid autonomous binding`);
+  }
+}
+
 function configReusePolicy(config: AIDataWorkflowNodeConfig): AIWorkflowReusePolicy | undefined {
   const raw = config.reuse_policy ?? config.reusePolicy;
   return raw === 'semantic-hash' || raw === 'never' ? raw : undefined;
@@ -548,10 +624,12 @@ export function createAIDataWorkflowRunGraph(
         inputs: nodeInputs(planNode),
         outputs: nodeOutputs(planNode),
         config,
+        ...(nodeSubflow(planNode) ? { subflow: nodeSubflow(planNode) } : {}),
         dependsOn: dependencies.get(planNode.id) ?? [],
         dependents: [],
         reusePolicy,
       };
+      assertSubflowBinding(runNode.tag, runNode.subflow, runNode.id);
       return [planNode.id, runNode];
     }),
   );
@@ -574,6 +652,96 @@ export function createAIDataWorkflowRunGraph(
   return graph;
 }
 
+function isRunGraphPortReference(value: AIDataWorkflowNodeInputs[string]): value is import('eager-data-flow-contract').FlowPortReference {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && typeof (value as { ref?: unknown }).ref === 'string'
+    && typeof (value as { nodeId?: unknown }).nodeId === 'string'
+    && typeof (value as { port?: unknown }).port === 'string');
+}
+
+/** Projects the current admitted RunGraph, including autonomous nodes, into the canonical Eager executor plan. */
+export function projectAIDataWorkflowRunGraphPlan(graph: AIDataWorkflowRunGraph): EagerDataFlowAuthoringPlan {
+  const activeOrder = graph.declarationOrder.filter((nodeId) => graph.nodes[nodeId]?.status !== 'Removed');
+  const nodePlans = activeOrder.map((nodeId): EagerDataFlowNodePlan => {
+    const node = graph.nodes[nodeId];
+    const base = graph.binding.definition.nodeById[nodeId]
+      ?? graph.binding.definition.nodes.find((candidate) => candidate.id === nodeId);
+    const dataDependencies = new Set(Object.values(node.inputs).flatMap((binding) => (
+      isRunGraphPortReference(binding) ? [binding.nodeId] : []
+    )));
+    const waitFor = node.dependsOn
+      .filter((dependency) => !dataDependencies.has(dependency))
+      .map((dependency) => ({ ref: `flow-node://#${dependency}`, nodeId: dependency }));
+    const common = { id: node.id, declarationIndex: node.declarationIndex, waitFor };
+    if (node.tag === 'EntryNode') return { ...common, tag: 'EntryNode', outputs: [...node.outputs] };
+    if (node.tag === 'ReturnNode') {
+      return { ...common, tag: 'ReturnNode', inputs: { ...node.inputs } } as EagerDataFlowNodePlan;
+    }
+    if (node.tag === 'SubFlowNode') {
+      if (!node.subflow) throw new AIDataWorkflowRunGraphError(`SubFlowNode ${node.id} has no durable child binding.`);
+      return {
+        ...common,
+        tag: 'SubFlowNode',
+        flow: node.subflow.flowRef,
+        inputs: { ...node.inputs },
+        outputs: [...node.outputs],
+      } as EagerDataFlowNodePlan;
+    }
+    if (node.tag !== 'TransformNode' && node.tag !== 'SinkNode') {
+      throw new AIDataWorkflowRunGraphError(`RunGraph node ${node.id} has unsupported executable tag ${node.tag}.`);
+    }
+    const configuredSource = typeof node.config.src === 'string' ? node.config.src : undefined;
+    const configuredImpl = typeof node.config.impl === 'string' ? node.config.impl : undefined;
+    const baseExecutable = base && (base.tag === 'TransformNode' || base.tag === 'SinkNode') ? base : undefined;
+    const executable = {
+      ...(configuredSource ?? baseExecutable?.src ? { src: configuredSource ?? baseExecutable?.src } : {}),
+      ...(configuredImpl ?? baseExecutable?.impl ? { impl: configuredImpl ?? baseExecutable?.impl } : {}),
+    };
+    return {
+      ...common,
+      tag: node.tag,
+      inputs: { ...node.inputs },
+      ...(node.tag === 'TransformNode' ? { outputs: [...node.outputs] } : {}),
+      ...executable,
+      config: { ...node.config },
+    } as EagerDataFlowNodePlan;
+  });
+  const nodeById = Object.fromEntries(nodePlans.map((node) => [node.id, node]));
+  const dataEdges = nodePlans.flatMap((node) => node.tag === 'EntryNode' ? [] : Object.entries(node.inputs).flatMap(
+    ([input, binding]) => isRunGraphPortReference(binding) ? [{
+      kind: 'data' as const,
+      fromNodeId: binding.nodeId,
+      fromPort: binding.port,
+      toNodeId: node.id,
+      toInput: input,
+      ref: binding.ref,
+    }] : [],
+  ));
+  const waitForEdges = nodePlans.flatMap((node) => node.waitFor.map((reference) => ({
+    kind: 'waitFor' as const,
+    fromNodeId: reference.nodeId,
+    toNodeId: node.id,
+    ref: reference.ref,
+  })));
+  const subflowEdges = nodePlans.flatMap((node) => node.tag === 'SubFlowNode' ? [{
+    kind: 'subflow' as const,
+    fromFlowId: graph.binding.definition.fqn,
+    nodeId: node.id,
+    targetFlowId: node.flow.slice('eager-data-flow://'.length),
+    ref: node.flow,
+  }] : []);
+  return {
+    ...graph.binding.definition,
+    nodes: nodePlans,
+    nodeById,
+    declarationOrder: activeOrder,
+    dataEdges,
+    waitForEdges,
+    subflowEdges,
+    diagnostics: [],
+  };
+}
+
 function makePatchNode(
   spec: AIDataWorkflowGraphPatchNodeSpec,
   generation: number,
@@ -588,6 +756,8 @@ function makePatchNode(
     platformDefaultPolicy,
   });
   assertReusePolicyAuthority(reusePolicy, nodeType, config, platformDefaultPolicy, spec.id);
+  const subflow = spec.subflow ? cloneSubflow(spec.subflow) : undefined;
+  assertSubflowBinding(tag, subflow, spec.id);
   return {
     id: spec.id,
     tag,
@@ -598,6 +768,7 @@ function makePatchNode(
     inputs: cloneRecord(spec.inputs),
     outputs: [...(spec.outputs ?? [])],
     config,
+    ...(subflow ? { subflow } : {}),
     dependsOn: uniqueStrings(spec.dependsOn ?? []),
     dependents: [],
     reusePolicy,
@@ -663,6 +834,9 @@ function applyInvalidations(
       const {
         result: _staleResult,
         semanticFingerprint: _staleFingerprint,
+        childInvocation: _staleChildInvocation,
+        childFreezeReceipt: _staleChildFreezeReceipt,
+        childTerminalReceipt: _staleChildTerminalReceipt,
         ...currentFacts
       } = node;
       nextNodes = {
@@ -783,6 +957,13 @@ export function applyAIDataWorkflowGraphPatch(
         );
       }
       const config = operation.changes.config ? cloneRecord(operation.changes.config) : existing.config;
+      const tag = operation.changes.tag ?? existing.tag;
+      const subflow = Object.prototype.hasOwnProperty.call(operation.changes, 'subflow')
+        ? operation.changes.subflow === null || operation.changes.subflow === undefined
+          ? undefined
+          : cloneSubflow(operation.changes.subflow)
+        : existing.subflow;
+      assertSubflowBinding(tag, subflow, existing.id);
       const nodeType = operation.changes.nodeType ?? existing.nodeType;
       const dependsOn = operation.changes.dependsOn
         ? uniqueStrings(operation.changes.dependsOn)
@@ -798,17 +979,26 @@ export function applyAIDataWorkflowGraphPatch(
           : existing.reusePolicy
       );
       assertReusePolicyAuthority(reusePolicy, nodeType, config, graph.platformDefaultPolicy, existing.id);
+      const { subflow: _existingSubflow, ...existingWithoutSubflow } = existing;
+      const {
+        childInvocation: _staleChildInvocation,
+        childFreezeReceipt: _staleChildFreezeReceipt,
+        childTerminalReceipt: _staleChildTerminalReceipt,
+        ...existingWithoutChild
+      } = existingWithoutSubflow;
+      const { subflow: _changedSubflow, ...changesWithoutSubflow } = operation.changes;
       nodes = {
         ...nodes,
         [existing.id]: {
-          ...existing,
-          ...operation.changes,
-          tag: operation.changes.tag ?? existing.tag,
+          ...existingWithoutChild,
+          ...changesWithoutSubflow,
+          tag,
           nodeType,
           generation,
           inputs: operation.changes.inputs ? cloneRecord(operation.changes.inputs) : existing.inputs,
           outputs: operation.changes.outputs ? [...operation.changes.outputs] : existing.outputs,
           config,
+          ...(subflow ? { subflow } : {}),
           dependsOn,
           reusePolicy,
         },
@@ -834,6 +1024,9 @@ export function applyAIDataWorkflowGraphPatch(
       result: _staleResult,
       semanticFingerprint: _staleFingerprint,
       invalidatedBy: _activeInvalidation,
+      childInvocation: _staleChildInvocation,
+      childFreezeReceipt: _staleChildFreezeReceipt,
+      childTerminalReceipt: _staleChildTerminalReceipt,
       ...currentFacts
     } = existing;
     nodes = {