@lota-sdk/core 0.1.9 → 0.1.12

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

@@ -0,0 +1,1624 @@
+import type {
+  ExecutionPlanToolResultData,
+  PlanEventRecord,
+  PlanEventType,
+  PlanFailureAction,
+  PlanFailureClass,
+  PlanNodeResultSubmission,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+  PlanSpecRecord,
+  PlanValidationIssueRecord,
+  SerializableExecutionPlan,
+} from '@lota-sdk/shared'
+import {
+  PlanEventSchema,
+  PlanNodeAttemptSchema,
+  PlanNodeRunSchema,
+  PlanRunSchema,
+  PlanValidationIssueSchema,
+} from '@lota-sdk/shared'
+import { RecordId } from 'surrealdb'
+
+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 { planApprovalService } from './plan-approval.service'
+import { planArtifactService } from './plan-artifact.service'
+import { planCheckpointService } from './plan-checkpoint.service'
+import { planRunService } from './plan-run.service'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+import { planValidatorService } from './plan-validator.service'
+
+const SUCCESSFUL_TERMINAL_NODE_STATUSES = new Set(['completed', 'partial', 'skipped'])
+const HUMAN_NODE_TYPES = new Set(['human-input', 'human-approval', 'human-review-edit', 'human-decision'])
+const STRUCTURAL_NODE_TYPES = new Set(['switch', 'join'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function readPathValue(source: unknown, path: string): unknown {
+  if (!path.trim()) return source
+
+  let current: unknown = source
+  for (const segment of path
+    .split('.')
+    .map((part) => part.trim())
+    .filter(Boolean)) {
+    if (!isRecord(current)) return undefined
+    current = current[segment]
+  }
+  return current
+}
+
+function setPathValue(target: Record<string, unknown>, path: string, value: unknown) {
+  const segments = path
+    .split('.')
+    .map((part) => part.trim())
+    .filter(Boolean)
+  if (segments.length === 0) return
+  const lastSegment = segments.at(-1)
+  if (!lastSegment) return
+
+  let current: Record<string, unknown> = target
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment]
+    if (!isRecord(next)) {
+      current[segment] = {}
+    }
+    current = current[segment] as Record<string, unknown>
+  }
+  current[lastSegment] = value
+}
+
+function parseLiteralValue(raw: string): unknown {
+  const trimmed = raw.trim()
+  if (!trimmed.length) return undefined
+  if (trimmed === 'true') return true
+  if (trimmed === 'false') return false
+  if (trimmed === 'null') return null
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed)
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('`') && trimmed.endsWith('`'))
+  ) {
+    return trimmed.slice(1, -1)
+  }
+
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    return trimmed
+  }
+}
+
+function buildArtifactContext(
+  artifacts: Array<{ name: string; kind: string; pointer: string; schemaRef?: string; payload?: unknown }>,
+) {
+  return Object.fromEntries(
+    artifacts.map((artifact) => [
+      artifact.name,
+      { kind: artifact.kind, pointer: artifact.pointer, schemaRef: artifact.schemaRef, payload: artifact.payload },
+    ]),
+  )
+}
+
+function buildNodeContext(params: {
+  nodeRun: PlanNodeRunRecord | undefined
+  artifacts: Array<{ name: string; kind: string; pointer: string; schemaRef?: string; payload?: unknown }>
+}) {
+  return {
+    input: params.nodeRun?.resolvedInput ?? {},
+    output: params.nodeRun?.latestStructuredOutput ?? {},
+    artifact: buildArtifactContext(params.artifacts),
+  }
+}
+
+function evaluateCondition(expression: string | undefined, context: Record<string, unknown>): boolean {
+  if (!expression?.trim()) return true
+  const normalized = expression.trim()
+  if (normalized === 'always') return true
+
+  const match = normalized.match(/^([a-zA-Z0-9_.]+)\s*(==|!=|>=|<=|>|<)\s*(.+)$/)
+  if (!match) {
+    return Boolean(readPathValue(context, normalized))
+  }
+
+  const [, leftPath, operator, rawRightValue] = match
+  const left = readPathValue(context, leftPath)
+  const right = parseLiteralValue(rawRightValue)
+
+  if (operator === '==') return Object.is(left, right)
+  if (operator === '!=') return !Object.is(left, right)
+  if (typeof left !== 'number' || typeof right !== 'number') return false
+  if (operator === '>=') return left >= right
+  if (operator === '<=') return left <= right
+  if (operator === '>') return left > right
+  return left < right
+}
+
+function isSuccessfulTerminalStatus(status: string): boolean {
+  return SUCCESSFUL_TERMINAL_NODE_STATUSES.has(status)
+}
+
+function isHumanNodeType(type: string): boolean {
+  return HUMAN_NODE_TYPES.has(type)
+}
+
+function isStructuralNodeType(type: string): boolean {
+  return STRUCTURAL_NODE_TYPES.has(type)
+}
+
+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
+}
+
+type PlanNodeRunUpdate = Omit<
+  Partial<PlanNodeRunRecord>,
+  | 'blockedReason'
+  | 'failureClass'
+  | 'resolvedInput'
+  | 'latestStructuredOutput'
+  | 'latestNotes'
+  | 'latestAttemptId'
+  | 'readyAt'
+  | 'startedAt'
+  | 'completedAt'
+> & {
+  blockedReason?: string | null
+  failureClass?: PlanFailureClass | null
+  resolvedInput?: Record<string, unknown> | null
+  latestStructuredOutput?: Record<string, unknown> | null
+  latestNotes?: string | null
+  latestAttemptId?: RecordIdInput | null
+  readyAt?: Date | null
+  startedAt?: Date | null
+  completedAt?: Date | null
+}
+
+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 }
+          : {}),
+  }
+}
+
+function toNodeRunData(nodeRun: PlanNodeRunRecord, patch: PlanNodeRunUpdate) {
+  return {
+    runId: ensureRecordId(nodeRun.runId, TABLES.PLAN_RUN),
+    planSpecId: ensureRecordId(nodeRun.planSpecId, TABLES.PLAN_SPEC),
+    nodeId: nodeRun.nodeId,
+    status: patch.status ?? nodeRun.status,
+    attemptCount: patch.attemptCount ?? nodeRun.attemptCount,
+    retryCount: patch.retryCount ?? nodeRun.retryCount,
+    ...(patch.resolvedInput === null
+      ? {}
+      : patch.resolvedInput !== undefined
+        ? { resolvedInput: patch.resolvedInput }
+        : nodeRun.resolvedInput
+          ? { resolvedInput: nodeRun.resolvedInput }
+          : {}),
+    ...(patch.latestStructuredOutput === null
+      ? {}
+      : patch.latestStructuredOutput !== undefined
+        ? { latestStructuredOutput: patch.latestStructuredOutput }
+        : nodeRun.latestStructuredOutput
+          ? { latestStructuredOutput: nodeRun.latestStructuredOutput }
+          : {}),
+    ...(patch.latestNotes === null
+      ? {}
+      : patch.latestNotes !== undefined
+        ? { latestNotes: patch.latestNotes }
+        : nodeRun.latestNotes
+          ? { latestNotes: nodeRun.latestNotes }
+          : {}),
+    ...(patch.latestAttemptId === null
+      ? {}
+      : patch.latestAttemptId !== undefined
+        ? { latestAttemptId: ensureRecordId(patch.latestAttemptId, TABLES.PLAN_NODE_ATTEMPT) }
+        : nodeRun.latestAttemptId
+          ? { latestAttemptId: ensureRecordId(nodeRun.latestAttemptId, TABLES.PLAN_NODE_ATTEMPT) }
+          : {}),
+    ...(patch.blockedReason === null
+      ? {}
+      : patch.blockedReason !== undefined
+        ? { blockedReason: patch.blockedReason }
+        : nodeRun.blockedReason
+          ? { blockedReason: nodeRun.blockedReason }
+          : {}),
+    ...(patch.failureClass === null
+      ? {}
+      : patch.failureClass !== undefined
+        ? { failureClass: patch.failureClass }
+        : nodeRun.failureClass
+          ? { failureClass: nodeRun.failureClass }
+          : {}),
+    ...(patch.readyAt === null
+      ? {}
+      : patch.readyAt !== undefined
+        ? { readyAt: patch.readyAt }
+        : nodeRun.readyAt
+          ? { readyAt: nodeRun.readyAt }
+          : {}),
+    ...(patch.startedAt === null
+      ? {}
+      : patch.startedAt !== undefined
+        ? { startedAt: patch.startedAt }
+        : nodeRun.startedAt
+          ? { startedAt: nodeRun.startedAt }
+          : {}),
+    ...(patch.completedAt === null
+      ? {}
+      : patch.completedAt !== undefined
+        ? { completedAt: patch.completedAt }
+        : nodeRun.completedAt
+          ? { completedAt: nodeRun.completedAt }
+          : {}),
+  }
+}
+
+function buildToolResult(params: {
+  action: ExecutionPlanToolResultData['action']
+  plan: SerializableExecutionPlan | null
+  message: string
+  changedNodeId?: string
+}): ExecutionPlanToolResultData {
+  return {
+    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 deriveApprovalStatus(response: Record<string, unknown>): 'approved' | 'rejected' | 'changes-requested' {
+  const approved = response.approved === true
+  const requiredEdits = Array.isArray(response.requiredEdits)
+    ? response.requiredEdits.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+    : []
+
+  if (approved && requiredEdits.length === 0) return 'approved'
+  if (requiredEdits.length > 0) return 'changes-requested'
+  return 'rejected'
+}
+
+class PlanExecutorService {
+  async submitNodeResult(params: {
+    workstreamId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    result: PlanNodeResultSubmission
+  }): Promise<ExecutionPlanToolResultData> {
+    const run = await planRunService.getRunById(params.runId)
+    if (
+      recordIdToString(run.workstreamId, TABLES.WORKSTREAM) !== recordIdToString(params.workstreamId, TABLES.WORKSTREAM)
+    ) {
+      throw new Error('Execution node result targets a different workstream.')
+    }
+    if (run.status === 'completed' || run.status === 'failed' || run.status === 'aborted') {
+      throw new Error('Execution run is no longer active.')
+    }
+
+    const spec = await planRunService.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = await planRunService.listNodeSpecs(spec.id)
+    const nodeSpec = nodeSpecs.find((candidate) => candidate.nodeId === params.nodeId)
+    if (!nodeSpec) {
+      throw new Error(`Execution node "${params.nodeId}" does not exist in this run.`)
+    }
+    if (isHumanNodeType(nodeSpec.type) || isStructuralNodeType(nodeSpec.type)) {
+      throw new Error(
+        `Execution node "${nodeSpec.label}" is executor-owned and cannot accept direct result submission.`,
+      )
+    }
+
+    const nodeRun = await planRunService.getNodeRunByNodeId(run.id, params.nodeId)
+    if (nodeRun.status !== 'running') {
+      throw new Error(`Execution node "${nodeSpec.label}" is not currently running.`)
+    }
+
+    const existingArtifacts = await planRunService.listArtifacts(run.id)
+    const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+    const validation = planValidatorService.validateNodeResult({
+      draft: { schemas: spec.schemaRegistry },
+      node: {
+        id: nodeSpec.nodeId,
+        type: nodeSpec.type,
+        label: nodeSpec.label,
+        owner: nodeSpec.owner,
+        objective: nodeSpec.objective,
+        instructions: nodeSpec.instructions,
+        inputSchemaRef: nodeSpec.inputSchemaRef,
+        outputSchemaRef: nodeSpec.outputSchemaRef,
+        deliverables: [...nodeSpec.deliverables],
+        successCriteria: [...nodeSpec.successCriteria],
+        completionChecks: [...nodeSpec.completionChecks],
+        retryPolicy: { ...nodeSpec.retryPolicy, retryOn: [...nodeSpec.retryPolicy.retryOn] },
+        failurePolicy: [...nodeSpec.failurePolicy],
+        timeoutMs: nodeSpec.timeoutMs,
+        toolPolicy: { allow: [...nodeSpec.toolPolicy.allow], deny: [...nodeSpec.toolPolicy.deny] },
+        contextPolicy: {
+          retrievalScopes: [...nodeSpec.contextPolicy.retrievalScopes],
+          attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
+          webPolicy: nodeSpec.contextPolicy.webPolicy,
+        },
+      },
+      result: params.result,
+    })
+
+    await databaseService.withTransaction(async (tx) => {
+      const attempt = await this.createAttempt({
+        tx,
+        run,
+        nodeRun,
+        emittedBy: params.emittedBy,
+        result: params.result,
+        status: validation.blocking.length > 0 ? 'failed' : 'completed',
+        failureClass: validation.failureClass,
+      })
+
+      const issues = await this.persistValidationIssues({
+        tx,
+        run,
+        spec,
+        attemptId: attempt.id,
+        nodeId: params.nodeId,
+        issues: [...validation.blocking, ...validation.warnings],
+      })
+
+      const finalizedAttempt = PlanNodeAttemptSchema.parse(
+        await tx
+          .update(ensureRecordId(attempt.id, TABLES.PLAN_NODE_ATTEMPT))
+          .content({
+            runId: ensureRecordId(attempt.runId, TABLES.PLAN_RUN),
+            nodeRunId: ensureRecordId(attempt.nodeRunId, TABLES.PLAN_NODE_RUN),
+            nodeId: attempt.nodeId,
+            emittedBy: attempt.emittedBy,
+            status: attempt.status,
+            ...(attempt.structuredOutput ? { structuredOutput: attempt.structuredOutput } : {}),
+            ...(attempt.notes ? { notes: attempt.notes } : {}),
+            validationIssueIds: issues.map((issue) => ensureRecordId(issue.id, TABLES.PLAN_VALIDATION_ISSUE)),
+            ...(attempt.failureClass ? { failureClass: attempt.failureClass } : {}),
+          })
+          .output('after'),
+      )
+
+      const persistedArtifacts = await planArtifactService.persistArtifacts({
+        tx,
+        runId: run.id,
+        attemptId: finalizedAttempt.id,
+        nodeId: params.nodeId,
+        artifacts: params.result.artifacts,
+      })
+
+      let nextNodeRun = PlanNodeRunSchema.parse(
+        await tx
+          .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+          .content(
+            toNodeRunData(nodeRun, {
+              attemptCount: nodeRun.attemptCount + 1,
+              latestAttemptId: finalizedAttempt.id,
+              latestStructuredOutput: params.result.structuredOutput ?? null,
+              latestNotes: params.result.notes ?? null,
+            }),
+          )
+          .output('after'),
+      )
+
+      const nodeRuns = await planRunService.listNodeRuns(run.id)
+      const withUpdatedNodeRuns = nodeRuns.map((candidate) =>
+        candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+      )
+      const nextArtifacts = [...existingArtifacts, ...persistedArtifacts]
+
+      if (validation.blocking.length > 0) {
+        const shouldRetry =
+          validation.failureClass &&
+          nodeSpec.retryPolicy.maxAttempts > nextNodeRun.retryCount &&
+          (nodeSpec.retryPolicy.retryOn.length === 0 || nodeSpec.retryPolicy.retryOn.includes(validation.failureClass))
+
+        if (shouldRetry) {
+          nextNodeRun = PlanNodeRunSchema.parse(
+            await tx
+              .update(ensureRecordId(nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(nextNodeRun, {
+                  status: 'ready',
+                  retryCount: nextNodeRun.retryCount + 1,
+                  failureClass: validation.failureClass,
+                  blockedReason: validation.blocking[0]?.message ?? null,
+                  readyAt: new Date(),
+                  startedAt: null,
+                  completedAt: null,
+                }),
+              )
+              .output('after'),
+          )
+
+          await this.emitEvent({
+            tx,
+            run,
+            spec,
+            nodeId: nextNodeRun.nodeId,
+            attemptId: finalizedAttempt.id,
+            eventType: 'validation-reported',
+            message: `Validation failed for node "${nodeSpec.label}", scheduling retry.`,
+            detail: { issues: validation.blocking.map((issue) => issue.code) },
+            emittedBy: params.emittedBy,
+          })
+
+          const synced = await this.syncRunGraph({
+            tx,
+            run,
+            spec,
+            nodeSpecs,
+            nodeRuns: withUpdatedNodeRuns.map((candidate) =>
+              candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+            ),
+            artifacts: nextArtifacts,
+            emittedBy: params.emittedBy,
+          })
+
+          const checkpoint = await this.saveCheckpoint({
+            tx,
+            run: synced.run,
+            nodeRuns: synced.nodeRuns,
+            artifacts: synced.artifacts,
+            sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+            reason: 'node-result-retry',
+          })
+
+          await this.attachCheckpoint(tx, synced.run, checkpoint)
+          return
+        }
+
+        const failureAction = this.resolveFailureAction(nodeSpec, validation.failureClass)
+        if (failureAction === 'human-review') {
+          nextNodeRun = PlanNodeRunSchema.parse(
+            await tx
+              .update(ensureRecordId(nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(nextNodeRun, {
+                  status: 'awaiting-human',
+                  retryCount: nextNodeRun.retryCount + 1,
+                  failureClass: validation.failureClass,
+                  blockedReason: validation.blocking[0]?.message ?? null,
+                  startedAt: nextNodeRun.startedAt ?? new Date(),
+                }),
+              )
+              .output('after'),
+          )
+
+          const approval = await planApprovalService.createPendingApproval({
+            tx,
+            runId: run.id,
+            nodeRunId: nextNodeRun.id,
+            nodeId: nextNodeRun.nodeId,
+            requestedBy: params.emittedBy,
+            presented: {
+              nodeId: nodeSpec.nodeId,
+              label: nodeSpec.label,
+              objective: nodeSpec.objective,
+              instructions: nodeSpec.instructions,
+              validationIssues: validation.blocking,
+            },
+          })
+
+          const failedRun = await this.replaceRun(tx, run, {
+            status: 'awaiting-human',
+            currentNodeId: nextNodeRun.nodeId,
+            waitingNodeId: nextNodeRun.nodeId,
+            readyNodeIds: [],
+            failureCount: run.failureCount + 1,
+          })
+
+          await this.emitEvent({
+            tx,
+            run: failedRun,
+            spec,
+            nodeId: nextNodeRun.nodeId,
+            attemptId: finalizedAttempt.id,
+            approvalId: approval.id,
+            eventType: 'approval-requested',
+            fromStatus: run.status,
+            toStatus: failedRun.status,
+            message: `Node "${nodeSpec.label}" requires human review before continuing.`,
+            detail: { issues: validation.blocking.map((issue) => issue.code) },
+            emittedBy: params.emittedBy,
+          })
+
+          const checkpoint = await this.saveCheckpoint({
+            tx,
+            run: failedRun,
+            nodeRuns: withUpdatedNodeRuns.map((candidate) =>
+              candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+            ),
+            artifacts: nextArtifacts,
+            sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+            reason: 'node-result-human-review',
+          })
+
+          await this.attachCheckpoint(tx, failedRun, checkpoint)
+          return
+        }
+
+        if (failureAction === 'replan') {
+          nextNodeRun = PlanNodeRunSchema.parse(
+            await tx
+              .update(ensureRecordId(nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(nextNodeRun, {
+                  status: 'blocked',
+                  retryCount: nextNodeRun.retryCount + 1,
+                  failureClass: validation.failureClass,
+                  blockedReason: validation.blocking[0]?.message ?? null,
+                }),
+              )
+              .output('after'),
+          )
+
+          const blockedRun = await this.replaceRun(tx, run, {
+            status: 'blocked',
+            currentNodeId: nextNodeRun.nodeId,
+            waitingNodeId: null,
+            readyNodeIds: [],
+            failureCount: run.failureCount + 1,
+          })
+
+          await this.emitEvent({
+            tx,
+            run: blockedRun,
+            spec,
+            nodeId: nextNodeRun.nodeId,
+            attemptId: finalizedAttempt.id,
+            eventType: 'node-blocked',
+            fromStatus: nodeRun.status,
+            toStatus: nextNodeRun.status,
+            message: `Node "${nodeSpec.label}" failed validation and requires replanning.`,
+            detail: { failureClass: validation.failureClass, issues: validation.blocking.map((issue) => issue.code) },
+            emittedBy: params.emittedBy,
+          })
+
+          const checkpoint = await this.saveCheckpoint({
+            tx,
+            run: blockedRun,
+            nodeRuns: withUpdatedNodeRuns.map((candidate) =>
+              candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+            ),
+            artifacts: nextArtifacts,
+            sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+            reason: 'node-result-replan',
+          })
+
+          await this.attachCheckpoint(tx, blockedRun, checkpoint)
+          return
+        }
+
+        nextNodeRun = PlanNodeRunSchema.parse(
+          await tx
+            .update(ensureRecordId(nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(
+              toNodeRunData(nextNodeRun, {
+                status: 'failed',
+                retryCount: nextNodeRun.retryCount + 1,
+                failureClass: validation.failureClass,
+                blockedReason: validation.blocking[0]?.message ?? null,
+                completedAt: new Date(),
+              }),
+            )
+            .output('after'),
+        )
+
+        const failedRun = await this.replaceRun(tx, run, {
+          status: 'failed',
+          currentNodeId: null,
+          waitingNodeId: null,
+          readyNodeIds: [],
+          failureCount: run.failureCount + 1,
+          completedAt: new Date(),
+        })
+
+        await this.emitEvent({
+          tx,
+          run: failedRun,
+          spec,
+          nodeId: nextNodeRun.nodeId,
+          attemptId: finalizedAttempt.id,
+          eventType: 'node-failed',
+          fromStatus: nodeRun.status,
+          toStatus: nextNodeRun.status,
+          message: `Node "${nodeSpec.label}" failed validation and the run has been aborted.`,
+          detail: { failureClass: validation.failureClass, issues: validation.blocking.map((issue) => issue.code) },
+          emittedBy: params.emittedBy,
+        })
+
+        const checkpoint = await this.saveCheckpoint({
+          tx,
+          run: failedRun,
+          nodeRuns: withUpdatedNodeRuns.map((candidate) =>
+            candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+          ),
+          artifacts: nextArtifacts,
+          sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+          reason: 'node-result-failed',
+        })
+
+        await this.attachCheckpoint(tx, failedRun, checkpoint)
+        return
+      }
+
+      nextNodeRun = PlanNodeRunSchema.parse(
+        await tx
+          .update(ensureRecordId(nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+          .content(
+            toNodeRunData(nextNodeRun, {
+              status: validation.warnings.length > 0 ? 'partial' : 'completed',
+              latestAttemptId: finalizedAttempt.id,
+              latestStructuredOutput: params.result.structuredOutput ?? null,
+              latestNotes: params.result.notes ?? null,
+              blockedReason: null,
+              failureClass: null,
+              completedAt: new Date(),
+            }),
+          )
+          .output('after'),
+      )
+
+      await this.emitEvent({
+        tx,
+        run,
+        spec,
+        nodeId: nextNodeRun.nodeId,
+        attemptId: finalizedAttempt.id,
+        eventType: validation.warnings.length > 0 ? 'node-partial' : 'node-completed',
+        fromStatus: nodeRun.status,
+        toStatus: nextNodeRun.status,
+        message:
+          validation.warnings.length > 0
+            ? `Node "${nodeSpec.label}" completed with warnings.`
+            : `Node "${nodeSpec.label}" completed successfully.`,
+        detail: { warningCount: validation.warnings.length },
+        emittedBy: params.emittedBy,
+      })
+
+      const synced = await this.syncRunGraph({
+        tx,
+        run,
+        spec,
+        nodeSpecs,
+        nodeRuns: withUpdatedNodeRuns.map((candidate) =>
+          candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+        ),
+        artifacts: nextArtifacts,
+        emittedBy: params.emittedBy,
+      })
+
+      const checkpoint = await this.saveCheckpoint({
+        tx,
+        run: synced.run,
+        nodeRuns: synced.nodeRuns,
+        artifacts: synced.artifacts,
+        sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+        reason: 'node-result-complete',
+      })
+
+      await this.attachCheckpoint(tx, synced.run, checkpoint)
+    })
+
+    const snapshot = await planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
+    })
+
+    return buildToolResult({
+      action: 'node-result-submitted',
+      plan: snapshot,
+      message: `Submitted result for node "${nodeSpec.label}".`,
+      changedNodeId: params.nodeId,
+    })
+  }
+
+  async submitHumanNodeResponse(params: {
+    workstreamId: RecordIdInput
+    approvalId?: string
+    respondedBy: string
+    response: Record<string, unknown>
+    approvalMessageId?: string
+  }): Promise<SerializableExecutionPlan | null> {
+    const run = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (!run || run.status !== 'awaiting-human' || !run.waitingNodeId) {
+      return null
+    }
+
+    const spec = await planRunService.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = await planRunService.listNodeSpecs(spec.id)
+    const nodeSpec = nodeSpecs.find((candidate) => candidate.nodeId === run.waitingNodeId)
+    if (!nodeSpec) {
+      throw new Error(`Waiting node "${run.waitingNodeId}" does not exist.`)
+    }
+
+    const nodeRun = await planRunService.getNodeRunByNodeId(run.id, run.waitingNodeId)
+    const approval =
+      (params.approvalId ? await planApprovalService.getApprovalById(params.approvalId) : null) ??
+      (await planApprovalService.getPendingApprovalForNodeRun(nodeRun.id))
+    if (!approval) {
+      throw new Error(`No pending approval exists for node "${nodeSpec.label}".`)
+    }
+
+    const existingArtifacts = await planRunService.listArtifacts(run.id)
+    const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+    const validation = planValidatorService.validateNodeResult({
+      draft: { schemas: spec.schemaRegistry },
+      node: {
+        id: nodeSpec.nodeId,
+        type: nodeSpec.type,
+        label: nodeSpec.label,
+        owner: nodeSpec.owner,
+        objective: nodeSpec.objective,
+        instructions: nodeSpec.instructions,
+        inputSchemaRef: nodeSpec.inputSchemaRef,
+        outputSchemaRef: nodeSpec.outputSchemaRef,
+        deliverables: [...nodeSpec.deliverables],
+        successCriteria: [...nodeSpec.successCriteria],
+        completionChecks: [...nodeSpec.completionChecks],
+        retryPolicy: { ...nodeSpec.retryPolicy, retryOn: [...nodeSpec.retryPolicy.retryOn] },
+        failurePolicy: [...nodeSpec.failurePolicy],
+        timeoutMs: nodeSpec.timeoutMs,
+        toolPolicy: { allow: [...nodeSpec.toolPolicy.allow], deny: [...nodeSpec.toolPolicy.deny] },
+        contextPolicy: {
+          retrievalScopes: [...nodeSpec.contextPolicy.retrievalScopes],
+          attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
+          webPolicy: nodeSpec.contextPolicy.webPolicy,
+        },
+      },
+      result: {
+        structuredOutput: params.response,
+        artifacts: [],
+        notes: typeof params.response.comments === 'string' ? params.response.comments : undefined,
+      },
+    })
+
+    await databaseService.withTransaction(async (tx) => {
+      const approvalStatus = deriveApprovalStatus(params.response)
+      await planApprovalService.updateApprovalResponse({
+        tx,
+        approval,
+        status: approvalStatus,
+        response: params.response,
+        respondedBy: params.respondedBy,
+        approvalMessageId: params.approvalMessageId,
+        comments: typeof params.response.comments === 'string' ? params.response.comments : undefined,
+        requiredEdits: Array.isArray(params.response.requiredEdits)
+          ? params.response.requiredEdits.filter((entry): entry is string => typeof entry === 'string')
+          : undefined,
+      })
+
+      const attempt = await this.createAttempt({
+        tx,
+        run,
+        nodeRun,
+        emittedBy: params.respondedBy,
+        result: {
+          structuredOutput: params.response,
+          artifacts: [],
+          notes: typeof params.response.comments === 'string' ? params.response.comments : undefined,
+        },
+        status: validation.blocking.length > 0 ? 'failed' : 'completed',
+        failureClass: validation.failureClass,
+      })
+
+      const issues = await this.persistValidationIssues({
+        tx,
+        run,
+        spec,
+        attemptId: attempt.id,
+        nodeId: nodeRun.nodeId,
+        issues: [...validation.blocking, ...validation.warnings],
+      })
+
+      await tx
+        .update(ensureRecordId(attempt.id, TABLES.PLAN_NODE_ATTEMPT))
+        .content({
+          runId: ensureRecordId(attempt.runId, TABLES.PLAN_RUN),
+          nodeRunId: ensureRecordId(attempt.nodeRunId, TABLES.PLAN_NODE_RUN),
+          nodeId: attempt.nodeId,
+          emittedBy: attempt.emittedBy,
+          status: attempt.status,
+          structuredOutput: params.response,
+          validationIssueIds: issues.map((issue) => ensureRecordId(issue.id, TABLES.PLAN_VALIDATION_ISSUE)),
+          ...(attempt.notes ? { notes: attempt.notes } : {}),
+          ...(attempt.failureClass ? { failureClass: attempt.failureClass } : {}),
+        })
+        .output('after')
+
+      const nextNodeRun =
+        validation.blocking.length > 0
+          ? PlanNodeRunSchema.parse(
+              await tx
+                .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+                .content(
+                  toNodeRunData(nodeRun, {
+                    status: 'blocked',
+                    attemptCount: nodeRun.attemptCount + 1,
+                    latestAttemptId: attempt.id,
+                    latestStructuredOutput: params.response,
+                    latestNotes: typeof params.response.comments === 'string' ? params.response.comments : null,
+                    blockedReason: validation.blocking[0]?.message ?? null,
+                    failureClass: validation.failureClass,
+                  }),
+                )
+                .output('after'),
+            )
+          : PlanNodeRunSchema.parse(
+              await tx
+                .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+                .content(
+                  toNodeRunData(nodeRun, {
+                    status: 'completed',
+                    attemptCount: nodeRun.attemptCount + 1,
+                    latestAttemptId: attempt.id,
+                    latestStructuredOutput: params.response,
+                    latestNotes: typeof params.response.comments === 'string' ? params.response.comments : null,
+                    blockedReason: null,
+                    failureClass: null,
+                    completedAt: new Date(),
+                  }),
+                )
+                .output('after'),
+            )
+
+      const nodeRuns = (await planRunService.listNodeRuns(run.id)).map((candidate) =>
+        candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+      )
+
+      if (validation.blocking.length > 0) {
+        const blockedRun = await this.replaceRun(tx, run, {
+          status: 'blocked',
+          currentNodeId: nextNodeRun.nodeId,
+          waitingNodeId: null,
+          readyNodeIds: [],
+          failureCount: run.failureCount + 1,
+        })
+
+        await this.emitEvent({
+          tx,
+          run: blockedRun,
+          spec,
+          nodeId: nextNodeRun.nodeId,
+          attemptId: attempt.id,
+          approvalId: approval.id,
+          eventType: 'approval-resolved',
+          fromStatus: run.status,
+          toStatus: blockedRun.status,
+          message: `Human response for node "${nodeSpec.label}" blocked execution.`,
+          detail: { issues: validation.blocking.map((issue) => issue.code) },
+          emittedBy: params.respondedBy,
+        })
+
+        const checkpoint = await this.saveCheckpoint({
+          tx,
+          run: blockedRun,
+          nodeRuns,
+          artifacts: existingArtifacts,
+          sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+          reason: 'human-response-blocked',
+        })
+        await this.attachCheckpoint(tx, blockedRun, checkpoint)
+        return
+      }
+
+      const synced = await this.syncRunGraph({
+        tx,
+        run,
+        spec,
+        nodeSpecs,
+        nodeRuns,
+        artifacts: existingArtifacts,
+        emittedBy: params.respondedBy,
+      })
+
+      await this.emitEvent({
+        tx,
+        run: synced.run,
+        spec,
+        nodeId: nextNodeRun.nodeId,
+        attemptId: attempt.id,
+        approvalId: approval.id,
+        eventType: 'approval-resolved',
+        fromStatus: run.status,
+        toStatus: synced.run.status,
+        message: `Human response for node "${nodeSpec.label}" accepted.`,
+        detail: { approvalStatus: approvalStatus },
+        emittedBy: params.respondedBy,
+      })
+
+      const checkpoint = await this.saveCheckpoint({
+        tx,
+        run: synced.run,
+        nodeRuns: synced.nodeRuns,
+        artifacts: synced.artifacts,
+        sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+        reason: 'human-response-complete',
+      })
+      await this.attachCheckpoint(tx, synced.run, checkpoint)
+    })
+
+    return await planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
+    })
+  }
+
+  async resumeRun(params: {
+    workstreamId: RecordIdInput
+    runId: string
+    emittedBy: string
+  }): Promise<ExecutionPlanToolResultData> {
+    const run = await planRunService.getRunById(params.runId)
+    if (
+      recordIdToString(run.workstreamId, TABLES.WORKSTREAM) !== recordIdToString(params.workstreamId, TABLES.WORKSTREAM)
+    ) {
+      throw new Error('Execution run belongs to a different workstream.')
+    }
+
+    const spec = await planRunService.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = await planRunService.listNodeSpecs(spec.id)
+    const nodeRuns = await planRunService.listNodeRuns(run.id)
+    const artifacts = await planRunService.listArtifacts(run.id)
+    const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+
+    await databaseService.withTransaction(async (tx) => {
+      let currentNodeRuns = [...nodeRuns]
+      for (const nodeRun of currentNodeRuns.filter((candidate) => candidate.status === 'running')) {
+        const resetNodeRun = PlanNodeRunSchema.parse(
+          await tx
+            .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(
+              toNodeRunData(nodeRun, {
+                status: 'ready',
+                readyAt: new Date(),
+                startedAt: nodeRun.startedAt ?? new Date(),
+              }),
+            )
+            .output('after'),
+        )
+        currentNodeRuns = currentNodeRuns.map((candidate) =>
+          candidate.nodeId === resetNodeRun.nodeId ? resetNodeRun : candidate,
+        )
+      }
+
+      const resetRun = await this.replaceRun(tx, run, {
+        status: run.status === 'awaiting-human' ? 'awaiting-human' : 'running',
+        currentNodeId: run.status === 'awaiting-human' ? (run.currentNodeId ?? null) : null,
+        waitingNodeId: run.status === 'awaiting-human' ? (run.waitingNodeId ?? null) : null,
+        readyNodeIds: currentNodeRuns
+          .filter((candidate) => candidate.status === 'ready')
+          .map((candidate) => candidate.nodeId),
+      })
+
+      await this.emitEvent({
+        tx,
+        run: resetRun,
+        spec,
+        eventType: 'run-resumed',
+        fromStatus: run.status,
+        toStatus: resetRun.status,
+        message: `Run "${spec.title}" resumed from the latest checkpoint.`,
+        detail: latestCheckpoint ? { checkpointId: recordIdToString(latestCheckpoint.id, TABLES.PLAN_CHECKPOINT) } : {},
+        emittedBy: params.emittedBy,
+      })
+
+      const synced =
+        resetRun.status === 'awaiting-human'
+          ? { run: resetRun, nodeRuns: currentNodeRuns, artifacts }
+          : await this.syncRunGraph({
+              tx,
+              run: resetRun,
+              spec,
+              nodeSpecs,
+              nodeRuns: currentNodeRuns,
+              artifacts,
+              emittedBy: params.emittedBy,
+            })
+
+      const checkpoint = await this.saveCheckpoint({
+        tx,
+        run: synced.run,
+        nodeRuns: synced.nodeRuns,
+        artifacts: synced.artifacts,
+        sequence: (latestCheckpoint?.sequence ?? 0) + 1,
+        reason: 'run-resumed',
+      })
+      await this.attachCheckpoint(tx, synced.run, checkpoint)
+    })
+
+    const snapshot = await planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
+    })
+
+    return buildToolResult({
+      action: 'run-resumed',
+      plan: snapshot,
+      message: `Resumed execution run "${snapshot.title}".`,
+    })
+  }
+
+  async syncRunGraph(params: {
+    tx: DatabaseTransaction
+    run: PlanRunRecord
+    spec: PlanSpecRecord
+    nodeSpecs: PlanNodeSpecRecord[]
+    nodeRuns: PlanNodeRunRecord[]
+    artifacts: Array<{
+      id: RecordIdInput
+      nodeId: string
+      name: string
+      kind: string
+      pointer: string
+      schemaRef?: string
+      payload?: unknown
+    }>
+    emittedBy: string
+  }): Promise<{
+    run: PlanRunRecord
+    nodeRuns: PlanNodeRunRecord[]
+    artifacts: Array<{
+      id: RecordIdInput
+      nodeId: string
+      name: string
+      kind: string
+      pointer: string
+      schemaRef?: string
+      payload?: unknown
+    }>
+  }> {
+    let currentRun = params.run
+    let currentNodeRuns = [...params.nodeRuns]
+    const currentArtifacts = [...params.artifacts]
+    const sortedNodeSpecs = [...params.nodeSpecs].sort((left, right) => left.position - right.position)
+
+    const replaceNodeRun = (nextNodeRun: PlanNodeRunRecord) => {
+      currentNodeRuns = currentNodeRuns.map((candidate) =>
+        candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate,
+      )
+    }
+
+    const getNodeRunsById = () => new Map(currentNodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
+    const getArtifactsByNodeId = () =>
+      currentArtifacts.reduce((groups, artifact) => {
+        const list = groups.get(artifact.nodeId) ?? []
+        list.push(artifact)
+        groups.set(artifact.nodeId, list)
+        return groups
+      }, new Map<string, typeof currentArtifacts>())
+
+    let changed = true
+    while (changed) {
+      changed = false
+      const nodeRunsById = getNodeRunsById()
+      const artifactsByNodeId = getArtifactsByNodeId()
+
+      for (const nodeSpec of sortedNodeSpecs) {
+        const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+        if (!nodeRun || nodeRun.status !== 'pending') continue
+
+        const upstreamRuns = nodeSpec.upstreamNodeIds
+          .map((nodeId) => nodeRunsById.get(nodeId))
+          .filter(Boolean) as PlanNodeRunRecord[]
+        if (
+          nodeSpec.upstreamNodeIds.length > 0 &&
+          !upstreamRuns.every((upstreamRun) => isSuccessfulTerminalStatus(upstreamRun.status))
+        ) {
+          continue
+        }
+
+        const activeIncomingEdges = params.spec.edges.filter((edge) => {
+          if (edge.target !== nodeSpec.nodeId) return false
+          const sourceRun = nodeRunsById.get(edge.source)
+          if (!sourceRun) return false
+          const context = buildNodeContext({ nodeRun: sourceRun, artifacts: artifactsByNodeId.get(edge.source) ?? [] })
+          return evaluateCondition(edge.when, context)
+        })
+
+        if (nodeSpec.upstreamNodeIds.length > 0 && activeIncomingEdges.length === 0) {
+          const skippedNodeRun = PlanNodeRunSchema.parse(
+            await params.tx
+              .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(nodeRun, {
+                  status: 'skipped',
+                  completedAt: new Date(),
+                  blockedReason: null,
+                  failureClass: null,
+                }),
+              )
+              .output('after'),
+          )
+          replaceNodeRun(skippedNodeRun)
+          await this.emitEvent({
+            tx: params.tx,
+            run: currentRun,
+            spec: params.spec,
+            nodeId: skippedNodeRun.nodeId,
+            eventType: 'node-skipped',
+            fromStatus: nodeRun.status,
+            toStatus: skippedNodeRun.status,
+            message: `Node "${nodeSpec.label}" was skipped because no inbound branch was activated.`,
+            emittedBy: params.emittedBy,
+          })
+          changed = true
+          continue
+        }
+
+        const resolvedInput = this.buildResolvedInput({ spec: params.spec, nodeSpec, nodeRunsById, artifactsByNodeId })
+        const readyNodeRun = PlanNodeRunSchema.parse(
+          await params.tx
+            .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(toNodeRunData(nodeRun, { status: 'ready', resolvedInput, readyAt: new Date() }))
+            .output('after'),
+        )
+        replaceNodeRun(readyNodeRun)
+        await this.emitEvent({
+          tx: params.tx,
+          run: currentRun,
+          spec: params.spec,
+          nodeId: readyNodeRun.nodeId,
+          eventType: 'node-ready',
+          fromStatus: nodeRun.status,
+          toStatus: readyNodeRun.status,
+          message: `Node "${nodeSpec.label}" is ready to execute.`,
+          emittedBy: params.emittedBy,
+        })
+        changed = true
+      }
+
+      const readyStructuralNodes = sortedNodeSpecs.filter((nodeSpec) => {
+        const nodeRun = getNodeRunsById().get(nodeSpec.nodeId)
+        return nodeRun?.status === 'ready' && isStructuralNodeType(nodeSpec.type)
+      })
+
+      for (const nodeSpec of readyStructuralNodes) {
+        const nodeRun = getNodeRunsById().get(nodeSpec.nodeId)
+        if (!nodeRun) continue
+
+        const completedNodeRun = PlanNodeRunSchema.parse(
+          await params.tx
+            .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(
+              toNodeRunData(nodeRun, {
+                status: 'completed',
+                startedAt: nodeRun.startedAt ?? new Date(),
+                completedAt: new Date(),
+              }),
+            )
+            .output('after'),
+        )
+        replaceNodeRun(completedNodeRun)
+        await this.emitEvent({
+          tx: params.tx,
+          run: currentRun,
+          spec: params.spec,
+          nodeId: completedNodeRun.nodeId,
+          eventType: 'node-auto-completed',
+          fromStatus: nodeRun.status,
+          toStatus: completedNodeRun.status,
+          message: `Structural node "${nodeSpec.label}" auto-completed.`,
+          emittedBy: params.emittedBy,
+        })
+        changed = true
+      }
+    }
+
+    const nodeRunsById = getNodeRunsById()
+    const activeRunningNode = currentNodeRuns.find((nodeRun) => nodeRun.status === 'running')
+    const activeHumanNode = currentNodeRuns.find((nodeRun) => nodeRun.status === 'awaiting-human')
+
+    if (!activeRunningNode && !activeHumanNode) {
+      const nextHumanNodeSpec = sortedNodeSpecs.find((nodeSpec) => {
+        const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+        return nodeRun?.status === 'ready' && isHumanNodeType(nodeSpec.type)
+      })
+
+      if (nextHumanNodeSpec) {
+        const nodeRun = nodeRunsById.get(nextHumanNodeSpec.nodeId)
+        if (!nodeRun) {
+          throw new Error(`Expected ready node run for "${nextHumanNodeSpec.nodeId}".`)
+        }
+        const awaitingHumanNodeRun = PlanNodeRunSchema.parse(
+          await params.tx
+            .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(toNodeRunData(nodeRun, { status: 'awaiting-human', startedAt: nodeRun.startedAt ?? new Date() }))
+            .output('after'),
+        )
+        replaceNodeRun(awaitingHumanNodeRun)
+
+        const approval = await planApprovalService.createPendingApproval({
+          tx: params.tx,
+          runId: currentRun.id,
+          nodeRunId: awaitingHumanNodeRun.id,
+          nodeId: awaitingHumanNodeRun.nodeId,
+          requestedBy: params.emittedBy,
+          presented: {
+            nodeId: nextHumanNodeSpec.nodeId,
+            label: nextHumanNodeSpec.label,
+            objective: nextHumanNodeSpec.objective,
+            instructions: nextHumanNodeSpec.instructions,
+            deliverables: nextHumanNodeSpec.deliverables,
+            successCriteria: nextHumanNodeSpec.successCriteria,
+            resolvedInput: awaitingHumanNodeRun.resolvedInput ?? {},
+          },
+        })
+
+        currentRun = await this.replaceRun(params.tx, currentRun, {
+          status: 'awaiting-human',
+          currentNodeId: awaitingHumanNodeRun.nodeId,
+          waitingNodeId: awaitingHumanNodeRun.nodeId,
+          readyNodeIds: currentNodeRuns
+            .filter((candidate) => candidate.status === 'ready' && candidate.nodeId !== awaitingHumanNodeRun.nodeId)
+            .map((candidate) => candidate.nodeId),
+        })
+
+        await this.emitEvent({
+          tx: params.tx,
+          run: currentRun,
+          spec: params.spec,
+          nodeId: awaitingHumanNodeRun.nodeId,
+          approvalId: approval.id,
+          eventType: 'approval-requested',
+          fromStatus: params.run.status,
+          toStatus: currentRun.status,
+          message: `Node "${nextHumanNodeSpec.label}" is awaiting human input.`,
+          emittedBy: params.emittedBy,
+        })
+      } else {
+        const nextActionNodeSpec = sortedNodeSpecs.find((nodeSpec) => {
+          const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+          return nodeRun?.status === 'ready' && !isStructuralNodeType(nodeSpec.type)
+        })
+
+        if (nextActionNodeSpec) {
+          const nodeRun = nodeRunsById.get(nextActionNodeSpec.nodeId)
+          if (!nodeRun) {
+            throw new Error(`Expected ready node run for "${nextActionNodeSpec.nodeId}".`)
+          }
+          const runningNodeRun = PlanNodeRunSchema.parse(
+            await params.tx
+              .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(toNodeRunData(nodeRun, { status: 'running', startedAt: nodeRun.startedAt ?? new Date() }))
+              .output('after'),
+          )
+          replaceNodeRun(runningNodeRun)
+
+          currentRun = await this.replaceRun(params.tx, currentRun, {
+            status: 'running',
+            currentNodeId: runningNodeRun.nodeId,
+            waitingNodeId: null,
+            readyNodeIds: currentNodeRuns
+              .filter((candidate) => candidate.status === 'ready' && candidate.nodeId !== runningNodeRun.nodeId)
+              .map((candidate) => candidate.nodeId),
+          })
+
+          await this.emitEvent({
+            tx: params.tx,
+            run: currentRun,
+            spec: params.spec,
+            nodeId: runningNodeRun.nodeId,
+            eventType: 'node-running',
+            fromStatus: nodeRun.status,
+            toStatus: runningNodeRun.status,
+            message: `Node "${nextActionNodeSpec.label}" is now running.`,
+            emittedBy: params.emittedBy,
+          })
+        } else if (currentNodeRuns.every((nodeRun) => isSuccessfulTerminalStatus(nodeRun.status))) {
+          currentRun = await this.replaceRun(params.tx, currentRun, {
+            status: 'completed',
+            currentNodeId: null,
+            waitingNodeId: null,
+            readyNodeIds: [],
+            completedAt: new Date(),
+          })
+
+          await this.emitEvent({
+            tx: params.tx,
+            run: currentRun,
+            spec: params.spec,
+            eventType: 'run-status-changed',
+            fromStatus: params.run.status,
+            toStatus: currentRun.status,
+            message: `Run "${params.spec.title}" completed.`,
+            emittedBy: params.emittedBy,
+          })
+        } else {
+          currentRun = await this.replaceRun(params.tx, currentRun, {
+            status: 'blocked',
+            currentNodeId: null,
+            waitingNodeId: null,
+            readyNodeIds: currentNodeRuns
+              .filter((candidate) => candidate.status === 'ready')
+              .map((candidate) => candidate.nodeId),
+          })
+        }
+      }
+    } else {
+      currentRun = await this.replaceRun(params.tx, currentRun, {
+        status: activeHumanNode ? 'awaiting-human' : 'running',
+        currentNodeId: activeHumanNode?.nodeId ?? activeRunningNode?.nodeId ?? null,
+        waitingNodeId: activeHumanNode?.nodeId ?? null,
+        readyNodeIds: currentNodeRuns
+          .filter((candidate) => candidate.status === 'ready')
+          .map((candidate) => candidate.nodeId),
+      })
+    }
+
+    return { run: currentRun, nodeRuns: currentNodeRuns, artifacts: currentArtifacts }
+  }
+
+  private resolveFailureAction(nodeSpec: PlanNodeSpecRecord, failureClass: PlanFailureClass | null): PlanFailureAction {
+    if (!failureClass) return 'abort'
+
+    const matchedRule = nodeSpec.failurePolicy.find((rule) => rule.on === failureClass)
+    return matchedRule?.action ?? 'abort'
+  }
+
+  private buildResolvedInput(params: {
+    spec: PlanSpecRecord
+    nodeSpec: PlanNodeSpecRecord
+    nodeRunsById: Map<string, PlanNodeRunRecord>
+    artifactsByNodeId: Map<
+      string,
+      Array<{ nodeId: string; name: string; kind: string; pointer: string; schemaRef?: string; payload?: unknown }>
+    >
+  }) {
+    const resolvedInput: Record<string, unknown> = {}
+
+    for (const edge of params.spec.edges.filter((candidate) => candidate.target === params.nodeSpec.nodeId)) {
+      const sourceRun = params.nodeRunsById.get(edge.source)
+      if (!sourceRun || !isSuccessfulTerminalStatus(sourceRun.status)) continue
+
+      const context = buildNodeContext({
+        nodeRun: sourceRun,
+        artifacts: params.artifactsByNodeId.get(edge.source) ?? [],
+      })
+      if (!evaluateCondition(edge.when, context)) continue
+
+      for (const [targetPath, sourcePath] of Object.entries(edge.map)) {
+        const value = readPathValue(context, sourcePath)
+        if (value !== undefined) {
+          setPathValue(resolvedInput, targetPath, value)
+        }
+      }
+    }
+
+    return resolvedInput
+  }
+
+  private async createAttempt(params: {
+    tx: DatabaseTransaction
+    run: PlanRunRecord
+    nodeRun: PlanNodeRunRecord
+    emittedBy: string
+    result: PlanNodeResultSubmission
+    status: 'completed' | 'failed'
+    failureClass: PlanFailureClass | null
+  }) {
+    const attemptId = new RecordId(TABLES.PLAN_NODE_ATTEMPT, Bun.randomUUIDv7())
+    return PlanNodeAttemptSchema.parse(
+      await params.tx
+        .create(attemptId)
+        .content({
+          runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+          nodeRunId: ensureRecordId(params.nodeRun.id, TABLES.PLAN_NODE_RUN),
+          nodeId: params.nodeRun.nodeId,
+          emittedBy: params.emittedBy,
+          status: params.status,
+          ...(params.result.structuredOutput ? { structuredOutput: params.result.structuredOutput } : {}),
+          ...(params.result.notes ? { notes: params.result.notes } : {}),
+          validationIssueIds: [],
+          ...(params.failureClass ? { failureClass: params.failureClass } : {}),
+        })
+        .output('after'),
+    )
+  }
+
+  private async persistValidationIssues(params: {
+    tx: DatabaseTransaction
+    run: PlanRunRecord
+    spec: PlanSpecRecord
+    attemptId: RecordIdInput
+    nodeId: string
+    issues: PlanValidationIssueInput[]
+  }): Promise<PlanValidationIssueRecord[]> {
+    const records: PlanValidationIssueRecord[] = []
+
+    for (const issue of params.issues) {
+      const issueId = new RecordId(TABLES.PLAN_VALIDATION_ISSUE, Bun.randomUUIDv7())
+      const created = await params.tx
+        .create(issueId)
+        .content({
+          planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+          nodeId: issue.nodeId ?? params.nodeId,
+          attemptId: ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT),
+          severity: issue.severity,
+          code: issue.code,
+          message: issue.message,
+          ...(issue.detail ? { detail: issue.detail } : {}),
+        })
+        .output('after')
+
+      records.push(PlanValidationIssueSchema.parse(created))
+    }
+
+    return records
+  }
+
+  private async emitEvent(params: {
+    tx: DatabaseTransaction
+    run: PlanRunRecord
+    spec: PlanSpecRecord
+    eventType: PlanEventType
+    message: string
+    emittedBy: string
+    nodeId?: string
+    attemptId?: RecordIdInput
+    approvalId?: RecordIdInput
+    fromStatus?: string
+    toStatus?: string
+    detail?: Record<string, unknown>
+  }): Promise<PlanEventRecord> {
+    const eventId = new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7())
+    const created = await params.tx
+      .create(eventId)
+      .content({
+        planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+        runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+        eventType: params.eventType,
+        message: params.message,
+        emittedBy: params.emittedBy,
+        ...(params.nodeId ? { nodeId: params.nodeId } : {}),
+        ...(params.attemptId ? { attemptId: ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT) } : {}),
+        ...(params.approvalId ? { approvalId: ensureRecordId(params.approvalId, TABLES.PLAN_APPROVAL) } : {}),
+        ...(params.fromStatus ? { fromStatus: params.fromStatus } : {}),
+        ...(params.toStatus ? { toStatus: params.toStatus } : {}),
+        ...(params.detail ? { detail: params.detail } : {}),
+      })
+      .output('after')
+
+    return PlanEventSchema.parse(created)
+  }
+
+  private async replaceRun(tx: DatabaseTransaction, run: PlanRunRecord, patch: PlanRunUpdate): Promise<PlanRunRecord> {
+    return PlanRunSchema.parse(
+      await tx.update(ensureRecordId(run.id, TABLES.PLAN_RUN)).content(toRunData(run, patch)).output('after'),
+    )
+  }
+
+  private async saveCheckpoint(params: {
+    tx: DatabaseTransaction
+    run: PlanRunRecord
+    nodeRuns: PlanNodeRunRecord[]
+    artifacts: Array<{ id: RecordIdInput; nodeId: string }>
+    sequence: number
+    reason: string
+  }) {
+    const checkpoint = await planCheckpointService.createCheckpoint({
+      tx: params.tx,
+      runId: params.run.id,
+      sequence: params.sequence,
+      runStatus: params.run.status,
+      readyNodeIds: params.run.readyNodeIds,
+      activeNodeIds: params.run.currentNodeId ? [params.run.currentNodeId] : [],
+      artifactIds: params.artifacts.map((artifact) => artifact.id),
+      lastCompletedNodeIds: params.nodeRuns
+        .filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+        .map((nodeRun) => nodeRun.nodeId),
+      snapshot: {
+        reason: params.reason,
+        runStatus: params.run.status,
+        currentNodeId: params.run.currentNodeId,
+        waitingNodeId: params.run.waitingNodeId,
+        readyNodeIds: params.run.readyNodeIds,
+        nodeStatuses: Object.fromEntries(params.nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun.status])),
+      },
+    })
+
+    await this.emitEvent({
+      tx: params.tx,
+      run: params.run,
+      spec: await planRunService.getPlanSpecById(params.run.planSpecId),
+      eventType: 'checkpoint-saved',
+      message: `Saved checkpoint ${checkpoint.sequence}.`,
+      detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: params.reason },
+      emittedBy: 'system',
+    })
+
+    return checkpoint
+  }
+
+  private async attachCheckpoint(
+    tx: DatabaseTransaction,
+    run: PlanRunRecord,
+    checkpoint: RecordIdInput | { id: RecordIdInput },
+  ) {
+    const checkpointId = checkpoint && typeof checkpoint === 'object' && 'id' in checkpoint ? checkpoint.id : checkpoint
+
+    await tx
+      .update(ensureRecordId(run.id, TABLES.PLAN_RUN))
+      .content(toRunData(run, { lastCheckpointId: checkpointId }))
+      .output('after')
+  }
+}
+
+export const planExecutorService = new PlanExecutorService()