@decaf-ts/integrations 0.3.1 → 0.3.3

package/lib/types/graph/events/GraphExecutionEventFactory.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @module integrations/graph/events/GraphExecutionEventFactory
+ * @summary Factory for creating graph execution events with unique ids, sequence numbers, and timestamps.
+ * @description Provides a stateful factory that produces monotonically-sequenced events for a single execution run.
+ */
+import type { GraphExecutionEvent } from "../types.d.mts";
+/**
+ * Factory that enriches partial events with a unique id, an incrementing
+ * sequence number, and a timestamp.
+ */
+export declare class GraphExecutionEventFactory {
+    private sequence;
+    /**
+     * Creates a fully-populated event from the given base fields.
+     *
+     * @param base - All event fields except `id`, `sequence`, and `timestamp`.
+     * @returns A complete {@link GraphExecutionEvent}.
+     */
+    create(base: Omit<GraphExecutionEvent, "id" | "sequence" | "timestamp">): GraphExecutionEvent;
+    /**
+     * Generates a unique event id using `crypto.randomUUID` when available,
+     * falling back to a timestamp + random string.
+     */
+    private createEventId;
+}

package/lib/types/graph/events/GraphExecutionObserver.d.cts

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/graph/events/GraphExecutionObserver
+ * @summary Observer interface for graph execution events.
+ * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
+ */
+import type { Observer } from "@decaf-ts/core";
+import type { GraphExecutionEvent } from "../types.d.cts";
+/**
+ * Observer that receives {@link GraphExecutionEvent} instances from the
+ * graph execution engine.
+ */
+export interface GraphExecutionObserver extends Observer<[GraphExecutionEvent]> {
+    /**
+     * Called by the engine when a new graph execution event is emitted.
+     */
+    refresh(event: GraphExecutionEvent): Promise<void>;
+}

package/lib/types/graph/events/GraphExecutionObserver.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/graph/events/GraphExecutionObserver
+ * @summary Observer interface for graph execution events.
+ * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
+ */
+import type { Observer } from "@decaf-ts/core";
+import type { GraphExecutionEvent } from "../types.d.mts";
+/**
+ * Observer that receives {@link GraphExecutionEvent} instances from the
+ * graph execution engine.
+ */
+export interface GraphExecutionObserver extends Observer<[GraphExecutionEvent]> {
+    /**
+     * Called by the engine when a new graph execution event is emitted.
+     */
+    refresh(event: GraphExecutionEvent): Promise<void>;
+}

package/lib/types/graph/events/index.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/graph/events
+ * @summary Graph execution event pipeline.
+ * @description Re-exports the observer interface, event emitter, and event factory.
+ */
+export * from "./GraphExecutionEvent.d.cts";
+export * from "./GraphExecutionObserver.d.cts";
+export * from "./GraphExecutionEventEmitter.d.cts";
+export * from "./GraphExecutionEventFactory.d.cts";

package/lib/types/graph/events/index.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/graph/events
+ * @summary Graph execution event pipeline.
+ * @description Re-exports the observer interface, event emitter, and event factory.
+ */
+export * from "./GraphExecutionEvent.d.mts";
+export * from "./GraphExecutionObserver.d.mts";
+export * from "./GraphExecutionEventEmitter.d.mts";
+export * from "./GraphExecutionEventFactory.d.mts";

package/lib/types/graph/execution/GraphExecutionContext.d.cts

