@omega-flow/engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,997 @@
+import { Edge, Event, Node, Workflow, WorkflowHistoryItem, WorkflowStatus, Context } from '@omega-flow/types';
+
+/**
+ * Represents a connection (edge) between two nodes in a workflow graph.
+ *
+ * EdgeModel wraps the underlying Edge definition and provides methods
+ * to access source and target node information, as well as handle identifiers
+ * for connecting specific input/output ports on nodes.
+ */
+declare class EdgeModel {
+    /** The underlying edge definition from the workflow */
+    edge: Edge;
+    /**
+     * Creates a new EdgeModel instance.
+     * @param edge - The edge definition from the workflow
+     * @throws Error if edge is missing, has no id, or lacks source/target
+     */
+    constructor(edge: Edge);
+    /**
+     * Gets the unique identifier of this edge.
+     * @returns The edge's ID as a string
+     */
+    getId(): string;
+    /**
+     * Gets the ID of the source (origin) node.
+     * @returns The source node's ID as a string
+     */
+    getSourceNodeId(): string;
+    /**
+     * Gets the source handle identifier (output port).
+     * Handles allow nodes to have multiple outputs (e.g., "true"/"false" for conditions).
+     * @returns The source handle name, or "_" if not specified
+     */
+    getSourceHandle(): string;
+    /**
+     * Gets the ID of the target (destination) node.
+     * @returns The target node's ID as a string
+     */
+    getTargetNodeId(): string;
+    /**
+     * Gets the target handle identifier (input port).
+     * @returns The target handle name, or "_" if not specified
+     */
+    getTargetHandle(): string;
+}
+
+/**
+ * Represents a connection from a source node to a target node via an edge.
+ *
+ * Connections are stored on the source node and define which target node
+ * is reachable through a specific edge. This structure enables nodes to
+ * look up their outgoing connections and determine the next node in the workflow.
+ */
+type Connection = {
+    /** The destination node that this connection leads to */
+    targetNode: NodeModel;
+    /** The edge that defines this connection, including handle information */
+    edge: EdgeModel;
+};
+
+/**
+ * Minimal interface for WorkflowManager used by schedulers.
+ * This forward declaration avoids circular dependency issues.
+ */
+interface IWorkflowManager {
+    /**
+     * Process an event through the workflow system.
+     * @param event - The event to process
+     */
+    processEvent(event: Event): Promise<void>;
+}
+/**
+ * Interface for scheduling future workflow events
+ * Used for timeouts, delays, and other time-based workflow events
+ */
+interface WorkflowScheduler {
+    /**
+     * Schedule an event to be delivered after a delay
+     * When the delay expires, the event will be passed to the workflow manager
+     * @param event - The event to schedule
+     * @param delayMs - Delay in milliseconds before the event is delivered
+     * @returns Promise resolving to a schedule ID that can be used to cancel the schedule
+     */
+    schedule(event: Event, delayMs: number): Promise<string>;
+    /**
+     * Cancel a scheduled event
+     * @param scheduleId - The ID of the schedule to cancel
+     * @returns Promise resolving to true if canceled, false if not found
+     */
+    cancel(scheduleId: string): Promise<boolean>;
+}
+
+interface NodeServices {
+    scheduler?: WorkflowScheduler;
+}
+
+/**
+ * Base class for all workflow node types.
+ *
+ * NodeModel represents a single step in a workflow graph. Each node can accept events,
+ * process them, and determine which node should be executed next. Subclasses must
+ * implement the `acceptEvent` and `nextNode` methods to define their specific behavior.
+ *
+ * When a workflow is on a node, that node is waiting for events (not yet processed).
+ * Processing happens when an event is accepted by the node.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomNode extends NodeModel {
+ *   async acceptEvent(event: Event): Promise<boolean> {
+ *     // Return true if event is accepted and processing is complete
+ *     return event.type === 'my-event';
+ *   }
+ *
+ *   async nextNode(event: Event): Promise<NodeModel | null> {
+ *     return this.getTargetNodeFromSourceHandle('output');
+ *   }
+ * }
+ * ```
+ */
+declare class NodeModel {
+    /**
+     * Factory method to create a new NodeModel instance.
+     * Subclasses should override this method to perform type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new NodeModel instance
+     */
+    static create(node: Node): NodeModel;
+    /** The underlying node definition from the workflow */
+    node: Node;
+    /** List of outgoing connections to other nodes */
+    connections: Connection[];
+    /** Internal state that persists across event processing. Use setState/getState to access. */
+    state: any;
+    /** Services available to nodes (scheduler, etc.) */
+    services: NodeServices;
+    /**
+     * Creates a new NodeModel instance.
+     * @param node - The node definition from the workflow
+     * @throws Error if node is missing or doesn't have an id
+     */
+    constructor(node: Node);
+    /**
+     * Gets the unique identifier of this node.
+     * @returns The node's ID as a string
+     */
+    getId(): string;
+    /**
+     * Gets the data payload associated with this node.
+     * This typically contains node-specific configuration like parameters.
+     * @returns The node's data object, or an empty object if not defined
+     */
+    getData(): any;
+    /**
+     * Checks if this node is equal to another node by comparing IDs.
+     * @param node - The node to compare against (can be null)
+     * @returns True if the nodes have the same ID, false otherwise
+     */
+    equals(node: NodeModel | null): boolean;
+    /**
+     * Gets the current internal state of the node.
+     * State is used to share data between `acceptEvent` and `nextNode` methods.
+     * @returns The current state object
+     */
+    getState(): any;
+    /**
+     * Replaces the entire internal state of the node.
+     * @param state - The new state object
+     */
+    setState(state: any): void;
+    /**
+     * Merges changes into the existing state (shallow merge).
+     * @param changes - Object containing state properties to update
+     */
+    updateState(changes: any): void;
+    /**
+     * Connects this node to a target node via an edge.
+     * This node becomes the source node of the connection.
+     * @param targetNode - The node to connect to
+     * @param edge - The edge defining the connection
+     * @throws Error if attempting to connect node to itself
+     * @throws Error if connection already exists with the same source handle
+     */
+    connect(targetNode: NodeModel, edge: EdgeModel): void;
+    /**
+     * Returns all outgoing connections from this node.
+     * @returns Array of Connection objects containing targetNode and edge
+     */
+    getConnections(): Connection[];
+    /**
+     * Returns all source handle identifiers (output labels) for this node.
+     * Source handles define the different output paths from this node.
+     * @returns Array of source handle strings
+     */
+    getSourceHandles(): string[];
+    /**
+     * Finds the target node connected to a specific source handle.
+     * @param sourceHandle - The source handle (output) identifier to look up
+     * @returns The connected NodeModel, or null if no connection exists for the handle
+     */
+    getTargetNodeFromSourceHandle(sourceHandle: string): NodeModel | null;
+    /**
+     * Returns the target node connected to the first source handle, or null
+     * if this node has no outgoing connections.
+     *
+     * Most pass-through nodes (single output) implement `nextNode` as
+     * `return this.getDefaultNext();`. Use it instead of repeating the
+     * `getSourceHandles()[0]` lookup by hand.
+     */
+    getDefaultNext(): NodeModel | null;
+    /**
+     * Accepts and processes an incoming event.
+     *
+     * This method must be overridden by subclasses to define how the node
+     * handles events. The method can be called multiple times for the same
+     * logical operation (e.g., start wait, then complete wait).
+     *
+     * @param event - The event to process
+     * @returns Promise resolving to true if event is accepted and processing is complete,
+     *          false if the node is still waiting or doesn't accept the event
+     * @throws Error if not implemented by subclass
+     */
+    acceptEvent(_event: Event): Promise<boolean>;
+    /**
+     * Determines the next node to execute after processing an event.
+     *
+     * This method must be overridden by subclasses. It is called after
+     * `acceptEvent` returns true to determine where the workflow should go next.
+     *
+     * @param event - The event that was processed
+     * @returns Promise resolving to the next NodeModel to execute,
+     *          or null if the workflow should end
+     * @throws Error if not implemented by subclass
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Core workflow execution engine that manages the lifecycle of a single workflow instance.
+ *
+ * WorkflowModel takes a workflow definition (graph of nodes and edges) and executes it
+ * by processing events and moving through nodes. It maintains execution state including
+ * the current node, history, and node-specific state.
+ *
+ * Workflow execution follows this model:
+ * 1. Workflow starts in `idle` status
+ * 2. After `start()` is called, status becomes `waiting`
+ * 3. When an event arrives via `acceptEvent()`:
+ *    - If current node accepts the event, status becomes `processing`
+ *    - After determining next node, status becomes `transforming`
+ *    - Once moved to next node, status returns to `waiting`
+ *    - Process repeats recursively until node doesn't accept the event
+ * 4. When workflow reaches an exit node, status becomes `completed`
+ *
+ * @example
+ * ```typescript
+ * const workflow = new WorkflowModel(workflowDef, nodeModels);
+ * workflow.start();
+ * await workflow.acceptEvent({ type: 'trigger', time: Date.now(), data: {} });
+ * const context = workflow.getContext(); // Save for later resumption
+ * ```
+ */
+declare class WorkflowModel {
+    #private;
+    /** The workflow definition containing metadata, flow (nodes/edges), and options */
+    workflow: Workflow;
+    /** Array of instantiated node models for this workflow */
+    nodes: NodeModel[];
+    /** Array of edge models connecting the nodes */
+    edges: EdgeModel[];
+    /** The node currently waiting for events (null before start or after completion) */
+    currentNode: NodeModel | null;
+    /** Execution history recording workflow transitions */
+    history: WorkflowHistoryItem[];
+    /** Current execution status of the workflow */
+    status: WorkflowStatus;
+    /** Unique identifier for this workflow instance */
+    instanceId: string;
+    /** Unix timestamp (ms) when this workflow instance was started */
+    startedAt: number;
+    /**
+     * Creates a new WorkflowModel instance from a workflow definition.
+     * @param workflow - The workflow definition to execute
+     * @param nodeModels - Map of node type names to their NodeModel classes
+     * @throws Error if workflow is invalid or missing required nodes
+     */
+    constructor(workflow: Workflow, nodeModels: Record<string, typeof NodeModel>, services?: NodeServices);
+    /**
+     * Restores workflow state from a previously saved context.
+     * Use this to resume a workflow that was interrupted or to restore from persistence.
+     * After calling setContext, you must call start() to begin processing events.
+     * @param context - The context to restore from
+     * @throws Error if workflow is already running
+     * @throws Error if context is invalid or doesn't match this workflow
+     * @throws Error if the current node in context doesn't exist in the workflow
+     */
+    setContext(context: Context): void;
+    /**
+     * Exports the current workflow state as a Context object.
+     * The context contains all information needed to restore the workflow later.
+     * @returns A Context object containing workflow state
+     */
+    getContext(): Context;
+    /**
+     * Gets the current execution status of the workflow.
+     * @returns The current WorkflowStatus
+     */
+    getStatus(): WorkflowStatus;
+    /**
+     * Starts or resumes the workflow execution.
+     * If no context was set, starts from the beginning at the start node.
+     * If a context was set via setContext(), resumes from the saved position.
+     * @throws Error if workflow is already running or completed
+     * @throws Error if workflow has no start node
+     */
+    start(): void;
+    /**
+     * Processes an incoming event through the workflow.
+     *
+     * This is the main event processing method. It passes the event to the current node
+     * and handles workflow transitions. The method recursively processes the event through
+     * subsequent nodes until a node doesn't accept the event or the workflow completes.
+     *
+     * @param event - The event to process
+     * @throws Error if workflow is not in waiting status
+     * @throws Error if event is invalid
+     * @throws Error if current node is not set
+     */
+    acceptEvent(event: Event): Promise<void>;
+    /**
+     * Gets the current node that is waiting for events.
+     * @returns The current NodeModel
+     * @throws Error if workflow is not running (still idle)
+     */
+    getCurrentNode(): NodeModel | null;
+    /**
+     * Finds the start node of the workflow.
+     * The start node is the node with no incoming edges.
+     * @returns The start NodeModel, or null if not found
+     */
+    getStartNode(): NodeModel | null;
+    /**
+     * Finds a node by its ID.
+     * @param nodeId - The ID of the node to find (can be null)
+     * @returns The NodeModel if found, or null if not found or nodeId is null
+     */
+    getNode(nodeId: string | null): NodeModel | null;
+}
+
+/**
+ * Node that performs an action and immediately proceeds to the next node.
+ *
+ * ActionModel accepts all events unconditionally and moves to the next node.
+ * It represents a step in the workflow that performs some operation (defined
+ * in the node's data) and continues without waiting.
+ *
+ * This node type is useful for:
+ * - Sending notifications
+ * - Updating external systems
+ * - Logging or recording events
+ * - Any non-blocking operation
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "action-1",
+ *   "type": "Action",
+ *   "data": {
+ *     "action": "sendEmail",
+ *     "params": { "to": "user@example.com" }
+ *   }
+ * }
+ * ```
+ */
+declare class ActionModel extends NodeModel {
+    /**
+     * Creates a new ActionModel instance.
+     * @param node - The node definition from the workflow
+     */
+    constructor(node: Node);
+    /**
+     * Factory method to create an ActionModel with type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new ActionModel instance
+     * @throws Error if node type is not "Action"
+     */
+    static create(node: Node): ActionModel;
+    /**
+     * Accepts all events immediately.
+     * Actions don't filter events - they execute whenever reached.
+     * @param _event - The event being processed (unused)
+     * @returns Always returns true (event accepted)
+     */
+    acceptEvent(_event: Event): Promise<boolean>;
+    /**
+     * Returns the next node connected to this action's output.
+     * @param _event - The event being processed (unused)
+     * @returns The next NodeModel, or null if no connection exists
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Node that evaluates conditions and routes to different paths based on the result.
+ *
+ * The conditions are configured in the node's data.conditions field using the
+ * shared `Conditions` format: top-level OR between groups, each group is AND
+ * (`all`) or OR (`any`) of leaf rules. The same shape is produced by the
+ * editor's visual condition builder, so no conversion is needed at runtime.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "condition-1",
+ *   "type": "Condition",
+ *   "data": {
+ *     "conditions": {
+ *       "groups": [
+ *         {
+ *           "operator": "all",
+ *           "conditions": [
+ *             { "fact": "amount", "operator": "greaterThan", "value": 100 }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class ConditionModel extends NodeModel {
+    constructor(node: Node);
+    /**
+     * Factory method to create a ConditionModel with type validation.
+     */
+    static create(node: Node): ConditionModel;
+    /**
+     * Evaluates the condition against the event data using the built-in
+     * evaluator. The result is stored in state for use by nextNode().
+     */
+    acceptEvent(event: Event): Promise<boolean>;
+    /**
+     * Routes to "true" handle if condition passed, "false" handle otherwise.
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Node that terminates the workflow execution.
+ *
+ * ExitModel accepts all events and returns null from nextNode(), which signals
+ * to the WorkflowModel that the workflow should be marked as completed.
+ * Every workflow should have at least one exit node to properly terminate.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "exit-1",
+ *   "type": "Exit",
+ *   "data": {}
+ * }
+ * ```
+ */
+declare class ExitModel extends NodeModel {
+    /**
+     * Creates a new ExitModel instance.
+     * @param node - The node definition from the workflow
+     */
+    constructor(node: Node);
+    /**
+     * Factory method to create an ExitModel with type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new ExitModel instance
+     * @throws Error if node type is not "Exit"
+     */
+    static create(node: Node): ExitModel;
+    /**
+     * Accepts all events immediately.
+     * Exit nodes don't filter events - they terminate whenever reached.
+     * @param _event - The event being processed (unused)
+     * @returns Always returns true (event accepted)
+     */
+    acceptEvent(_event: Event): Promise<boolean>;
+    /**
+     * Always returns null to signal workflow termination.
+     * @param _event - The event being processed (unused)
+     * @returns Always null, signaling workflow completion
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Node that waits for a specific event type before proceeding.
+ *
+ * TriggerModel acts as a start node or checkpoint in a workflow that only
+ * accepts events matching the configured event type. This allows workflows
+ * to be triggered by specific events from external systems.
+ *
+ * The trigger event type is configured in the node's data.params.event field.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "trigger-1",
+ *   "type": "Trigger",
+ *   "data": {
+ *     "params": { "event": "order_placed" }
+ *   }
+ * }
+ * ```
+ */
+declare class TriggerModel extends NodeModel {
+    /**
+     * Creates a new TriggerModel instance.
+     * @param node - The node definition from the workflow
+     */
+    constructor(node: Node);
+    /**
+     * Factory method to create a TriggerModel with type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new TriggerModel instance
+     * @throws Error if node type is not "Trigger"
+     */
+    static create(node: Node): TriggerModel;
+    /**
+     * Accepts events that match the configured trigger event type.
+     * @param event - The event being processed
+     * @returns True if event.type matches the configured params.event, false otherwise
+     */
+    acceptEvent(event: Event): Promise<boolean>;
+    /**
+     * Returns the next node connected to this trigger's output.
+     * @param _event - The event being processed (unused)
+     * @returns The next NodeModel, or null if no connection exists
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Node that pauses workflow execution for a specified duration.
+ *
+ * WaitModel implements a time-based delay in the workflow. On the first event,
+ * it starts waiting and returns false (not accepted). Subsequent events check
+ * if the wait duration has elapsed. Once complete, the node accepts the event
+ * and proceeds to the next node.
+ *
+ * The wait duration is configured in the node's data.params.duration field
+ * (in milliseconds).
+ *
+ * State tracking:
+ * - `waitStartsAt`: Timestamp when waiting began
+ * - `waitEndsAt`: Timestamp when waiting completed
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "wait-1",
+ *   "type": "Wait",
+ *   "data": {
+ *     "params": { "duration": 60000 }
+ *   }
+ * }
+ * ```
+ */
+declare class WaitModel extends NodeModel {
+    /**
+     * Creates a new WaitModel instance.
+     * @param node - The node definition from the workflow
+     */
+    constructor(node: Node);
+    /**
+     * Factory method to create a WaitModel with type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new WaitModel instance
+     * @throws Error if node type is not "Wait"
+     */
+    static create(node: Node): WaitModel;
+    /**
+     * Checks if the node is currently in a waiting state.
+     * @returns True if waiting has been started but not completed
+     */
+    isWaiting(): boolean;
+    /**
+     * Starts the waiting period by recording the start time and scheduling a timeout event.
+     * @param time - The timestamp when waiting begins (usually event.time)
+     * @param eventData - Optional event data to include in the scheduled timeout (for routing)
+     */
+    startWaiting(time: number, eventData?: any): Promise<void>;
+    /**
+     * Stops the waiting period by recording the end time.
+     * @param time - The timestamp when waiting ends
+     */
+    stopWaiting(time: number): void;
+    /**
+     * Checks if the configured wait duration has elapsed.
+     * @param currentTime - The current timestamp to check against
+     * @returns True if waiting and the duration has passed, false otherwise
+     */
+    isWaitComplete(currentTime: number): boolean;
+    /**
+     * Processes events during the waiting period.
+     * - First event: Starts waiting and returns false
+     * - Subsequent events: Checks if wait is complete
+     *   - If complete: Stops waiting and returns true
+     *   - If not complete: Returns false (still waiting)
+     * @param event - The event being processed
+     * @returns True if wait is complete and event is accepted, false if still waiting
+     */
+    acceptEvent(event: Event): Promise<boolean>;
+    /**
+     * Returns the next node connected to this wait node's output.
+     * @param _event - The event being processed (unused)
+     * @returns The next NodeModel, or null if no connection exists
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+/**
+ * Node that waits for either a specific event or a timeout, whichever comes first.
+ *
+ * TriggerOrTimeoutModel extends WaitModel to add event-based triggering.
+ * It will proceed when either:
+ * 1. A matching event arrives (configured in params.event) — routes via the `trigger` source handle
+ * 2. The timeout duration elapses (configured in params.duration) — routes via the `timeout` source handle
+ *
+ * This is useful for scenarios like:
+ * - "Wait for payment confirmation or timeout after 24 hours"
+ * - "Wait for user action or proceed automatically after delay"
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "trigger-or-timeout-1",
+ *   "type": "TriggerOrTimeout",
+ *   "data": {
+ *     "params": {
+ *       "event": "payment_received",
+ *       "duration": 86400000
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class TriggerOrTimeoutModel extends WaitModel {
+    /**
+     * Creates a new TriggerOrTimeoutModel instance.
+     * @param node - The node definition from the workflow
+     */
+    constructor(node: Node);
+    /**
+     * Factory method to create a TriggerOrTimeoutModel with type validation.
+     * @param node - The node definition from the workflow
+     * @returns A new TriggerOrTimeoutModel instance
+     * @throws Error if node type is not "TriggerOrTimeout"
+     */
+    static create(node: Node): TriggerOrTimeoutModel;
+    /**
+     * Processes events, accepting either a matching trigger event or timeout completion.
+     * - If event type matches params.event: Records `resolvedBy: "trigger"` and accepts
+     * - If already waiting and timeout elapsed: Records `resolvedBy: "timeout"` and accepts
+     * - If not waiting: Starts waiting and returns false
+     * @param event - The event being processed
+     * @returns True if event matches trigger or timeout completed, false if still waiting
+     */
+    acceptEvent(event: Event): Promise<boolean>;
+    /**
+     * Routes execution to the `trigger` source handle if the matching event
+     * resolved the wait, or the `timeout` source handle if the duration elapsed.
+     * @param _event - The event being processed (unused)
+     * @returns The next NodeModel, or null if no connection exists for the resolved handle
+     */
+    nextNode(_event: Event): Promise<NodeModel | null>;
+}
+
+declare const _default: {
+    Action: typeof ActionModel;
+    Condition: typeof ConditionModel;
+    Exit: typeof ExitModel;
+    Trigger: typeof TriggerModel;
+    Wait: typeof WaitModel;
+    TriggerOrTimeout: typeof TriggerOrTimeoutModel;
+};
+
+/**
+ * Interface for workflow storage backend
+ * Responsible for loading workflow definitions
+ */
+interface WorkflowStore {
+    /**
+     * Retrieve a workflow definition by its ID
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow
+     * @returns Promise resolving to the workflow definition, or null if not found
+     */
+    getWorkflow(domain: string, workflowId: string): Promise<Workflow | null>;
+    /**
+     * Get all workflow definitions in the store
+     * @returns Promise resolving to an array of all workflows
+     */
+    getAllWorkflows(domain: string): Promise<Workflow[]>;
+}
+
+/**
+ * Interface for workflow context storage backend
+ * Responsible for persisting and retrieving workflow execution state for each subject
+ */
+interface WorkflowMemory {
+    /**
+     * Retrieve all workflow contexts for a specific subject in a domain
+     * Supports multiple concurrent instances of the same workflow for a subject
+     * @param domain - The domain identifier (tenant, organization, etc.)
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject (user, order, device, etc.)
+     * @returns Promise resolving to an array of contexts (empty if none found)
+     */
+    getContexts(domain: string, workflowId: string, subjectId: string): Promise<Context[]>;
+    /**
+     * Save workflow context for a specific subject in a domain
+     * @param domain - The domain identifier (tenant, organization, etc.)
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject
+     * @param context - The context to save (identified by context.instanceId)
+     */
+    saveContext(domain: string, workflowId: string, subjectId: string, context: Context): Promise<void>;
+    /**
+     * Delete workflow context for a specific subject and instance in a domain
+     * @param domain - The domain identifier (tenant, organization, etc.)
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject
+     * @param instanceId - The unique identifier of the workflow instance
+     */
+    deleteContext(domain: string, workflowId: string, subjectId: string, instanceId: string): Promise<void>;
+}
+
+/**
+ * Constructor type for a NodeModel subclass.
+ * Re-exported from `@omega-flow/engine` as `NodeModelClass`.
+ */
+type NodeModelClass = typeof NodeModel;
+/**
+ * Map of node type names to their NodeModel classes.
+ * Re-exported from `@omega-flow/engine` as `NodeModelRegistry`.
+ */
+type NodeModelRegistry = Record<string, NodeModelClass>;
+/**
+ * Configuration options for WorkflowManager.
+ */
+interface WorkflowManagerConfig {
+    /** Storage backend for workflow definitions */
+    workflowStore: WorkflowStore;
+    /** Storage backend for workflow execution contexts */
+    workflowMemory: WorkflowMemory;
+    /** Scheduler for time-based workflow events */
+    workflowScheduler: WorkflowScheduler;
+    /** Map of node type names to their NodeModel classes */
+    nodeModels: NodeModelRegistry;
+    /**
+     * Function to extract domain and subject ID from an event.
+     * The domain allows multi-tenant workflow isolation.
+     * The subject ID identifies which entity (user, order, etc.) the workflow is for.
+     * @param event - The incoming event
+     * @returns Tuple of [domain, subjectId]
+     */
+    eventExtractor: (event: Event) => [string, string];
+}
+/**
+ * Orchestrates multiple workflows across multiple subjects and domains.
+ *
+ * WorkflowManager is the top-level coordinator that:
+ * - Routes incoming events to the appropriate workflow instances
+ * - Manages workflow lifecycle (start, resume, complete)
+ * - Handles state persistence via WorkflowMemory
+ * - Enforces workflow frequency rules (one_time, every_rematch)
+ *
+ * Each combination of (domain, workflowId, subjectId) can have multiple
+ * workflow instances depending on the frequency configuration.
+ *
+ * @example
+ * ```typescript
+ * const manager = new WorkflowManager({
+ *   workflowStore: new InMemoryWorkflowStore([...]),
+ *   workflowMemory: new InMemoryWorkflowMemory(),
+ *   workflowScheduler: new InMemoryWorkflowScheduler(),
+ *   nodeModels: { Trigger: TriggerModel, Action: ActionModel, Exit: ExitModel },
+ *   eventExtractor: (event) => [event.data.domain, event.data.userId],
+ * });
+ *
+ * await manager.processEvent({ type: 'user_signup', time: Date.now(), data: {...} });
+ * ```
+ */
+declare class WorkflowManager {
+    /** Storage backend for workflow definitions */
+    private workflowStore;
+    /** Storage backend for workflow execution contexts */
+    private workflowMemory;
+    /** Scheduler for time-based workflow events */
+    private workflowScheduler;
+    /** Map of node type names to their NodeModel classes */
+    private nodeModels;
+    /** Function to extract domain and subject ID from events */
+    private eventExtractor;
+    /**
+     * Creates a new WorkflowManager instance.
+     * @param config - Configuration options including storage backends and node models
+     */
+    constructor(config: WorkflowManagerConfig);
+    /**
+     * Process an event by routing it to appropriate workflow instances
+     * @param event - The event to process
+     */
+    processEvent(event: Event): Promise<void>;
+    /**
+     * Process a specific workflow definition for an event
+     * @param workflowDef - The workflow definition
+     * @param event - The event to process
+     * @param domain - The domain identifier
+     * @param subjectId - The subject ID extracted from the event
+     */
+    private processWorkflowForEvent;
+    /**
+     * Check if a new workflow instance can be started based on frequency option
+     * @param workflowDef - The workflow definition
+     * @param activeContexts - Currently active workflow instances
+     * @param completedContexts - Completed workflow instances
+     * @returns true if a new instance can be started
+     */
+    private canStartNewInstance;
+    /**
+     * Try to start a new workflow instance for a subject
+     * Only saves context if the workflow actually started (start node accepted the event)
+     * @param workflowDef - The workflow definition
+     * @param event - The triggering event
+     * @param domain - The domain identifier
+     * @param subjectId - The subject ID
+     */
+    private tryStartNewWorkflowInstance;
+    /**
+     * Resume an existing workflow instance and process an event
+     * @param workflowDef - The workflow definition
+     * @param context - The existing context
+     * @param event - The event to process
+     * @param domain - The domain identifier
+     * @param subjectId - The subject ID
+     */
+    private resumeWorkflowInstance;
+    /**
+     * Get the workflow scheduler instance
+     * Useful for nodes that need to schedule future events
+     * @returns The workflow scheduler
+     */
+    getScheduler(): WorkflowScheduler;
+}
+
+/**
+ * In-memory implementation of WorkflowStore.
+ *
+ * Stores workflow definitions in memory using a nested Map structure.
+ * Useful for testing, development, and single-instance deployments.
+ *
+ * Storage structure: domain -> workflowId -> Workflow
+ */
+declare class InMemoryWorkflowStore implements WorkflowStore {
+    /** Nested map storing workflows by domain and workflow ID */
+    private workflows;
+    /**
+     * Creates a new InMemoryWorkflowStore.
+     * @param workflows - Optional array of workflows to initialize the store with
+     */
+    constructor(workflows?: Array<{
+        domain: string;
+        workflow: Workflow;
+    }>);
+    /**
+     * Retrieve a workflow definition by its ID
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow
+     * @returns Promise resolving to the workflow definition, or null if not found
+     */
+    getWorkflow(domain: string, workflowId: string): Promise<Workflow | null>;
+    /**
+     * Add or update a workflow definition in the store
+     * @param domain - The domain identifier
+     * @param workflow - The workflow definition to add or update
+     */
+    setWorkflow(domain: string, workflow: Workflow): Promise<void>;
+    /**
+     * Remove a workflow definition from the store
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow to remove
+     */
+    deleteWorkflow(domain: string, workflowId: string): Promise<void>;
+    /**
+     * Get all workflow definitions in the store for a specific domain
+     * @param domain - The domain identifier
+     * @returns Promise resolving to an array of all workflows in the domain
+     */
+    getAllWorkflows(domain: string): Promise<Workflow[]>;
+}
+
+/**
+ * In-memory implementation of WorkflowMemory.
+ *
+ * Stores workflow execution contexts in memory using a nested Map structure.
+ * Useful for testing, development, and single-instance deployments.
+ *
+ * Storage structure: domain -> workflowId -> subjectId -> instanceId -> Context
+ */
+declare class InMemoryWorkflowMemory implements WorkflowMemory {
+    /** Nested map storing contexts by domain, workflow, subject, and instance */
+    private contexts;
+    /**
+     * Creates a new InMemoryWorkflowMemory with empty storage.
+     */
+    constructor();
+    /**
+     * Retrieve all workflow contexts for a specific subject in a domain
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject
+     * @returns Promise resolving to an array of contexts
+     */
+    getContexts(domain: string, workflowId: string, subjectId: string): Promise<Context[]>;
+    /**
+     * Save workflow context for a specific subject in a domain
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject
+     * @param context - The context to save (identified by context.instanceId)
+     */
+    saveContext(domain: string, workflowId: string, subjectId: string, context: Context): Promise<void>;
+    /**
+     * Delete workflow context for a specific subject and instance in a domain
+     * @param domain - The domain identifier
+     * @param workflowId - The unique identifier of the workflow
+     * @param subjectId - The unique identifier of the subject
+     * @param instanceId - The unique identifier of the workflow instance
+     */
+    deleteContext(domain: string, workflowId: string, subjectId: string, instanceId: string): Promise<void>;
+    /**
+     * Clear all contexts from memory
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * In-memory implementation of WorkflowScheduler using setTimeout.
+ *
+ * Stores scheduled events in memory with their timeout handles.
+ * When a timeout fires, the event is delivered to the workflow manager.
+ * Useful for testing, development, and single-instance deployments.
+ *
+ * Note: Requires setWorkflowManager() to be called before scheduling events.
+ */
+declare class InMemoryWorkflowScheduler implements WorkflowScheduler {
+    /** Map of schedule IDs to their setTimeout handles */
+    private schedules;
+    /** Counter for generating unique schedule IDs */
+    private scheduleIdCounter;
+    /** Reference to the workflow manager for event delivery */
+    private workflowManager;
+    /**
+     * Creates a new InMemoryWorkflowScheduler.
+     * Call setWorkflowManager() before scheduling any events.
+     */
+    constructor();
+    /**
+     * Set the workflow manager reference
+     * The scheduler will call processEvent on the manager when scheduled events are due
+     * @param manager - The workflow manager instance
+     */
+    setWorkflowManager(manager: IWorkflowManager): void;
+    /**
+     * Schedule an event to be delivered after a delay
+     * When the delay expires, the event will be passed to the workflow manager
+     * @param event - The event to schedule
+     * @param delayMs - Delay in milliseconds before the event is delivered
+     * @returns Promise resolving to a schedule ID that can be used to cancel
+     */
+    schedule(event: Event, delayMs: number): Promise<string>;
+    /**
+     * Cancel a scheduled event
+     * @param scheduleId - The ID of the schedule to cancel
+     * @returns Promise resolving to true if canceled, false if not found
+     */
+    cancel(scheduleId: string): Promise<boolean>;
+    /**
+     * Get the number of currently scheduled events
+     * @returns The count of active schedules
+     */
+    getScheduleCount(): number;
+    /**
+     * Cancel all scheduled events
+     */
+    cancelAll(): Promise<void>;
+}
+
+export { type Connection, InMemoryWorkflowMemory, InMemoryWorkflowScheduler, InMemoryWorkflowStore, NodeModel, type NodeModelClass, type NodeModelRegistry, type NodeServices, WorkflowManager, type WorkflowManagerConfig, type WorkflowMemory, WorkflowModel, type WorkflowScheduler, type WorkflowStore, _default as defaultNodeModels };