yaml-flow 2.3.0 → 2.4.0

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

@@ -0,0 +1,309 @@
+import { G as GraphConfig, c as ExecutionState, T as TaskConfig, l as TaskState, e as GraphEvent } from '../types-CTu8RqY0.js';
+export { f as GraphSettings } from '../types-CTu8RqY0.js';
+
+/**
+ * Continuous Event Graph — Types
+ *
+ * A long-lived, evolving event-graph where both config and state
+ * mutate over time. The single `LiveGraph` type bundles them.
+ *
+ * Events are shared with event-graph (task-started, task-completed, etc.).
+ * Graph mutations (addNode, removeNode, etc.) are unique to this mode.
+ */
+
+/**
+ * The single evolving object for a continuous-mode graph.
+ * Bundles config + state so they can't get out of sync.
+ */
+interface LiveGraph {
+    /** The current graph configuration (evolves as nodes are added/removed) */
+    config: GraphConfig;
+    /** The current execution state (evolves as events arrive) */
+    state: ExecutionState;
+}
+interface ScheduleResult {
+    /** Tasks ready to dispatch now — all requires satisfied */
+    eligible: string[];
+    /** Tasks waiting on tokens that some producer will eventually provide (normal) */
+    pending: PendingTask[];
+    /** Tasks waiting on tokens that NO task can produce (caller's problem) */
+    unresolved: UnresolvedDependency[];
+    /** Tasks waiting on tokens whose producer FAILED (caller's problem) */
+    blocked: BlockedTask[];
+    /** Token conflicts: multiple tasks produce the same token */
+    conflicts: Record<string, string[]>;
+}
+interface PendingTask {
+    taskName: string;
+    /** Tokens this task needs that haven't been produced yet but have a viable producer */
+    waitingOn: string[];
+}
+interface UnresolvedDependency {
+    taskName: string;
+    /** Tokens this task needs that no task in the graph can produce */
+    missingTokens: string[];
+}
+interface BlockedTask {
+    taskName: string;
+    /** Tokens this task needs whose only producer has failed */
+    failedTokens: string[];
+    /** The tasks that failed and would have produced those tokens */
+    failedProducers: string[];
+}
+interface LiveGraphHealth {
+    /** Total number of tasks in the graph */
+    totalNodes: number;
+    /** Task counts by status */
+    running: number;
+    completed: number;
+    failed: number;
+    waiting: number;
+    notStarted: number;
+    /** Number of disabled (inactivated) nodes */
+    disabled: number;
+    /** Number of tasks with unresolvable dependencies */
+    unresolvedCount: number;
+    /** Number of tasks whose producer has failed */
+    blockedCount: number;
+    /** Tokens that no task produces (open dependencies) */
+    openDependencies: string[];
+    /** Cycles detected in the current graph (if any) */
+    cycles: string[][];
+    /** Tokens produced by multiple tasks */
+    conflictTokens: string[];
+}
+interface NodeInfo {
+    /** Node name */
+    name: string;
+    /** The task configuration */
+    config: TaskConfig;
+    /** The current runtime state */
+    state: TaskState;
+}
+interface LiveGraphSnapshot {
+    /** Schema version for forward compatibility */
+    version: number;
+    /** The graph config at snapshot time */
+    config: GraphConfig;
+    /** The execution state at snapshot time */
+    state: ExecutionState;
+    /** ISO timestamp of when the snapshot was taken */
+    snapshotAt: string;
+}
+interface UnreachableTokensResult {
+    tokens: {
+        /** The token that cannot be produced */
+        token: string;
+        /** Why it's unreachable */
+        reason: 'no-producer' | 'all-producers-failed' | 'transitive';
+        /** Tasks that could produce it (but are themselves unreachable/failed) */
+        producers: string[];
+    }[];
+}
+interface UnreachableNodesResult {
+    nodes: {
+        /** The node that can never become eligible */
+        nodeName: string;
+        /** Unreachable tokens this node requires (empty if the node itself is failed/disabled) */
+        missingTokens: string[];
+    }[];
+}
+interface UpstreamResult {
+    /** The target node being inspected */
+    nodeName: string;
+    /** All upstream nodes that transitively feed into the target */
+    nodes: {
+        nodeName: string;
+        /** Tokens this node provides that are in the dependency chain */
+        providesTokens: string[];
+    }[];
+    /** All tokens in the upstream dependency chain */
+    tokens: string[];
+}
+interface DownstreamResult {
+    /** The target node being inspected */
+    nodeName: string;
+    /** All downstream nodes that transitively depend on the target */
+    nodes: {
+        nodeName: string;
+        /** Tokens this node requires that are in the dependency chain */
+        requiresTokens: string[];
+    }[];
+    /** All tokens in the downstream dependency chain */
+    tokens: string[];
+}
+
+/**
+ * Continuous Event Graph — Core
+ *
+ * All functions are pure: f(LiveGraph, input) → LiveGraph
+ *
+ * - createLiveGraph: bootstrap from a GraphConfig
+ * - applyEvent: reduce an event (task-started, task-completed, etc.)
+ * - addNode / removeNode: structural graph mutations
+ * - addRequires / removeRequires / addProvides / removeProvides: wiring mutations
+ */
+
+/**
+ * Create a LiveGraph from a GraphConfig.
+ * Initialises execution state for all tasks in the config.
+ */
+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.
+ *
+ * Config is NOT mutated by events — only state changes.
+ */
+declare function applyEvent(live: LiveGraph, event: 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.
+ */
+declare function addNode(live: LiveGraph, name: string, taskConfig: TaskConfig): LiveGraph;
+/**
+ * Remove a node (task) from the live graph. Updates both config and state atomically.
+ * If the node doesn't exist, returns the graph unchanged.
+ * NOTE: Does not clean up references — other nodes' requires/provides are left intact.
+ * The caller can use removeRequires() to clean up if needed.
+ */
+declare function removeNode(live: LiveGraph, name: string): LiveGraph;
+/**
+ * Add requires tokens to a node. If the node doesn't exist, returns unchanged.
+ * Deduplicates — won't add tokens already in requires.
+ */
+declare function addRequires(live: LiveGraph, nodeName: string, tokens: string[]): LiveGraph;
+/**
+ * Remove requires tokens from a node. If the node doesn't exist, returns unchanged.
+ */
+declare function removeRequires(live: LiveGraph, nodeName: string, tokens: string[]): LiveGraph;
+/**
+ * Add provides tokens to a node. If the node doesn't exist, returns unchanged.
+ * Deduplicates — won't add tokens already in provides.
+ */
+declare function addProvides(live: LiveGraph, nodeName: string, tokens: string[]): LiveGraph;
+/**
+ * Remove provides tokens from a node. If the node doesn't exist, returns unchanged.
+ */
+declare function removeProvides(live: LiveGraph, nodeName: string, tokens: string[]): LiveGraph;
+/**
+ * Inject tokens into the live graph's available outputs.
+ * Equivalent to applyEvent(live, { type: 'inject-tokens', tokens, timestamp }).
+ */
+declare function injectTokens(live: LiveGraph, tokens: string[]): LiveGraph;
+/**
+ * Drain (remove) tokens from the live graph's available outputs.
+ * Inverse of injectTokens — useful for expiring stale data or revoking signals.
+ * Tokens that aren't currently available are silently ignored.
+ * Pure function.
+ */
+declare function drainTokens(live: LiveGraph, tokens: string[]): LiveGraph;
+/**
+ * Reset a node's state back to not-started, clearing error, retry count, progress.
+ * Config is untouched. Useful when a failed task should be retried later.
+ * If the node doesn't exist, returns unchanged.
+ */
+declare function resetNode(live: LiveGraph, name: string): LiveGraph;
+/**
+ * Disable a node — sets its status to 'inactivated'.
+ * The scheduler will skip inactivated tasks. Config is untouched.
+ * If the node doesn't exist or is already inactivated, returns unchanged.
+ */
+declare function disableNode(live: LiveGraph, name: string): LiveGraph;
+/**
+ * Enable a previously-disabled node — sets its status back to 'not-started'.
+ * Only acts on 'inactivated' nodes. If the node isn't inactivated, returns unchanged.
+ */
+declare function enableNode(live: LiveGraph, name: string): LiveGraph;
+/**
+ * Get the config and state for a single node.
+ * Returns undefined if the node doesn't exist.
+ */
+declare function getNode(live: LiveGraph, name: string): NodeInfo | undefined;
+/**
+ * Serialize a LiveGraph to a plain JSON-safe object.
+ * Can be persisted to disk, database, etc.
+ */
+declare function snapshot(live: LiveGraph): LiveGraphSnapshot;
+/**
+ * Restore a LiveGraph from a snapshot. Validates the shape.
+ * Throws if the snapshot is invalid.
+ */
+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
+ *
+ * Pure read-only projection: LiveGraph → LiveGraphHealth
+ *
+ * Live health report combining config structure + runtime state.
+ */
+
+/**
+ * Compute a live health report for the graph.
+ * Combines structural analysis (cycles, conflicts, open deps) with runtime state (task statuses).
+ * Pure function — no side effects.
+ */
+declare function inspect(live: LiveGraph): LiveGraphHealth;
+/**
+ * Get all tokens that are required but cannot be produced given the current
+ * graph state. This is **transitive**: if token X is unreachable, and node A
+ * is the only producer of token Y but A requires X, then Y is also unreachable.
+ *
+ * Takes into account:
+ * - Tokens already in availableOutputs (reachable)
+ * - Tokens from completed tasks (reachable)
+ * - Failed/disabled producers (non-viable)
+ *
+ * Pure function.
+ */
+declare function getUnreachableTokens(live: LiveGraph): UnreachableTokensResult;
+/**
+ * Get all nodes that can never become eligible given the current graph state.
+ * A node is unreachable if any of its required tokens is unreachable.
+ *
+ * This is the node-level companion to getUnreachableTokens — uses the same
+ * transitive analysis.
+ *
+ * Pure function.
+ */
+declare function getUnreachableNodes(live: LiveGraph): UnreachableNodesResult;
+/**
+ * Get all nodes that transitively feed into the given node.
+ * "What's upstream of X?" — traces backwards through requires → provides chains.
+ *
+ * Returns the set of upstream nodes and the tokens connecting them.
+ * Does NOT include the target node itself.
+ * Pure function.
+ */
+declare function getUpstream(live: LiveGraph, nodeName: string): UpstreamResult;
+/**
+ * Get all nodes that transitively depend on the given node.
+ * "What breaks if I disable X?" — traces forwards through provides → requires chains.
+ *
+ * Returns the set of downstream nodes and the tokens connecting them.
+ * Does NOT include the target node itself.
+ * Pure function.
+ */
+declare function getDownstream(live: LiveGraph, nodeName: string): DownstreamResult;
+
+export { type BlockedTask, type DownstreamResult, ExecutionState, GraphConfig, GraphEvent, type LiveGraph, type LiveGraphHealth, type LiveGraphSnapshot, type NodeInfo, type PendingTask, type ScheduleResult, TaskConfig, TaskState, type UnreachableNodesResult, type UnreachableTokensResult, type UnresolvedDependency, type UpstreamResult, addNode, addProvides, addRequires, applyEvent, createLiveGraph, disableNode, drainTokens, enableNode, getDownstream, getNode, getUnreachableNodes, getUnreachableTokens, getUpstream, injectTokens, inspect, removeNode, removeProvides, removeRequires, resetNode, restore, schedule, snapshot };