@lota-sdk/core 0.1.9 → 0.1.11

package/src/services/execution-plan.service.ts

@@ -1,889 +1,682 @@
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
 import {
-  ExecutionPlanEventSchema,
-  ExecutionPlanSchema,
-  ExecutionPlanTaskResultStatusSchema,
-  ExecutionPlanTaskSchema,
+  PlanCheckpointSchema,
+  PlanEventSchema,
+  PlanNodeRunSchema,
+  PlanNodeSpecRecordSchema,
+  PlanRunSchema,
+  PlanSpecSchema,
 } from '@lota-sdk/shared/schemas/execution-plan'
 import type {
-  ExecutionPlanEventRecord,
-  ExecutionPlanRecord,
-  ExecutionPlanStatus,
-  ExecutionPlanTaskRecord,
-  ExecutionPlanTaskResultStatus,
-  ExecutionPlanTaskStatus,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+  PlanSpecRecord,
   SerializableExecutionPlan,
-  SerializableExecutionPlanCarriedTask,
-  SerializableExecutionPlanEvent,
-  SerializableExecutionPlanTask,
 } from '@lota-sdk/shared/schemas/execution-plan'
 import type {
   CreateExecutionPlanArgs,
   ExecutionPlanToolResultData,
+  GetActiveExecutionPlanArgs,
   ReplaceExecutionPlanArgs,
-  SetExecutionTaskStatusArgs,
-  RestartExecutionTaskArgs,
+  ResumeExecutionPlanRunArgs,
+  SubmitExecutionNodeResultArgs,
 } from '@lota-sdk/shared/schemas/tools'
-import { BoundQuery, RecordId } from 'surrealdb'
+import { RecordId } from 'surrealdb'
 
-import type { RecordIdInput, RecordIdRef } from '../db/record-id'
+import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
 import { databaseService } from '../db/service'
+import type { DatabaseTransaction } from '../db/service'
 import { TABLES } from '../db/tables'
