@lota-sdk/core 0.4.1 → 0.4.2

package/src/services/artifact.service.ts

@@ -0,0 +1,371 @@
+import { ArtifactRecordSchema, GetArtifactResultSchema, PublishArtifactArgsSchema } from '@lota-sdk/shared'
+import type {
+  ArtifactRecord,
+  ArtifactReference,
+  ArtifactStatus,
+  ArtifactVersionSummary,
+  GetArtifactResult,
+  PublishArtifactArgs,
+} from '@lota-sdk/shared'
+
+import type { RecordIdInput } from '../db/record-id'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import type { DatabaseTransaction } from '../db/service'
+import { TABLES } from '../db/tables'
+import { generatedDocumentStorageService } from '../storage/generated-document-storage.service'
+import { toIsoDateTimeString } from '../utils/date-time'
+
+const ARTIFACT_PUBLISH_MAX_ATTEMPTS = 5
+
+function describePublishInputShape(value: unknown): string {
+  if (typeof value === 'string') {
+    return `string(${value.length})`
+  }
+
+  if (Array.isArray(value)) {
+    const firstEntry: unknown = value[0]
+    const firstType =
+      firstEntry === undefined
+        ? 'empty'
+        : Array.isArray(firstEntry)
+          ? 'array'
+          : firstEntry === null
+            ? 'null'
+            : typeof firstEntry
+    return `array(len=${value.length}, first=${firstType})`
+  }
+
+  if (value === null) {
+    return 'null'
+  }
+
+  if (typeof value === 'object') {
+    return `object(keys=${Object.keys(value).sort().join(',')})`
+  }
+
+  return typeof value
+}
+
+function formatPublishError(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message
+  }
+
+  return typeof error === 'string' ? error : JSON.stringify(error)
+}
+
+function slugify(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return normalized || 'artifact'
+}
+
+function encodeStorageSegment(value: string): string {
+  return Buffer.from(value, 'utf8').toString('base64url') || 'artifact'
+}
+
+function hashCanonicalSegment(value: string): string {
+  return new Bun.CryptoHasher('sha256').update(value.trim()).digest('hex')
+}
+
+function buildCanonicalKey(
+  params: Pick<
+    PublishArtifactArgs,
+    'canonicalKey' | 'title' | 'deliverableName' | 'sourcePlanNodeId' | 'sourcePlanRunId'
+  >,
+): string {
+  const explicit = params.canonicalKey?.trim()
+  if (explicit) {
+    return explicit
+  }
+
+  if (params.deliverableName?.trim()) {
+    const parts = ['plan-deliverable', `artifact-${hashCanonicalSegment(params.deliverableName)}`]
+    if (params.sourcePlanRunId?.trim()) {
+      parts.push(`run-${hashCanonicalSegment(params.sourcePlanRunId)}`)
+    }
+    if (params.sourcePlanNodeId?.trim()) {
+      parts.push(`node-${hashCanonicalSegment(params.sourcePlanNodeId)}`)
+    }
+    return parts.join(':')
+  }
+
+  return `${slugify(params.title)}-${Bun.randomUUIDv7()}`
+}
+
+function buildArtifactRelativePath(params: {
+  canonicalKey: string
+  version: number
+  title: string
+  publishAttemptId: string
+}): string {
+  return `${encodeStorageSegment(params.canonicalKey)}/v${params.version}/${params.publishAttemptId}-${slugify(params.title)}.md`
+}
+
+function extractInternalReferences(content: string): ArtifactReference[] {
+  const matches = new Set<string>()
+  const markdownLinkPattern = /\]\((venturos:\/\/(?:artifact|document)\/[A-Za-z0-9:_-]+)\)/g
+  const bareLinkPattern = /\b(venturos:\/\/(?:artifact|document)\/[A-Za-z0-9:_-]+)\b/g
+
+  for (const pattern of [markdownLinkPattern, bareLinkPattern]) {
+    for (const match of content.matchAll(pattern)) {
+      const uri = match[1]?.trim()
+      if (uri) {
+        matches.add(uri)
+      }
+    }
+  }
+
+  return [...matches]
+    .map((uri) => {
+      if (uri.startsWith('venturos://artifact/')) {
+        return { uri, targetType: 'artifact' as const, targetId: uri.slice('venturos://artifact/'.length) }
+      }
+      if (uri.startsWith('venturos://document/')) {
+        return { uri, targetType: 'document' as const, targetId: uri.slice('venturos://document/'.length) }
+      }
+      return null
+    })
+    .filter((reference): reference is ArtifactReference => reference !== null)
+}
+
+function toVersionSummary(record: ArtifactRecord): ArtifactVersionSummary {
+  return {
+    id: recordIdToString(record.id, TABLES.ARTIFACT),
+    title: record.title,
+    version: record.version,
+    status: record.status,
+    createdAt: toIsoDateTimeString(record.createdAt),
+  }
+}
+
+function isRetryablePublishError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const message = error.message.toLowerCase()
+  return (
+    message.includes('conflict') ||
+    message.includes('duplicate') ||
+    message.includes('unique') ||
+    message.includes('already exists')
+  )
+}
+
+interface PublishArtifactTransactionOptions {
+  onStorageWrite?: (storageKey: string) => void
+  onStorageCleanup?: (storageKey: string) => void
+}
+
+class ArtifactService {
+  private async listArtifactsForCanonicalKeyInTransaction(params: {
+    tx: DatabaseTransaction
+    organizationId: string
+    canonicalKey: string
+  }): Promise<ArtifactRecord[]> {
+    const records = await params.tx.query({
+      query: `SELECT * FROM ${TABLES.ARTIFACT} WHERE organizationId = $organizationId AND canonicalKey = $canonicalKey ORDER BY version DESC`,
+      bindings: {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        canonicalKey: params.canonicalKey,
+      },
+    })
+
+    return ArtifactRecordSchema.array().parse(records)
+  }
+
+  async publishArtifactInTransaction(
+    args: PublishArtifactArgs,
+    tx: DatabaseTransaction,
+    options: PublishArtifactTransactionOptions = {},
+  ): Promise<ArtifactRecord> {
+    let params: PublishArtifactArgs
+    try {
+      params = PublishArtifactArgsSchema.parse(args)
+    } catch (error) {
+      throw new Error(
+        `artifact service transaction input parse failed (${describePublishInputShape(args)}): ${formatPublishError(error)}`,
+      )
+    }
+    const organizationRef = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
+    const canonicalKey = buildCanonicalKey(params)
+    const existing = await this.listArtifactsForCanonicalKeyInTransaction({
+      tx,
+      organizationId: params.organizationId,
+      canonicalKey,
+    })
+    const latestVersion = existing.reduce((max, record) => Math.max(max, record.version), 0)
+    const version = latestVersion + 1
+    const publishAttemptId = Bun.randomUUIDv7()
+    const references = extractInternalReferences(params.content)
+    const stored = await generatedDocumentStorageService.writeTextArtifact({
+      organizationId: params.organizationId,
+      namespace: 'artifacts',
+      relativePath: buildArtifactRelativePath({ canonicalKey, version, title: params.title, publishAttemptId }),
+      content: params.content,
+      mediaType: 'text/markdown',
+    })
+    options.onStorageWrite?.(stored.storageKey)
+
+    try {
+      const createdResult = await tx
+        .create(TABLES.ARTIFACT)
+        .content({
+          organizationId: organizationRef,
+          authorAgentId: params.authorAgentId,
+          title: params.title,
+          artifactKind: params.artifactKind,
+          templateId: params.templateId,
+          canonicalKey,
+          version,
+          status: 'active',
+          storageKey: stored.storageKey,
+          ...(params.description ? { description: params.description } : {}),
+          tags: [...new Set(params.tags)],
+          references,
+          ...(params.sourceThreadId ? { sourceThreadId: ensureRecordId(params.sourceThreadId, TABLES.THREAD) } : {}),
+          ...(params.sourcePlanRunId
+            ? { sourcePlanRunId: ensureRecordId(params.sourcePlanRunId, TABLES.PLAN_RUN) }
+            : {}),
+          ...(params.sourcePlanNodeId ? { sourcePlanNodeId: params.sourcePlanNodeId } : {}),
+        })
+        .output('after')
+      const createdRecord: unknown = Array.isArray(createdResult) ? createdResult.at(0) : createdResult
+      if (!createdRecord) {
+        throw new Error(`Artifact create returned no record for canonical key ${canonicalKey}.`)
+      }
+
+      const created = ArtifactRecordSchema.parse(createdRecord)
+
+      const previousActive = existing.find((record) => record.status === 'active')
+      if (previousActive) {
+        await tx
+          .update(ensureRecordId(previousActive.id, TABLES.ARTIFACT))
+          .merge({ status: 'superseded', supersededBy: ensureRecordId(created.id, TABLES.ARTIFACT) })
+          .output('after')
+      }
+
+      return created
+    } catch (error) {
+      await generatedDocumentStorageService.deleteTextArtifact(stored.storageKey).catch(() => undefined)
+      options.onStorageCleanup?.(stored.storageKey)
+      throw error
+    }
+  }
+
+  async publishArtifact(args: PublishArtifactArgs): Promise<ArtifactRecord> {
+    let params: PublishArtifactArgs
+    try {
+      params = PublishArtifactArgsSchema.parse(args)
+    } catch (error) {
+      throw new Error(
+        `artifact service input parse failed (${describePublishInputShape(args)}): ${formatPublishError(error)}`,
+      )
+    }
+
+    let lastError: unknown = null
+    for (let attempt = 1; attempt <= ARTIFACT_PUBLISH_MAX_ATTEMPTS; attempt += 1) {
+      let pendingStorageKey: string | null = null
+      try {
+        return await databaseService.withTransaction(
+          async (tx) =>
+            await this.publishArtifactInTransaction(params, tx, {
+              onStorageWrite: (storageKey) => {
+                pendingStorageKey = storageKey
+              },
+              onStorageCleanup: (storageKey) => {
+                if (pendingStorageKey === storageKey) {
+                  pendingStorageKey = null
+                }
+              },
+            }),
+        )
+      } catch (error) {
+        const storageKeyToCleanup = pendingStorageKey
+        pendingStorageKey = null
+        if (storageKeyToCleanup !== null) {
+          await generatedDocumentStorageService.deleteTextArtifact(storageKeyToCleanup).catch(() => undefined)
+        }
+        lastError = error
+        if (!isRetryablePublishError(error) || attempt === ARTIFACT_PUBLISH_MAX_ATTEMPTS) {
+          throw error
+        }
+      }
+    }
+
+    throw lastError instanceof Error ? lastError : new Error('Artifact publish failed.')
+  }
+
+  async getArtifactRecord(artifactId: RecordIdInput): Promise<ArtifactRecord | null> {
+    return await databaseService.findOne(
+      TABLES.ARTIFACT,
+      { id: ensureRecordId(artifactId, TABLES.ARTIFACT) },
+      ArtifactRecordSchema,
+    )
+  }
+
+  async listArtifacts(params: {
+    organizationId: RecordIdInput
+    canonicalKey?: string
+    status?: ArtifactStatus
+    includeNonActive?: boolean
+    sourceThreadId?: RecordIdInput
+    limit?: number
+  }): Promise<ArtifactRecord[]> {
+    const records = await databaseService.findMany(
+      TABLES.ARTIFACT,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        ...(params.canonicalKey ? { canonicalKey: params.canonicalKey } : {}),
+        ...(params.sourceThreadId ? { sourceThreadId: ensureRecordId(params.sourceThreadId, TABLES.THREAD) } : {}),
+      },
+      ArtifactRecordSchema,
+      { orderBy: 'createdAt', orderDir: 'DESC', ...(params.limit ? { limit: params.limit } : {}) },
+    )
+
+    if (params.status) {
+      return records.filter((record) => record.status === params.status)
+    }
+
+    if (params.includeNonActive) {
+      return records
+    }
+
+    return records.filter((record) => record.status === 'active')
+  }
+
+  async getArtifact(artifactId: RecordIdInput): Promise<GetArtifactResult> {
+    const artifact = await this.getArtifactRecord(artifactId)
+    if (!artifact) {
+      throw new Error(`Artifact not found: ${recordIdToString(artifactId, TABLES.ARTIFACT)}`)
+    }
+
+    const [content, versions, backlinks] = await Promise.all([
+      generatedDocumentStorageService.readTextArtifact(artifact.storageKey),
+      this.listArtifacts({
+        organizationId: artifact.organizationId,
+        canonicalKey: artifact.canonicalKey,
+        includeNonActive: true,
+      }),
+      this.listBacklinks(artifact),
+    ])
+
+    return GetArtifactResultSchema.parse({ artifact, content, versions: versions.map(toVersionSummary), backlinks })
+  }
+
+  async listBacklinks(artifact: Pick<ArtifactRecord, 'id' | 'organizationId'>): Promise<ArtifactRecord[]> {
+    const artifactId = recordIdToString(artifact.id, TABLES.ARTIFACT)
+    const records = await this.listArtifacts({ organizationId: artifact.organizationId, includeNonActive: true })
+
+    return records.filter((record) =>
+      record.references.some((reference) => reference.targetType === 'artifact' && reference.targetId === artifactId),
+    )
+  }
+}
+
+export const artifactService = new ArtifactService()

