yaml-flow 2.2.0 → 2.4.0

package/README.md

@@ -801,6 +801,188 @@ 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.
+
+---
+
+## Continuous Event Graph
+
+A **long-lived, evolving** event-graph where both the graph config and execution state mutate over time. Ideal for dashboards, monitoring systems, and any scenario where the workflow has no fixed endpoint.
+
+The core type is `LiveGraph` — it bundles `config` + `state` so they can't get out of sync. Every function is pure: `f(LiveGraph, input) → LiveGraph`.
+
+```typescript
+import {
+  createLiveGraph, applyEvent,
+  addNode, removeNode,
+  addRequires, removeRequires, addProvides, removeProvides,
+  injectTokens, drainTokens,
+  schedule, inspect,
+  resetNode, disableNode, enableNode, getNode,
+  snapshot, restore,
+  getUnreachableTokens, getUnreachableNodes,
+  getUpstream, getDownstream,
+} from 'yaml-flow/continuous-event-graph';
+```
+
+### Quick Start
+
+```typescript
+import { createLiveGraph, applyEvent, addNode, schedule, inspect } from 'yaml-flow/continuous-event-graph';
+
+// 1. Bootstrap
+let live = createLiveGraph({
+  settings: { completion: 'manual' },
+  tasks: {
+    fetch_prices: { provides: ['price-data'] },
+    compute:      { requires: ['price-data'], provides: ['indicators'] },
+  },
+});
+
+// 2. Schedule — what's ready?
+schedule(live).eligible;  // ['fetch_prices']
+
+// 3. Apply events — immutable state transitions
+live = applyEvent(live, { type: 'task-started', taskName: 'fetch_prices', timestamp: new Date().toISOString() });
+live = applyEvent(live, { type: 'task-completed', taskName: 'fetch_prices', timestamp: new Date().toISOString() });
+schedule(live).eligible;  // ['compute']
+
+// 4. Evolve — add a node at runtime
+live = addNode(live, 'alert', { requires: ['indicators'], provides: ['alert-sent'] });
+
+// 5. Health check
+inspect(live);  // { totalNodes: 3, running: 0, completed: 1, ... }
+```
+
+### Graph Mutations
+
+| Function | Description |
+|---|---|
+| `addNode(live, name, config)` | Add a task to the graph (config + state) |
+| `removeNode(live, name)` | Remove a task from the graph |
+| `addRequires(live, node, tokens)` | Add requires tokens to a node |
+| `removeRequires(live, node, tokens)` | Remove requires tokens from a node |
+| `addProvides(live, node, tokens)` | Add provides tokens to a node |
+| `removeProvides(live, node, tokens)` | Remove provides tokens from a node |
+
+### Token Management
+
+```typescript
+// Inject external data/signals
+live = injectTokens(live, ['market-open', 'price-data']);
+
+// Drain stale/expired tokens
+live = drainTokens(live, ['price-data']);  // forces re-fetch before downstream can run
+```
+
+### Node Lifecycle
+
+| Function | Description |
+|---|---|
+| `resetNode(live, name)` | Reset a node to `not-started` (for retry) |
+| `disableNode(live, name)` | Set a node to `inactivated` (scheduler skips it) |
+| `enableNode(live, name)` | Re-enable a disabled node |
+| `getNode(live, name)` | Get config + state for a single node |
+
+### Graph Traversal
+
+```typescript
+// "What feeds into generate_signals?"
+const upstream = getUpstream(live, 'generate_signals');
+upstream.nodes;   // [{ nodeName: 'fetch_prices', providesTokens: ['price-data'] }, ...]
+upstream.tokens;  // ['price-data', 'indicators', ...]
+
+// "What breaks if fetch_prices goes down?"
+const downstream = getDownstream(live, 'fetch_prices');
+downstream.nodes;   // [{ nodeName: 'compute', requiresTokens: ['price-data'] }, ...]
+downstream.tokens;  // ['price-data', 'indicators', ...]
+```
+
+### Reachability Analysis
+
+```typescript
+// Tokens that can never be produced given the current state
+const unreachableTokens = getUnreachableTokens(live);
+unreachableTokens.tokens;  // [{ token: 'ghost', reason: 'no-producer', producers: [] }]
+
+// Nodes that can never become eligible
+const unreachableNodes = getUnreachableNodes(live);
+unreachableNodes.nodes;  // [{ nodeName: 'orphan', missingTokens: ['ghost'] }]
+```
+
+### Persistence
+
+```typescript
+// Save
+const snap = snapshot(live);        // JSON-safe object
+localStorage.setItem('graph', JSON.stringify(snap));
+
+// Restore
+const data = JSON.parse(localStorage.getItem('graph')!);
+const restored = restore(data);     // → LiveGraph (validates shape)
+```
+
+### Continuous Event Graph API Reference
+
+| Function | Description |
+|---|---|
+| `createLiveGraph(config, id?)` | Bootstrap a LiveGraph from a GraphConfig |
+| `applyEvent(live, event)` | Apply an execution event (task-started, task-completed, etc.) |
+| `addNode(live, name, config)` | Add a node (both config + state) |
+| `removeNode(live, name)` | Remove a node |
+| `addRequires / removeRequires` | Wire/unwire requires tokens |
+| `addProvides / removeProvides` | Wire/unwire provides tokens |
+| `injectTokens(live, tokens)` | Add tokens to available outputs |
+| `drainTokens(live, tokens)` | Remove tokens from available outputs |
+| `schedule(live)` | Classify tasks: eligible / pending / unresolved / blocked / conflicts |
+| `inspect(live)` | Health report: statuses, cycles, open deps, conflicts |
+| `resetNode(live, name)` | Reset node to not-started |
+| `disableNode(live, name)` | Disable a node (inactivated) |
+| `enableNode(live, name)` | Re-enable a disabled node |
+| `getNode(live, name)` | Get a node's config + state |
+| `getUpstream(live, name)` | Transitive upstream: what feeds into this node? |
+| `getDownstream(live, name)` | Transitive downstream: what depends on this node? |
+| `getUnreachableTokens(live)` | Tokens that can never be produced |
+| `getUnreachableNodes(live)` | Nodes that can never become eligible |
+| `snapshot(live)` | Serialize to a JSON-safe snapshot |
+| `restore(data)` | Restore a LiveGraph from a snapshot |
+
+---
+
 ## Loading & Exporting Graph Configs
 
 ```typescript
@@ -835,6 +1017,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
@@ -847,6 +1030,17 @@ import type { BatchOptions, BatchResult, BatchItemResult, BatchProgress } from '
 // Config utilities
 import { resolveVariables, resolveConfigTemplates } from 'yaml-flow/config';
 
+// Continuous Event Graph (long-lived evolving workflows)
+import {
+  createLiveGraph, applyEvent, addNode, removeNode,
+  addRequires, removeRequires, addProvides, removeProvides,
+  injectTokens, drainTokens, schedule, inspect,
+  resetNode, disableNode, enableNode, getNode,
+  snapshot, restore,
+  getUnreachableTokens, getUnreachableNodes,
+  getUpstream, getDownstream,
+} from 'yaml-flow/continuous-event-graph';
+
 // Backward compatibility (v1 names → v2)
 import { FlowEngine, createEngine } from 'yaml-flow';  // aliases for StepMachine, createStepMachine
 ```