@@ -0,0 +1,50 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionContext
+ * @summary Decaf Context for graph node execution.
+ * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline.
+ */
+import { Context } from "@decaf-ts/core";
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEvent, GraphRunId } from "../types.d.cts";
+/**
+ * Context passed to every graph node executor.
+ *
+ * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
+ * `GraphExecutionContext` per node execution and passes it to
+ * `executor.execute(inputs, context)`. The executor uses `context.progress(...)`
+ * and `context.log(...)` to report intermediate state.
+ */
+export declare class GraphExecutionContext extends Context {
+    readonly runId: GraphRunId;
+    readonly parentRunId: GraphRunId | undefined;
+    readonly workflow: GraphWorkflowDefinition;
+    readonly node: GraphNodeDefinition;
+    readonly path: string[];
+    private readonly emitFn;
+    readonly metadata: Record<string, unknown>;
+    /**
+     * @param runId - Unique identifier for the current execution run.
+     * @param parentRunId - Run id of the parent execution (for nested loop bodies).
+     * @param workflow - The workflow definition being executed.
+     * @param node - The node definition being executed.
+     * @param path - Dotted path from the workflow root to this node.
+     * @param emitFn - Callback invoked when an event is emitted from this context.
+     * @param metadata - Free-form metadata attached to this context.
+     */
+    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    /**
+     * Emits a partial graph execution event. The engine fills in runId,
+     * parentRunId, workflowId, nodeId, and path automatically.
+     */
+    emit(event: Partial<GraphExecutionEvent>): Promise<void>;
+    /**
+     * Emits a `NODE_OUTPUT` event with the given payload, useful for reporting
+     * intermediate progress from within a node executor.
+     */
+    progress(payload: unknown): Promise<void>;
+    /**
+     * Emits a `NODE_OUTPUT` event with a structured `{ message, payload }` shape
+     * so executors can log human-readable messages.
+     */
+    log(message: string, payload?: unknown): Promise<void>;
+}

package/lib/types/graph/execution/GraphExecutionContext.d.mts

@@ -0,0 +1,50 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionContext
+ * @summary Decaf Context for graph node execution.
+ * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline.
+ */
+import { Context } from "@decaf-ts/core";
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEvent, GraphRunId } from "../types.d.mts";
+/**
+ * Context passed to every graph node executor.
+ *
+ * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
+ * `GraphExecutionContext` per node execution and passes it to
+ * `executor.execute(inputs, context)`. The executor uses `context.progress(...)`
+ * and `context.log(...)` to report intermediate state.
+ */
+export declare class GraphExecutionContext extends Context {
+    readonly runId: GraphRunId;
+    readonly parentRunId: GraphRunId | undefined;
+    readonly workflow: GraphWorkflowDefinition;
+    readonly node: GraphNodeDefinition;
+    readonly path: string[];
+    private readonly emitFn;
+    readonly metadata: Record<string, unknown>;
+    /**
+     * @param runId - Unique identifier for the current execution run.
+     * @param parentRunId - Run id of the parent execution (for nested loop bodies).
+     * @param workflow - The workflow definition being executed.
+     * @param node - The node definition being executed.
+     * @param path - Dotted path from the workflow root to this node.
+     * @param emitFn - Callback invoked when an event is emitted from this context.
+     * @param metadata - Free-form metadata attached to this context.
+     */
+    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    /**
+     * Emits a partial graph execution event. The engine fills in runId,
+     * parentRunId, workflowId, nodeId, and path automatically.
+     */
+    emit(event: Partial<GraphExecutionEvent>): Promise<void>;
+    /**
+     * Emits a `NODE_OUTPUT` event with the given payload, useful for reporting
+     * intermediate progress from within a node executor.
+     */
+    progress(payload: unknown): Promise<void>;
+    /**
+     * Emits a `NODE_OUTPUT` event with a structured `{ message, payload }` shape
+     * so executors can log human-readable messages.
+     */
+    log(message: string, payload?: unknown): Promise<void>;
+}

package/lib/types/graph/execution/GraphExecutionEngine.d.cts

