yaml-flow 3.0.0 → 3.1.1

package/dist/continuous-event-graph/index.d.ts

@@ -1,7 +1,8 @@
-import { L as LiveGraph, N as NodeInfo, b as LiveGraphSnapshot, S as ScheduleResult, D as DownstreamResult, U as UnreachableNodesResult, c as UnreachableTokensResult, e as UpstreamResult, a as LiveGraphHealth } from '../types-BuEo3wVG.js';
-export { B as BlockedTask, P as PendingTask, d as UnresolvedDependency } from '../types-BuEo3wVG.js';
-import { T as TaskConfig, e as GraphEvent, G as GraphConfig } from '../types-BpWrH1sf.js';
-export { c as ExecutionState, f as GraphSettings, l as TaskState } from '../types-BpWrH1sf.js';
+import { L as LiveGraph, N as NodeInfo, b as LiveGraphSnapshot, S as ScheduleResult, D as DownstreamResult, U as UnreachableNodesResult, c as UnreachableTokensResult, e as UpstreamResult, a as LiveGraphHealth } from '../types-ClRA8hzC.js';
+export { B as BlockedTask, P as PendingTask, d as UnresolvedDependency } from '../types-ClRA8hzC.js';
+import { T as TaskConfig, f as GraphEvent, G as GraphConfig, e as GraphEngineStore } from '../types-DEj7OakX.js';
+export { c as ExecutionState, g as GraphSettings } from '../types-DEj7OakX.js';
+import { a as GraphValidationResult } from '../validate-DEZ2Ymdb.js';
 
 /**
  * Continuous Event Graph — Core
@@ -233,66 +234,584 @@ declare class FileJournal implements Journal {
  * without touching the core engine types.
  */
 
