@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/{plan-helpers.ts → plan/plan-helpers.ts}

@@ -1,4 +1,4 @@
-import { isRecord } from '../utils/string'
+import { isRecord } from '../../utils/string'
 
 export function readPathValue(source: unknown, path: string): unknown {
   if (!path.trim()) return source

package/src/services/{plan-run-data.ts → plan/plan-run-data.ts}

@@ -5,10 +5,10 @@ import type {
   SerializableExecutionPlan,
 } from '@lota-sdk/shared'
 
-import type { RecordIdInput } from '../db/record-id'
-import { ensureRecordId } from '../db/record-id'
-import { TABLES } from '../db/tables'
-import { toDatabaseDateTime } from '../utils/date-time'
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { toDatabaseDateTime } from '../../utils/date-time'
 
 export type PlanRunUpdate = Omit<
   Partial<PlanRunRecord>,

package/src/services/plan/plan-run-serialization.ts

@@ -0,0 +1,15 @@
+import type { PlanRunRecord } from '@lota-sdk/shared'
+
+import type { makePlanRunService } from './plan-run.service'
+
+const FULL_PLAN_SNAPSHOT_OPTIONS = {
+  includeEvents: true,
+  includeArtifacts: true,
+  includeApprovals: true,
+  includeCheckpoints: true,
+  includeValidationIssues: true,
+} as const
+
+export function serializeRunFull(planRunService: ReturnType<typeof makePlanRunService>, run: PlanRunRecord) {
+  return planRunService.toSerializablePlan(run, FULL_PLAN_SNAPSHOT_OPTIONS)
+}

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

@@ -0,0 +1,644 @@
+import {
+  PlanApprovalSchema,
+  PlanArtifactSchema,
+  PlanCheckpointSchema,
+  PlanEventSchema,
+  PlanNodeAttemptSchema,
+  PlanNodeRunSchema,
+  PlanNodeSpecRecordSchema,
+  PlanRunSchema,
+  PlanSpecSchema,
+  PlanValidationIssueSchema,
+} from '@lota-sdk/shared'
+import type {
+  PlanApprovalRecord,
+  PlanArtifactRecord,
+  PlanCheckpointRecord,
+  PlanEventRecord,
+  PlanNodeRunRecord,
+  PlanNodeRunStatus,
+  PlanRunRecord,
+  PlanValidationIssueRecord,
+  SerializablePlanApproval,
+  SerializablePlanArtifact,
+  SerializablePlanCheckpoint,
+  SerializablePlanEvent,
+  SerializablePlanNode,
+  SerializablePlanValidationIssue,
+} from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+import type { RecordId } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { ServiceError } from '../../effect/errors'
+import { DatabaseServiceTag } from '../../effect/services'
+import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../../utils/date-time'
+
+const ACTIVE_RUN_STATUSES = new Set(['pending-approval', 'running', 'awaiting-human', 'blocked'])
+
+function buildProgress(nodeRuns: PlanNodeRunRecord[]) {
+  const counts = nodeRuns.reduce(
+    (summary, nodeRun) => {
+      summary[nodeRun.status] += 1
+      return summary
+    },
+    {
+      pending: 0,
+      ready: 0,
+      running: 0,
+      'awaiting-human': 0,
+      completed: 0,
+      partial: 0,
+      blocked: 0,
+      failed: 0,
+      skipped: 0,
+      scheduled: 0,
+      monitoring: 0,
+    } satisfies Record<PlanNodeRunStatus, number>,
+  )
+
+  const total = nodeRuns.length
+  const completedWork = counts.completed + counts.partial + counts.skipped
+
+  return {
+    total,
+    pending: counts.pending,
+    ready: counts.ready,
+    running: counts.running,
+    awaitingHuman: counts['awaiting-human'],
+    completed: counts.completed,
+    partial: counts.partial,
+    blocked: counts.blocked,
+    failed: counts.failed,
+    skipped: counts.skipped,
+    scheduled: counts.scheduled,
+    monitoring: counts.monitoring,
+    completionRatio: total > 0 ? Number((completedWork / total).toFixed(4)) : undefined,
+  }
+}
+
+function serializeArtifact(artifact: PlanArtifactRecord): SerializablePlanArtifact {
+  return {
+    id: recordIdToString(artifact.id, TABLES.PLAN_ARTIFACT),
+    nodeId: artifact.nodeId,
+    attemptId: recordIdToString(artifact.attemptId, TABLES.PLAN_NODE_ATTEMPT),
+    name: artifact.name,
+    kind: artifact.kind,
+    pointer: artifact.pointer,
+    schemaRef: artifact.schemaRef,
+    description: artifact.description,
+    content: artifact.content,
+    payload: artifact.payload,
+    publishedArtifactId: artifact.publishedArtifactId
+      ? recordIdToString(artifact.publishedArtifactId, TABLES.ARTIFACT)
+      : undefined,
+    createdAt: toIsoDateTimeString(artifact.createdAt),
+  }
+}
+
+function serializeValidationIssue(issue: PlanValidationIssueRecord): SerializablePlanValidationIssue {
+  return {
+    id: recordIdToString(issue.id, TABLES.PLAN_VALIDATION_ISSUE),
+    nodeId: issue.nodeId,
+    attemptId: issue.attemptId ? recordIdToString(issue.attemptId, TABLES.PLAN_NODE_ATTEMPT) : undefined,
+    severity: issue.severity,
+    code: issue.code,
+    message: issue.message,
+    detail: issue.detail,
+    createdAt: toIsoDateTimeString(issue.createdAt),
+  }
+}
+
+function serializeApproval(approval: PlanApprovalRecord): SerializablePlanApproval {
+  return {
+    id: recordIdToString(approval.id, TABLES.PLAN_APPROVAL),
+    nodeId: approval.nodeId,
+    status: approval.status,
+    presented: approval.presented,
+    response: approval.response,
+    requestedBy: approval.requestedBy,
+    respondedBy: approval.respondedBy,
+    approvalMessageId: approval.approvalMessageId,
+    comments: approval.comments,
+    requiredEdits: [...approval.requiredEdits],
+    createdAt: toIsoDateTimeString(approval.createdAt),
+    respondedAt: toOptionalIsoDateTimeString(approval.respondedAt),
+  }
+}
+
+function serializeCheckpoint(checkpoint: PlanCheckpointRecord): SerializablePlanCheckpoint {
+  return {
+    id: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT),
+    sequence: checkpoint.sequence,
+    runStatus: checkpoint.runStatus,
+    readyNodeIds: [...checkpoint.readyNodeIds],
+    activeNodeIds: [...checkpoint.activeNodeIds],
+    artifactIds: checkpoint.artifactIds.map((artifactId) => recordIdToString(artifactId, TABLES.PLAN_ARTIFACT)),
+    lastCompletedNodeIds: [...checkpoint.lastCompletedNodeIds],
+    snapshot: checkpoint.snapshot,
+    createdAt: toIsoDateTimeString(checkpoint.createdAt),
+  }
+}
+
+function serializeEvent(event: PlanEventRecord): SerializablePlanEvent {
+  return {
+    id: recordIdToString(event.id, TABLES.PLAN_EVENT),
+    nodeId: event.nodeId,
+    attemptId: event.attemptId ? recordIdToString(event.attemptId, TABLES.PLAN_NODE_ATTEMPT) : undefined,
+    approvalId: event.approvalId ? recordIdToString(event.approvalId, TABLES.PLAN_APPROVAL) : undefined,
+    eventType: event.eventType,
+    fromStatus: event.fromStatus,
+    toStatus: event.toStatus,
+    message: event.message,
+    detail: event.detail,
+    emittedBy: event.emittedBy,
+    createdAt: toIsoDateTimeString(event.createdAt),
+  }
+}
+
+type PlanRunServiceError = ServiceError
+
+class PlanRunNotFoundError extends Schema.TaggedErrorClass<PlanRunNotFoundError>()('PlanRunNotFoundError', {
+  message: Schema.String,
+  entity: Schema.Literals(['plan spec', 'plan run', 'plan node spec', 'plan node run']),
+  id: Schema.String,
+}) {}
+
+class PlanRunSerializationError extends Schema.TaggedErrorClass<PlanRunSerializationError>()(
+  'PlanRunSerializationError',
+  { message: Schema.String },
+) {}
+
+function tryPlanRunPromise<A>(
+  message: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+): Effect.Effect<A, PlanRunServiceError> {
+  return Effect.suspend(() => {
+    try {
+      const value = thunk()
+      if (Effect.isEffect(value)) {
+        return value.pipe(Effect.mapError((cause) => new ServiceError({ message, cause })))
+      }
+
+      return Effect.tryPromise({
+        try: () => Promise.resolve(value),
+        catch: (cause) => new ServiceError({ message, cause }),
+      })
+    } catch (cause) {
+      return Effect.fail(new ServiceError({ message, cause }))
+    }
+  })
+}
+
+export function makePlanRunService(db: SurrealDBService) {
+  const getPlanSpecByIdEffect = (planSpecId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const planSpecRecordId = ensureRecordId(planSpecId, TABLES.PLAN_SPEC)
+      const spec = yield* tryPlanRunPromise(
+        `Failed to load plan spec ${recordIdToString(planSpecId, TABLES.PLAN_SPEC)}`,
+        () => db.findOne(TABLES.PLAN_SPEC, { id: planSpecRecordId }, PlanSpecSchema),
+      )
+
+      if (!spec) {
+        return yield* new PlanRunNotFoundError({
+          message: `Plan spec not found: ${recordIdToString(planSpecId, TABLES.PLAN_SPEC)}`,
+          entity: 'plan spec',
+          id: recordIdToString(planSpecId, TABLES.PLAN_SPEC),
+        })
+      }
+
+      return spec
+    })
+
+  const listPlanSpecsByThreadEffect = (threadId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan specs for thread ${recordIdToString(threadId, TABLES.THREAD)}`, () =>
+      db.findMany(TABLES.PLAN_SPEC, { threadId: ensureRecordId(threadId, TABLES.THREAD) }, PlanSpecSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'DESC',
+      }),
+    )
+
+  const listRunsBySpecEffect = (planSpecId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan runs for spec ${recordIdToString(planSpecId, TABLES.PLAN_SPEC)}`, () =>
+      db.findMany(TABLES.PLAN_RUN, { planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC) }, PlanRunSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'DESC',
+      }),
+    )
+
+  const listNodeSpecsEffect = (planSpecId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan node specs for spec ${recordIdToString(planSpecId, TABLES.PLAN_SPEC)}`, () =>
+      db.findMany(
+        TABLES.PLAN_NODE_SPEC,
+        { planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC) },
+        PlanNodeSpecRecordSchema,
+        { orderBy: 'position', orderDir: 'ASC' },
+      ),
+    )
+
+  const getNodeSpecByNodeIdEffect = (planSpecId: RecordIdInput, nodeId: string) =>
+    Effect.gen(function* () {
+      const nodeSpec = yield* tryPlanRunPromise(`Failed to load plan node spec "${nodeId}"`, () =>
+        db.findOne(
+          TABLES.PLAN_NODE_SPEC,
+          { planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC), nodeId },
+          PlanNodeSpecRecordSchema,
+        ),
+      )
+
+      if (!nodeSpec) {
+        return yield* new PlanRunNotFoundError({
+          message: `Plan node spec "${nodeId}" not found.`,
+          entity: 'plan node spec',
+          id: nodeId,
+        })
+      }
+
+      return nodeSpec
+    })
+
+  const getRunByIdEffect = (runId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const runRecordId = ensureRecordId(runId, TABLES.PLAN_RUN)
+      const run = yield* tryPlanRunPromise(`Failed to load plan run ${recordIdToString(runId, TABLES.PLAN_RUN)}`, () =>
+        db.findOne(TABLES.PLAN_RUN, { id: runRecordId }, PlanRunSchema),
+      )
+
+      if (!run) {
+        return yield* new PlanRunNotFoundError({
+          message: `Plan run not found: ${recordIdToString(runId, TABLES.PLAN_RUN)}`,
+          entity: 'plan run',
+          id: recordIdToString(runId, TABLES.PLAN_RUN),
+        })
+      }
+
+      return run
+    })
+
+  const getActiveRunRecordsEffect = (threadId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const runs = yield* tryPlanRunPromise(
+        `Failed to load active plan runs for thread ${recordIdToString(threadId, TABLES.THREAD)}`,
+        () =>
+          db.findMany(TABLES.PLAN_RUN, { threadId: ensureRecordId(threadId, TABLES.THREAD) }, PlanRunSchema, {
+            orderBy: 'updatedAt',
+            orderDir: 'DESC',
+          }),
+      )
+      return runs.filter((run) => ACTIVE_RUN_STATUSES.has(run.status))
+    })
+
+  const getActiveRunRecordEffect = (threadId: RecordIdInput) =>
+    Effect.map(getActiveRunRecordsEffect(threadId), (runs) => (runs.length > 0 ? runs[0] : null))
+
+  const getRunsCreatedInContextEffect = (params: {
+    organizationId: RecordIdInput
+    sourceThreadId?: RecordIdInput
+    createdByAgentId?: string
+    statuses?: ReadonlyArray<PlanRunRecord['status']>
+  }) =>
+    Effect.gen(function* () {
+      const filter: Record<string, unknown> = {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+      }
+      if (params.sourceThreadId) {
+        filter.sourceThreadId = ensureRecordId(params.sourceThreadId, TABLES.THREAD)
+      }
+      if (params.createdByAgentId) {
+        filter.createdByAgentId = params.createdByAgentId
+      }
+
+      const statuses = params.statuses ? new Set(params.statuses) : ACTIVE_RUN_STATUSES
+      const runs = yield* tryPlanRunPromise(
+        `Failed to load execution plans in context ${recordIdToString(params.organizationId, TABLES.ORGANIZATION)}`,
+        () => db.findMany(TABLES.PLAN_RUN, filter, PlanRunSchema, { orderBy: 'updatedAt', orderDir: 'DESC' }),
+      )
+      return runs.filter((run) => statuses.has(run.status))
+    })
+
+  const listNodeRunsEffect = (runId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan node runs for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`, () =>
+      db.findMany(TABLES.PLAN_NODE_RUN, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanNodeRunSchema, {
+        orderBy: 'nodeId',
+        orderDir: 'ASC',
+      }),
+    )
+
+  const getNodeRunByNodeIdEffect = (runId: RecordIdInput, nodeId: string) =>
+    Effect.gen(function* () {
+      const nodeRun = yield* tryPlanRunPromise(`Failed to load plan node run "${nodeId}"`, () =>
+        db.findOne(TABLES.PLAN_NODE_RUN, { runId: ensureRecordId(runId, TABLES.PLAN_RUN), nodeId }, PlanNodeRunSchema),
+      )
+
+      if (!nodeRun) {
+        return yield* new PlanRunNotFoundError({
+          message: `Plan node run "${nodeId}" not found.`,
+          entity: 'plan node run',
+          id: nodeId,
+        })
+      }
+
+      return nodeRun
+    })
+
+  const listArtifactsEffect = (runId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan artifacts for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`, () =>
+      db.findMany(TABLES.PLAN_ARTIFACT, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanArtifactSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'ASC',
+      }),
+    )
+
+  const listAttemptsEffect = (runId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan attempts for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`, () =>
+      db.findMany(TABLES.PLAN_NODE_ATTEMPT, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanNodeAttemptSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'ASC',
+      }),
+    )
+
+  const listValidationIssuesEffect = (params: {
+    runId?: RecordIdInput
+    planSpecId?: RecordIdInput
+    attemptId?: RecordIdInput
+  }) =>
+    Effect.gen(function* () {
+      const filter: Record<string, unknown> = {}
+      if (params.runId) filter.runId = ensureRecordId(params.runId, TABLES.PLAN_RUN)
+      if (params.planSpecId) filter.planSpecId = ensureRecordId(params.planSpecId, TABLES.PLAN_SPEC)
+      if (params.attemptId) filter.attemptId = ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT)
+
+      return yield* tryPlanRunPromise('Failed to load plan validation issues', () =>
+        db.findMany(TABLES.PLAN_VALIDATION_ISSUE, filter, PlanValidationIssueSchema, {
+          orderBy: 'createdAt',
+          orderDir: 'ASC',
+        }),
+      )
+    })
+
+  const listApprovalsEffect = (runId: RecordIdInput) =>
+    tryPlanRunPromise(`Failed to load plan approvals for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`, () =>
+      db.findMany(TABLES.PLAN_APPROVAL, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanApprovalSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'ASC',
+      }),
+    )
+
+  const getLatestCheckpointEffect = (runId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const checkpoints = yield* tryPlanRunPromise(
+        `Failed to load latest checkpoint for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`,
+        () =>
+          db.findMany(TABLES.PLAN_CHECKPOINT, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanCheckpointSchema, {
+            orderBy: 'sequence',
+            orderDir: 'DESC',
+            limit: 1,
+          }),
+      )
+      return checkpoints.at(0) ?? null
+    })
+
+  const getNextCheckpointSequenceEffect = (runId: RecordIdInput) =>
+    Effect.map(getLatestCheckpointEffect(runId), (latestCheckpoint) =>
+      latestCheckpoint ? latestCheckpoint.sequence + 1 : 1,
+    )
+
+  const listEventsEffect = (runId: RecordIdInput, limit = 20) =>
+    Effect.gen(function* () {
+      const events = yield* tryPlanRunPromise(
+        `Failed to load plan events for run ${recordIdToString(runId, TABLES.PLAN_RUN)}`,
+        () =>
+          db.findMany(TABLES.PLAN_EVENT, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanEventSchema, {
+            orderBy: 'createdAt',
+            orderDir: 'DESC',
+            limit,
+          }),
+      )
+      return [...events].reverse()
+    })
+
+  const collectLineageArtifactsEffect = (run: PlanRunRecord) =>
+    Effect.gen(function* () {
+      const collect = (
+        currentRunId: RecordId | null,
+        depth: number,
+      ): Effect.Effect<SerializablePlanArtifact[], PlanRunServiceError | PlanRunNotFoundError> =>
+        Effect.gen(function* () {
+          if (!currentRunId || depth >= 5) {
+            return []
+          }
+
+          const previousRun = yield* tryPlanRunPromise(
+            `Failed to load lineage run ${recordIdToString(currentRunId, TABLES.PLAN_RUN)}`,
+            () => db.findOne(TABLES.PLAN_RUN, { id: currentRunId }, PlanRunSchema),
+          )
+          if (!previousRun) {
+            return []
+          }
+
+          const [olderArtifacts, artifacts] = yield* Effect.all([
+            collect(
+              previousRun.replacedRunId ? ensureRecordId(previousRun.replacedRunId, TABLES.PLAN_RUN) : null,
+              depth + 1,
+            ),
+            listArtifactsEffect(previousRun.id),
+          ])
+
+          return [...olderArtifacts, ...artifacts.map(serializeArtifact)]
+        })
+
+      return yield* collect(run.replacedRunId ? ensureRecordId(run.replacedRunId, TABLES.PLAN_RUN) : null, 0)
+    })
+
+  const toSerializablePlanEffect = (
+    run: PlanRunRecord,
+    options?: {
+      includeArtifacts?: boolean
+      includeApprovals?: boolean
+      includeCheckpoints?: boolean
+      includeEvents?: boolean
+      includeValidationIssues?: boolean
+      slim?: boolean
+    },
+  ) =>
+    Effect.gen(function* () {
+      const slim = options?.slim === true
+      const spec = yield* getPlanSpecByIdEffect(run.planSpecId)
+      const [
+        nodeSpecs,
+        nodeRuns,
+        artifacts,
+        lineageArtifacts,
+        approvals,
+        validationIssues,
+        latestCheckpoint,
+        recentEvents,
+      ] = yield* Effect.all([
+        listNodeSpecsEffect(spec.id),
+        listNodeRunsEffect(run.id),
+        options?.includeArtifacts === false ? Effect.succeed<PlanArtifactRecord[]>([]) : listArtifactsEffect(run.id),
+        options?.includeArtifacts === false || slim
+          ? Effect.succeed<SerializablePlanArtifact[]>([])
+          : collectLineageArtifactsEffect(run),
+        options?.includeApprovals === false || slim
+          ? Effect.succeed<PlanApprovalRecord[]>([])
+          : listApprovalsEffect(run.id),
+        options?.includeValidationIssues === false || slim
+          ? Effect.succeed<PlanValidationIssueRecord[]>([])
+          : listValidationIssuesEffect({ runId: run.id, planSpecId: spec.id }),
+        options?.includeCheckpoints
+          ? getLatestCheckpointEffect(run.id)
+          : Effect.succeed<PlanCheckpointRecord | null>(null),
+        options?.includeEvents === false
+          ? Effect.succeed<PlanEventRecord[]>([])
+          : listEventsEffect(run.id, slim ? 5 : 20),
+      ])
+
+      const nodeRunsById = new Map(nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
+      const activeNodeIds = new Set(run.currentNodeId ? [run.currentNodeId] : [])
+      const readyNodeIds = new Set(run.readyNodeIds)
+
+      const nodes: SerializablePlanNode[] = []
+      for (const nodeSpec of nodeSpecs) {
+        const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+        if (!nodeRun) {
+          return yield* new PlanRunSerializationError({
+            message: `Plan run ${recordIdToString(run.id, TABLES.PLAN_RUN)} is missing node run "${nodeSpec.nodeId}".`,
+          })
+        }
+
+        const isActiveOrReady = activeNodeIds.has(nodeSpec.nodeId) || readyNodeIds.has(nodeSpec.nodeId)
+
+        if (slim && !isActiveOrReady) {
+          nodes.push({
+            id: nodeSpec.nodeId,
+            type: nodeSpec.type,
+            label: nodeSpec.label,
+            owner: { executorType: nodeSpec.owner.executorType, ref: nodeSpec.owner.ref },
+            objective: nodeSpec.objective,
+            status: nodeRun.status,
+            upstreamNodeIds: [...nodeSpec.upstreamNodeIds],
+            downstreamNodeIds: [...nodeSpec.downstreamNodeIds],
+            ...(nodeRun.completedAt ? { completedAt: toOptionalIsoDateTimeString(nodeRun.completedAt) } : {}),
+          } as SerializablePlanNode)
+          continue
+        }
+
+        nodes.push({
+          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,
+          },
+          executionVisibility: nodeSpec.executionVisibility,
+          schedule: nodeSpec.schedule,
+          deadline: nodeSpec.deadline,
+          escalation: nodeSpec.escalation,
+          monitoringConfig: nodeSpec.monitoringConfig,
+          delayAfterPredecessorMs: nodeSpec.delayAfterPredecessorMs,
+          deliberationConfig: nodeSpec.deliberationConfig,
+          status: nodeRun.status,
+          attemptCount: nodeRun.attemptCount,
+          retryCount: nodeRun.retryCount,
+          resolvedInput: nodeRun.resolvedInput,
+          latestStructuredOutput: nodeRun.latestStructuredOutput,
+          latestNotes: nodeRun.latestNotes,
+          blockedReason: nodeRun.blockedReason,
+          failureClass: nodeRun.failureClass,
+          upstreamNodeIds: [...nodeSpec.upstreamNodeIds],
+          downstreamNodeIds: [...nodeSpec.downstreamNodeIds],
+          readyAt: toOptionalIsoDateTimeString(nodeRun.readyAt),
+          startedAt: toOptionalIsoDateTimeString(nodeRun.startedAt),
+          completedAt: toOptionalIsoDateTimeString(nodeRun.completedAt),
+        })
+      }
+
+      return {
+        specId: recordIdToString(spec.id, TABLES.PLAN_SPEC),
+        runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+        threadId: recordIdToString(run.threadId, TABLES.THREAD),
+        sourceThreadId: run.sourceThreadId ? recordIdToString(run.sourceThreadId, TABLES.THREAD) : undefined,
+        organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+        title: spec.title,
+        objective: spec.objective,
+        version: spec.version,
+        status: run.status,
+        leadAgentId: run.leadAgentId,
+        createdByAgentId: run.createdByAgentId,
+        defaultExecutionVisibility: spec.defaultExecutionVisibility,
+        executionMode: spec.executionMode,
+        schemaRegistry: slim ? {} : structuredClone(spec.schemaRegistry),
+        entryNodeIds: [...spec.entryNodeIds],
+        edges: [...spec.edges],
+        schedule: spec.schedule,
+        activeNodeIds: run.currentNodeId ? [run.currentNodeId] : [],
+        readyNodeIds: [...run.readyNodeIds],
+        waitingNodeId: run.waitingNodeId,
+        replacedRunId: run.replacedRunId ? recordIdToString(run.replacedRunId, TABLES.PLAN_RUN) : undefined,
+        failureCount: run.failureCount,
+        startedAt: toOptionalIsoDateTimeString(run.startedAt),
+        completedAt: toOptionalIsoDateTimeString(run.completedAt),
+        progress: buildProgress(nodeRuns),
+        nodes,
+        artifacts: artifacts.map(serializeArtifact),
+        lineageArtifacts,
+        validationIssues: validationIssues.map(serializeValidationIssue),
+        approvals: approvals.map(serializeApproval),
+        latestCheckpoint: latestCheckpoint ? serializeCheckpoint(latestCheckpoint) : null,
+        recentEvents: recentEvents.map(serializeEvent),
+      }
+    })
+
+  return {
+    getPlanSpecById: getPlanSpecByIdEffect,
+    listPlanSpecsByThread: listPlanSpecsByThreadEffect,
+    listRunsBySpec: listRunsBySpecEffect,
+    listNodeSpecs: listNodeSpecsEffect,
+    getNodeSpecByNodeId: getNodeSpecByNodeIdEffect,
+    getRunById: getRunByIdEffect,
+    getActiveRunRecord: getActiveRunRecordEffect,
+    getActiveRunRecords: getActiveRunRecordsEffect,
+    getRunsCreatedInContext: getRunsCreatedInContextEffect,
+    listNodeRuns: listNodeRunsEffect,
+    getNodeRunByNodeId: getNodeRunByNodeIdEffect,
+    listArtifacts: listArtifactsEffect,
+    listAttempts: listAttemptsEffect,
+    listValidationIssues: listValidationIssuesEffect,
+    listApprovals: listApprovalsEffect,
+    getLatestCheckpoint: getLatestCheckpointEffect,
+    getNextCheckpointSequence: getNextCheckpointSequenceEffect,
+    listEvents: listEventsEffect,
+    toSerializablePlan: toSerializablePlanEffect,
+    collectLineageArtifacts: collectLineageArtifactsEffect,
+  }
+}
+
+export class PlanRunServiceTag extends Context.Service<PlanRunServiceTag, ReturnType<typeof makePlanRunService>>()(
+  'PlanRunService',
+) {}
+
+export const PlanRunServiceLive = Layer.effect(
+  PlanRunServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    return makePlanRunService(db)
+  }),
+)