@lota-sdk/core 0.4.8 → 0.4.10

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

@@ -0,0 +1,1737 @@
+import type {
+  ExecutionPlanToolResultData,
+  PlanFailureClass,
+  PlanNodeResultSubmission,
+  SerializableExecutionPlan,
+} from '@lota-sdk/shared'
+import { PlanNodeAttemptSchema, PlanNodeRunSchema } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+import type { z } from 'zod'
+
+import { aiLogger } from '../../config/logger'
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { DatabaseTransaction } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { BadRequestError, NotFoundError } from '../../effect/errors'
+import { effectTryPromise as effectTryPromiseShared } from '../../effect/helpers'
+import { runPromise } from '../../effect/runtime'
+import { DatabaseServiceTag } from '../../effect/services'
+import { GeneratedDocumentStorageServiceTag } from '../../storage/generated-document-storage.service'
+import { nowDate } from '../../utils/date-time'
+import { toError } from '../../utils/errors'
+import { ArtifactServiceTag } from '../artifact.service'
+import { BackgroundWorkService } from '../background-work.service'
+import { FeedbackLoopServiceTag } from '../feedback-loop.service'
+import { InstitutionalMemoryServiceTag } from '../institutional-memory.service'
+import { QualityMetricsServiceTag } from '../quality-metrics.service'
+import { PlanApprovalServiceTag } from './plan-approval.service'
+import { PlanArtifactServiceTag } from './plan-artifact.service'
+import { PlanCheckpointServiceTag } from './plan-checkpoint.service'
+import { makePlanCompletionSideEffects } from './plan-completion-side-effects'
+import { PlanCoordinationServiceTag } from './plan-coordination.service'
+import { PlanEventDeliveryServiceTag } from './plan-event-delivery.service'
+import type { PlanExecutorContext } from './plan-executor-context'
+import { syncRunGraph } from './plan-executor-graph'
+import type { HumanNodeResponsePayload } from './plan-executor-helpers'
+import {
+  buildPublishedArtifactContent,
+  buildResolvedInput,
+  deriveApprovalStatus,
+  isHumanNodeType,
+  readHumanRequiredEdits,
+  readHumanResponseComments,
+  isStructuralNodeType,
+  resolveFailureAction,
+  toNodeRunData,
+} from './plan-executor-helpers'
+import {
+  attachCheckpoint,
+  createAttempt,
+  emitEvent,
+  persistValidationIssues,
+  replaceRun,
+  saveCheckpoint,
+} from './plan-executor-persistence'
+import { toPlanNodeValidationSpec } from './plan-node-spec'
+import { buildExecutionPlanToolResult } from './plan-run-data'
+import { serializeRunFull } from './plan-run-serialization'
+import { PlanRunServiceTag } from './plan-run.service'
+import { PlanSchedulerServiceTag } from './plan-scheduler.service'
+import { withTransactionAndEventsEffect } from './plan-transaction-events'
+import { PlanValidatorServiceTag } from './plan-validator.service'
+
+interface PlanExecutorDeps {
+  db: Context.Service.Shape<typeof DatabaseServiceTag>
+  storage: Context.Service.Shape<typeof GeneratedDocumentStorageServiceTag>
+  artifactService: Context.Service.Shape<typeof ArtifactServiceTag>
+  feedbackLoopService: Context.Service.Shape<typeof FeedbackLoopServiceTag>
+  institutionalMemoryService: Context.Service.Shape<typeof InstitutionalMemoryServiceTag>
+  planApprovalService: Context.Service.Shape<typeof PlanApprovalServiceTag>
+  planArtifactService: Context.Service.Shape<typeof PlanArtifactServiceTag>
+  planCheckpointService: Context.Service.Shape<typeof PlanCheckpointServiceTag>
+  planCoordinationService: Context.Service.Shape<typeof PlanCoordinationServiceTag>
+  planEventDeliveryService: Context.Service.Shape<typeof PlanEventDeliveryServiceTag>
+  planRunService: Context.Service.Shape<typeof PlanRunServiceTag>
+  planSchedulerService: Context.Service.Shape<typeof PlanSchedulerServiceTag>
+  planValidatorService: Context.Service.Shape<typeof PlanValidatorServiceTag>
+  qualityMetricsService: Context.Service.Shape<typeof QualityMetricsServiceTag>
+}
+
+type PlanExecutorService = ReturnType<typeof makePlanExecutorService>
+
+function saveCheckpointWithContext(
+  context: Pick<PlanExecutorContext, 'planCheckpointService'>,
+  params: Omit<Parameters<typeof saveCheckpoint>[0], 'planCheckpointService'>,
+) {
+  return saveCheckpoint({ ...params, planCheckpointService: context.planCheckpointService })
+}
+
+class PlanExecutorInternalError extends Schema.TaggedErrorClass<PlanExecutorInternalError>()(
+  'PlanExecutorInternalError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+function fromPromise<A>(thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>) {
+  return effectTryPromiseShared(
+    thunk,
+    (cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause }),
+  )
+}
+
+function parseRowOrFail<T>(
+  schema: z.ZodType<T>,
+  value: unknown,
+  operation: string,
+): Effect.Effect<T, PlanExecutorInternalError> {
+  return Effect.try({
+    try: () => schema.parse(value),
+    catch: (cause) => new PlanExecutorInternalError({ message: `Failed to parse ${operation} row`, cause }),
+  })
+}
+
+function withDatabaseTransactionEffect<A, E, R>(
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>,
+  run: (tx: DatabaseTransaction) => Effect.Effect<A, E, R>,
+) {
+  return databaseService.withTransaction((tx) => run(tx))
+}
+
+type SaveCheckpointParams = Parameters<typeof saveCheckpointWithContext>[1]
+type CapturedPlanEvents = Parameters<typeof emitEvent>[0]['capturedEvents']
+type EffectSuccess<T> = T extends Effect.Effect<infer A, infer _E, infer _R> ? A : Awaited<T>
+type ActivePlanRunRecord = NonNullable<
+  EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['getActiveRunRecord']>>
+>
+type PlanRunRecord = EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['getRunById']>>
+type PlanSpecRecord = EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['getPlanSpecById']>>
+type PlanNodeSpecRecord = EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['listNodeSpecs']>>[number]
+type PlanNodeRunRecord = EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['getNodeRunByNodeId']>>
+type PlanArtifacts = EffectSuccess<ReturnType<PlanExecutorContext['planRunService']['listArtifacts']>>
+type PlanNodeResultValidation = ReturnType<PlanExecutorContext['planValidatorService']['validateNodeResult']>
+type PlanApprovalRecord = NonNullable<
+  EffectSuccess<ReturnType<PlanExecutorContext['planApprovalService']['getApprovalById']>>
+>
+type ApprovalResolutionStatus = ReturnType<typeof deriveApprovalStatus>
+
+interface LoadedNodeResultSubmission {
+  run: PlanRunRecord
+  spec: PlanSpecRecord
+  nodeSpecs: PlanNodeSpecRecord[]
+  nodeSpec: PlanNodeSpecRecord
+  nodeRun: PlanNodeRunRecord
+  existingArtifacts: PlanArtifacts
+  nextCheckpointSequence: number
+  validation: PlanNodeResultValidation
+}
+
+interface PersistedNodeResultAttempt {
+  attemptId: RecordIdInput
+  nextNodeRun: PlanNodeRunRecord
+  withUpdatedNodeRuns: PlanNodeRunRecord[]
+  nextArtifacts: PlanArtifacts
+}
+
+interface LoadedHumanNodeResponseSubmission {
+  run: ActivePlanRunRecord
+  spec: PlanSpecRecord
+  nodeSpecs: PlanNodeSpecRecord[]
+  nodeSpec: PlanNodeSpecRecord
+  nodeRun: PlanNodeRunRecord
+  approval: PlanApprovalRecord
+  existingArtifacts: PlanArtifacts
+  nextCheckpointSequence: number
+  validation: PlanNodeResultValidation
+  responseComments?: string
+  submittedResult: PlanNodeResultSubmission
+}
+
+interface PersistedHumanNodeResponseAttempt {
+  attemptId: RecordIdInput
+  approvalStatus: ApprovalResolutionStatus
+  nextNodeRun: PlanNodeRunRecord
+  nodeRuns: PlanNodeRunRecord[]
+}
+
+function replaceNodeRunInList<T extends { nodeId: string }>(nodeRuns: readonly T[], nextNodeRun: T): T[] {
+  return nodeRuns.map((candidate) => (candidate.nodeId === nextNodeRun.nodeId ? nextNodeRun : candidate))
+}
+
+function saveAndAttachCheckpointEffect(
+  context: Pick<PlanExecutorContext, 'planCheckpointService'>,
+  params: SaveCheckpointParams,
+) {
+  return Effect.gen(function* () {
+    const checkpoint = yield* saveCheckpointWithContext(context, params)
+    yield* attachCheckpoint(params.tx, params.run, checkpoint)
+  })
+}
+
+function loadNodeResultSubmissionContextEffect(
+  context: Pick<PlanExecutorContext, 'planRunService' | 'planValidatorService'>,
+  params: { threadId: RecordIdInput; runId: string; nodeId: string; result: PlanNodeResultSubmission },
+) {
+  return Effect.gen(function* () {
+    const run = yield* context.planRunService.getRunById(params.runId)
+    if (recordIdToString(run.threadId, TABLES.THREAD) !== recordIdToString(params.threadId, TABLES.THREAD)) {
+      return yield* new BadRequestError({ message: 'Execution node result targets a different thread.' })
+    }
+    if (run.status === 'completed' || run.status === 'failed' || run.status === 'aborted') {
+      return yield* new BadRequestError({ message: 'Execution run is no longer active.' })
+    }
+
+    const spec = yield* context.planRunService.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = yield* context.planRunService.listNodeSpecs(spec.id)
+    const nodeSpec = nodeSpecs.find((candidate) => candidate.nodeId === params.nodeId)
+    if (!nodeSpec) {
+      return yield* new NotFoundError({
+        resource: 'plan-node',
+        id: params.nodeId,
+        message: `Execution node "${params.nodeId}" does not exist in this run.`,
+      })
+    }
+    if (isHumanNodeType(nodeSpec.type) || isStructuralNodeType(nodeSpec.type)) {
+      return yield* new BadRequestError({
+        message: `Execution node "${nodeSpec.label}" is executor-owned and cannot accept direct result submission.`,
+      })
+    }
+
+    const nodeRun = yield* context.planRunService.getNodeRunByNodeId(run.id, params.nodeId)
+    if (nodeRun.status !== 'running') {
+      return yield* new BadRequestError({ message: `Execution node "${nodeSpec.label}" is not currently running.` })
+    }
+
+    const existingArtifacts = yield* context.planRunService.listArtifacts(run.id)
+    const nextCheckpointSequence = yield* context.planRunService.getNextCheckpointSequence(run.id)
+    const validation = context.planValidatorService.validateNodeResult({
+      draft: { schemas: spec.schemaRegistry },
+      node: toPlanNodeValidationSpec(nodeSpec),
+      result: params.result,
+    })
+
+    return {
+      run,
+      spec,
+      nodeSpecs,
+      nodeSpec,
+      nodeRun,
+      existingArtifacts,
+      nextCheckpointSequence,
+      validation,
+    } satisfies LoadedNodeResultSubmission
+  })
+}
+
+function publishNodeResultArtifactsEffect(params: {
+  artifactService: PlanExecutorContext['artifactService']
+  tx: DatabaseTransaction
+  run: PlanRunRecord
+  nodeSpec: PlanNodeSpecRecord
+  nodeId: string
+  emittedBy: string
+  result: PlanNodeResultSubmission
+  publishedArtifactStorageKeys: string[]
+}) {
+  const { artifactService, tx, run, nodeSpec, nodeId, emittedBy, result, publishedArtifactStorageKeys } = params
+
+  return Effect.forEach(result.artifacts, (artifact) =>
+    Effect.gen(function* () {
+      const deliverable = nodeSpec.deliverables.find((candidate) => candidate.name === artifact.name)
+      if (!deliverable?.publishAs) {
+        return artifact
+      }
+      const publishAs = deliverable.publishAs
+
+      const content = buildPublishedArtifactContent({ artifact, notes: result.notes })
+      const published = yield* artifactService
+        .publishArtifactInTransaction(
+          {
+            organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+            authorAgentId: emittedBy,
+            title: artifact.name,
+            artifactKind: publishAs.artifactKind,
+            templateId: publishAs.templateId,
+            canonicalKey: publishAs.canonicalKey,
+            content,
+            tags: [],
+            ...(artifact.description ? { description: artifact.description } : {}),
+            sourceThreadId: recordIdToString(run.threadId, TABLES.THREAD),
+            sourcePlanRunId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            sourcePlanNodeId: nodeId,
+            deliverableName: artifact.name,
+          },
+          tx,
+        )
+        .pipe(Effect.mapError((cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause })))
+      publishedArtifactStorageKeys.push(published.storageKey)
+
+      return { ...artifact, content, publishedArtifactId: recordIdToString(published.id, TABLES.ARTIFACT) }
+    }),
+  )
+}
+
+function persistNodeResultAttemptEffect(
+  context: Pick<PlanExecutorContext, 'artifactService' | 'planArtifactService' | 'planRunService'>,
+  params: {
+    tx: DatabaseTransaction
+    submission: LoadedNodeResultSubmission
+    nodeId: string
+    emittedBy: string
+    result: PlanNodeResultSubmission
+    publishedArtifactStorageKeys: string[]
+  },
+) {
+  const { tx, submission, nodeId, emittedBy, result, publishedArtifactStorageKeys } = params
+
+  return Effect.gen(function* () {
+    const attempt = yield* createAttempt({
+      tx,
+      run: submission.run,
+      nodeRun: submission.nodeRun,
+      emittedBy,
+      result,
+      status: submission.validation.blocking.length > 0 ? 'failed' : 'completed',
+      failureClass: submission.validation.failureClass,
+    })
+
+    const issues = yield* persistValidationIssues({
+      tx,
+      run: submission.run,
+      spec: submission.spec,
+      attemptId: attempt.id,
+      nodeId,
+      issues: [...submission.validation.blocking, ...submission.validation.warnings],
+    })
+
+    const updatedAttemptRow = yield* fromPromise(() =>
+      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: { id: RecordIdInput }) =>
+            ensureRecordId(issue.id, TABLES.PLAN_VALIDATION_ISSUE),
+          ),
+          ...(attempt.failureClass ? { failureClass: attempt.failureClass } : {}),
+        })
+        .output('after'),
+    )
+    void (yield* parseRowOrFail(PlanNodeAttemptSchema, updatedAttemptRow, 'plan node attempt'))
+
+    const publishedArtifacts =
+      submission.validation.blocking.length > 0
+        ? result.artifacts
+        : yield* publishNodeResultArtifactsEffect({
+            artifactService: context.artifactService,
+            tx,
+            run: submission.run,
+            nodeSpec: submission.nodeSpec,
+            nodeId,
+            emittedBy,
+            result,
+            publishedArtifactStorageKeys,
+          })
+
+    const persistedArtifacts = yield* context.planArtifactService.persistArtifacts({
+      tx,
+      runId: submission.run.id,
+      attemptId: attempt.id,
+      nodeId,
+      artifacts: publishedArtifacts,
+    })
+
+    const nextNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(submission.nodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(submission.nodeRun, {
+            attemptCount: submission.nodeRun.attemptCount + 1,
+            latestAttemptId: attempt.id,
+            latestStructuredOutput: result.structuredOutput ?? null,
+            latestNotes: result.notes,
+          }),
+        )
+        .output('after'),
+    )
+    const nextNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, nextNodeRunRow, 'plan node run')
+
+    const nodeRuns = yield* context.planRunService.listNodeRuns(submission.run.id)
+
+    return {
+      attemptId: attempt.id,
+      nextNodeRun,
+      withUpdatedNodeRuns: replaceNodeRunInList(nodeRuns, nextNodeRun),
+      nextArtifacts: [...submission.existingArtifacts, ...persistedArtifacts],
+    } satisfies PersistedNodeResultAttempt
+  })
+}
+
+function handleRetryNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, emittedBy } = params
+
+  return Effect.gen(function* () {
+    const retryNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(persisted.nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(persisted.nextNodeRun, {
+            status: 'ready',
+            retryCount: persisted.nextNodeRun.retryCount + 1,
+            failureClass: submission.validation.failureClass,
+            blockedReason: submission.validation.blocking[0]?.message ?? null,
+            readyAt: nowDate(),
+            startedAt: null,
+            completedAt: null,
+          }),
+        )
+        .output('after'),
+    )
+    const retryNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, retryNodeRunRow, 'plan node run')
+
+    yield* emitEvent({
+      tx,
+      run: submission.run,
+      spec: submission.spec,
+      nodeId: retryNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      eventType: 'validation-reported',
+      message: `Validation failed for node "${submission.nodeSpec.label}", scheduling retry.`,
+      detail: { issues: submission.validation.blocking.map((issue) => issue.code) },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* emitEvent({
+      tx,
+      run: submission.run,
+      spec: submission.spec,
+      nodeId: retryNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      eventType: 'node-unblocked',
+      fromStatus: submission.nodeRun.status,
+      toStatus: retryNodeRun.status,
+      message: `Node "${submission.nodeSpec.label}" is ready for another attempt.`,
+      detail: { retryCount: retryNodeRun.retryCount },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    const synced = yield* fromPromise(() =>
+      syncRunGraph(context, {
+        tx,
+        run: submission.run,
+        spec: submission.spec,
+        nodeSpecs: submission.nodeSpecs,
+        nodeRuns: replaceNodeRunInList(persisted.withUpdatedNodeRuns, retryNodeRun),
+        artifacts: persisted.nextArtifacts,
+        emittedBy,
+        capturedEvents: emittedEvents,
+      }),
+    )
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: synced.run,
+      spec: submission.spec,
+      nodeRuns: synced.nodeRuns,
+      artifacts: synced.artifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'node-result-retry',
+      capturedEvents: emittedEvents,
+    })
+  })
+}
+
+function handleHumanReviewNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, emittedBy } = params
+
+  return Effect.gen(function* () {
+    const awaitingHumanNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(persisted.nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(persisted.nextNodeRun, {
+            status: 'awaiting-human',
+            retryCount: persisted.nextNodeRun.retryCount + 1,
+            failureClass: submission.validation.failureClass,
+            blockedReason: submission.validation.blocking[0]?.message ?? null,
+            startedAt: persisted.nextNodeRun.startedAt ?? nowDate(),
+          }),
+        )
+        .output('after'),
+    )
+    const awaitingHumanNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, awaitingHumanNodeRunRow, 'plan node run')
+
+    const approval = yield* context.planApprovalService
+      .createPendingApproval({
+        tx,
+        runId: submission.run.id,
+        nodeRunId: awaitingHumanNodeRun.id,
+        nodeId: awaitingHumanNodeRun.nodeId,
+        requestedBy: emittedBy,
+        presented: {
+          nodeId: submission.nodeSpec.nodeId,
+          label: submission.nodeSpec.label,
+          objective: submission.nodeSpec.objective,
+          instructions: submission.nodeSpec.instructions,
+          validationIssues: submission.validation.blocking,
+        },
+      })
+      .pipe(Effect.mapError((cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause })))
+
+    const awaitingHumanRun = yield* replaceRun(tx, submission.run, {
+      status: 'awaiting-human',
+      currentNodeId: awaitingHumanNodeRun.nodeId,
+      waitingNodeId: awaitingHumanNodeRun.nodeId,
+      readyNodeIds: [],
+      failureCount: submission.run.failureCount + 1,
+    })
+
+    yield* emitEvent({
+      tx,
+      run: awaitingHumanRun,
+      spec: submission.spec,
+      nodeId: awaitingHumanNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      approvalId: approval.id,
+      eventType: 'approval-requested',
+      fromStatus: submission.run.status,
+      toStatus: awaitingHumanRun.status,
+      message: `Node "${submission.nodeSpec.label}" requires human review before continuing.`,
+      detail: { issues: submission.validation.blocking.map((issue) => issue.code) },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: awaitingHumanRun,
+      spec: submission.spec,
+      nodeRuns: replaceNodeRunInList(persisted.withUpdatedNodeRuns, awaitingHumanNodeRun),
+      artifacts: persisted.nextArtifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'node-result-human-review',
+      capturedEvents: emittedEvents,
+    })
+  })
+}
+
+function handleReplanNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, emittedBy } = params
+
+  return Effect.gen(function* () {
+    const blockedNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(persisted.nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(persisted.nextNodeRun, {
+            status: 'blocked',
+            retryCount: persisted.nextNodeRun.retryCount + 1,
+            failureClass: submission.validation.failureClass,
+            blockedReason: submission.validation.blocking[0]?.message ?? null,
+          }),
+        )
+        .output('after'),
+    )
+    const blockedNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, blockedNodeRunRow, 'plan node run')
+
+    const blockedRun = yield* replaceRun(tx, submission.run, {
+      status: 'blocked',
+      currentNodeId: blockedNodeRun.nodeId,
+      waitingNodeId: null,
+      readyNodeIds: [],
+      failureCount: submission.run.failureCount + 1,
+    })
+
+    yield* emitEvent({
+      tx,
+      run: blockedRun,
+      spec: submission.spec,
+      nodeId: blockedNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      eventType: 'node-blocked',
+      fromStatus: submission.nodeRun.status,
+      toStatus: blockedNodeRun.status,
+      message: `Node "${submission.nodeSpec.label}" failed validation and requires replanning.`,
+      detail: {
+        failureClass: submission.validation.failureClass,
+        issues: submission.validation.blocking.map((issue) => issue.code),
+      },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: blockedRun,
+      spec: submission.spec,
+      nodeRuns: replaceNodeRunInList(persisted.withUpdatedNodeRuns, blockedNodeRun),
+      artifacts: persisted.nextArtifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'node-result-replan',
+      capturedEvents: emittedEvents,
+    })
+  })
+}
+
+function handleFailedNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, emittedBy } = params
+
+  return Effect.gen(function* () {
+    const failedNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(persisted.nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(persisted.nextNodeRun, {
+            status: 'failed',
+            retryCount: persisted.nextNodeRun.retryCount + 1,
+            failureClass: submission.validation.failureClass,
+            blockedReason: submission.validation.blocking[0]?.message ?? null,
+            completedAt: nowDate(),
+          }),
+        )
+        .output('after'),
+    )
+    const failedNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, failedNodeRunRow, 'plan node run')
+
+    const failedRun = yield* replaceRun(tx, submission.run, {
+      status: 'failed',
+      currentNodeId: null,
+      waitingNodeId: null,
+      readyNodeIds: [],
+      failureCount: submission.run.failureCount + 1,
+      completedAt: nowDate(),
+    })
+
+    yield* emitEvent({
+      tx,
+      run: failedRun,
+      spec: submission.spec,
+      nodeId: failedNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      eventType: 'node-failed',
+      fromStatus: submission.nodeRun.status,
+      toStatus: failedNodeRun.status,
+      message: `Node "${submission.nodeSpec.label}" failed validation and the run has been aborted.`,
+      detail: {
+        failureClass: submission.validation.failureClass,
+        issues: submission.validation.blocking.map((issue) => issue.code),
+      },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: failedRun,
+      spec: submission.spec,
+      nodeRuns: replaceNodeRunInList(persisted.withUpdatedNodeRuns, failedNodeRun),
+      artifacts: persisted.nextArtifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'node-result-failed',
+      capturedEvents: emittedEvents,
+    })
+  })
+}
+
+function handleBlockedNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+  },
+) {
+  const { submission, persisted } = params
+
+  return Effect.gen(function* () {
+    const shouldRetry =
+      submission.validation.failureClass &&
+      submission.nodeSpec.retryPolicy.maxAttempts > persisted.nextNodeRun.retryCount &&
+      (submission.nodeSpec.retryPolicy.retryOn.length === 0 ||
+        submission.nodeSpec.retryPolicy.retryOn.includes(submission.validation.failureClass))
+
+    if (shouldRetry) {
+      return yield* handleRetryNodeResultEffect(context, params)
+    }
+
+    const failureAction = resolveFailureAction(submission.nodeSpec, submission.validation.failureClass)
+    if (failureAction === 'human-review') {
+      return yield* handleHumanReviewNodeResultEffect(context, params)
+    }
+    if (failureAction === 'replan') {
+      return yield* handleReplanNodeResultEffect(context, params)
+    }
+
+    return yield* handleFailedNodeResultEffect(context, params)
+  })
+}
+
+function handleSuccessfulNodeResultEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedNodeResultSubmission
+    persisted: PersistedNodeResultAttempt
+    emittedBy: string
+    result: PlanNodeResultSubmission
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, emittedBy, result } = params
+
+  return Effect.gen(function* () {
+    const completedNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(persisted.nextNodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(persisted.nextNodeRun, {
+            status: submission.validation.warnings.length > 0 ? 'partial' : 'completed',
+            latestAttemptId: persisted.attemptId,
+            latestStructuredOutput: result.structuredOutput ?? null,
+            latestNotes: result.notes,
+            blockedReason: null,
+            failureClass: null,
+            completedAt: nowDate(),
+          }),
+        )
+        .output('after'),
+    )
+    const completedNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, completedNodeRunRow, 'plan node run')
+
+    yield* emitEvent({
+      tx,
+      run: submission.run,
+      spec: submission.spec,
+      nodeId: completedNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      eventType: submission.validation.warnings.length > 0 ? 'node-partial' : 'node-completed',
+      fromStatus: submission.nodeRun.status,
+      toStatus: completedNodeRun.status,
+      message:
+        submission.validation.warnings.length > 0
+          ? `Node "${submission.nodeSpec.label}" completed with warnings.`
+          : `Node "${submission.nodeSpec.label}" completed successfully.`,
+      detail: { warningCount: submission.validation.warnings.length },
+      emittedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    const synced = yield* fromPromise(() =>
+      syncRunGraph(context, {
+        tx,
+        run: submission.run,
+        spec: submission.spec,
+        nodeSpecs: submission.nodeSpecs,
+        nodeRuns: replaceNodeRunInList(persisted.withUpdatedNodeRuns, completedNodeRun),
+        artifacts: persisted.nextArtifacts,
+        emittedBy,
+        capturedEvents: emittedEvents,
+      }),
+    )
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: synced.run,
+      spec: submission.spec,
+      nodeRuns: synced.nodeRuns,
+      artifacts: synced.artifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'node-result-complete',
+      capturedEvents: emittedEvents,
+    })
+  })
+}
+
+function resolveApprovalForWaitingNodeEffect(
+  context: Pick<PlanExecutorContext, 'planApprovalService'>,
+  params: { approvalId?: string; nodeRun: PlanNodeRunRecord; nodeLabel: string },
+) {
+  return Effect.gen(function* () {
+    const approvalId = params.approvalId ?? null
+    const explicitApproval = approvalId
+      ? yield* context.planApprovalService
+          .getApprovalById(approvalId)
+          .pipe(Effect.mapError((cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause })))
+      : null
+
+    if (approvalId && !explicitApproval) {
+      return yield* new NotFoundError({
+        resource: 'plan-approval',
+        id: approvalId,
+        message: `Approval "${approvalId}" does not exist.`,
+      })
+    }
+
+    if (
+      explicitApproval &&
+      recordIdToString(explicitApproval.nodeRunId, TABLES.PLAN_NODE_RUN) !==
+        recordIdToString(params.nodeRun.id, TABLES.PLAN_NODE_RUN)
+    ) {
+      return yield* new BadRequestError({
+        message: `Approval "${approvalId}" does not belong to node "${params.nodeLabel}".`,
+      })
+    }
+
+    if (explicitApproval && explicitApproval.status !== 'pending') {
+      return yield* new BadRequestError({ message: `Approval "${approvalId}" is no longer pending.` })
+    }
+
+    const approval =
+      explicitApproval ??
+      (yield* context.planApprovalService
+        .getPendingApprovalForNodeRun(params.nodeRun.id)
+        .pipe(Effect.mapError((cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause }))))
+    if (!approval) {
+      return yield* new BadRequestError({ message: `No pending approval exists for node "${params.nodeLabel}".` })
+    }
+
+    return approval satisfies PlanApprovalRecord
+  })
+}
+
+function loadHumanNodeResponseContextEffect(
+  context: Pick<PlanExecutorContext, 'planApprovalService' | 'planRunService' | 'planValidatorService'>,
+  params: { threadId: RecordIdInput; approvalId?: string; response: HumanNodeResponsePayload },
+) {
+  return Effect.gen(function* () {
+    const run = yield* context.planRunService.getActiveRunRecord(params.threadId)
+    if (!run || run.status !== 'awaiting-human' || !run.waitingNodeId) {
+      return null
+    }
+
+    const responseComments = readHumanResponseComments(params.response)
+    const submittedResult: PlanNodeResultSubmission = {
+      structuredOutput: params.response,
+      artifacts: [],
+      notes: responseComments ?? 'Human response submitted.',
+    }
+    const waitingNodeId = run.waitingNodeId
+    const spec = yield* context.planRunService.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = yield* context.planRunService.listNodeSpecs(spec.id)
+    const nodeSpec = nodeSpecs.find((candidate) => candidate.nodeId === waitingNodeId)
+    if (!nodeSpec) {
+      return yield* new NotFoundError({
+        resource: 'plan-node',
+        id: waitingNodeId,
+        message: `Waiting node "${waitingNodeId}" does not exist.`,
+      })
+    }
+
+    const nodeRun = yield* context.planRunService.getNodeRunByNodeId(run.id, waitingNodeId)
+    const approval = yield* resolveApprovalForWaitingNodeEffect(context, {
+      approvalId: params.approvalId,
+      nodeRun,
+      nodeLabel: nodeSpec.label,
+    })
+    const existingArtifacts = yield* context.planRunService.listArtifacts(run.id)
+    const nextCheckpointSequence = yield* context.planRunService.getNextCheckpointSequence(run.id)
+    const validation = context.planValidatorService.validateNodeResult({
+      draft: { schemas: spec.schemaRegistry },
+      node: toPlanNodeValidationSpec(nodeSpec),
+      result: submittedResult,
+    })
+
+    return {
+      run,
+      spec,
+      nodeSpecs,
+      nodeSpec,
+      nodeRun,
+      approval,
+      existingArtifacts,
+      nextCheckpointSequence,
+      validation,
+      responseComments,
+      submittedResult,
+    } satisfies LoadedHumanNodeResponseSubmission
+  })
+}
+
+function persistHumanNodeResponseAttemptEffect(
+  context: Pick<PlanExecutorContext, 'planApprovalService' | 'planRunService'>,
+  params: {
+    tx: DatabaseTransaction
+    submission: LoadedHumanNodeResponseSubmission
+    respondedBy: string
+    approvalMessageId?: string
+    response: HumanNodeResponsePayload
+  },
+) {
+  const { tx, submission, respondedBy, approvalMessageId, response } = params
+
+  return Effect.gen(function* () {
+    const approvalStatus = deriveApprovalStatus(response)
+    yield* context.planApprovalService
+      .updateApprovalResponse({
+        tx,
+        approval: submission.approval,
+        status: approvalStatus,
+        response,
+        respondedBy,
+        approvalMessageId,
+        comments: submission.responseComments,
+        requiredEdits: readHumanRequiredEdits(response),
+      })
+      .pipe(Effect.mapError((cause) => new PlanExecutorInternalError({ message: toError(cause).message, cause })))
+
+    const attempt = yield* createAttempt({
+      tx,
+      run: submission.run,
+      nodeRun: submission.nodeRun,
+      emittedBy: respondedBy,
+      result: submission.submittedResult,
+      status: submission.validation.blocking.length > 0 ? 'failed' : 'completed',
+      failureClass: submission.validation.failureClass,
+    })
+
+    const issues = yield* persistValidationIssues({
+      tx,
+      run: submission.run,
+      spec: submission.spec,
+      attemptId: attempt.id,
+      nodeId: submission.nodeRun.nodeId,
+      issues: [...submission.validation.blocking, ...submission.validation.warnings],
+    })
+
+    const updatedHumanAttemptRow = yield* fromPromise(() =>
+      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: response,
+          validationIssueIds: issues.map((issue: { id: RecordIdInput }) =>
+            ensureRecordId(issue.id, TABLES.PLAN_VALIDATION_ISSUE),
+          ),
+          ...(attempt.notes ? { notes: attempt.notes } : {}),
+          ...(attempt.failureClass ? { failureClass: attempt.failureClass } : {}),
+        })
+        .output('after'),
+    )
+    void (yield* parseRowOrFail(PlanNodeAttemptSchema, updatedHumanAttemptRow, 'plan node attempt'))
+
+    const nextNodeRunRow = yield* fromPromise(() =>
+      tx
+        .update(ensureRecordId(submission.nodeRun.id, TABLES.PLAN_NODE_RUN))
+        .content(
+          toNodeRunData(submission.nodeRun, {
+            status: submission.validation.blocking.length > 0 ? 'blocked' : 'completed',
+            attemptCount: submission.nodeRun.attemptCount + 1,
+            latestAttemptId: attempt.id,
+            latestStructuredOutput: response,
+            latestNotes: submission.responseComments ?? null,
+            blockedReason: submission.validation.blocking[0]?.message ?? null,
+            failureClass: submission.validation.blocking.length > 0 ? submission.validation.failureClass : null,
+            ...(submission.validation.blocking.length > 0 ? {} : { completedAt: nowDate() }),
+          }),
+        )
+        .output('after'),
+    )
+    const nextNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, nextNodeRunRow, 'plan node run')
+
+    const nodeRuns = replaceNodeRunInList(yield* context.planRunService.listNodeRuns(submission.run.id), nextNodeRun)
+
+    return { attemptId: attempt.id, approvalStatus, nextNodeRun, nodeRuns } satisfies PersistedHumanNodeResponseAttempt
+  })
+}
+
+function handleBlockedHumanNodeResponseEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedHumanNodeResponseSubmission
+    persisted: PersistedHumanNodeResponseAttempt
+    respondedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, respondedBy } = params
+
+  return Effect.gen(function* () {
+    const blockedRun = yield* replaceRun(tx, submission.run, {
+      status: 'blocked',
+      currentNodeId: persisted.nextNodeRun.nodeId,
+      waitingNodeId: null,
+      readyNodeIds: [],
+      failureCount: submission.run.failureCount + 1,
+    })
+
+    yield* emitEvent({
+      tx,
+      run: blockedRun,
+      spec: submission.spec,
+      nodeId: persisted.nextNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      approvalId: submission.approval.id,
+      eventType: 'approval-resolved',
+      fromStatus: submission.run.status,
+      toStatus: blockedRun.status,
+      message: `Human response for node "${submission.nodeSpec.label}" blocked execution.`,
+      detail: { issues: submission.validation.blocking.map((issue) => issue.code) },
+      emittedBy: respondedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: blockedRun,
+      spec: submission.spec,
+      nodeRuns: persisted.nodeRuns,
+      artifacts: submission.existingArtifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'human-response-blocked',
+      capturedEvents: emittedEvents,
+    })
+
+    const latestRun = yield* context.planRunService.getRunById(submission.run.id)
+    return yield* serializeRunFull(context.planRunService, latestRun)
+  })
+}
+
+function handleAcceptedHumanNodeResponseEffect(
+  context: PlanExecutorContext,
+  params: {
+    tx: DatabaseTransaction
+    emittedEvents: CapturedPlanEvents
+    submission: LoadedHumanNodeResponseSubmission
+    persisted: PersistedHumanNodeResponseAttempt
+    respondedBy: string
+  },
+) {
+  const { tx, emittedEvents, submission, persisted, respondedBy } = params
+
+  return Effect.gen(function* () {
+    const synced = yield* fromPromise(() =>
+      syncRunGraph(context, {
+        tx,
+        run: submission.run,
+        spec: submission.spec,
+        nodeSpecs: submission.nodeSpecs,
+        nodeRuns: persisted.nodeRuns,
+        artifacts: submission.existingArtifacts,
+        emittedBy: respondedBy,
+        capturedEvents: emittedEvents,
+      }),
+    )
+
+    yield* emitEvent({
+      tx,
+      run: synced.run,
+      spec: submission.spec,
+      nodeId: persisted.nextNodeRun.nodeId,
+      attemptId: persisted.attemptId,
+      approvalId: submission.approval.id,
+      eventType: 'approval-resolved',
+      fromStatus: submission.run.status,
+      toStatus: synced.run.status,
+      message: `Human response for node "${submission.nodeSpec.label}" accepted.`,
+      detail: { approvalStatus: persisted.approvalStatus },
+      emittedBy: respondedBy,
+      capturedEvents: emittedEvents,
+    })
+
+    yield* saveAndAttachCheckpointEffect(context, {
+      tx,
+      run: synced.run,
+      spec: submission.spec,
+      nodeRuns: synced.nodeRuns,
+      artifacts: synced.artifacts,
+      sequence: submission.nextCheckpointSequence,
+      reason: 'human-response-complete',
+      capturedEvents: emittedEvents,
+    })
+
+    const latestRun = yield* context.planRunService.getRunById(submission.run.id)
+    return yield* serializeRunFull(context.planRunService, latestRun)
+  })
+}
+
+const submitNodeResultEffect = Effect.fn('PlanExecutor.submitNodeResult')(function* (
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    result: PlanNodeResultSubmission
+  },
+) {
+  const {
+    databaseService,
+    generatedDocumentStorageService,
+    planCompletionSideEffects,
+    planEventDeliveryService,
+    planRunService,
+  } = context
+
+  const submission = yield* loadNodeResultSubmissionContextEffect(context, params)
+  const publishedArtifactStorageKeys: string[] = []
+
+  yield* withTransactionAndEventsEffect({
+    db: databaseService,
+    planEventDeliveryService,
+    run: (tx, emittedEvents) =>
+      Effect.gen(function* () {
+        const persisted = yield* persistNodeResultAttemptEffect(context, {
+          tx,
+          submission,
+          nodeId: params.nodeId,
+          emittedBy: params.emittedBy,
+          result: params.result,
+          publishedArtifactStorageKeys,
+        })
+
+        if (submission.validation.blocking.length > 0) {
+          return yield* handleBlockedNodeResultEffect(context, {
+            tx,
+            emittedEvents,
+            submission,
+            persisted,
+            emittedBy: params.emittedBy,
+          })
+        }
+
+        return yield* handleSuccessfulNodeResultEffect(context, {
+          tx,
+          emittedEvents,
+          submission,
+          persisted,
+          emittedBy: params.emittedBy,
+          result: params.result,
+        })
+      }),
+  }).pipe(
+    Effect.withSpan('PlanExecutor.submitNodeResult.persistTransaction'),
+    Effect.tapError(() =>
+      Effect.forEach(publishedArtifactStorageKeys, (storageKey) =>
+        generatedDocumentStorageService.deleteTextArtifact(storageKey).pipe(Effect.ignore),
+      ).pipe(Effect.asVoid),
+    ),
+  )
+
+  const orgId = recordIdToString(submission.run.organizationId, TABLES.ORGANIZATION)
+  const runIdStr = recordIdToString(submission.run.id, TABLES.PLAN_RUN)
+
+  const background = yield* BackgroundWorkService
+
+  yield* background.run(
+    fromPromise(() =>
+      planCompletionSideEffects.runPlanNodeCompletionSideEffects({
+        runId: runIdStr,
+        organizationId: orgId,
+        nodeId: params.nodeId,
+        nodeLabel: submission.nodeSpec.label,
+        nodeOwnerRef: submission.nodeSpec.owner.ref,
+        nodeOwnerType: submission.nodeSpec.owner.executorType,
+        nodeType: submission.nodeSpec.type,
+        nodeStartedAt: submission.nodeRun.startedAt,
+        nodeAttemptCount: submission.nodeRun.attemptCount + 1,
+        artifactCount: params.result.artifacts.length,
+        validationIssues: [...submission.validation.blocking, ...submission.validation.warnings],
+      }),
+    ).pipe(
+      Effect.catchTag('PlanExecutorInternalError', (error) =>
+        Effect.sync(() => {
+          aiLogger.warn`Failed to record node completion metrics for run ${runIdStr} node ${params.nodeId}: ${error.message}`
+        }),
+      ),
+    ),
+    'plan-executor.recordNodeCompletionMetrics',
+  )
+
+  const updatedRun = yield* planRunService.getRunById(submission.run.id)
+  if (updatedRun.status === 'completed') {
+    yield* background.run(
+      fromPromise(() =>
+        planCompletionSideEffects.runPlanCompletionSideEffectsSafely({ runId: runIdStr, organizationId: orgId }),
+      ).pipe(
+        Effect.catchTag('PlanExecutorInternalError', (error) =>
+          Effect.sync(() => {
+            aiLogger.warn`Plan completion side-effects failed for run ${runIdStr}: ${error.message}`
+          }),
+        ),
+      ),
+      'plan-executor.runPlanCompletionSideEffects',
+    )
+  }
+
+  const snapshot = yield* serializeRunFull(planRunService, updatedRun)
+
+  return buildExecutionPlanToolResult({
+    action: 'node-result-submitted',
+    plan: snapshot,
+    message: `Submitted result for node "${submission.nodeSpec.label}".`,
+  })
+})
+
+/** @lintignore */
+function submitNodeResult(
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    result: PlanNodeResultSubmission
+  },
+): Promise<ExecutionPlanToolResultData> {
+  return submitNodeResultEffect(context, params).pipe(runPromise)
+}
+
+const submitHumanNodeResponseEffect = Effect.fn('PlanExecutor.submitHumanNodeResponse')(function* (
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    approvalId?: string
+    respondedBy: string
+    response: HumanNodeResponsePayload
+    approvalMessageId?: string
+  },
+) {
+  const { databaseService, planEventDeliveryService } = context
+
+  const submission = yield* loadHumanNodeResponseContextEffect(context, params)
+  if (!submission) {
+    return null
+  }
+
+  return yield* withTransactionAndEventsEffect({
+    db: databaseService,
+    planEventDeliveryService,
+    run: (tx, emittedEvents) =>
+      Effect.gen(function* () {
+        const persisted = yield* persistHumanNodeResponseAttemptEffect(context, {
+          tx,
+          submission,
+          respondedBy: params.respondedBy,
+          approvalMessageId: params.approvalMessageId,
+          response: params.response,
+        })
+
+        if (submission.validation.blocking.length > 0) {
+          return yield* handleBlockedHumanNodeResponseEffect(context, {
+            tx,
+            emittedEvents,
+            submission,
+            persisted,
+            respondedBy: params.respondedBy,
+          })
+        }
+
+        return yield* handleAcceptedHumanNodeResponseEffect(context, {
+          tx,
+          emittedEvents,
+          submission,
+          persisted,
+          respondedBy: params.respondedBy,
+        })
+      }),
+  }).pipe(Effect.withSpan('PlanExecutor.submitHumanNodeResponse.persistTransaction'))
+})
+
+/** @lintignore */
+function submitHumanNodeResponse(
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    approvalId?: string
+    respondedBy: string
+    response: HumanNodeResponsePayload
+    approvalMessageId?: string
+  },
+): Promise<SerializableExecutionPlan | null> {
+  return submitHumanNodeResponseEffect(context, params).pipe(runPromise)
+}
+
+const resumeRunEffect = Effect.fn('PlanExecutor.resumeRun')(function* (
+  context: PlanExecutorContext,
+  params: { threadId: RecordIdInput; runId: string; emittedBy: string },
+) {
+  const { databaseService, planEventDeliveryService, planRunService } = context
+
+  const run = yield* planRunService.getRunById(params.runId)
+  const spec = yield* planRunService.getPlanSpecById(run.planSpecId)
+  const [nodeSpecs, nodeRuns, artifacts, latestCheckpoint, nextCheckpointSequence] = yield* Effect.all([
+    planRunService.listNodeSpecs(spec.id),
+    planRunService.listNodeRuns(run.id),
+    planRunService.listArtifacts(run.id),
+    planRunService.getLatestCheckpoint(run.id),
+    planRunService.getNextCheckpointSequence(run.id),
+  ]).pipe(Effect.withSpan('PlanExecutor.resumeRun.loadRunGraph'))
+
+  const snapshot = yield* withTransactionAndEventsEffect({
+    db: databaseService,
+    planEventDeliveryService,
+    run: (tx, emittedEvents) =>
+      Effect.gen(function* () {
+        let currentNodeRuns = [...nodeRuns]
+        for (const currentNodeRun of currentNodeRuns.filter((candidate) => candidate.status === 'running')) {
+          const resetNodeRunRow = yield* fromPromise(() =>
+            tx
+              .update(ensureRecordId(currentNodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(currentNodeRun, {
+                  status: 'ready',
+                  readyAt: nowDate(),
+                  startedAt: currentNodeRun.startedAt ?? nowDate(),
+                }),
+              )
+              .output('after'),
+          )
+          const resetNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, resetNodeRunRow, 'plan node run')
+          currentNodeRuns = currentNodeRuns.map((candidate) =>
+            candidate.nodeId === resetNodeRun.nodeId ? resetNodeRun : candidate,
+          )
+        }
+
+        const resetRun = yield* 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),
+        })
+
+        yield* 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,
+          capturedEvents: emittedEvents,
+        })
+
+        const synced =
+          resetRun.status === 'awaiting-human'
+            ? { run: resetRun, nodeRuns: currentNodeRuns, artifacts }
+            : yield* fromPromise(() =>
+                syncRunGraph(context, {
+                  tx,
+                  run: resetRun,
+                  spec,
+                  nodeSpecs,
+                  nodeRuns: currentNodeRuns,
+                  artifacts,
+                  emittedBy: params.emittedBy,
+                  capturedEvents: emittedEvents,
+                }),
+              )
+
+        const checkpoint = yield* saveCheckpointWithContext(context, {
+          tx,
+          run: synced.run,
+          spec,
+          nodeRuns: synced.nodeRuns,
+          artifacts: synced.artifacts,
+          sequence: nextCheckpointSequence,
+          reason: 'run-resumed',
+          capturedEvents: emittedEvents,
+        })
+        yield* attachCheckpoint(tx, synced.run, checkpoint)
+        const latestRun = yield* planRunService.getRunById(run.id)
+        return yield* serializeRunFull(planRunService, latestRun)
+      }),
+  }).pipe(Effect.withSpan('PlanExecutor.resumeRun.persistTransaction'))
+
+  return buildExecutionPlanToolResult({
+    action: 'run-resumed',
+    plan: snapshot,
+    message: `Resumed execution run "${snapshot.title}".`,
+  })
+})
+
+/** @lintignore */
+function resumeRun(
+  context: PlanExecutorContext,
+  params: { threadId: RecordIdInput; runId: string; emittedBy: string },
+): Promise<ExecutionPlanToolResultData> {
+  return resumeRunEffect(context, params).pipe(runPromise)
+}
+
+const transitionNodeToRunningEffect = Effect.fn('PlanExecutor.transitionNodeToRunning')(function* (
+  context: PlanExecutorContext,
+  params: { runId: string; nodeId: string },
+) {
+  const { databaseService, planRunService } = context
+
+  const run = yield* planRunService.getRunById(params.runId)
+  const nodeRun = yield* planRunService.getNodeRunByNodeId(run.id, params.nodeId)
+  if (nodeRun.status !== 'ready') return
+
+  yield* withDatabaseTransactionEffect(databaseService, (tx) =>
+    Effect.gen(function* () {
+      const runningNodeRunRow = yield* fromPromise(() =>
+        tx
+          .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+          .content(toNodeRunData(nodeRun, { status: 'running', startedAt: nodeRun.startedAt ?? nowDate() }))
+          .output('after'),
+      )
+      const runningNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, runningNodeRunRow, 'plan node run')
+
+      const nodeRuns = yield* planRunService.listNodeRuns(run.id)
+      yield* replaceRun(tx, run, {
+        status: 'running',
+        currentNodeId: runningNodeRun.nodeId,
+        waitingNodeId: null,
+        readyNodeIds: nodeRuns
+          .filter((candidate) => candidate.status === 'ready' && candidate.nodeId !== runningNodeRun.nodeId)
+          .map((candidate) => candidate.nodeId),
+      })
+    }),
+  ).pipe(Effect.withSpan('PlanExecutor.transitionNodeToRunning.persistTransaction'))
+})
+
+/** @lintignore */
+function transitionNodeToRunning(
+  context: PlanExecutorContext,
+  params: { runId: string; nodeId: string },
+): Promise<void> {
+  return transitionNodeToRunningEffect(context, params).pipe(runPromise)
+}
+
+const blockNodeOnDispatchFailureEffect = Effect.fn('PlanExecutor.blockNodeOnDispatchFailure')(function* (
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    message: string
+    failureClass: PlanFailureClass
+  },
+) {
+  const { databaseService, planEventDeliveryService, planRunService } = context
+
+  const run = yield* planRunService.getRunById(params.runId)
+  const spec = yield* planRunService.getPlanSpecById(run.planSpecId)
+  const [nodeSpec, nodeRun, artifacts, nextCheckpointSequence] = yield* Effect.all([
+    planRunService.getNodeSpecByNodeId(spec.id, params.nodeId),
+    planRunService.getNodeRunByNodeId(run.id, params.nodeId),
+    planRunService.listArtifacts(run.id),
+    planRunService.getNextCheckpointSequence(run.id),
+  ]).pipe(Effect.withSpan('PlanExecutor.blockNodeOnDispatchFailure.loadNodeContext'))
+
+  return yield* withTransactionAndEventsEffect({
+    db: databaseService,
+    planEventDeliveryService,
+    run: (tx, emittedEvents) =>
+      Effect.gen(function* () {
+        let blockedNodeRun: PlanNodeRunRecord
+        if (nodeRun.status === 'blocked') {
+          blockedNodeRun = nodeRun
+        } else {
+          const blockedNodeRunRow = yield* fromPromise(() =>
+            tx
+              .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+              .content(
+                toNodeRunData(nodeRun, {
+                  status: 'blocked',
+                  blockedReason: params.message,
+                  failureClass: params.failureClass,
+                }),
+              )
+              .output('after'),
+          )
+          blockedNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, blockedNodeRunRow, 'plan node run')
+        }
+
+        const blockedRun = yield* replaceRun(tx, run, {
+          status: 'blocked',
+          currentNodeId: blockedNodeRun.nodeId,
+          waitingNodeId: null,
+          readyNodeIds: [],
+          failureCount: run.failureCount + 1,
+        })
+
+        yield* emitEvent({
+          tx,
+          run: blockedRun,
+          spec,
+          nodeId: blockedNodeRun.nodeId,
+          eventType: 'node-blocked',
+          fromStatus: nodeRun.status,
+          toStatus: blockedNodeRun.status,
+          message: `Node "${nodeSpec.label}" failed during owner dispatch.`,
+          detail: { failureClass: params.failureClass, phase: 'dispatch', error: params.message },
+          emittedBy: params.emittedBy,
+          capturedEvents: emittedEvents,
+        })
+
+        const checkpointNodeRuns = (yield* planRunService.listNodeRuns(run.id)).map((candidate) =>
+          candidate.nodeId === blockedNodeRun.nodeId ? blockedNodeRun : candidate,
+        )
+        const checkpoint = yield* saveCheckpointWithContext(context, {
+          tx,
+          run: blockedRun,
+          spec,
+          nodeRuns: checkpointNodeRuns,
+          artifacts,
+          sequence: nextCheckpointSequence,
+          reason: 'owner-dispatch-failed',
+          capturedEvents: emittedEvents,
+        })
+        yield* attachCheckpoint(tx, blockedRun, checkpoint)
+        const latestRun = yield* planRunService.getRunById(run.id)
+        return yield* serializeRunFull(planRunService, latestRun)
+      }),
+  }).pipe(Effect.withSpan('PlanExecutor.blockNodeOnDispatchFailure.persistTransaction'))
+})
+
+/** @lintignore */
+function blockNodeOnDispatchFailure(
+  context: PlanExecutorContext,
+  params: {
+    threadId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    message: string
+    failureClass: PlanFailureClass
+  },
+): Promise<SerializableExecutionPlan> {
+  return blockNodeOnDispatchFailureEffect(context, params).pipe(runPromise)
+}
+
+const promoteDelayedNodeEffect = Effect.fn('PlanExecutor.promoteDelayedNode')(function* (
+  context: PlanExecutorContext,
+  params: { runId: string; nodeId: string; emittedBy: string },
+) {
+  const { databaseService, planEventDeliveryService, planRunService } = context
+
+  const run = yield* planRunService.getRunById(params.runId)
+  if (run.status === 'completed' || run.status === 'failed' || run.status === 'aborted') {
+    return
+  }
+
+  const spec = yield* planRunService.getPlanSpecById(run.planSpecId)
+  const nodeSpecs = yield* planRunService.listNodeSpecs(spec.id)
+  const nodeRun = yield* planRunService.getNodeRunByNodeId(run.id, params.nodeId)
+  if (nodeRun.status !== 'scheduled') return
+
+  const [nodeRuns, artifacts, nextCheckpointSequence] = yield* Effect.all([
+    planRunService.listNodeRuns(run.id),
+    planRunService.listArtifacts(run.id),
+    planRunService.getNextCheckpointSequence(run.id),
+  ]).pipe(Effect.withSpan('PlanExecutor.promoteDelayedNode.loadRunContext'))
+
+  yield* withTransactionAndEventsEffect({
+    db: databaseService,
+    planEventDeliveryService,
+    run: (tx, emittedEvents) =>
+      Effect.gen(function* () {
+        const readyNodeRunRow = yield* fromPromise(() =>
+          tx
+            .update(ensureRecordId(nodeRun.id, TABLES.PLAN_NODE_RUN))
+            .content(toNodeRunData(nodeRun, { status: 'ready', readyAt: nowDate() }))
+            .output('after'),
+        )
+        const readyNodeRun = yield* parseRowOrFail(PlanNodeRunSchema, readyNodeRunRow, 'plan node run')
+
+        const updatedNodeRuns = nodeRuns.map((candidate) =>
+          candidate.nodeId === readyNodeRun.nodeId ? readyNodeRun : candidate,
+        )
+
+        const currentNodeSpec = nodeSpecs.find((s) => s.nodeId === params.nodeId)
+        yield* emitEvent({
+          tx,
+          run,
+          spec,
+          nodeId: readyNodeRun.nodeId,
+          eventType: 'node-ready',
+          fromStatus: nodeRun.status,
+          toStatus: readyNodeRun.status,
+          message: `Node "${currentNodeSpec?.label ?? params.nodeId}" promoted to ready after delay.`,
+          emittedBy: params.emittedBy,
+          capturedEvents: emittedEvents,
+        })
+
+        const synced = yield* fromPromise(() =>
+          syncRunGraph(context, {
+            tx,
+            run,
+            spec,
+            nodeSpecs,
+            nodeRuns: updatedNodeRuns,
+            artifacts,
+            emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
+          }),
+        )
+
+        const checkpoint = yield* saveCheckpointWithContext(context, {
+          tx,
+          run: synced.run,
+          spec,
+          nodeRuns: synced.nodeRuns,
+          artifacts: synced.artifacts,
+          sequence: nextCheckpointSequence,
+          reason: 'delayed-node-promoted',
+          capturedEvents: emittedEvents,
+        })
+        yield* attachCheckpoint(tx, synced.run, checkpoint)
+      }),
+  }).pipe(Effect.withSpan('PlanExecutor.promoteDelayedNode.persistTransaction'))
+})
+
+/** @lintignore */
+function promoteDelayedNode(
+  context: PlanExecutorContext,
+  params: { runId: string; nodeId: string; emittedBy: string },
+): Promise<void> {
+  return promoteDelayedNodeEffect(context, params).pipe(runPromise)
+}
+
+export function makePlanExecutorService(deps: PlanExecutorDeps) {
+  const context: PlanExecutorContext = {
+    databaseService: deps.db,
+    generatedDocumentStorageService: deps.storage,
+    artifactService: deps.artifactService,
+    feedbackLoopService: deps.feedbackLoopService,
+    institutionalMemoryService: deps.institutionalMemoryService,
+    planApprovalService: deps.planApprovalService,
+    planArtifactService: deps.planArtifactService,
+    planCheckpointService: deps.planCheckpointService,
+    planCoordinationService: deps.planCoordinationService,
+    planEventDeliveryService: deps.planEventDeliveryService,
+    planRunService: deps.planRunService,
+    planSchedulerService: deps.planSchedulerService,
+    planValidatorService: deps.planValidatorService,
+    qualityMetricsService: deps.qualityMetricsService,
+    planCompletionSideEffects: makePlanCompletionSideEffects({
+      databaseService: deps.db,
+      feedbackLoopService: deps.feedbackLoopService,
+      institutionalMemoryService: deps.institutionalMemoryService,
+      planEventDeliveryService: deps.planEventDeliveryService,
+      planRunService: deps.planRunService,
+      qualityMetricsService: deps.qualityMetricsService,
+    }),
+  }
+
+  return {
+    submitNodeResult: (params: Parameters<typeof submitNodeResult>[1]) => submitNodeResult(context, params),
+    submitNodeResultEffect: (params: Parameters<typeof submitNodeResultEffect>[1]) =>
+      submitNodeResultEffect(context, params),
+    submitHumanNodeResponse: (params: Parameters<typeof submitHumanNodeResponse>[1]) =>
+      submitHumanNodeResponse(context, params),
+    submitHumanNodeResponseEffect: (params: Parameters<typeof submitHumanNodeResponseEffect>[1]) =>
+      submitHumanNodeResponseEffect(context, params),
+    resumeRun: (params: Parameters<typeof resumeRun>[1]) => resumeRun(context, params),
+    resumeRunEffect: (params: Parameters<typeof resumeRunEffect>[1]) => resumeRunEffect(context, params),
+    transitionNodeToRunning: (params: Parameters<typeof transitionNodeToRunning>[1]) =>
+      transitionNodeToRunning(context, params),
+    transitionNodeToRunningEffect: (params: Parameters<typeof transitionNodeToRunningEffect>[1]) =>
+      transitionNodeToRunningEffect(context, params),
+    blockNodeOnDispatchFailure: (params: Parameters<typeof blockNodeOnDispatchFailure>[1]) =>
+      blockNodeOnDispatchFailure(context, params),
+    blockNodeOnDispatchFailureEffect: (params: Parameters<typeof blockNodeOnDispatchFailureEffect>[1]) =>
+      blockNodeOnDispatchFailureEffect(context, params),
+    promoteDelayedNode: (params: Parameters<typeof promoteDelayedNode>[1]) => promoteDelayedNode(context, params),
+    promoteDelayedNodeEffect: (params: Parameters<typeof promoteDelayedNodeEffect>[1]) =>
+      promoteDelayedNodeEffect(context, params),
+    syncRunGraph: (params: Parameters<typeof syncRunGraph>[1]) => syncRunGraph(context, params),
+    resolveFailureAction,
+    buildResolvedInput,
+  }
+}
+
+export class PlanExecutorServiceTag extends Context.Service<PlanExecutorServiceTag, PlanExecutorService>()(
+  '@lota-sdk/core/PlanExecutorService',
+) {}
+
+export const PlanExecutorServiceLive = Layer.effect(
+  PlanExecutorServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const storage = yield* GeneratedDocumentStorageServiceTag
+    return makePlanExecutorService({
+      db,
+      storage,
+      artifactService: yield* ArtifactServiceTag,
+      feedbackLoopService: yield* FeedbackLoopServiceTag,
+      institutionalMemoryService: yield* InstitutionalMemoryServiceTag,
+      planApprovalService: yield* PlanApprovalServiceTag,
+      planArtifactService: yield* PlanArtifactServiceTag,
+      planCheckpointService: yield* PlanCheckpointServiceTag,
+      planCoordinationService: yield* PlanCoordinationServiceTag,
+      planEventDeliveryService: yield* PlanEventDeliveryServiceTag,
+      planRunService: yield* PlanRunServiceTag,
+      planSchedulerService: yield* PlanSchedulerServiceTag,
+      planValidatorService: yield* PlanValidatorServiceTag,
+      qualityMetricsService: yield* QualityMetricsServiceTag,
+    })
+  }),
+)