ai-data-workflow-logic 0.1.4 → 0.1.6

package/package.json

@@ -1,26 +1,28 @@
 {
   "name": "ai-data-workflow-logic",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "description": "EagerDataFlow-backed AI Data Workflow RunGraph helpers",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./browser": "./src/browser.ts"
+    "./browser": "./src/browser.ts",
+    "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "ai-data-workflow-contract": "0.1.0",
-    "ai-workflow-contract": "0.1.0",
-    "ai-workflow-logic": "0.1.0",
-    "eager-data-flow-contract": "0.1.0",
-    "eager-data-flow-logic": "^0.1.1"
+    "ai-data-workflow-contract": "0.1.2",
+    "ai-workflow-contract": "0.1.5",
+    "ai-workflow-logic": "0.1.5",
+    "eager-data-flow-contract": "0.1.2",
+    "eager-data-flow-logic": "0.1.3",
+    "flow-step-space-logic": "0.1.0",
+    "work-ctrl-flow-logic": "0.1.2"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.com"
+    "access": "public"
   }
 }

package/src/filesystem.ts

@@ -0,0 +1,446 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+  AIDataWorkflowRunCheckpoint,
+  AIDataWorkflowRunGraph,
+} from 'ai-data-workflow-contract';
+import type {
+  AIDataWorkflowRuntime,
+  AIAgentHostEffectPort,
+  FrozenAIAgentTaskBinding,
+  AIWorkflowProfileDurableState,
+  AIWorkflowReusePolicy,
+  FlowClosedValue,
+} from 'ai-workflow-contract';
+import type {
+  EagerDataFlowModuleImporter,
+} from 'eager-data-flow-logic';
+import type { EagerDataFlowDurableNodeState } from 'eager-data-flow-contract';
+import {
+  createFilesystemCodeResolver,
+  materializeEagerDataFlowPlan,
+} from 'eager-data-flow-logic';
+import { assembleDefinitionStepProfileDirectory } from 'flow-step-space-logic/filesystem';
+import { FilesystemFlowRunCheckpointStore } from 'ai-workflow-logic/checkpoint-filesystem';
+import {
+  normalizeAIWorkflowProfileDurableState,
+  normalizeFlowClosedObject,
+  normalizeFlowClosedValue,
+} from 'ai-workflow-logic';
+import {
+  loadMaterializedFlowInstance,
+  materializeFlowInstance,
+  type FlowInstanceSourceIdentity,
+} from 'work-ctrl-flow-logic';
+import {
+  commitAIDataWorkflowCheckpoint,
+  createAIDataWorkflowCheckpoint,
+  createAIDataWorkflowRunGraph,
+  createAIDataWorkflowAgentNodeRuntimeBinder,
+  loadAIDataWorkflowCheckpoint,
+  loadAIDataWorkflowSources,
+  recordAIDataWorkflowNodeResult,
+} from './index.js';
+
+export interface MaterializedAIDataWorkflowRuntime {
+  readonly supportRoot: string;
+  readonly workflow: AIDataWorkflowRuntime;
+  readonly importModule: EagerDataFlowModuleImporter;
+  readonly agentEffects?: AIAgentHostEffectPort;
+  readonly agentTaskProofs?: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
+  readonly checkpointObserver?: (event: {
+    readonly checkpoint: AIDataWorkflowRunCheckpoint;
+    readonly nodeId: string;
+    readonly phase: 'before' | 'after' | 'failed';
+  }) => void | Promise<void>;
+}
+
+export interface StartMaterializedAIDataWorkflowInput {
+  readonly instanceId: string;
+  readonly runId: string;
+  readonly bundleDir?: string;
+  readonly source?: FlowInstanceSourceIdentity;
+  readonly input: Readonly<Record<string, unknown>>;
+}
+
+export interface StartMaterializedAIDataWorkflowConfig {
+  readonly checkpointConfig: FlowClosedValue;
+  readonly platformDefaultPolicy?: AIWorkflowReusePolicy;
+  readonly initialState?: FlowClosedValue;
+  readonly durableAI: AIWorkflowProfileDurableState;
+}
+
+export interface MaterializedAIDataWorkflowResult {
+  readonly checkpoint: AIDataWorkflowRunCheckpoint;
+  readonly graph: AIDataWorkflowRunGraph;
+}
+
+export interface ContinueMaterializedAIDataWorkflowInput {
+  readonly instanceId: string;
+  readonly runId: string;
+}
+
+export type ContinueMaterializedAIDataWorkflowConfig = Readonly<Record<never, never>>;
+
+/** Runtime-first canonical Data execution from a frozen instance. */
+export async function startMaterializedAIDataWorkflow(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  input: StartMaterializedAIDataWorkflowInput,
+  config: StartMaterializedAIDataWorkflowConfig,
+): Promise<MaterializedAIDataWorkflowResult> {
+  requireAgentTaskBindings(runtime);
+  const instance = ensureAIDataInstance(runtime, input);
+  const binding = loadAIDataBinding(instance.definitionDir);
+  const checkpointStore = new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot });
+  const checkpointRuntime = { checkpointStore };
+  const existing = await loadAIDataWorkflowCheckpoint(checkpointRuntime, input);
+  if (existing) {
+    assertStartMatchesCheckpoint(existing, input, config);
+    return executeAIDataCheckpoint(runtime, binding, existing);
+  }
+  const graph = createAIDataWorkflowRunGraph({
+    binding,
+    runId: input.runId,
+    platformDefaultPolicy: config.platformDefaultPolicy,
+  });
+  const initialState = { status: 'Pending', generation: graph.currentGeneration } as const;
+  if (config.initialState !== undefined
+    && JSON.stringify(normalizeFlowClosedValue(config.initialState, 'aiData.start.state')) !== JSON.stringify(initialState)) {
+    throw new Error('AI Data Workflow initialState must equal the canonical Pending RunGraph projection.');
+  }
+  const v0 = await createAIDataWorkflowCheckpoint(checkpointRuntime, {
+    instanceId: input.instanceId,
+    definition: instance.descriptor.definition,
+    graph: durableGraph(graph),
+    input: input.input as FlowClosedValue,
+    config: config.checkpointConfig,
+    state: initialState,
+    output: null,
+    controllerSidecars: { status: 'Pending' },
+    nodeSidecars: nodeStatuses(graph),
+    ai: config.durableAI,
+  });
+  return executeAIDataCheckpoint(runtime, binding, v0);
+}
+
+/** Runtime-first continuation from a checkpoint reconstructed in a fresh process. */
+export async function continueMaterializedAIDataWorkflow(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  input: ContinueMaterializedAIDataWorkflowInput,
+  _config: ContinueMaterializedAIDataWorkflowConfig,
+): Promise<MaterializedAIDataWorkflowResult> {
+  requireAgentTaskBindings(runtime);
+  const instanceDir = path.join(runtime.supportRoot, 'instances', input.instanceId);
+  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
+  const binding = loadAIDataBinding(instance.definitionDir);
+  const checkpoint = await loadAIDataWorkflowCheckpoint(
+    { checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }) },
+    input,
+  );
+  if (!checkpoint) throw new Error(`AI Data Workflow run ${input.runId} does not have a canonical checkpoint.`);
+  return executeAIDataCheckpoint(runtime, binding, checkpoint);
+}
+
+function requireAgentTaskBindings(runtime: MaterializedAIDataWorkflowRuntime): void {
+  if (runtime.agentEffects && (!runtime.agentTaskProofs || Object.keys(runtime.agentTaskProofs).length === 0)) {
+    throw new Error('AI_AGENT_TASK_PROOF_REQUIRED: materialized AI Data Agent effects require run-freeze task proofs.');
+  }
+}
+
+async function executeAIDataCheckpoint(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  binding: ReturnType<typeof loadAIDataBinding>,
+  checkpoint: AIDataWorkflowRunCheckpoint,
+): Promise<MaterializedAIDataWorkflowResult> {
+  let accepted = checkpoint;
+  let graph: AIDataWorkflowRunGraph = {
+    ...checkpoint.profile.runGraph,
+    binding,
+  };
+  const status = checkpointStatus(checkpoint);
+  if (status === 'Succeeded' || status === 'Failed') return { checkpoint, graph };
+  if (status !== 'Pending' && status !== 'Running') {
+    throw new Error(`AI Data Workflow checkpoint ${checkpoint.runId} has unsupported continuation status ${String(status)}.`);
+  }
+  if (typeof checkpoint.input !== 'object' || checkpoint.input === null || Array.isArray(checkpoint.input)) {
+    throw new Error(`AI Data Workflow checkpoint ${checkpoint.runId} input must be a closed object.`);
+  }
+  const invocationInput = checkpoint.input as Readonly<Record<string, FlowClosedValue>>;
+  const checkpointRuntime = {
+    checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }),
+  };
+  let transitionTail = Promise.resolve();
+  const transition = <T>(operation: () => Promise<T>): Promise<T> => {
+    const result = transitionTail.then(operation);
+    transitionTail = result.then(() => undefined, () => undefined);
+    return result;
+  };
+  const commitGraph = (
+    updateGraph: (current: AIDataWorkflowRunGraph) => AIDataWorkflowRunGraph,
+    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) {
+      try {
+        await runtime.checkpointObserver({ checkpoint: accepted, nodeId, phase });
+      } catch (cause) {
+        throw new AIDataCheckpointObserverError(cause);
+      }
+    }
+  });
+  let output: unknown;
+  try {
+    const executable = await materializeEagerDataFlowPlan(binding.definition, {
+      resolveCode: createFilesystemCodeResolver(runtime.importModule),
+    });
+    output = await executable.invoke(runtime.workflow, invocationInput, {
+      completedNodes: completedEagerNodes(graph),
+      ...(runtime.agentEffects ? {
+        bindNode: ((binder) => (nodeRuntime: unknown, identity: { readonly nodeId: string }) => binder(
+          nodeRuntime as AIDataWorkflowRuntime,
+          identity,
+        ))(createAIDataWorkflowAgentNodeRuntimeBinder({
+          flowInstanceId: checkpoint.instanceId,
+          runId: checkpoint.runId,
+          checkpointRuntime,
+          effects: runtime.agentEffects,
+          workflowRef: `resource://${binding.definition.fqn}`,
+          taskProofs: runtime.agentTaskProofs ?? {},
+          generationForNode: (nodeId) => graph.nodes[nodeId]?.generation ?? 0,
+        })),
+      } : {}),
+      onNodeStart: (nodeId) => {
+        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.`);
+          return recordAIDataWorkflowNodeResult(current, nodeId, {
+            nodeId,
+            generation: node.generation,
+            status: 'Running',
+          });
+        }, nodeId, 'before');
+      },
+      onNodeSuccess: (settlement) => {
+        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.`);
+          return recordAIDataWorkflowNodeResult(current, settlement.nodeId, {
+            nodeId: settlement.nodeId,
+            generation: node.generation,
+            status: 'Succeeded',
+            ...(settlement.output !== undefined ? { output: settlement.output } : {}),
+            ...(settlement.returned !== undefined ? { output: settlement.returned } : {}),
+          });
+        }, settlement.nodeId, 'after');
+      },
+      onNodeFailure: ({ nodeId }) => {
+        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.`);
+          return recordAIDataWorkflowNodeResult(current, nodeId, {
+            nodeId,
+            generation: node.generation,
+            status: 'Failed',
+          });
+        }, nodeId, 'failed');
+      },
+    });
+  } catch (error) {
+    const observerError = findCheckpointObserverError(error);
+    if (observerError) throw observerError.cause;
+    throw error;
+  }
+  if (checkpointStatus(accepted) !== 'Succeeded') {
+    throw new Error(`AI Data Workflow ${checkpoint.runId} completed without a terminal RunGraph projection.`);
+  }
+  if (JSON.stringify(accepted.output) !== JSON.stringify(normalizeFlowClosedValue(output, 'aiData.execution.output'))) {
+    throw new Error(`AI Data Workflow ${checkpoint.runId} Return output does not match its durable RunGraph result.`);
+  }
+  return { checkpoint: accepted, graph };
+}
+
+class AIDataCheckpointObserverError extends Error {
+  constructor(public override readonly cause: unknown) {
+    super('AI Data checkpoint observer interrupted execution.');
+    this.name = 'AIDataCheckpointObserverError';
+  }
+}
+
+function findCheckpointObserverError(value: unknown): AIDataCheckpointObserverError | undefined {
+  if (value instanceof AIDataCheckpointObserverError) return value;
+  if (typeof value !== 'object' || value === null || !('cause' in value)) return undefined;
+  return findCheckpointObserverError(value.cause);
+}
+
+function completedEagerNodes(
+  graph: AIDataWorkflowRunGraph,
+): Readonly<Record<string, EagerDataFlowDurableNodeState>> {
+  return Object.fromEntries(graph.declarationOrder.flatMap((nodeId) => {
+    const node = graph.nodes[nodeId];
+    if (!node || (node.status !== 'Succeeded' && node.status !== 'Reused') || !node.result) return [];
+    const state: EagerDataFlowDurableNodeState = {
+      nodeId,
+      ...(node.tag === 'ReturnNode'
+        ? { returned: node.result.output as Readonly<Record<string, unknown>> }
+        : node.tag === 'SinkNode'
+          ? {}
+          : { output: node.result.output as Readonly<Record<string, unknown>> }),
+    };
+    return [[nodeId, state] as const];
+  }));
+}
+
+/** Fresh reconstruction reads only the frozen instance and canonical checkpoint. */
+export async function loadMaterializedAIDataWorkflowRun(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  input: Pick<StartMaterializedAIDataWorkflowInput, 'instanceId' | 'runId'>,
+): Promise<MaterializedAIDataWorkflowResult | undefined> {
+  const instanceDir = path.join(runtime.supportRoot, 'instances', input.instanceId);
+  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
+  const binding = loadAIDataBinding(instance.definitionDir);
+  const checkpoint = await loadAIDataWorkflowCheckpoint(
+    { checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }) },
+    input,
+  );
+  if (!checkpoint) return undefined;
+  return {
+    checkpoint,
+    graph: {
+      ...checkpoint.profile.runGraph,
+      binding,
+    },
+  };
+}
+
+function ensureAIDataInstance(
+  runtime: MaterializedAIDataWorkflowRuntime,
+  input: StartMaterializedAIDataWorkflowInput,
+) {
+  const instancesDir = path.join(runtime.supportRoot, 'instances');
+  const instanceDir = path.join(instancesDir, input.instanceId);
+  if (fs.existsSync(instanceDir)) {
+    return loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
+  }
+  if (!input.bundleDir || !input.source) {
+    if (input.bundleDir || input.source) throw new Error('bundleDir and source identity must be provided together.');
+    throw new Error('bundleDir and source identity are required for first admission.');
+  }
+  return materializeFlowInstance({
+    definitionDir: input.bundleDir,
+    instancesDir,
+    instanceId: input.instanceId,
+    source: input.source,
+    validateDefinition: validateAIDataDefinition,
+  });
+}
+
+function validateAIDataDefinition(definitionDir: string): void {
+  loadAIDataBinding(definitionDir);
+}
+
+function loadAIDataBinding(definitionDir: string) {
+  const assembled = assembleDefinitionStepProfileDirectory(definitionDir, 'AIDataWorkflow');
+  if (assembled.diagnostics.length > 0) {
+    throw new Error(`AIDataWorkflow StepSpace is invalid: ${assembled.diagnostics.map((item) => item.code).join(', ')}`);
+  }
+  const sources = Object.fromEntries((assembled.sources as readonly ({ readonly ref: string; readonly content: string } | { readonly name: string; readonly content: string })[])
+    .map((source) => ['name' in source ? source.name : source.ref, source.content]));
+  const loaded = loadAIDataWorkflowSources(sources, { baseUri: definitionDir });
+  if (!loaded.binding || loaded.diagnostics.length > 0) {
+    throw new Error(`AIDataWorkflow definition is invalid: ${loaded.diagnostics.map((item) => item.code).join(', ')}`);
+  }
+  return assembled.forest
+    ? { ...loaded.binding, definition: { ...loaded.binding.definition, definitionStepForest: assembled.forest } }
+    : loaded.binding;
+}
+
+function durableGraph(graph: AIDataWorkflowRunGraph): AIDataWorkflowRunGraph {
+  const { baseUri: _baseUri, ...definition } = graph.binding.definition;
+  return {
+    ...graph,
+    binding: { ...graph.binding, definition },
+  };
+}
+
+function nodeStatuses(graph: AIDataWorkflowRunGraph) {
+  return Object.fromEntries(
+    graph.declarationOrder.map((nodeId) => [nodeId, {
+      status: graph.nodes[nodeId].status,
+      generation: graph.nodes[nodeId].generation,
+    }]),
+  );
+}
+
+function graphCheckpointStatus(
+  graph: AIDataWorkflowRunGraph,
+): 'Pending' | 'Running' | 'Succeeded' | 'Failed' {
+  const nodes = Object.values(graph.nodes).filter((node) => node.status !== 'Removed');
+  if (nodes.some((node) => node.status === 'Failed')) return 'Failed';
+  if (nodes.some((node) => node.status === 'Running')) return 'Running';
+  if (nodes.length > 0 && nodes.every((node) => node.status === 'Succeeded' || node.status === 'Reused')) {
+    return 'Succeeded';
+  }
+  return 'Pending';
+}
+
+function graphCheckpointOutput(
+  graph: AIDataWorkflowRunGraph,
+  status: ReturnType<typeof graphCheckpointStatus>,
+): FlowClosedValue {
+  if (status !== 'Succeeded') return null;
+  const returnNode = graph.declarationOrder
+    .map((nodeId) => graph.nodes[nodeId])
+    .find((node) => node?.tag === 'ReturnNode');
+  if (!returnNode?.result || returnNode.result.output === undefined) {
+    throw new Error(`AI Data Workflow ${graph.runId} terminal RunGraph has no Return result.`);
+  }
+  return normalizeFlowClosedValue(returnNode.result.output, 'aiData.execution.output');
+}
+
+function checkpointStatus(checkpoint: AIDataWorkflowRunCheckpoint): unknown {
+  return checkpoint.controllerSidecars.status;
+}
+
+function assertStartMatchesCheckpoint(
+  checkpoint: AIDataWorkflowRunCheckpoint,
+  input: StartMaterializedAIDataWorkflowInput,
+  config: StartMaterializedAIDataWorkflowConfig,
+): void {
+  const normalizedInput = normalizeFlowClosedObject(input.input, 'aiData.start.input');
+  const normalizedConfig = normalizeFlowClosedValue(config.checkpointConfig, 'aiData.start.config');
+  if (JSON.stringify(normalizedInput) !== JSON.stringify(checkpoint.input)
+    || JSON.stringify(normalizedConfig) !== JSON.stringify(checkpoint.config)
+    || config.platformDefaultPolicy !== checkpoint.profile.runGraph.platformDefaultPolicy) {
+    throw new Error(`AI Data Workflow run ${input.runId} is already bound to different start facts.`);
+  }
+  if (checkpointStatus(checkpoint) === 'Pending') {
+    const normalizedAI = normalizeAIWorkflowProfileDurableState(config.durableAI, 'aiData.start.ai');
+    if ((config.initialState !== undefined
+      && JSON.stringify(normalizeFlowClosedValue(config.initialState, 'aiData.start.state')) !== JSON.stringify(checkpoint.state))
+      || JSON.stringify(normalizedAI) !== JSON.stringify(checkpoint.profile.ai)) {
+      throw new Error(`AI Data Workflow run ${input.runId} has different pending initialization facts.`);
+    }
+  }
+}

package/src/index.ts

@@ -7,13 +7,18 @@ import type {
   AIDataWorkflowNodeTag,
   AIDataWorkflowReuseCandidate,
   AIDataWorkflowRunGraph,
+  AIDataWorkflowRunCheckpoint,
   AIDataWorkflowRunNode,
   AIDataWorkflowRunNodeStatus,
   AIDataWorkflowSemanticInput,
 } from 'ai-data-workflow-contract';
 import type {
   AIDataWorkflowDefinitionBinding,
+  AIDataWorkflowRunProfileState,
   AIDataWorkflowRuntime,
+  AIAgentHostEffectPort,
+  FrozenAIAgentTaskBinding,
+  AIWorkflowAuthoredEffects,
   AIWorkflowDefinitionRef,
   AIWorkflowEffectProvider,
   AIWorkflowEffectiveReusePolicy,
@@ -24,8 +29,16 @@ import type {
   AIWorkflowRunState,
   AIWorkflowRunStatus,
   AIWorkflowRuntimeContext,
+  AIWorkflowProfileDurableState,
   AIWorkflowSemanticFingerprint,
-  AIWorkflowStateStore,
+  AIWorkflowStateProjection,
+  FlowClosedObject,
+  FlowClosedValue,
+  FlowDefinitionArtifactIdentity,
+  FlowRunCheckpointCommit,
+  FlowRunCheckpointKey,
+  FlowRunCheckpointRuntime,
+  FlowRunProfileState,
 } from 'ai-workflow-contract';
 import type {
   EagerDataFlowAuthoringPlan,
@@ -38,9 +51,76 @@ import type {
 import { loadEagerDataFlowProfileSources } from 'eager-data-flow-logic';
 import {
   createAIWorkflowRuntimeContext,
+  commitFlowRunCheckpoint,
   defineAIDataWorkflow,
+  loadFlowRunCheckpoint,
   resolveAIWorkflowReusePolicy,
+  bindAIAgentProcessors,
 } from 'ai-workflow-logic';
+import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
+
+export interface CreateAIDataWorkflowCheckpointInput {
+  readonly instanceId: string;
+  readonly definition: FlowDefinitionArtifactIdentity;
+  readonly graph: AIDataWorkflowRunGraph;
+  readonly input: FlowClosedValue;
+  readonly config: FlowClosedValue;
+  readonly state: FlowClosedValue;
+  readonly output: FlowClosedValue;
+  readonly controllerSidecars: FlowClosedObject;
+  readonly nodeSidecars: FlowClosedObject;
+  readonly ai: AIWorkflowProfileDurableState;
+}
+
+/** Creates the first complete Data checkpoint as one runtime-owned transition. */
+export function createAIDataWorkflowCheckpoint(
+  runtime: FlowRunCheckpointRuntime,
+  input: CreateAIDataWorkflowCheckpointInput,
+): Promise<AIDataWorkflowRunCheckpoint> {
+  return commitAIDataWorkflowCheckpoint(runtime, {
+    expectedVersion: null,
+    checkpoint: {
+      schemaVersion: 'depa.flow-run-checkpoint/v1',
+      instanceId: input.instanceId,
+      runId: input.graph.runId,
+      definition: input.definition,
+      version: 0,
+      input: input.input,
+      config: input.config,
+      state: input.state,
+      output: input.output,
+      controllerSidecars: input.controllerSidecars,
+      nodeSidecars: input.nodeSidecars,
+      profile: { kind: 'AIDataWorkflow', runGraph: input.graph, ai: input.ai },
+    },
+  });
+}
+
+export async function commitAIDataWorkflowCheckpoint(
+  runtime: FlowRunCheckpointRuntime,
+  input: FlowRunCheckpointCommit<AIDataWorkflowRunProfileState<AIDataWorkflowRunGraph>>,
+): Promise<AIDataWorkflowRunCheckpoint> {
+  const checkpoint = await commitFlowRunCheckpoint(
+    runtime,
+    input as unknown as FlowRunCheckpointCommit<FlowRunProfileState>,
+  );
+  if (checkpoint.profile.kind !== 'AIDataWorkflow') {
+    throw new Error(`Flow run ${checkpoint.runId} is not an AI Data Workflow checkpoint.`);
+  }
+  return checkpoint as unknown as AIDataWorkflowRunCheckpoint;
+}
+
+export async function loadAIDataWorkflowCheckpoint(
+  runtime: FlowRunCheckpointRuntime,
+  input: FlowRunCheckpointKey,
+): Promise<AIDataWorkflowRunCheckpoint | undefined> {
+  const checkpoint = await loadFlowRunCheckpoint(runtime, input);
+  if (checkpoint === undefined) return undefined;
+  if (checkpoint.profile.kind !== 'AIDataWorkflow') {
+    throw new Error(`Flow run ${input.runId} is not an AI Data Workflow checkpoint.`);
+  }
+  return checkpoint as unknown as AIDataWorkflowRunCheckpoint;
+}
 
 export class AIDataWorkflowRunGraphError extends Error {
   constructor(message: string) {
@@ -51,14 +131,14 @@ export class AIDataWorkflowRunGraphError extends Error {
 
 export interface CreateAIDataWorkflowRuntimeOptions<
   Effects extends AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore,
+  Store extends AIWorkflowStateProjection,
 > {
   readonly ai: AIWorkflowRuntimeContext<Effects, Store>;
 }
 
 export function createAIDataWorkflowRuntime<
   Effects extends AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore,
+  Store extends AIWorkflowStateProjection,
 >(
   options: CreateAIDataWorkflowRuntimeOptions<Effects, Store>,
 ): AIDataWorkflowRuntime<Effects, Store> {
@@ -67,6 +147,42 @@ export function createAIDataWorkflowRuntime<
   };
 }
 
+export interface CreateAIDataWorkflowAgentNodeRuntimeBinderOptions {
+  readonly flowInstanceId: string;
+  readonly runId: string;
+  readonly checkpointRuntime: FlowRunCheckpointRuntime;
+  readonly effects: AIAgentHostEffectPort;
+  readonly workflowRef: `resource://${string}`;
+  readonly taskProofs: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
+  readonly generationForNode: (nodeId: string) => number;
+  readonly metadata?: FlowClosedObject;
+}
+
+/** Composition seam for ordinary TransformNode and SinkNode Processors. */
+export function createAIDataWorkflowAgentNodeRuntimeBinder(
+  options: CreateAIDataWorkflowAgentNodeRuntimeBinderOptions,
+): (runtime: AIDataWorkflowRuntime<any, AIWorkflowStateProjection>, identity: { readonly nodeId: string }) => AIDataWorkflowRuntime<AIWorkflowAuthoredEffects, AIWorkflowStateProjection> {
+  return (runtime, identity) => {
+    const generation = options.generationForNode(identity.nodeId);
+    const proof = options.taskProofs[identity.nodeId];
+    if (!proof) throw new Error(`AI_AGENT_TASK_PROOF_REQUIRED: no frozen proof for node ${identity.nodeId}.`);
+    const taskBinding = assertFrozenAIAgentTaskBinding(proof).task;
+    const effects = bindAIAgentProcessors({
+      checkpointRuntime: options.checkpointRuntime,
+      checkpointKey: { instanceId: options.flowInstanceId, runId: options.runId },
+      nodeId: identity.nodeId,
+      invocationKey: `${identity.nodeId}#${generation}`,
+      generation,
+      workflowKind: 'AIDataWorkflow',
+      workflowRef: options.workflowRef,
+      taskBinding,
+      effects: options.effects,
+      ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+    });
+    return Object.freeze({ ai: Object.freeze({ ...runtime.ai, effects }) });
+  };
+}
+
 export function defineEagerBackedAIDataWorkflow(
   definition: AIDataWorkflowDefinitionBinding['definition'],
 ): AIDataWorkflowDefinitionBinding {
@@ -296,6 +412,73 @@ function assertKnownDependencies(
         `AI Data Workflow node ${nodeId} depends on unknown node ${dependency}`,
       );
     }
