yaml-flow 1.0.0 → 2.0.0

package/README.md

@@ -1,379 +1,610 @@
 # yaml-flow
 
-A lightweight, isomorphic workflow engine with declarative YAML flows and pluggable persistence.
+Two workflow engines in one package. Pick the model that fits your problem.
 
 [![npm version](https://badge.fury.io/js/yaml-flow.svg)](https://www.npmjs.com/package/yaml-flow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+```
+npm install yaml-flow
+```
 
-- **Isomorphic** — Runs in both browser and Node.js
-- **Declarative Flows** — Define workflows in YAML with JSON Schema validation
-- **Pure Function Handlers** — Step handlers are simple `(input, context) => result` functions
-- **Pluggable Storage** — Bring your own persistence (memory, localStorage, file, Redis, etc.)
-- **Zero Core Dependencies** — Lightweight core, optional add-ons for YAML parsing
-- **Resumable** — Pause and resume flows from persisted state
-- **Circuit Breakers** — Prevent infinite loops with configurable limits
-- **Retry Logic** — Built-in exponential backoff for failed steps
-- **Event System** — Subscribe to flow events for UI updates
+## Which Mode Do I Need?
 
-## Installation
+yaml-flow ships two execution models. They solve fundamentally different problems.
 
-```bash
-npm install yaml-flow
-```
+| | **Step Machine** | **Event Graph** |
+|---|---|---|
+| **Mental model** | Flowchart — each step decides what runs next | Dependency graph — tasks self-select when their inputs are ready |
+| **Core function** | `applyStepResult(flow, state, step, result) → newState` | `next(graph, state) → eligibleTasks` + `apply(state, event, graph) → newState` |
+| **Config shape** | `steps:` with `transitions:` mapping | `tasks:` with `requires:` / `provides:` arrays |
+| **Who decides next?** | The sender (current step's result picks the transition) | The receivers (tasks become eligible when their required tokens appear) |
+| **Has a driver?** | Yes — `StepMachine` class runs the loop for you | No — you call `next()` and `apply()` yourself (or write a 10-line loop) |
+| **Import** | `import { StepMachine } from 'yaml-flow/step-machine'` | `import { next, apply } from 'yaml-flow/event-graph'` |
+
+### Use Step Machine when…
+
+- Your workflow is a **known sequence** of steps with conditional branching.
+- You need **pause/resume** built in.
+- The work is conversational: receive input → process → decide next step → repeat.
+- You want to hand the library a YAML file and some handler functions and call `.run()`.
+
+**Examples:** form wizards, approval chains, AI chat loops, order processing pipelines, ETL with linear stages.
+
+### Use Event Graph when…
 
-## Quick Start
+- Tasks have **complex dependencies** — diamonds, fan-out, fan-in, optional paths.
+- You don't know the execution order up front; it **emerges from the data**.
+- Multiple tasks can run **in parallel** once their inputs are satisfied.
+- You need **conflict resolution** when two tasks compete to produce the same output.
+- Your system is **event-driven**: external events inject tokens that unblock downstream tasks.
+- You want the engine to be a **pure function** you embed in your own scheduler, serverless function, or agent loop.
 
-### 1. Define Your Flow (YAML)
+**Examples:** CI/CD pipelines, agent tool orchestration, research workflows (fetch → analyse A | analyse B → merge), build systems, multi-model AI routing, eligibility engines.
+
+### When in doubt
+
+Start with **Step Machine** if your workflow diagram is a straight line with branches.  
+Start with **Event Graph** if your workflow diagram has diamonds or parallel lanes.
+
+Both are pure `f(state, input) → newState` at their core. You can always call the reducer directly without the driver class.
+
+---
+
+## Step Machine — Quick Start
+
+### 1. Define a flow
 
 ```yaml
-# my-flow.yaml
+# support-ticket.yaml
 settings:
-  start_step: greet
-  max_total_steps: 10
+  start_step: classify
+  max_total_steps: 20
 
 steps:
-  greet:
-    produces_data:
-      - message
+  classify:
+    produces_data: [category, priority]
+    transitions:
+      billing: handle_billing
+      technical: handle_technical
+      general: handle_general
+
+  handle_billing:
+    expects_data: [category]
+    produces_data: [resolution]
+    transitions:
+      resolved: close_ticket
+      escalate: escalate_ticket
+
+  handle_technical:
+    expects_data: [category]
+    produces_data: [resolution]
     transitions:
-      success: done
-      failure: error
+      resolved: close_ticket
+      escalate: escalate_ticket
+    retry:
+      max_attempts: 2
+      delay_ms: 1000
+
+  handle_general:
+    expects_data: [category]
+    produces_data: [resolution]
+    transitions:
+      resolved: close_ticket
+
+  escalate_ticket:
+    expects_data: [category, priority]
+    produces_data: [escalation_id]
+    transitions:
+      done: close_ticket
 
 terminal_states:
-  done:
-    return_intent: success
-    return_artifacts: message
-  
-  error:
-    return_intent: error
-    return_artifacts: false
+  close_ticket:
+    return_intent: resolved
+    return_artifacts: [resolution]
 ```
 
-### 2. Create Step Handlers
+### 2. Write handlers and run
 
 ```typescript
-import { createEngine, loadFlow, MemoryStore } from 'yaml-flow';
+import { createStepMachine, loadStepFlow } from 'yaml-flow/step-machine';
+import { MemoryStore } from 'yaml-flow/stores/memory';
+
+const flow = await loadStepFlow('./support-ticket.yaml');
 
 const handlers = {
-  greet: async (input, ctx) => {
-    return {
-      result: 'success',
-      data: { message: `Hello, ${input.name}!` }
-    };
-  }
+  classify: async (input) => {
+    const category = detectCategory(input.message);
+    return { result: category, data: { category, priority: 'high' } };
+  },
+  handle_billing: async (input, ctx) => {
+    const answer = await ctx.components.ai.ask(`Billing issue: ${input.category}`);
+    return { result: 'resolved', data: { resolution: answer } };
+  },
+  handle_technical: async (input, ctx) => {
+    const answer = await ctx.components.ai.ask(`Tech issue: ${input.category}`);
+    return answer.confidence > 0.7
+      ? { result: 'resolved', data: { resolution: answer.text } }
+      : { result: 'escalate' };
+  },
+  handle_general: async (input) => {
+    return { result: 'resolved', data: { resolution: 'See FAQ.' } };
+  },
+  escalate_ticket: async (input, ctx) => {
+    const id = await ctx.components.ticketSystem.escalate(input.category);
+    return { result: 'done', data: { escalation_id: id } };
+  },
 };
+
+const machine = createStepMachine(flow, handlers, {
+  store: new MemoryStore(),
+  components: { ai: myAIClient, ticketSystem: myTicketAPI },
+});
+
+const result = await machine.run({ message: 'I was double-charged' });
+// result.intent  → 'resolved'
+// result.data    → { resolution: '...' }
+// result.stepHistory → ['classify', 'handle_billing']
 ```
 
-### 3. Run the Flow
+### Step Machine features at a glance
+
+| Feature | Config |
+|---|---|
+| Transitions | `transitions: { success: next_step, failure: error_step }` |
+| Retry | `retry: { max_attempts: 3, delay_ms: 1000, backoff_multiplier: 2 }` |
+| Circuit breaker | `circuit_breaker: { max_iterations: 5, on_open: fallback }` |
+| Pause / resume | `await machine.pause(runId)` / `await machine.resume(runId)` |
+| Cancellation | Pass `signal: AbortController.signal` in options |
+| Events | `machine.on('step:complete', fn)` — also `flow:start`, `flow:complete`, `transition`, etc. |
+| Data flow | `expects_data` filters what a handler receives; `produces_data` documents what it returns |
+
+### Using the pure reducer directly (no driver)
 
 ```typescript
-const flow = await loadFlow('./my-flow.yaml');
-const engine = createEngine(flow, handlers);
+import { createInitialState, applyStepResult, checkCircuitBreaker, computeStepInput } from 'yaml-flow/step-machine';
+
+let state = createInitialState(flow, 'run-1');
 
-const result = await engine.run({ name: 'World' });
-console.log(result.data.message); // "Hello, World!"
+// Your own loop
+while (true) {
+  const cb = checkCircuitBreaker(flow, state, state.currentStep);
+  if (cb.broken) { state = cb.newState; continue; }
+  state = cb.newState;
+
+  const input = computeStepInput(flow, state.currentStep, allData);
+  const stepResult = await handlers[state.currentStep](input, context);
+  const { newState, isTerminal } = applyStepResult(flow, state, state.currentStep, stepResult);
+  state = newState;
+  if (isTerminal) break;
+}
 ```
 
-## Flow Configuration
+---
 
-### Settings
+## Event Graph — Quick Start
+
+The event graph has no driver class. You call two pure functions in a loop:
+
+- **`next(graph, state)`** → tells you which tasks are eligible right now
+- **`apply(state, event, graph)`** → applies an event and returns the new state
+
+You decide how to actually execute the tasks (call an API, run a function, ask an LLM, etc.).
+
+### 1. Define a graph
 
 ```yaml
+# research-pipeline.yaml
 settings:
-  start_step: my_step      # Required: First step to execute
-  max_total_steps: 100     # Optional: Circuit breaker (default: 100)
-  timeout_ms: 60000        # Optional: Flow timeout in ms
-```
+  completion: goal-reached
+  goal: [final-report]
+  conflict_strategy: parallel-all
 
-### Steps
+tasks:
+  fetch_sources:
+    provides: [raw-sources]
 
-```yaml
-steps:
-  my_step:
-    description: "What this step does"
-    expects_data:          # Input data keys
-      - input_key
-    produces_data:         # Output data keys
-      - output_key
-    transitions:           # Result -> next step mapping
-      success: next_step
-      failure: error_step
-    retry:                 # Optional retry config
-      max_attempts: 3
-      delay_ms: 1000
-      backoff_multiplier: 2
-    circuit_breaker:       # Optional loop protection
-      max_iterations: 5
-      on_open: fallback_step
-```
+  analyse_sentiment:
+    requires: [raw-sources]
+    provides: [sentiment-result]
 
-### Terminal States
+  analyse_entities:
+    requires: [raw-sources]
+    provides: [entity-result]
 
-```yaml
-terminal_states:
-  success:
-    return_intent: "success"
-    return_artifacts:
-      - result_data
-      - metadata
-  
-  error:
-    return_intent: "error"
-    return_artifacts: false
+  merge_analysis:
+    requires: [sentiment-result, entity-result]
+    provides: [merged-analysis]
+
+  generate_report:
+    requires: [merged-analysis]
+    provides: [final-report]
 ```
 
-## Step Handlers
+`fetch_sources` runs first (no requires). Once it completes, both `analyse_sentiment` and `analyse_entities` become eligible in parallel. `merge_analysis` waits for both. `generate_report` waits for the merge. Done when `final-report` appears.
 
-Step handlers are pure async functions:
+### 2. Write a driver loop
 
 ```typescript
-type StepHandler = (input: StepInput, context: StepContext) => Promise<StepResult>;
-
-interface StepInput {
-  [key: string]: unknown;  // Data from expects_data
-}
+import { next, apply, createInitialExecutionState } from 'yaml-flow/event-graph';
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
 
-interface StepContext {
-  runId: string;           // Current run ID
-  stepName: string;        // Current step name
-  components: object;      // Injected dependencies
-  store: FlowStore;        // Direct store access
-  signal?: AbortSignal;    // Cancellation signal
-  emit: (event, data) => void;  // Event emitter
-}
+const graph = parse(readFileSync('./research-pipeline.yaml', 'utf8'));
+let state = createInitialExecutionState(graph, 'exec-1');
 
-interface StepResult {
-  result: string;          // Transition key (e.g., 'success', 'failure')
-  data?: object;           // Output data (matches produces_data)
-}
-```
+while (true) {
+  const schedule = next(graph, state);
 
-### Example Handler
+  if (schedule.isComplete) {
+    console.log('Done!', state.availableOutputs);
+    break;
+  }
+  if (schedule.stuckDetection.is_stuck) {
+    console.error('Stuck:', schedule.stuckDetection.stuck_description);
+    break;
+  }
 
-```typescript
-const handlers = {
-  async processOrder(input, ctx) {
-    const { order } = input;
-    
-    // Access injected database client
-    const db = ctx.components.db;
-    
-    try {
-      const savedOrder = await db.orders.save(order);
-      
-      return {
-        result: 'success',
-        data: { 
-          order_id: savedOrder.id,
-          status: 'pending'
-        }
-      };
-    } catch (error) {
-      return {
-        result: 'failure',
-        data: { error: error.message }
-      };
+  // Execute all eligible tasks (in parallel)
+  const results = await Promise.all(
+    schedule.eligibleTasks.map(async (taskName) => {
+      state = apply(state, { type: 'task-started', taskName, timestamp: new Date().toISOString() }, graph);
+
+      try {
+        const output = await executeTask(taskName, state);
+        return { taskName, success: true, result: output };
+      } catch (err) {
+        return { taskName, success: false, error: err.message };
+      }
+    })
+  );
+
+  // Feed results back into the reducer
+  for (const r of results) {
+    if (r.success) {
+      state = apply(state, { type: 'task-completed', taskName: r.taskName, result: r.result, timestamp: new Date().toISOString() }, graph);
+    } else {
+      state = apply(state, { type: 'task-failed', taskName: r.taskName, error: r.error, timestamp: new Date().toISOString() }, graph);
     }
   }
-};
+}
 ```
 
-## Storage Adapters
+That's the entire integration. ~30 lines. The engine is pure; your loop owns the I/O.
 
-### Memory (Default)
+### Event Graph features at a glance
 
-```typescript
-import { MemoryStore } from 'yaml-flow';
+| Feature | Config | What it does |
+|---|---|---|
+| Dependencies | `requires: [a, b]` / `provides: [c]` | Task runs when all required tokens are available |
+| 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 |
+| 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 |
+| Completion strategies | `completion: all-tasks-done \| all-outputs-done \| goal-reached \| manual` | When is the graph "done"? |
+| Conflict resolution | `conflict_strategy: alphabetical \| priority-first \| parallel-all \| ...` | What happens when two tasks produce the same output? |
+| Stuck detection | Automatic via `next()` | Returns `is_stuck: true` with description when no progress is possible |
 
-const engine = createEngine(flow, handlers, {
-  store: new MemoryStore()
-});
-```
+### Completion strategies explained
 
-### LocalStorage (Browser)
+| Strategy | Meaning |
+|---|---|
+| `all-tasks-done` | Every task has completed (or failed/inactivated) |
+| `all-outputs-done` | Every `provides` token from every task is available |
+| `goal-reached` | Specific tokens listed in `settings.goal` are available |
+| `only-resolved` | All non-failed tasks have completed |
+| `manual` | Never auto-completes; you decide when to stop |
 
-```typescript
-import { LocalStorageStore } from 'yaml-flow/stores/localStorage';
+### Conflict resolution strategies
 
-const engine = createEngine(flow, handlers, {
-  store: new LocalStorageStore({ prefix: 'myapp' })
-});
-```
+When multiple eligible tasks produce the same output token, only one should run (unless you want parallel-all). The `conflict_strategy` setting controls the selection:
 
-### File System (Node.js)
+| Strategy | Behaviour |
+|---|---|
+| `alphabetical` | Pick the alphabetically first task name (default, deterministic) |
+| `priority-first` | Pick the task with the highest `priority` value |
+| `duration-first` | Pick the task with the lowest `estimatedDuration` |
+| `cost-optimized` | Pick the task with the lowest `estimatedCost` |
+| `resource-aware` | Pick the task with the lowest total resource requirements |
+| `round-robin` | Rotate among competing tasks across scheduler calls |
+| `random-select` | Pick one at random |
+| `parallel-all` | Run all competing tasks (no conflict resolution) |
+| `user-choice` | Return all candidates; let the caller decide |
+| `skip-conflicts` | Skip all tasks involved in a conflict |
 
-```typescript
-import { FileStore } from 'yaml-flow/stores/file';
+---
 
-const engine = createEngine(flow, handlers, {
-  store: new FileStore({ directory: './flow-data' })
-});
-```
+## Practical Patterns
 
-### Custom Store
+### Pattern: AI Agent Tool Orchestration (Event Graph)
 
-Implement the `FlowStore` interface:
+An agent needs to gather evidence from multiple sources, then synthesize.
 
-```typescript
-interface FlowStore {
-  saveRunState(runId: string, state: RunState): Promise<void>;
-  loadRunState(runId: string): Promise<RunState | null>;
-  deleteRunState(runId: string): Promise<void>;
-  setData(runId: string, key: string, value: unknown): Promise<void>;
-  getData(runId: string, key: string): Promise<unknown>;
-  getAllData(runId: string): Promise<Record<string, unknown>>;
-  clearData(runId: string): Promise<void>;
-}
+```yaml
+settings:
+  completion: goal-reached
+  goal: [final-answer]
+  conflict_strategy: parallel-all
+
+tasks:
+  search_web:
+    provides: [web-results]
+  search_database:
+    provides: [db-results]
+  search_documents:
+    provides: [doc-results]
+
+  synthesize:
+    requires: [web-results, db-results, doc-results]
+    provides: [draft-answer]
+
+  verify:
+    requires: [draft-answer]
+    provides: [final-answer]
+    on:
+      verified: [final-answer]
+      rejected: [needs-revision]
+    on_failure: [verification-skipped]
+
+  revise:
+    requires: [needs-revision]
+    provides: [draft-answer]
+    repeatable: { max: 3 }
 ```
 
-## Component Injection
+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.
 
-Inject external dependencies (databases, API clients, etc.):
+### Pattern: Order Processing Pipeline (Step Machine)
 
-```typescript
-const engine = createEngine(flow, handlers, {
-  components: {
-    db: databaseClient,
-    api: httpClient,
-    cache: redisClient,
-    ai: openAIClient
-  }
-});
+```yaml
+settings:
+  start_step: validate
+  max_total_steps: 15
 
-// Access in handlers
-const handlers = {
-  async fetchData(input, ctx) {
-    const result = await ctx.components.api.get('/data');
-    return { result: 'success', data: { fetched: result } };
-  }
-};
-```
+steps:
+  validate:
+    produces_data: [validated_order]
+    transitions:
+      valid: charge_payment
+      invalid: reject
 
-## Events
+  charge_payment:
+    expects_data: [validated_order]
+    produces_data: [payment_id]
+    transitions:
+      success: ship
+      declined: reject
+    retry:
+      max_attempts: 3
+      delay_ms: 2000
+      backoff_multiplier: 2
 
-Subscribe to flow events:
+  ship:
+    expects_data: [validated_order, payment_id]
+    produces_data: [tracking_number]
+    transitions:
+      shipped: confirm
+      failure: refund
 
-```typescript
-const engine = createEngine(flow, handlers);
+  refund:
+    expects_data: [payment_id]
+    produces_data: [refund_id]
+    transitions:
+      done: reject
 
-// Subscribe to events
-const unsubscribe = engine.on('step:complete', (event) => {
-  console.log(`Step ${event.data.step} completed with ${event.data.result}`);
-});
+  confirm:
+    expects_data: [tracking_number]
+    transitions:
+      done: complete
 
-// Available events:
-// - flow:start, flow:complete, flow:error, flow:paused, flow:resumed
-// - step:start, step:complete, step:error
-// - transition
+terminal_states:
+  complete:
+    return_intent: success
+    return_artifacts: [tracking_number, payment_id]
+  reject:
+    return_intent: rejected
+    return_artifacts: false
 ```
 
-## Pause & Resume
+Linear with branches. The current step decides what's next. Retry on payment failures with exponential backoff.
+
+### Pattern: Inject External Events (Event Graph)
 
 ```typescript
-// Start flow
-const result = engine.run({ data: 'value' });
+// A task is waiting for human approval
+const graph = {
+  settings: { completion: 'goal-reached', goal: ['deployed'] },
+  tasks: {
+    build:    { provides: ['build-artifact'] },
+    test:     { requires: ['build-artifact'], provides: ['test-passed'] },
+    approve:  { requires: ['test-passed', 'human-approval'], provides: ['approved'] },
+    deploy:   { requires: ['approved'], provides: ['deployed'] },
+  },
+};
+
+let state = createInitialExecutionState(graph, 'deploy-1');
+
+// ... run build and test normally ...
 
-// Pause (from another context)
-await engine.pause(runId);
+// Later, when a human clicks "Approve" in your UI:
+state = apply(state, {
+  type: 'inject-tokens',
+  tokens: ['human-approval'],
+  timestamp: new Date().toISOString(),
+}, graph);
 
-// Later: resume
-const resumed = await engine.resume(runId);
+// Now next(graph, state) will return 'approve' as eligible
 ```
 
-## Cancellation
+### Pattern: Conditional Branching in Event Graph
 
-```typescript
-const controller = new AbortController();
+```yaml
+tasks:
+  classify_image:
+    provides: [classification]
+    on:
+      photo: [is-photo]
+      document: [is-document]
+      screenshot: [is-screenshot]
+
+  enhance_photo:
+    requires: [is-photo]
+    provides: [processed-image]
+
+  ocr_document:
+    requires: [is-document]
+    provides: [extracted-text]
+
+  crop_screenshot:
+    requires: [is-screenshot]
+    provides: [processed-image]
+```
 
-const engine = createEngine(flow, handlers, {
-  signal: controller.signal
-});
+Only one downstream path activates based on the classifier result. This is the event-graph equivalent of a switch statement.
 
-// Start flow
-const resultPromise = engine.run();
+---
 
-// Cancel
-controller.abort();
-```
+## Storage Adapters
 
-## Browser Usage
+All three stores work with both modes. Step Machine uses them for run state persistence. Event Graph state is plain JSON — serialize it yourself or use a store.
 
-### With Bundler (Vite, webpack, etc.)
+### Memory (default, all environments)
 
 ```typescript
-import { createEngine, MemoryStore } from 'yaml-flow';
+import { MemoryStore } from 'yaml-flow/stores/memory';
+```
 
-// Flow as JSON (pre-parsed at build time)
-const flow = {
-  settings: { start_step: 'start' },
-  steps: { start: { transitions: { success: 'done' } } },
-  terminal_states: { done: { return_intent: 'success' } }
-};
+### LocalStorage (browser)
 
-const engine = createEngine(flow, handlers);
+```typescript
+import { LocalStorageStore } from 'yaml-flow/stores/localStorage';
+new LocalStorageStore({ prefix: 'myapp' });
 ```
 
-### From URL
+### File System (Node.js)
 
 ```typescript
-import { loadFlowFromUrl, createEngine } from 'yaml-flow';
-
-const flow = await loadFlowFromUrl('/flows/my-flow.json');
-const engine = createEngine(flow, handlers);
+import { FileStore } from 'yaml-flow/stores/file';
+new FileStore({ directory: './flow-data' });
 ```
 
-## JSON Schema
-
-Use the included JSON Schema for IDE autocomplete:
+### Custom Store
 
-```yaml
-# yaml-language-server: $schema=node_modules/yaml-flow/schema/flow.schema.json
+Implement the `StepMachineStore` interface:
 
-settings:
-  start_step: my_step
-  # ... IDE autocomplete works here
+```typescript
+interface StepMachineStore {
+  saveRunState(runId: string, state: StepMachineState): Promise<void>;
+  loadRunState(runId: string): Promise<StepMachineState | null>;
+  deleteRunState(runId: string): Promise<void>;
+  setData(runId: string, key: string, value: unknown): Promise<void>;
+  getData(runId: string, key: string): Promise<unknown>;
+  getAllData(runId: string): Promise<Record<string, unknown>>;
+  clearData(runId: string): Promise<void>;
+}
 ```
 
-## API Reference
+---
 
-### `createEngine(flow, handlers, options?)`
+## Package Exports
 
-Create a new flow engine instance.
+```typescript
+// Everything (both modes + stores)
+import { StepMachine, next, apply, MemoryStore } from 'yaml-flow';
 
-### `loadFlow(source)`
+// Step Machine only
+import { StepMachine, createStepMachine, loadStepFlow } from 'yaml-flow/step-machine';
+import { applyStepResult, checkCircuitBreaker, createInitialState } from 'yaml-flow/step-machine';
 
-Load and validate a flow from file path, URL, or object.
+// Event Graph only
+import { next, apply, applyAll, getCandidateTasks } from 'yaml-flow/event-graph';
+import { createInitialExecutionState, isExecutionComplete, detectStuckState } from 'yaml-flow/event-graph';
+import { TASK_STATUS, COMPLETION_STRATEGIES, CONFLICT_STRATEGIES } from 'yaml-flow/event-graph';
 
-### `FlowEngine.run(initialData?)`
+// Stores
+import { MemoryStore, LocalStorageStore, FileStore } from 'yaml-flow/stores';
 
-Execute the flow from start.
+// Backward compatibility (v1 names → v2)
+import { FlowEngine, createEngine } from 'yaml-flow';  // aliases for StepMachine, createStepMachine
+```
 
-### `FlowEngine.resume(runId)`
+---
 
-Resume a paused flow.
+## API Reference
 
-### `FlowEngine.pause(runId)`
+### Step Machine
+
+| Export | Description |
+|---|---|
+| `createStepMachine(flow, handlers, options?)` | Create and validate a StepMachine instance |
+| `StepMachine.run(initialData?)` | Execute flow from start, returns `StepMachineResult` |
+| `StepMachine.pause(runId)` | Pause a running flow |
+| `StepMachine.resume(runId)` | Resume a paused flow |
+| `StepMachine.on(event, listener)` | Subscribe to events (`step:start`, `step:complete`, `flow:complete`, `transition`, etc.) |
+| `loadStepFlow(path)` | Load + validate a YAML/JSON flow file |
+| `applyStepResult(flow, state, step, result)` | Pure reducer: apply a step result to state |
+| `checkCircuitBreaker(flow, state, step)` | Pure: check/increment circuit breaker |
+| `computeStepInput(flow, step, allData)` | Pure: filter data to what a step expects |
+| `createInitialState(flow, runId)` | Pure: create starting state |
+
+### Event Graph
+
+| Export | Description |
+|---|---|
+| `next(graph, state)` | Pure scheduler: returns `{ eligibleTasks, isComplete, stuckDetection, conflicts }` |
+| `apply(state, event, graph)` | Pure reducer: apply one event, returns new state |
+| `applyAll(state, events, graph)` | Apply multiple events sequentially |
+| `createInitialExecutionState(graph, executionId)` | Create starting state for a graph |
+| `getCandidateTasks(graph, state)` | Low-level: just the eligible task list |
+| `isExecutionComplete(graph, state)` | Check completion against configured strategy |
+| `detectStuckState({graph, state, ...})` | Check if execution is stuck |
+| `addDynamicTask(graph, name, config)` | Immutably add a task to a graph config |
+
+### Event Types (for `apply()`)
+
+| Event | Fields | Effect |
+|---|---|---|
+| `task-started` | `taskName` | Sets task status to `running` |
+| `task-completed` | `taskName`, `result?` | Marks completed, adds `provides` tokens (or `on[result]` tokens) |
+| `task-failed` | `taskName`, `error` | Retries or marks failed, injects `on_failure` tokens |
+| `task-progress` | `taskName`, `message?`, `progress?` | Updates progress/messages |
+| `inject-tokens` | `tokens[]` | Adds tokens to available outputs (unblocks waiting tasks) |
+| `agent-action` | `action: start\|stop\|pause\|resume` | Controls execution lifecycle |
+| `task-creation` | `taskName`, `taskConfig` | Adds a new task to execution state |
+
+---
 
-Pause a running flow.
+## Examples
 
-### `FlowEngine.on(event, listener)`
+See the [examples/](./examples) directory:
 
-Subscribe to flow events.
+| Example | Mode | Demonstrates |
+|---|---|---|
+| [Simple Greeting](./examples/node/simple-greeting.ts) | Step Machine | Basic flow with file store |
+| [AI Conversation](./examples/node/ai-conversation.ts) | Step Machine | Retry, circuit breakers, component injection |
+| [Research Pipeline](./examples/event-graph/research-pipeline.ts) | Event Graph | Parallel tasks, goal-based completion |
+| [CI/CD Pipeline](./examples/event-graph/ci-cd-pipeline.ts) | Event Graph | External events, conditional routing, failure tokens |
+| [Order Processing](./examples/flows/order-processing.yaml) | Step Machine | YAML flow definition |
+| [Browser Demo](./examples/browser/index.html) | Step Machine | In-browser usage |
 
-### `FlowEngine.getStore()`
+---
 
-Get the store instance.
+## Migrating from v1
 
-## Examples
+v2 is backward compatible. The old names still work:
+
+```typescript
+// v1 (still works)
+import { FlowEngine, createEngine } from 'yaml-flow';
 
-See the [examples](./examples) directory:
+// v2 (preferred)
+import { StepMachine, createStepMachine } from 'yaml-flow/step-machine';
+```
 
-- [Simple Greeting (Node.js)](./examples/node/simple-greeting.ts)
-- [AI Conversation (Node.js)](./examples/node/ai-conversation.ts)
-- [Browser Demo](./examples/browser/index.html)
-- [Order Processing (Flow)](./examples/flows/order-processing.yaml)
+The `FlowStore` interface is now `StepMachineStore` (same shape). `RunState` is now `StepMachineState` (same shape). Both old names resolve to the new types.
 
 ## License