@lota-sdk/core 0.1.14 → 0.1.16

package/src/services/ownership-dispatcher.service.ts

@@ -0,0 +1,403 @@
+import type {
+  ExecutionMode,
+  OwnershipDispatchContext,
+  PlanArtifactRecord,
+  PlanArtifactSubmission,
+  PlanFailureClass,
+  PlanNodeResultSubmission,
+  PlanNodeRunRecord,
+  PlanNodeSpec,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+  PlanSchemaRegistry,
+  PlanSpecRecord,
+  PlanDraft,
+  SerializableExecutionPlan,
+} from '@lota-sdk/shared'
+
+import { agentRoster } from '../config/agent-defaults'
+import type { RecordIdInput } from '../db/record-id'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import { agentExecutorService } from './agent-executor.service'
+import { domainAgentExecutorService } from './domain-agent-executor.service'
+import { monitoringWindowService } from './monitoring-window.service'
+import { planExecutorService } from './plan-executor.service'
+import { planRunService } from './plan-run.service'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+import { pluginExecutorService } from './plugin-executor.service'
+import { skillResolverService } from './skill-resolver.service'
+import { systemExecutorService } from './system-executor.service'
+import { userService } from './user.service'
+import { WorkstreamSchema } from './workstream.types'
+
+const STABLE_RUN_STATUSES = new Set(['awaiting-human', 'blocked', 'failed', 'completed', 'aborted'])
+const MAX_DISPATCH_ITERATIONS = 64
+
+function toPlanNodeSpec(nodeSpec: PlanNodeSpecRecord): PlanNodeSpec {
+  return {
+    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,
+    },
+    ...(nodeSpec.schedule ? { schedule: nodeSpec.schedule } : {}),
+    ...(nodeSpec.deadline ? { deadline: nodeSpec.deadline } : {}),
+    ...(nodeSpec.monitoringConfig ? { monitoringConfig: nodeSpec.monitoringConfig } : {}),
+    ...(nodeSpec.delayAfterPredecessorMs ? { delayAfterPredecessorMs: nodeSpec.delayAfterPredecessorMs } : {}),
+    ...(nodeSpec.deliberationConfig ? { deliberationConfig: nodeSpec.deliberationConfig } : {}),
+  }
+}
+
+function toArtifactSubmission(artifact: PlanArtifactRecord): PlanArtifactSubmission {
+  return {
+    name: artifact.name,
+    kind: artifact.kind,
+    pointer: artifact.pointer,
+    ...(artifact.schemaRef ? { schemaRef: artifact.schemaRef } : {}),
+    ...(artifact.description ? { description: artifact.description } : {}),
+    ...(artifact.payload !== undefined ? { payload: artifact.payload } : {}),
+  }
+}
+
+function classifyDispatchFailure(params: {
+  ownerType: PlanNodeSpec['owner']['executorType']
+  error: unknown
+}): PlanFailureClass {
+  const errorMessage =
+    params.error instanceof Error ? params.error.message.toLowerCase() : String(params.error).toLowerCase()
+  if (errorMessage.includes('timeout')) {
+    return 'timeout_exceeded'
+  }
+  if (params.ownerType === 'plugin' || params.ownerType === 'system') {
+    return 'external_system_unavailable'
+  }
+  return 'non_recoverable_logic_error'
+}
+
+function formatDispatchError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+class OwnershipDispatcherService {
+  validateDraftExecutors(draft: PlanDraft): PlanValidationIssueInput[] {
+    const issues: PlanValidationIssueInput[] = []
+
+    for (const node of draft.nodes) {
+      if (node.owner.executorType === 'agent') {
+        if (!agentRoster.includes(node.owner.ref) && !domainAgentExecutorService.hasAgent(node.owner.ref)) {
+          issues.push({
+            severity: 'blocking',
+            code: 'agent_executor_missing',
+            message: `Node "${node.label}" references unknown agent executor "${node.owner.ref}".`,
+            nodeId: node.id,
+            detail: { agentId: node.owner.ref },
+          })
+        }
+        continue
+      }
+
+      if (node.owner.executorType === 'plugin') {
+        issues.push(...pluginExecutorService.validateOwner(node.owner, node.id))
+        continue
+      }
+
+      if (node.owner.executorType === 'system') {
+        issues.push(...systemExecutorService.validateOwner(node.owner, node.id))
+        continue
+      }
+
+      if (node.owner.executorType === 'skill') {
+        // Skill owners are validated at execution time via skillResolverService.
+      }
+    }
+
+    return issues
+  }
+
+  async dispatchRunToStableBoundary(params: {
+    runId: RecordIdInput
+    emittedBy: string
+  }): Promise<SerializableExecutionPlan> {
+    const initialRun = await planRunService.getRunById(params.runId)
+    const autoDispatchEnabled = await this.shouldAutoDispatch(initialRun)
+    if (!autoDispatchEnabled) {
+      return this.serializeRun(initialRun.id)
+    }
+
+    let iteration = 0
+    while (iteration < MAX_DISPATCH_ITERATIONS) {
+      const run = await planRunService.getRunById(params.runId)
+      if (STABLE_RUN_STATUSES.has(run.status) || run.status !== 'running' || !run.currentNodeId) {
+        return this.serializeRun(run.id)
+      }
+
+      const spec = await planRunService.getPlanSpecById(run.planSpecId)
+
+      if (spec.executionMode === 'graph-full') {
+        const { globalOrchestratorService } = await import('./global-orchestrator.service')
+        await globalOrchestratorService.routeGraphFull({
+          workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+        })
+        return this.serializeRun(run.id)
+      }
+
+      const nodeSpecRecord = await planRunService.getNodeSpecByNodeId(spec.id, run.currentNodeId)
+      const planNode = toPlanNodeSpec(nodeSpecRecord)
+      if (planNode.owner.executorType === 'user') {
+        return this.serializeRun(run.id)
+      }
+
+      const nodeRun = await planRunService.getNodeRunByNodeId(run.id, nodeSpecRecord.nodeId)
+      if (nodeRun.status === 'monitoring') {
+        // Monitoring nodes are managed by the scheduler — treat as stable
+        return this.serializeRun(run.id)
+      }
+      if (nodeRun.status !== 'running') {
+        return this.serializeRun(run.id)
+      }
+
+      const [artifacts, dispatchContext] = await Promise.all([
+        planRunService.listArtifacts(run.id),
+        this.buildDispatchContext(run),
+      ])
+      const inputArtifacts = artifacts
+        .filter((artifact) => nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
+        .map((artifact) => toArtifactSubmission(artifact))
+
+      try {
+        const result = await this.dispatchNode({
+          nodeSpec: planNode,
+          resolvedInput: nodeRun.resolvedInput ?? {},
+          inputArtifacts,
+          context: { ...dispatchContext, nodeId: planNode.id },
+          executionMode: spec.executionMode,
+          schemaRegistry: spec.schemaRegistry,
+        })
+
+        await planExecutorService.submitNodeResult({
+          workstreamId: run.workstreamId,
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+          nodeId: planNode.id,
+          emittedBy: planNode.owner.ref,
+          result,
+        })
+      } catch (error) {
+        await planExecutorService.blockNodeOnDispatchFailure({
+          workstreamId: run.workstreamId,
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+          nodeId: planNode.id,
+          emittedBy: planNode.owner.ref,
+          message: formatDispatchError(error),
+          failureClass: classifyDispatchFailure({ ownerType: planNode.owner.executorType, error }),
+        })
+        return await this.serializeRun(run.id)
+      }
+
+      iteration += 1
+    }
+
+    throw new Error(
+      `Ownership dispatch exceeded ${MAX_DISPATCH_ITERATIONS} iterations for run ${recordIdToString(
+        ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        TABLES.PLAN_RUN,
+      )}.`,
+    )
+  }
+
+  async dispatchReadyNode(params: {
+    run: PlanRunRecord
+    nodeSpecRecord: PlanNodeSpecRecord
+    nodeRun: PlanNodeRunRecord
+    spec: PlanSpecRecord
+    executionModeOverride?: ExecutionMode
+  }): Promise<PlanNodeResultSubmission> {
+    const planNode = toPlanNodeSpec(params.nodeSpecRecord)
+    const [artifacts, dispatchContext] = await Promise.all([
+      planRunService.listArtifacts(params.run.id),
+      this.buildDispatchContext(params.run),
+    ])
+    const inputArtifacts = artifacts
+      .filter((artifact) => params.nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
+      .map((artifact) => toArtifactSubmission(artifact))
+
+    return this.dispatchNode({
+      nodeSpec: planNode,
+      resolvedInput: params.nodeRun.resolvedInput ?? {},
+      inputArtifacts,
+      context: { ...dispatchContext, nodeId: planNode.id },
+      executionMode: params.spec.executionMode,
+      executionModeOverride: params.executionModeOverride,
+      schemaRegistry: params.spec.schemaRegistry,
+    })
+  }
+
+  private async shouldAutoDispatch(run: PlanRunRecord): Promise<boolean> {
+    const workspaceProvider = getRuntimeAdapters().services?.workspaceProvider
+    if (!workspaceProvider) {
+      return true
+    }
+
+    const workspace = await workspaceProvider.getWorkspace(ensureRecordId(run.organizationId, TABLES.ORGANIZATION))
+    const lifecycleState = await workspaceProvider.getLifecycleState?.(workspace)
+    return lifecycleState?.bootstrapActive !== true
+  }
+
+  private async buildDispatchContext(run: PlanRunRecord): Promise<Omit<OwnershipDispatchContext, 'nodeId'>> {
+    const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
+    const workstreamId = recordIdToString(run.workstreamId, TABLES.WORKSTREAM)
+    const planId = recordIdToString(run.id, TABLES.PLAN_RUN)
+    const workstream = await databaseService.findOne(
+      TABLES.WORKSTREAM,
+      { id: ensureRecordId(run.workstreamId, TABLES.WORKSTREAM) },
+      WorkstreamSchema,
+    )
+    const userId = workstream?.userId ? recordIdToString(workstream.userId, TABLES.USER) : undefined
+    const userName = userId
+      ? await userService
+          .getUser(userId)
+          .then((user) => user.name)
+          .catch(() => undefined)
+      : undefined
+
+    return {
+      organizationId,
+      workstreamId,
+      planId,
+      leadAgentId: run.leadAgentId,
+      ...(userId ? { userId } : {}),
+      ...(userName ? { userName } : {}),
+    }
+  }
+
+  private async serializeRun(runId: RecordIdInput): Promise<SerializableExecutionPlan> {
+    return planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
+      includeEvents: true,
+      includeArtifacts: true,
+      includeApprovals: true,
+      includeCheckpoints: true,
+      includeValidationIssues: true,
+    })
+  }
+
+  async dispatchNode(params: {
+    nodeSpec: PlanNodeSpec
+    resolvedInput: Record<string, unknown>
+    inputArtifacts: PlanArtifactSubmission[]
+    context: OwnershipDispatchContext
+    executionMode?: ExecutionMode
+    executionModeOverride?: ExecutionMode
+    schemaRegistry?: PlanSchemaRegistry
+  }) {
+    const effectiveExecutionMode = params.executionModeOverride ?? params.executionMode
+    if (params.nodeSpec.type === 'monitoring' && params.nodeSpec.monitoringConfig) {
+      await monitoringWindowService.startMonitoringWindow({
+        runId: params.context.planId,
+        nodeId: params.nodeSpec.id,
+        config: params.nodeSpec.monitoringConfig,
+        organizationId: params.context.organizationId,
+        workstreamId: params.context.workstreamId,
+      })
+      return {
+        structuredOutput: { status: 'monitoring-started', config: params.nodeSpec.monitoringConfig },
+        artifacts: [],
+      }
+    }
+
+    if (params.nodeSpec.owner.executorType === 'agent') {
+      if (domainAgentExecutorService.hasAgent(params.nodeSpec.owner.ref)) {
+        return domainAgentExecutorService.executeNode({
+          nodeSpec: params.nodeSpec,
+          resolvedInput: params.resolvedInput,
+          inputArtifacts: params.inputArtifacts,
+          context: params.context,
+        })
+      }
+      return agentExecutorService.executeNode({
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        inputArtifacts: params.inputArtifacts,
+        context: params.context,
+        executionMode: effectiveExecutionMode,
+        schemaRegistry: params.schemaRegistry,
+      })
+    }
+    if (params.nodeSpec.owner.executorType === 'plugin') {
+      return pluginExecutorService.executeNode({
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      })
+    }
+    if (params.nodeSpec.owner.executorType === 'system') {
+      return systemExecutorService.executeNode({
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      })
+    }
+    if (params.nodeSpec.owner.executorType === 'skill') {
+      const resolved = await skillResolverService.resolve({
+        skillRef: params.nodeSpec.owner.ref,
+        organizationId: params.context.organizationId,
+      })
+      if (!resolved) {
+        throw new Error(`Skill "${params.nodeSpec.owner.ref}" could not be resolved. This is a configuration error.`)
+      }
+
+      if (resolved.executorType === 'agent') {
+        const skillNodeSpec = { ...params.nodeSpec, owner: { executorType: 'agent' as const, ref: resolved.ref } }
+        if (domainAgentExecutorService.hasAgent(resolved.ref)) {
+          return domainAgentExecutorService.executeNode({
+            nodeSpec: skillNodeSpec,
+            resolvedInput: params.resolvedInput,
+            inputArtifacts: params.inputArtifacts,
+            context: params.context,
+          })
+        }
+        return agentExecutorService.executeNode({
+          nodeSpec: skillNodeSpec,
+          resolvedInput: params.resolvedInput,
+          inputArtifacts: params.inputArtifacts,
+          context: params.context,
+          executionMode: effectiveExecutionMode,
+          schemaRegistry: params.schemaRegistry,
+        })
+      }
+      return pluginExecutorService.executeNode({
+        nodeSpec: {
+          ...params.nodeSpec,
+          owner: {
+            executorType: 'plugin' as const,
+            ref: resolved.ref,
+            operation: resolved.operation ?? params.nodeSpec.owner.ref,
+          },
+        },
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      })
+    }
+
+    throw new Error(`User-owned node "${params.nodeSpec.id}" cannot be auto-dispatched.`)
+  }
+}
+
+export const ownershipDispatcherService = new OwnershipDispatcherService()

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

