yaml-flow 2.2.0 → 2.3.0

package/README.md

@@ -801,6 +801,44 @@ Entry points (no requires) get rounded shapes, leaf tasks get double-bracketed s
 
 ---
 
+## Graph Validation (Semantic)
+
+Validate the logical correctness of a graph — catches issues that structural validation (`validateGraphConfig`) can't.
+
+```typescript
+import { validateGraph } from 'yaml-flow/event-graph';
+
+const result = validateGraph(graph);
+
+result.valid;     // true if no errors (warnings/info allowed)
+result.errors;    // issues that will break execution
+result.warnings;  // issues that may cause unexpected behavior
+result.issues;    // all issues (errors + warnings + info)
+
+// Each issue
+result.issues[0].severity; // 'error' | 'warning' | 'info'
+result.issues[0].code;     // e.g. 'CIRCULAR_DEPENDENCY'
+result.issues[0].message;  // human-readable description
+result.issues[0].tasks;    // affected task names
+result.issues[0].tokens;   // affected tokens
+```
+
+| Issue Code | Severity | Description |
+|---|---|---|
+| `EMPTY_GRAPH` | error | Graph has no tasks |
+| `DANGLING_REQUIRES` | error | Task requires a token that no task produces |
+| `CIRCULAR_DEPENDENCY` | error | Cycle detected in task dependencies |
+| `SELF_DEPENDENCY` | error | Task requires a token it provides itself |
+| `UNREACHABLE_GOAL` | error | Goal token cannot be produced by any task |
+| `MISSING_GOAL` | error | `goal-reached` strategy without goal array |
+| `PROVIDE_CONFLICT` | warning | Multiple tasks produce the same token |
+| `DEAD_END_TASK` | warning | Task has no provides — can't unblock downstream |
+| `ISOLATED_TASK` | info | Disconnected task with no requires or dependents |
+
+Use `validateGraphConfig()` for structural checks (JSON shape) and `validateGraph()` for semantic checks (logical correctness). Both are pure functions.
+
+---
+
 ## Loading & Exporting Graph Configs
 
 ```typescript
@@ -835,6 +873,7 @@ import { next, apply, applyAll, getCandidateTasks } from 'yaml-flow/event-graph'
 import { createInitialExecutionState, isExecutionComplete, detectStuckState } from 'yaml-flow/event-graph';
 import { planExecution, graphToMermaid, flowToMermaid } from 'yaml-flow/event-graph';
 import { loadGraphConfig, validateGraphConfig, exportGraphConfig } from 'yaml-flow/event-graph';
+import { validateGraph } from 'yaml-flow/event-graph';
 import { TASK_STATUS, COMPLETION_STRATEGIES, CONFLICT_STRATEGIES } from 'yaml-flow/event-graph';
 
 // Stores
@@ -889,6 +928,7 @@ import { FlowEngine, createEngine } from 'yaml-flow';  // aliases for StepMachin
 | `validateGraphConfig(config)` | Validate a GraphConfig, returns error strings |
 | `exportGraphConfig(config, options?)` | Export a GraphConfig to JSON or YAML string |
 | `exportGraphConfigToFile(config, path)` | Export a GraphConfig to a file |
+| `validateGraph(graph)` | Semantic validation: cycles, dangling requires, unreachable goals, conflicts |
 
 ### Event Types (for `apply()`)
 

package/dist/{constants-Bwvkbr5s.d.cts → constants-BftTHiuV.d.cts}

@@ -438,6 +438,56 @@ declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions)
  */
 declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
 
+/**
+ * Event Graph — Semantic Graph Validation
+ *
+ * Validates the logical correctness of a static graph configuration.
+ * Unlike validateGraphConfig() which checks JSON structure, this checks:
+ *   - Dangling requires (tokens no task produces)
+ *   - Circular dependencies
+ *   - Provide conflicts (multiple tasks producing same token)
+ *   - Unreachable goal tokens
+ *   - Dead-end tasks (no provides)
+ *   - Self-dependencies
+ *   - Orphaned tasks (disconnected from the graph)
+ *
+ * Pure function — config in, diagnostics out.
+ */
+
+type IssueSeverity = 'error' | 'warning' | 'info';
+interface GraphIssue {
+    /** Severity: error = will break execution, warning = may cause problems, info = notable */
+    severity: IssueSeverity;
+    /** Machine-readable issue code */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Affected task names (if applicable) */
+    tasks?: string[];
+    /** Affected tokens (if applicable) */
+    tokens?: string[];
+}
+interface GraphValidationResult {
+    /** true if no errors (warnings/info are allowed) */
+    valid: boolean;
+    /** All issues found */
+    issues: GraphIssue[];
+    /** Just the errors */
+    errors: GraphIssue[];
+    /** Just the warnings */
+    warnings: GraphIssue[];
+}
+/**
+ * Validate the semantic correctness of a static event-graph configuration.
+ *
+ * Checks for logical issues that would cause execution failures, stuck states,
+ * or unexpected behavior. Does NOT check JSON structure (use validateGraphConfig for that).
+ *
+ * @param graph - The event-graph configuration to validate
+ * @returns Validation result with categorized issues
+ */
+declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+
 /**
  * Event Graph — Constants
  */
@@ -454,4 +504,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { next as $, type AgentActionEvent as A, createInitialExecutionState as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, detectStuckState as F, type GraphConfig as G, exportGraphConfig as H, type InjectTokensEvent as I, exportGraphConfigToFile as J, flowToMermaid as K, getAllTasks as L, type MermaidOptions as M, getCandidateTasks as N, getProvides as O, getRequires as P, getTask as Q, graphToMermaid as R, type SchedulerResult as S, type TaskConfig as T, hasTask as U, isExecutionComplete as V, isNonActiveTask as W, isRepeatableTask as X, isTaskCompleted as Y, isTaskRunning as Z, loadGraphConfig as _, CONFLICT_STRATEGIES as a, planExecution as a0, validateGraphConfig as a1, type RepeatableConfig as a2, type TaskCircuitBreakerConfig as a3, type TaskMessage as a4, type TaskProgressEvent as a5, type TaskRetryConfig as a6, addKeyToProvides as a7, addKeyToRequires as a8, getRepeatableMax as a9, groupTasksByProvides as aa, hasOutputConflict as ab, removeKeyFromProvides as ac, removeKeyFromRequires as ad, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphSettings as m, type StuckDetection as n, TASK_STATUS as o, type TaskCompletedEvent as p, type TaskCreationEvent as q, type TaskFailedEvent as r, type TaskStartedEvent as s, type TaskState as t, type TaskStatus as u, addDynamicTask as v, apply as w, applyAll as x, computeAvailableOutputs as y, createDefaultTaskState as z };
+export { isTaskCompleted as $, type AgentActionEvent as A, applyAll as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, computeAvailableOutputs as F, type GraphConfig as G, createDefaultTaskState as H, type InjectTokensEvent as I, createInitialExecutionState as J, detectStuckState as K, exportGraphConfig as L, type MermaidOptions as M, exportGraphConfigToFile as N, flowToMermaid as O, getAllTasks as P, getCandidateTasks as Q, getProvides as R, type SchedulerResult as S, type TaskConfig as T, getRequires as U, getTask as V, graphToMermaid as W, hasTask as X, isExecutionComplete as Y, isNonActiveTask as Z, isRepeatableTask as _, CONFLICT_STRATEGIES as a, isTaskRunning as a0, loadGraphConfig as a1, next as a2, planExecution as a3, validateGraph as a4, validateGraphConfig as a5, type RepeatableConfig as a6, type TaskCircuitBreakerConfig as a7, type TaskMessage as a8, type TaskProgressEvent as a9, type TaskRetryConfig as aa, addKeyToProvides as ab, addKeyToRequires as ac, getRepeatableMax as ad, groupTasksByProvides as ae, hasOutputConflict as af, removeKeyFromProvides as ag, removeKeyFromRequires as ah, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphIssue as m, type GraphSettings as n, type GraphValidationResult as o, type IssueSeverity as p, type StuckDetection as q, TASK_STATUS as r, type TaskCompletedEvent as s, type TaskCreationEvent as t, type TaskFailedEvent as u, type TaskStartedEvent as v, type TaskState as w, type TaskStatus as x, addDynamicTask as y, apply as z };

package/dist/{constants-Ewufm5cK.d.ts → constants-DMbnp--H.d.ts}

@@ -438,6 +438,56 @@ declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions)
  */
 declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
 
+/**
+ * Event Graph — Semantic Graph Validation
+ *
+ * Validates the logical correctness of a static graph configuration.
+ * Unlike validateGraphConfig() which checks JSON structure, this checks:
+ *   - Dangling requires (tokens no task produces)
+ *   - Circular dependencies
+ *   - Provide conflicts (multiple tasks producing same token)
+ *   - Unreachable goal tokens
+ *   - Dead-end tasks (no provides)
+ *   - Self-dependencies
+ *   - Orphaned tasks (disconnected from the graph)
+ *
+ * Pure function — config in, diagnostics out.
+ */
+
+type IssueSeverity = 'error' | 'warning' | 'info';
+interface GraphIssue {
+    /** Severity: error = will break execution, warning = may cause problems, info = notable */
+    severity: IssueSeverity;
+    /** Machine-readable issue code */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Affected task names (if applicable) */
+    tasks?: string[];
+    /** Affected tokens (if applicable) */
+    tokens?: string[];
+}
+interface GraphValidationResult {
+    /** true if no errors (warnings/info are allowed) */
+    valid: boolean;
+    /** All issues found */
+    issues: GraphIssue[];
+    /** Just the errors */
+    errors: GraphIssue[];
+    /** Just the warnings */
+    warnings: GraphIssue[];
+}
+/**
+ * Validate the semantic correctness of a static event-graph configuration.
+ *
+ * Checks for logical issues that would cause execution failures, stuck states,
+ * or unexpected behavior. Does NOT check JSON structure (use validateGraphConfig for that).
+ *
+ * @param graph - The event-graph configuration to validate
+ * @returns Validation result with categorized issues
+ */
+declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+
 /**
  * Event Graph — Constants
  */
@@ -454,4 +504,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { next as $, type AgentActionEvent as A, createInitialExecutionState as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, detectStuckState as F, type GraphConfig as G, exportGraphConfig as H, type InjectTokensEvent as I, exportGraphConfigToFile as J, flowToMermaid as K, getAllTasks as L, type MermaidOptions as M, getCandidateTasks as N, getProvides as O, getRequires as P, getTask as Q, graphToMermaid as R, type SchedulerResult as S, type TaskConfig as T, hasTask as U, isExecutionComplete as V, isNonActiveTask as W, isRepeatableTask as X, isTaskCompleted as Y, isTaskRunning as Z, loadGraphConfig as _, CONFLICT_STRATEGIES as a, planExecution as a0, validateGraphConfig as a1, type RepeatableConfig as a2, type TaskCircuitBreakerConfig as a3, type TaskMessage as a4, type TaskProgressEvent as a5, type TaskRetryConfig as a6, addKeyToProvides as a7, addKeyToRequires as a8, getRepeatableMax as a9, groupTasksByProvides as aa, hasOutputConflict as ab, removeKeyFromProvides as ac, removeKeyFromRequires as ad, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphSettings as m, type StuckDetection as n, TASK_STATUS as o, type TaskCompletedEvent as p, type TaskCreationEvent as q, type TaskFailedEvent as r, type TaskStartedEvent as s, type TaskState as t, type TaskStatus as u, addDynamicTask as v, apply as w, applyAll as x, computeAvailableOutputs as y, createDefaultTaskState as z };
+export { isTaskCompleted as $, type AgentActionEvent as A, applyAll as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, computeAvailableOutputs as F, type GraphConfig as G, createDefaultTaskState as H, type InjectTokensEvent as I, createInitialExecutionState as J, detectStuckState as K, exportGraphConfig as L, type MermaidOptions as M, exportGraphConfigToFile as N, flowToMermaid as O, getAllTasks as P, getCandidateTasks as Q, getProvides as R, type SchedulerResult as S, type TaskConfig as T, getRequires as U, getTask as V, graphToMermaid as W, hasTask as X, isExecutionComplete as Y, isNonActiveTask as Z, isRepeatableTask as _, CONFLICT_STRATEGIES as a, isTaskRunning as a0, loadGraphConfig as a1, next as a2, planExecution as a3, validateGraph as a4, validateGraphConfig as a5, type RepeatableConfig as a6, type TaskCircuitBreakerConfig as a7, type TaskMessage as a8, type TaskProgressEvent as a9, type TaskRetryConfig as aa, addKeyToProvides as ab, addKeyToRequires as ac, getRepeatableMax as ad, groupTasksByProvides as ae, hasOutputConflict as af, removeKeyFromProvides as ag, removeKeyFromRequires as ah, type CompletionResult as b, type CompletionStrategy as c, type ConflictStrategy as d, EXECUTION_STATUS as e, type ExecutionConfig as f, type ExecutionMode as g, type ExecutionPlan as h, type ExecutionState as i, type ExecutionStatus as j, type ExportOptions as k, type GraphEvent as l, type GraphIssue as m, type GraphSettings as n, type GraphValidationResult as o, type IssueSeverity as p, type StuckDetection as q, TASK_STATUS as r, type TaskCompletedEvent as s, type TaskCreationEvent as t, type TaskFailedEvent as u, type TaskStartedEvent as v, type TaskState as w, type TaskStatus as x, addDynamicTask as y, apply as z };

package/dist/event-graph/index.cjs

@@ -1254,6 +1254,213 @@ ${serialized}`;
   return String(obj);
 }
 
