yaml-flow 2.8.0 → 3.1.0

package/README.md

@@ -280,7 +280,9 @@ That's the entire integration. ~30 lines. The engine is pure; your loop owns the
 | Conditional routing | `on: { positive: [pos-result], negative: [neg-result] }` | Different outputs based on task result |
 | Failure tokens | `on_failure: [data-unavailable]` | Inject tokens on failure so downstream alternatives can activate |
 | Retry | `retry: { max_attempts: 3 }` | Auto-retry on failure (task resets to not-started) |
-| Repeatable tasks | `repeatable: true` or `repeatable: { max: 5 }` | Task can re-execute when its inputs refresh |
+| Refresh strategy | `refreshStrategy: 'data-changed'` (default) | When a completed task should re-run: `data-changed`, `epoch-changed`, `time-based`, `manual`, `once` |
+| Max executions | `maxExecutions: 5` | Cap how many times a task can execute |
+| Refresh interval | `refreshInterval: 300` | Seconds between re-runs (for `time-based` strategy) |
 | Circuit breaker | `circuit_breaker: { max_executions: 10, on_break: [stop-token] }` | Inject tokens after N executions |
 | External events | `apply(state, { type: 'inject-tokens', tokens: ['user-approved'] })` | Unblock tasks waiting on external input |
 | Dynamic tasks | `apply(state, { type: 'task-creation', taskName: 'new', taskConfig: {...} })` | Add tasks at runtime |
@@ -352,11 +354,55 @@ tasks:
   revise:
     requires: [needs-revision]
     provides: [draft-answer]
-    repeatable: { max: 3 }
+    refreshStrategy: epoch-changed
+    maxExecutions: 3
 ```
 
 The three searches run in parallel. `synthesize` waits for all three. `verify` can produce different token sets depending on its result. If rejected, `revise` picks up and feeds back into `verify` (up to 3 times). If verify itself fails, `verification-skipped` unblocks any downstream task waiting on it.
 
+### Refresh Strategies
+
+| Strategy | Behavior |
+|---|---|
+| `data-changed` (default) | Re-run when upstream output content changes (tracked via `dataHash`) |
+| `epoch-changed` | Re-run when upstream task execution count increases (classic "inputs refreshed") |
+| `time-based` | Re-run after `refreshInterval` seconds since last completion |
+| `manual` | Never auto-eligible; only via external `inject-tokens` or explicit push |
+| `once` | Run once, never re-run (classic one-shot task) |
+
+Set a board-level default in `settings.refreshStrategy`, then override per-task:
+
+```yaml
+settings:
+  completion: manual
+  refreshStrategy: epoch-changed   # board default
+tasks:
+  fetch_prices:
+    provides: [price-data]
+    refreshStrategy: time-based     # override: poll every 60s
+    refreshInterval: 60
+  compute:
+    requires: [price-data]
+    provides: [indicators]
+    # inherits epoch-changed from settings
+  alert:
+    requires: [indicators]
+    provides: [alert-sent]
+    refreshStrategy: data-changed   # override: only if indicators actually changed
+    maxExecutions: 10               # safety cap
+```
+
+Handlers can return a `dataHash` with completion events to enable content-aware freshness:
+
+```typescript
+apply(state, {
+  type: 'task-completed',
+  taskName: 'fetch_prices',
+  dataHash: crypto.createHash('md5').update(JSON.stringify(data)).digest('hex'),
+  timestamp: new Date().toISOString(),
+}, graph);
+```
+
 ### Pattern: Order Processing Pipeline (Step Machine)
 
 ```yaml