@@ -0,0 +1,112 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionEngine
+ * @summary Reference graph execution engine.
+ * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result.
+ */
+import type { Observable } from "@decaf-ts/core";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEvent, GraphExecutionOptions, GraphExecutionResult, GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.cts";
+import type { GraphExecutionObserver } from "../events/GraphExecutionObserver.d.cts";
+import { GraphExecutionEventEmitter } from "../events/GraphExecutionEventEmitter.d.cts";
+import type { GraphNodeExecutorRegistry } from "../registry/GraphNodeExecutorRegistry.d.cts";
+import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.cts";
+import type { GraphValueStoreAdapter } from "../store/GraphValueStoreAdapter.d.cts";
+/**
+ * Configuration for the {@link GraphExecutionEngine}.
+ */
+export interface GraphExecutionEngineConfig {
+    registry: GraphNodeExecutorRegistry;
+    planner?: GraphExecutionPlanner;
+    valueStoreAdapter?: GraphValueStoreAdapter;
+    eventEmitter?: GraphExecutionEventEmitter;
+    defaultOptions?: Partial<GraphExecutionOptions>;
+}
+/**
+ * Reference graph execution engine.
+ *
+ * Executes a {@link GraphWorkflowDefinition} by:
+ * 1. Planning the workflow into topological layers.
+ * 2. Seeding workflow inputs into the value store.
+ * 3. Executing nodes layer-by-layer with configurable concurrency.
+ * 4. Routing values along edges.
+ * 5. Emitting structured events through Decaf's Observable pipeline.
+ * 6. Returning a complete {@link GraphExecutionResult}.
+ */
+export declare class GraphExecutionEngine implements Observable<[GraphExecutionObserver], [GraphExecutionEvent]> {
+    private readonly emitter;
+    private readonly planner;
+    private readonly valueStoreAdapter;
+    private readonly defaultOptions;
+    constructor(config: GraphExecutionEngineConfig);
+    private readonly config;
+    observe(observer: GraphExecutionObserver): () => void;
+    unObserve(observer: GraphExecutionObserver): void;
+    updateObservers(event: GraphExecutionEvent): Promise<void>;
+    /**
+     * Executes a workflow with the given inputs and options.
+     */
+    execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+    /**
+     * Pins a node and its upstream dependencies after a completed run.
+     *
+     * Delegates to {@link GraphPinningService}. The plan and result must come
+     * from a prior successful execution of the same workflow.
+     */
+    pinNode(options: GraphPinNodeOptions): Promise<void>;
+    /**
+     * Unpins a node by its fingerprint.
+     */
+    unpinNode(options: GraphUnpinNodeOptions): Promise<void>;
+    /**
+     * Creates a {@link GraphPinningService} backed by this engine's value store
+     * adapter.
+     */
+    private createPinningService;
+    /**
+     * Emits a pinning-related event to all observers.
+     */
+    private emitPinningEvent;
+    /**
+     * Executes a layer of nodes with the configured concurrency.
+     */
+    private executeLayer;
+    /**
+     * Executes a single node.
+     */
+    private executeNode;
+    /**
+     * Resolves a node's input values from incoming edges.
+     */
+    private resolveNodeInputs;
+    /**
+     * Attempts to read a pinned value for the node. Returns the cached outputs
+     * when a valid pinned value exists, or `undefined` to proceed with normal
+     * execution.
+     */
+    private tryPinnedValue;
+    /**
+     * Recursively computes fingerprints for all upstream dependencies of a node
+     * using the results already accumulated in the frame.
+     */
+    private computeDependencyFingerprints;
+    /**
+     * Routes a node's outputs to downstream inputs and workflow outputs.
+     */
+    private routeOutgoingEdges;
+    /**
+     * Emits an event, records it in the frame, and dispatches to observers.
+     */
+    private emitEvent;
+    /**
+     * Merges default options with the given options.
+     */
+    private mergeOptions;
+    /**
+     * Generates a unique run id.
+     */
+    private generateRunId;
+    /**
+     * Converts an error into a serialized payload.
+     */
+    private toErrorPayload;
+}

package/lib/types/graph/execution/GraphExecutionEngine.d.mts

