@tagma/sdk 0.5.2 → 0.6.1

package/src/validate-raw.ts

@@ -1,412 +1,412 @@
-// ═══ Raw Pipeline Config Validation ═══
-//
-// Validates a RawPipelineConfig without resolving inheritance or executing
-// anything — intended for real-time feedback in a visual editor (e.g. drag
-// to add a task, live error highlighting).
-//
-// Returns a flat list of ValidationError objects. An empty array means valid.
-
-import type { RawPipelineConfig } from './types';
-import {
-  isValidTaskId,
-  qualifyTaskId,
-  buildTaskIndex,
-  resolveTaskRef,
-  type TaskIndex,
-} from './task-ref';
-
-const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
-function isValidDuration(input: string): boolean {
-  return DURATION_RE.test(input.trim());
-}
-
-// D8: IDs may only contain letters, digits, underscores, and hyphens, and must
-// start with a letter or underscore. Dots are explicitly forbidden because the
-// engine uses "trackId.taskId" as the qualified separator — a dot in either
-// part creates an ambiguous qualified ID and breaks resolveRef.
-// Canonical regex and helper live in ./task-ref so every resolver (dag.ts,
-// engine.ts, editor) stays in lockstep with what we accept here.
-const isValidId = isValidTaskId;
-
-const VALID_ON_FAILURE = new Set(['skip_downstream', 'stop_all', 'ignore']);
-const VALID_REASONING_EFFORT = new Set(['low', 'medium', 'high']);
-
-// Built-in plugin types always known to the SDK core, regardless of which
-// external plugin packages are installed. These MUST stay in sync with the
-// types that `bootstrapBuiltins()` registers, otherwise the editor will
-// emit false-positive "unknown type" warnings for stock pipelines.
-const BUILTIN_TRIGGER_TYPES: ReadonlySet<string> = new Set(['manual', 'file']);
-const BUILTIN_COMPLETION_TYPES: ReadonlySet<string> = new Set([
-  'exit_code',
-  'file_exists',
-  'output_check',
-]);
-const BUILTIN_MIDDLEWARE_TYPES: ReadonlySet<string> = new Set(['static_context']);
-
-/**
- * Optional second argument to `validateRaw`: the set of plugin types currently
- * registered in the SDK runtime, keyed by category. Hosts (e.g. the editor
- * server) pass this so `validateRaw` can emit a soft warning when a task
- * references a type that isn't loaded — otherwise the Task panel would show
- * no hint and the pipeline would only blow up at run time. Callers that
- * legitimately validate a config offline (before plugins are loaded) can omit
- * this argument and no plugin warnings will be produced.
- */
-export interface KnownPluginTypes {
-  readonly triggers?: readonly string[];
-  readonly completions?: readonly string[];
-  readonly middlewares?: readonly string[];
-}
-
-export type ValidationSeverity = 'error' | 'warning';
-
-export interface ValidationError {
-  /** JSONPath-style location, e.g. "tracks[0].tasks[1].prompt" */
-  path: string;
-  message: string;
-  /**
-   * H8: not all "errors" are equally fatal. The DAG runtime is happy to
-   * insert implicit `continue_from → depends_on` ordering, so the matching
-   * validate-raw check is a *style* nit, not a hard failure. Severity lets
-   * the editor render it as a soft warning instead of blocking save / run.
-   * Existing call sites that don't read this field still treat every entry
-   * as fatal — defaulting `severity` to undefined preserves that behaviour.
-   */
-  severity?: ValidationSeverity;
-}
-
-/**
- * Validate a raw pipeline config.
- * Checks structure, required fields, prompt/command exclusivity,
- * depends_on reference integrity, and circular dependencies.
- *
- * Plugin type checks: when `knownTypes` is provided, task/track references to
- * trigger/completion/middleware types that are neither built-in nor in the
- * supplied set produce a soft warning (severity: 'warning') — these don't
- * block save/run but light up the Task panel so users discover the broken
- * reference in the editor instead of at run time. Omit `knownTypes` to skip
- * plugin checks entirely (offline/pre-load validation).
- */
-export function validateRaw(
-  config: RawPipelineConfig,
-  knownTypes?: KnownPluginTypes,
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-
-  const knownTriggers = knownTypes
-    ? new Set<string>([...BUILTIN_TRIGGER_TYPES, ...(knownTypes.triggers ?? [])])
-    : null;
-  const knownCompletions = knownTypes
-    ? new Set<string>([...BUILTIN_COMPLETION_TYPES, ...(knownTypes.completions ?? [])])
-    : null;
-  const knownMiddlewares = knownTypes
-    ? new Set<string>([...BUILTIN_MIDDLEWARE_TYPES, ...(knownTypes.middlewares ?? [])])
-    : null;
-
-  // ── Top level ──
-  if (!config.name?.trim()) {
-    errors.push({ path: 'name', message: 'Pipeline name is required' });
-  }
-  if (config.reasoning_effort && !VALID_REASONING_EFFORT.has(config.reasoning_effort)) {
-    errors.push({
-      path: 'reasoning_effort',
-      message: `Invalid reasoning_effort "${config.reasoning_effort}". Expected "low", "medium", or "high".`,
-    });
-  }
-
-  if (!config.tracks || config.tracks.length === 0) {
-    errors.push({ path: 'tracks', message: 'At least one track is required' });
-    return errors; // No point going further without tracks
-  }
-
-  // ── Build qualified ID sets for cross-reference checks ──
-  // Qualified ID format: "trackId.taskId" (mirrors the engine's convention).
-  // Shared with dag.ts so "ambiguous" / "not found" stay consistent — refs
-  // that buildDag later throws on will be reported here as errors first.
-  const index = buildTaskIndex(config);
-
-  // ── Per-track validation ──
-  const seenTrackIds = new Set<string>();
-  for (let ti = 0; ti < config.tracks.length; ti++) {
-    const track = config.tracks[ti];
-    const trackPath = `tracks[${ti}]`;
-
-    if (!track.id?.trim()) {
-      errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
-    } else if (!isValidId(track.id)) {
-      errors.push({
-        path: `${trackPath}.id`,
-        message: `Track id "${track.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
-      });
-    } else if (seenTrackIds.has(track.id)) {
-      errors.push({ path: `${trackPath}.id`, message: `Duplicate track id "${track.id}"` });
-    } else {
-      seenTrackIds.add(track.id);
-    }
-    if (!track.name?.trim()) {
-      errors.push({ path: `${trackPath}.name`, message: 'Track name is required' });
-    }
-    if (track.on_failure && !VALID_ON_FAILURE.has(track.on_failure)) {
-      errors.push({
-        path: `${trackPath}.on_failure`,
-        message: `Invalid on_failure value "${track.on_failure}". Expected "skip_downstream", "stop_all", or "ignore".`,
-      });
-    }
-    if (track.reasoning_effort && !VALID_REASONING_EFFORT.has(track.reasoning_effort)) {
-      errors.push({
-        path: `${trackPath}.reasoning_effort`,
-        message: `Invalid reasoning_effort "${track.reasoning_effort}". Expected "low", "medium", or "high".`,
-      });
-    }
-
-    // Track-level middlewares can reference a plugin that was uninstalled
-    // after the YAML was written — surface a warning so the user notices
-    // before hitting Run.
-    if (knownMiddlewares && track.middlewares) {
-      for (let mi = 0; mi < track.middlewares.length; mi++) {
-        const mw = track.middlewares[mi];
-        if (mw?.type && !knownMiddlewares.has(mw.type)) {
-          errors.push({
-            path: `${trackPath}.middlewares[${mi}].type`,
-            message: `Middleware type "${mw.type}" is not registered. Install the plugin (e.g. @tagma/middleware-${mw.type}) or remove the reference — the pipeline will fail at run time.`,
-            severity: 'warning',
-          });
-        }
-      }
-    }
-
-    if (!track.tasks || track.tasks.length === 0) {
-      errors.push({
-        path: `${trackPath}.tasks`,
-        message: `Track "${track.id || ti}": must have at least one task`,
-      });
-      continue;
-    }
-
-    // ── Per-task validation ──
-    const seenTaskIds = new Set<string>();
-    for (let ki = 0; ki < track.tasks.length; ki++) {
-      const task = track.tasks[ki];
-      const taskPath = `${trackPath}.tasks[${ki}]`;
-
-      if (!task.id?.trim()) {
-        errors.push({ path: `${taskPath}.id`, message: 'Task id is required' });
-        continue; // Can't check further without an id
-      }
-
-      if (!isValidId(task.id)) {
-        errors.push({
-          path: `${taskPath}.id`,
-          message: `Task id "${task.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
-        });
-      }
-      if (seenTaskIds.has(task.id)) {
-        errors.push({
-          path: taskPath,
-          message: `Duplicate task id "${task.id}" in track "${track.id}"`,
-        });
-      }
-      seenTaskIds.add(task.id);
-
-      const hasPromptKey = typeof task.prompt === 'string';
-      const hasCommandKey = typeof task.command === 'string';
-      const promptEmpty = hasPromptKey && task.prompt!.trim().length === 0;
-      const commandEmpty = hasCommandKey && task.command!.trim().length === 0;
-
-      if (hasPromptKey && hasCommandKey) {
-        errors.push({
-          path: taskPath,
-          message: `Task "${task.id}": cannot have both "prompt" and "command"`,
-        });
-      } else if (!hasPromptKey && !hasCommandKey) {
-        errors.push({
-          path: taskPath,
-          message: `Task "${task.id}": must have "prompt" or "command"`,
-        });
-      } else if (promptEmpty) {
-        errors.push({
-          path: taskPath,
-          message: `Task "${task.id}": prompt content cannot be empty`,
-        });
-      } else if (commandEmpty) {
-        errors.push({
-          path: taskPath,
-          message: `Task "${task.id}": command content cannot be empty`,
-        });
-      }
-
-      // ── Field-level validations ──
-      if (task.timeout && !isValidDuration(task.timeout)) {
-        errors.push({
-          path: `${taskPath}.timeout`,
-          message: `Invalid duration format "${task.timeout}". Expected e.g. "30s", "5m", "1h".`,
-        });
-      }
-      if (task.reasoning_effort && !VALID_REASONING_EFFORT.has(task.reasoning_effort)) {
-        errors.push({
-          path: `${taskPath}.reasoning_effort`,
-          message: `Invalid reasoning_effort "${task.reasoning_effort}". Expected "low", "medium", or "high".`,
-        });
-      }
-
-      // ── Plugin type warnings (trigger / completion / middlewares) ──
-      // Only fire when the host supplied a `knownTypes` snapshot, so offline
-      // validation stays quiet. The messages deliberately name the npm
-      // scope so users can copy-paste the install command.
-      if (knownTriggers && task.trigger?.type && !knownTriggers.has(task.trigger.type)) {
-        errors.push({
-          path: `${taskPath}.trigger.type`,
-          message: `Trigger type "${task.trigger.type}" is not registered. Install the plugin (e.g. @tagma/trigger-${task.trigger.type}) or the task will fail at run time.`,
-          severity: 'warning',
-        });
-      }
-      if (
-        knownCompletions &&
-        task.completion?.type &&
-        !knownCompletions.has(task.completion.type)
-      ) {
-        errors.push({
-          path: `${taskPath}.completion.type`,
-          message: `Completion type "${task.completion.type}" is not registered. Install the plugin (e.g. @tagma/completion-${task.completion.type}) or the task will fail at run time.`,
-          severity: 'warning',
-        });
-      }
-      if (knownMiddlewares && task.middlewares) {
-        for (let mi = 0; mi < task.middlewares.length; mi++) {
-          const mw = task.middlewares[mi];
-          if (mw?.type && !knownMiddlewares.has(mw.type)) {
-            errors.push({
-              path: `${taskPath}.middlewares[${mi}].type`,
-              message: `Middleware type "${mw.type}" is not registered. Install the plugin (e.g. @tagma/middleware-${mw.type}) or remove the reference — the pipeline will fail at run time.`,
-              severity: 'warning',
-            });
-          }
-        }
-      }
-
-      // ── depends_on reference checks ──
-      if (task.depends_on && task.depends_on.length > 0) {
-        for (const dep of task.depends_on) {
-          const resolved = resolveTaskRef(dep, track.id, index);
-          if (resolved.kind === 'not_found') {
-            errors.push({
-              path: `${taskPath}.depends_on`,
-              message: `Task "${task.id}": depends_on "${dep}" — no such task found`,
-            });
-          } else if (resolved.kind === 'ambiguous') {
-            errors.push({
-              path: `${taskPath}.depends_on`,
-              message: `Task "${task.id}": depends_on "${dep}" is ambiguous — multiple tracks have a task with this id. Use the fully-qualified form "trackId.${dep}".`,
-            });
-          }
-        }
-      }
-
-      // ── continue_from reference check ──
-      if (task.continue_from) {
-        const resolved = resolveTaskRef(task.continue_from, track.id, index);
-        if (resolved.kind === 'not_found') {
-          errors.push({
-            path: `${taskPath}.continue_from`,
-            message: `Task "${task.id}": continue_from "${task.continue_from}" — no such task found`,
-          });
-        } else if (resolved.kind === 'ambiguous') {
-          errors.push({
-            path: `${taskPath}.continue_from`,
-            message: `Task "${task.id}": continue_from "${task.continue_from}" is ambiguous — multiple tracks have a task with this id. Use the fully-qualified form "trackId.${task.continue_from}".`,
-          });
-        } else if (
-          !task.depends_on ||
-          !task.depends_on.some((dep) => {
-            const depResolved = resolveTaskRef(dep, track.id, index);
-            return depResolved.kind === 'resolved' && depResolved.qid === resolved.qid;
-          })
-        ) {
-          // H8: demote to a warning. dag.ts/buildDag inserts continue_from
-          // as an implicit dependency at runtime, so the pipeline runs fine
-          // without the explicit listing. Treat as a style hint rather than
-          // blocking save / run, otherwise we frighten users with a red
-          // "Configuration error" for code that would have run successfully.
-          errors.push({
-            path: `${taskPath}.continue_from`,
-            message: `Task "${task.id}": continue_from "${task.continue_from}" should also be listed in depends_on for clarity (the runtime will add it implicitly).`,
-            severity: 'warning',
-          });
-        }
-      }
-    }
-  }
-
-  // ── Cycle detection ──
-  errors.push(...detectCycles(config, index));
-
-  return errors;
-}
-
-function detectCycles(config: RawPipelineConfig, index: TaskIndex): ValidationError[] {
-  // Build adjacency: qualifiedId → [resolved dep qualifiedIds]
-  const adj = new Map<string, string[]>();
-
-  for (const track of config.tracks) {
-    if (!track.id) continue;
-    for (const task of track.tasks ?? []) {
-      if (!task.id) continue;
-      const qid = qualifyTaskId(track.id, task.id);
-      const deps: string[] = [];
-      for (const dep of task.depends_on ?? []) {
-        const resolved = resolveTaskRef(dep, track.id, index);
-        if (resolved.kind === 'resolved') deps.push(resolved.qid);
-      }
-      if (task.continue_from) {
-        const resolved = resolveTaskRef(task.continue_from, track.id, index);
-        if (resolved.kind === 'resolved' && !deps.includes(resolved.qid)) deps.push(resolved.qid);
-      }
-      adj.set(qid, deps);
-    }
-  }
-
-  const errors: ValidationError[] = [];
-  const visited = new Set<string>();
-  const inStack = new Set<string>();
-  // Deduplicate cycles: the same cycle can be discovered from multiple entry points.
-  // Canonical key = sorted node list joined — order-independent fingerprint.
-  const seenCycles = new Set<string>();
-
-  // Use a mutable path array instead of copying at each level (O(n) vs O(n^2)).
-  const pathStack: string[] = [];
-
-  function dfs(id: string): void {
-    if (inStack.has(id)) {
-      const cycleStart = pathStack.indexOf(id);
-      // Unique nodes in the cycle (without repeating the start node) for dedup.
-      // Previously the duplicate start node caused different sorted keys when
-      // the same cycle was discovered from different entry points.
-      const uniqueNodes = pathStack.slice(cycleStart);
-      const key = [...uniqueNodes].sort().join(',');
-      if (!seenCycles.has(key)) {
-        seenCycles.add(key);
-        const display = [...uniqueNodes, id]; // include start for readable display
-        errors.push({
-          path: 'tracks',
-          message: `Circular dependency detected: ${display.join(' → ')}`,
-        });
-      }
-      return;
-    }
-    if (visited.has(id)) return;
-    visited.add(id);
-    inStack.add(id);
-    pathStack.push(id);
-    for (const dep of adj.get(id) ?? []) {
-      dfs(dep);
-    }
-    pathStack.pop();
-    inStack.delete(id);
-  }
-
-  for (const id of adj.keys()) {
-    if (!visited.has(id)) dfs(id);
-  }
-
-  return errors;
-}
+// ═══ Raw Pipeline Config Validation ═══
+//
+// Validates a RawPipelineConfig without resolving inheritance or executing
+// anything — intended for real-time feedback in a visual editor (e.g. drag
+// to add a task, live error highlighting).
+//
+// Returns a flat list of ValidationError objects. An empty array means valid.
+
+import type { RawPipelineConfig } from './types';
+import {
+  isValidTaskId,
+  qualifyTaskId,
+  buildTaskIndex,
+  resolveTaskRef,
+  type TaskIndex,
+} from './task-ref';
+
+const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
+function isValidDuration(input: string): boolean {
+  return DURATION_RE.test(input.trim());
+}
+
+// D8: IDs may only contain letters, digits, underscores, and hyphens, and must
+// start with a letter or underscore. Dots are explicitly forbidden because the
+// engine uses "trackId.taskId" as the qualified separator — a dot in either
+// part creates an ambiguous qualified ID and breaks resolveRef.
+// Canonical regex and helper live in ./task-ref so every resolver (dag.ts,
+// engine.ts, editor) stays in lockstep with what we accept here.
+const isValidId = isValidTaskId;
+
+const VALID_ON_FAILURE = new Set(['skip_downstream', 'stop_all', 'ignore']);
+const VALID_REASONING_EFFORT = new Set(['low', 'medium', 'high']);
+
+// Built-in plugin types always known to the SDK core, regardless of which
+// external plugin packages are installed. These MUST stay in sync with the
+// types that `bootstrapBuiltins()` registers, otherwise the editor will
+// emit false-positive "unknown type" warnings for stock pipelines.
+const BUILTIN_TRIGGER_TYPES: ReadonlySet<string> = new Set(['manual', 'file']);
+const BUILTIN_COMPLETION_TYPES: ReadonlySet<string> = new Set([
+  'exit_code',
+  'file_exists',
+  'output_check',
+]);
+const BUILTIN_MIDDLEWARE_TYPES: ReadonlySet<string> = new Set(['static_context']);
+
+/**
+ * Optional second argument to `validateRaw`: the set of plugin types currently
+ * registered in the SDK runtime, keyed by category. Hosts (e.g. the editor
+ * server) pass this so `validateRaw` can emit a soft warning when a task
+ * references a type that isn't loaded — otherwise the Task panel would show
+ * no hint and the pipeline would only blow up at run time. Callers that
+ * legitimately validate a config offline (before plugins are loaded) can omit
+ * this argument and no plugin warnings will be produced.
+ */
+export interface KnownPluginTypes {
+  readonly triggers?: readonly string[];
+  readonly completions?: readonly string[];
+  readonly middlewares?: readonly string[];
+}
+
+export type ValidationSeverity = 'error' | 'warning';
+
+export interface ValidationError {
+  /** JSONPath-style location, e.g. "tracks[0].tasks[1].prompt" */
+  path: string;
+  message: string;
+  /**
+   * H8: not all "errors" are equally fatal. The DAG runtime is happy to
+   * insert implicit `continue_from → depends_on` ordering, so the matching
+   * validate-raw check is a *style* nit, not a hard failure. Severity lets
+   * the editor render it as a soft warning instead of blocking save / run.
+   * Existing call sites that don't read this field still treat every entry
+   * as fatal — defaulting `severity` to undefined preserves that behaviour.
+   */
+  severity?: ValidationSeverity;
+}
+
+/**
+ * Validate a raw pipeline config.
+ * Checks structure, required fields, prompt/command exclusivity,
+ * depends_on reference integrity, and circular dependencies.
+ *
+ * Plugin type checks: when `knownTypes` is provided, task/track references to
+ * trigger/completion/middleware types that are neither built-in nor in the
+ * supplied set produce a soft warning (severity: 'warning') — these don't
+ * block save/run but light up the Task panel so users discover the broken
+ * reference in the editor instead of at run time. Omit `knownTypes` to skip
+ * plugin checks entirely (offline/pre-load validation).
+ */
+export function validateRaw(
+  config: RawPipelineConfig,
+  knownTypes?: KnownPluginTypes,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  const knownTriggers = knownTypes
+    ? new Set<string>([...BUILTIN_TRIGGER_TYPES, ...(knownTypes.triggers ?? [])])
+    : null;
+  const knownCompletions = knownTypes
+    ? new Set<string>([...BUILTIN_COMPLETION_TYPES, ...(knownTypes.completions ?? [])])
+    : null;
+  const knownMiddlewares = knownTypes
+    ? new Set<string>([...BUILTIN_MIDDLEWARE_TYPES, ...(knownTypes.middlewares ?? [])])
+    : null;
+
+  // ── Top level ──
+  if (!config.name?.trim()) {
+    errors.push({ path: 'name', message: 'Pipeline name is required' });
+  }
+  if (config.reasoning_effort && !VALID_REASONING_EFFORT.has(config.reasoning_effort)) {
+    errors.push({
+      path: 'reasoning_effort',
+      message: `Invalid reasoning_effort "${config.reasoning_effort}". Expected "low", "medium", or "high".`,
+    });
+  }
+
+  if (!config.tracks || config.tracks.length === 0) {
+    errors.push({ path: 'tracks', message: 'At least one track is required' });
+    return errors; // No point going further without tracks
+  }
+
+  // ── Build qualified ID sets for cross-reference checks ──
+  // Qualified ID format: "trackId.taskId" (mirrors the engine's convention).
+  // Shared with dag.ts so "ambiguous" / "not found" stay consistent — refs
+  // that buildDag later throws on will be reported here as errors first.
+  const index = buildTaskIndex(config);
+
+  // ── Per-track validation ──
+  const seenTrackIds = new Set<string>();
+  for (let ti = 0; ti < config.tracks.length; ti++) {
+    const track = config.tracks[ti];
+    const trackPath = `tracks[${ti}]`;
+
+    if (!track.id?.trim()) {
+      errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
+    } else if (!isValidId(track.id)) {
+      errors.push({
+        path: `${trackPath}.id`,
+        message: `Track id "${track.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
+      });
+    } else if (seenTrackIds.has(track.id)) {
+      errors.push({ path: `${trackPath}.id`, message: `Duplicate track id "${track.id}"` });
+    } else {
+      seenTrackIds.add(track.id);
+    }
+    if (!track.name?.trim()) {
+      errors.push({ path: `${trackPath}.name`, message: 'Track name is required' });
+    }
+    if (track.on_failure && !VALID_ON_FAILURE.has(track.on_failure)) {
+      errors.push({
+        path: `${trackPath}.on_failure`,
+        message: `Invalid on_failure value "${track.on_failure}". Expected "skip_downstream", "stop_all", or "ignore".`,
+      });
+    }
+    if (track.reasoning_effort && !VALID_REASONING_EFFORT.has(track.reasoning_effort)) {
+      errors.push({
+        path: `${trackPath}.reasoning_effort`,
+        message: `Invalid reasoning_effort "${track.reasoning_effort}". Expected "low", "medium", or "high".`,
+      });
+    }
+
+    // Track-level middlewares can reference a plugin that was uninstalled
+    // after the YAML was written — surface a warning so the user notices
+    // before hitting Run.
+    if (knownMiddlewares && track.middlewares) {
+      for (let mi = 0; mi < track.middlewares.length; mi++) {
+        const mw = track.middlewares[mi];
+        if (mw?.type && !knownMiddlewares.has(mw.type)) {
+          errors.push({
+            path: `${trackPath}.middlewares[${mi}].type`,
+            message: `Middleware type "${mw.type}" is not registered. Install the plugin (e.g. @tagma/middleware-${mw.type}) or remove the reference — the pipeline will fail at run time.`,
+            severity: 'warning',
+          });
+        }
+      }
+    }
+
+    if (!track.tasks || track.tasks.length === 0) {
+      errors.push({
+        path: `${trackPath}.tasks`,
+        message: `Track "${track.id || ti}": must have at least one task`,
+      });
+      continue;
+    }
+
+    // ── Per-task validation ──
+    const seenTaskIds = new Set<string>();
+    for (let ki = 0; ki < track.tasks.length; ki++) {
+      const task = track.tasks[ki];
+      const taskPath = `${trackPath}.tasks[${ki}]`;
+
+      if (!task.id?.trim()) {
+        errors.push({ path: `${taskPath}.id`, message: 'Task id is required' });
+        continue; // Can't check further without an id
+      }
+
+      if (!isValidId(task.id)) {
+        errors.push({
+          path: `${taskPath}.id`,
+          message: `Task id "${task.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
+        });
+      }
+      if (seenTaskIds.has(task.id)) {
+        errors.push({
+          path: taskPath,
+          message: `Duplicate task id "${task.id}" in track "${track.id}"`,
+        });
+      }
+      seenTaskIds.add(task.id);
+
+      const hasPromptKey = typeof task.prompt === 'string';
+      const hasCommandKey = typeof task.command === 'string';
+      const promptEmpty = hasPromptKey && task.prompt!.trim().length === 0;
+      const commandEmpty = hasCommandKey && task.command!.trim().length === 0;
+
+      if (hasPromptKey && hasCommandKey) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": cannot have both "prompt" and "command"`,
+        });
+      } else if (!hasPromptKey && !hasCommandKey) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": must have "prompt" or "command"`,
+        });
+      } else if (promptEmpty) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": prompt content cannot be empty`,
+        });
+      } else if (commandEmpty) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": command content cannot be empty`,
+        });
+      }
+
+      // ── Field-level validations ──
+      if (task.timeout && !isValidDuration(task.timeout)) {
+        errors.push({
+          path: `${taskPath}.timeout`,
+          message: `Invalid duration format "${task.timeout}". Expected e.g. "30s", "5m", "1h".`,
+        });
+      }
+      if (task.reasoning_effort && !VALID_REASONING_EFFORT.has(task.reasoning_effort)) {
+        errors.push({
+          path: `${taskPath}.reasoning_effort`,
+          message: `Invalid reasoning_effort "${task.reasoning_effort}". Expected "low", "medium", or "high".`,
+        });
+      }
+
+      // ── Plugin type warnings (trigger / completion / middlewares) ──
+      // Only fire when the host supplied a `knownTypes` snapshot, so offline
+      // validation stays quiet. The messages deliberately name the npm
+      // scope so users can copy-paste the install command.
+      if (knownTriggers && task.trigger?.type && !knownTriggers.has(task.trigger.type)) {
+        errors.push({
+          path: `${taskPath}.trigger.type`,
+          message: `Trigger type "${task.trigger.type}" is not registered. Install the plugin (e.g. @tagma/trigger-${task.trigger.type}) or the task will fail at run time.`,
+          severity: 'warning',
+        });
+      }
+      if (
+        knownCompletions &&
+        task.completion?.type &&
+        !knownCompletions.has(task.completion.type)
+      ) {
+        errors.push({
+          path: `${taskPath}.completion.type`,
+          message: `Completion type "${task.completion.type}" is not registered. Install the plugin (e.g. @tagma/completion-${task.completion.type}) or the task will fail at run time.`,
+          severity: 'warning',
+        });
+      }
+      if (knownMiddlewares && task.middlewares) {
+        for (let mi = 0; mi < task.middlewares.length; mi++) {
+          const mw = task.middlewares[mi];
+          if (mw?.type && !knownMiddlewares.has(mw.type)) {
+            errors.push({
+              path: `${taskPath}.middlewares[${mi}].type`,
+              message: `Middleware type "${mw.type}" is not registered. Install the plugin (e.g. @tagma/middleware-${mw.type}) or remove the reference — the pipeline will fail at run time.`,
+              severity: 'warning',
+            });
+          }
+        }
+      }
+
+      // ── depends_on reference checks ──
+      if (task.depends_on && task.depends_on.length > 0) {
+        for (const dep of task.depends_on) {
+          const resolved = resolveTaskRef(dep, track.id, index);
+          if (resolved.kind === 'not_found') {
+            errors.push({
+              path: `${taskPath}.depends_on`,
+              message: `Task "${task.id}": depends_on "${dep}" — no such task found`,
+            });
+          } else if (resolved.kind === 'ambiguous') {
+            errors.push({
+              path: `${taskPath}.depends_on`,
+              message: `Task "${task.id}": depends_on "${dep}" is ambiguous — multiple tracks have a task with this id. Use the fully-qualified form "trackId.${dep}".`,
+            });
+          }
+        }
+      }
+
+      // ── continue_from reference check ──
+      if (task.continue_from) {
+        const resolved = resolveTaskRef(task.continue_from, track.id, index);
+        if (resolved.kind === 'not_found') {
+          errors.push({
+            path: `${taskPath}.continue_from`,
+            message: `Task "${task.id}": continue_from "${task.continue_from}" — no such task found`,
+          });
+        } else if (resolved.kind === 'ambiguous') {
+          errors.push({
+            path: `${taskPath}.continue_from`,
+            message: `Task "${task.id}": continue_from "${task.continue_from}" is ambiguous — multiple tracks have a task with this id. Use the fully-qualified form "trackId.${task.continue_from}".`,
+          });
+        } else if (
+          !task.depends_on ||
+          !task.depends_on.some((dep) => {
+            const depResolved = resolveTaskRef(dep, track.id, index);
+            return depResolved.kind === 'resolved' && depResolved.qid === resolved.qid;
+          })
+        ) {
+          // H8: demote to a warning. dag.ts/buildDag inserts continue_from
+          // as an implicit dependency at runtime, so the pipeline runs fine
+          // without the explicit listing. Treat as a style hint rather than
+          // blocking save / run, otherwise we frighten users with a red
+          // "Configuration error" for code that would have run successfully.
+          errors.push({
+            path: `${taskPath}.continue_from`,
+            message: `Task "${task.id}": continue_from "${task.continue_from}" should also be listed in depends_on for clarity (the runtime will add it implicitly).`,
+            severity: 'warning',
+          });
+        }
+      }
+    }
+  }
+
+  // ── Cycle detection ──
+  errors.push(...detectCycles(config, index));
+
+  return errors;
+}
+
+function detectCycles(config: RawPipelineConfig, index: TaskIndex): ValidationError[] {
+  // Build adjacency: qualifiedId → [resolved dep qualifiedIds]
+  const adj = new Map<string, string[]>();
+
+  for (const track of config.tracks) {
+    if (!track.id) continue;
+    for (const task of track.tasks ?? []) {
+      if (!task.id) continue;
+      const qid = qualifyTaskId(track.id, task.id);
+      const deps: string[] = [];
+      for (const dep of task.depends_on ?? []) {
+        const resolved = resolveTaskRef(dep, track.id, index);
+        if (resolved.kind === 'resolved') deps.push(resolved.qid);
+      }
+      if (task.continue_from) {
+        const resolved = resolveTaskRef(task.continue_from, track.id, index);
+        if (resolved.kind === 'resolved' && !deps.includes(resolved.qid)) deps.push(resolved.qid);
+      }
+      adj.set(qid, deps);
+    }
+  }
+
+  const errors: ValidationError[] = [];
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+  // Deduplicate cycles: the same cycle can be discovered from multiple entry points.
+  // Canonical key = sorted node list joined — order-independent fingerprint.
+  const seenCycles = new Set<string>();
+
+  // Use a mutable path array instead of copying at each level (O(n) vs O(n^2)).
+  const pathStack: string[] = [];
+
+  function dfs(id: string): void {
+    if (inStack.has(id)) {
+      const cycleStart = pathStack.indexOf(id);
+      // Unique nodes in the cycle (without repeating the start node) for dedup.
+      // Previously the duplicate start node caused different sorted keys when
+      // the same cycle was discovered from different entry points.
+      const uniqueNodes = pathStack.slice(cycleStart);
+      const key = [...uniqueNodes].sort().join(',');
+      if (!seenCycles.has(key)) {
+        seenCycles.add(key);
+        const display = [...uniqueNodes, id]; // include start for readable display
+        errors.push({
+          path: 'tracks',
+          message: `Circular dependency detected: ${display.join(' → ')}`,
+        });
+      }
+      return;
+    }
+    if (visited.has(id)) return;
+    visited.add(id);
+    inStack.add(id);
+    pathStack.push(id);
+    for (const dep of adj.get(id) ?? []) {
+      dfs(dep);
+    }
+    pathStack.pop();
+    inStack.delete(id);
+  }
+
+  for (const id of adj.keys()) {
+    if (!visited.has(id)) dfs(id);
+  }
+
+  return errors;
+}