@@ -889,6 +1083,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()`)
 
@@ -917,6 +1112,7 @@ See the [examples/](./examples) directory:
 | [Batch Tickets](./examples/batch/batch-step-machine.ts) | Batch | Concurrent processing, progress tracking |
 | [URL Pipeline](./examples/graph-of-graphs/url-processing-pipeline.ts) | Graph-of-Graphs | Outer event-graph → batch × inner event-graph per item |
 | [Multi-Stage ETL](./examples/graph-of-graphs/multi-stage-etl.ts) | Graph-of-Graphs | Mixed modes: event-graph outer → step-machine + event-graph subs |
+| [Stock Dashboard](./examples/continuous-event-graph/stock-dashboard.ts) | Continuous Event Graph | Runtime mutations, token drain, upstream/downstream, snapshot |
 | [Order Processing](./examples/flows/order-processing.yaml) | Step Machine | YAML flow definition |
 | [Browser Demo](./examples/browser/index.html) | Step Machine | In-browser usage |
 

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

@@ -1,191 +1,6 @@
+import { G as GraphConfig, c as ExecutionState, S as SchedulerResult, e as GraphEvent, T as TaskConfig, l as TaskState, g as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-CTu8RqY0.cjs';
 import { e as StepFlowConfig } from './types-FZ_eyErS.cjs';
 
-/**
- * Event Graph — Core Types
- *
- * Type definitions for the stateless event-graph engine.
- * Pure: f(state, event) → newState
- */
-interface GraphConfig {
-    id?: string;
-    settings: GraphSettings;
-    tasks: Record<string, TaskConfig>;
-}
-interface GraphSettings {
-    /** Completion strategy */
-    completion: CompletionStrategy;
-    /** Conflict resolution strategy */
-    conflict_strategy?: ConflictStrategy;
-    /** Execution mode */
-    execution_mode?: ExecutionMode;
-    /** Goal outputs — used with 'goal-reached' completion */
-    goal?: string[];
-    /** Max total scheduler iterations (safety limit, default: 1000) */
-    max_iterations?: number;
-    /** Timeout in ms (declared for drivers, not enforced by pure engine) */
-    timeout_ms?: number;
-}
-interface TaskConfig {
-    /** What this task needs to become eligible */
-    requires?: string[];
-    /** What this task produces on successful completion */
-    provides: string[];
-    /** Conditional provides based on handler result */
-    on?: Record<string, string[]>;
-    /** Tokens to inject into available outputs on failure */
-    on_failure?: string[];
-    /** Task execution method (informational — driver concern) */
-    method?: string;
-    /** Arbitrary task configuration (driver concern) */
-    config?: Record<string, unknown>;
-    /** Task priority (higher = preferred in conflict resolution) */
-    priority?: number;
-    /** Estimated duration in ms (used by duration-first strategy) */
-    estimatedDuration?: number;
-    /** Estimated cost (used by cost-optimized strategy) */
-    estimatedCost?: number;
-    /** Resource requirements (used by resource-aware strategy) */
-    estimatedResources?: Record<string, number>;
-    /** Retry configuration */
-    retry?: TaskRetryConfig;
-    /** Repeatable task configuration */
-    repeatable?: boolean | RepeatableConfig;
-    /** Circuit breaker: max executions before breaking */
-    circuit_breaker?: TaskCircuitBreakerConfig;
-    /** Description */
-    description?: string;
-}
-interface TaskRetryConfig {
-    max_attempts: number;
-    delay_ms?: number;
-    backoff_multiplier?: number;
-}
-interface RepeatableConfig {
-    /** Max times this task can repeat (undefined = unlimited) */
-    max?: number;
-}
-interface TaskCircuitBreakerConfig {
-    /** Max executions before injecting break tokens */
-    max_executions: number;
-    /** Tokens to inject when breaker trips */
-    on_break: string[];
-}
-interface ExecutionState {
-    /** Current status of the execution */
-    status: ExecutionStatus;
-    /** Task states keyed by task name */
-    tasks: Record<string, TaskState>;
-    /** Tokens currently available in the system */
-    availableOutputs: string[];
-    /** Stuck detection result */
-    stuckDetection: StuckDetection;
-    /** Last update timestamp */
-    lastUpdated: string;
-    /** Execution ID for this run */
-    executionId: string | null;
-    /** Execution configuration */
-    executionConfig: ExecutionConfig;
-}
-interface ExecutionConfig {
-    executionMode: ExecutionMode;
-    conflictStrategy: ConflictStrategy;
-    completionStrategy: CompletionStrategy;
-}
-interface TaskState {
-    status: TaskStatus;
-    executionCount: number;
-    retryCount: number;
-    lastEpoch: number;
-    startedAt?: string;
-    completedAt?: string;
-    failedAt?: string;
-    lastUpdated?: string;
-    error?: string;
-    messages?: TaskMessage[];
-    progress?: number | null;
-}
-interface TaskMessage {
-    message: string;
-    timestamp: string;
-    status: string;
-}
-interface StuckDetection {
-    is_stuck: boolean;
-    stuck_description: string | null;
-    outputs_unresolvable: string[];
-    tasks_blocked: string[];
-}
-type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | InjectTokensEvent | AgentActionEvent | TaskCreationEvent;
-interface TaskStartedEvent {
-    type: 'task-started';
-    taskName: string;
-    timestamp: string;
-    executionId?: string;
-}
-interface TaskCompletedEvent {
-    type: 'task-completed';
-    taskName: string;
-    /** Handler result key — used for conditional routing via `on` */
-    result?: string;
-    /** Data payload from task execution */
-    data?: Record<string, unknown>;
-    timestamp: string;
-    executionId?: string;
-}
-interface TaskFailedEvent {
-    type: 'task-failed';
-    taskName: string;
-    error: string;
-    timestamp: string;
-    executionId?: string;
-}
-interface TaskProgressEvent {
-    type: 'task-progress';
-    taskName: string;
-    message?: string;
-    progress?: number;
-    timestamp: string;
-    executionId?: string;
-}
-interface InjectTokensEvent {
-    type: 'inject-tokens';
-    tokens: string[];
-    timestamp: string;
-}
-interface AgentActionEvent {
-    type: 'agent-action';
-    action: 'start' | 'stop' | 'pause' | 'resume';
-    timestamp: string;
-    config?: Partial<ExecutionConfig>;
-}
-interface TaskCreationEvent {
-    type: 'task-creation';
-    taskName: string;
-    taskConfig: TaskConfig;
-    timestamp: string;
-}
-interface SchedulerResult {
-    /** Tasks eligible for execution */
-    eligibleTasks: string[];
-    /** Whether the graph execution is complete */
-    isComplete: boolean;
-    /** Stuck detection result */
-    stuckDetection: StuckDetection;
-    /** Whether conflicts were detected */
-    hasConflicts: boolean;
-    /** Conflict groups: output → competing task names */
-    conflicts: Record<string, string[]>;
-    /** Strategy used for conflict resolution */
-    strategy: ConflictStrategy;
-    /** Processing log for diagnostics */
-    processingLog: string[];
-}
-type TaskStatus = 'not-started' | 'running' | 'completed' | 'failed' | 'inactivated';
-type ExecutionStatus = 'created' | 'running' | 'paused' | 'stopped' | 'completed' | 'failed';
-type CompletionStrategy = 'all-tasks-done' | 'all-outputs-done' | 'only-resolved' | 'goal-reached' | 'manual';
-type ExecutionMode = 'dependency-mode' | 'eligibility-mode';
-type ConflictStrategy = 'alphabetical' | 'priority-first' | 'duration-first' | 'cost-optimized' | 'resource-aware' | 'random-select' | 'user-choice' | 'parallel-all' | 'skip-conflicts' | 'round-robin';
-
 /**
  * Event Graph — Scheduler
  *
@@ -438,6 +253,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 +319,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 A, isTaskRunning as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, loadGraphConfig as F, type GraphIssue as G, next as H, type IssueSeverity as I, planExecution as J, validateGraph as K, validateGraphConfig as L, type MermaidOptions as M, addKeyToProvides as N, addKeyToRequires as O, getRepeatableMax as P, groupTasksByProvides as Q, hasOutputConflict as R, removeKeyFromProvides as S, TASK_STATUS as T, removeKeyFromRequires as U, CONFLICT_STRATEGIES as a, type CompletionResult as b, EXECUTION_STATUS as c, type ExecutionPlan as d, type ExportOptions as e, type GraphValidationResult as f, addDynamicTask as g, apply as h, applyAll as i, computeAvailableOutputs as j, createDefaultTaskState as k, createInitialExecutionState as l, detectStuckState as m, exportGraphConfig as n, exportGraphConfigToFile as o, flowToMermaid as p, getAllTasks as q, getCandidateTasks as r, getProvides as s, getRequires as t, getTask as u, graphToMermaid as v, hasTask as w, isExecutionComplete as x, isNonActiveTask as y, isRepeatableTask as z };