yaml-flow 3.1.1 → 5.0.0

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

@@ -1,8 +1,12 @@
-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';
+import { L as LiveGraph, N as NodeInfo, b as LiveGraphSnapshot, D as DownstreamResult, U as UnreachableNodesResult, c as UnreachableTokensResult, e as UpstreamResult, a as LiveGraphHealth } from '../types-C2eJ7DAV.js';
+export { B as BlockedTask, P as PendingTask, S as ScheduleResult, d as UnresolvedDependency } from '../types-C2eJ7DAV.js';
+import { T as TaskConfig, f as GraphEvent, G as GraphConfig } from '../types-CMFSIjpc.js';
+export { c as ExecutionState, e as GraphEngineStore, g as GraphSettings } from '../types-CMFSIjpc.js';
+export { s as schedule } from '../schedule-CMcZe5Ny.js';
+import { R as ReactiveGraph, e as TaskHandlerInput, T as TaskHandlerFn } from '../live-cards-bridge-Or7fdEJV.js';
+export { L as LiveBoard, a as LiveCard, b as LiveCardsToReactiveOptions, c as LiveCardsToReactiveResult, d as ReactiveGraphOptions, f as TaskHandlerReturn, h as computeDataHash, g as createReactiveGraph, l as liveCardsToReactiveGraph } from '../live-cards-bridge-Or7fdEJV.js';
+import { a as GraphValidationResult } from '../validate-DJQTQ6bP.js';
+export { J as Journal, M as MemoryJournal } from '../journal-NLYuqege.js';
 
 /**
  * Continuous Event Graph — Core
@@ -21,11 +25,12 @@ import { a as GraphValidationResult } from '../validate-DEZ2Ymdb.js';
  */
 declare function createLiveGraph(config: GraphConfig, executionId?: string): LiveGraph;
 /**
- * Apply an execution event to the LiveGraph, producing a new LiveGraph.
- * Events are the shared vocabulary: task-started, task-completed, task-failed,
- * task-progress, inject-tokens, agent-action.
+ * Apply an event to the LiveGraph, producing a new LiveGraph.
+ * Events are the shared vocabulary — both execution state transitions
+ * (task-started, task-completed, etc.) and structural mutations
+ * (task-upsert, task-removal, node-requires-add, etc.).
  *
- * Config is NOT mutated by events — only state changes.
+ * Pure function: f(LiveGraph, GraphEvent) → LiveGraph
  */
 declare function applyEvent(live: LiveGraph, event: GraphEvent): LiveGraph;
 /**
@@ -35,8 +40,9 @@ declare function applyEvent(live: LiveGraph, event: GraphEvent): LiveGraph;
  */
 declare function applyEvents(live: LiveGraph, events: GraphEvent[]): LiveGraph;
 /**
- * Add a node (task) to the live graph. Updates both config and state atomically.
- * If the node already exists, returns the graph unchanged.
+ * Upsert a node (task) in the live graph. Updates both config and state atomically.
+ * If the node already exists, replaces its config but preserves its state.
+ * If new, creates fresh default state.
  */
 declare function addNode(live: LiveGraph, name: string, taskConfig: TaskConfig): LiveGraph;
 /**
@@ -109,24 +115,6 @@ declare function snapshot(live: LiveGraph): LiveGraphSnapshot;
  */
 declare function restore(data: unknown): LiveGraph;
 
-/**
- * Continuous Event Graph — Schedule
- *
- * Pure read-only projection: LiveGraph → ScheduleResult
- *
- * Classifies every non-terminal task into one of:
- *   - eligible: all requires satisfied, ready to dispatch
- *   - pending: requires not yet met, but a viable producer exists (normal waiting)
- *   - unresolved: requires not met, NO task in the graph can produce them (caller's problem)
- *   - blocked: requires not met because the producing task FAILED (caller's problem)
- */
-
-/**
- * Compute the scheduling status of every task in the live graph.
- * Pure function — no side effects.
- */
-declare function schedule(live: LiveGraph): ScheduleResult;
-
 /**
  * Continuous Event Graph — Inspect
  *
@@ -183,185 +171,6 @@ declare function getUpstream(live: LiveGraph, nodeName: string): UpstreamResult;
  */
 declare function getDownstream(live: LiveGraph, nodeName: string): DownstreamResult;
 