package/src/services/autonomous-job.service.ts

@@ -306,12 +306,14 @@ class AutonomousJobService {
         jobId: buildAutonomousAtJobId(jobId),
       })
 
-      await databaseService.update(
-        TABLES.AUTONOMOUS_JOB_RUN,
-        queuedRun.id,
-        { queueJobId: ensureRecordId(enqueueResult.queueJobId, TABLES.QUEUE_JOB) },
-        AutonomousJobRunRowSchema,
-      )
+      if (enqueueResult.queueJobId) {
+        await databaseService.update(
+          TABLES.AUTONOMOUS_JOB_RUN,
+          queuedRun.id,
+          { queueJobId: ensureRecordId(enqueueResult.queueJobId, TABLES.QUEUE_JOB) },
+          AutonomousJobRunRowSchema,
+        )
+      }
     } else {
       const { upsertAutonomousJobScheduler } = await import('../queues/autonomous-job.queue')
       await upsertAutonomousJobScheduler({ autonomousJobId: jobId, schedule: row.schedule })
@@ -477,12 +479,14 @@ class AutonomousJobService {
       jobId: buildAutonomousManualJobId(recordIdToString(row.id, TABLES.AUTONOMOUS_JOB)),
     })
 
-    await databaseService.update(
-      TABLES.AUTONOMOUS_JOB_RUN,
-      queuedRun.id,
-      { queueJobId: ensureRecordId(enqueueResult.queueJobId, TABLES.QUEUE_JOB) },
-      AutonomousJobRunRowSchema,
-    )
+    if (enqueueResult.queueJobId) {
+      await databaseService.update(
+        TABLES.AUTONOMOUS_JOB_RUN,
+        queuedRun.id,
+        { queueJobId: ensureRecordId(enqueueResult.queueJobId, TABLES.QUEUE_JOB) },
+        AutonomousJobRunRowSchema,
+      )
+    }
 
     return this.toPublicRun(await this.getRunRow(queuedRun.id))
   }

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