@@ -35,7 +35,7 @@ class PlanApprovalService {
   }
 
   async getApprovalById(approvalId: RecordIdInput): Promise<PlanApprovalRecord | null> {
-    return await databaseService.findOne(
+    return databaseService.findOne(
       TABLES.PLAN_APPROVAL,
       { id: ensureRecordId(approvalId, TABLES.PLAN_APPROVAL) },
       PlanApprovalSchema,

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

@@ -17,6 +17,7 @@ class PlanArtifactService {
   }): Promise<PlanArtifactRecord[]> {
     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 = await params.tx

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

@@ -23,6 +23,7 @@ class PlanBuilderService {
   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],
     }

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

@@ -2,11 +2,13 @@ import { PlanCheckpointSchema } from '@lota-sdk/shared'
 import type { PlanCheckpointRecord, PlanRunStatus } from '@lota-sdk/shared'
 import { RecordId } from 'surrealdb'
 
+import { serverLogger } from '../config/logger'
 import type { RecordIdInput } from '../db/record-id'
-import { ensureRecordId } from '../db/record-id'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
 import { databaseService } from '../db/service'
 import type { DatabaseTransaction } from '../db/service'
 import { TABLES } from '../db/tables'
+import { planWorkspaceService } from './plan-workspace.service'
 
 class PlanCheckpointService {
   async createCheckpoint(params: {
@@ -19,7 +21,33 @@ class PlanCheckpointService {
     artifactIds: RecordIdInput[]
     lastCompletedNodeIds: string[]
     snapshot: Record<string, unknown>
+    includeWorkspace?: boolean
   }): Promise<PlanCheckpointRecord> {
+    const snapshotData = { ...params.snapshot }
+
+    if (params.includeWorkspace) {
+      const runIdStr = recordIdToString(params.runId, TABLES.PLAN_RUN)
+      const workspaceSnapshot = await planWorkspaceService
+        .currentRead({ runId: runIdStr })
+        .then((all) => {
+          // Filter to entries at or before the checkpoint sequence
+          const filtered: Record<string, unknown> = {}
+          for (const [key, entry] of Object.entries(all)) {
+            if (entry.writeSequence <= params.sequence) {
+              filtered[key] = entry
+            }
+          }
+          return filtered
+        })
+        .catch((error) => {
+          serverLogger.warn`Workspace snapshot failed for run ${runIdStr}: ${error}`
+          return {}
+        })
+      if (Object.keys(workspaceSnapshot).length > 0) {
+        snapshotData.workspaceSnapshot = workspaceSnapshot
+      }
+    }
+
     const checkpointId = new RecordId(TABLES.PLAN_CHECKPOINT, Bun.randomUUIDv7())
     const created = await params.tx
       .create(checkpointId)
@@ -31,7 +59,7 @@ class PlanCheckpointService {
         activeNodeIds: [...params.activeNodeIds],
         artifactIds: params.artifactIds.map((artifactId) => ensureRecordId(artifactId, TABLES.PLAN_ARTIFACT)),
         lastCompletedNodeIds: [...params.lastCompletedNodeIds],
-        snapshot: params.snapshot,
+        snapshot: snapshotData,
       })
       .output('after')
 

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

@@ -72,6 +72,11 @@ class PlanCompilerService {
         attachmentPolicy: node.contextPolicy.attachmentPolicy,
         webPolicy: node.contextPolicy.webPolicy,
       },
+      ...(node.schedule ? { schedule: node.schedule } : {}),
+      ...(node.deadline ? { deadline: node.deadline } : {}),
+      ...(node.monitoringConfig ? { monitoringConfig: node.monitoringConfig } : {}),
+      ...(node.delayAfterPredecessorMs ? { delayAfterPredecessorMs: node.delayAfterPredecessorMs } : {}),
+      ...(node.deliberationConfig ? { deliberationConfig: node.deliberationConfig } : {}),
       upstreamNodeIds,
       downstreamNodeIds,
     }))

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

@@ -0,0 +1,152 @@
+import type { PlanArtifactRecord, PlanDependency } from '@lota-sdk/shared'
+
+import { serverLogger } from '../config/logger'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+export interface DependencyResolutionResult {
+  resolved: Map<string, PlanArtifactRecord>
+  unresolved: PlanDependency[]
+  notifications: Array<{ dependency: PlanDependency; reason: string }>
+}
+
+class PlanCoordinationService {
+  /**
+   * Resolve cross-plan artifact dependencies.
+   * For each dependency:
+   *   1. Find the source plan by title in the workstream
+   *   2. Find the artifact by (nodeId, artifactName) in that plan's run
+   *   3. Check staleness if maxStalenessMs set
+   *   4. Based on triggerMode:
+   *      'block'       -> unresolved if missing/stale
+   *      'notify'      -> proceed but record notification
+   *      'best-effort' -> proceed regardless, no notification
+   */
+  async resolveDependencies(params: {
+    dependencies: PlanDependency[]
+    workstreamId: string
+  }): Promise<DependencyResolutionResult> {
+    const { planRunService } = await import('./plan-run.service')
+
+    const resolved = new Map<string, PlanArtifactRecord>()
+    const unresolved: PlanDependency[] = []
+    const notifications: DependencyResolutionResult['notifications'] = []
+
+    for (const dep of params.dependencies) {
+      const depKey = `${dep.sourcePlanTitle}:${dep.sourceNodeId}:${dep.artifactName}`
+
+      const specs = await planRunService.listPlanSpecsByWorkstream(params.workstreamId)
+      const sourceSpec = specs.find((s) => s.title === dep.sourcePlanTitle)
+      if (!sourceSpec) {
+        const reason = `Source plan "${dep.sourcePlanTitle}" not found in workstream.`
+        if (dep.triggerMode === 'block') {
+          unresolved.push(dep)
+        } else if (dep.triggerMode === 'notify') {
+          notifications.push({ dependency: dep, reason })
+          serverLogger.warn`Dependency unmet (notify): ${reason}`
+        }
+        // best-effort: silently proceed
+        continue
+      }
+
+      const runs = await planRunService.listRunsBySpec(sourceSpec.id)
+      const activeRun = runs.find((r) => r.status === 'completed' || r.status === 'running')
+      if (!activeRun) {
+        const reason = `No active run found for plan "${dep.sourcePlanTitle}".`
+        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 = await planRunService.listArtifacts(activeRun.id)
+      const artifact = artifacts.find((a) => a.nodeId === dep.sourceNodeId && a.name === dep.artifactName)
+
+      if (!artifact) {
+        const reason = `Artifact "${dep.artifactName}" not found on node "${dep.sourceNodeId}" in plan "${dep.sourcePlanTitle}".`
+        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 && this.isStale(artifact, dep.maxStalenessMs)) {
+        const reason = `Artifact "${dep.artifactName}" from plan "${dep.sourcePlanTitle}" 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}`
+        }
+        // best-effort and notify: use stale artifact anyway
+      }
+
+      resolved.set(depKey, artifact)
+    }
+
+    return { resolved, unresolved, notifications }
+  }
+
+  /** Check if an artifact has exceeded the staleness window. */
+  isStale(artifact: Pick<PlanArtifactRecord, 'createdAt'>, maxStalenessMs: number): boolean {
+    if (!maxStalenessMs) return false
+    return Date.now() - artifact.createdAt.getTime() > maxStalenessMs
+  }
+
+  /**
+   * Validate no circular dependencies exist using Kahn's algorithm.
+   * Build adjacency: planTitle -> depends on planTitles
+   * Run topological sort; if not all visited -> cycle exists.
+   */
+  validateNoCycles(specs: Array<{ title: string; dependencies?: PlanDependency[] }>): PlanValidationIssueInput[] {
+    const adj = new Map<string, Set<string>>()
+    const inDegree = new Map<string, number>()
+
+    for (const spec of specs) {
+      if (!adj.has(spec.title)) adj.set(spec.title, new Set())
+      if (!inDegree.has(spec.title)) inDegree.set(spec.title, 0)
+
+      for (const dep of spec.dependencies ?? []) {
+        if (!adj.has(dep.sourcePlanTitle)) adj.set(dep.sourcePlanTitle, new Set())
+        if (!inDegree.has(dep.sourcePlanTitle)) inDegree.set(dep.sourcePlanTitle, 0)
+
+        adj.get(dep.sourcePlanTitle)?.add(spec.title)
+        inDegree.set(spec.title, (inDegree.get(spec.title) ?? 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.title))
+    if (unvisited.length === 0) return []
+
+    return [
+      {
+        severity: 'blocking',
+        code: 'circular_dependency',
+        message: `Circular plan dependencies detected involving: ${unvisited.map((s) => s.title).join(', ')}`,
+      },
+    ]
+  }
+}
+
+export const planCoordinationService = new PlanCoordinationService()