@tagma/sdk 0.4.14 → 0.4.16

package/src/dag.ts

@@ -5,6 +5,7 @@ import type {
   TaskConfig,
   TrackConfig,
 } from './types';
+import { buildTaskIndex, qualifyTaskId, resolveTaskRef } from './task-ref';
 
 export interface DagNode {
   readonly taskId: string; // fully qualified: track_id.task_id or just task_id
@@ -27,33 +28,17 @@ export interface Dag {
   readonly sorted: readonly string[]; // topological order
 }
 
-// Build a global task ID: for cross-track refs we use "track_id.task_id"
-// Within a track, bare "task_id" is also valid
-function qualifyId(trackId: string, taskId: string): string {
-  return `${trackId}.${taskId}`;
-}
-
 export function buildDag(config: PipelineConfig): Dag {
   const nodes = new Map<string, DagNode>();
-  // Map bare task IDs to qualified IDs (for resolving unqualified refs)
-  const bareToQualified = new Map<string, string>();
 
-  // 1. Register all nodes
+  // 1. Register all nodes. Duplicates throw — same-track task-id collisions
+  //    would otherwise silently overwrite one another in the DAG.
   for (const track of config.tracks) {
     for (const task of track.tasks) {
-      const qid = qualifyId(track.id, task.id);
-
+      const qid = qualifyTaskId(track.id, task.id);
       if (nodes.has(qid)) {
         throw new Error(`Duplicate task ID: "${qid}"`);
       }
-
-      // Track bare ID → qualified. If same bare ID in multiple tracks, mark ambiguous
-      if (bareToQualified.has(task.id)) {
-        bareToQualified.set(task.id, '__ambiguous__');
-      } else {
-        bareToQualified.set(task.id, qid);
-      }
-
       nodes.set(qid, {
         taskId: qid,
         task,
@@ -63,34 +48,27 @@ export function buildDag(config: PipelineConfig): Dag {
     }
   }
 
-  // Helper to resolve a dependency ref to a qualified ID
+  // Shared index for ref resolution — same code path validate-raw uses.
+  const index = buildTaskIndex(config);
+
   function resolveRef(ref: string, fromTrackId: string): string {
-    // Already qualified (contains dot)
-    if (ref.includes('.')) {
-      if (!nodes.has(ref)) {
-        throw new Error(`Task reference "${ref}" not found`);
-      }
-      return ref;
-    }
-    // Try within same track first
-    const sameTrack = qualifyId(fromTrackId, ref);
-    if (nodes.has(sameTrack)) return sameTrack;
-    // Try global bare lookup
-    const global = bareToQualified.get(ref);
-    if (global && global !== '__ambiguous__') return global;
-    if (global === '__ambiguous__') {
+    const result = resolveTaskRef(ref, fromTrackId, index);
+    if (result.kind === 'ambiguous') {
       throw new Error(
         `Ambiguous task reference "${ref}" exists in multiple tracks. ` +
           `Use "track_id.task_id" format.`,
       );
     }
-    throw new Error(`Task reference "${ref}" not found`);
+    if (result.kind === 'not_found') {
+      throw new Error(`Task reference "${ref}" not found`);
+    }
+    return result.qid;
   }
 
   // 2. Resolve depends_on and continue_from to qualified IDs
   for (const track of config.tracks) {
     for (const task of track.tasks) {
-      const qid = qualifyId(track.id, task.id);
+      const qid = qualifyTaskId(track.id, task.id);
       const deps: string[] = [];
       let resolvedContinueFrom: string | undefined;
 
@@ -100,18 +78,27 @@ export function buildDag(config: PipelineConfig): Dag {
         }
       }
       if (task.continue_from) {
-        let resolved: string;
-        try {
-          resolved = resolveRef(task.continue_from, track.id);
-        } catch {
+        // Preserve the ambiguous-vs-not-found distinction in the user-facing
+        // error: rewording "ambiguous" as "no such task found" (the previous
+        // behavior) hid the real problem and sent users searching for a
+        // missing task that actually existed in two places.
+        const result = resolveTaskRef(task.continue_from, track.id, index);
+        if (result.kind === 'ambiguous') {
+          throw new Error(
+            `Task "${qid}": continue_from "${task.continue_from}" is ambiguous — ` +
+              `multiple tracks have a task with this id. Use the fully-qualified ` +
+              `form "trackId.${task.continue_from}".`,
+          );
+        }
+        if (result.kind === 'not_found') {
           throw new Error(
             `Task "${qid}": continue_from "${task.continue_from}" — no such task found. ` +
               `Use a fully-qualified reference (trackId.taskId) or ensure the target task exists.`,
           );
         }
-        resolvedContinueFrom = resolved;
-        if (!deps.includes(resolved)) {
-          deps.push(resolved); // continue_from implies dependency
+        resolvedContinueFrom = result.qid;
+        if (!deps.includes(result.qid)) {
+          deps.push(result.qid); // continue_from implies dependency
         }
       }
 
@@ -137,22 +124,37 @@ export function buildDag(config: PipelineConfig): Dag {
     }
   }
 
-  const queue: string[] = [];
+  // D20: deterministic topo order. Kahn's algorithm dequeues in insertion
+  // order by default, which depends on map iteration order — itself a
+  // function of the (track, task) order in the YAML. Two pipelines that
+  // are DAG-equivalent but written in a different order produced different
+  // `sorted` arrays, leading to subtle run-to-run non-determinism for
+  // parallel tasks with side effects (writing the same file, touching the
+  // same repo). Break the tie by qualified id so identical DAG shapes
+  // always yield identical schedules across machines and across YAML
+  // round-trips.
+  const ready: string[] = [];
   for (const [id, degree] of inDegree) {
-    if (degree === 0) queue.push(id);
+    if (degree === 0) ready.push(id);
   }
+  ready.sort();
 
   const sorted: string[] = [];
-  // Use an index pointer instead of shift() to avoid O(n) per dequeue.
   let qi = 0;
-  while (qi < queue.length) {
-    const current = queue[qi++]!;
+  while (qi < ready.length) {
+    const current = ready[qi++]!;
     sorted.push(current);
+    // Collect children whose in-degree hits zero in this step, then push
+    // them into the ready bucket in sorted order — keeps each "wave" of
+    // parallel-eligible tasks ordered by qid.
+    const newlyReady: string[] = [];
     for (const child of adjacency.get(current)!) {
       const newDegree = inDegree.get(child)! - 1;
       inDegree.set(child, newDegree);
-      if (newDegree === 0) queue.push(child);
+      if (newDegree === 0) newlyReady.push(child);
     }
+    if (newlyReady.length > 1) newlyReady.sort();
+    for (const child of newlyReady) ready.push(child);
   }
 
   if (sorted.length !== nodes.size) {
@@ -193,38 +195,30 @@ export interface RawDag {
  */
 export function buildRawDag(config: RawPipelineConfig): RawDag {
   const nodes = new Map<string, RawDagNode>();
-  const bareToQualified = new Map<string, string>();
 
-  // 1. Register all concrete tasks
+  // 1. Register all concrete tasks. Duplicates are skipped (not thrown) so
+  //    partially-typed editor state doesn't produce a hard error.
   for (const track of config.tracks) {
     for (const task of track.tasks) {
-      const qid = `${track.id}.${task.id}`;
-      if (nodes.has(qid)) continue; // skip duplicates silently
-
-      if (bareToQualified.has(task.id)) {
-        bareToQualified.set(task.id, '__ambiguous__');
-      } else {
-        bareToQualified.set(task.id, qid);
-      }
+      const qid = qualifyTaskId(track.id, task.id);
+      if (nodes.has(qid)) continue;
       nodes.set(qid, { taskId: qid, trackId: track.id, rawTask: task, dependsOn: [] });
     }
   }
 
-  // 2. Resolve dependency refs leniently (missing / ambiguous refs are skipped)
+  const index = buildTaskIndex(config);
+
   function tryResolve(ref: string, fromTrackId: string): string | null {
-    if (ref.includes('.')) return nodes.has(ref) ? ref : null;
-    const sameTrack = `${fromTrackId}.${ref}`;
-    if (nodes.has(sameTrack)) return sameTrack;
-    const global = bareToQualified.get(ref);
-    if (global && global !== '__ambiguous__') return global;
-    return null;
+    const result = resolveTaskRef(ref, fromTrackId, index);
+    return result.kind === 'resolved' ? result.qid : null;
   }
 
+  // 2. Resolve dependency refs leniently (missing / ambiguous refs are skipped)
   const edges: { from: string; to: string }[] = [];
 
   for (const track of config.tracks) {
     for (const task of track.tasks) {
-      const qid = `${track.id}.${task.id}`;
+      const qid = qualifyTaskId(track.id, task.id);
       const deps: string[] = [];
 
       for (const ref of task.depends_on ?? []) {