@@ -839,6 +885,37 @@ Use `validateGraphConfig()` for structural checks (JSON shape) and `validateGrap
 
 ---
 
+## JSON Schema Validation
+
+Full structural validation using AJV against the JSON Schema definitions. Catches malformed configs before they reach the engine.
+
+```typescript
+import { validateGraphSchema } from 'yaml-flow/event-graph';
+import { validateFlowSchema } from 'yaml-flow/step-machine';
+import { validateLiveCardSchema } from 'yaml-flow/card-compute';
+
+// Event graph
+const r1 = validateGraphSchema(config);
+r1.ok;      // true | false
+r1.errors;  // AJV error objects (when invalid)
+
+// Step machine
+const r2 = validateFlowSchema(config);
+
+// Live cards
+const r3 = validateLiveCardSchema(config);
+```
+
+| Validator | Schema file | What it checks |
+|---|---|---|
+| `validateGraphSchema` | `schema/event-graph.schema.json` | Tasks, settings, refreshStrategy, retry, circuit_breaker, inference hints |
+| `validateFlowSchema` | `schema/flow.schema.json` | Steps, transitions, retry, terminal states |
+| `validateLiveCardSchema` | `schema/live-cards.schema.json` | Cards, sources, elements, compute, data bindings |
+
+All validators are synchronous, pure functions. They return `{ ok: boolean, errors?: ErrorObject[] }`.
+
+---
+
 ## 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.
@@ -980,6 +1057,100 @@ const restored = restore(data);     // → LiveGraph (validates shape)
 | `getUnreachableNodes(live)` | Nodes that can never become eligible |
 | `snapshot(live)` | Serialize to a JSON-safe snapshot |
 | `restore(data)` | Restore a LiveGraph from a snapshot |
+| `applyEvents(live, events)` | Apply multiple events atomically (batch reduce) |
+
+### Reactive Graph (Push-based Execution)
+
+The reactive layer adds **self-sustaining execution** on top of the pure LiveGraph. Register handlers, push one event, and the graph drives itself to completion. No daemon, no polling — each handler callback triggers the next wave.
+
+```typescript
+import { createReactiveGraph, MemoryJournal } from 'yaml-flow/continuous-event-graph';
+
+// 1. Create with handlers
+const rg = createReactiveGraph(config, {
+  handlers: {
+    fetch:     async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
+    transform: async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
+    notify:    async ({ callbackToken }) => { /* ... */ return 'task-initiated'; },
+  },
+  onDrain: (events, live, schedule) => console.log(`${events.length} events, ${schedule.eligible.length} eligible`),
+});
+
+// 2. Push one event — the chain sustains itself
+rg.push({ type: 'inject-tokens', tokens: [], timestamp: new Date().toISOString() });
+// fetch runs -> completes -> transform becomes eligible -> runs -> notify -> done
+
+// 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. 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
+
+// 7. Cleanup
+rg.dispose();
+```
+
+**How it works internally:**
+
+```
+push(event)
+  -> applyEvent (pure state change)
+  -> schedule (what's eligible?)
+  -> dispatch handlers (fire-and-forget)
+  -> handler completes -> appends to journal
+  -> drain journal -> applyEvents (batch) -> schedule -> dispatch
+  -> repeat until nothing is eligible
+```
+
+The journal serializes concurrent callbacks — multiple handlers complete simultaneously, their events batch into a single `applyEvents()` call. No race conditions.
+
+**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:**
+
+| Method | Description |
+|---|---|
+| `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, TaskHandlerFn>` |
+| `journal` | `MemoryJournal` | Event log adapter (`MemoryJournal` or `FileJournal`) |
+| `onDrain` | — | Called after each drain cycle (observability) |
 
 ---
 
@@ -1234,15 +1405,25 @@ import { resolveVariables, resolveConfigTemplates } from 'yaml-flow/config';
 
 // Continuous Event Graph (long-lived evolving workflows)
 import {
-  createLiveGraph, applyEvent, addNode, removeNode,
+  createLiveGraph, applyEvent, applyEvents, addNode, removeNode,
   addRequires, removeRequires, addProvides, removeProvides,
   injectTokens, drainTokens, schedule, inspect,
   resetNode, disableNode, enableNode, getNode,
   snapshot, restore,
   getUnreachableTokens, getUnreachableNodes,
   getUpstream, getDownstream,
+  createReactiveGraph, MemoryJournal, FileJournal,
+} from 'yaml-flow/continuous-event-graph';
+import type {
+  ReactiveGraph, TaskHandler, TaskHandlerContext, TaskHandlerResult,
+  DispatchEntry, Journal,
 } from 'yaml-flow/continuous-event-graph';
 
+// JSON Schema Validators
+import { validateGraphSchema } from 'yaml-flow/event-graph';
+import { validateFlowSchema } from 'yaml-flow/step-machine';
+import { validateLiveCardSchema } from 'yaml-flow/card-compute';
+
 // LLM Inference (AI-assisted completion detection)
 import {
   buildInferencePrompt, inferCompletions, applyInferences, inferAndApply,
@@ -1321,6 +1502,11 @@ See the [examples/](./examples) directory:
 | [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 |
+| [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 |
 | [Data Pipeline](./examples/inference/data-pipeline.ts) | Inference | Iterative inference — evidence arrives in waves |
 | [Pluggable Adapters](./examples/inference/pluggable-adapters.ts) | Inference | OpenAI, Anthropic, Azure, CLI, HTTP adapter factories |

package/dist/{constants-BEbO2_OK.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, g as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-DAI_a2as.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';
 
 /**
@@ -15,7 +15,7 @@ import { e as StepFlowConfig } from './types-FZ_eyErS.js';
 declare function next(graph: GraphConfig, state: ExecutionState): SchedulerResult;
 /**
  * Get candidate tasks whose dependencies are all met.
- * Handles repeatable tasks and circuit breakers.
+ * Uses refreshStrategy to determine re-execution eligibility.
  * Pure function.
  */
 declare function getCandidateTasks(graph: GraphConfig, state: ExecutionState): string[];
@@ -54,17 +54,22 @@ 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 isRepeatableTask(taskConfig: TaskConfig): boolean;
-declare function getRepeatableMax(taskConfig: TaskConfig): number | undefined;
+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;
+declare function isRerunnable(taskConfig: TaskConfig, graphSettings?: {
+    refreshStrategy?: RefreshStrategy;
+}): boolean;
+declare function getMaxExecutions(taskConfig: TaskConfig): number | undefined;
 /**
  * Dynamically compute available outputs from all completed tasks.
- * For repeatable tasks, outputs are versioned by epoch.
+ * 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).
@@ -85,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.
  */
@@ -254,54 +259,29 @@ declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions)
 declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
 
 /**
- * Event Graph — Semantic Graph Validation
+ * schema-validator — Full JSON Schema validation for EventGraph configs.
  *
- * 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)
+ * Uses AJV to validate against the published event-graph.schema.json.
+ * For a lightweight sync check without AJV, use `validateGraphConfig()` instead.
  *
- * Pure function — config in, diagnostics out.
+ * @example
+ * ```typescript
+ * import { validateGraphSchema } from 'yaml-flow/event-graph';
+ *
+ * const result = validateGraphSchema(config);
+ * if (!result.ok) console.error(result.errors);
+ * ```
  */
-
-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[];
+interface SchemaValidationResult {
+    ok: boolean;
+    errors: string[];
 }
 /**
- * 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).
+ * Validate an event-graph config against the full event-graph.schema.json (draft-07).
  *
- * @param graph - The event-graph configuration to validate
- * @returns Validation result with categorized issues
+ * Requires `ajv` and `ajv-formats` to be installed.
  */
-declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+declare function validateGraphSchema(config: unknown): SchemaValidationResult;
 
 /**
  * Event Graph — Constants
@@ -319,4 +299,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-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 };
+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-BNjeIlZ8.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, g as StuckDetection, C as CompletionStrategy, a as ConflictStrategy, b as ExecutionMode, d as ExecutionStatus, m as TaskStatus } from './types-DAI_a2as.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';
 
 /**
@@ -15,7 +15,7 @@ import { e as StepFlowConfig } from './types-FZ_eyErS.cjs';
 declare function next(graph: GraphConfig, state: ExecutionState): SchedulerResult;
 /**
  * Get candidate tasks whose dependencies are all met.
- * Handles repeatable tasks and circuit breakers.
+ * Uses refreshStrategy to determine re-execution eligibility.
  * Pure function.
  */
 declare function getCandidateTasks(graph: GraphConfig, state: ExecutionState): string[];
@@ -54,17 +54,22 @@ 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 isRepeatableTask(taskConfig: TaskConfig): boolean;
-declare function getRepeatableMax(taskConfig: TaskConfig): number | undefined;
+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;
+declare function isRerunnable(taskConfig: TaskConfig, graphSettings?: {
+    refreshStrategy?: RefreshStrategy;
+}): boolean;
+declare function getMaxExecutions(taskConfig: TaskConfig): number | undefined;
 /**
  * Dynamically compute available outputs from all completed tasks.
- * For repeatable tasks, outputs are versioned by epoch.
+ * 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).
@@ -85,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.
  */
@@ -254,54 +259,29 @@ declare function exportGraphConfig(config: GraphConfig, options?: ExportOptions)
 declare function exportGraphConfigToFile(config: GraphConfig, filePath: string, options?: ExportOptions): Promise<void>;
 
 /**
- * Event Graph — Semantic Graph Validation
+ * schema-validator — Full JSON Schema validation for EventGraph configs.
  *
- * 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)
+ * Uses AJV to validate against the published event-graph.schema.json.
+ * For a lightweight sync check without AJV, use `validateGraphConfig()` instead.
  *
- * Pure function — config in, diagnostics out.
+ * @example
+ * ```typescript
+ * import { validateGraphSchema } from 'yaml-flow/event-graph';
+ *
+ * const result = validateGraphSchema(config);
+ * if (!result.ok) console.error(result.errors);
+ * ```
  */
-
-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[];
+interface SchemaValidationResult {
+    ok: boolean;
+    errors: string[];
 }
 /**
- * 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).
+ * Validate an event-graph config against the full event-graph.schema.json (draft-07).
  *
- * @param graph - The event-graph configuration to validate
- * @returns Validation result with categorized issues
+ * Requires `ajv` and `ajv-formats` to be installed.
  */
-declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+declare function validateGraphSchema(config: unknown): SchemaValidationResult;
 
 /**
  * Event Graph — Constants
@@ -319,4 +299,4 @@ declare const DEFAULTS: {
     readonly MAX_ITERATIONS: 1000;
 };
 
-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 };
+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 };