@@ -15,6 +15,7 @@ import type {
 } from '@lota-sdk/shared'
 import {
   PlanCheckpointSchema,
+  PlanDraftSchema,
   PlanEventSchema,
   PlanNodeRunSchema,
   PlanNodeSpecRecordSchema,
@@ -247,7 +248,7 @@ class ExecutionPlanService {
     leadAgentId: string
     input: PlanDraft
   }): Promise<ExecutionPlanToolResultData> {
-    const preparedDraft = planBuilderService.prepareDraft(params.input)
+    const preparedDraft = planBuilderService.prepareDraft(PlanDraftSchema.parse(params.input))
     const validation = planValidatorService.validateDraft(preparedDraft)
     if (validation.blocking.length > 0) {
       throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)
@@ -336,18 +337,8 @@ class ExecutionPlanService {
     }
 
     const activeSpec = await planRunService.getPlanSpecById(activeRun.planSpecId)
-    const preparedDraft = planBuilderService.prepareDraft({
-      title: params.input.title,
-      objective: params.input.objective,
-      nodes: params.input.nodes,
-      edges: params.input.edges,
-      entryNodeIds: params.input.entryNodeIds,
-      schemas: params.input.schemas,
-      defaultExecutionVisibility: params.input.defaultExecutionVisibility,
-      executionMode: params.input.executionMode,
-      schedule: params.input.schedule,
-      dependencies: params.input.dependencies,
-    })
+    const { runId: _runId, reason: _reason, ...draftInput } = params.input
+    const preparedDraft = planBuilderService.prepareDraft(PlanDraftSchema.parse(draftInput))
     const validation = planValidatorService.validateDraft(preparedDraft)
     if (validation.blocking.length > 0) {
       throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)

package/src/services/index.ts

@@ -1,6 +1,7 @@
 export * from './adaptive-playbook.service'
 export * from './agent-executor.service'
 export * from './agent-activity.service'
+export * from './artifact.service'
 export * from './artifact-provenance.service'
 export * from './attachment.service'
 export * from './autonomous-job.service'

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

@@ -74,7 +74,11 @@ function toArtifactSubmission(artifact: PlanArtifactRecord): PlanArtifactSubmiss
     name: artifact.name,
     kind: artifact.kind,
     ...(artifact.description ? { description: artifact.description } : {}),
+    ...(artifact.content !== undefined ? { content: artifact.content } : {}),
     ...(artifact.payload !== undefined ? { payload: artifact.payload } : {}),
+    ...(artifact.publishedArtifactId
+      ? { publishedArtifactId: recordIdToString(artifact.publishedArtifactId, TABLES.ARTIFACT) }
+      : {}),
   }
 }
 

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

