@decaf-ts/integrations 0.3.1 → 0.3.2

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";

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

@@ -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.mts";
+export * from "./types.d.mts";
+export * from "./decorators.d.mts";
+export * from "./errors/GraphExecutionError.d.mts";
+export * from "./errors/GraphCycleError.d.mts";
+export * from "./errors/GraphInputError.d.mts";
+export * from "./errors/GraphLoopLimitError.d.mts";
+export * from "./errors/GraphPinningError.d.mts";
+export * from "./errors/GraphPortError.d.mts";
+export * from "./errors/GraphStoreError.d.mts";
+export * from "./errors/GraphTopologyError.d.mts";
+export * from "./events/GraphExecutionEvent.d.mts";
+export * from "./events/GraphExecutionObserver.d.mts";
+export * from "./events/GraphExecutionEventEmitter.d.mts";
+export * from "./events/GraphExecutionEventFactory.d.mts";
+export * from "./execution/GraphExecutionContext.d.mts";
+export * from "./execution/GraphNodeExecutor.d.mts";
+export * from "./execution/GraphExecutionFrame.d.mts";
+export * from "./execution/GraphExecutionResult.d.mts";
+export * from "./execution/GraphExecutionEngine.d.mts";
+export * from "./registry/GraphNodeExecutorRegistry.d.mts";
+export * from "./registry/GraphNodeExecutorResolver.d.mts";
+export * from "./store/GraphValueKey.d.mts";
+export * from "./store/GraphCachedValue.d.mts";
+export * from "./store/GraphValueStoreAdapter.d.mts";
+export * from "./store/InMemoryGraphValueStoreAdapter.d.mts";
+export * from "./store/GraphValueStore.d.mts";
+export * from "./planning/GraphExecutionPlanNode.d.mts";
+export * from "./planning/GraphExecutionPlanEdge.d.mts";
+export * from "./planning/GraphExecutionPlanLayer.d.mts";
+export * from "./planning/GraphExecutionPlan.d.mts";
+export * from "./planning/GraphRelationResolver.d.mts";
+export * from "./planning/GraphExecutionPlanner.d.mts";
+export * from "./planning/GraphTopology.d.mts";
+export * from "./validation/GraphDefinitionValidator.d.mts";
+export * from "./validation/GraphPortSchemaResolver.d.mts";
+export * from "./validation/GraphValueValidator.d.mts";
+export * from "./loops/GraphConditionEvaluator.d.mts";
+export * from "./loops/GraphLoopExecutionContext.d.mts";
+export * from "./loops/ForeachGraphNodeExecutor.d.mts";
+export * from "./loops/WhileGraphNodeExecutor.d.mts";
+export * from "./loops/UntilGraphNodeExecutor.d.mts";
+export * from "./pinning/GraphPinningMetadata.d.mts";
+export * from "./pinning/GraphPinningPolicy.d.mts";
+export * from "./pinning/GraphPinningDependencyResolver.d.mts";
+export * from "./pinning/GraphPinningService.d.mts";
+export * from "./snapshots/GraphExecutionSnapshotMapper.d.mts";

package/lib/types/graph/loops/ForeachGraphNodeExecutor.d.cts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/loops/ForeachGraphNodeExecutor
+ * @summary Foreach loop node executor.
+ * @description Executes a body workflow once per item in the input array, collecting results in order.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.foreach` nodes.
+ *
+ * Expects input:
+ * - `items`: array of values to iterate over
+ * - `state?`: optional initial state
+ *
+ * Produces output:
+ * - `results`: array of body outputs (in item order)
+ * - `state?`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class ForeachGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/ForeachGraphNodeExecutor.d.mts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/loops/ForeachGraphNodeExecutor
+ * @summary Foreach loop node executor.
+ * @description Executes a body workflow once per item in the input array, collecting results in order.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.foreach` nodes.
+ *
+ * Expects input:
+ * - `items`: array of values to iterate over
+ * - `state?`: optional initial state
+ *
+ * Produces output:
+ * - `results`: array of body outputs (in item order)
+ * - `state?`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class ForeachGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/GraphConditionEvaluator.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/loops/GraphConditionEvaluator
+ * @summary Evaluator for built-in loop condition types.
+ * @description Supports safe, built-in condition types only. Does NOT evaluate arbitrary JavaScript expressions.
+ */
+import type { GraphConditionDefinition } from "../types.d.cts";
+/**
+ * Evaluates loop conditions using built-in comparison types.
+ */
+export declare class GraphConditionEvaluator {
+    /**
+     * Evaluates a condition against the given state.
+     *
+     * @param condition - The condition definition.
+     * @param state - The current loop state.
+     * @returns `true` when the condition passes.
+     */
+    evaluate(condition: GraphConditionDefinition, state: unknown): boolean;
+    /**
+     * Resolves a value that may be a dotted path into the state object.
+     */
+    private resolveValue;
+}