-import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
-
-const ACTIVE_PLAN_STATUSES: ExecutionPlanStatus[] = ['draft', 'executing', 'blocked']
-const ACTIVE_PLAN_STATUS_SET = new Set<ExecutionPlanStatus>(ACTIVE_PLAN_STATUSES)
-const SUCCESSFUL_RESULT_STATUS_SET = new Set<ExecutionPlanTaskResultStatus>(['success', 'partial'])
-const CARRIED_RESULT_STATUS_SET = new Set<ExecutionPlanTaskResultStatus>(['success', 'partial'])
-const RESTART_REQUIRED_TASK_STATUS_SET = new Set<ExecutionPlanTaskStatus>(['completed', 'failed', 'skipped'])
-const TASK_STATUS_TRANSITIONS: Record<ExecutionPlanTaskStatus, ReadonlySet<ExecutionPlanTaskStatus>> = {
-  pending: new Set<ExecutionPlanTaskStatus>(['in-progress', 'blocked', 'skipped']),
-  'in-progress': new Set<ExecutionPlanTaskStatus>(['completed', 'blocked', 'failed', 'skipped']),
-  blocked: new Set<ExecutionPlanTaskStatus>(['in-progress', 'completed', 'failed', 'skipped']),
-  completed: new Set<ExecutionPlanTaskStatus>(),
-  failed: new Set<ExecutionPlanTaskStatus>(),
-  skipped: new Set<ExecutionPlanTaskStatus>(),
-}
-
-function normalizeTaskInput(
-  input: CreateExecutionPlanArgs['tasks'][number]['input'],
-): string | Record<string, unknown> | undefined {
-  if (input === undefined) return undefined
-  return typeof input === 'string' ? input : structuredClone(input)
-}
-
-function isExecutionPlanRecord(value: RecordIdInput | ExecutionPlanRecord): value is ExecutionPlanRecord {
-  return typeof value === 'object' && 'workstreamId' in value
-}
-
-function isExecutionPlanTaskRecord(value: RecordIdInput | ExecutionPlanTaskRecord): value is ExecutionPlanTaskRecord {
-  return typeof value === 'object' && 'position' in value
-}
-
-function toPlanId(planId: RecordIdInput | ExecutionPlanRecord): RecordIdRef {
-  return ensureRecordId(isExecutionPlanRecord(planId) ? planId.id : planId, TABLES.PLAN)
-}
-
-function toTaskId(taskId: RecordIdInput | ExecutionPlanTaskRecord): RecordIdRef {
-  return ensureRecordId(isExecutionPlanTaskRecord(taskId) ? taskId.id : taskId, TABLES.PLAN_TASK)
-}
-
-function toPlanIdString(planId: RecordIdInput | ExecutionPlanRecord): string {
-  return recordIdToString(toPlanId(planId), TABLES.PLAN)
-}
-
-function toTaskIdString(taskId: RecordIdInput | ExecutionPlanTaskRecord): string {
-  return recordIdToString(toTaskId(taskId), TABLES.PLAN_TASK)
-}
-
-function setDefinedOptionValue<TValue>(
-  target: Record<string, unknown>,
-  key: string,
-  value: TValue | null | undefined,
-  mapValue?: (value: TValue) => unknown,
-) {
-  if (value === undefined || value === null) return
-  target[key] = mapValue ? mapValue(value) : value
-}
-
-function pushOptionalAssignment<TValue>(
-  assignments: string[],
-  bindings: Record<string, unknown>,
-  key: string,
-  value: TValue | null | undefined,
-  mapValue?: (value: TValue) => unknown,
-) {
-  if (value === undefined) return
-  if (value === null) {
-    assignments.push(`${key} = NONE`)
-    return
-  }
-
-  assignments.push(`${key} = $${key}`)
-  bindings[key] = mapValue ? mapValue(value) : value
-}
-
-function serializeTask(task: ExecutionPlanTaskRecord): SerializableExecutionPlanTask {
+import { readApprovalContinuationResponse } from '../runtime/approval-continuation'
+import { extractMessageText } from '../runtime/workstream-chat-helpers'
+import { planBuilderService } from './plan-builder.service'
+import type { CompiledPlanNode } from './plan-compiler.service'
+import { planCompilerService } from './plan-compiler.service'
+import { planExecutorService } from './plan-executor.service'
+import { planRunService } from './plan-run.service'
+import { planValidatorService } from './plan-validator.service'
+
+function buildToolResult(params: {
+  action: ExecutionPlanToolResultData['action']
+  plan: SerializableExecutionPlan | null
+  message: string
+  changedNodeId?: string
+}): ExecutionPlanToolResultData {
   return {
-    id: recordIdToString(task.id, TABLES.PLAN_TASK),
-    position: task.position,
-    title: task.title,
-    rationale: task.rationale,
-    kind: task.kind,
-    ownerType: task.ownerType,
-    ownerRef: task.ownerRef,
-    status: task.status,
-    resultStatus: task.resultStatus,
-    ...(task.input !== undefined ? { input: task.input } : {}),
-    outputSummary: task.outputSummary,
-    blockedReason: task.blockedReason,
-    externalRef: task.externalRef,
-    retryCount: task.retryCount,
-    idempotencyKey: task.idempotencyKey,
-    startedAt: toOptionalIsoDateTimeString(task.startedAt),
-    completedAt: toOptionalIsoDateTimeString(task.completedAt),
+    action: params.action,
+    message: params.message,
+    ...(params.changedNodeId ? { changedNodeId: params.changedNodeId } : {}),
+    ...(params.plan ? { plan: params.plan } : {}),
+    hasPlan: params.plan !== null,
+    status: params.plan?.status,
   }
 }
 
-function serializeEvent(event: ExecutionPlanEventRecord): SerializableExecutionPlanEvent {
-  return {
-    id: recordIdToString(event.id, TABLES.PLAN_EVENT),
-    taskId: event.taskId ? recordIdToString(event.taskId, TABLES.PLAN_TASK) : undefined,
-    eventType: event.eventType,
-    fromStatus: event.fromStatus,
-    toStatus: event.toStatus,
-    message: event.message,
-    detail: event.detail,
-    emittedBy: event.emittedBy,
-    createdAt: toIsoDateTimeString(event.createdAt),
-  }
+function aggregateBlockingIssues(issues: Array<{ code: string; message: string }>): string {
+  return issues.map((issue) => `${issue.code}: ${issue.message}`).join(' | ')
 }
 
-function buildProgress(tasks: ExecutionPlanTaskRecord[]) {
-  const counts = tasks.reduce(
-    (summary, task) => {
-      summary[task.status] += 1
-      return summary
-    },
-    { pending: 0, 'in-progress': 0, completed: 0, blocked: 0, failed: 0, skipped: 0 } satisfies Record<
-      ExecutionPlanTaskStatus,
-      number
-    >,
-  )
-  const total = tasks.length
-  const completedWork = counts.completed + counts.skipped
-
+function toSpecData(spec: PlanSpecRecord, patch: Partial<PlanSpecRecord> & { replacedSpecId?: RecordIdInput | null }) {
   return {
-    total,
-    pending: counts.pending,
-    inProgress: counts['in-progress'],
-    completed: counts.completed,
-    blocked: counts.blocked,
-    failed: counts.failed,
-    skipped: counts.skipped,
-    completionRatio: total > 0 ? Number((completedWork / total).toFixed(4)) : undefined,
+    organizationId: ensureRecordId(spec.organizationId, TABLES.ORGANIZATION),
+    workstreamId: ensureRecordId(spec.workstreamId, TABLES.WORKSTREAM),
+    title: patch.title ?? spec.title,
+    objective: patch.objective ?? spec.objective,
+    version: patch.version ?? spec.version,
+    status: patch.status ?? spec.status,
+    leadAgentId: patch.leadAgentId ?? spec.leadAgentId,
+    schemaRegistry: patch.schemaRegistry ? structuredClone(patch.schemaRegistry) : structuredClone(spec.schemaRegistry),
+    edges: patch.edges ? [...patch.edges] : [...spec.edges],
+    entryNodeIds: patch.entryNodeIds ? [...patch.entryNodeIds] : [...spec.entryNodeIds],
+    ...(patch.replacedSpecId
+      ? { replacedSpecId: ensureRecordId(patch.replacedSpecId, TABLES.PLAN_SPEC) }
+      : spec.replacedSpecId
+        ? { replacedSpecId: ensureRecordId(spec.replacedSpecId, TABLES.PLAN_SPEC) }
+        : {}),
+    ...(patch.compiledAt !== undefined
+      ? { compiledAt: patch.compiledAt }
+      : spec.compiledAt
+        ? { compiledAt: spec.compiledAt }
+        : {}),
   }
 }
 
-function findCurrentTask(
-  tasks: ExecutionPlanTaskRecord[],
-  currentTaskId: string | Record<string, unknown> | null | undefined,
-) {
-  if (currentTaskId) {
-    const normalized = recordIdToString(currentTaskId as RecordIdInput, TABLES.PLAN_TASK)
-    const matched = tasks.find((task) => recordIdToString(task.id, TABLES.PLAN_TASK) === normalized)
-    if (matched) return matched
-  }
-
-  return tasks.find((task) => task.status === 'in-progress') ?? tasks.find((task) => task.status === 'pending') ?? null
+type PlanRunUpdate = Omit<
+  Partial<PlanRunRecord>,
+  'currentNodeId' | 'waitingNodeId' | 'replacedRunId' | 'lastCheckpointId' | 'startedAt' | 'completedAt'
+> & {
+  currentNodeId?: string | null
+  waitingNodeId?: string | null
+  replacedRunId?: RecordIdInput | null
+  lastCheckpointId?: RecordIdInput | null
+  startedAt?: Date | null
+  completedAt?: Date | null
 }
 
-function assertTaskStatusTransition(
-  task: ExecutionPlanTaskRecord,
-  nextStatus: ExecutionPlanTaskStatus,
-  taskTitle: string,
-): void {
-  if (task.status === nextStatus) {
-    throw new Error(`Execution task "${taskTitle}" is already ${nextStatus}.`)
-  }
-
-  if (RESTART_REQUIRED_TASK_STATUS_SET.has(task.status)) {
-    throw new Error(`Use restartExecutionTask before changing execution task "${taskTitle}" from ${task.status}.`)
-  }
-
-  if (TASK_STATUS_TRANSITIONS[task.status].has(nextStatus)) {
-    return
+function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
+  return {
+    planSpecId: ensureRecordId(run.planSpecId, TABLES.PLAN_SPEC),
+    organizationId: ensureRecordId(run.organizationId, TABLES.ORGANIZATION),
+    workstreamId: ensureRecordId(run.workstreamId, TABLES.WORKSTREAM),
+    leadAgentId: patch.leadAgentId ?? run.leadAgentId,
+    status: patch.status ?? run.status,
+    ...(patch.currentNodeId === null
+      ? {}
+      : patch.currentNodeId !== undefined
+        ? { currentNodeId: patch.currentNodeId }
+        : run.currentNodeId
+          ? { currentNodeId: run.currentNodeId }
+          : {}),
+    ...(patch.waitingNodeId === null
+      ? {}
+      : patch.waitingNodeId !== undefined
+        ? { waitingNodeId: patch.waitingNodeId }
+        : run.waitingNodeId
+          ? { waitingNodeId: run.waitingNodeId }
+          : {}),
+    readyNodeIds: patch.readyNodeIds ? [...patch.readyNodeIds] : [...run.readyNodeIds],
+    failureCount: patch.failureCount ?? run.failureCount,
+    ...(patch.replacedRunId === null
+      ? {}
+      : patch.replacedRunId
+        ? { replacedRunId: ensureRecordId(patch.replacedRunId, TABLES.PLAN_RUN) }
+        : run.replacedRunId
+          ? { replacedRunId: ensureRecordId(run.replacedRunId, TABLES.PLAN_RUN) }
+          : {}),
+    ...(patch.lastCheckpointId === null
+      ? {}
+      : patch.lastCheckpointId
+        ? { lastCheckpointId: ensureRecordId(patch.lastCheckpointId, TABLES.PLAN_CHECKPOINT) }
+        : run.lastCheckpointId
+          ? { lastCheckpointId: ensureRecordId(run.lastCheckpointId, TABLES.PLAN_CHECKPOINT) }
+          : {}),
+    ...(patch.startedAt === null
+      ? {}
+      : patch.startedAt !== undefined
+        ? { startedAt: patch.startedAt }
+        : run.startedAt
+          ? { startedAt: run.startedAt }
+          : {}),
+    ...(patch.completedAt === null
+      ? {}
+      : patch.completedAt !== undefined
+        ? { completedAt: patch.completedAt }
+        : run.completedAt
+          ? { completedAt: run.completedAt }
+          : {}),
   }
-
-  throw new Error(`Cannot change execution task "${taskTitle}" from ${task.status} to ${nextStatus}.`)
 }
 
-class ExecutionPlanService {
-  private async getTaskById(taskId: RecordIdInput): Promise<ExecutionPlanTaskRecord> {
-    const recordId = ensureRecordId(taskId, TABLES.PLAN_TASK)
-    const row = await databaseService.findOne(TABLES.PLAN_TASK, { id: recordId }, ExecutionPlanTaskSchema)
-    if (!row) {
-      throw new Error(`Execution plan task not found: ${recordId.toString()}`)
+function buildApprovalResponseFromMessages(
+  messages: ChatMessage[],
+): { approvalId: string; response: Record<string, unknown> } | null {
+  for (const message of [...messages].reverse()) {
+    if (message.role !== 'assistant') continue
+    const approvalResponse = readApprovalContinuationResponse(message)
+    if (!approvalResponse) continue
+
+    const response: Record<string, unknown> = {
+      approved: approvalResponse.approved,
+      requiredEdits: [...approvalResponse.requiredEdits],
     }
-    return row
-  }
-
-  private async listPlanTasks(planId: RecordIdInput): Promise<ExecutionPlanTaskRecord[]> {
-    return await databaseService.findMany(
-      TABLES.PLAN_TASK,
-      { planId: ensureRecordId(planId, TABLES.PLAN) },
-      ExecutionPlanTaskSchema,
-      { orderBy: 'position', orderDir: 'ASC' },
-    )
-  }
-
-  private async listPlanEvents(planId: RecordIdInput, limit = 20): Promise<ExecutionPlanEventRecord[]> {
-    return (
-      await databaseService.findMany(
-        TABLES.PLAN_EVENT,
-        { planId: ensureRecordId(planId, TABLES.PLAN) },
-        ExecutionPlanEventSchema,
-        { orderBy: 'createdAt', orderDir: 'DESC', limit },
-      )
-    ).reverse()
-  }
-
-  private async emitEvent(params: {
-    planId: RecordIdInput
-    taskId?: RecordIdInput | null
-    eventType: ExecutionPlanEventRecord['eventType']
-    fromStatus?: string | null
-    toStatus?: string | null
-    message: string
-    detail?: Record<string, unknown> | null
-    emittedBy: string
-  }): Promise<void> {
-    const eventData: Record<string, unknown> = {
-      planId: ensureRecordId(params.planId, TABLES.PLAN),
-      eventType: params.eventType,
-      message: params.message,
-      emittedBy: params.emittedBy,
+    if (approvalResponse.comments) {
+      response.comments = approvalResponse.comments
     }
-    setDefinedOptionValue(eventData, 'taskId', params.taskId, (taskId) => ensureRecordId(taskId, TABLES.PLAN_TASK))
-    setDefinedOptionValue(eventData, 'fromStatus', params.fromStatus)
-    setDefinedOptionValue(eventData, 'toStatus', params.toStatus)
-    setDefinedOptionValue(eventData, 'detail', params.detail)
 
-    await databaseService.create(TABLES.PLAN_EVENT, eventData, ExecutionPlanEventSchema)
+    return { approvalId: approvalResponse.approvalId, response }
   }
 
-  private async updatePlanStatus(params: {
-    plan: ExecutionPlanRecord
-    status: ExecutionPlanStatus
-    currentTaskId?: RecordIdInput | null
-    restartFromTaskId?: RecordIdInput | null
-    failureCount?: number
-    startedAt?: Date | null
-    completedAt?: Date | null
-    emittedBy: string
-    message?: string
-    detail?: Record<string, unknown>
-  }): Promise<ExecutionPlanRecord> {
-    const bindings: Record<string, unknown> = { status: params.status }
-    const assignments = ['status = $status']
-    pushOptionalAssignment(assignments, bindings, 'currentTaskId', params.currentTaskId, (taskId) =>
-      ensureRecordId(taskId, TABLES.PLAN_TASK),
-    )
-    pushOptionalAssignment(assignments, bindings, 'restartFromTaskId', params.restartFromTaskId, (taskId) =>
-      ensureRecordId(taskId, TABLES.PLAN_TASK),
-    )
-    if (params.failureCount !== undefined) {
-      assignments.push('failureCount = $failureCount')
-      bindings.failureCount = params.failureCount
-    }
-    pushOptionalAssignment(assignments, bindings, 'startedAt', params.startedAt)
-    pushOptionalAssignment(assignments, bindings, 'completedAt', params.completedAt)
-
-    const rows = await databaseService.query<unknown>(
-      new BoundQuery(`UPDATE ONLY ${toPlanIdString(params.plan)} SET ${assignments.join(', ')} RETURN AFTER`, bindings),
-    )
-    const next = rows.at(0) ? ExecutionPlanSchema.parse(rows[0]) : null
-
-    if (!next) {
-      throw new Error(`Failed to update execution plan ${recordIdToString(params.plan.id, TABLES.PLAN)}`)
-    }
-
-    if (params.plan.status !== next.status) {
-      await this.emitEvent({
-        planId: next.id,
-        eventType: 'plan-status-changed',
-        fromStatus: params.plan.status,
-        toStatus: next.status,
-        message: params.message ?? `Plan status changed from ${params.plan.status} to ${next.status}.`,
-        detail: params.detail,
-        emittedBy: params.emittedBy,
-      })
-    }
-
-    return next
-  }
-
-  private async updateTaskRecord(params: {
-    task: ExecutionPlanTaskRecord
-    status: ExecutionPlanTaskStatus
-    resultStatus: ExecutionPlanTaskResultStatus
-    outputSummary?: string | null
-    blockedReason?: string | null
-    externalRef?: string | null
-    startedAt?: Date | null
-    completedAt?: Date | null
-  }): Promise<ExecutionPlanTaskRecord> {
-    const bindings: Record<string, unknown> = { status: params.status, resultStatus: params.resultStatus }
-    const assignments = ['status = $status', 'resultStatus = $resultStatus']
-    pushOptionalAssignment(assignments, bindings, 'outputSummary', params.outputSummary)
-    pushOptionalAssignment(assignments, bindings, 'blockedReason', params.blockedReason)
-    pushOptionalAssignment(assignments, bindings, 'externalRef', params.externalRef)
-    pushOptionalAssignment(assignments, bindings, 'startedAt', params.startedAt)
-    pushOptionalAssignment(assignments, bindings, 'completedAt', params.completedAt)
-
-    const rows = await databaseService.query<unknown>(
-      new BoundQuery(`UPDATE ONLY ${toTaskIdString(params.task)} SET ${assignments.join(', ')} RETURN AFTER`, bindings),
-    )
-    const next = rows.at(0) ? ExecutionPlanTaskSchema.parse(rows[0]) : null
-    if (!next) {
-      throw new Error(`Failed to update execution task ${recordIdToString(params.task.id, TABLES.PLAN_TASK)}`)
-    }
-
-    return next
-  }
-
-  private async getActivePlanRecord(workstreamId: RecordIdInput): Promise<ExecutionPlanRecord | null> {
-    const plans = await databaseService.findMany(
-      TABLES.PLAN,
-      { workstreamId: ensureRecordId(workstreamId, TABLES.WORKSTREAM) },
-      ExecutionPlanSchema,
-      { orderBy: 'updatedAt', orderDir: 'DESC' },
-    )
-
-    return plans.find((plan) => ACTIVE_PLAN_STATUS_SET.has(plan.status)) ?? null
-  }
-
-  private async collectCarriedTasks(plan: ExecutionPlanRecord): Promise<SerializableExecutionPlanCarriedTask[]> {
-    const carried: SerializableExecutionPlanCarriedTask[] = []
-    let currentReplacedPlanId = plan.replacedPlanId ? ensureRecordId(plan.replacedPlanId, TABLES.PLAN) : null
-    let depth = 0
-
-    while (currentReplacedPlanId && depth < 5) {
-      const previousPlan = await databaseService.findOne(
-        TABLES.PLAN,
-        { id: currentReplacedPlanId },
-        ExecutionPlanSchema,
-      )
-      if (!previousPlan) break
-
-      const previousTasks = await this.listPlanTasks(previousPlan.id)
-      const currentPlanId = recordIdToString(previousPlan.id, TABLES.PLAN)
-      carried.unshift(
-        ...previousTasks
-          .filter(
-            (task) =>
-              CARRIED_RESULT_STATUS_SET.has(task.resultStatus) &&
-              typeof task.outputSummary === 'string' &&
-              task.outputSummary.trim().length > 0,
-          )
-          .map((task) => ({
-            planId: currentPlanId,
-            taskId: recordIdToString(task.id, TABLES.PLAN_TASK),
-            title: task.title,
-            resultStatus: task.resultStatus,
-            outputSummary: task.outputSummary ?? '',
-          })),
-      )
-
-      currentReplacedPlanId = previousPlan.replacedPlanId
-        ? ensureRecordId(previousPlan.replacedPlanId, TABLES.PLAN)
-        : null
-      depth += 1
-    }
-
-    return carried
-  }
-
-  private async toSerializablePlan(
-    plan: ExecutionPlanRecord,
-    options?: { includeEvents?: boolean },
-  ): Promise<SerializableExecutionPlan> {
-    const tasks = await this.listPlanTasks(plan.id)
-    const recentEvents = options?.includeEvents ? await this.listPlanEvents(plan.id, 20) : []
-    const carriedTasks = await this.collectCarriedTasks(plan)
-    const currentTask = findCurrentTask(tasks, plan.currentTaskId)
-
-    return {
-      planId: recordIdToString(plan.id, TABLES.PLAN),
-      workstreamId: recordIdToString(plan.workstreamId, TABLES.WORKSTREAM),
-      organizationId: recordIdToString(plan.organizationId, TABLES.ORGANIZATION),
-      title: plan.title,
-      objective: plan.objective,
-      status: plan.status,
-      leadAgentId: plan.leadAgentId,
-      currentTaskId: currentTask ? recordIdToString(currentTask.id, TABLES.PLAN_TASK) : undefined,
-      restartFromTaskId: plan.restartFromTaskId
-        ? recordIdToString(plan.restartFromTaskId, TABLES.PLAN_TASK)
-        : undefined,
-      replacedPlanId: plan.replacedPlanId ? recordIdToString(plan.replacedPlanId, TABLES.PLAN) : undefined,
-      failureCount: plan.failureCount,
-      startedAt: toOptionalIsoDateTimeString(plan.startedAt),
-      completedAt: toOptionalIsoDateTimeString(plan.completedAt),
-      progress: buildProgress(tasks),
-      tasks: tasks.map(serializeTask),
-      recentEvents: recentEvents.map(serializeEvent),
-      carriedTasks,
-    }
-  }
-
-  private buildToolResult(params: {
-    action: ExecutionPlanToolResultData['action']
-    plan: SerializableExecutionPlan | null
-    message?: string
-    changedTaskId?: string
-  }): ExecutionPlanToolResultData {
-    return {
-      action: params.action,
-      ...(params.message ? { message: params.message } : {}),
-      ...(params.changedTaskId !== undefined ? { changedTaskId: params.changedTaskId } : {}),
-      ...(params.plan ? { plan: params.plan } : {}),
-      hasPlan: params.plan !== null,
-      status: params.plan?.status,
-    }
-  }
+  return null
+}
 
+class ExecutionPlanService {
   async hasActivePlan(workstreamId: RecordIdInput): Promise<boolean> {
-    return (await this.getActivePlanRecord(workstreamId)) !== null
+    return (await planRunService.getActiveRunRecord(workstreamId)) !== null
   }
 
   async getActivePlanForWorkstream(
     workstreamId: RecordIdInput,
-    options?: { includeEvents?: boolean },
+    options?: Partial<GetActiveExecutionPlanArgs>,
   ): Promise<SerializableExecutionPlan | null> {
-    const plan = await this.getActivePlanRecord(workstreamId)
-    if (!plan) return null
-    return await this.toSerializablePlan(plan, options)
+    const run = await planRunService.getActiveRunRecord(workstreamId)
+    if (!run) return null
+
+    return await planRunService.toSerializablePlan(run, {
+      includeEvents: options?.includeEvents,
+      includeArtifacts: options?.includeArtifacts,
+      includeApprovals: options?.includeApprovals,
+      includeCheckpoints: options?.includeCheckpoints,
+      includeValidationIssues: options?.includeValidationIssues,
+    })
+  }
+
+  async getActivePlanToolResult(params: {
+    workstreamId: RecordIdInput
+    includeEvents?: boolean
+    includeArtifacts?: boolean
+    includeApprovals?: boolean
+    includeCheckpoints?: boolean
+    includeValidationIssues?: boolean
+  }): Promise<ExecutionPlanToolResultData> {
+    const plan = await this.getActivePlanForWorkstream(params.workstreamId, params)
+    return buildToolResult({
+      action: plan ? 'loaded' : 'none',
+      plan,
+      message: plan ? `Loaded execution run "${plan.title}".` : 'No active execution run.',
+    })
   }
 
   async createPlan(params: {
     organizationId: RecordIdInput
     workstreamId: RecordIdInput
-    leadAgentId: ExecutionPlanRecord['leadAgentId']
+    leadAgentId: string
     input: CreateExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const activePlan = await this.getActivePlanRecord(params.workstreamId)
-    if (activePlan) {
-      throw new Error('An active execution plan already exists for this workstream. Replace it instead.')
+    const activeRun = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (activeRun) {
+      throw new Error('An active execution run already exists for this workstream. Replace it instead.')
     }
 
-    const planId = new RecordId(TABLES.PLAN, Bun.randomUUIDv7())
-    const taskIds = params.input.tasks.map(() => new RecordId(TABLES.PLAN_TASK, Bun.randomUUIDv7()))
-    const organizationId = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
-    const workstreamId = ensureRecordId(params.workstreamId, TABLES.WORKSTREAM)
-    const planData: Record<string, unknown> = {
-      organizationId,
-      workstreamId,
-      title: params.input.title,
-      objective: params.input.objective,
-      status: 'draft',
-      leadAgentId: params.leadAgentId,
-      currentTaskId: taskIds[0],
-      failureCount: 0,
+    const preparedDraft = planBuilderService.prepareDraft(params.input)
+    const validation = planValidatorService.validateDraft(preparedDraft)
+    if (validation.blocking.length > 0) {
+      throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)
     }
+    const compiled = planCompilerService.compile(preparedDraft)
+
+    const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
+    const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
+
+    await databaseService.withTransaction(async (tx) => {
+      const spec = PlanSpecSchema.parse(
+        await tx
+          .create(specId)
+          .content({
+            organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+            workstreamId: ensureRecordId(params.workstreamId, TABLES.WORKSTREAM),
+            title: compiled.draft.title,
+            objective: compiled.draft.objective,
+            version: 1,
+            status: 'compiled',
+            leadAgentId: params.leadAgentId,
+            schemaRegistry: structuredClone(compiled.draft.schemas),
+            edges: [...compiled.draft.edges],
+            entryNodeIds: [...(compiled.draft.entryNodeIds ?? [])],
+            compiledAt: new Date(),
+          })
+          .output('after'),
+      )
 
-    const plan = await databaseService.createWithId(TABLES.PLAN, planId, planData, ExecutionPlanSchema)
-
-    for (const [index, task] of params.input.tasks.entries()) {
-      const taskData: Record<string, unknown> = {
-        planId,
-        organizationId,
-        workstreamId,
-        position: index,
-        title: task.title,
-        rationale: task.rationale,
-        kind: task.kind,
-        ownerType: task.ownerType,
-        ownerRef: task.ownerRef,
-        status: 'pending',
-        resultStatus: 'not-started',
-        retryCount: 0,
-        idempotencyKey: `${planId.toString()}:${index}`,
-      }
-      setDefinedOptionValue(taskData, 'input', task.input, normalizeTaskInput)
-
-      await databaseService.createWithId(TABLES.PLAN_TASK, taskIds[index], taskData, ExecutionPlanTaskSchema)
-    }
+      const nodeSpecs = await this.createNodeSpecs(tx, spec.id, compiled.nodes)
+      const run = PlanRunSchema.parse(
+        await tx
+          .create(runId)
+          .content({
+            planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+            organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+            workstreamId: ensureRecordId(params.workstreamId, TABLES.WORKSTREAM),
+            leadAgentId: params.leadAgentId,
+            status: 'running',
+            readyNodeIds: [],
+            failureCount: 0,
+            startedAt: new Date(),
+          })
+          .output('after'),
+      )
 
-    await this.emitEvent({
-      planId: plan.id,
-      eventType: 'plan-created',
-      message: `Created execution plan "${plan.title}" with ${params.input.tasks.length} tasks.`,
-      detail: { title: plan.title, objective: plan.objective, taskCount: params.input.tasks.length },
-      emittedBy: params.leadAgentId,
+      const nodeRuns = await this.createNodeRuns(tx, run.id, spec.id, nodeSpecs)
+      const synced = await planExecutorService.syncRunGraph({
+        tx,
+        run,
+        spec,
+        nodeSpecs,
+        nodeRuns,
+        artifacts: [],
+        emittedBy: params.leadAgentId,
+      })
+
+      const event = await tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+          eventType: 'plan-created',
+          message: `Created execution plan "${spec.title}".`,
+          emittedBy: params.leadAgentId,
+          detail: { title: spec.title, objective: spec.objective, nodeCount: nodeSpecs.length },
+        })
+        .output('after')
+      PlanEventSchema.parse(event)
+
+      const checkpoint = PlanCheckpointSchema.parse(
+        await tx
+          .create(new RecordId(TABLES.PLAN_CHECKPOINT, Bun.randomUUIDv7()))
+          .content({
+            runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+            sequence: 1,
+            runStatus: synced.run.status,
+            readyNodeIds: [...synced.run.readyNodeIds],
+            activeNodeIds: synced.run.currentNodeId ? [synced.run.currentNodeId] : [],
+            artifactIds: [],
+            lastCompletedNodeIds: synced.nodeRuns
+              .filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+              .map((nodeRun) => nodeRun.nodeId),
+            snapshot: {
+              reason: 'plan-created',
+              currentNodeId: synced.run.currentNodeId,
+              waitingNodeId: synced.run.waitingNodeId,
+              readyNodeIds: synced.run.readyNodeIds,
+            },
+          })
+          .output('after'),
+      )
+
+      const updatedRun = PlanRunSchema.parse(
+        await tx
+          .update(ensureRecordId(synced.run.id, TABLES.PLAN_RUN))
+          .content(toRunData(synced.run, { lastCheckpointId: checkpoint.id }))
+          .output('after'),
+      )
+
+      const checkpointEvent = await tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(updatedRun.id, TABLES.PLAN_RUN),
+          eventType: 'checkpoint-saved',
+          message: 'Saved checkpoint 1.',
+          emittedBy: 'system',
+          detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: 'plan-created' },
+        })
+        .output('after')
+      PlanEventSchema.parse(checkpointEvent)
     })
 
-    const serializable = await this.toSerializablePlan(plan, { includeEvents: true })
-    return this.buildToolResult({
-      action: 'created',
-      plan: serializable,
-      message: `Created execution plan "${plan.title}".`,
+    const plan = await planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
     })
+
+    return buildToolResult({ action: 'created', plan, message: `Created execution plan "${plan.title}".` })
   }
 
   async replacePlan(params: {
     workstreamId: RecordIdInput
     organizationId: RecordIdInput
-    leadAgentId: ExecutionPlanRecord['leadAgentId']
+    leadAgentId: string
     input: ReplaceExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const activePlan = await this.getActivePlanRecord(params.workstreamId)
-    if (!activePlan) {
-      throw new Error('No active execution plan exists for this workstream.')
+    const activeRun = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (!activeRun) {
+      throw new Error('No active execution run exists for this workstream.')
     }
-    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
-      throw new Error('Only the active execution plan can be replaced.')
+    if (recordIdToString(activeRun.id, TABLES.PLAN_RUN) !== params.input.runId) {
+      throw new Error('Only the active execution run can be replaced.')
     }
 
-    const oldPlan = await this.updatePlanStatus({
-      plan: activePlan,
-      status: 'aborted',
-      currentTaskId: activePlan.currentTaskId,
-      restartFromTaskId: activePlan.restartFromTaskId,
-      emittedBy: params.leadAgentId,
-      message: `Plan "${activePlan.title}" was replaced.`,
-      detail: { reason: params.input.reason },
-    })
-
-    const planId = new RecordId(TABLES.PLAN, Bun.randomUUIDv7())
-    const taskIds = params.input.tasks.map(() => new RecordId(TABLES.PLAN_TASK, Bun.randomUUIDv7()))
-    const organizationId = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
-    const workstreamId = ensureRecordId(params.workstreamId, TABLES.WORKSTREAM)
-    const nextPlanData: Record<string, unknown> = {
-      organizationId,
-      workstreamId,
+    const activeSpec = await planRunService.getPlanSpecById(activeRun.planSpecId)
+    const preparedDraft = planBuilderService.prepareDraft({
       title: params.input.title,
       objective: params.input.objective,
-      status: 'draft',
-      leadAgentId: params.leadAgentId,
-      currentTaskId: taskIds[0],
-      replacedPlanId: ensureRecordId(oldPlan.id, TABLES.PLAN),
-      failureCount: 0,
+      nodes: params.input.nodes,
+      edges: params.input.edges,
+      entryNodeIds: params.input.entryNodeIds,
+      schemas: params.input.schemas,
+    })
+    const validation = planValidatorService.validateDraft(preparedDraft)
+    if (validation.blocking.length > 0) {
+      throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)
     }
+    const compiled = planCompilerService.compile(preparedDraft)
 
-    const nextPlan = await databaseService.createWithId(TABLES.PLAN, planId, nextPlanData, ExecutionPlanSchema)
-
-    for (const [index, task] of params.input.tasks.entries()) {
-      const taskData: Record<string, unknown> = {
-        planId,
-        organizationId,
-        workstreamId,
-        position: index,
-        title: task.title,
-        rationale: task.rationale,
-        kind: task.kind,
-        ownerType: task.ownerType,
-        ownerRef: task.ownerRef,
-        status: 'pending',
-        resultStatus: 'not-started',
-        retryCount: 0,
-        idempotencyKey: `${planId.toString()}:${index}`,
-      }
-      setDefinedOptionValue(taskData, 'input', task.input, normalizeTaskInput)
-
-      await databaseService.createWithId(TABLES.PLAN_TASK, taskIds[index], taskData, ExecutionPlanTaskSchema)
-    }
+    const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
+    const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
 
-    await this.emitEvent({
-      planId: oldPlan.id,
-      eventType: 'replan',
-      message: `Created replacement plan "${nextPlan.title}".`,
-      detail: {
-        reason: params.input.reason,
-        oldPlanId: recordIdToString(oldPlan.id, TABLES.PLAN),
-        newPlanId: recordIdToString(nextPlan.id, TABLES.PLAN),
-      },
-      emittedBy: params.leadAgentId,
-    })
-    await this.emitEvent({
-      planId: nextPlan.id,
-      eventType: 'plan-created',
-      message: `Created execution plan "${nextPlan.title}" with ${params.input.tasks.length} tasks.`,
-      detail: {
-        title: nextPlan.title,
-        objective: nextPlan.objective,
-        taskCount: params.input.tasks.length,
-        replacedPlanId: recordIdToString(oldPlan.id, TABLES.PLAN),
-      },
-      emittedBy: params.leadAgentId,
-    })
-    await this.emitEvent({
-      planId: nextPlan.id,
-      eventType: 'plan-replaced',
-      message: `Plan "${nextPlan.title}" replaces "${oldPlan.title}".`,
-      detail: { reason: params.input.reason, replacedPlanId: recordIdToString(oldPlan.id, TABLES.PLAN) },
-      emittedBy: params.leadAgentId,
+    await databaseService.withTransaction(async (tx) => {
+      const supersededSpec = PlanSpecSchema.parse(
+        await tx
+          .update(ensureRecordId(activeSpec.id, TABLES.PLAN_SPEC))
+          .content(toSpecData(activeSpec, { status: 'superseded' }))
+          .output('after'),
+      )
+
+      const abortedRun = PlanRunSchema.parse(
+        await tx
+          .update(ensureRecordId(activeRun.id, TABLES.PLAN_RUN))
+          .content(
+            toRunData(activeRun, {
+              status: 'aborted',
+              currentNodeId: null,
+              waitingNodeId: null,
+              readyNodeIds: [],
+              completedAt: new Date(),
+            }),
+          )
+          .output('after'),
+      )
+
+      const spec = PlanSpecSchema.parse(
+        await tx
+          .create(specId)
+          .content({
+            organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+            workstreamId: ensureRecordId(params.workstreamId, TABLES.WORKSTREAM),
+            title: compiled.draft.title,
+            objective: compiled.draft.objective,
+            version: supersededSpec.version + 1,
+            status: 'compiled',
+            leadAgentId: params.leadAgentId,
+            schemaRegistry: structuredClone(compiled.draft.schemas),
+            edges: [...compiled.draft.edges],
+            entryNodeIds: [...(compiled.draft.entryNodeIds ?? [])],
+            replacedSpecId: ensureRecordId(supersededSpec.id, TABLES.PLAN_SPEC),
+            compiledAt: new Date(),
+          })
+          .output('after'),
+      )
+
+      const nodeSpecs = await this.createNodeSpecs(tx, spec.id, compiled.nodes)
+      const run = PlanRunSchema.parse(
+        await tx
+          .create(runId)
+          .content({
+            planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+            organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+            workstreamId: ensureRecordId(params.workstreamId, TABLES.WORKSTREAM),
+            leadAgentId: params.leadAgentId,
+            status: 'running',
+            readyNodeIds: [],
+            failureCount: 0,
+            replacedRunId: ensureRecordId(abortedRun.id, TABLES.PLAN_RUN),
+            startedAt: new Date(),
+          })
+          .output('after'),
+      )
+
+      const nodeRuns = await this.createNodeRuns(tx, run.id, spec.id, nodeSpecs)
+      const synced = await planExecutorService.syncRunGraph({
+        tx,
+        run,
+        spec,
+        nodeSpecs,
+        nodeRuns,
+        artifacts: [],
+        emittedBy: params.leadAgentId,
+      })
+
+      const replaceEvent = await tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+          eventType: 'plan-replaced',
+          message: `Replaced execution plan "${activeSpec.title}" with "${spec.title}".`,
+          emittedBy: params.leadAgentId,
+          detail: { reason: params.input.reason, replacedRunId: recordIdToString(abortedRun.id, TABLES.PLAN_RUN) },
+        })
+        .output('after')
+      PlanEventSchema.parse(replaceEvent)
+
+      const checkpoint = PlanCheckpointSchema.parse(
+        await tx
+          .create(new RecordId(TABLES.PLAN_CHECKPOINT, Bun.randomUUIDv7()))
+          .content({
+            runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+            sequence: 1,
+            runStatus: synced.run.status,
+            readyNodeIds: [...synced.run.readyNodeIds],
+            activeNodeIds: synced.run.currentNodeId ? [synced.run.currentNodeId] : [],
+            artifactIds: [],
+            lastCompletedNodeIds: synced.nodeRuns
+              .filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+              .map((nodeRun) => nodeRun.nodeId),
+            snapshot: {
+              reason: 'plan-replaced',
+              currentNodeId: synced.run.currentNodeId,
+              waitingNodeId: synced.run.waitingNodeId,
+              readyNodeIds: synced.run.readyNodeIds,
+            },
+          })
+          .output('after'),
+      )
+
+      const updatedRun = PlanRunSchema.parse(
+        await tx
+          .update(ensureRecordId(synced.run.id, TABLES.PLAN_RUN))
+          .content(toRunData(synced.run, { lastCheckpointId: checkpoint.id }))
+          .output('after'),
+      )
+
+      const checkpointEvent = await tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(updatedRun.id, TABLES.PLAN_RUN),
+          eventType: 'checkpoint-saved',
+          message: 'Saved checkpoint 1.',
+          emittedBy: 'system',
+          detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: 'plan-replaced' },
+        })
+        .output('after')
+      PlanEventSchema.parse(checkpointEvent)
     })
 
-    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
-    return this.buildToolResult({
-      action: 'replaced',
-      plan: serializable,
-      message: `Replaced execution plan with "${nextPlan.title}".`,
+    const plan = await planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
     })
+
+    return buildToolResult({ action: 'replaced', plan, message: `Replaced execution plan with "${plan.title}".` })
   }
 
-  async getActivePlanToolResult(params: {
+  async submitNodeResult(params: {
     workstreamId: RecordIdInput
-    includeEvents?: boolean
+    emittedBy: string
+    input: SubmitExecutionNodeResultArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const plan = await this.getActivePlanForWorkstream(params.workstreamId, { includeEvents: params.includeEvents })
-    return this.buildToolResult({
-      action: plan ? 'loaded' : 'none',
-      plan,
-      ...(plan ? { message: `Loaded execution plan "${plan.title}".` } : { message: 'No active execution plan.' }),
+    return await planExecutorService.submitNodeResult({
+      workstreamId: params.workstreamId,
+      runId: params.input.runId,
+      nodeId: params.input.nodeId,
+      emittedBy: params.emittedBy,
+      result: params.input.result,
     })
   }
 
-  async setTaskStatus(params: {
+  async resumeRun(params: {
     workstreamId: RecordIdInput
     emittedBy: string
-    input: SetExecutionTaskStatusArgs
+    input: ResumeExecutionPlanRunArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const activePlan = await this.getActivePlanRecord(params.workstreamId)
-    if (!activePlan) {
-      throw new Error('No active execution plan exists for this workstream.')
-    }
-    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
-      throw new Error('Task updates must target the active execution plan.')
-    }
-
-    const task = await this.getTaskById(params.input.taskId)
-    if (recordIdToString(task.planId, TABLES.PLAN) !== params.input.planId) {
-      throw new Error('Execution task does not belong to the provided plan.')
-    }
-    assertTaskStatusTransition(task, params.input.status, task.title)
-
-    const tasks = await this.listPlanTasks(activePlan.id)
-    const otherInProgressTask = tasks.find(
-      (candidate) =>
-        candidate.status === 'in-progress' &&
-        recordIdToString(candidate.id, TABLES.PLAN_TASK) !== recordIdToString(task.id, TABLES.PLAN_TASK),
-    )
-    if (params.input.status === 'in-progress' && otherInProgressTask) {
-      throw new Error('Only one execution-plan task may be in progress at a time.')
-    }
-
-    if (params.input.status === 'pending') {
-      throw new Error('Use restartExecutionTask to reset a task back to pending.')
-    }
-
-    if (params.input.status === 'completed') {
-      if (!params.input.resultStatus) {
-        throw new Error('Completed tasks require resultStatus.')
-      }
-      if (!SUCCESSFUL_RESULT_STATUS_SET.has(params.input.resultStatus)) {
-        throw new Error('Completed tasks require resultStatus to be success or partial.')
-      }
-      if (!params.input.outputSummary?.trim() && !params.input.externalRef?.trim()) {
-        throw new Error('Completed tasks require outputSummary or externalRef.')
-      }
-    }
-
-    if (params.input.status === 'blocked' && !params.input.blockedReason?.trim()) {
-      throw new Error('Blocked tasks require blockedReason.')
-    }
-
-    if (params.input.status === 'failed' && !params.input.outputSummary?.trim()) {
-      throw new Error('Failed tasks require outputSummary.')
-    }
-
-    const now = new Date()
-    let nextPlan = activePlan
-    let nextResultStatus = task.resultStatus
-    let nextFailureCount = activePlan.failureCount
-    let taskStartedAt: Date | null | undefined = task.startedAt
-      ? undefined
-      : params.input.status === 'in-progress'
-        ? now
-        : undefined
-    let taskCompletedAt: Date | null | undefined = undefined
-    let message = ''
-
-    if (params.input.status === 'in-progress') {
-      nextPlan = await this.updatePlanStatus({
-        plan: activePlan,
-        status: 'executing',
-        currentTaskId: task.id,
-        restartFromTaskId: null,
-        ...(activePlan.startedAt ? {} : { startedAt: now }),
-        emittedBy: params.emittedBy,
-      })
-      nextResultStatus = task.resultStatus
-      message = `Started task "${task.title}".`
-    } else if (params.input.status === 'completed' || params.input.status === 'skipped') {
-      nextResultStatus =
-        params.input.status === 'completed'
-          ? ExecutionPlanTaskResultStatusSchema.parse(params.input.resultStatus)
-          : (params.input.resultStatus ?? 'not-started')
-      taskCompletedAt = now
-
-      const refreshedTasks = tasks.map((candidate) =>
-        recordIdToString(candidate.id, TABLES.PLAN_TASK) === recordIdToString(task.id, TABLES.PLAN_TASK)
-          ? { ...candidate, status: params.input.status, resultStatus: nextResultStatus }
-          : candidate,
-      )
-      const nextPendingTask =
-        refreshedTasks.find((candidate) => candidate.position > task.position && candidate.status === 'pending') ??
-        refreshedTasks.find((candidate) => candidate.status === 'pending') ??
-        null
-
-      if (nextPendingTask) {
-        nextPlan = await this.updatePlanStatus({
-          plan: activePlan,
-          status: 'executing',
-          currentTaskId: nextPendingTask.id,
-          restartFromTaskId: null,
-          failureCount: 0,
-          emittedBy: params.emittedBy,
-        })
-      } else {
-        nextPlan = await this.updatePlanStatus({
-          plan: activePlan,
-          status: 'completed',
-          currentTaskId: null,
-          restartFromTaskId: null,
-          failureCount: 0,
-          completedAt: now,
-          ...(activePlan.startedAt ? {} : { startedAt: now }),
-          emittedBy: params.emittedBy,
-        })
-      }
-
-      nextFailureCount = 0
-      message =
-        params.input.status === 'completed' ? `Completed task "${task.title}".` : `Skipped task "${task.title}".`
-    } else {
-      nextFailureCount = activePlan.failureCount + 1
-      nextResultStatus =
-        params.input.status === 'failed'
-          ? 'failed'
-          : (params.input.resultStatus ?? (params.input.outputSummary?.trim() ? 'partial' : task.resultStatus))
-      nextPlan = await this.updatePlanStatus({
-        plan: activePlan,
-        status: 'blocked',
-        currentTaskId: task.id,
-        restartFromTaskId: task.id,
-        failureCount: nextFailureCount,
-        emittedBy: params.emittedBy,
-      })
-      if (params.input.status === 'failed') {
-        taskCompletedAt = now
-      }
-      message = params.input.status === 'failed' ? `Task "${task.title}" failed.` : `Task "${task.title}" is blocked.`
-    }
-
-    const updatedTask = await this.updateTaskRecord({
-      task,
-      status: params.input.status,
-      resultStatus: nextResultStatus,
-      ...(params.input.outputSummary !== undefined ? { outputSummary: params.input.outputSummary || null } : {}),
-      ...(params.input.blockedReason !== undefined ? { blockedReason: params.input.blockedReason || null } : {}),
-      ...(params.input.externalRef !== undefined ? { externalRef: params.input.externalRef || null } : {}),
-      ...(params.input.status === 'in-progress' && taskStartedAt ? { startedAt: taskStartedAt } : {}),
-      ...(taskCompletedAt !== undefined ? { completedAt: taskCompletedAt } : {}),
-    })
-
-    const eventType =
-      params.input.status === 'in-progress'
-        ? 'task-started'
-        : params.input.status === 'completed'
-          ? 'task-completed'
-          : params.input.status === 'blocked'
-            ? 'task-blocked'
-            : params.input.status === 'failed'
-              ? 'task-failed'
-              : 'task-skipped'
-
-    await this.emitEvent({
-      planId: nextPlan.id,
-      taskId: updatedTask.id,
-      eventType,
-      fromStatus: task.status,
-      toStatus: updatedTask.status,
-      message,
-      detail: {
-        resultStatus: updatedTask.resultStatus,
-        outputSummary: updatedTask.outputSummary,
-        blockedReason: updatedTask.blockedReason,
-        externalRef: updatedTask.externalRef,
-        failureCount: nextFailureCount,
-      },
+    return await planExecutorService.resumeRun({
+      workstreamId: params.workstreamId,
+      runId: params.input.runId,
       emittedBy: params.emittedBy,
     })
+  }
 
-    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
-    return this.buildToolResult({
-      action: 'task-status-updated',
-      plan: serializable,
-      message:
-        nextFailureCount >= 2 && nextPlan.status === 'blocked'
-          ? `${message} Failure budget reached; the plan is paused until it is restarted or replaced.`
-          : message,
-      changedTaskId: recordIdToString(updatedTask.id, TABLES.PLAN_TASK),
+  async applyApprovalResponseFromMessages(params: {
+    workstreamId: RecordIdInput
+    approvalMessages: ChatMessage[]
+    respondedBy: string
+  }): Promise<SerializableExecutionPlan | null> {
+    const approvalResponse = buildApprovalResponseFromMessages(params.approvalMessages)
+    if (!approvalResponse) return null
+
+    return await planExecutorService.submitHumanNodeResponse({
+      workstreamId: params.workstreamId,
+      approvalId: approvalResponse.approvalId,
+      respondedBy: params.respondedBy,
+      response: approvalResponse.response,
     })
   }
 
-  async restartTask(params: {
+  async respondToApproval(params: {
     workstreamId: RecordIdInput
     emittedBy: string
-    input: RestartExecutionTaskArgs
-  }): Promise<ExecutionPlanToolResultData> {
-    const activePlan = await this.getActivePlanRecord(params.workstreamId)
-    if (!activePlan) {
-      throw new Error('No active execution plan exists for this workstream.')
-    }
-    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
-      throw new Error('Only the active execution plan can restart tasks.')
-    }
+    input: { approvalId: string; response: Record<string, unknown>; approvalMessageId?: string }
+  }): Promise<SerializableExecutionPlan | null> {
+    return await planExecutorService.submitHumanNodeResponse({
+      workstreamId: params.workstreamId,
+      approvalId: params.input.approvalId,
+      respondedBy: params.emittedBy,
+      response: params.input.response,
+      approvalMessageId: params.input.approvalMessageId,
+    })
+  }
 
-    const tasks = await this.listPlanTasks(activePlan.id)
-    const targetTask = tasks.find((task) => recordIdToString(task.id, TABLES.PLAN_TASK) === params.input.taskId)
-    if (!targetTask) {
-      throw new Error('Execution plan task not found for restart.')
+  async applyHumanInputFromUserMessage(params: {
+    workstreamId: RecordIdInput
+    message: ChatMessage
+    respondedBy: string
+  }): Promise<SerializableExecutionPlan | null> {
+    const run = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (!run || run.status !== 'awaiting-human' || !run.waitingNodeId) return null
+
+    const nodeSpec = await planRunService.getNodeSpecByNodeId(run.planSpecId, run.waitingNodeId)
+    if (nodeSpec.type === 'human-approval') {
+      return null
     }
-    if (targetTask.status !== 'blocked' && targetTask.status !== 'failed') {
-      throw new Error('Only blocked or failed execution tasks can be restarted.')
+    if (
+      nodeSpec.type !== 'human-input' &&
+      nodeSpec.type !== 'human-review-edit' &&
+      nodeSpec.type !== 'human-decision'
+    ) {
+      return null
     }
 
-    for (const task of tasks) {
-      const shouldReset =
-        recordIdToString(task.id, TABLES.PLAN_TASK) === params.input.taskId ||
-        (params.input.resetDownstream && task.position > targetTask.position)
-
-      if (!shouldReset) continue
-
-      const nextStatus: ExecutionPlanTaskStatus = 'pending'
-      await this.updateTaskRecord({
-        task,
-        status: nextStatus,
-        resultStatus: 'not-started',
-        outputSummary: null,
-        blockedReason: null,
-        externalRef: null,
-        startedAt: null,
-        completedAt: null,
-      })
+    const response = {
+      responseText: extractMessageText(params.message).trim(),
+      messageId: params.message.id,
+      approved: nodeSpec.type === 'human-decision' ? true : undefined,
+    } satisfies Record<string, unknown>
+
+    return await planExecutorService.submitHumanNodeResponse({
+      workstreamId: params.workstreamId,
+      respondedBy: params.respondedBy,
+      response,
+      approvalMessageId: params.message.id,
+    })
+  }
+
+  private async createNodeSpecs(
+    tx: DatabaseTransaction,
+    planSpecId: RecordIdInput,
+    nodes: CompiledPlanNode[],
+  ): Promise<PlanNodeSpecRecord[]> {
+    const createdRecords: PlanNodeSpecRecord[] = []
+
+    for (const compiledNode of nodes) {
+      const nodeSpecId = new RecordId(TABLES.PLAN_NODE_SPEC, Bun.randomUUIDv7())
+      const created = await tx
+        .create(nodeSpecId)
+        .content({
+          planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC),
+          nodeId: compiledNode.node.id,
+          position: compiledNode.position,
+          type: compiledNode.node.type,
+          label: compiledNode.node.label,
+          owner: compiledNode.node.owner,
+          objective: compiledNode.node.objective,
+          instructions: compiledNode.node.instructions,
+          ...(compiledNode.node.inputSchemaRef ? { inputSchemaRef: compiledNode.node.inputSchemaRef } : {}),
+          ...(compiledNode.node.outputSchemaRef ? { outputSchemaRef: compiledNode.node.outputSchemaRef } : {}),
+          deliverables: [...compiledNode.node.deliverables],
+          successCriteria: [...compiledNode.node.successCriteria],
+          completionChecks: [...compiledNode.node.completionChecks],
+          retryPolicy: { ...compiledNode.node.retryPolicy, retryOn: [...compiledNode.node.retryPolicy.retryOn] },
+          failurePolicy: [...compiledNode.node.failurePolicy],
+          ...(compiledNode.node.timeoutMs ? { timeoutMs: compiledNode.node.timeoutMs } : {}),
+          toolPolicy: { allow: [...compiledNode.node.toolPolicy.allow], deny: [...compiledNode.node.toolPolicy.deny] },
+          contextPolicy: {
+            retrievalScopes: [...compiledNode.node.contextPolicy.retrievalScopes],
+            attachmentPolicy: compiledNode.node.contextPolicy.attachmentPolicy,
+            webPolicy: compiledNode.node.contextPolicy.webPolicy,
+          },
+          upstreamNodeIds: [...compiledNode.upstreamNodeIds],
+          downstreamNodeIds: [...compiledNode.downstreamNodeIds],
+        })
+        .output('after')
+
+      createdRecords.push(PlanNodeSpecRecordSchema.parse(created))
     }
 
-    const nextPlan = await this.updatePlanStatus({
-      plan: activePlan,
-      status: 'executing',
-      currentTaskId: targetTask.id,
-      restartFromTaskId: targetTask.id,
-      failureCount: 0,
-      completedAt: null,
-      ...(activePlan.startedAt ? {} : { startedAt: new Date() }),
-      emittedBy: params.emittedBy,
-    })
+    return createdRecords
+  }
 
-    await this.emitEvent({
-      planId: nextPlan.id,
-      taskId: targetTask.id,
-      eventType: 'task-restarted',
-      fromStatus: targetTask.status,
-      toStatus: 'pending',
-      message: `Restarted task "${targetTask.title}".`,
-      detail: { resetDownstream: params.input.resetDownstream },
-      emittedBy: params.emittedBy,
-    })
+  private async createNodeRuns(
+    tx: DatabaseTransaction,
+    runId: RecordIdInput,
+    planSpecId: RecordIdInput,
+    nodeSpecs: PlanNodeSpecRecord[],
+  ): Promise<PlanNodeRunRecord[]> {
+    const createdNodeRuns: PlanNodeRunRecord[] = []
+    for (const nodeSpec of nodeSpecs) {
+      const nodeRunId = new RecordId(TABLES.PLAN_NODE_RUN, Bun.randomUUIDv7())
+      const created = await tx
+        .create(nodeRunId)
+        .content({
+          runId: ensureRecordId(runId, TABLES.PLAN_RUN),
+          planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC),
+          nodeId: nodeSpec.nodeId,
+          status: 'pending',
+          attemptCount: 0,
+          retryCount: 0,
+        })
+        .output('after')
 
-    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
-    return this.buildToolResult({
-      action: 'task-restarted',
-      plan: serializable,
-      changedTaskId: recordIdToString(targetTask.id, TABLES.PLAN_TASK),
-      message: `Restarted task "${targetTask.title}".`,
-    })
+      createdNodeRuns.push(PlanNodeRunSchema.parse(created))
+    }
+
+    return createdNodeRuns
   }
 }