+// src/event-graph/validate.ts
+function buildProducerMap2(tasks) {
+  const map = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getProvides(config)) {
+      if (!map[token]) map[token] = [];
+      map[token].push(name);
+    }
+    if (config.on) {
+      for (const tokens of Object.values(config.on)) {
+        for (const token of tokens) {
+          if (!map[token]) map[token] = [];
+          if (!map[token].includes(name)) map[token].push(name);
+        }
+      }
+    }
+    if (config.on_failure) {
+      for (const token of config.on_failure) {
+        if (!map[token]) map[token] = [];
+        if (!map[token].includes(name)) map[token].push(name);
+      }
+    }
+  }
+  return map;
+}
+function buildTaskDeps(tasks, producerMap) {
+  const deps = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    deps[name] = /* @__PURE__ */ new Set();
+    for (const token of getRequires(config)) {
+      for (const producer of producerMap[token] || []) {
+        if (producer !== name) deps[name].add(producer);
+      }
+    }
+  }
+  return deps;
+}
+function detectCycles(taskNames, deps) {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = {};
+  const parent = {};
+  const cycles = [];
+  for (const name of taskNames) {
+    color[name] = WHITE;
+    parent[name] = null;
+  }
+  function dfs(node) {
+    color[node] = GRAY;
+    for (const dep of deps[node] || []) {
+      if (color[dep] === GRAY) {
+        const cycle = [dep];
+        let cur = node;
+        while (cur !== dep) {
+          cycle.push(cur);
+          cur = parent[cur];
+        }
+        cycle.push(dep);
+        cycle.reverse();
+        cycles.push(cycle);
+      } else if (color[dep] === WHITE) {
+        parent[dep] = node;
+        dfs(dep);
+      }
+    }
+    color[node] = BLACK;
+  }
+  for (const name of taskNames) {
+    if (color[name] === WHITE) {
+      dfs(name);
+    }
+  }
+  return cycles;
+}
+function validateGraph(graph) {
+  const issues = [];
+  const tasks = getAllTasks(graph);
+  const taskNames = Object.keys(tasks);
+  if (taskNames.length === 0) {
+    issues.push({
+      severity: "error",
+      code: "EMPTY_GRAPH",
+      message: "Graph has no tasks"
+    });
+    return buildResult(issues);
+  }
+  const producerMap = buildProducerMap2(tasks);
+  const deps = buildTaskDeps(tasks, producerMap);
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getRequires(config)) {
+      if (!producerMap[token]) {
+        issues.push({
+          severity: "error",
+          code: "DANGLING_REQUIRES",
+          message: `Task "${name}" requires token "${token}" but no task produces it`,
+          tasks: [name],
+          tokens: [token]
+        });
+      }
+    }
+  }
+  const cycles = detectCycles(taskNames, deps);
+  for (const cycle of cycles) {
+    issues.push({
+      severity: "error",
+      code: "CIRCULAR_DEPENDENCY",
+      message: `Circular dependency: ${cycle.join(" \u2192 ")}`,
+      tasks: cycle.filter((_t, i) => i < cycle.length - 1)
+      // dedupe last = first
+    });
+  }
+  for (const [name, config] of Object.entries(tasks)) {
+    const req = getRequires(config);
+    const prov = getProvides(config);
+    const self = req.filter((token) => prov.includes(token));
+    if (self.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "SELF_DEPENDENCY",
+        message: `Task "${name}" requires tokens it provides itself: [${self.join(", ")}]`,
+        tasks: [name],
+        tokens: self
+      });
+    }
+  }
+  for (const [token, producers] of Object.entries(producerMap)) {
+    if (producers.length > 1) {
+      issues.push({
+        severity: "warning",
+        code: "PROVIDE_CONFLICT",
+        message: `Token "${token}" is produced by multiple tasks: [${producers.join(", ")}]. This requires a conflict strategy.`,
+        tasks: producers,
+        tokens: [token]
+      });
+    }
+  }
+  if (graph.settings.completion === "goal-reached" && graph.settings.goal) {
+    for (const goalToken of graph.settings.goal) {
+      if (!producerMap[goalToken]) {
+        issues.push({
+          severity: "error",
+          code: "UNREACHABLE_GOAL",
+          message: `Goal token "${goalToken}" cannot be produced by any task`,
+          tokens: [goalToken]
+        });
+      }
+    }
+  }
+  if (taskNames.length > 1) {
+    for (const [name, config] of Object.entries(tasks)) {
+      const prov = getProvides(config);
+      const onProv = config.on ? Object.values(config.on).flat() : [];
+      const failProv = config.on_failure || [];
+      if (prov.length === 0 && onProv.length === 0 && failProv.length === 0) {
+        issues.push({
+          severity: "warning",
+          code: "DEAD_END_TASK",
+          message: `Task "${name}" has no provides \u2014 it cannot unblock any downstream task`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  const allRequired = /* @__PURE__ */ new Set();
+  for (const config of Object.values(tasks)) {
+    for (const token of getRequires(config)) {
+      allRequired.add(token);
+    }
+  }
+  for (const [name, config] of Object.entries(tasks)) {
+    const req = getRequires(config);
+    const prov = getProvides(config);
+    const onProv = config.on ? Object.values(config.on).flat() : [];
+    const allProv = [...prov, ...onProv];
+    const isEntryPoint = req.length === 0;
+    const hasDownstream = allProv.some((token) => allRequired.has(token));
+    if (isEntryPoint && !hasDownstream && taskNames.length > 1) {
+      const isGoalRelevant = graph.settings.completion === "goal-reached" && graph.settings.goal?.some((g) => allProv.includes(g));
+      if (!isGoalRelevant) {
+        issues.push({
+          severity: "info",
+          code: "ISOLATED_TASK",
+          message: `Task "${name}" is disconnected \u2014 it has no requires and nothing depends on its provides`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  if (graph.settings.completion === "goal-reached" && !graph.settings.goal) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_GOAL",
+      message: 'Completion strategy is "goal-reached" but no goal tokens are defined'
+    });
+  }
+  return buildResult(issues);
+}
+function buildResult(issues) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  return {
+    valid: errors.length === 0,
+    issues,
+    errors,
+    warnings
+  };
+}
+
 exports.COMPLETION_STRATEGIES = COMPLETION_STRATEGIES;
 exports.CONFLICT_STRATEGIES = CONFLICT_STRATEGIES;
 exports.DEFAULTS = DEFAULTS;
@@ -1299,6 +1506,7 @@ exports.removeKeyFromProvides = removeKeyFromProvides;
 exports.removeKeyFromRequires = removeKeyFromRequires;
 exports.selectBestAlternative = selectBestAlternative;
 exports.selectRandomTasks = selectRandomTasks;
+exports.validateGraph = validateGraph;
 exports.validateGraphConfig = validateGraphConfig;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map