ai-ctrl-workflow-logic 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-ctrl-workflow-logic",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "description": "WorkCtrlFlow-backed AI Ctrl Workflow adapter logic",
   "type": "module",
@@ -8,24 +8,27 @@
   "exports": {
     ".": "./src/index.ts",
     "./browser": "./src/browser.ts",
-    "./filesystem": "./src/filesystem.ts"
+    "./filesystem": "./src/filesystem.ts",
+    "./sources": "./src/source-loader.ts"
   },
   "dependencies": {
-    "ai-ctrl-workflow-contract": "0.2.0",
-    "ai-workflow-contract": "0.2.0",
-    "ai-workflow-logic": "0.2.0",
-    "flow-step-space-logic": "0.1.1",
-    "instant-ctrl-flow-contract": "0.1.2",
-    "instant-ctrl-flow-logic": "0.1.6",
-    "task-manager-contract": "0.1.3",
-    "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-contract": "0.1.3",
-    "work-ctrl-flow-logic": "0.1.5"
+    "depa-behavior-tree": "0.1.2",
+    "ai-ctrl-workflow-contract": "0.2.2",
+    "ai-workflow-contract": "0.2.3",
+    "ai-workflow-logic": "0.2.3",
+    "flow-step-space-logic": "0.1.2",
+    "instant-ctrl-flow-contract": "0.1.3",
+    "instant-ctrl-flow-logic": "0.1.7",
+    "task-manager-contract": "0.1.4",
+    "task-manager-logic": "0.1.7",
+    "work-ctrl-flow-contract": "0.1.4",
+    "work-ctrl-flow-logic": "0.1.6"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
   }
 }

package/src/delegation.ts

@@ -0,0 +1,55 @@
+import { BehaviorResult, type ActionHandler, type CtrlFlowNodeType, type INodeConfig } from 'depa-behavior-tree';
+import { createFlowHandlers, flowStateOf } from 'instant-ctrl-flow-logic';
+import { WaitNodeHandler, type TickController, type WorkCtrlFlowEngineOptions } from 'work-ctrl-flow-logic';
+import type { FlowBundleSpec, FlowCodeResolver } from 'instant-ctrl-flow-contract';
+import { WorkflowDelegationSuspendedError } from 'ai-workflow-logic';
+
+/** Uses the existing scheduler, native WaitHandles and resume token history. */
+export function createAICtrlWorkflowDelegationHandlers(
+  spec: FlowBundleSpec,
+  resolveCode: FlowCodeResolver,
+  bindNodeRuntime: WorkCtrlFlowEngineOptions['bindNodeRuntime'],
+  controller: () => TickController,
+): Record<string, ActionHandler<CtrlFlowNodeType, INodeConfig>> {
+  const handlers = createFlowHandlers(spec, resolveCode, {
+    begin: () => { throw Error('Delegation Run handler does not own branch decisions'); },
+    record: () => { throw Error('Delegation Run handler does not own branch decisions'); },
+    runtimeForNode: (nodeId, runtime, state) => bindNodeRuntime?.(runtime, controller().runtimeIdentity(nodeId, state)) ?? runtime,
+  });
+  return { 'flow.Run': { async execute(ctx) {
+    const c = controller();
+    if (c.suspended.length) { c.inertKeys.add(ctx.node.Key); return BehaviorResult.Failure; }
+    const key = c.invocationKeyFor(ctx.node.Key);
+    const recorded = c.snapshot.nodeResults[key];
+    if (recorded) {
+      if (bindNodeRuntime) c.invocationKeyFor(ctx.node.Key);
+      return recorded === 'Success' ? BehaviorResult.Success : BehaviorResult.Failure;
+    }
+    const result = await handlers['flow.Run']!.execute(ctx);
+    const flow = flowStateOf(ctx);
+    if (!(flow.fault instanceof WorkflowDelegationSuspendedError)) {
+      if (result !== BehaviorResult.Running) c.snapshot.nodeResults[key] = result === BehaviorResult.Success ? 'Success' : 'Failure';
+      for (const handle of [...c.snapshot.openWaitHandles]) {
+        if (!handle.nodeKey.startsWith(`${ctx.node.Key}:delegation:`) || handle.signalKey !== key) continue;
+        handle.status = 'Consumed'; handle.closedAtMs = c.now();
+        c.snapshot.appliedResumeSignals.push(`${handle.waitHandleId}:${handle.resumeToken}`);
+        c.snapshot.waitResults[handle.invocationKey] = { result: result === BehaviorResult.Success ? 'Success' : 'Failure' };
+        c.snapshot.openWaitHandles = c.snapshot.openWaitHandles.filter(item => item !== handle);
+        c.snapshot.closedWaitHandles.push(handle);
+      }
+      return result;
+    }
+    const delegationInvocationKey = flow.fault.invocationKey;
+    const status = flow.fault.status;
+    delete flow.fault;
+    // Signal payload is only a wakeup; task output always comes from owner observation.
+    const prefix = `${ctx.node.Key}:delegation:`;
+    const scope=key.slice(0,key.lastIndexOf('/')+1);
+    const count = c.snapshot.closedWaitHandles.filter(handle => handle.nodeKey.startsWith(prefix) && handle.invocationKey.startsWith(`${scope}${prefix}`)).length;
+    const proxy = Object.create(ctx);
+    Object.defineProperty(proxy, 'node', { value: { ...ctx.node, Key: `${prefix}${count}`, Config: { signalKind: 'workflow.delegation.observe', signalKey: key } } });
+    return new WaitNodeHandler('external-job', controller, async (_ctx, handle) => {
+      handle.metadata = { workflowDelegation: { kind: 'workflow.task-delegation/v1', invocationKey: delegationInvocationKey, actionInvocationKey: key, status } };
+    }).execute(proxy);
+  } } };
+}