+    if (nodes[dependency]?.status === 'Removed') {
+      throw new AIDataWorkflowRunGraphError(
+        `AI Data Workflow node ${nodeId} cannot depend on removed node ${dependency}`,
+      );
+    }
+  }
+}
+
+function assertRunGraphInputReferences(
+  nodes: Readonly<Record<string, AIDataWorkflowRunNode>>,
+): void {
+  for (const node of Object.values(nodes)) {
+    for (const [inputName, input] of Object.entries(node.inputs)) {
+      if (inputName.length === 0 || inputName !== inputName.trim()) {
+        throw new AIDataWorkflowRunGraphError(`AI Data Workflow node ${node.id} has an invalid input identity`);
+      }
+      if (typeof input !== 'object' || input === null || Array.isArray(input)) continue;
+      if (!('ref' in input) && !('nodeId' in input) && !('port' in input)) continue;
+      const reference = input as { readonly ref?: unknown; readonly nodeId?: unknown; readonly port?: unknown };
+      if (typeof reference.nodeId !== 'string' || typeof reference.port !== 'string'
+        || reference.ref !== `flow-port://#${reference.nodeId}/${reference.port}`) {
+        throw new AIDataWorkflowRunGraphError(
+          `AI Data Workflow node ${node.id} input ${inputName} has an invalid flow-port reference`,
+        );
+      }
+      const source = nodes[reference.nodeId];
+      if (!source || source.status === 'Removed' || !source.outputs.includes(reference.port)) {
+        throw new AIDataWorkflowRunGraphError(
+          `AI Data Workflow node ${node.id} input ${inputName} references an undeclared source output`,
+        );
+      }
+      if (!node.dependsOn.includes(reference.nodeId)) {
+        throw new AIDataWorkflowRunGraphError(
+          `AI Data Workflow node ${node.id} input ${inputName} is not projected by dependsOn`,
+        );
+      }
+    }
+  }
+}
+
+function assertReusePolicyAuthority(
+  reusePolicy: AIWorkflowEffectiveReusePolicy,
+  nodeType: AIWorkflowEffectiveReusePolicy['nodeType'],
+  config: Readonly<Record<string, unknown>>,
+  platformDefaultPolicy: AIWorkflowReusePolicy | undefined,
+  nodeId: string,
+): void {
+  if (reusePolicy.nodeType !== nodeType) {
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow node ${nodeId} reuse policy nodeType must equal ${nodeType}`,
+    );
+  }
+  const explicitValue = config.reuse_policy ?? config.reusePolicy;
+  const explicitPolicy = explicitValue === 'semantic-hash' || explicitValue === 'never'
+    ? explicitValue
+    : undefined;
+  const expected = explicitPolicy
+    ? { policy: explicitPolicy, source: 'node', nodeType }
+    : nodeType === 'manual'
+      ? { policy: 'never', source: 'node-type-default', nodeType }
+      : platformDefaultPolicy
+        ? { policy: platformDefaultPolicy, source: 'platform-default', nodeType }
+        : { policy: 'semantic-hash', source: 'node-type-default', nodeType };
+  if (reusePolicy.policy !== expected.policy || reusePolicy.source !== expected.source) {
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow node ${nodeId} reuse policy must match its declared config and platform authority`,
+    );
   }
 }
 
