@lota-sdk/core 0.4.7 → 0.4.9

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

@@ -0,0 +1,60 @@
+import { PlanArtifactSchema } from '@lota-sdk/shared'
+import type { PlanArtifactRecord, PlanArtifactSubmission } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
+import { RecordId } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import type { DatabaseTransaction } from '../../db/service'
+import { TABLES } from '../../db/tables'
+
+export function makePlanArtifactService() {
+  return {
+    persistArtifacts(params: {
+      tx: DatabaseTransaction
+      runId: RecordIdInput
+      attemptId: RecordIdInput
+      nodeId: string
+      artifacts: PlanArtifactSubmission[]
+    }) {
+      return Effect.gen(function* () {
+        const records: PlanArtifactRecord[] = []
+
+        // Sequential: SurrealDB transactions require ordered operations
+        for (const artifact of params.artifacts) {
+          const artifactId = new RecordId(TABLES.PLAN_ARTIFACT, Bun.randomUUIDv7())
+          const created = yield* params.tx
+            .create(artifactId)
+            .content({
+              runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+              attemptId: ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT),
+              nodeId: params.nodeId,
+              name: artifact.name,
+              kind: artifact.kind,
+              pointer: artifact.publishedArtifactId
+                ? `venturos://artifact/${artifact.publishedArtifactId}`
+                : `artifact://${params.nodeId}/${artifact.name}`,
+              ...(artifact.description ? { description: artifact.description } : {}),
+              ...(artifact.content ? { content: artifact.content } : {}),
+              ...(artifact.payload ? { payload: artifact.payload } : {}),
+              ...(artifact.publishedArtifactId
+                ? { publishedArtifactId: ensureRecordId(artifact.publishedArtifactId, TABLES.ARTIFACT) }
+                : {}),
+            })
+            .output('after')
+
+          records.push(PlanArtifactSchema.parse(created))
+        }
+
+        return records
+      })
+    },
+  }
+}
+
+export class PlanArtifactServiceTag extends Context.Service<
+  PlanArtifactServiceTag,
+  ReturnType<typeof makePlanArtifactService>
+>()('PlanArtifactService') {}
+
+export const PlanArtifactServiceLive = Layer.succeed(PlanArtifactServiceTag, makePlanArtifactService())

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

@@ -0,0 +1,76 @@
+import type { PlanDraft } from '@lota-sdk/shared'
+import { Context, Layer } from 'effect'
+
+import { isExecutableConditionExpression } from './plan-helpers'
+
+function buildImplicitLinearEdges(draft: PlanDraft) {
+  if (draft.edges.length > 0 || draft.nodes.length <= 1) {
+    return draft.edges
+  }
+
+  return draft.nodes
+    .slice(0, -1)
+    .map((node, index) => ({
+      id: `edge_${node.id}_to_${draft.nodes[index + 1]?.id ?? index + 1}`,
+      source: node.id,
+      target: draft.nodes[index + 1].id,
+      map: {},
+    }))
+}
+
+function structureDesign(draft: PlanDraft): PlanDraft {
+  return {
+    ...draft,
+    executionMode: draft.executionMode ?? 'linear',
+    edges: buildImplicitLinearEdges(draft),
+    entryNodeIds: draft.entryNodeIds && draft.entryNodeIds.length > 0 ? draft.entryNodeIds : [draft.nodes[0].id],
+  }
+}
+
+function semanticCompletion(draft: PlanDraft): PlanDraft {
+  return {
+    ...draft,
+    nodes: draft.nodes.map((node) => ({
+      ...node,
+      deliverables: [...node.deliverables],
+      successCriteria: [...node.successCriteria],
+      completionChecks: [...node.completionChecks],
+      failurePolicy: [...node.failurePolicy],
+      retryPolicy: { ...node.retryPolicy, retryOn: [...node.retryPolicy.retryOn] },
+      toolPolicy: { allow: [...node.toolPolicy.allow], deny: [...node.toolPolicy.deny] },
+      contextPolicy: {
+        retrievalScopes: [...node.contextPolicy.retrievalScopes],
+        attachmentPolicy: node.contextPolicy.attachmentPolicy,
+        webPolicy: node.contextPolicy.webPolicy,
+      },
+    })),
+    edges: draft.edges.map((edge) => {
+      const normalizedWhen = edge.when?.trim()
+      const { when: _when, ...edgeWithoutWhen } = edge
+      return {
+        ...edgeWithoutWhen,
+        ...(normalizedWhen && isExecutableConditionExpression(normalizedWhen) ? { when: normalizedWhen } : {}),
+        map: { ...edge.map },
+      }
+    }),
+    schemas: structuredClone(draft.schemas),
+    entryNodeIds: [...(draft.entryNodeIds ?? [])],
+  }
+}
+
+export function makePlanBuilderService() {
+  return {
+    structureDesign,
+    semanticCompletion,
+    prepareDraft(draft: PlanDraft): PlanDraft {
+      return semanticCompletion(structureDesign(draft))
+    },
+  }
+}
+
+export class PlanBuilderServiceTag extends Context.Service<
+  PlanBuilderServiceTag,
+  ReturnType<typeof makePlanBuilderService>
+>()('PlanBuilderService') {}
+
+export const PlanBuilderServiceLive = Layer.succeed(PlanBuilderServiceTag, makePlanBuilderService())

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