package/src/filesystem.ts

@@ -21,6 +21,8 @@ import {
 } from 'ai-workflow-logic';
 import { createFilesystemFlowCodeResolver, type FlowModuleImporter } from 'instant-ctrl-flow-logic/filesystem';
 import type { FlowNodeSpec } from 'instant-ctrl-flow-contract';
+import { projectWorkCtrlFlowInvocationOwners } from 'work-ctrl-flow-logic';
+import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 import {
   assembleDefinitionStepProfileDirectory,
   createFilesystemDefinitionStepProfileRuntime,
@@ -135,24 +137,29 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
     agentTaskProofs: _agentTaskProofs,
     ...controllerOptions
   } = options;
+  const bindAgentNode=options.agentEffects?createAICtrlWorkflowAgentNodeRuntimeBinder({
+    flowInstanceId:options.instanceId,
+    checkpointRuntime:{checkpointStore},
+    effects:options.agentEffects,
+    workflowRef:`resource://${binding.definition.fqn}`,
+    taskProofs:options.agentTaskProofs??{},
+  }):undefined;
   const controller = createAICtrlWorkflowController({
     ...controllerOptions,
     binding,
     store,
     resolveCode: createFilesystemFlowCodeResolver(options.importModule),
-    ...(options.agentEffects ? {
-      bindNodeRuntime: createAICtrlWorkflowAgentNodeRuntimeBinder({
-        flowInstanceId: options.instanceId,
-        checkpointRuntime: { checkpointStore },
-        effects: options.agentEffects,
-        workflowRef: `resource://${binding.definition.fqn}`,
-        taskProofs: options.agentTaskProofs ?? {},
-      }),
+    suspendDelegations: options.agentEffects?.delegation !== undefined,
+    ...(bindAgentNode ? {
+      // Pure branch/loop predicates have no Agent task. Keep the Agent binder
+      // exact for the nodes whose frozen proof actually grants that facade.
+      bindNodeRuntime:(runtime,identity)=>options.agentTaskProofs?.[identity.nodeId]?bindAgentNode(runtime,identity):runtime,
     } : {}),
   });
   const materializedController: AICtrlWorkflowController = {
     ...controller,
     async start(treeId, startOptions) {
+      for (const proof of Object.values(options.agentTaskProofs ?? {})) assertFrozenAIAgentTaskBinding(proof);
       const existing = await controller.store.load(treeId);
       if (existing) {
         if (startOptions?.input !== undefined
@@ -165,6 +172,10 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
       }
       return controller.start(treeId, startOptions);
     },
+    async resume(treeId, signal) {
+      for (const proof of Object.values(options.agentTaskProofs ?? {})) assertFrozenAIAgentTaskBinding(proof);
+      return controller.resume(treeId, signal);
+    },
   };
   return Object.assign(materializedController, {
     checkpointStore,
@@ -211,6 +222,7 @@ function profileAuthorityFromBinding(
   return Object.freeze({
     profileKind: 'AICtrlWorkflow' as const,
     definitionStepIds: Object.freeze([...definitionStepIds]),
+    definitionInvocationOwners: projectWorkCtrlFlowInvocationOwners(binding.definition),
     extensionsByStepId: Object.freeze(Object.fromEntries((forest?.stepOrder ?? []).flatMap((stepId) => {
       const extensions = Object.fromEntries(Object.entries(forest!.steps[stepId].extensions).map(([kind, extension]) => [kind, Object.freeze({
         ...(extension.schemaRef === undefined ? {} : { schemaRef: extension.schemaRef }),

package/src/index.ts

@@ -1,3 +1,5 @@
+import { createAICtrlWorkflowDelegationHandlers } from './delegation.js';
+export { createAICtrlWorkflowDelegationHandlers } from './delegation.js';
 import type {
   AICtrlWorkflowController,
   AICtrlWorkflowNodeRecord,
@@ -8,6 +10,7 @@ import type {
   AICtrlWorkflowRunProfileState,
   AICtrlWorkflowRuntime,
   AIAgentHostEffectPort,
+  AIAgentProcessorRuntime,
   FrozenAIAgentTaskBinding,
   AIWorkflowAuthoredEffects,
   AIWorkflowEffectProvider,
@@ -25,10 +28,11 @@ import type {
 import {
   commitFlowRunCheckpoint,
   createAIWorkflowRuntimeContext,
-  defineAICtrlWorkflow,
   loadFlowRunCheckpoint,
   projectWorkCtrlSnapshotToCheckpointData,
   bindAIAgentProcessors,
+  bindWorkflowNodeTasks,
+  bindWorkflowTaskDelegation,
 } from 'ai-workflow-logic';
 import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 import type {
@@ -37,7 +41,6 @@ import type {
   FlowSourceCollection,
   LoadFlowSourcesOptions,
 } from 'instant-ctrl-flow-contract';
-import { loadCtrlFlowProfileFromSources } from 'instant-ctrl-flow-logic';
 import type {
   ResumeSignal,
   TickOutcome,
@@ -184,23 +187,39 @@ export function createAICtrlWorkflowAgentNodeRuntimeBinder(
     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: AIWorkflowAuthoredEffects = bindAIAgentProcessors({
+    const visit = identity.invocationKey.slice(identity.invocationKey.lastIndexOf('#') + 1);
+    const scope = identity.invocationKey.includes('/') ? identity.invocationKey.slice(0, identity.invocationKey.lastIndexOf('/')) : '';
+    const agentRuntime = {
       checkpointRuntime: options.checkpointRuntime,
       checkpointKey: { instanceId: options.flowInstanceId, runId: identity.treeId },
       nodeId: identity.nodeId,
       invocationKey: identity.invocationKey,
+      nodeContext:{generation:identity.generation??Number(visit),scope},
       workflowKind: 'AICtrlWorkflow',
       workflowRef: options.workflowRef,
       taskBinding,
       effects: options.effects,
       ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-    });
-    return Object.freeze({ ...runtime, ai: Object.freeze({ ...workflowRuntime.ai, effects }) });
+    } satisfies AIAgentProcessorRuntime;
+    const effects: AIWorkflowAuthoredEffects = bindAIAgentProcessors(agentRuntime);
+    const delegation=options.effects.delegation ? bindWorkflowTaskDelegation({
+        checkpointRuntime: options.checkpointRuntime,
+        checkpointKey: { instanceId: options.flowInstanceId, runId: identity.treeId },
+        nodeId: identity.nodeId, invocationKey: identity.invocationKey,
+        workflowKind: 'AICtrlWorkflow', workflowRef: options.workflowRef, taskBinding,
+        visit: identity.visit ?? `${scope}#${visit}`, generation: identity.generation ?? Number(visit), effects: options.effects.delegation,
+      }) : undefined;
+    return Object.freeze({ ...runtime, ai: Object.freeze({ ...workflowRuntime.ai, effects,
+      tasks:bindWorkflowNodeTasks(agentRuntime,delegation),
+      ...(delegation?{delegation}:{}),
+    }) });
   };
 }
 
 export interface CreateAICtrlWorkflowControllerOptions
   extends Omit<WorkCtrlFlowEngineOptions, 'definition' | 'runtime' | 'expectedForm'> {
+  /** Set by composition when a native delegation owner is bound. */
+  readonly suspendDelegations?: boolean;
   readonly binding: AICtrlWorkflowDefinitionBinding;
   readonly resolveCode: FlowCodeResolver<AICtrlWorkflowRuntime>;
   readonly resolveFlow?: WorkCtrlFlowDefinition['resolveFlow'];
@@ -218,6 +237,10 @@ export function createAICtrlWorkflowController(
   };
   const engine = new WorkCtrlFlowEngine({
     ...options,
+    ...(options.suspendDelegations ? { extraHandlers: controller => ({
+      ...createAICtrlWorkflowDelegationHandlers(options.binding.definition, options.resolveCode as FlowCodeResolver, options.bindNodeRuntime, controller),
+      ...options.extraHandlers?.(controller),
+    }) } : {}),
     expectedForm: 'WorkCtrlFlow',
     definition,
     runtime: createAICtrlWorkflowRuntime({ runtime: options.runtime, ai: options.ai }),
@@ -231,34 +254,7 @@ export function createAICtrlWorkflowController(
   };
 }
 
-export function defineWorkCtrlFlowBackedAICtrlWorkflow(
-  definition: AICtrlWorkflowDefinitionBinding['definition'],
-): AICtrlWorkflowDefinitionBinding {
-  return defineAICtrlWorkflow(definition);
-}
-
-export interface AICtrlWorkflowSourceLoadResult {
-  readonly binding?: AICtrlWorkflowDefinitionBinding;
-  readonly diagnostics: readonly FlowDiagnostic[];
-}
-
-export function loadAICtrlWorkflowSources(
-  sources: FlowSourceCollection,
-  options: LoadFlowSourcesOptions = {},
-): AICtrlWorkflowSourceLoadResult {
-  const loaded = loadCtrlFlowProfileFromSources(sources, {
-    ...options,
-    profileRoot: 'AICtrlWorkflow',
-    substrateForm: 'WorkCtrlFlow',
-  });
-  if (!loaded.spec || loaded.diagnostics.length > 0) {
-    return { diagnostics: loaded.diagnostics };
-  }
-  return {
-    binding: defineWorkCtrlFlowBackedAICtrlWorkflow(loaded.spec),
-    diagnostics: loaded.diagnostics,
-  };
-}
+export * from './source-loader.js';
 
 function nodeIdFromInvocationKey(invocationKey: string): string {
   const withoutVisit = invocationKey.slice(0, invocationKey.lastIndexOf('#'));
@@ -331,4 +327,3 @@ export async function getAICtrlWorkflowRunRecord(
   return snapshot ? projectAICtrlWorkflowRunRecord(snapshot, await controller.getOutcome(treeId)) : undefined;
 }
 
-export * from './holon-task.js';

package/src/source-loader.ts

@@ -0,0 +1,37 @@
+import type { AICtrlWorkflowDefinitionBinding } from "ai-workflow-contract";
+import { defineAICtrlWorkflow } from "ai-workflow-logic/definitions";
+import type {
+  FlowDiagnostic,
+  FlowSourceCollection,
+  LoadFlowSourcesOptions,
+} from "instant-ctrl-flow-contract";
+import { loadCtrlFlowProfileFromSources } from "instant-ctrl-flow-logic/browser";
+
+export function defineWorkCtrlFlowBackedAICtrlWorkflow(
+  definition: AICtrlWorkflowDefinitionBinding["definition"],
+): AICtrlWorkflowDefinitionBinding {
+  return defineAICtrlWorkflow(definition);
+}
+
+export interface AICtrlWorkflowSourceLoadResult {
+  readonly binding?: AICtrlWorkflowDefinitionBinding;
+  readonly diagnostics: readonly FlowDiagnostic[];
+}
+
+export function loadAICtrlWorkflowSources(
+  sources: FlowSourceCollection,
+  options: LoadFlowSourcesOptions = {},
+): AICtrlWorkflowSourceLoadResult {
+  const loaded = loadCtrlFlowProfileFromSources(sources, {
+    ...options,
+    profileRoot: "AICtrlWorkflow",
+    substrateForm: "WorkCtrlFlow",
+  });
+  if (!loaded.spec || loaded.diagnostics.length > 0) {
+    return { diagnostics: loaded.diagnostics };
+  }
+  return {
+    binding: defineWorkCtrlFlowBackedAICtrlWorkflow(loaded.spec),
+    diagnostics: loaded.diagnostics,
+  };
+}

package/src/holon-task.ts

@@ -1,264 +0,0 @@
-import {
-  createAIOrganizationTaskProfile,
-  normalizeHolonTaskSnapshotReceipt,
-  normalizeHolonTaskTarget,
-  type FrozenHolonTaskTarget,
-  type HolonTaskSnapshotAdoptionReceipt,
-  type HolonTaskSnapshotReceipt,
-} from 'ai-workflow-contract';
-import { assertFrozenHolonTaskTarget } from 'ai-workflow-logic/run-freeze';
-import {
-  createHolonTaskSpace,
-  prepareHolonTaskSnapshot,
-  type CreateHolonTaskSpaceConfig,
-  type CreateHolonTaskSpaceRuntime,
-  type HolonOrganizationSnapshotReadPort,
-} from 'ai-workflow-logic';
-import type {
-  TaskClaimToken,
-  TaskCommandReceipt,
-  TaskRecord,
-  TaskSettlementReceipt,
-  TaskSpaceSnapshot,
-} from 'task-manager-contract';
-import {
-  cancelTask,
-  replanTask,
-  type TaskManagerRuntime,
-  type TaskProcessorResult,
-} from 'task-manager-logic';
-
-export interface AICtrlHolonTaskRuntime {
-  readonly taskManager: TaskManagerRuntime;
-  readonly organizationSnapshots: HolonOrganizationSnapshotReadPort;
-}
-
-export interface OpenAICtrlHolonTaskInput {
-  readonly frozenTarget: FrozenHolonTaskTarget;
-  readonly commandId: string;
-  readonly taskSpaceId: string;
-  readonly taskId: string;
-  readonly taskName: string;
-  readonly createdAt: string;
-}
-
-export interface OpenAICtrlHolonTaskResult {
-  readonly snapshot: TaskSpaceSnapshot;
-  readonly receipt: TaskCommandReceipt;
-  readonly snapshotReceipt: HolonTaskSnapshotReceipt;
-  readonly created: boolean;
-  readonly replayed: boolean;
-}
-
-export async function openAICtrlHolonTask(
-  runtime: AICtrlHolonTaskRuntime,
-  input: OpenAICtrlHolonTaskInput,
-  config: CreateHolonTaskSpaceConfig,
-): Promise<OpenAICtrlHolonTaskResult> {
-  const proof = assertFrozenHolonTaskTarget(input.frozenTarget);
-  const existing = await runtime.taskManager.owner.readSnapshot(input.taskSpaceId);
-  if (existing) {
-    const task = exactOrganizationTask(existing, input.taskId);
-    const target = normalizeHolonTaskTarget(task.profile.facts.target);
-    if (JSON.stringify(target) !== JSON.stringify(proof.target)) {
-      throw new Error('AI_CTRL_HOLON_TASK_TARGET_CONFLICT: existing TaskSpace is bound to another frozen target');
-    }
-    const receipt = await runtime.taskManager.owner.readReceiptByCommand(input.taskSpaceId, input.commandId);
-    if (!receipt) throw new Error('AI_CTRL_HOLON_TASK_OPEN_RECEIPT_MISSING: existing TaskSpace has no matching create receipt');
-    return Object.freeze({
-      snapshot: existing,
-      receipt,
-      snapshotReceipt: normalizeHolonTaskSnapshotReceipt(task.profile.facts.snapshotReceipt),
-      created: false,
-      replayed: true,
-    });
-  }
-  const created = await createHolonTaskSpace(runtime as CreateHolonTaskSpaceRuntime, {
-    commandId: input.commandId,
-    taskSpaceId: input.taskSpaceId,
-    taskId: input.taskId,
-    taskName: input.taskName,
-    target: proof.target,
-    createdAt: input.createdAt,
-  }, config);
-  return Object.freeze({ ...created, created: true });
-}
-
-export type ObserveAICtrlHolonTaskResult =
-  | Readonly<{
-      readonly kind: 'waiting';
-      readonly taskSpaceId: string;
-      readonly taskId: string;
-      readonly expectedSettlementCommandId: string;
-      readonly observedRevision: number;
-    }>
-  | Readonly<{
-      readonly kind: 'settled';
-      readonly receipt: TaskSettlementReceipt;
-      readonly task: TaskRecord;
-    }>;
-
-export async function observeAICtrlHolonTask(
-  runtime: Pick<AICtrlHolonTaskRuntime, 'taskManager'>,
-  input: Readonly<{
-    readonly taskSpaceId: string;
-    readonly taskId: string;
-    readonly settlementCommandId: string;
-  }>,
-  _config: Readonly<Record<string, never>>,
-): Promise<ObserveAICtrlHolonTaskResult> {
-  const snapshot = await runtime.taskManager.owner.readSnapshot(input.taskSpaceId);
-  if (!snapshot) throw new Error(`AI_CTRL_HOLON_TASK_SPACE_MISSING: ${input.taskSpaceId}`);
-  const task = exactOrganizationTask(snapshot, input.taskId);
-  const receipt = await runtime.taskManager.owner.readReceiptByCommand(input.taskSpaceId, input.settlementCommandId);
-  if (!receipt) return Object.freeze({
-    kind: 'waiting',
-    taskSpaceId: input.taskSpaceId,
-    taskId: input.taskId,
-    expectedSettlementCommandId: input.settlementCommandId,
-    observedRevision: snapshot.revision,
-  });
-  if (receipt.kind !== 'task-settlement-receipt' || receipt.taskId !== input.taskId
-    || !['Succeeded', 'Failed', 'Cancelled'].includes(task.status)
-    || receipt.status !== task.status) {
-    throw new Error('AI_CTRL_HOLON_TASK_SETTLEMENT_RECEIPT_MISMATCH: receipt does not bind the terminal task projection');
-  }
-  return Object.freeze({ kind: 'settled', receipt, task });
-}
-
-export interface ReplanAICtrlHolonTaskInput {
-  readonly frozenSuccessorTarget: FrozenHolonTaskTarget;
-  readonly taskSpaceId: string;
-  readonly previousTaskId: string;
-  readonly successorTaskId: string;
-  readonly successorTaskName: string;
-  readonly cancelCommandId: string;
-  readonly replanCommandId: string;
-  readonly planId: string;
-  readonly replannedAt: string;
-  readonly activeClaim?: TaskClaimToken;
-}
-
-export interface ReplanAICtrlHolonTaskResult extends TaskProcessorResult {
-  readonly adoptionReceipt: HolonTaskSnapshotAdoptionReceipt;
-  readonly successorSnapshotReceipt: HolonTaskSnapshotReceipt;
-}
-
-export async function replanAICtrlHolonTask(
-  runtime: AICtrlHolonTaskRuntime,
-  input: ReplanAICtrlHolonTaskInput,
-  config: CreateHolonTaskSpaceConfig,
-): Promise<ReplanAICtrlHolonTaskResult> {
-  const successorProof = assertFrozenHolonTaskTarget(input.frozenSuccessorTarget);
-  const initial = await requiredSnapshot(runtime.taskManager, input.taskSpaceId);
-  const previous = exactOrganizationTask(initial, input.previousTaskId);
-  const previousTarget = normalizeHolonTaskTarget(previous.profile.facts.target);
-  const previousSnapshotReceipt = normalizeHolonTaskSnapshotReceipt(previous.profile.facts.snapshotReceipt);
-  if (previousTarget.executionBinding.ref !== successorProof.target.executionBinding.ref
-    || previousTarget.executionBinding.digest !== successorProof.target.executionBinding.digest) {
-    throw new Error('AI_CTRL_HOLON_TASK_REPLAN_SUCCESSOR_INSTANCE_REQUIRED: execution binding changed');
-  }
-  if (previousTarget.invocation.workflowKind !== successorProof.target.invocation.workflowKind
-    || previousTarget.invocation.workflowRef !== successorProof.target.invocation.workflowRef
-    || previousTarget.invocation.nodeId !== successorProof.target.invocation.nodeId) {
-    throw new Error('AI_CTRL_HOLON_TASK_REPLAN_SUCCESSOR_INSTANCE_REQUIRED: workflow executable identity changed');
-  }
-
-  // Read and validate the successor authority before mutating the current task.
-  // The following cancel + replan commands are independently idempotent, so a
-  // retry can converge after an interruption between their commits.
-  const prepared = await prepareHolonTaskSnapshot(runtime, {
-    taskSpaceId: input.taskSpaceId,
-    target: successorProof.target,
-  });
-
-  let current = initial;
-  if (!['Succeeded', 'Failed', 'Cancelled'].includes(previous.status)) {
-    if (previous.activeClaim && (!input.activeClaim || JSON.stringify(previous.activeClaim) !== JSON.stringify(input.activeClaim))) {
-      throw new Error('AI_CTRL_HOLON_TASK_REPLAN_CLAIM_REQUIRED: active task requires its exact claim capability');
-    }
-    const cancelled = await cancelTask(runtime.taskManager, {
-      kind: 'task.cancel',
-      commandId: input.cancelCommandId,
-      taskSpaceId: input.taskSpaceId,
-      expectedRevision: current.revision,
-      taskId: previous.taskId,
-      cancelledAt: input.replannedAt,
-      reason: 'organization-snapshot-replan',
-      ...(input.activeClaim === undefined ? {} : { claim: input.activeClaim }),
-    }, config);
-    current = cancelled.snapshot;
-  }
-
-  const adoptionReceipt: HolonTaskSnapshotAdoptionReceipt = Object.freeze({
-    kind: 'holon-task-snapshot-adoption-receipt',
-    schemaVersion: 'ai-workflow.holon-task-snapshot-adoption-receipt/v1',
-    taskSpaceId: input.taskSpaceId,
-    previousTaskId: input.previousTaskId,
-    successorTaskId: input.successorTaskId,
-    previousIssuerReceiptId: previousSnapshotReceipt.issuerReceiptId,
-    successorIssuerReceiptId: prepared.snapshotReceipt.issuerReceiptId,
-    executionBindingDigest: previousTarget.executionBinding.digest,
-    adoptedAt: input.replannedAt,
-  });
-  const priorAdoptions = Array.isArray(previous.profile.facts.snapshotAdoptions)
-    ? previous.profile.facts.snapshotAdoptions
-    : [];
-  const successorProfile = createAIOrganizationTaskProfile(
-    prepared.target,
-    prepared.snapshotReceipt,
-    [...priorAdoptions, adoptionReceipt],
-  );
-  const successorDefinition = Object.freeze({
-    kind: 'task' as const,
-    taskId: input.successorTaskId,
-    name: input.successorTaskName,
-    order: current.definition.tasks.length,
-    profile: successorProfile,
-    inputArtifacts: prepared.artifactRefs,
-  });
-  const rootCount = current.definition.relations.filter((relation) => relation.kind === 'parent-child' && relation.parentTaskId === null).length;
-  const replanned = await replanTask(runtime.taskManager, {
-    kind: 'task.replan',
-    commandId: input.replanCommandId,
-    taskSpaceId: input.taskSpaceId,
-    expectedRevision: current.revision,
-    replannedAt: input.replannedAt,
-    plan: {
-      kind: 'task-plan',
-      planId: input.planId,
-      tasks: [...current.definition.tasks, successorDefinition],
-      relations: [
-        ...current.definition.relations,
-        {
-          kind: 'parent-child',
-          relationId: `root:${input.successorTaskId}`,
-          parentTaskId: null,
-          childTaskId: input.successorTaskId,
-          order: rootCount,
-        },
-      ],
-      reason: 'organization-snapshot-replan',
-    },
-    artifactBodies: prepared.artifactBodies,
-  }, config);
-  return Object.freeze({
-    ...replanned,
-    adoptionReceipt,
-    successorSnapshotReceipt: prepared.snapshotReceipt,
-  });
-}
-
-function exactOrganizationTask(snapshot: TaskSpaceSnapshot, taskId: string): TaskRecord {
-  const task = snapshot.tasks.find((candidate) => candidate.taskId === taskId);
-  if (!task || task.profile.profileKind !== 'depa.ai.organization-task' || task.profile.schemaVersion !== 1) {
-    throw new Error(`AI_CTRL_HOLON_TASK_PROFILE_MISMATCH: ${taskId}`);
-  }
-  return task;
-}
-
-async function requiredSnapshot(runtime: TaskManagerRuntime, taskSpaceId: string): Promise<TaskSpaceSnapshot> {
-  const snapshot = await runtime.owner.readSnapshot(taskSpaceId);
-  if (!snapshot) throw new Error(`AI_CTRL_HOLON_TASK_SPACE_MISSING: ${taskSpaceId}`);
-  return snapshot;
-}