yaml-flow 3.0.0 → 3.1.0

package/README.md

@@ -1069,11 +1069,10 @@ import { createReactiveGraph, MemoryJournal } from 'yaml-flow/continuous-event-g
 // 1. Create with handlers
 const rg = createReactiveGraph(config, {
   handlers: {
-    fetch:     async (ctx) => { const data = await fetchAPI(); return { dataHash: hash(data) }; },
-    transform: async (ctx) => { return { result: 'success' }; },
-    notify:    async (ctx) => { await sendSlack('done'); return {}; },
+    fetch:     async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
+    transform: async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
+    notify:    async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
   },
-  defaultTimeoutMs: 30_000,
   onDrain: (events, live, schedule) => console.log(`${events.length} events, ${schedule.eligible.length} eligible`),
 });
 
@@ -1081,18 +1080,30 @@ const rg = createReactiveGraph(config, {
 rg.push({ type: 'inject-tokens', tokens: [], timestamp: new Date().toISOString() });
 // fetch runs -> completes -> transform becomes eligible -> runs -> notify -> done
 
-// 3. Add nodes at runtime (with handler)
-rg.addNode('alert', { requires: ['anomaly'], provides: ['alerted'] }, async (ctx) => {
-  await pageOncall(ctx.taskName);
-  return {};
+// 3. Add nodes at runtime
+rg.addNode('alert', { requires: ['anomaly'], provides: ['alerted'], taskHandlers: ['alert'] });
+rg.registerHandler('alert', async ({ callbackToken }) => {
+  // ... do work, then resolve the callback
+  rg.resolveCallback(callbackToken, { alerted: true });
+  return 'task-initiated';
 });
 
-// 4. Read state
+// 4. Dynamic wiring mutations
+rg.addRequires('alert', ['sentiment']);      // add a new dependency
+rg.removeRequires('alert', ['sentiment']);   // detach it
+rg.addProvides('fetch', ['market-data']);    // produce a new token
+rg.removeProvides('fetch', ['market-data']); // stop producing it
+
+// 5. Batch events + selective retrigger
+rg.pushAll([event1, event2]);               // atomic multi-event push
+rg.retrigger('fetch');                       // re-run a single task
+rg.retriggerAll(['fetch', 'transform']);     // re-run multiple tasks
+
+// 6. Read state
 rg.getState();          // LiveGraph snapshot
 rg.getSchedule();       // current ScheduleResult
-rg.getDispatchState();  // Map<taskName, DispatchEntry>
 
-// 5. Cleanup
+// 7. Cleanup
 rg.dispose();
 ```
 
@@ -1110,27 +1121,36 @@ push(event)
 
 The journal serializes concurrent callbacks — multiple handlers complete simultaneously, their events batch into a single `applyEvents()` call. No race conditions.
 
-**Dispatch lifecycle (reactive-layer internal, NOT in core types):**
+**Handler model:** Handlers are initiators. They receive a `callbackToken` and return `'task-initiated'` or `'task-initiate-failure'`. When work completes, call `rg.resolveCallback(token, data, errors?)` to push the result back through the engine.
+
+**ReactiveGraph API:**
 
-| Status | Meaning |
+| Method | Description |
 |---|---|
-| `initiated` | Handler callback fired, awaiting response |
-| `dispatch-failed` | Handler threw synchronously |
-| `timed-out` | No callback within deadline |
-| `retry-queued` | Will retry on next drain cycle |
-| `abandoned` | Max dispatch retries exceeded -> pushes `task-failed` to core |
+| `push(event)` | Push a single event into the engine |
+| `pushAll(events)` | Push multiple events atomically |
+| `resolveCallback(token, data, errors?)` | Resolve a handler's callback token |
+| `addNode(name, config)` | Add a task to the live graph |
+| `removeNode(name)` | Remove a task from the live graph |
+| `addRequires(name, tokens)` | Add require tokens to a task |
+| `removeRequires(name, tokens)` | Remove require tokens from a task |
+| `addProvides(name, tokens)` | Add provide tokens to a task |
+| `removeProvides(name, tokens)` | Remove provide tokens from a task |
+| `registerHandler(name, fn)` | Register a named handler |
+| `unregisterHandler(name)` | Unregister a handler |
+| `retrigger(name)` | Reset and re-run a single task |
+| `retriggerAll(names)` | Reset and re-run multiple tasks |
+| `getState()` | Current LiveGraph snapshot |
+| `getSchedule()` | Current ScheduleResult |
+| `dispose()` | Shut down the reactive graph |
 
 **Options:**
 
 | Option | Default | Description |
 |---|---|---|
-| `handlers` | (required) | `Record<string, TaskHandler>` |
-| `maxDispatchRetries` | `3` | Times to retry invoking a handler |
-| `defaultTimeoutMs` | `30000` | Handler callback deadline (0 = no timeout) |
+| `handlers` | (required) | `Record<string, TaskHandlerFn>` |
 | `journal` | `MemoryJournal` | Event log adapter (`MemoryJournal` or `FileJournal`) |
 | `onDrain` | — | Called after each drain cycle (observability) |
-| `onDispatchFailed` | — | Called when handler invocation fails |
-| `onAbandoned` | — | Called when task dispatch is abandoned |
 
 ---
 
@@ -1484,6 +1504,7 @@ See the [examples/](./examples) directory:
 | [Stock Dashboard](./examples/continuous-event-graph/stock-dashboard.ts) | Continuous Event Graph | Runtime mutations, token drain, upstream/downstream, snapshot |
 | [Reactive Pipeline](./examples/continuous-event-graph/reactive-pipeline.ts) | Reactive Graph | Self-driving ETL — push once, 4 tasks complete automatically |
 | [Reactive Monitoring](./examples/continuous-event-graph/reactive-monitoring.ts) | Reactive Graph | Conditional routing, on_failure escalation, runtime addNode |
+| [Live Portfolio Dashboard](./examples/continuous-event-graph/live-portfolio-dashboard.ts) | Reactive Graph + Live Cards | 15+ cards, disk roundtrip, addRequires/removeRequires, addProvides/removeProvides, pushAll, retriggerAll |
 | [Executor Pipeline](./examples/event-graph/executor-pipeline.ts) | Event Graph (library) | You-drive-the-loop ETL with random async delays |
 | [Executor Diamond](./examples/event-graph/executor-diamond.ts) | Event Graph (library) | Parallel fan-out/fan-in diamond DAG with async executors |
 | [Azure Deployment](./examples/inference/azure-deployment.ts) | Inference | LLM analyzes deployment logs, auto-completes checkpoints |

package/dist/{constants-B_ftYTTE.d.ts → constants-B2zqu10b.d.ts}

@@ -1,4 +1,4 @@
-import { G as GraphConfig, c as ExecutionState, S as SchedulerResult, e as GraphEvent, T as TaskConfig, l as TaskState, R as RefreshStrategy, g as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-BpWrH1sf.js';
+import { G as GraphConfig, c as ExecutionState, S as SchedulerResult, f as GraphEvent, T as TaskConfig, e as GraphEngineStore, R as RefreshStrategy, h as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-DEj7OakX.js';
 import { e as StepFlowConfig } from './types-FZ_eyErS.js';
 
 /**
@@ -54,9 +54,9 @@ declare function getRequires(task: TaskConfig | undefined): string[];
 declare function getAllTasks(graph: GraphConfig): Record<string, TaskConfig>;
 declare function getTask(graph: GraphConfig, taskName: string): TaskConfig | undefined;
 declare function hasTask(graph: GraphConfig, taskName: string): boolean;
-declare function isNonActiveTask(taskState: TaskState | undefined): boolean;
-declare function isTaskCompleted(taskState: TaskState | undefined): boolean;
-declare function isTaskRunning(taskState: TaskState | undefined): boolean;
+declare function isNonActiveTask(taskState: GraphEngineStore | undefined): boolean;
+declare function isTaskCompleted(taskState: GraphEngineStore | undefined): boolean;
+declare function isTaskRunning(taskState: GraphEngineStore | undefined): boolean;
 declare function getRefreshStrategy(taskConfig: TaskConfig, graphSettings?: {
     refreshStrategy?: RefreshStrategy;
 }): RefreshStrategy;
@@ -69,7 +69,7 @@ declare function getMaxExecutions(taskConfig: TaskConfig): number | undefined;
  * Tasks with strategies other than 'once' may have completed and reset.
  * Pure function.
  */
-declare function computeAvailableOutputs(graph: GraphConfig, taskStates: Record<string, TaskState>): string[];
+declare function computeAvailableOutputs(graph: GraphConfig, taskStates: Record<string, GraphEngineStore>): string[];
 /**
  * Group candidate tasks by the outputs they provide.
  * Used to detect conflicts (multiple tasks providing the same output).
@@ -90,7 +90,7 @@ declare function addDynamicTask(graph: GraphConfig, taskName: string, taskConfig
 /**
  * Create default task state for a new task.
  */
-declare function createDefaultTaskState(): TaskState;
+declare function createDefaultGraphEngineStore(): GraphEngineStore;
 /**
  * Create the initial execution state for a graph.
  */
@@ -258,56 +258,6 @@ 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;
-
 /**
  * schema-validator — Full JSON Schema validation for EventGraph configs.
  *
@@ -349,4 +299,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { isNonActiveTask as A, isRerunnable as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, isTaskCompleted as F, type GraphIssue as G, isTaskRunning as H, type IssueSeverity as I, loadGraphConfig as J, next as K, planExecution as L, type MermaidOptions as M, validateGraph as N, validateGraphConfig as O, validateGraphSchema as P, addKeyToProvides as Q, addKeyToRequires as R, groupTasksByProvides as S, TASK_STATUS as T, hasOutputConflict as U, removeKeyFromProvides as V, removeKeyFromRequires as W, 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, getMaxExecutions as s, getProvides as t, getRefreshStrategy as u, getRequires as v, getTask as w, graphToMermaid as x, hasTask as y, isExecutionComplete as z };
+export { isRerunnable as A, isTaskCompleted as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, isTaskRunning as F, loadGraphConfig as G, next as H, planExecution as I, validateGraphConfig as J, validateGraphSchema as K, addKeyToProvides as L, type MermaidOptions as M, addKeyToRequires as N, groupTasksByProvides as O, hasOutputConflict as P, removeKeyFromProvides as Q, removeKeyFromRequires as R, TASK_STATUS as T, CONFLICT_STRATEGIES as a, type CompletionResult as b, EXECUTION_STATUS as c, type ExecutionPlan as d, type ExportOptions as e, addDynamicTask as f, apply as g, applyAll as h, computeAvailableOutputs as i, createDefaultGraphEngineStore as j, createInitialExecutionState as k, detectStuckState as l, exportGraphConfig as m, exportGraphConfigToFile as n, flowToMermaid as o, getAllTasks as p, getCandidateTasks as q, getMaxExecutions as r, getProvides as s, getRefreshStrategy as t, getRequires as u, getTask as v, graphToMermaid as w, hasTask as x, isExecutionComplete as y, isNonActiveTask as z };

package/dist/{constants-CiyHX8L-.d.cts → constants-DJZU1pwJ.d.cts}

@@ -1,4 +1,4 @@
-import { G as GraphConfig, c as ExecutionState, S as SchedulerResult, e as GraphEvent, T as TaskConfig, l as TaskState, R as RefreshStrategy, g as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-BpWrH1sf.cjs';
+import { G as GraphConfig, c as ExecutionState, S as SchedulerResult, f as GraphEvent, T as TaskConfig, e as GraphEngineStore, R as RefreshStrategy, h as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-DEj7OakX.cjs';
 import { e as StepFlowConfig } from './types-FZ_eyErS.cjs';
 
 /**
@@ -54,9 +54,9 @@ declare function getRequires(task: TaskConfig | undefined): string[];
 declare function getAllTasks(graph: GraphConfig): Record<string, TaskConfig>;
 declare function getTask(graph: GraphConfig, taskName: string): TaskConfig | undefined;
 declare function hasTask(graph: GraphConfig, taskName: string): boolean;
-declare function isNonActiveTask(taskState: TaskState | undefined): boolean;
-declare function isTaskCompleted(taskState: TaskState | undefined): boolean;
-declare function isTaskRunning(taskState: TaskState | undefined): boolean;
+declare function isNonActiveTask(taskState: GraphEngineStore | undefined): boolean;
+declare function isTaskCompleted(taskState: GraphEngineStore | undefined): boolean;
+declare function isTaskRunning(taskState: GraphEngineStore | undefined): boolean;
 declare function getRefreshStrategy(taskConfig: TaskConfig, graphSettings?: {
     refreshStrategy?: RefreshStrategy;
 }): RefreshStrategy;
@@ -69,7 +69,7 @@ declare function getMaxExecutions(taskConfig: TaskConfig): number | undefined;
  * Tasks with strategies other than 'once' may have completed and reset.
  * Pure function.
  */
-declare function computeAvailableOutputs(graph: GraphConfig, taskStates: Record<string, TaskState>): string[];
+declare function computeAvailableOutputs(graph: GraphConfig, taskStates: Record<string, GraphEngineStore>): string[];
 /**
  * Group candidate tasks by the outputs they provide.
  * Used to detect conflicts (multiple tasks providing the same output).
@@ -90,7 +90,7 @@ declare function addDynamicTask(graph: GraphConfig, taskName: string, taskConfig
 /**
  * Create default task state for a new task.
  */
-declare function createDefaultTaskState(): TaskState;
+declare function createDefaultGraphEngineStore(): GraphEngineStore;
 /**
  * Create the initial execution state for a graph.
  */
@@ -258,56 +258,6 @@ 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;
-
 /**
  * schema-validator — Full JSON Schema validation for EventGraph configs.
  *
@@ -349,4 +299,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-export { isNonActiveTask as A, isRerunnable as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, isTaskCompleted as F, type GraphIssue as G, isTaskRunning as H, type IssueSeverity as I, loadGraphConfig as J, next as K, planExecution as L, type MermaidOptions as M, validateGraph as N, validateGraphConfig as O, validateGraphSchema as P, addKeyToProvides as Q, addKeyToRequires as R, groupTasksByProvides as S, TASK_STATUS as T, hasOutputConflict as U, removeKeyFromProvides as V, removeKeyFromRequires as W, 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, getMaxExecutions as s, getProvides as t, getRefreshStrategy as u, getRequires as v, getTask as w, graphToMermaid as x, hasTask as y, isExecutionComplete as z };
+export { isRerunnable as A, isTaskCompleted as B, COMPLETION_STRATEGIES as C, DEFAULTS as D, EXECUTION_MODES as E, isTaskRunning as F, loadGraphConfig as G, next as H, planExecution as I, validateGraphConfig as J, validateGraphSchema as K, addKeyToProvides as L, type MermaidOptions as M, addKeyToRequires as N, groupTasksByProvides as O, hasOutputConflict as P, removeKeyFromProvides as Q, removeKeyFromRequires as R, TASK_STATUS as T, CONFLICT_STRATEGIES as a, type CompletionResult as b, EXECUTION_STATUS as c, type ExecutionPlan as d, type ExportOptions as e, addDynamicTask as f, apply as g, applyAll as h, computeAvailableOutputs as i, createDefaultGraphEngineStore as j, createInitialExecutionState as k, detectStuckState as l, exportGraphConfig as m, exportGraphConfigToFile as n, flowToMermaid as o, getAllTasks as p, getCandidateTasks as q, getMaxExecutions as r, getProvides as s, getRefreshStrategy as t, getRequires as u, getTask as v, graphToMermaid as w, hasTask as x, isExecutionComplete as y, isNonActiveTask as z };