@@ -0,0 +1,103 @@
+import { PlanCheckpointSchema } from '@lota-sdk/shared'
+import type { PlanRunStatus } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
+import { RecordId } from 'surrealdb'
+
+import { serverLogger } from '../../config/logger'
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService, DatabaseTransaction } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { DatabaseServiceTag } from '../../effect/services'
+import type { makePlanWorkspaceService } from './plan-workspace.service'
+import { PlanWorkspaceServiceTag } from './plan-workspace.service'
+
+interface PlanCheckpointDeps {
+  db: SurrealDBService
+  planWorkspaceService: ReturnType<typeof makePlanWorkspaceService>
+}
+
+export function makePlanCheckpointService(deps: PlanCheckpointDeps) {
+  const { db, planWorkspaceService } = deps
+
+  return {
+    createCheckpoint: (params: {
+      tx: DatabaseTransaction
+      runId: RecordIdInput
+      sequence: number
+      runStatus: PlanRunStatus
+      readyNodeIds: string[]
+      activeNodeIds: string[]
+      artifactIds: RecordIdInput[]
+      lastCompletedNodeIds: string[]
+      snapshot: Record<string, unknown>
+      includeWorkspace?: boolean
+    }) =>
+      Effect.gen(function* () {
+        const snapshotData = { ...params.snapshot }
+
+        if (params.includeWorkspace) {
+          const runIdStr = recordIdToString(params.runId, TABLES.PLAN_RUN)
+          const workspaceSnapshotEffect = planWorkspaceService.currentRead({ runId: runIdStr }).pipe(
+            Effect.map((all: Record<string, { writeSequence: number }>) => {
+              const filtered: Record<string, unknown> = {}
+              for (const [key, entry] of Object.entries(all)) {
+                if (entry.writeSequence <= params.sequence) {
+                  filtered[key] = entry
+                }
+              }
+              return filtered
+            }),
+            Effect.orElseSucceed(() => {
+              serverLogger.warn`Workspace snapshot failed for run ${runIdStr}`
+              return {} as Record<string, unknown>
+            }),
+          )
+          const workspaceSnapshot: Record<string, unknown> = yield* workspaceSnapshotEffect
+          if (Object.keys(workspaceSnapshot).length > 0) {
+            snapshotData.workspaceSnapshot = workspaceSnapshot
+          }
+        }
+
+        const checkpointId = new RecordId(TABLES.PLAN_CHECKPOINT, Bun.randomUUIDv7())
+        const created = yield* params.tx
+          .create(checkpointId)
+          .content({
+            runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+            sequence: params.sequence,
+            runStatus: params.runStatus,
+            readyNodeIds: [...params.readyNodeIds],
+            activeNodeIds: [...params.activeNodeIds],
+            artifactIds: params.artifactIds.map((artifactId) => ensureRecordId(artifactId, TABLES.PLAN_ARTIFACT)),
+            lastCompletedNodeIds: [...params.lastCompletedNodeIds],
+            snapshot: snapshotData,
+          })
+          .output('after')
+
+        return PlanCheckpointSchema.parse(created)
+      }),
+
+    loadLatestForRun: (runId: RecordIdInput) =>
+      db
+        .findMany(TABLES.PLAN_CHECKPOINT, { runId: ensureRecordId(runId, TABLES.PLAN_RUN) }, PlanCheckpointSchema, {
+          orderBy: 'sequence',
+          orderDir: 'DESC',
+          limit: 1,
+        })
+        .pipe(Effect.map((checkpoints) => checkpoints.at(0) ?? null)),
+  }
+}
+
+export class PlanCheckpointServiceTag extends Context.Service<
+  PlanCheckpointServiceTag,
+  ReturnType<typeof makePlanCheckpointService>
+>()('PlanCheckpointService') {}
+
+export const PlanCheckpointServiceLive = Layer.effect(
+  PlanCheckpointServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const planWorkspaceService = yield* PlanWorkspaceServiceTag
+    return makePlanCheckpointService({ db, planWorkspaceService })
+  }),
+)