@@ -0,0 +1,112 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionEngine
+ * @summary Reference graph execution engine.
+ * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result.
+ */
+import type { Observable } from "@decaf-ts/core";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEvent, GraphExecutionOptions, GraphExecutionResult, GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.mts";
+import type { GraphExecutionObserver } from "../events/GraphExecutionObserver.d.mts";
+import { GraphExecutionEventEmitter } from "../events/GraphExecutionEventEmitter.d.mts";
+import type { GraphNodeExecutorRegistry } from "../registry/GraphNodeExecutorRegistry.d.mts";
+import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.mts";
+import type { GraphValueStoreAdapter } from "../store/GraphValueStoreAdapter.d.mts";
+/**
+ * Configuration for the {@link GraphExecutionEngine}.
+ */
+export interface GraphExecutionEngineConfig {
+    registry: GraphNodeExecutorRegistry;
+    planner?: GraphExecutionPlanner;
+    valueStoreAdapter?: GraphValueStoreAdapter;
+    eventEmitter?: GraphExecutionEventEmitter;
+    defaultOptions?: Partial<GraphExecutionOptions>;
+}
+/**
+ * Reference graph execution engine.
+ *
+ * Executes a {@link GraphWorkflowDefinition} by:
+ * 1. Planning the workflow into topological layers.
+ * 2. Seeding workflow inputs into the value store.
+ * 3. Executing nodes layer-by-layer with configurable concurrency.
+ * 4. Routing values along edges.
+ * 5. Emitting structured events through Decaf's Observable pipeline.
+ * 6. Returning a complete {@link GraphExecutionResult}.
+ */
+export declare class GraphExecutionEngine implements Observable<[GraphExecutionObserver], [GraphExecutionEvent]> {
+    private readonly emitter;
+    private readonly planner;
+    private readonly valueStoreAdapter;
+    private readonly defaultOptions;
+    constructor(config: GraphExecutionEngineConfig);
+    private readonly config;
+    observe(observer: GraphExecutionObserver): () => void;
+    unObserve(observer: GraphExecutionObserver): void;
+    updateObservers(event: GraphExecutionEvent): Promise<void>;
+    /**
+     * Executes a workflow with the given inputs and options.
+     */
+    execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+    /**
+     * Pins a node and its upstream dependencies after a completed run.
+     *
+     * Delegates to {@link GraphPinningService}. The plan and result must come
+     * from a prior successful execution of the same workflow.
+     */
+    pinNode(options: GraphPinNodeOptions): Promise<void>;
+    /**
+     * Unpins a node by its fingerprint.
+     */
+    unpinNode(options: GraphUnpinNodeOptions): Promise<void>;
+    /**
+     * Creates a {@link GraphPinningService} backed by this engine's value store
+     * adapter.
+     */
+    private createPinningService;
+    /**
+     * Emits a pinning-related event to all observers.
+     */
+    private emitPinningEvent;
+    /**
+     * Executes a layer of nodes with the configured concurrency.
+     */
+    private executeLayer;
+    /**
+     * Executes a single node.
+     */
+    private executeNode;
+    /**
+     * Resolves a node's input values from incoming edges.
+     */
+    private resolveNodeInputs;
+    /**
+     * Attempts to read a pinned value for the node. Returns the cached outputs
+     * when a valid pinned value exists, or `undefined` to proceed with normal
+     * execution.
+     */
+    private tryPinnedValue;
+    /**
+     * Recursively computes fingerprints for all upstream dependencies of a node
+     * using the results already accumulated in the frame.
+     */
+    private computeDependencyFingerprints;
+    /**
+     * Routes a node's outputs to downstream inputs and workflow outputs.
+     */
+    private routeOutgoingEdges;
+    /**
+     * Emits an event, records it in the frame, and dispatches to observers.
+     */
+    private emitEvent;
+    /**
+     * Merges default options with the given options.
+     */
+    private mergeOptions;
+    /**
+     * Generates a unique run id.
+     */
+    private generateRunId;
+    /**
+     * Converts an error into a serialized payload.
+     */
+    private toErrorPayload;
+}

package/lib/types/graph/execution/GraphExecutionFrame.d.cts

@@ -0,0 +1,29 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionFrame
+ * @summary Per-run state container for graph execution.
+ * @description Holds the run id, execution plan, value store, accumulated node results, events, and timing for a single workflow execution.
+ */
+import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.cts";
+import type { GraphValueStore } from "../store/GraphValueStore.d.cts";
+import type { GraphExecutionEventFactory } from "../events/GraphExecutionEventFactory.d.cts";
+import type { GraphExecutionEvent, GraphNodeExecutionResult, GraphRunId } from "../types.d.cts";
+/**
+ * Mutable state for a single graph execution run.
+ */
+export declare class GraphExecutionFrame {
+    readonly runId: GraphRunId;
+    readonly plan: GraphExecutionPlan;
+    readonly valueStore: GraphValueStore;
+    readonly eventFactory: GraphExecutionEventFactory;
+    readonly startedAt: Date;
+    readonly nodeResults: Map<string, GraphNodeExecutionResult>;
+    readonly events: GraphExecutionEvent[];
+    finishedAt?: Date;
+    constructor(runId: GraphRunId, plan: GraphExecutionPlan, valueStore: GraphValueStore, eventFactory: GraphExecutionEventFactory);
+    /** Records a node execution result. */
+    recordNodeResult(result: GraphNodeExecutionResult): void;
+    /** Appends an event to the run's event log. */
+    appendEvent(event: GraphExecutionEvent): void;
+    /** Marks the run as finished. */
+    finish(): void;
+}

package/lib/types/graph/execution/GraphExecutionFrame.d.mts