-/**
- * Continuous Event Graph — Journal
- *
- * Append-only event log for the reactive layer.
- * Handlers append events here; drain() reads and clears atomically.
- *
- * Two adapters:
- *   - MemoryJournal: in-process array (default)
- *   - FileJournal:   append to a JSONL file, truncate on drain
- */
-
-interface Journal {
-    /** Append an event to the journal. Safe to call from concurrent callbacks. */
-    append(event: GraphEvent): void;
-    /** Read all pending events and clear the journal atomically. */
-    drain(): GraphEvent[];
-    /** Number of pending events (for observability). */
-    readonly size: number;
-}
-declare class MemoryJournal implements Journal {
-    private buffer;
-    append(event: GraphEvent): void;
-    drain(): GraphEvent[];
-    get size(): number;
-}
-declare class FileJournal implements Journal {
-    private readonly path;
-    private pending;
-    constructor(path: string);
-    append(event: GraphEvent): void;
-    drain(): GraphEvent[];
-    get size(): number;
-}
-
-/**
- * Continuous Event Graph — Reactive Layer
- *
- * Push-based, self-sustaining execution wrapper.
- *
- * Pattern:
- *   1. Register handlers for tasks
- *   2. Push an event (or inject tokens)
- *   3. The graph drives itself: drain journal → applyEvents → schedule → dispatch → repeat
- *
- * No daemon, no polling. Each handler callback appends to the journal,
- * which triggers a drain cycle that may dispatch the next wave.
- *
- * Dispatch failures, retries, and timeouts are managed internally
- * without touching the core engine types.
- */
-
-/**
- * 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 {
-    /** Named handler registry — handler name → handler function */
-    handlers: Record<string, TaskHandlerFn>;
-    /** Journal adapter (default: MemoryJournal) */
-    journal?: Journal;
-    /** Called after each drain cycle — for observability */
-    onDrain?: (events: GraphEvent[], live: LiveGraph, scheduleResult: ScheduleResult) => void;
-}
-interface ReactiveGraph {
-    /** Push an event into the graph via journal. Triggers drain → schedule → dispatch. */
-    push(event: GraphEvent): void;
-    /** Push multiple events via journal. Single drain cycle after all are journaled. */
-    pushAll(events: GraphEvent[]): void;
-    /**
-     * 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;
-    /** Stop accepting events. */
-    dispose(): void;
-}
-declare function createReactiveGraph(config: GraphConfig, options: ReactiveGraphOptions, executionId?: string): ReactiveGraph;
-
 /**
  * Continuous Event Graph — Validation Utilities
  *
@@ -665,153 +474,4 @@ declare function createWebhookHandler(options: WebhookHandlerOptions): TaskHandl
  */
 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 };
+export { DownstreamResult, GraphConfig, GraphEvent, type GraphMutation, LiveGraph, LiveGraphHealth, LiveGraphSnapshot, NodeInfo, ReactiveGraph, type ReactiveGraphValidationInput, type ResolveCallbackFn, type ScriptHandlerOptions, type ShellHandlerOptions, TaskConfig, TaskHandlerFn, TaskHandlerInput, UnreachableNodesResult, UnreachableTokensResult, UpstreamResult, type WebhookHandlerOptions, addNode, addProvides, addRequires, applyEvent, applyEvents, createCallbackHandler, createFireAndForgetHandler, createLiveGraph, createNoopHandler, createScriptHandler, createShellHandler, createWebhookHandler, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, mutateGraph, removeNode, removeProvides, removeRequires, resetNode, restore, snapshot, validateLiveGraph, validateReactiveGraph };