package/src/services/{plan-compiler.service.ts → plan/plan-compiler.service.ts}

@@ -1,6 +1,9 @@
 import type { PlanDraft, PlanNodeSpec, PlanNodeSpecRecord } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
 
-import { planValidatorService } from './plan-validator.service'
+import { ValidationError } from '../../effect/errors'
+import type { makePlanValidatorService } from './plan-validator.service'
+import { PlanValidatorServiceTag } from './plan-validator.service'
 
 export interface CompiledPlanNode {
   node: PlanNodeSpec
@@ -14,12 +17,14 @@ interface CompiledPlanDraft {
   nodes: CompiledPlanNode[]
 }
 
-class PlanCompilerService {
-  compile(draft: PlanDraft): CompiledPlanDraft {
+export function makePlanCompilerService(planValidatorService: ReturnType<typeof makePlanValidatorService>) {
+  function compile(draft: PlanDraft): Effect.Effect<CompiledPlanDraft, ValidationError> {
     const validation = planValidatorService.validateDraft(draft)
     if (validation.blocking.length > 0) {
-      throw new Error(
-        `Plan draft failed validation: ${validation.blocking.map((issue) => `${issue.code}: ${issue.message}`).join(' | ')}`,
+      return Effect.fail(
+        new ValidationError({
+          message: `Plan draft failed validation: ${validation.blocking.map((issue) => `${issue.code}: ${issue.message}`).join(' | ')}`,
+        }),
       )
     }
 
@@ -36,7 +41,7 @@ class PlanCompilerService {
       downstreamByNodeId.get(edge.source)?.push(edge.target)
     }
 
-    return {
+    return Effect.succeed({
       draft,
       nodes: draft.nodes.map((node, index) => ({
         node,
@@ -44,10 +49,10 @@ class PlanCompilerService {
         upstreamNodeIds: [...(upstreamByNodeId.get(node.id) ?? [])],
         downstreamNodeIds: [...(downstreamByNodeId.get(node.id) ?? [])],
       })),
-    }
+    })
   }
 
-  toNodeSpecRecords(
+  function toNodeSpecRecords(
     compiled: CompiledPlanDraft,
   ): Array<Omit<PlanNodeSpecRecord, 'id' | 'planSpecId' | 'createdAt' | 'updatedAt'>> {
     return compiled.nodes.map(({ node, position, upstreamNodeIds, downstreamNodeIds }) => ({
@@ -83,6 +88,18 @@ class PlanCompilerService {
       downstreamNodeIds,
     }))
   }
+
+  return { compile, toNodeSpecRecords }
 }
 
-export const planCompilerService = new PlanCompilerService()
+export class PlanCompilerServiceTag extends Context.Service<
+  PlanCompilerServiceTag,
+  ReturnType<typeof makePlanCompilerService>
+>()('PlanCompilerService') {}
+
+export const PlanCompilerServiceLive = Layer.effect(
+  PlanCompilerServiceTag,
+  Effect.map(PlanValidatorServiceTag.asEffect(), (planValidatorService) =>
+    makePlanCompilerService(planValidatorService),
+  ),
+)

package/src/services/plan/plan-completion-side-effects.ts

@@ -0,0 +1,175 @@
+import type { PlanNodeOwner, PlanNodeType } from '@lota-sdk/shared'
+import { PlanEventSchema } from '@lota-sdk/shared'
+import { Schema, Effect, Metric } from 'effect'
+
+import { aiLogger } from '../../config/logger'
+import { ensureRecordId } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { runPromise } from '../../effect/runtime'
+import { nowEpochMillis, unsafeDateFrom } from '../../utils/date-time'
+import type { makeFeedbackLoopService } from '../feedback-loop.service'
+import type { makeInstitutionalMemoryService } from '../institutional-memory.service'
+import type { makeQualityMetricsService } from '../quality-metrics.service'
+import type { makePlanEventDeliveryService } from './plan-event-delivery.service'
+import type { makePlanRunService } from './plan-run.service'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+const planNodeExecutionDuration = Metric.histogram('plan_node_execution_duration_ms', {
+  boundaries: Metric.boundariesFromIterable([100, 500, 1000, 5000, 10_000, 30_000, 60_000]),
+})
+
+interface PlanCompletionSideEffectsDeps {
+  databaseService: SurrealDBService
+  feedbackLoopService: ReturnType<typeof makeFeedbackLoopService>
+  institutionalMemoryService: ReturnType<typeof makeInstitutionalMemoryService>
+  planEventDeliveryService: ReturnType<typeof makePlanEventDeliveryService>
+  planRunService: ReturnType<typeof makePlanRunService>
+  qualityMetricsService: ReturnType<typeof makeQualityMetricsService>
+}
+
+class PlanCompletionSideEffectsError extends Schema.TaggedErrorClass<PlanCompletionSideEffectsError>()(
+  'PlanCompletionSideEffectsError',
+  { message: Schema.String, cause: Schema.Defect },
+) {}
+
+function tryPlanCompletionPromise<A>(
+  message: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+): Effect.Effect<A, PlanCompletionSideEffectsError> {
+  return Effect.suspend(() => {
+    try {
+      const value = thunk()
+      if (Effect.isEffect(value)) {
+        return value.pipe(Effect.mapError((cause) => new PlanCompletionSideEffectsError({ message, cause })))
+      }
+
+      return Effect.tryPromise({
+        try: () => Promise.resolve(value),
+        catch: (cause) => new PlanCompletionSideEffectsError({ message, cause }),
+      })
+    } catch (cause) {
+      return Effect.fail(new PlanCompletionSideEffectsError({ message, cause }))
+    }
+  })
+}
+
+export function makePlanCompletionSideEffects({
+  databaseService,
+  feedbackLoopService,
+  institutionalMemoryService,
+  planEventDeliveryService,
+  planRunService,
+  qualityMetricsService,
+}: PlanCompletionSideEffectsDeps) {
+  function runPlanNodeCompletionSideEffects(params: {
+    runId: string
+    organizationId: string
+    nodeId: string
+    nodeLabel: string
+    nodeOwnerRef: string
+    nodeOwnerType: PlanNodeOwner['executorType']
+    nodeType: PlanNodeType
+    nodeStartedAt?: string | Date | null
+    nodeAttemptCount: number
+    artifactCount: number
+    validationIssues: PlanValidationIssueInput[]
+  }): Promise<void> {
+    return runPromise(
+      Effect.gen(function* () {
+        const executionTimeMs = params.nodeStartedAt
+          ? nowEpochMillis() - unsafeDateFrom(params.nodeStartedAt).getTime()
+          : 0
+        if (executionTimeMs > 0) {
+          yield* Metric.update(
+            Metric.withAttributes(planNodeExecutionDuration, { nodeType: params.nodeType }),
+            executionTimeMs,
+          )
+        }
+        yield* qualityMetricsService.recordNodeMetrics({
+          organizationId: params.organizationId,
+          runId: params.runId,
+          nodeId: params.nodeId,
+          metrics: {
+            executionTimeMs: Math.max(0, executionTimeMs),
+            attemptCount: params.nodeAttemptCount,
+            artifactCount: params.artifactCount,
+            validationIssueCount: params.validationIssues.length,
+            ownerRef: params.nodeOwnerRef,
+            ownerType: params.nodeOwnerType,
+            nodeType: params.nodeType,
+          },
+        })
+      }),
+    )
+  }
+
+  function runPlanCompletionSideEffects(params: { runId: string; organizationId: string }): Promise<void> {
+    return runPromise(
+      Effect.gen(function* () {
+        yield* qualityMetricsService.recordCycleMetrics({ organizationId: params.organizationId, runId: params.runId })
+
+        const recommendations = yield* feedbackLoopService
+          .analyzeOutcomes({ runId: params.runId, organizationId: params.organizationId })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new PlanCompletionSideEffectsError({ message: 'Failed to analyze plan feedback outcomes.', cause }),
+            ),
+          )
+        if (recommendations.length > 0) {
+          const run = yield* planRunService.getRunById(params.runId)
+          const specRecord = yield* planRunService.getPlanSpecById(run.planSpecId)
+          const event = yield* tryPlanCompletionPromise('Failed to create feedback analyzed plan event.', () =>
+            databaseService.create(
+              TABLES.PLAN_EVENT,
+              {
+                planSpecId: ensureRecordId(specRecord.id, TABLES.PLAN_SPEC),
+                runId: ensureRecordId(run.id, TABLES.PLAN_RUN),
+                eventType: 'feedback-analyzed',
+                message: `Feedback analysis produced ${recommendations.length} recommendation(s).`,
+                detail: { recommendations },
+                emittedBy: 'system',
+              },
+              PlanEventSchema,
+            ),
+          )
+          yield* Effect.tryPromise({
+            try: () => planEventDeliveryService.dispatchEvent(event),
+            catch: (cause) =>
+              new PlanCompletionSideEffectsError({
+                message: 'Failed to dispatch feedback analyzed plan event.',
+                cause,
+              }),
+          })
+        }
+
+        yield* institutionalMemoryService
+          .extractPatterns({ organizationId: params.organizationId, runId: params.runId })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new PlanCompletionSideEffectsError({
+                  message: 'Failed to extract institutional memory patterns.',
+                  cause,
+                }),
+            ),
+          )
+      }),
+    )
+  }
+
+  function runPlanCompletionSideEffectsSafely(params: { runId: string; organizationId: string }): Promise<void> {
+    return runPromise(
+      Effect.catch(
+        tryPlanCompletionPromise('Plan completion side effects failed.', () => runPlanCompletionSideEffects(params)),
+        (error: unknown) =>
+          Effect.sync(() => {
+            aiLogger.warn`Plan completion side effects failed for run ${params.runId}: ${error instanceof Error ? error.message : String(error)}`
+          }),
+      ),
+    )
+  }
+
+  return { runPlanNodeCompletionSideEffects, runPlanCompletionSideEffectsSafely }
+}

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

@@ -0,0 +1,181 @@
+import type { PlanArtifactRecord, PlanDependency } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+
+import { serverLogger } from '../../config/logger'
+import { recordIdToString } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { nowEpochMillis } from '../../utils/date-time'
+import type { makePlanRunService } from './plan-run.service'
+import { PlanRunServiceTag } from './plan-run.service'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+export interface DependencyResolutionResult {
+  resolved: Map<string, PlanArtifactRecord>
+  unresolved: PlanDependency[]
+  notifications: Array<{ dependency: PlanDependency; reason: string }>
+}
+
+class PlanCoordinationError extends Schema.TaggedErrorClass<PlanCoordinationError>()('PlanCoordinationError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+function isStale(artifact: Pick<PlanArtifactRecord, 'createdAt'>, maxStalenessMs: number): boolean {
+  if (!maxStalenessMs) return false
+  return nowEpochMillis() - artifact.createdAt.getTime() > maxStalenessMs
+}
+
+function validateNoCycles(
+  specs: Array<{ id: string; title?: string; dependencies?: PlanDependency[] }>,
+): PlanValidationIssueInput[] {
+  const adj = new Map<string, Set<string>>()
+  const inDegree = new Map<string, number>()
+  const labels = new Map(specs.map((spec) => [spec.id, spec.title ?? spec.id]))
+
+  for (const spec of specs) {
+    if (!adj.has(spec.id)) adj.set(spec.id, new Set())
+    if (!inDegree.has(spec.id)) inDegree.set(spec.id, 0)
+
+    for (const dep of spec.dependencies ?? []) {
+      if (!adj.has(dep.sourcePlanSpecId)) adj.set(dep.sourcePlanSpecId, new Set())
+      if (!inDegree.has(dep.sourcePlanSpecId)) inDegree.set(dep.sourcePlanSpecId, 0)
+
+      adj.get(dep.sourcePlanSpecId)?.add(spec.id)
+      inDegree.set(spec.id, (inDegree.get(spec.id) ?? 0) + 1)
+    }
+  }
+
+  const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([t]) => t)
+  const visited = new Set<string>()
+
+  while (queue.length > 0) {
+    const node = queue.shift()
+    if (!node) break
+    visited.add(node)
+    for (const dep of adj.get(node) ?? []) {
+      const d = (inDegree.get(dep) ?? 0) - 1
+      inDegree.set(dep, d)
+      if (d === 0) queue.push(dep)
+    }
+  }
+
+  const unvisited = specs.filter((s) => !visited.has(s.id))
+  if (unvisited.length === 0) return []
+
+  return [
+    {
+      severity: 'blocking',
+      code: 'circular_dependency',
+      message: `Circular plan dependencies detected involving: ${unvisited.map((s) => labels.get(s.id) ?? s.id).join(', ')}`,
+    },
+  ]
+}
+
+export function makePlanCoordinationService(planRunService: ReturnType<typeof makePlanRunService>) {
+  const resolveDependencies = (params: { dependencies: PlanDependency[]; threadId: string }) => {
+    const resolved = new Map<string, PlanArtifactRecord>()
+    const unresolved: PlanDependency[] = []
+    const notifications: DependencyResolutionResult['notifications'] = []
+
+    return Effect.gen(function* () {
+      const specs = yield* planRunService
+        .listPlanSpecsByThread(params.threadId)
+        .pipe(
+          Effect.mapError(
+            (cause) => new PlanCoordinationError({ message: 'Failed to list plan specs by thread.', cause }),
+          ),
+        )
+
+      for (const dep of params.dependencies) {
+        const depKey = `${dep.sourcePlanSpecId}:${dep.sourceNodeId}:${dep.artifactName}`
+        const sourceSpec = specs.find((spec) => recordIdToString(spec.id, TABLES.PLAN_SPEC) === dep.sourcePlanSpecId)
+        if (!sourceSpec) {
+          const reason = `Source plan "${dep.sourcePlanSpecId}" not found in thread.`
+          if (dep.triggerMode === 'block') {
+            unresolved.push(dep)
+          } else if (dep.triggerMode === 'notify') {
+            notifications.push({ dependency: dep, reason })
+            serverLogger.warn`Dependency unmet (notify): ${reason}`
+          }
+          continue
+        }
+
+        const runs = yield* planRunService
+          .listRunsBySpec(sourceSpec.id)
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new PlanCoordinationError({ message: 'Failed to list plan runs for dependency resolution.', cause }),
+            ),
+          )
+        const activeRun = runs.find((run) => run.status === 'completed' || run.status === 'running')
+        if (!activeRun) {
+          const reason = `No active run found for plan "${sourceSpec.title}".`
+          if (dep.triggerMode === 'block') {
+            unresolved.push(dep)
+          } else if (dep.triggerMode === 'notify') {
+            notifications.push({ dependency: dep, reason })
+            serverLogger.warn`Dependency unmet (notify): ${reason}`
+          }
+          continue
+        }
+
+        const artifacts = yield* planRunService
+          .listArtifacts(activeRun.id)
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new PlanCoordinationError({
+                  message: 'Failed to list plan artifacts for dependency resolution.',
+                  cause,
+                }),
+            ),
+          )
+        const artifact = artifacts.find(
+          (candidate) => candidate.nodeId === dep.sourceNodeId && candidate.name === dep.artifactName,
+        )
+        if (!artifact) {
+          const reason = `Artifact "${dep.artifactName}" not found on node "${dep.sourceNodeId}" in plan "${sourceSpec.title}".`
+          if (dep.triggerMode === 'block') {
+            unresolved.push(dep)
+          } else if (dep.triggerMode === 'notify') {
+            notifications.push({ dependency: dep, reason })
+            serverLogger.warn`Dependency unmet (notify): ${reason}`
+          }
+          continue
+        }
+
+        if (dep.maxStalenessMs && isStale(artifact, dep.maxStalenessMs)) {
+          const reason = `Artifact "${dep.artifactName}" from plan "${sourceSpec.title}" is stale.`
+          if (dep.triggerMode === 'block') {
+            unresolved.push(dep)
+            continue
+          }
+          if (dep.triggerMode === 'notify') {
+            notifications.push({ dependency: dep, reason })
+            serverLogger.warn`Dependency stale (notify): ${reason}`
+          }
+        }
+
+        resolved.set(depKey, artifact)
+      }
+
+      return { resolved, unresolved, notifications }
+    })
+  }
+
+  return { resolveDependencies, isStale, validateNoCycles }
+}
+
+export class PlanCoordinationServiceTag extends Context.Service<
+  PlanCoordinationServiceTag,
+  ReturnType<typeof makePlanCoordinationService>
+>()('PlanCoordinationService') {}
+
+export const PlanCoordinationServiceLive = Layer.effect(
+  PlanCoordinationServiceTag,
+  Effect.gen(function* () {
+    const planRunService = yield* PlanRunServiceTag
+    return makePlanCoordinationService(planRunService)
+  }),
+)