@@ -0,0 +1,29 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionFrame
+ * @summary Per-run state container for graph execution.
+ * @description Holds the run id, execution plan, value store, accumulated node results, events, and timing for a single workflow execution.
+ */
+import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.mts";
+import type { GraphValueStore } from "../store/GraphValueStore.d.mts";
+import type { GraphExecutionEventFactory } from "../events/GraphExecutionEventFactory.d.mts";
+import type { GraphExecutionEvent, GraphNodeExecutionResult, GraphRunId } from "../types.d.mts";
+/**
+ * Mutable state for a single graph execution run.
+ */
+export declare class GraphExecutionFrame {
+    readonly runId: GraphRunId;
+    readonly plan: GraphExecutionPlan;
+    readonly valueStore: GraphValueStore;
+    readonly eventFactory: GraphExecutionEventFactory;
+    readonly startedAt: Date;
+    readonly nodeResults: Map<string, GraphNodeExecutionResult>;
+    readonly events: GraphExecutionEvent[];
+    finishedAt?: Date;
+    constructor(runId: GraphRunId, plan: GraphExecutionPlan, valueStore: GraphValueStore, eventFactory: GraphExecutionEventFactory);
+    /** Records a node execution result. */
+    recordNodeResult(result: GraphNodeExecutionResult): void;
+    /** Appends an event to the run's event log. */
+    appendEvent(event: GraphExecutionEvent): void;
+    /** Marks the run as finished. */
+    finish(): void;
+}

package/lib/types/graph/execution/GraphExecutionResult.d.cts

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionResult
+ * @summary Helper for building GraphExecutionResult objects.
+ * @description Provides a builder function that assembles a result from a frame.
+ */
+import type { GraphExecutionFrame } from "./GraphExecutionFrame.d.cts";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.cts";
+import type { GraphExecutionStatus } from "../constants.d.cts";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Builds a {@link GraphExecutionResult} from a completed frame.
+ */
+export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, workflow: GraphWorkflowDefinition, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;

package/lib/types/graph/execution/GraphExecutionResult.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/graph/execution/GraphExecutionResult
+ * @summary Helper for building GraphExecutionResult objects.
+ * @description Provides a builder function that assembles a result from a frame.
+ */
+import type { GraphExecutionFrame } from "./GraphExecutionFrame.d.mts";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
+import type { GraphExecutionStatus } from "../constants.d.mts";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Builds a {@link GraphExecutionResult} from a completed frame.
+ */
+export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, workflow: GraphWorkflowDefinition, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;

package/lib/types/graph/execution/GraphNodeExecutor.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/execution/GraphNodeExecutor
+ * @summary Interface implemented by every graph node executor.
+ * @description A node executor receives the node's resolved input values and a {@link GraphExecutionContext}, and returns the node's output values.
+ */
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for a specific graph node kind.
+ *
+ * Implementations are registered in the {@link GraphNodeExecutorRegistry}
+ * and resolved by the engine using the node's `kind`.
+ */
+export interface GraphNodeExecutor<Input extends GraphExecutionValues = GraphExecutionValues, Output extends GraphExecutionValues = GraphExecutionValues> {
+    /**
+     * Executes the node logic.
+     *
+     * @param input - Resolved input values keyed by port name.
+     * @param context - Decaf context for emitting progress and events.
+     * @returns The node's output values keyed by port name.
+     */
+    execute(input: Input, context: GraphExecutionContext): Promise<Output> | Output;
+}

package/lib/types/graph/execution/GraphNodeExecutor.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/execution/GraphNodeExecutor
+ * @summary Interface implemented by every graph node executor.
+ * @description A node executor receives the node's resolved input values and a {@link GraphExecutionContext}, and returns the node's output values.
+ */
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for a specific graph node kind.
+ *
+ * Implementations are registered in the {@link GraphNodeExecutorRegistry}
+ * and resolved by the engine using the node's `kind`.
+ */
+export interface GraphNodeExecutor<Input extends GraphExecutionValues = GraphExecutionValues, Output extends GraphExecutionValues = GraphExecutionValues> {
+    /**
+     * Executes the node logic.
+     *
+     * @param input - Resolved input values keyed by port name.
+     * @param context - Decaf context for emitting progress and events.
+     * @returns The node's output values keyed by port name.
+     */
+    execute(input: Input, context: GraphExecutionContext): Promise<Output> | Output;
+}

