ai-workflow-logic 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-logic",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "description": "AI workflow domain projections and pure runtime helpers with an explicit Halfcode filesystem adapter",
   "type": "module",
@@ -8,12 +8,15 @@
   "exports": {
     ".": "./src/index.ts",
     "./browser": "./src/browser.ts",
+    "./checkpoint-filesystem": "./src/checkpoint-filesystem.ts",
     "./filesystem": "./src/filesystem.ts",
     "./run-freeze": "./src/run-freeze.ts"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.1.3",
-    "halfcode-compiler.xnl": "0.2.2"
+    "ai-workflow-contract": "0.1.4",
+    "halfcode-compiler.xnl": "0.2.2",
+    "work-ctrl-flow-contract": "0.1.1",
+    "work-ctrl-flow-logic": "0.1.1"
   },
   "files": [
     "src"

package/src/agent-invocation.ts

@@ -0,0 +1,282 @@
+import type {
+  AIAgentEffectConfig,
+  AIAgentHostRunResult,
+  AIAgentInstanceReference,
+  AIAgentInvocation,
+  AIAgentInvocationReceipt,
+  AIAgentProcessorRuntime,
+  AIAgentRunResult,
+  AIAgentSelector,
+  AIWorkflowAuthoredEffects,
+  AIWorkflowFlowRunCheckpoint,
+  AIWorkflowProfileDurableState,
+  FlowClosedValue,
+} from 'ai-workflow-contract';
+import {
+  AIAgentInvocationError,
+  normalizeAIAgentEffectConfig,
+  normalizeAIAgentInvocation,
+  normalizeAIAgentSelector,
+  normalizeCanonicalAIAgentState,
+  assertAIAgentNodeTaskBinding,
+} from './agent-state.js';
+import { normalizeFlowClosedObject, normalizeFlowClosedValue } from './run-checkpoint.js';
+
+export { AIAgentInvocationError, normalizeAIAgentEffectConfig, normalizeAIAgentInvocation, normalizeAIAgentSelector } from './agent-state.js';
+
+function fail(code: string, location: string, message: string): never {
+  throw new AIAgentInvocationError(code, location, message);
+}
+
+function profileAI(checkpoint: AIWorkflowFlowRunCheckpoint): AIWorkflowProfileDurableState {
+  if (checkpoint.profile.kind !== 'AICtrlWorkflow' && checkpoint.profile.kind !== 'AIDataWorkflow') {
+    return fail('AI_AGENT_PROFILE_REQUIRED', 'checkpoint.profile.kind', 'Agent invocation requires an AI workflow profile.');
+  }
+  return normalizeCanonicalAIAgentState(checkpoint.profile.ai, 'checkpoint.profile.ai');
+}
+
+async function loadCheckpoint(runtime: AIAgentProcessorRuntime): Promise<AIWorkflowFlowRunCheckpoint> {
+  const checkpoint = await runtime.checkpointRuntime.checkpointStore.load(runtime.checkpointKey) as AIWorkflowFlowRunCheckpoint | undefined;
+  if (!checkpoint) fail('AI_AGENT_CHECKPOINT_NOT_FOUND', 'runtime.checkpointKey', 'Canonical Flow checkpoint does not exist.');
+  if (checkpoint.instanceId !== runtime.checkpointKey.instanceId || checkpoint.runId !== runtime.checkpointKey.runId) {
+    fail('AI_AGENT_CHECKPOINT_IDENTITY_MISMATCH', 'runtime.checkpointKey', 'Loaded checkpoint identity differs from the requested run.');
+  }
+  return checkpoint;
+}
+
+function withAI(checkpoint: AIWorkflowFlowRunCheckpoint, ai: AIWorkflowProfileDurableState): AIWorkflowFlowRunCheckpoint {
+  if (checkpoint.profile.kind === 'AICtrlWorkflow') return { ...checkpoint, version: checkpoint.version + 1, profile: { ...checkpoint.profile, ai } };
+  if (checkpoint.profile.kind === 'AIDataWorkflow') return { ...checkpoint, version: checkpoint.version + 1, profile: { ...checkpoint.profile, ai } };
+  return fail('AI_AGENT_PROFILE_REQUIRED', 'checkpoint.profile.kind', 'Agent invocation requires an AI workflow profile.');
+}
+
+async function commitAI(runtime: AIAgentProcessorRuntime, checkpoint: AIWorkflowFlowRunCheckpoint, ai: AIWorkflowProfileDurableState): Promise<AIWorkflowFlowRunCheckpoint> {
+  return runtime.checkpointRuntime.checkpointStore.commit({ expectedVersion: checkpoint.version, checkpoint: withAI(checkpoint, normalizeCanonicalAIAgentState(ai)) }) as Promise<AIWorkflowFlowRunCheckpoint>;
+}
+
+function same(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function semanticFacts(config: AIAgentEffectConfig, invocationMetadata?: Readonly<Record<string, FlowClosedValue>>): Readonly<Record<string, FlowClosedValue>> {
+  return normalizeFlowClosedObject({
+    materialRefs: config.materialRefs ?? [],
+    effectPolicy: config.effectPolicy ?? null,
+    invocationMetadata: invocationMetadata ?? null,
+  }, 'semanticFacts');
+}
+
+function assertTaskAuthority(runtime: AIAgentProcessorRuntime, config: AIAgentEffectConfig): void {
+  if (!runtime.taskBinding) fail('AI_AGENT_TASK_BINDING_REQUIRED', 'runtime.taskBinding', 'A frozen Agent task binding is required.');
+  assertAIAgentNodeTaskBinding(runtime.taskBinding, {
+    workflowKind: runtime.workflowKind,
+    workflowRef: runtime.workflowRef,
+    nodeId: runtime.nodeId,
+  }, config);
+}
+
+function assertSameInvocation(receipt: AIAgentInvocationReceipt, runtime: AIAgentProcessorRuntime, mode: 'new' | 'targeted', input: FlowClosedValue, config: AIAgentEffectConfig, invocationMetadata?: Readonly<Record<string, FlowClosedValue>>): void {
+  if (receipt.nodeId !== runtime.nodeId || receipt.mode !== mode || receipt.agentDefinitionRef !== config.agentDefinitionRef || !same(receipt.input, input) || receipt.generation !== runtime.generation || !same(receipt.semanticFacts, semanticFacts(config, invocationMetadata))) {
+    fail('AI_AGENT_INVOCATION_KEY_CONFLICT', `checkpoint.profile.ai.invocationsByKey.${runtime.invocationKey}`, 'Invocation key is already bound to different facts.');
+  }
+  if (mode === 'new' && receipt.instanceName !== config.instanceName) fail('AI_AGENT_INVOCATION_KEY_CONFLICT', `checkpoint.profile.ai.invocationsByKey.${runtime.invocationKey}.instanceName`, 'Invocation key has another name intent.');
+}
+
+function resultFromReceipt(ai: AIWorkflowProfileDurableState, receipt: AIAgentInvocationReceipt): AIAgentRunResult {
+  if (receipt.status !== 'completed' || receipt.instanceId === undefined || receipt.output === undefined) fail('AI_AGENT_COMPLETED_INVOCATION_INCOMPLETE', 'receipt', 'Completed receipt is incomplete.');
+  const instance = ai.instancesById[receipt.instanceId];
+  if (!instance) fail('AI_AGENT_INSTANCE_ID_NOT_FOUND', 'receipt.instanceId', 'Completed receipt instance is missing.');
+  return Object.freeze({
+    output: receipt.output,
+    instance,
+    receipt: Object.freeze({ invocationKey: receipt.invocationKey, nodeId: receipt.nodeId, status: 'completed' as const }),
+  });
+}
+
+function pendingReceipt(runtime: AIAgentProcessorRuntime, mode: 'new' | 'targeted', input: FlowClosedValue, config: AIAgentEffectConfig, instance?: AIAgentInstanceReference, invocationMetadata?: Readonly<Record<string, FlowClosedValue>>): AIAgentInvocationReceipt {
+  const instanceName = mode === 'targeted' ? instance?.instanceName : config.instanceName;
+  return Object.freeze({
+    invocationKey: runtime.invocationKey,
+    nodeId: runtime.nodeId,
+    status: 'pending',
+    mode,
+    agentDefinitionRef: config.agentDefinitionRef,
+    input,
+    semanticFacts: semanticFacts(config, invocationMetadata),
+    ...(instanceName === undefined ? {} : { instanceName }),
+    ...(instance === undefined ? {} : { instanceId: instance.instanceId }),
+    ...(runtime.generation === undefined ? {} : { generation: runtime.generation }),
+    ...(runtime.metadata === undefined ? {} : { metadata: normalizeFlowClosedObject(runtime.metadata, 'runtime.metadata') }),
+  });
+}
+
+function reserveName(ai: AIWorkflowProfileDurableState, receipt: AIAgentInvocationReceipt): void {
+  if (receipt.instanceName === undefined) return;
+  if (ai.instanceIdByName[receipt.instanceName] !== undefined) fail('AI_AGENT_INSTANCE_NAME_ALREADY_BOUND', 'config.instanceName', 'Instance name is already bound.');
+  for (const existing of Object.values(ai.invocationsByKey)) {
+    if (existing.invocationKey !== receipt.invocationKey && existing.status === 'pending' && existing.instanceName === receipt.instanceName) {
+      fail('AI_AGENT_INSTANCE_NAME_RESERVED', 'config.instanceName', 'Instance name is already reserved by another invocation.');
+    }
+  }
+}
+
+function resolveSelector(ai: AIWorkflowProfileDurableState, selector: AIAgentSelector, config: AIAgentEffectConfig): AIAgentInstanceReference {
+  const instanceId = 'byInstanceId' in selector ? selector.byInstanceId : ai.instanceIdByName[selector.byInstanceName];
+  if (instanceId === undefined) fail('AI_AGENT_INSTANCE_NAME_NOT_FOUND', 'selector.byInstanceName', 'Named Agent instance does not exist.');
+  const instance = ai.instancesById[instanceId];
+  if (!instance) fail('AI_AGENT_INSTANCE_ID_NOT_FOUND', 'selector', 'Agent instance does not exist.');
+  if (instance.instanceName !== undefined && ai.instanceIdByName[instance.instanceName] !== instance.instanceId) fail('AI_AGENT_INSTANCE_INDEX_CONFLICT', 'checkpoint.profile.ai', 'Agent instance indexes are not reciprocal.');
+  if (instance.agentDefinitionRef !== config.agentDefinitionRef) fail('AI_AGENT_DEFINITION_CONFLICT', 'config.agentDefinitionRef', 'Target instance is bound to another Agent definition.');
+  return instance;
+}
+
+function normalizeHostResult(result: AIAgentHostRunResult, config: AIAgentEffectConfig, expected?: AIAgentInstanceReference): { output: FlowClosedValue; instance: AIAgentInstanceReference; hostReceipt?: Record<string, FlowClosedValue> } {
+  const output = normalizeFlowClosedValue(result.output, 'hostResult.output');
+  const source = result.instance;
+  if (!source || typeof source !== 'object') fail('AI_AGENT_HOST_INSTANCE_INVALID', 'hostResult.instance', 'Host result must contain an instance reference.');
+  const candidate = normalizeCanonicalAIAgentState({
+    schemaVersion: 'depa.ai-agent-state/v1',
+    instancesById: {
+      [source.instanceId]: {
+        authority: source.authority,
+        instanceId: source.instanceId,
+        ...(source.instanceName === undefined ? {} : { instanceName: source.instanceName }),
+        ...(source.sessionId === undefined ? {} : { sessionId: source.sessionId }),
+        ...(source.metadata === undefined ? {} : { metadata: source.metadata }),
+        agentDefinitionRef: source.agentDefinitionRef ?? config.agentDefinitionRef,
+      },
+    },
+    instanceIdByName: source.instanceName === undefined ? {} : { [source.instanceName]: source.instanceId },
+    invocationsByKey: {},
+  }, 'hostResult.state');
+  const instance = candidate.instancesById[source.instanceId];
+  if (!instance || instance.agentDefinitionRef !== config.agentDefinitionRef) fail('AI_AGENT_HOST_DEFINITION_CONFLICT', 'hostResult.instance.agentDefinitionRef', 'Host instance uses another Agent definition.');
+  if (config.instanceName !== undefined && instance.instanceName !== config.instanceName) fail('AI_AGENT_HOST_NAME_CONFLICT', 'hostResult.instance.instanceName', 'Host instance did not preserve the reserved name.');
+  if (expected && (instance.instanceId !== expected.instanceId || instance.authority !== expected.authority)) fail('AI_AGENT_HOST_TARGET_CONFLICT', 'hostResult.instance', 'Host targeted result differs from the selected instance.');
+  return { output, instance, ...(result.hostReceipt === undefined ? {} : { hostReceipt: normalizeFlowClosedObject(result.hostReceipt, 'hostResult.hostReceipt') }) };
+}
+
+async function complete(runtime: AIAgentProcessorRuntime, checkpoint: AIWorkflowFlowRunCheckpoint, pending: AIAgentInvocationReceipt, host: AIAgentHostRunResult, config: AIAgentEffectConfig, expected?: AIAgentInstanceReference): Promise<AIAgentRunResult> {
+  const normalized = normalizeHostResult(host, config, expected);
+  const latest = await loadCheckpoint(runtime);
+  const ai = profileAI(latest);
+  const accepted = ai.invocationsByKey[runtime.invocationKey];
+  if (accepted?.status === 'completed') return resultFromReceipt(ai, accepted);
+  if (!accepted || !same(accepted, pending)) fail('AI_AGENT_INVOCATION_RESERVATION_CHANGED', 'checkpoint.profile.ai', 'Invocation reservation changed before completion.');
+  const prior = ai.instancesById[normalized.instance.instanceId];
+  if (prior && !same(prior, normalized.instance)) fail('AI_AGENT_INSTANCE_ID_CONFLICT', 'hostResult.instance.instanceId', 'Instance id is already bound to different facts.');
+  if (normalized.instance.instanceName !== undefined) {
+    const priorId = ai.instanceIdByName[normalized.instance.instanceName];
+    if (priorId !== undefined && priorId !== normalized.instance.instanceId) fail('AI_AGENT_INSTANCE_NAME_ALREADY_BOUND', 'hostResult.instance.instanceName', 'Instance name is already bound to another id.');
+  }
+  const completed: AIAgentInvocationReceipt = Object.freeze({ ...pending, status: 'completed', instanceId: normalized.instance.instanceId, output: normalized.output, ...(normalized.hostReceipt === undefined ? {} : { hostReceipt: normalized.hostReceipt }) });
+  const nextAI = normalizeCanonicalAIAgentState({
+    ...ai,
+    instancesById: { ...ai.instancesById, [normalized.instance.instanceId]: normalized.instance },
+    instanceIdByName: normalized.instance.instanceName === undefined ? ai.instanceIdByName : { ...ai.instanceIdByName, [normalized.instance.instanceName]: normalized.instance.instanceId },
+    invocationsByKey: { ...ai.invocationsByKey, [runtime.invocationKey]: completed },
+  });
+  try {
+    const committed = await commitAI(runtime, latest, nextAI);
+    return resultFromReceipt(profileAI(committed), completed);
+  } catch (error) {
+    const converged = await loadCheckpoint(runtime);
+    if (converged.version <= latest.version) throw error;
+    const convergedAI = profileAI(converged);
+    const acceptedCompletion = convergedAI.invocationsByKey[pending.invocationKey];
+    if (!acceptedCompletion || acceptedCompletion.status !== 'completed'
+      || acceptedCompletion.nodeId !== pending.nodeId
+      || acceptedCompletion.mode !== pending.mode
+      || acceptedCompletion.agentDefinitionRef !== pending.agentDefinitionRef
+      || acceptedCompletion.instanceId !== normalized.instance.instanceId
+      || acceptedCompletion.instanceName !== normalized.instance.instanceName
+      || acceptedCompletion.generation !== pending.generation
+      || !same(acceptedCompletion.input, pending.input)
+      || !same(acceptedCompletion.semanticFacts, pending.semanticFacts)) throw error;
+    const acceptedInstance = convergedAI.instancesById[normalized.instance.instanceId];
+    if (!acceptedInstance || !same(acceptedInstance, normalized.instance)) throw error;
+    return resultFromReceipt(convergedAI, acceptedCompletion);
+  }
+}
+
+export async function runAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(runtime: AIAgentProcessorRuntime, input: Input, configInput: AIAgentEffectConfig): Promise<AIAgentRunResult<Output>> {
+  const inputValue = normalizeFlowClosedValue(input, 'input') as Input;
+  const config = normalizeAIAgentEffectConfig(configInput);
+  assertTaskAuthority(runtime, config);
+  let checkpoint = await loadCheckpoint(runtime);
+  let ai = profileAI(checkpoint);
+  let receipt = ai.invocationsByKey[runtime.invocationKey];
+  if (receipt) {
+    assertSameInvocation(receipt, runtime, 'new', inputValue, config);
+    if (receipt.status === 'completed') return resultFromReceipt(ai, receipt) as AIAgentRunResult<Output>;
+  } else {
+    receipt = pendingReceipt(runtime, 'new', inputValue, config);
+    reserveName(ai, receipt);
+    try {
+      checkpoint = await commitAI(runtime, checkpoint, { ...ai, invocationsByKey: { ...ai.invocationsByKey, [runtime.invocationKey]: receipt } });
+    } catch (error) {
+      const latest = await loadCheckpoint(runtime);
+      if (latest.version <= checkpoint.version) throw error;
+      const latestAI = profileAI(latest);
+      const accepted = latestAI.invocationsByKey[runtime.invocationKey];
+      if (accepted) {
+        assertSameInvocation(accepted, runtime, 'new', inputValue, config);
+        checkpoint = latest;
+      } else {
+        reserveName(latestAI, receipt);
+        checkpoint = await commitAI(runtime, latest, { ...latestAI, invocationsByKey: { ...latestAI.invocationsByKey, [runtime.invocationKey]: receipt } });
+      }
+    }
+    ai = profileAI(checkpoint);
+    receipt = ai.invocationsByKey[runtime.invocationKey]!;
+  }
+  if (receipt.status === 'completed') return resultFromReceipt(ai, receipt) as AIAgentRunResult<Output>;
+  const host = await runtime.effects.runAgent({ invocationKey: runtime.invocationKey, flowInstanceId: runtime.checkpointKey.instanceId, runId: runtime.checkpointKey.runId, nodeId: runtime.nodeId, ...(runtime.generation === undefined ? {} : { generation: runtime.generation }), input: inputValue, agentDefinitionRef: config.agentDefinitionRef, ...(config.instanceName === undefined ? {} : { instanceName: config.instanceName }), ...(config.materialRefs === undefined ? {} : { materialRefs: config.materialRefs }), ...(config.effectPolicy === undefined ? {} : { effectPolicy: config.effectPolicy }), ...(runtime.signal === undefined ? {} : { signal: runtime.signal }), ...(runtime.metadata === undefined ? {} : { metadata: runtime.metadata }) });
+  return complete(runtime, checkpoint, receipt, host, config) as Promise<AIAgentRunResult<Output>>;
+}
+
+export async function runTargetedAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(runtime: AIAgentProcessorRuntime, selectorInput: AIAgentSelector, invocationInput: AIAgentInvocation<Input>, configInput: AIAgentEffectConfig): Promise<AIAgentRunResult<Output>> {
+  const selector = normalizeAIAgentSelector(selectorInput);
+  const invocation = normalizeAIAgentInvocation<Input>(invocationInput);
+  const config = normalizeAIAgentEffectConfig(configInput);
+  assertTaskAuthority(runtime, config);
+  let checkpoint = await loadCheckpoint(runtime);
+  let ai = profileAI(checkpoint);
+  const instance = resolveSelector(ai, selector, config);
+  let receipt = ai.invocationsByKey[runtime.invocationKey];
+  if (receipt) {
+    assertSameInvocation(receipt, runtime, 'targeted', invocation.payload, config, invocation.metadata);
+    if (receipt.instanceId !== instance.instanceId) fail('AI_AGENT_INVOCATION_TARGET_CONFLICT', 'selector', 'Invocation key is reserved for another instance.');
+    if (receipt.status === 'completed') return resultFromReceipt(ai, receipt) as AIAgentRunResult<Output>;
+  } else {
+    receipt = pendingReceipt(runtime, 'targeted', invocation.payload, config, instance, invocation.metadata);
+    try {
+      checkpoint = await commitAI(runtime, checkpoint, { ...ai, invocationsByKey: { ...ai.invocationsByKey, [runtime.invocationKey]: receipt } });
+    } catch (error) {
+      const latest = await loadCheckpoint(runtime);
+      if (latest.version <= checkpoint.version) throw error;
+      const latestAI = profileAI(latest);
+      const resolved = resolveSelector(latestAI, selector, config);
+      if (resolved.instanceId !== instance.instanceId) fail('AI_AGENT_SELECTOR_CHANGED', 'selector', 'Selector resolved to another instance after checkpoint conflict.');
+      const accepted = latestAI.invocationsByKey[runtime.invocationKey];
+      if (accepted) {
+        assertSameInvocation(accepted, runtime, 'targeted', invocation.payload, config, invocation.metadata);
+        checkpoint = latest;
+      } else {
+        checkpoint = await commitAI(runtime, latest, { ...latestAI, invocationsByKey: { ...latestAI.invocationsByKey, [runtime.invocationKey]: receipt } });
+      }
+    }
+    ai = profileAI(checkpoint);
+    receipt = ai.invocationsByKey[runtime.invocationKey]!;
+  }
+  if (receipt.status === 'completed') return resultFromReceipt(ai, receipt) as AIAgentRunResult<Output>;
+  const host = await runtime.effects.runTargetedAgent({ invocationKey: runtime.invocationKey, flowInstanceId: runtime.checkpointKey.instanceId, runId: runtime.checkpointKey.runId, nodeId: runtime.nodeId, ...(runtime.generation === undefined ? {} : { generation: runtime.generation }), input: invocation.payload, instance, agentDefinitionRef: config.agentDefinitionRef, ...(config.materialRefs === undefined ? {} : { materialRefs: config.materialRefs }), ...(config.effectPolicy === undefined ? {} : { effectPolicy: config.effectPolicy }), ...(runtime.signal === undefined ? {} : { signal: runtime.signal }), metadata: { ...(runtime.metadata ?? {}), ...(invocation.metadata ?? {}) } });
+  return complete(runtime, checkpoint, receipt, host, config, instance) as Promise<AIAgentRunResult<Output>>;
+}
+
+export function bindAIAgentProcessors(runtime: AIAgentProcessorRuntime): AIWorkflowAuthoredEffects {
+  return Object.freeze({
+    runAgent: <Input extends FlowClosedValue, Output extends FlowClosedValue>(input: Input, config: AIAgentEffectConfig) => runAgent<Input, Output>(runtime, input, config),
+    runTargetedAgent: <Input extends FlowClosedValue, Output extends FlowClosedValue>(selector: AIAgentSelector, invocation: AIAgentInvocation<Input>, config: AIAgentEffectConfig) => runTargetedAgent<Input, Output>(runtime, selector, invocation, config),
+  });
+}

package/src/agent-state.ts

@@ -0,0 +1,293 @@
+import type {
+  AIAgentEffectConfig,
+  AIAgentInstanceReference,
+  AIAgentInvocation,
+  AIAgentInvocationReceipt,
+  AIAgentSelector,
+  AIWorkflowProfileDurableState,
+  AIWorkflowAgentTaskRef,
+  AIWorkflowKind,
+  FlowClosedObject,
+  FlowClosedValue,
+  LegacyAIWorkflowProfileDurableState,
+} from 'ai-workflow-contract';
+import { normalizeFlowClosedObject, normalizeFlowClosedValue } from './run-checkpoint.js';
+
+export class AIAgentInvocationError extends Error {
+  constructor(public readonly code: string, public readonly location: string, message: string) {
+    super(`${location}: ${message}`);
+    this.name = 'AIAgentInvocationError';
+  }
+}
+
+function fail(code: string, location: string, message: string): never {
+  throw new AIAgentInvocationError(code, location, message);
+}
+
+function record(value: unknown, required: readonly string[], optional: readonly string[], location: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) fail('AI_AGENT_OBJECT_REQUIRED', location, 'Expected a plain data object.');
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) fail('AI_AGENT_OBJECT_REQUIRED', location, 'Expected a plain data object.');
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const allowed = new Set([...required, ...optional]);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== 'string') fail('AI_AGENT_SYMBOL_UNSUPPORTED', location, 'Symbol fields are not supported.');
+    const descriptor = descriptors[key]!;
+    if (!('value' in descriptor)) fail('AI_AGENT_ACCESSOR_UNSUPPORTED', `${location}.${key}`, 'Accessor fields are not supported.');
+    if (!allowed.has(key)) fail('AI_AGENT_FIELD_UNSUPPORTED', `${location}.${key}`, 'Unexpected field.');
+  }
+  for (const key of required) if (!Object.prototype.hasOwnProperty.call(descriptors, key)) fail('AI_AGENT_FIELD_REQUIRED', `${location}.${key}`, 'Required field is missing.');
+  return value as Record<string, unknown>;
+}
+
+function objectMap(value: unknown, location: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) fail('AI_AGENT_INDEX_REQUIRED', location, 'Expected a plain data index.');
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) fail('AI_AGENT_INDEX_REQUIRED', location, 'Expected a plain data index.');
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const output: Record<string, unknown> = {};
+  for (const key of Object.keys(descriptors).sort(compareCodeUnits)) {
+    const descriptor = descriptors[key]!;
+    if (!('value' in descriptor)) fail('AI_AGENT_ACCESSOR_UNSUPPORTED', `${location}.${key}`, 'Accessor fields are not supported.');
+    output[key] = descriptor.value;
+  }
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== 'string')) fail('AI_AGENT_SYMBOL_UNSUPPORTED', location, 'Symbol fields are not supported.');
+  return output;
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = left.charCodeAt(index) - right.charCodeAt(index);
+    if (difference !== 0) return difference;
+  }
+  return left.length - right.length;
+}
+
+function identity(value: unknown, location: string): string {
+  if (typeof value !== 'string' || value.length === 0 || value.trim() !== value || value.normalize('NFC') !== value) {
+    fail('AI_AGENT_IDENTITY_INVALID', location, 'Expected one non-empty NFC identity without surrounding whitespace.');
+  }
+  return value;
+}
+
+function resourceRef(value: unknown, location: string): `resource://${string}` {
+  const result = identity(value, location);
+  if (!result.startsWith('resource://') || result.length === 11) fail('AI_AGENT_DEFINITION_REF_INVALID', location, 'Expected an exact resource:// identity.');
+  return result as `resource://${string}`;
+}
+
+function optionalClosedObject(value: unknown, location: string): FlowClosedObject {
+  return normalizeFlowClosedObject(value, location);
+}
+
+const FORBIDDEN_RUNTIME_STATE_KEYS = new Set([
+  'actor', 'actorstate', 'compaction', 'conversation', 'history', 'providertranscript', 'transcript',
+]);
+
+function safeOpaqueObject(value: unknown, location: string): FlowClosedObject {
+  const normalized = optionalClosedObject(value, location);
+  const visit = (item: FlowClosedValue, itemLocation: string): void => {
+    if (Array.isArray(item)) {
+      item.forEach((nested, index) => visit(nested, `${itemLocation}[${index}]`));
+      return;
+    }
+    if (item === null || typeof item !== 'object') return;
+    for (const [key, nested] of Object.entries(item)) {
+      const semanticKey = key.normalize('NFC').toLowerCase().replace(/[^a-z0-9]/g, '');
+      if (FORBIDDEN_RUNTIME_STATE_KEYS.has(semanticKey)) {
+        fail('AI_AGENT_RUNTIME_STATE_FIELD_FORBIDDEN', `${itemLocation}.${key}`, 'Runtime-owned Agent state cannot enter the Flow checkpoint.');
+      }
+      visit(nested, `${itemLocation}.${key}`);
+    }
+  };
+  visit(normalized, location);
+  return normalized;
+}
+
+function optionalStringArray(value: unknown, location: string): readonly string[] {
+  if (!Array.isArray(value)) fail('AI_AGENT_ARRAY_REQUIRED', location, 'Expected an array.');
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.prototype.hasOwnProperty.call(descriptors, String(index))) fail('AI_AGENT_ARRAY_SPARSE', `${location}[${index}]`, 'Sparse arrays are not supported.');
+  }
+  return Object.freeze(value.map((item, index) => identity(item, `${location}[${index}]`)));
+}
+
+export function normalizeAIAgentSelector(value: unknown, location = 'selector'): AIAgentSelector {
+  const input = record(value, [], ['byInstanceId', 'byInstanceName'], location);
+  const hasId = Object.prototype.hasOwnProperty.call(input, 'byInstanceId');
+  const hasName = Object.prototype.hasOwnProperty.call(input, 'byInstanceName');
+  if (hasId === hasName) fail('AI_AGENT_SELECTOR_EXACTLY_ONE', location, 'Selector must contain exactly one supported key.');
+  return Object.freeze(hasId
+    ? { byInstanceId: identity(input.byInstanceId, `${location}.byInstanceId`) }
+    : { byInstanceName: identity(input.byInstanceName, `${location}.byInstanceName`) });
+}
+
+export function normalizeAIAgentEffectConfig(value: unknown, location = 'config'): AIAgentEffectConfig {
+  const input = record(value, ['agentDefinitionRef'], ['instanceName', 'materialRefs', 'effectPolicy'], location);
+  return Object.freeze({
+    agentDefinitionRef: resourceRef(input.agentDefinitionRef, `${location}.agentDefinitionRef`),
+    ...(Object.prototype.hasOwnProperty.call(input, 'instanceName') ? { instanceName: identity(input.instanceName, `${location}.instanceName`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'materialRefs') ? { materialRefs: optionalStringArray(input.materialRefs, `${location}.materialRefs`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'effectPolicy') ? { effectPolicy: safeOpaqueObject(input.effectPolicy, `${location}.effectPolicy`) } : {}),
+  });
+}
+
+export interface AIAgentNodeBindingIdentity {
+  readonly workflowKind: AIWorkflowKind;
+  readonly workflowRef: `resource://${string}`;
+  readonly nodeId: string;
+}
+
+/** Exact frozen task proof used by Ctrl/Data loaders before constructing a node runtime. */
+export function assertAIAgentNodeTaskBinding(
+  task: AIWorkflowAgentTaskRef,
+  identityInput: AIAgentNodeBindingIdentity,
+  configInput: AIAgentEffectConfig,
+): AIAgentEffectConfig {
+  const taskValue = record(task, ['workflowKind', 'workflowRef', 'nodeId', 'agentDefinitionRef'], [], 'task');
+  const identityValue = record(identityInput, ['workflowKind', 'workflowRef', 'nodeId'], [], 'identity');
+  if (identityValue.workflowKind !== 'AICtrlWorkflow' && identityValue.workflowKind !== 'AIDataWorkflow') fail('AI_AGENT_TASK_WORKFLOW_KIND_INVALID', 'identity.workflowKind', 'Unsupported AI workflow kind.');
+  const identity = {
+    workflowKind: identityValue.workflowKind,
+    workflowRef: resourceRef(identityValue.workflowRef, 'identity.workflowRef'),
+    nodeId: identityValue.nodeId,
+  } as const;
+  const config = normalizeAIAgentEffectConfig(configInput);
+  if (taskValue.workflowKind !== identity.workflowKind) fail('AI_AGENT_TASK_WORKFLOW_KIND_MISMATCH', 'task.workflowKind', 'Frozen task workflow kind differs from the node.');
+  if (resourceRef(taskValue.workflowRef, 'task.workflowRef') !== identity.workflowRef) fail('AI_AGENT_TASK_WORKFLOW_REF_MISMATCH', 'task.workflowRef', 'Frozen task workflow identity differs from the node.');
+  if (identityValue.nodeId !== taskValue.nodeId) fail('AI_AGENT_TASK_NODE_ID_MISMATCH', 'task.nodeId', 'Frozen task node identity differs from the node.');
+  if (resourceRef(taskValue.agentDefinitionRef, 'task.agentDefinitionRef') !== config.agentDefinitionRef) fail('AI_AGENT_TASK_DEFINITION_MISMATCH', 'config.agentDefinitionRef', 'Frozen task Agent definition differs from config.');
+  return config;
+}
+
+export function normalizeAIAgentInvocation<Input extends FlowClosedValue = FlowClosedValue>(value: unknown, location = 'invocation'): AIAgentInvocation<Input> {
+  const input = record(value, ['kind', 'payload'], ['metadata'], location);
+  if (input.kind !== 'ai.agent') fail('AI_AGENT_INVOCATION_KIND_INVALID', `${location}.kind`, 'Invocation kind must be ai.agent.');
+  return Object.freeze({
+    kind: 'ai.agent',
+    payload: normalizeFlowClosedValue(input.payload, `${location}.payload`) as Input,
+    ...(Object.prototype.hasOwnProperty.call(input, 'metadata') ? { metadata: safeOpaqueObject(input.metadata, `${location}.metadata`) } : {}),
+  });
+}
+
+function normalizeInstance(value: unknown, id: string, location: string): AIAgentInstanceReference {
+  const input = record(value, ['authority', 'instanceId', 'agentDefinitionRef'], ['instanceName', 'sessionId', 'metadata'], location);
+  const instanceId = identity(input.instanceId, `${location}.instanceId`);
+  if (instanceId !== id) fail('AI_AGENT_INSTANCE_ID_INDEX_MISMATCH', `${location}.instanceId`, 'Instance id must equal its index key.');
+  return Object.freeze({
+    authority: identity(input.authority, `${location}.authority`),
+    instanceId,
+    agentDefinitionRef: resourceRef(input.agentDefinitionRef, `${location}.agentDefinitionRef`),
+    ...(Object.prototype.hasOwnProperty.call(input, 'instanceName') ? { instanceName: identity(input.instanceName, `${location}.instanceName`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'sessionId') ? { sessionId: identity(input.sessionId, `${location}.sessionId`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'metadata') ? { metadata: safeOpaqueObject(input.metadata, `${location}.metadata`) } : {}),
+  });
+}
+
+function normalizeReceipt(value: unknown, key: string, instances: Readonly<Record<string, AIAgentInstanceReference>>, location: string): AIAgentInvocationReceipt {
+  const input = record(value, ['invocationKey', 'nodeId', 'status', 'mode', 'agentDefinitionRef', 'input', 'semanticFacts'], ['instanceName', 'instanceId', 'generation', 'metadata', 'output', 'hostReceipt'], location);
+  const invocationKey = identity(input.invocationKey, `${location}.invocationKey`);
+  if (invocationKey !== key) fail('AI_AGENT_INVOCATION_KEY_INDEX_MISMATCH', `${location}.invocationKey`, 'Invocation key must equal its index key.');
+  if (input.status !== 'pending' && input.status !== 'completed') fail('AI_AGENT_INVOCATION_STATUS_INVALID', `${location}.status`, 'Status must be pending or completed.');
+  if (input.mode !== 'new' && input.mode !== 'targeted') fail('AI_AGENT_INVOCATION_MODE_INVALID', `${location}.mode`, 'Mode must be new or targeted.');
+  const instanceId = Object.prototype.hasOwnProperty.call(input, 'instanceId') ? identity(input.instanceId, `${location}.instanceId`) : undefined;
+  if (input.mode === 'targeted' && instanceId === undefined) fail('AI_AGENT_TARGETED_INSTANCE_REQUIRED', location, 'Targeted invocation requires an instance id.');
+  if (input.status === 'completed' && (instanceId === undefined || instances[instanceId] === undefined || !Object.prototype.hasOwnProperty.call(input, 'output'))) {
+    fail('AI_AGENT_COMPLETED_INVOCATION_INCOMPLETE', location, 'Completed invocation requires an indexed instance and output.');
+  }
+  const agentDefinitionRef = resourceRef(input.agentDefinitionRef, `${location}.agentDefinitionRef`);
+  if (instanceId !== undefined && instances[instanceId] !== undefined
+    && instances[instanceId].agentDefinitionRef !== agentDefinitionRef) {
+    fail('AI_AGENT_RECEIPT_DEFINITION_MISMATCH', `${location}.agentDefinitionRef`, 'Invocation receipt definition must equal its indexed instance definition.');
+  }
+  if (instanceId !== undefined && instances[instanceId] !== undefined) {
+    const receiptName = Object.prototype.hasOwnProperty.call(input, 'instanceName')
+      ? identity(input.instanceName, `${location}.instanceName`)
+      : undefined;
+    if (receiptName !== instances[instanceId].instanceName) {
+      fail('AI_AGENT_RECEIPT_INSTANCE_NAME_MISMATCH', `${location}.instanceName`, 'Invocation receipt name must equal its indexed instance name.');
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'generation') && (typeof input.generation !== 'number' || !Number.isSafeInteger(input.generation) || input.generation < 0)) {
+    fail('AI_AGENT_GENERATION_INVALID', `${location}.generation`, 'Generation must be a non-negative safe integer.');
+  }
+  return Object.freeze({
+    invocationKey,
+    nodeId: identity(input.nodeId, `${location}.nodeId`),
+    status: input.status,
+    mode: input.mode,
+    agentDefinitionRef,
+    input: normalizeFlowClosedValue(input.input, `${location}.input`),
+    semanticFacts: safeOpaqueObject(input.semanticFacts, `${location}.semanticFacts`),
+    ...(Object.prototype.hasOwnProperty.call(input, 'instanceName') ? { instanceName: identity(input.instanceName, `${location}.instanceName`) } : {}),
+    ...(instanceId === undefined ? {} : { instanceId }),
+    ...(Object.prototype.hasOwnProperty.call(input, 'generation') ? { generation: input.generation as number } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'metadata') ? { metadata: safeOpaqueObject(input.metadata, `${location}.metadata`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'output') ? { output: normalizeFlowClosedValue(input.output, `${location}.output`) } : {}),
+    ...(Object.prototype.hasOwnProperty.call(input, 'hostReceipt') ? { hostReceipt: safeOpaqueObject(input.hostReceipt, `${location}.hostReceipt`) } : {}),
+  });
+}
+
+export function normalizeCanonicalAIAgentState(value: unknown, location = 'ai'): AIWorkflowProfileDurableState {
+  const input = record(value, ['schemaVersion', 'instancesById', 'instanceIdByName', 'invocationsByKey'], [], location);
+  if (input.schemaVersion !== 'depa.ai-agent-state/v1') fail('AI_AGENT_STATE_SCHEMA_UNSUPPORTED', `${location}.schemaVersion`, 'Unsupported Agent state schema.');
+  const instanceValues = objectMap(input.instancesById, `${location}.instancesById`);
+  const instancesById: Record<string, AIAgentInstanceReference> = {};
+  for (const id of Object.keys(instanceValues).sort(compareCodeUnits)) instancesById[identity(id, `${location}.instancesById`)] = normalizeInstance(instanceValues[id], id, `${location}.instancesById.${id}`);
+  const nameValues = objectMap(input.instanceIdByName, `${location}.instanceIdByName`);
+  const instanceIdByName: Record<string, string> = {};
+  const seenIds = new Set<string>();
+  for (const rawName of Object.keys(nameValues).sort(compareCodeUnits)) {
+    const name = identity(rawName, `${location}.instanceIdByName`);
+    const id = identity(nameValues[name], `${location}.instanceIdByName.${name}`);
+    if (!instancesById[id] || instancesById[id].instanceName !== name) fail('AI_AGENT_INSTANCE_NAME_INDEX_MISMATCH', `${location}.instanceIdByName.${name}`, 'Name index must be reciprocal.');
+    if (seenIds.has(id)) fail('AI_AGENT_INSTANCE_NAME_DUPLICATE', `${location}.instanceIdByName.${name}`, 'One instance cannot have multiple names.');
+    seenIds.add(id);
+    instanceIdByName[name] = id;
+  }
+  for (const instance of Object.values(instancesById)) if (instance.instanceName !== undefined && instanceIdByName[instance.instanceName] !== instance.instanceId) fail('AI_AGENT_INSTANCE_NAME_INDEX_MISSING', `${location}.instancesById.${instance.instanceId}.instanceName`, 'Named instance requires reciprocal index.');
+  const receiptValues = objectMap(input.invocationsByKey, `${location}.invocationsByKey`);
+  const invocationsByKey: Record<string, AIAgentInvocationReceipt> = {};
+  const reservations = new Set<string>();
+  for (const key of Object.keys(receiptValues).sort(compareCodeUnits)) {
+    const receipt = normalizeReceipt(receiptValues[key], identity(key, `${location}.invocationsByKey`), instancesById, `${location}.invocationsByKey.${key}`);
+    if (receipt.status === 'pending' && receipt.mode === 'new' && receipt.instanceName !== undefined) {
+      if (reservations.has(receipt.instanceName) || instanceIdByName[receipt.instanceName] !== undefined) fail('AI_AGENT_INSTANCE_NAME_RESERVED', `${location}.invocationsByKey.${key}.instanceName`, 'Name has another accepted binding or reservation.');
+      reservations.add(receipt.instanceName);
+    }
+    invocationsByKey[key] = receipt;
+  }
+  return Object.freeze({ schemaVersion: 'depa.ai-agent-state/v1', instancesById: Object.freeze(instancesById), instanceIdByName: Object.freeze(instanceIdByName), invocationsByKey: Object.freeze(invocationsByKey) });
+}
+
+export function upgradeLegacyAIWorkflowProfileDurableState(value: LegacyAIWorkflowProfileDurableState, agentDefinitionRefs: Readonly<Record<string, `resource://${string}`>>, location = 'legacyAI'): AIWorkflowProfileDurableState {
+  const input = record(value, ['externalRuntimeRefs', 'receipts'], [], location);
+  const refs = objectMap(input.externalRuntimeRefs, `${location}.externalRuntimeRefs`);
+  const instancesById: Record<string, AIAgentInstanceReference> = {};
+  const instanceIdByName: Record<string, string> = {};
+  for (const name of Object.keys(refs).sort(compareCodeUnits)) {
+    const refLocation = `${location}.externalRuntimeRefs.${name}`;
+    const ref = record(refs[name], ['authority', 'instanceId'], ['sessionId', 'metadata'], refLocation);
+    const instanceId = identity(ref.instanceId, `${refLocation}.instanceId`);
+    if (instancesById[instanceId]) fail('AI_AGENT_LEGACY_INSTANCE_DUPLICATE', refLocation, 'Legacy instance id is not unique.');
+    const agentDefinitionRef = agentDefinitionRefs[name];
+    if (!agentDefinitionRef) fail('AI_AGENT_LEGACY_DEFINITION_REQUIRED', refLocation, 'Explicit Agent definition is required for legacy upgrade.');
+    instanceIdByName[name] = instanceId;
+    instancesById[instanceId] = { authority: identity(ref.authority, `${refLocation}.authority`), instanceId, instanceName: identity(name, refLocation), agentDefinitionRef: resourceRef(agentDefinitionRef, `${refLocation}.agentDefinitionRef`), ...(Object.prototype.hasOwnProperty.call(ref, 'sessionId') ? { sessionId: identity(ref.sessionId, `${refLocation}.sessionId`) } : {}), ...(Object.prototype.hasOwnProperty.call(ref, 'metadata') ? { metadata: optionalClosedObject(ref.metadata, `${refLocation}.metadata`) } : {}) };
+  }
+  if (!Array.isArray(input.receipts)) fail('AI_AGENT_ARRAY_REQUIRED', `${location}.receipts`, 'Expected receipts array.');
+  const invocationsByKey: Record<string, AIAgentInvocationReceipt> = {};
+  input.receipts.forEach((item, index) => {
+    const receiptLocation = `${location}.receipts[${index}]`;
+    const receipt = record(item, ['nodeId', 'externalRuntimeRef'], ['metadata'], receiptLocation);
+    const nodeId = identity(receipt.nodeId, `${receiptLocation}.nodeId`);
+    const name = identity(receipt.externalRuntimeRef, `${receiptLocation}.externalRuntimeRef`);
+    const instanceId = instanceIdByName[name];
+    if (!instanceId) fail('AI_WORKFLOW_EXTERNAL_RUNTIME_REF_UNKNOWN', `${receiptLocation}.externalRuntimeRef`, 'Legacy receipt reference is unknown.');
+    const key = `${nodeId}#legacy-${index + 1}`;
+    invocationsByKey[key] = { invocationKey: key, nodeId, status: 'completed', mode: 'targeted', agentDefinitionRef: instancesById[instanceId]!.agentDefinitionRef, instanceId, instanceName: name, input: null, semanticFacts: {}, output: null, ...(Object.prototype.hasOwnProperty.call(receipt, 'metadata') ? { metadata: safeOpaqueObject(receipt.metadata, `${receiptLocation}.metadata`) } : {}) };
+  });
+  return normalizeCanonicalAIAgentState({ schemaVersion: 'depa.ai-agent-state/v1', instancesById, instanceIdByName, invocationsByKey }, location);
+}