yaml-flow 2.7.0 → 3.0.0

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

@@ -1,7 +1,7 @@
-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-C2lOwquM.cjs';
-export { B as BlockedTask, P as PendingTask, d as UnresolvedDependency } from '../types-C2lOwquM.cjs';
-import { T as TaskConfig, e as GraphEvent, G as GraphConfig } from '../types-DAI_a2as.cjs';
-export { c as ExecutionState, f as GraphSettings, l as TaskState } from '../types-DAI_a2as.cjs';
+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-CxJg9Jrt.cjs';
+export { B as BlockedTask, P as PendingTask, d as UnresolvedDependency } from '../types-CxJg9Jrt.cjs';
+import { T as TaskConfig, e as GraphEvent, G as GraphConfig } from '../types-BpWrH1sf.cjs';
+export { c as ExecutionState, f as GraphSettings, l as TaskState } from '../types-BpWrH1sf.cjs';
 
 /**
  * Continuous Event Graph — Core
@@ -27,6 +27,12 @@ declare function createLiveGraph(config: GraphConfig, executionId?: string): Liv
  * Config is NOT mutated by events — only state changes.
  */
 declare function applyEvent(live: LiveGraph, event: GraphEvent): LiveGraph;
+/**
+ * Apply multiple events atomically to a LiveGraph.
+ * Events are reduced sequentially, but the caller only sees the final state.
+ * Use this for batch processing (e.g. draining a journal of pending events).
+ */
+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.
@@ -176,4 +182,117 @@ declare function getUpstream(live: LiveGraph, nodeName: string): UpstreamResult;
  */
 declare function getDownstream(live: LiveGraph, nodeName: string): DownstreamResult;
 
-export { DownstreamResult, GraphConfig, GraphEvent, LiveGraph, LiveGraphHealth, LiveGraphSnapshot, NodeInfo, ScheduleResult, TaskConfig, UnreachableNodesResult, UnreachableTokensResult, UpstreamResult, addNode, addProvides, addRequires, applyEvent, createLiveGraph, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, removeNode, removeProvides, removeRequires, resetNode, restore, schedule, snapshot };
+/**
+ * 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.
+ */
+
+/** 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;
+}
+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;
+    /** 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(event: GraphEvent): void;
+    /** Push multiple events. 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. */
+    removeNode(name: 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. */
+    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 };

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

@@ -1,7 +1,7 @@
-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-mS_pPftm.js';
-export { B as BlockedTask, P as PendingTask, d as UnresolvedDependency } from '../types-mS_pPftm.js';
-import { T as TaskConfig, e as GraphEvent, G as GraphConfig } from '../types-DAI_a2as.js';
-export { c as ExecutionState, f as GraphSettings, l as TaskState } from '../types-DAI_a2as.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-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';
 
 /**
  * Continuous Event Graph — Core
@@ -27,6 +27,12 @@ declare function createLiveGraph(config: GraphConfig, executionId?: string): Liv
  * Config is NOT mutated by events — only state changes.
  */
 declare function applyEvent(live: LiveGraph, event: GraphEvent): LiveGraph;
+/**
+ * Apply multiple events atomically to a LiveGraph.
+ * Events are reduced sequentially, but the caller only sees the final state.
+ * Use this for batch processing (e.g. draining a journal of pending events).
+ */
+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.
@@ -176,4 +182,117 @@ declare function getUpstream(live: LiveGraph, nodeName: string): UpstreamResult;
  */
 declare function getDownstream(live: LiveGraph, nodeName: string): DownstreamResult;
 
-export { DownstreamResult, GraphConfig, GraphEvent, LiveGraph, LiveGraphHealth, LiveGraphSnapshot, NodeInfo, ScheduleResult, TaskConfig, UnreachableNodesResult, UnreachableTokensResult, UpstreamResult, addNode, addProvides, addRequires, applyEvent, createLiveGraph, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, removeNode, removeProvides, removeRequires, resetNode, restore, schedule, snapshot };
+/**
+ * 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.
+ */
+
+/** 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;
+}
+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;
+    /** 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(event: GraphEvent): void;
+    /** Push multiple events. 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. */
+    removeNode(name: 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. */
+    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 };