package/lib/types/graph/execution/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/execution
+ * @summary Graph execution context and executor interface.
+ * @description Re-exports the graph execution context and node executor interface.
+ */
+export * from "./GraphExecutionContext.d.cts";
+export * from "./GraphNodeExecutor.d.cts";
+export * from "./GraphExecutionResult.d.cts";
+export * from "./GraphExecutionFrame.d.cts";
+export * from "./GraphExecutionEngine.d.cts";

package/lib/types/graph/execution/index.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/execution
+ * @summary Graph execution context and executor interface.
+ * @description Re-exports the graph execution context and node executor interface.
+ */
+export * from "./GraphExecutionContext.d.mts";
+export * from "./GraphNodeExecutor.d.mts";
+export * from "./GraphExecutionResult.d.mts";
+export * from "./GraphExecutionFrame.d.mts";
+export * from "./GraphExecutionEngine.d.mts";

package/lib/types/graph/index.d.cts

@@ -0,0 +1,52 @@
+/**
+ * @module integrations/graph
+ * @summary Decaf Graph Execution Engine.
+ * @description Reference interpreter for Decaf graph workflows. Executes workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports structured loops, configurable value stores, and pinnable/cacheable nodes.
+ */
+export * from "./constants.d.cts";
+export * from "./types.d.cts";
+export * from "./decorators.d.cts";
+export * from "./errors/GraphExecutionError.d.cts";
+export * from "./errors/GraphCycleError.d.cts";
+export * from "./errors/GraphInputError.d.cts";
+export * from "./errors/GraphLoopLimitError.d.cts";
+export * from "./errors/GraphPinningError.d.cts";
+export * from "./errors/GraphPortError.d.cts";
+export * from "./errors/GraphStoreError.d.cts";
+export * from "./errors/GraphTopologyError.d.cts";
+export * from "./events/GraphExecutionEvent.d.cts";
+export * from "./events/GraphExecutionObserver.d.cts";
+export * from "./events/GraphExecutionEventEmitter.d.cts";
+export * from "./events/GraphExecutionEventFactory.d.cts";
+export * from "./execution/GraphExecutionContext.d.cts";
+export * from "./execution/GraphNodeExecutor.d.cts";
+export * from "./execution/GraphExecutionFrame.d.cts";
+export * from "./execution/GraphExecutionResult.d.cts";
+export * from "./execution/GraphExecutionEngine.d.cts";
+export * from "./registry/GraphNodeExecutorRegistry.d.cts";
+export * from "./registry/GraphNodeExecutorResolver.d.cts";
+export * from "./store/GraphValueKey.d.cts";
+export * from "./store/GraphCachedValue.d.cts";
+export * from "./store/GraphValueStoreAdapter.d.cts";
+export * from "./store/InMemoryGraphValueStoreAdapter.d.cts";
+export * from "./store/GraphValueStore.d.cts";
+export * from "./planning/GraphExecutionPlanNode.d.cts";
+export * from "./planning/GraphExecutionPlanEdge.d.cts";
+export * from "./planning/GraphExecutionPlanLayer.d.cts";
+export * from "./planning/GraphExecutionPlan.d.cts";
+export * from "./planning/GraphRelationResolver.d.cts";
+export * from "./planning/GraphExecutionPlanner.d.cts";
+export * from "./planning/GraphTopology.d.cts";
+export * from "./validation/GraphDefinitionValidator.d.cts";
+export * from "./validation/GraphPortSchemaResolver.d.cts";
+export * from "./validation/GraphValueValidator.d.cts";
+export * from "./loops/GraphConditionEvaluator.d.cts";
+export * from "./loops/GraphLoopExecutionContext.d.cts";
+export * from "./loops/ForeachGraphNodeExecutor.d.cts";
+export * from "./loops/WhileGraphNodeExecutor.d.cts";
+export * from "./loops/UntilGraphNodeExecutor.d.cts";
+export * from "./pinning/GraphPinningMetadata.d.cts";
+export * from "./pinning/GraphPinningPolicy.d.cts";
+export * from "./pinning/GraphPinningDependencyResolver.d.cts";
+export * from "./pinning/GraphPinningService.d.cts";
+export * from "./snapshots/GraphExecutionSnapshotMapper.d.cts";