@@ -319,6 +502,7 @@ export function createAIDataWorkflowRunGraph(
         explicitPolicy: configReusePolicy(config),
         platformDefaultPolicy,
       });
+      assertReusePolicyAuthority(reusePolicy, nodeType, config, platformDefaultPolicy, planNode.id);
       const runNode: AIDataWorkflowRunNode = {
         id: planNode.id,
         tag: planNode.tag,
@@ -341,15 +525,18 @@ export function createAIDataWorkflowRunGraph(
     assertKnownDependencies(nodes, node.id, node.dependsOn);
   }
 
-  return {
+  const graph = {
     runId,
     binding,
+    ...(platformDefaultPolicy === undefined ? {} : { platformDefaultPolicy }),
     currentGeneration: 0,
     nodes: recomputeDependents(nodes, declarationOrder),
     declarationOrder,
     patchHistory: [],
     invalidations: [],
   };
+  assertRunGraphInputReferences(graph.nodes);
+  return graph;
 }
 
 function makePatchNode(
@@ -360,6 +547,12 @@ function makePatchNode(
   const tag = spec.tag ?? GENERATED_NODE_TAG;
   const config = cloneRecord(spec.config);
   const nodeType = nodeTypeForPatchNode({ ...spec, tag, config });
+  const reusePolicy = spec.reusePolicy ?? resolveAIWorkflowReusePolicy({
+    nodeType,
+    explicitPolicy: configReusePolicy(config),
+    platformDefaultPolicy,
+  });
+  assertReusePolicyAuthority(reusePolicy, nodeType, config, platformDefaultPolicy, spec.id);
   return {
     id: spec.id,
     tag,
@@ -372,11 +565,7 @@ function makePatchNode(
     config,
     dependsOn: uniqueStrings(spec.dependsOn ?? []),
     dependents: [],
-    reusePolicy: spec.reusePolicy ?? resolveAIWorkflowReusePolicy({
-      nodeType,
-      explicitPolicy: configReusePolicy(config),
-      platformDefaultPolicy,
-    }),
+    reusePolicy,
   };
 }
 
@@ -412,13 +601,18 @@ function applyInvalidations(
   let nextNodes: Record<string, AIDataWorkflowRunNode> = Object.fromEntries(
     Object.entries(nodes).map(([nodeId, node]) => [nodeId, cloneNode(node)]),
   );
-  const invalidations = existingInvalidations.map(cloneInvalidation);
+  let invalidations = existingInvalidations.map(cloneInvalidation);
   const emitted = new Set<string>();
 
   for (const source of sources) {
     for (const nodeId of collectTransitive(nextNodes, source.nodeId, source.includeSource)) {
       const node = nextNodes[nodeId];
       if (!node || node.status === 'Removed') continue;
+      if (generation < node.generation) {
+        throw new AIDataWorkflowRunGraphError(
+          `AI Data Workflow invalidation generation ${generation} precedes node ${nodeId}@${node.generation}`,
+        );
+      }
       const key = `${source.nodeId}:${nodeId}:${generation}`;
       if (emitted.has(key)) continue;
       emitted.add(key);
@@ -429,14 +623,20 @@ function applyInvalidations(
         sourceNodeId: source.nodeId,
         ...(atMs === undefined ? {} : { atMs }),
       };
+      invalidations = invalidations.filter((fact) => fact.nodeId !== nodeId);
       invalidations.push(invalidation);
+      const {
+        result: _staleResult,
+        semanticFingerprint: _staleFingerprint,
+        ...currentFacts
+      } = node;
       nextNodes = {
         ...nextNodes,
         [nodeId]: {
-          ...node,
+          ...currentFacts,
           status: 'Invalidated',
           generation,
-          invalidatedBy: [...(node.invalidatedBy ?? []), invalidation],
+          invalidatedBy: [invalidation],
         },
       };
     }
@@ -454,6 +654,15 @@ export function invalidateAIDataWorkflowNode(
   requireNode(graph.nodes, nodeId);
   const generation = options.generation ?? graph.currentGeneration;
   const sourceNodeId = options.sourceNodeId ?? nodeId;
+  requireNode(graph.nodes, sourceNodeId);
+  if (!Number.isSafeInteger(generation) || generation < 0) {
+    throw new AIDataWorkflowRunGraphError('AI Data Workflow invalidation generation must be a non-negative safe integer');
+  }
+  if (generation < graph.currentGeneration) {
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow invalidation generation ${generation} precedes current generation ${graph.currentGeneration}`,
+    );
+  }
   const cloned = cloneGraph(graph);
   const { nodes, invalidations } = applyInvalidations(
     cloned.nodes,
@@ -462,6 +671,7 @@ export function invalidateAIDataWorkflowNode(
     generation,
     options.atMs,
   );
+  if (invalidations.length === cloned.invalidations.length) return cloned;
   return {
     ...cloned,
     currentGeneration: Math.max(cloned.currentGeneration, generation),
@@ -477,8 +687,26 @@ export function applyAIDataWorkflowGraphPatch(
   if (graph.patchHistory.some((record) => record.patchId === patch.patchId)) {
     throw new AIDataWorkflowRunGraphError(`AI Data Workflow patch ${patch.patchId} already applied`);
   }
+  const patchTargets = new Set<string>();
+  for (const operation of patch.operations) {
+    const target = operation.op === 'add-node' ? operation.node.id : operation.nodeId;
+    if (patchTargets.has(target)) {
+      throw new AIDataWorkflowRunGraphError(
+        `AI Data Workflow patch ${patch.patchId} targets node ${target} more than once`,
+      );
+    }
+    patchTargets.add(target);
+  }
 
-  const generation = graph.currentGeneration + 1;
+  const generation = patch.generation ?? graph.currentGeneration + 1;
+  if (!Number.isSafeInteger(generation) || generation < 1) {
+    throw new AIDataWorkflowRunGraphError('AI Data Workflow patch generation must be a positive safe integer');
+  }
+  if (generation < graph.currentGeneration) {
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow patch generation ${generation} precedes current generation ${graph.currentGeneration}`,
+    );
+  }
   const atMs = patch.atMs ?? Date.now();
   let declarationOrder = [...graph.declarationOrder];
   let nodes = Object.fromEntries(
@@ -499,6 +727,7 @@ export function applyAIDataWorkflowGraphPatch(
           declarationIndex: operation.node.declarationIndex ?? declarationOrder.length,
         },
         generation,
+        graph.platformDefaultPolicy,
       );
       assertKnownDependencies(nodes, node.id, node.dependsOn);
       nodes = { ...nodes, [node.id]: node };
@@ -508,6 +737,11 @@ export function applyAIDataWorkflowGraphPatch(
 
     if (operation.op === 'update-node') {
       const existing = requireNode(nodes, operation.nodeId);
+      if (generation < existing.generation) {
+        throw new AIDataWorkflowRunGraphError(
+          `AI Data Workflow patch generation ${generation} precedes node ${existing.id}@${existing.generation}`,
+        );
+      }
       if (existing.status === 'Removed') {
         throw new AIDataWorkflowRunGraphError(
           `AI Data Workflow node ${operation.nodeId} has been removed`,
@@ -520,13 +754,15 @@ export function applyAIDataWorkflowGraphPatch(
         : existing.dependsOn;
       assertKnownDependencies(nodes, existing.id, dependsOn);
       const reusePolicy = operation.changes.reusePolicy ?? (
-        operation.changes.config
+        operation.changes.config || operation.changes.nodeType
           ? resolveAIWorkflowReusePolicy({
             nodeType,
             explicitPolicy: configReusePolicy(config),
+            platformDefaultPolicy: graph.platformDefaultPolicy,
           })
           : existing.reusePolicy
       );
+      assertReusePolicyAuthority(reusePolicy, nodeType, config, graph.platformDefaultPolicy, existing.id);
       nodes = {
         ...nodes,
         [existing.id]: {
@@ -551,10 +787,24 @@ export function applyAIDataWorkflowGraphPatch(
     }
 
     const existing = requireNode(nodes, operation.nodeId);
+    if (existing.status === 'Removed') {
+      throw new AIDataWorkflowRunGraphError(`AI Data Workflow node ${operation.nodeId} has already been removed`);
+    }
+    if (generation < existing.generation) {
+      throw new AIDataWorkflowRunGraphError(
+        `AI Data Workflow patch generation ${generation} precedes node ${existing.id}@${existing.generation}`,
+      );
+    }
+    const {
+      result: _staleResult,
+      semanticFingerprint: _staleFingerprint,
+      invalidatedBy: _activeInvalidation,
+      ...currentFacts
+    } = existing;
     nodes = {
       ...nodes,
       [existing.id]: {
-        ...existing,
+        ...currentFacts,
         generation,
         status: 'Removed',
       },
@@ -569,13 +819,13 @@ export function applyAIDataWorkflowGraphPatch(
   nodes = recomputeDependents(nodes, declarationOrder);
   const invalidated = applyInvalidations(
     nodes,
-    graph.invalidations,
+    graph.invalidations.filter((fact) => nodes[fact.nodeId]?.status !== 'Removed'),
     invalidationSources,
     generation,
     atMs,
   );
 
-  return {
+  const nextGraph = {
     ...graph,
     currentGeneration: generation,
     nodes: invalidated.nodes,
@@ -592,6 +842,11 @@ export function applyAIDataWorkflowGraphPatch(
     ],
     invalidations: invalidated.invalidations,
   };
+  for (const node of Object.values(nextGraph.nodes)) {
+    if (node.status !== 'Removed') assertKnownDependencies(nextGraph.nodes, node.id, node.dependsOn);
+  }
+  assertRunGraphInputReferences(nextGraph.nodes);
+  return nextGraph;
 }
 
 function stableSemanticValue(value: unknown): string {
@@ -608,10 +863,14 @@ function stableSemanticValue(value: unknown): string {
 
   const entries = Object.entries(value as Record<string, unknown>)
     .filter(([, item]) => typeof item !== 'function' && typeof item !== 'symbol')
-    .sort(([left], [right]) => left.localeCompare(right));
+    .sort(([left], [right]) => compareCodeUnits(left, right));
   return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableSemanticValue(item)}`).join(',')}}`;
 }
 
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 function fnv1a64(value: string): string {
   let hash = 0xcbf29ce484222325n;
   const prime = 0x100000001b3n;
@@ -695,10 +954,29 @@ export function recordAIDataWorkflowNodeResult(
   result: AIWorkflowNodeResult,
 ): AIDataWorkflowRunGraph {
   const node = requireNode(graph.nodes, nodeId);
+  if (result.nodeId !== nodeId) {
+    throw new AIDataWorkflowRunGraphError(`AI Data Workflow result identity ${result.nodeId} does not match node ${nodeId}`);
+  }
+  if (result.generation !== node.generation) {
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow result generation ${result.generation} does not match node ${nodeId}@${node.generation}`,
+    );
+  }
+  if (node.result
+    && (node.result.status === 'Succeeded' || node.result.status === 'Failed' || node.result.status === 'Reused')) {
+    if (JSON.stringify(node.result) === JSON.stringify(result)) return cloneGraph(graph);
+    throw new AIDataWorkflowRunGraphError(
+      `AI Data Workflow terminal result ${nodeId}@${node.generation} is immutable`,
+    );
+  }
+  const {
+    invalidatedBy: _acceptedInvalidation,
+    ...nodeFacts
+  } = node;
   const nodes = {
     ...graph.nodes,
     [nodeId]: {
-      ...node,
+      ...nodeFacts,
       generation: result.generation,
       status: toRunNodeStatus(result.status),
       result: cloneNodeResult(result),
@@ -709,6 +987,7 @@ export function recordAIDataWorkflowNodeResult(
     ...graph,
     currentGeneration: Math.max(graph.currentGeneration, result.generation),
     nodes: recomputeDependents(nodes, graph.declarationOrder),
+    invalidations: graph.invalidations.filter((fact) => fact.nodeId !== nodeId),
   };
 }