-/** Context passed to task handlers. */
-interface TaskHandlerContext {
-    /** Name of the task being executed */
-    taskName: string;
-    /** Current snapshot of the live graph (read-only — do not mutate) */
-    live: Readonly<LiveGraph>;
-    /** The task's own config */
-    config: TaskConfig;
-}
-/** A task handler function. Return value becomes the event's `data` payload. */
-type TaskHandler = (ctx: TaskHandlerContext) => Promise<TaskHandlerResult>;
-interface TaskHandlerResult {
-    /** Optional result key for conditional routing (task's `on` map) */
-    result?: string;
-    /** Optional data payload */
-    data?: Record<string, unknown>;
-    /** Optional content hash for data-changed strategy */
-    dataHash?: string;
-}
-/** Internal dispatch tracking — NOT exposed to the core engine. */
-interface DispatchEntry {
-    status: 'initiated' | 'dispatch-failed' | 'timed-out' | 'retry-queued' | 'abandoned';
-    dispatchedAt: number;
-    dispatchAttempts: number;
-    lastError?: string;
+/**
+ * Deterministic hash of a data payload.
+ * Recursively-sorted JSON → SHA-256 hex (first 16 chars for compactness).
+ * Used to auto-compute dataHash when the handler doesn't provide one.
+ * Exported so handler authors can pre-compute or test hashes.
+ */
+declare function computeDataHash(data: Record<string, unknown>): string;
+/**
+ * Input passed to a task handler function.
+ *
+ * The reactive layer resolves upstream data from `requires` into `state`,
+ * and provides this task's own engine store as `taskState`.
+ * Handlers push output data back via `graph.resolveCallback(callbackToken, data)`.
+ */
+interface TaskHandlerInput {
+    /** This task's node ID (task name) */
+    nodeId: string;
+    /**
+     * Upstream dependency data, keyed by require token name.
+     * Only tokens from this task's `requires` are present.
+     * Value is the producing task's `data` field (or undefined if not yet available).
+     */
+    state: Readonly<Record<string, Record<string, unknown> | undefined>>;
+    /**
+     * This task's own GraphEngineStore — includes status, data, executionCount, etc.
+     */
+    taskState: Readonly<GraphEngineStore>;
+    /** This task's config */
+    config: Readonly<TaskConfig>;
+    /**
+     * Opaque callback token encoding this task's identity.
+     * Pass this to `graph.resolveCallback(callbackToken, data)` to complete the task.
+     * Can be serialized and sent to external systems (webhooks, other scripts,
+     * message queues) — any process with this token can push data back.
+     */
+    callbackToken: string;
 }
+/**
+ * Handler return value — initiation status only.
+ * - `'task-initiated'` — async work started successfully; data will arrive via resolveCallback
+ * - `'task-initiate-failure'` — failed to start (bad config, connection refused, etc.)
+ */
+type TaskHandlerReturn = 'task-initiated' | 'task-initiate-failure';
+/**
+ * A named task handler function.
+ * Registered in the handler registry, referenced by name in `taskConfig.taskHandlers`.
+ *
+ * The handler's job is to **initiate** async work, not await it.
+ *
+ * Flow:
+ *   1. Handler receives `callbackToken` + upstream `state`
+ *   2. Handler kicks off background work (internal, external script, webhook, etc.)
+ *      — passes `callbackToken` to the background work
+ *   3. Handler returns `'task-initiated'` immediately
+ *   4. Background work runs independently — when done, it calls
+ *      `graph.resolveCallback(callbackToken, data)` for success, or
+ *      `graph.resolveCallback(callbackToken, {}, ['error msg'])` for failure
+ *   5. resolveCallback completes the task → data-changed cascade fires
+ *
+ * The callbackToken is opaque — pass it to the background work so it can
+ * call back. Works across processes, scripts, webhooks, message queues.
+ *
+ * @example
+ * ```ts
+ * const fetchYahoo: TaskHandlerFn = async ({ state, callbackToken }) => {
+ *   const symbols = state['portfolio-form']?.holdings?.map(h => h.symbol) ?? [];
+ *   // Kick off background work — do NOT await
+ *   fetch(`https://api.yahoo.com/prices?s=${symbols.join(',')}`)
+ *     .then(res => res.json())
+ *     .then(prices => graph.resolveCallback(callbackToken, { prices }))
+ *     .catch(err => graph.resolveCallback(callbackToken, {}, [err.message]));
+ *   // Return immediately — background work will resolveCallback when done
+ *   return 'task-initiated';
+ * };
+ * ```
+ */
+type TaskHandlerFn = (input: TaskHandlerInput) => Promise<TaskHandlerReturn>;
 interface ReactiveGraphOptions {
-    /** Task handlers keyed by task name */
-    handlers: Record<string, TaskHandler>;
-    /** Max times to retry dispatching a handler that fails to invoke (default: 3) */
-    maxDispatchRetries?: number;
-    /** Default timeout in ms for handler callbacks (default: 30000). 0 = no timeout. */
-    defaultTimeoutMs?: number;
+    /** Named handler registry — handler name → handler function */
+    handlers: Record<string, TaskHandlerFn>;
     /** Journal adapter (default: MemoryJournal) */
     journal?: Journal;
-    /** Called when a handler fails to dispatch */
-    onDispatchFailed?: (taskName: string, error: Error, attempt: number) => void;
-    /** Called when a task is abandoned after max dispatch retries */
-    onAbandoned?: (taskName: string) => void;
     /** Called after each drain cycle — for observability */
     onDrain?: (events: GraphEvent[], live: LiveGraph, scheduleResult: ScheduleResult) => void;
 }
 interface ReactiveGraph {
-    /** Push an event into the graph. Triggers drain → schedule → dispatch cascade. */
+    /** Push an event into the graph via journal. Triggers drain → schedule → dispatch. */
     push(event: GraphEvent): void;
-    /** Push multiple events. Single drain cycle after all are journaled. */
+    /** Push multiple events via journal. Single drain cycle after all are journaled. */
     pushAll(events: GraphEvent[]): void;
-    /** Add a node with its handler. Triggers re-evaluation. */
-    addNode(name: string, taskConfig: TaskConfig, handler: TaskHandler): void;
-    /** Remove a node and its handler. */
+    /**
+     * Resolve a callback token — complete (or fail) a task after initiation.
+     * Journals task-completed or task-failed, then drains.
+     * Gracefully ignores invalid tokens or tokens for tasks no longer in the graph.
+     */
+    resolveCallback(callbackToken: string, data: Record<string, unknown>, errors?: string[]): void;
+    /** Add a node to the graph config. Journals nothing — structural mutation. */
+    addNode(name: string, taskConfig: TaskConfig): void;
+    /** Remove a node from the graph config. Structural mutation. */
     removeNode(name: string): void;
+    /** Add required tokens to an existing node. Structural mutation + drain. */
+    addRequires(nodeName: string, tokens: string[]): void;
+    /** Remove required tokens from an existing node. Structural mutation + drain. */
+    removeRequires(nodeName: string, tokens: string[]): void;
+    /** Add provided tokens to an existing node. Structural mutation + drain. */
+    addProvides(nodeName: string, tokens: string[]): void;
+    /** Remove provided tokens from an existing node. Structural mutation. */
+    removeProvides(nodeName: string, tokens: string[]): void;
+    /** Register a named handler in the registry. */
+    registerHandler(name: string, fn: TaskHandlerFn): void;
+    /** Unregister a named handler from the registry. */
+    unregisterHandler(name: string): void;
+    /**
+     * Re-trigger a task: journals a task-restart event, then drains.
+     * data-changed cascade handles downstream automatically.
+     */
+    retrigger(taskName: string): void;
+    /** Re-trigger multiple tasks via journal. */
+    retriggerAll(taskNames: string[]): void;
     /** Read-only snapshot of current LiveGraph state. */
     getState(): LiveGraph;
     /** Current schedule projection. */
     getSchedule(): ScheduleResult;
-    /** Internal dispatch tracking (for observability/debugging). */
-    getDispatchState(): ReadonlyMap<string, DispatchEntry>;
-    /** Cancel pending timeouts and stop dispatching. */
+    /** Stop accepting events. */
     dispose(): void;
 }
 declare function createReactiveGraph(config: GraphConfig, options: ReactiveGraphOptions, executionId?: string): ReactiveGraph;
 
-export { type DispatchEntry, DownstreamResult, FileJournal, GraphConfig, GraphEvent, type Journal, LiveGraph, LiveGraphHealth, LiveGraphSnapshot, MemoryJournal, NodeInfo, type ReactiveGraph, type ReactiveGraphOptions, ScheduleResult, TaskConfig, type TaskHandler, type TaskHandlerContext, type TaskHandlerResult, UnreachableNodesResult, UnreachableTokensResult, UpstreamResult, addNode, addProvides, addRequires, applyEvent, applyEvents, createLiveGraph, createReactiveGraph, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, removeNode, removeProvides, removeRequires, resetNode, restore, schedule, snapshot };
+/**
+ * Continuous Event Graph — Validation Utilities
+ *
+ * Runtime state-consistency checks for LiveGraph and ReactiveGraph.
+ * Unlike event-graph/validate.ts which validates static GraphConfig structure,
+ * these validate the *live* runtime state against its config.
+ *
+ * Pure functions — config+state in, diagnostics out.
+ */
+
+/**
+ * Validate that a LiveGraph's runtime state is consistent with its config.
+ *
+ * Checks:
+ *   - Every config task has a corresponding state entry (MISSING_STATE)
+ *   - No orphan state entries exist for tasks not in config (ORPHAN_STATE)
+ *   - Running tasks have a startedAt timestamp (RUNNING_WITHOUT_START)
+ *   - Completed tasks have a completedAt timestamp (COMPLETED_WITHOUT_TIMESTAMP)
+ *   - Failed tasks have a failedAt timestamp and error (FAILED_WITHOUT_INFO)
+ *   - Available outputs match what completed tasks should have produced (PHANTOM_OUTPUT / MISSING_OUTPUT)
+ *   - Execution counts are non-negative (INVALID_EXECUTION_COUNT)
+ *   - No task has executionCount > maxExecutions when capped (EXCEEDED_MAX_EXECUTIONS)
+ */
+declare function validateLiveGraph(live: LiveGraph): GraphValidationResult;
+/**
+ * Input for reactive graph validation.
+ * Accepts the reactive graph instance plus the original options (for handler list reference).
+ */
+interface ReactiveGraphValidationInput {
+    /** The reactive graph instance to validate */
+    graph: ReactiveGraph;
+    /** The handler registry (handler name → handler function) */
+    handlers: Record<string, unknown>;
+}
+/**
+ * Validate reactive-graph-specific consistency.
+ *
+ * Checks:
+ *   - Every handler name referenced in taskConfig.taskHandlers exists in the registry (MISSING_HANDLER)
+ *   - No handlers registered that are not referenced by any task's taskHandlers (ORPHAN_HANDLER)
+ *   - Plus all validateLiveGraph checks on the underlying state
+ */
+declare function validateReactiveGraph(input: ReactiveGraphValidationInput): GraphValidationResult;
+
+/**
+ * Continuous Event Graph — mutateGraph
+ *
+ * A higher-level batch mutation API.
+ *
+ * Unlike calling addNode/removeNode/injectTokens individually, mutateGraph
+ * accepts a declarative array of mutations and applies them atomically.
+ * This is useful for:
+ *   - Applying a set of structural changes + events in a single call
+ *   - Building mutation pipelines from external configs
+ *   - Reducing boilerplate when scripting graph changes
+ *
+ * Pattern: mutateGraph(live, mutations[]) → LiveGraph
+ * Pure function — no side effects.
+ */
+
+type GraphMutation = AddNodeMutation | RemoveNodeMutation | AddRequiresMutation | RemoveRequiresMutation | AddProvidesMutation | RemoveProvidesMutation | InjectTokensMutation | DrainTokensMutation | ResetNodeMutation | DisableNodeMutation | EnableNodeMutation | ApplyEventsMutation;
+interface AddNodeMutation {
+    type: 'add-node';
+    name: string;
+    config: TaskConfig;
+}
+interface RemoveNodeMutation {
+    type: 'remove-node';
+    name: string;
+}
+interface AddRequiresMutation {
+    type: 'add-requires';
+    taskName: string;
+    tokens: string[];
+}
+interface RemoveRequiresMutation {
+    type: 'remove-requires';
+    taskName: string;
+    tokens: string[];
+}
+interface AddProvidesMutation {
+    type: 'add-provides';
+    taskName: string;
+    tokens: string[];
+}
+interface RemoveProvidesMutation {
+    type: 'remove-provides';
+    taskName: string;
+    tokens: string[];
+}
+interface InjectTokensMutation {
+    type: 'inject-tokens';
+    tokens: string[];
+}
+interface DrainTokensMutation {
+    type: 'drain-tokens';
+    tokens: string[];
+}
+interface ResetNodeMutation {
+    type: 'reset-node';
+    name: string;
+}
+interface DisableNodeMutation {
+    type: 'disable-node';
+    name: string;
+}
+interface EnableNodeMutation {
+    type: 'enable-node';
+    name: string;
+}
+interface ApplyEventsMutation {
+    type: 'apply-events';
+    events: GraphEvent[];
+}
+/**
+ * Apply an ordered array of mutations to a LiveGraph, returning the new state.
+ *
+ * Mutations are applied in order. Each mutation can depend on the result of
+ * the previous one (e.g., add a node, then inject tokens it requires).
+ *
+ * Pure function — does not modify the input.
+ *
+ * @param live - The current LiveGraph
+ * @param mutations - Ordered array of mutations to apply
+ * @returns The new LiveGraph after all mutations
+ * @throws Error if a mutation references a non-existent task (for safety)
+ */
+declare function mutateGraph(live: LiveGraph, mutations: GraphMutation[]): LiveGraph;
+
+/**
+ * Continuous Event Graph — Handler Factories
+ *
+ * Ready-made TaskHandlerFn factories for common integration patterns.
+ * Each factory returns a TaskHandlerFn compatible with createReactiveGraph.
+ *
+ * In the callbackToken model, handlers are **initiators** — they kick off
+ * background work and return 'task-initiated'. The background work calls
+ * graph.resolveCallback(callbackToken, data) when done.
+ *
+ * Factories that wrap synchronous/async compute accept a `getGraph` getter
+ * to obtain the resolveCallback reference (lazy-bound because the graph
+ * doesn't exist yet at handler-creation time).
+ *
+ * Patterns:
+ *   createCallbackHandler   — wrap an async function that computes data
+ *   createFireAndForgetHandler — side-effect-only (always resolves empty data)
+ *   createShellHandler      — run a shell command, resolve with stdout
+ *   createScriptHandler     — spawn a Node.js/Python script
+ *   createWebhookHandler    — POST to a URL, resolve with response
+ *   createNoopHandler       — always resolves immediately (testing/placeholders)
+ */
+
+/** Minimal resolveCallback interface — matches ReactiveGraph.resolveCallback */
+interface ResolveCallbackFn {
+    (callbackToken: string, data: Record<string, unknown>, errors?: string[]): void;
+}
+/**
+ * Wrap a plain async function as a TaskHandlerFn.
+ *
+ * The function receives TaskHandlerInput and returns data.
+ * The factory handles the callbackToken plumbing — it fires
+ * the function in the background and calls resolveCallback.
+ *
+ * @param fn - Async function that computes and returns data
+ * @param getResolve - Lazy getter for the resolveCallback function
+ *
+ * @example
+ * ```ts
+ * let graph: ReactiveGraph;
+ * const handler = createCallbackHandler(
+ *   async ({ state }) => {
+ *     const prices = await fetchPrices(state['portfolio-form']?.symbols);
+ *     return { prices };
+ *   },
+ *   () => graph.resolveCallback.bind(graph),
+ * );
+ * graph = createReactiveGraph(config, { handlers: { fetchPrices: handler } });
+ * ```
+ */
+declare function createCallbackHandler(fn: (input: TaskHandlerInput) => Promise<Record<string, unknown>>, getResolve: () => ResolveCallbackFn): TaskHandlerFn;
+/**
+ * Fire-and-forget variant — the async function is invoked but
+ * the handler always resolves the task with empty data.
+ * Useful for side-effect-only tasks (logging, notifications).
+ *
+ * @param fn - Side-effect function (logging, alerting, etc.)
+ * @param getResolve - Lazy getter for the resolveCallback function
+ *
+ * @example
+ * ```ts
+ * const handler = createFireAndForgetHandler(
+ *   async ({ nodeId }) => { await sendSlack(`${nodeId} started`); },
+ *   () => graph.resolveCallback.bind(graph),
+ * );
+ * ```
+ */
+declare function createFireAndForgetHandler(fn: (input: TaskHandlerInput) => Promise<void> | void, getResolve: () => ResolveCallbackFn): TaskHandlerFn;
+interface ShellHandlerOptions {
+    /** Shell command to run. Supports ${taskName} placeholder. */
+    command: string;
+    /** Working directory (default: process.cwd()) */
+    cwd?: string;
+    /** Additional environment variables */
+    env?: Record<string, string>;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Map exit codes to result keys (default: 0 → 'success', non-zero → 'failure') */
+    exitCodeMap?: Record<number, string>;
+    /** If true, include stdout/stderr in data payload */
+    captureOutput?: boolean;
+    /** Lazy getter for the resolveCallback function */
+    getResolve: () => ResolveCallbackFn;
+}
+/**
+ * Create a TaskHandlerFn that runs a shell command.
+ *
+ * By default, exit code 0 = resolves with stdout data, non-zero = resolves with error.
+ * Use exitCodeMap to map specific codes to result keys for conditional routing.
+ *
+ * @example
+ * ```ts
+ * const handler = createShellHandler({
+ *   command: 'python scripts/process.py --task ${taskName}',
+ *   cwd: '/app',
+ *   captureOutput: true,
+ *   getResolve: () => graph.resolveCallback.bind(graph),
+ * });
+ * ```
+ */
+declare function createShellHandler(options: ShellHandlerOptions): TaskHandlerFn;
+interface ScriptHandlerOptions {
+    /** Path to the script file */
+    scriptPath: string;
+    /** Runtime to use (default: auto-detected from extension) */
+    runtime?: 'node' | 'python' | 'python3' | 'bash' | 'sh';
+    /** Additional CLI arguments */
+    args?: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Timeout in ms (default: 60000) */
+    timeoutMs?: number;
+    /** If true, include stdout/stderr in data payload */
+    captureOutput?: boolean;
+    /** Lazy getter for the resolveCallback function */
+    getResolve: () => ResolveCallbackFn;
+}
+/**
+ * Create a TaskHandlerFn that spawns a script file.
+ *
+ * Auto-detects the runtime from the file extension unless overridden.
+ * The task name is passed as the first argument to the script,
+ * followed by any additional args.
+ *
+ * @example
+ * ```ts
+ * const handler = createScriptHandler({
+ *   scriptPath: './scripts/etl.py',
+ *   args: ['--verbose'],
+ *   captureOutput: true,
+ *   getResolve: () => graph.resolveCallback.bind(graph),
+ * });
+ * ```
+ */
+declare function createScriptHandler(options: ScriptHandlerOptions): TaskHandlerFn;
+interface WebhookHandlerOptions {
+    /** URL to POST to. Supports ${taskName} placeholder. */
+    url: string;
+    /** HTTP method (default: POST) */
+    method?: 'POST' | 'PUT' | 'PATCH';
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** If true, treat non-2xx status as failure */
+    failOnNon2xx?: boolean;
+    /** Lazy getter for the resolveCallback function */
+    getResolve: () => ResolveCallbackFn;
+}
+/**
+ * Create a TaskHandlerFn that sends an HTTP request.
+ *
+ * Uses native fetch (Node 18+). The task context (nodeId, config)
+ * is sent as the JSON body along with the callbackToken.
+ *
+ * @example
+ * ```ts
+ * const handler = createWebhookHandler({
+ *   url: 'https://api.example.com/tasks/${taskName}/trigger',
+ *   headers: { 'Authorization': 'Bearer ...' },
+ *   getResolve: () => graph.resolveCallback.bind(graph),
+ * });
+ * ```
+ */
+declare function createWebhookHandler(options: WebhookHandlerOptions): TaskHandlerFn;
+/**
+ * Create a handler that always resolves immediately with static data.
+ * Useful for testing, placeholders, or passthrough tasks.
+ *
+ * @param getResolve - Lazy getter for the resolveCallback function
+ * @param staticData - Optional static data to resolve with
+ */
+declare function createNoopHandler(getResolve: () => ResolveCallbackFn, staticData?: Record<string, unknown>): TaskHandlerFn;
+
+/**
+ * Live Cards → Reactive Graph
+ *
+ * Takes an array of live card JSONs (card / source nodes) and produces
+ * a fully wired ReactiveGraph where:
+ *
+ *   - Each card becomes a task in the graph
+ *   - card.data.requires → task.requires (upstream card IDs as tokens)
+ *   - Each card produces a token equal to its own ID
+ *   - Card-type nodes: handler runs CardCompute.run() on a clone of the card,
+ *     returns the computed state as data (auto-hashed by the reactive layer)
+ *   - Source-type nodes: handler uses the source definition to fetch data,
+ *     or falls back to a user-provided handler / noop
+ *
+ * The reactive graph auto-computes dataHash on every handler result,
+ * so `data-changed` refresh strategy works out of the box.
+ *
+ * @example
+ * ```ts
+ * import { liveCardsToReactiveGraph } from 'yaml-flow/continuous-event-graph';
+ *
+ * const cards = [
+ *   { id: 'prices', type: 'source', source: { kind: 'api', bindTo: 'state.raw', url_template: '...' }, state: {} },
+ *   { id: 'dashboard', type: 'card', data: { requires: ['prices'] }, state: {}, compute: { total: { fn: 'sum', ... } }, view: { ... } },
+ * ];
+ *
+ * const rg = liveCardsToReactiveGraph(cards, {
+ *   sourceHandlers: {
+ *     prices: async () => ({ data: { raw: await fetchPrices() } }),
+ *   },
+ * });
+ *
+ * // One push → the whole board computes itself
+ * rg.push({ type: 'inject-tokens', tokens: [], timestamp: new Date().toISOString() });
+ * ```
+ */
+
+/**
+ * Minimal live card shape accepted by this utility.
+ * Matches the live-cards.schema.json structure.
+ */
+interface LiveCard {
+    id: string;
+    type: 'card' | 'source';
+    meta?: {
+        title?: string;
+        tags?: string[];
+    };
+    data?: {
+        requires?: string[];
+        provides?: Record<string, unknown>;
+    };
+    state?: Record<string, unknown>;
+    compute?: Record<string, unknown>;
+    source?: {
+        kind: 'api' | 'websocket' | 'static' | 'llm';
+        bindTo: string;
+        url_template?: string;
+        method?: string;
+        headers?: Record<string, unknown>;
+        body_template?: Record<string, unknown>;
+        poll_interval?: number;
+        transform?: string;
+        [key: string]: unknown;
+    };
+    view?: Record<string, unknown>;
+}
+/**
+ * A Board is a named container of live card nodes.
+ * Matches the shape used by LiveCard.Board() in browser/live-cards.js:
+ *   LiveCard.Board(engine, el, { nodes, positions?, mode, canvas, ... })
+ *
+ * The `nodes` array contains the card/source JSON objects.
+ * Board-level metadata (id, title, settings) is carried through to the
+ * generated GraphConfig.
+ */
+interface LiveBoard {
+    /** Board identifier */
+    id?: string;
+    /** Human-readable title */
+    title?: string;
+    /** The card/source nodes on this board */
+    nodes: LiveCard[];
+    /** Board display mode (informational — not used by the reactive graph) */
+    mode?: 'board' | 'canvas';
+    /** Canvas positions keyed by node ID (informational — not used) */
+    positions?: Record<string, {
+        x?: number;
+        y?: number;
+        w?: number;
+        h?: number;
+    }>;
+    /** Board-level settings forwarded to GraphConfig.settings */
+    settings?: Partial<GraphConfig['settings']>;
+}
+interface LiveCardsToReactiveOptions {
+    /** Custom handlers for source nodes (keyed by card ID). */
+    sourceHandlers?: Record<string, TaskHandlerFn>;
+    /**
+     * Default handler factory for source nodes without an explicit handler.
+     * Called once per source card during graph construction.
+     * If not provided, source nodes without explicit handlers get a noop handler
+     * that returns the card's current state.
+     */
+    defaultSourceHandler?: (card: LiveCard) => TaskHandlerFn;
+    /**
+     * Custom handlers for card nodes (keyed by card ID).
+     * Overrides the default CardCompute.run() behavior.
+     */
+    cardHandlers?: Record<string, TaskHandlerFn>;
+    /**
+     * If provided, upstream card state is injected into downstream cards
+     * before running compute. The key is the upstream card ID and the value
+     * is the upstream card's latest state.
+     */
+    sharedState?: Map<string, Record<string, unknown>>;
+    /** Override reactive graph options (journal, callbacks, etc.) */
+    reactiveOptions?: Partial<Omit<ReactiveGraphOptions, 'handlers'>>;
+    /** Graph-level settings overrides */
+    graphSettings?: Partial<GraphConfig['settings']>;
+    /** Execution ID for the reactive graph */
+    executionId?: string;
+}
+interface LiveCardsToReactiveResult {
+    /** The fully wired reactive graph — ready to push events into. */
+    graph: ReactiveGraph;
+    /** The generated GraphConfig (for inspection/serialization). */
+    config: GraphConfig;
+    /** The handler map (for use with validateReactiveGraph). */
+    handlers: Record<string, TaskHandlerFn>;
+    /** Card lookup by ID (original references). */
+    cards: Map<string, LiveCard>;
+    /**
+     * Shared state map: cardId → latest computed state.
+     * Updated automatically by built-in handlers after each task completes.
+     * Custom cardHandlers/sourceHandlers can also read upstream data directly
+     * from the engine: graph.getState().state.tasks[cardId].data
+     */
+    sharedState: Map<string, Record<string, unknown>>;
+}
+/**
+ * Convert live card JSONs or a Board into a fully wired ReactiveGraph.
+ *
+ * Overloads:
+ *   liveCardsToReactiveGraph(cards[], options?)  — from a flat array of cards
+ *   liveCardsToReactiveGraph(board, options?)    — from a LiveBoard object
+ */
+declare function liveCardsToReactiveGraph(input: LiveCard[] | LiveBoard, options?: LiveCardsToReactiveOptions): LiveCardsToReactiveResult;
+
+export { DownstreamResult, FileJournal, GraphConfig, GraphEngineStore, GraphEvent, type GraphMutation, type Journal, type LiveBoard, type LiveCard, type LiveCardsToReactiveOptions, type LiveCardsToReactiveResult, LiveGraph, LiveGraphHealth, LiveGraphSnapshot, MemoryJournal, NodeInfo, type ReactiveGraph, type ReactiveGraphOptions, type ReactiveGraphValidationInput, type ResolveCallbackFn, ScheduleResult, type ScriptHandlerOptions, type ShellHandlerOptions, TaskConfig, type TaskHandlerFn, type TaskHandlerInput, type TaskHandlerReturn, UnreachableNodesResult, UnreachableTokensResult, UpstreamResult, type WebhookHandlerOptions, addNode, addProvides, addRequires, applyEvent, applyEvents, computeDataHash, createCallbackHandler, createFireAndForgetHandler, createLiveGraph, createNoopHandler, createReactiveGraph, createScriptHandler, createShellHandler, createWebhookHandler, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, liveCardsToReactiveGraph, mutateGraph, removeNode, removeProvides, removeRequires, resetNode, restore, schedule, snapshot, validateLiveGraph, validateReactiveGraph };