@@ -28,9 +28,15 @@ class PlanArtifactService {
           nodeId: params.nodeId,
           name: artifact.name,
           kind: artifact.kind,
-          pointer: `artifact://${params.nodeId}/${artifact.name}`,
+          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')
 

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

@@ -1,6 +1,8 @@
 import type { PlanArtifactRecord, PlanDependency } from '@lota-sdk/shared'
 
 import { serverLogger } from '../config/logger'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
 import type { PlanValidationIssueInput } from './plan-validator.service'
 
 export interface DependencyResolutionResult {
@@ -13,7 +15,7 @@ class PlanCoordinationService {
   /**
    * Resolve cross-plan artifact dependencies.
    * For each dependency:
-   *   1. Find the source plan by title in the thread
+   *   1. Find the source plan by spec id in the thread
    *   2. Find the artifact by (nodeId, artifactName) in that plan's run
    *   3. Check staleness if maxStalenessMs set
    *   4. Based on triggerMode:
@@ -30,14 +32,14 @@ class PlanCoordinationService {
     const resolved = new Map<string, PlanArtifactRecord>()
     const unresolved: PlanDependency[] = []
     const notifications: DependencyResolutionResult['notifications'] = []
+    const specs = await planRunService.listPlanSpecsByThread(params.threadId)
 
     for (const dep of params.dependencies) {
-      const depKey = `${dep.sourcePlanTitle}:${dep.sourceNodeId}:${dep.artifactName}`
+      const depKey = `${dep.sourcePlanSpecId}:${dep.sourceNodeId}:${dep.artifactName}`
 
-      const specs = await planRunService.listPlanSpecsByThread(params.threadId)
-      const sourceSpec = specs.find((s) => s.title === dep.sourcePlanTitle)
+      const sourceSpec = specs.find((s) => recordIdToString(s.id, TABLES.PLAN_SPEC) === dep.sourcePlanSpecId)
       if (!sourceSpec) {
-        const reason = `Source plan "${dep.sourcePlanTitle}" not found in thread.`
+        const reason = `Source plan "${dep.sourcePlanSpecId}" not found in thread.`
         if (dep.triggerMode === 'block') {
           unresolved.push(dep)
         } else if (dep.triggerMode === 'notify') {
@@ -51,7 +53,7 @@ class PlanCoordinationService {
       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}".`
+        const reason = `No active run found for plan "${sourceSpec.title}".`
         if (dep.triggerMode === 'block') {
           unresolved.push(dep)
         } else if (dep.triggerMode === 'notify') {
@@ -65,7 +67,7 @@ class PlanCoordinationService {
       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}".`
+        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') {
@@ -76,7 +78,7 @@ class PlanCoordinationService {
       }
 
       if (dep.maxStalenessMs && this.isStale(artifact, dep.maxStalenessMs)) {
-        const reason = `Artifact "${dep.artifactName}" from plan "${dep.sourcePlanTitle}" is stale.`
+        const reason = `Artifact "${dep.artifactName}" from plan "${sourceSpec.title}" is stale.`
         if (dep.triggerMode === 'block') {
           unresolved.push(dep)
           continue
@@ -102,23 +104,26 @@ class PlanCoordinationService {
 
   /**
    * Validate no circular dependencies exist using Kahn's algorithm.
-   * Build adjacency: planTitle -> depends on planTitles
+   * Build adjacency: planSpecId -> depends on upstream planSpecIds
    * Run topological sort; if not all visited -> cycle exists.
    */
-  validateNoCycles(specs: Array<{ title: string; dependencies?: PlanDependency[] }>): PlanValidationIssueInput[] {
+  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.title)) adj.set(spec.title, new Set())
-      if (!inDegree.has(spec.title)) inDegree.set(spec.title, 0)
+      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.sourcePlanTitle)) adj.set(dep.sourcePlanTitle, new Set())
-        if (!inDegree.has(dep.sourcePlanTitle)) inDegree.set(dep.sourcePlanTitle, 0)
+        if (!adj.has(dep.sourcePlanSpecId)) adj.set(dep.sourcePlanSpecId, new Set())
+        if (!inDegree.has(dep.sourcePlanSpecId)) inDegree.set(dep.sourcePlanSpecId, 0)
 
-        adj.get(dep.sourcePlanTitle)?.add(spec.title)
-        inDegree.set(spec.title, (inDegree.get(spec.title) ?? 0) + 1)
+        adj.get(dep.sourcePlanSpecId)?.add(spec.id)
+        inDegree.set(spec.id, (inDegree.get(spec.id) ?? 0) + 1)
       }
     }
 
@@ -136,14 +141,14 @@ class PlanCoordinationService {
       }
     }
 
-    const unvisited = specs.filter((s) => !visited.has(s.title))
+    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) => s.title).join(', ')}`,
+        message: `Circular plan dependencies detected involving: ${unvisited.map((s) => labels.get(s.id) ?? s.id).join(', ')}`,
       },
     ]
   }