package/lib/types/graph/loops/GraphConditionEvaluator.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/loops/GraphConditionEvaluator
+ * @summary Evaluator for built-in loop condition types.
+ * @description Supports safe, built-in condition types only. Does NOT evaluate arbitrary JavaScript expressions.
+ */
+import type { GraphConditionDefinition } from "../types.d.mts";
+/**
+ * Evaluates loop conditions using built-in comparison types.
+ */
+export declare class GraphConditionEvaluator {
+    /**
+     * Evaluates a condition against the given state.
+     *
+     * @param condition - The condition definition.
+     * @param state - The current loop state.
+     * @returns `true` when the condition passes.
+     */
+    evaluate(condition: GraphConditionDefinition, state: unknown): boolean;
+    /**
+     * Resolves a value that may be a dotted path into the state object.
+     */
+    private resolveValue;
+}

package/lib/types/graph/loops/GraphLoopExecutionContext.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/loops/GraphLoopExecutionContext
+ * @summary Context for loop node execution.
+ * @description Carries loop-specific metadata and iteration state during loop execution.
+ */
+import type { GraphLoopMetadata } from "../types.d.cts";
+/**
+ * Context for a single loop execution, carrying the loop metadata and
+ * current iteration index.
+ */
+export declare class GraphLoopExecutionContext {
+    readonly iteration: number;
+    readonly metadata: GraphLoopMetadata;
+    constructor(iteration: number, metadata: GraphLoopMetadata);
+}

package/lib/types/graph/loops/GraphLoopExecutionContext.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/loops/GraphLoopExecutionContext
+ * @summary Context for loop node execution.
+ * @description Carries loop-specific metadata and iteration state during loop execution.
+ */
+import type { GraphLoopMetadata } from "../types.d.mts";
+/**
+ * Context for a single loop execution, carrying the loop metadata and
+ * current iteration index.
+ */
+export declare class GraphLoopExecutionContext {
+    readonly iteration: number;
+    readonly metadata: GraphLoopMetadata;
+    constructor(iteration: number, metadata: GraphLoopMetadata);
+}

package/lib/types/graph/loops/UntilGraphNodeExecutor.d.cts

@@ -0,0 +1,22 @@
+/**
+ * @module integrations/graph/loops/UntilGraphNodeExecutor
+ * @summary Until loop node executor.
+ * @description Executes a body workflow at least once and repeats until a condition is true.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.until` nodes.
+ *
+ * Executes the body at least once, then checks the condition. Repeats until
+ * the condition evaluates to true.
+ */
+export declare class UntilGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/UntilGraphNodeExecutor.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @module integrations/graph/loops/UntilGraphNodeExecutor
+ * @summary Until loop node executor.
+ * @description Executes a body workflow at least once and repeats until a condition is true.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.until` nodes.
+ *
+ * Executes the body at least once, then checks the condition. Repeats until
+ * the condition evaluates to true.
+ */
+export declare class UntilGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/WhileGraphNodeExecutor.d.cts

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/graph/loops/WhileGraphNodeExecutor
+ * @summary While loop node executor.
+ * @description Executes a body workflow repeatedly while a condition is true, enforcing a maximum iteration limit.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.while` nodes.
+ *
+ * Expects input:
+ * - `state`: initial state
+ *
+ * Produces output:
+ * - `state`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class WhileGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/WhileGraphNodeExecutor.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/graph/loops/WhileGraphNodeExecutor
+ * @summary While loop node executor.
+ * @description Executes a body workflow repeatedly while a condition is true, enforcing a maximum iteration limit.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.while` nodes.
+ *
+ * Expects input:
+ * - `state`: initial state
+ *
+ * Produces output:
+ * - `state`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class WhileGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/loops
+ * @summary Structured loop executors.
+ * @description Re-exports the condition evaluator, loop execution context, and foreach/while/until executors.
+ */
+export * from "./GraphConditionEvaluator.d.cts";
+export * from "./GraphLoopExecutionContext.d.cts";
+export * from "./ForeachGraphNodeExecutor.d.cts";
+export * from "./WhileGraphNodeExecutor.d.cts";
+export * from "./UntilGraphNodeExecutor.d.cts";

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/loops
+ * @summary Structured loop executors.
+ * @description Re-exports the condition evaluator, loop execution context, and foreach/while/until executors.
+ */
+export * from "./GraphConditionEvaluator.d.mts";
+export * from "./GraphLoopExecutionContext.d.mts";
+export * from "./ForeachGraphNodeExecutor.d.mts";
+export * from "./WhileGraphNodeExecutor.d.mts";
+export * from "./UntilGraphNodeExecutor.d.mts";