@gravito/flux 3.0.1 → 3.0.2

package/dist/index.node.d.cts

@@ -1,314 +1,399 @@
-import { j as WorkflowContext, F as FluxWaitResult, W as WorkflowDefinition, k as WorkflowDescriptor, a as FluxConfig, c as FluxResult, m as WorkflowState, o as WorkflowStorage, l as WorkflowFilter, f as FluxTraceSink, d as FluxTraceEvent, n as WorkflowStatus, S as StepDefinition, h as StepExecution, i as StepResult, b as FluxLogger } from './types-CZwYGpou.cjs';
-export { e as FluxTraceEventType, g as StepDescriptor } from './types-CZwYGpou.cjs';
+import { l as WorkflowContext, q as StepHandlerResult, W as WorkflowDefinition, m as WorkflowDescriptor, a as WorkflowState, o as WorkflowStatus, h as LockProvider, L as Lock, S as StepDefinition, j as StepExecution, k as StepResult, c as FluxLogger, p as WorkflowStorage, n as WorkflowFilter, g as FluxTraceSink, e as FluxTraceEvent, b as FluxConfig, d as FluxResult, C as CronScheduleOptions } from './types-CRz5XdLd.cjs';
+export { f as FluxTraceEventType, M as MemoryLockProvider, i as StepDescriptor } from './types-CRz5XdLd.cjs';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * @fileoverview Workflow Builder - Fluent API for defining workflows
- *
- * Type-safe, chainable workflow definition.
- *
- * @module @gravito/flux/builder
- */
-
-/**
- * Options for configuring a single step in a workflow.
- * @public
+ * Configuration options for a workflow step.
+ * Allows fine-tuning of execution behavior such as retries, timeouts, and conditional logic.
  */
-interface StepOptions<TInput = any, TData = any> {
-    /** Maximum number of automatic retries on failure (default: 0) */
+interface StepOptions<TInput = unknown, TData = Record<string, any>> {
+    /** Maximum number of retry attempts on failure. */
     retries?: number;
-    /** Maximum execution time in milliseconds before timeout error */
+    /** Execution time limit in milliseconds. */
     timeout?: number;
-    /** Predicate to determine if the step should be executed or skipped */
+    /** Predicate to determine if the step should execute based on current context. */
     when?: (ctx: WorkflowContext<TInput, TData>) => boolean;
-    /** Logic to undo the effects of this step if a later step fails */
+    /** Logic to execute for rolling back changes if a subsequent step fails. */
+    compensate?: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void;
+}
+interface ParallelStepConfig<TInput = unknown, TData = Record<string, any>> {
+    name: string;
+    handler: (ctx: WorkflowContext<TInput, TData>) => StepHandlerResult;
+    options?: StepOptions<TInput, TData>;
+    /** Shorthand for options.compensate - rollback logic if subsequent steps fail */
     compensate?: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void;
+    /** Shorthand for options.retries */
+    retries?: number;
+    /** Shorthand for options.timeout */
+    timeout?: number;
+    /** Shorthand for options.when */
+    when?: (ctx: WorkflowContext<TInput, TData>) => boolean;
 }
 /**
- * WorkflowBuilder provides a fluent, type-safe API for defining sequential logic.
+ * A fluent API for defining workflows in a type-safe manner.
+ * The builder pattern ensures that workflows are constructed with all necessary components
+ * before being passed to the execution engine.
  *
  * @example
  * ```typescript
- * const myFlow = createWorkflow('process-order')
- *   .input<{ orderId: string }>()
- *   .step('validate', async (ctx) => { ... })
- *   .step('charge', async (ctx) => { ... }, { compensate: async (ctx) => { ... } })
- *   .commit('ship', async (ctx) => { ... });
+ * const flow = new WorkflowBuilder('order-process')
+ *   .input<{ id: string }>()
+ *   .step('validate', (ctx) => { ... })
+ *   .build();
  * ```
- * @public
  */
-declare class WorkflowBuilder<TInput = unknown, TData = Record<string, unknown>> {
-    drum: any;
+declare class WorkflowBuilder<TInput = unknown, TData = Record<string, any>> {
     private _name;
+    private _version?;
     private _steps;
     private _validateInput?;
+    private _parallelGroupCounter;
+    /**
+     * Initializes a new workflow builder with a unique name.
+     * @param name - The identifier for this workflow definition.
+     */
     constructor(name: string);
     /**
-     * Define input type
-     *
-     * This method is used for TypeScript type inference.
+     * Defines the expected input type for the workflow.
+     * This is a type-only operation that enables compile-time safety for subsequent steps.
+     * @returns A builder instance with the specified input type.
      */
     input<T>(): WorkflowBuilder<T, TData>;
     /**
-     * Define workflow data (state) type
-     *
-     * This method is used for TypeScript type inference.
+     * Defines the structure of the shared data object used across steps.
+     * @returns A builder instance with the specified data type.
      */
-    data<T>(): WorkflowBuilder<TInput, T>;
+    data<T extends Record<string, any>>(): WorkflowBuilder<TInput, T>;
     /**
-     * Add input validator
+     * Sets the semantic version of this workflow definition.
+     * @param v - A semantic version string (e.g., "1.0.0", "2.1.0").
+     * @returns The builder instance for chaining.
+     */
+    version(v: string): this;
+    /**
+     * Attaches a runtime validator for the workflow input.
+     * @param validator - A type guard function to verify input integrity.
+     * @returns The builder instance for chaining.
      */
     validate(validator: (input: unknown) => input is TInput): this;
     /**
-     * Add a step to the workflow
+     * Adds a standard processing step to the workflow.
+     * Standard steps are subject to compensation if the workflow fails later.
+     *
+     * @param name - Unique name for the step.
+     * @param handler - The business logic to execute.
+     * @param options - Optional execution configuration.
+     * @returns The builder instance for chaining.
+     */
+    step(name: string, handler: (ctx: WorkflowContext<TInput, TData>) => StepHandlerResult, options?: StepOptions<TInput, TData>): this;
+    /**
+     * Adds multiple steps that execute in parallel.
+     * All steps in a parallel group will run concurrently and must all succeed before proceeding.
+     *
+     * @param steps - Array of step configurations to execute in parallel.
+     * @returns The builder instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * workflow.stepParallel([
+     *   { name: 'fetch-user', handler: async (ctx) => { ctx.data.user = await getUser() } },
+     *   { name: 'fetch-orders', handler: async (ctx) => { ctx.data.orders = await getOrders() } },
+     *   { name: 'fetch-profile', handler: async (ctx) => { ctx.data.profile = await getProfile() } }
+     * ])
+     * ```
      */
-    step(name: string, handler: (ctx: WorkflowContext<TInput, TData>) => void | Promise<void | undefined | FluxWaitResult> | undefined | FluxWaitResult, options?: StepOptions<TInput, TData>): this;
+    stepParallel(steps: ParallelStepConfig<TInput, TData>[]): this;
     /**
-     * Add a commit step (always executes, even on replay)
+     * Adds a "commit" step that represents a permanent side-effect.
+     * Commit steps are intended for operations that should not be rolled back
+     * or re-executed during certain replay scenarios.
      *
-     * Commit steps are for side effects that should not be skipped,
-     * such as database writes or external API calls.
+     * @param name - Unique name for the step.
+     * @param handler - The side-effect logic to execute.
+     * @param options - Optional execution configuration (compensation is not allowed).
+     * @returns The builder instance for chaining.
      */
     commit(name: string, handler: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void, options?: Omit<StepOptions<TInput, TData>, 'compensate'>): this;
     /**
-     * Build the workflow definition
+     * Finalizes the workflow definition.
+     * @returns A complete workflow blueprint ready for execution.
+     * @throws Error if the workflow has no steps defined.
      */
     build(): WorkflowDefinition<TInput, TData>;
     /**
-     * Describe workflow (serializable metadata)
+     * Generates a structural description of the workflow for introspection.
+     * @returns A descriptor containing step metadata.
      */
     describe(): WorkflowDescriptor;
-    /**
-     * Get workflow name
-     */
+    /** The name of the workflow being built. */
     get name(): string;
-    /**
-     * Get step count
-     */
+    /** The number of steps currently defined in the workflow. */
     get stepCount(): number;
 }
 /**
- * Create a new workflow builder
+ * Factory function to initiate a new workflow definition.
  *
- * @param name - Unique workflow name
- * @returns WorkflowBuilder instance
+ * @param name - The unique name for the workflow.
+ * @returns A new WorkflowBuilder instance.
  *
  * @example
  * ```typescript
- * const uploadFlow = createWorkflow('image-upload')
- *   .input<{ file: Buffer }>()
- *   .step('resize', async (ctx) => {
- *     ctx.data.resized = await sharp(ctx.input.file).resize(200).toBuffer()
- *   })
- *   .commit('save', async (ctx) => {
- *     await storage.put(ctx.data.resized)
- *   })
+ * const flow = createWorkflow('my-flow')
+ *   .step('hello', () => console.log('world'))
+ *   .build();
  * ```
  */
 declare function createWorkflow(name: string): WorkflowBuilder;
 
 /**
- * @fileoverview Flux Engine - Main workflow execution engine
+ * Orchestrates the lifecycle and state transformations of a workflow context.
  *
- * Orchestrates workflow execution with storage and event handling.
- *
- * @module @gravito/flux
- */
-
-/**
- * FluxEngine is the primary execution orchestrator for workflows.
- * It manages context lifecycle, persistence via storage adapters,
- * step execution with retries, and transactional rollbacks (compensation).
+ * The ContextManager is responsible for initializing new contexts, restoring them from
+ * persisted states, and performing immutable updates during execution.
  *
  * @example
  * ```typescript
- * const engine = new FluxEngine({
- *   storage: new BunSQLiteStorage(),
- *   logger: new FluxConsoleLogger()
- * });
- *
- * const workflow = createWorkflow('onboard-user')
- *   .step('create-account', async (ctx) => { ... })
- *   .step('send-email', async (ctx) => { ... });
- *
- * const result = await engine.execute(workflow, { email: 'user@example.com' });
- * if (result.status === 'completed') {
- *   console.log('User onboarded successfully');
- * }
+ * const manager = new ContextManager();
+ * const ctx = manager.create('order-flow', { id: '123' }, 5);
  * ```
- * @public
  */
-declare class FluxEngine {
-    private storage;
-    private executor;
-    private contextManager;
-    private config;
-    constructor(config?: FluxConfig);
+declare class ContextManager {
     /**
-     * Execute a workflow with input data
+     * Initializes a fresh workflow context with a pending status and empty history.
      *
-     * @param workflow - Workflow builder or definition
-     * @param input - Input data for the workflow
-     * @returns Execution result
-     */
-    execute<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, input: TInput): Promise<FluxResult<TData>>;
-    /**
-     * Resume a paused or failed workflow
+     * @param name - The human-readable identifier for the workflow type.
+     * @param input - The initial data required to start the workflow.
+     * @param stepCount - Total number of steps defined in the workflow for history pre-allocation.
+     * @returns A new WorkflowContext instance.
      *
-     * @param workflowId - Workflow instance ID
-     * @returns Execution result or null if not found
-     */
-    resume<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, options?: {
-        fromStep?: number | string;
-    }): Promise<FluxResult<TData> | null>;
-    /**
-     * Send a signal to a suspended workflow
-     */
-    signal<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, signalName: string, payload?: any): Promise<FluxResult<TData>>;
-    /**
-     * Retry a specific step (replays from that step onward)
+     * @example
+     * ```typescript
+     * const ctx = manager.create('signup', { email: 'user@example.com' }, 3);
+     * ```
      */
-    retryStep<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, stepName: string): Promise<FluxResult<TData> | null>;
+    create<TInput, TData extends Record<string, any> = Record<string, any>>(name: string, input: TInput, stepCount: number): WorkflowContext<TInput, TData>;
     /**
-     * Get workflow state by ID
-     */
-    get<TInput = any, TData = any>(workflowId: string): Promise<WorkflowState<TInput, TData> | null>;
-    /**
-     * Save workflow state manually (e.g., for external updates)
+     * Reconstructs a workflow context from a previously persisted state.
+     *
+     * Used for resuming suspended workflows or replaying failed ones from a specific point.
+     *
+     * @param state - The persisted state object.
+     * @returns A hydrated WorkflowContext ready for execution.
+     *
+     * @example
+     * ```typescript
+     * const state = await storage.load(id);
+     * const ctx = manager.restore(state);
+     * ```
      */
-    saveState<TInput, TData>(state: WorkflowState<TInput, TData>): Promise<void>;
+    restore<TInput, TData extends Record<string, any> = Record<string, any>>(state: WorkflowState<TInput, TData>): WorkflowContext<TInput, TData>;
     /**
-     * List workflows
+     * Converts a runtime context into a serializable state for persistence.
+     *
+     * Captures the current progress, data, and execution history.
+     *
+     * @param ctx - The active workflow context.
+     * @returns A serializable WorkflowState object.
+     *
+     * @example
+     * ```typescript
+     * const state = manager.toState(ctx);
+     * await storage.save(state);
+     * ```
      */
-    list(filter?: Parameters<WorkflowStorage['list']>[0]): Promise<WorkflowState<any, any>[]>;
+    toState<TInput, TData extends Record<string, any>>(ctx: WorkflowContext<TInput, TData>): WorkflowState<TInput, TData>;
     /**
-     * Initialize engine (init storage)
+     * Updates the overall status of the workflow.
+     *
+     * @param ctx - The current context.
+     * @param status - The new status to apply.
+     * @returns A new context instance with the updated status.
+     *
+     * @example
+     * ```typescript
+     * const runningCtx = manager.updateStatus(ctx, 'running');
+     * ```
      */
-    init(): Promise<void>;
+    updateStatus<TInput, TData extends Record<string, any>>(ctx: WorkflowContext<TInput, TData>, status: WorkflowStatus): WorkflowContext<TInput, TData>;
     /**
-     * Shutdown engine (cleanup)
+     * Increments the current step pointer.
+     *
+     * @param ctx - The current context.
+     * @returns A new context instance pointing to the next step.
+     *
+     * @example
+     * ```typescript
+     * const nextStepCtx = manager.advanceStep(ctx);
+     * console.log(nextStepCtx.currentStep); // ctx.currentStep + 1
+     * ```
      */
-    close(): Promise<void>;
-    private resolveDefinition;
-    private resolveStartIndex;
-    private resetHistoryFrom;
+    advanceStep<TInput, TData extends Record<string, any>>(ctx: WorkflowContext<TInput, TData>): WorkflowContext<TInput, TData>;
     /**
-     * Rollback workflow by executing compensation handlers in reverse order
+     * Assigns a name to a specific step in the execution history.
+     *
+     * Useful for tracking which step is currently being executed or has been completed.
+     *
+     * @param ctx - The current context.
+     * @param index - The index of the step in the history array.
+     * @param name - The name to assign to the step.
+     * @returns A new context instance with the updated history.
+     *
+     * @example
+     * ```typescript
+     * const namedCtx = manager.setStepName(ctx, 0, 'validate-user');
+     * console.log(namedCtx.history[0].name); // 'validate-user'
+     * ```
      */
-    private rollback;
-    private runFrom;
-    private emitTrace;
+    setStepName<TInput, TData extends Record<string, any>>(ctx: WorkflowContext<TInput, TData>, index: number, name: string): WorkflowContext<TInput, TData>;
 }
 
 /**
- * @fileoverview In-memory storage adapter
+ * @fileoverview Redis-based Lock Provider for distributed workflow execution
  *
- * Simple storage for development and testing.
+ * Provides a Redis-backed distributed locking mechanism for coordinating
+ * workflow execution across multiple nodes in a cluster.
  *
- * @module @gravito/flux/storage
+ * @module @gravito/flux/core
  */
 
 /**
- * Memory Storage
- *
- * In-memory storage adapter for development and testing.
- * Data is not persisted across restarts.
+ * Minimal Redis client interface for compatibility with ioredis/redis libraries.
+ * Consumers should provide a client that implements these methods.
  */
-declare class MemoryStorage implements WorkflowStorage {
-    private store;
-    save(state: WorkflowState): Promise<void>;
-    load(id: string): Promise<WorkflowState | null>;
-    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
-    delete(id: string): Promise<void>;
-    init(): Promise<void>;
-    close(): Promise<void>;
+interface RedisClient {
     /**
-     * Get store size (for testing)
+     * SET command with optional NX and PX options.
+     * @param key - The key to set
+     * @param value - The value to set
+     * @param options - SET options (NX for only-if-not-exists, PX for expiry in ms)
+     * @returns 'OK' if set, null if key exists (with NX)
      */
-    size(): number;
+    set(key: string, value: string, options?: {
+        NX?: boolean;
+        PX?: number;
+    }): Promise<'OK' | null>;
+    /**
+     * GET command to retrieve a value.
+     * @param key - The key to get
+     * @returns The value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * DEL command to delete a key.
+     * @param key - The key to delete
+     * @returns Number of keys deleted
+     */
+    del(key: string): Promise<number>;
+    /**
+     * EVAL command to execute Lua scripts atomically.
+     * @param script - The Lua script
+     * @param keys - Array of keys
+     * @param args - Array of arguments
+     * @returns Script result
+     */
+    eval(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
 }
-
 /**
- * @fileoverview JSON file trace sink (NDJSON)
- *
- * Writes trace events to a newline-delimited JSON file.
+ * Configuration options for RedisLockProvider.
  */
-
-/**
- * Options for configuring the `JsonFileTraceSink`.
- *
- * @public
- * @since 3.0.0
- */
-interface JsonFileTraceSinkOptions {
-    /** Absolute path where the trace file should be stored. */
-    path: string;
-    /** Whether to reset (clear) the file on initialization. @default true */
-    reset?: boolean;
+interface RedisLockProviderOptions {
+    /** Redis client instance (must implement RedisClient interface) */
+    client: RedisClient;
+    /** Prefix for all lock keys (default: 'flux:lock:') */
+    keyPrefix?: string;
+    /** Default TTL for locks in milliseconds (default: 30000) */
+    defaultTtl?: number;
+    /** Delay between retry attempts in milliseconds (default: 100) */
+    retryDelay?: number;
+    /** Maximum number of retry attempts (default: 0, no retries) */
+    maxRetries?: number;
 }
 /**
- * A trace sink that writes events to a newline-delimited JSON (NDJSON) file.
+ * Redis-based implementation of LockProvider for distributed locking.
  *
- * This sink is ideal for local development and debugging as it produces
- * a human-readable and easily machine-parsable log of workflow events.
+ * Uses Redis SET NX PX for atomic lock acquisition and Lua scripts
+ * for safe release and refresh operations.
  *
  * @example
  * ```typescript
- * const sink = new JsonFileTraceSink({
- *   path: './traces/workflow.jsonl',
- *   reset: true
- * });
- * ```
+ * import Redis from 'ioredis'
+ * import { RedisLockProvider } from '@gravito/flux'
  *
- * @public
- * @since 3.0.0
- */
-declare class JsonFileTraceSink implements FluxTraceSink {
-    private path;
-    private ready;
-    constructor(options: JsonFileTraceSinkOptions);
-    private init;
-    emit(event: FluxTraceEvent): Promise<void>;
-}
-
-/**
- * @fileoverview Context Manager for workflow execution
- *
- * Manages workflow context lifecycle and state snapshots.
- *
- * @module @gravito/flux/core
- */
-
-/**
- * Context Manager
+ * const redis = new Redis()
+ * const lockProvider = new RedisLockProvider({
+ *   client: redis,
+ *   keyPrefix: 'myapp:locks:',
+ *   defaultTtl: 30000,
+ * })
  *
- * Creates and manages workflow execution contexts.
+ * const lock = await lockProvider.acquire('workflow-123', 'node-1', 30000)
+ * if (lock) {
+ *   try {
+ *     // Do work with the lock
+ *   } finally {
+ *     await lock.release()
+ *   }
+ * }
+ * ```
  */
-declare class ContextManager {
+declare class RedisLockProvider implements LockProvider {
+    private readonly client;
+    private readonly keyPrefix;
+    private readonly defaultTtl;
+    private readonly retryDelay;
+    private readonly maxRetries;
+    constructor(options: RedisLockProviderOptions);
     /**
-     * Create a new workflow context
+     * Attempts to acquire a lock for a specific resource.
+     *
+     * Uses Redis SET with NX (only if not exists) and PX (expire in ms)
+     * for atomic lock acquisition. Supports retry with configurable delay.
+     *
+     * @param resourceId - The unique ID of the resource to lock
+     * @param owner - The identifier of the node/process requesting the lock
+     * @param ttl - Time-to-live for the lock in milliseconds
+     * @returns A Lock object if successful, otherwise null
      */
-    create<TInput, TData = any>(name: string, input: TInput, stepCount: number): WorkflowContext<TInput, TData>;
+    acquire(resourceId: string, owner: string, ttl: number): Promise<Lock | null>;
     /**
-     * Restore context from saved state
+     * Refreshes an existing lock to extend its lifetime.
+     *
+     * Uses a Lua script to atomically check ownership and extend TTL.
+     *
+     * @param resourceId - The ID of the resource
+     * @param owner - The current owner of the lock
+     * @param ttl - The new time-to-live from the current moment
+     * @returns True if the lock was successfully refreshed
+     */
+    refresh(resourceId: string, owner: string, ttl: number): Promise<boolean>;
+    /**
+     * Forcefully releases a lock, regardless of the owner.
+     *
+     * @param resourceId - The ID of the resource to unlock
      */
-    restore<TInput, TData = any>(state: WorkflowState<TInput, TData>): WorkflowContext<TInput, TData>;
+    release(resourceId: string): Promise<void>;
     /**
-     * Convert context to serializable state
+     * Safely releases a lock only if owned by the specified owner.
+     *
+     * Uses a Lua script to atomically check ownership and delete.
+     *
+     * @param resourceId - The ID of the resource to unlock
+     * @param owner - The owner that should release the lock
+     * @returns True if the lock was released, false if not owned
      */
-    toState<TInput, TData>(ctx: WorkflowContext<TInput, TData>): WorkflowState<TInput, TData>;
+    releaseIfOwned(resourceId: string, owner: string): Promise<boolean>;
     /**
-     * Update context status (returns new context for immutability)
+     * Generates the Redis key for a resource.
      */
-    updateStatus<TInput, TData>(ctx: WorkflowContext<TInput, TData>, status: WorkflowStatus): WorkflowContext<TInput, TData>;
+    private getKey;
     /**
-     * Advance to next step
+     * Creates a Lock object with a release method.
      */
-    advanceStep<TInput, TData>(ctx: WorkflowContext<TInput, TData>): WorkflowContext<TInput, TData>;
+    private createLock;
     /**
-     * Update step name in history
+     * Sleeps for the specified duration.
      */
-    setStepName<TInput, TData>(ctx: WorkflowContext<TInput, TData>, index: number, name: string): void;
+    private sleep;
 }
 
 /**
@@ -320,36 +405,93 @@ declare class ContextManager {
  */
 
 /**
- * State Machine for workflow status management
+ * Manages the lifecycle states of a workflow instance.
+ *
+ * The StateMachine enforces transition rules and notifies listeners of state changes.
+ * It is designed to be the single source of truth for a workflow's current progress.
  *
- * Provides validated state transitions using EventTarget for events.
+ * @example
+ * ```typescript
+ * const sm = new StateMachine();
+ * sm.addEventListener('transition', (e) => console.log(e.detail));
+ * sm.transition('running');
+ * ```
  */
 declare class StateMachine extends EventTarget {
     private _status;
     /**
-     * Current status
+     * The current operational status of the workflow.
      */
     get status(): WorkflowStatus;
     /**
-     * Check if transition to target status is allowed
+     * Evaluates if a transition to the specified status is valid from the current state.
+     *
+     * @param to - The target status to check.
+     * @returns True if the transition is permitted by the transition map.
+     *
+     * @example
+     * ```typescript
+     * if (sm.canTransition('completed')) {
+     *   sm.transition('completed');
+     * }
+     * ```
      */
     canTransition(to: WorkflowStatus): boolean;
     /**
-     * Transition to a new status
+     * Moves the workflow to a new status if the transition is valid.
+     *
+     * @param to - The target status.
+     * @throws {Error} If the transition is illegal according to the defined rules.
      *
-     * @throws {Error} If transition is not allowed
+     * @example
+     * ```typescript
+     * try {
+     *   sm.transition('completed');
+     * } catch (e) {
+     *   // Handle invalid transition
+     * }
+     * ```
      */
     transition(to: WorkflowStatus): void;
     /**
-     * Force set status (for replay/restore)
+     * Overrides the current status without validation.
+     *
+     * This should only be used during workflow restoration from persisted storage
+     * or when replaying history where the state is already known to be valid.
+     *
+     * @param status - The status to force set.
+     *
+     * @example
+     * ```typescript
+     * // Restore state from database
+     * sm.forceStatus(storedState.status);
+     * ```
      */
     forceStatus(status: WorkflowStatus): void;
     /**
-     * Check if workflow is in terminal state
+     * Determines if the workflow has reached a state where no further execution is possible.
+     *
+     * @returns True if the status is 'completed', 'failed', or 'rolled_back'.
+     *
+     * @example
+     * ```typescript
+     * if (sm.isTerminal()) {
+     *   console.log('Workflow finished');
+     * }
+     * ```
      */
     isTerminal(): boolean;
     /**
-     * Check if workflow can be executed
+     * Checks if the workflow is in a state that allows for execution or resumption.
+     *
+     * @returns True if the workflow can be started or resumed.
+     *
+     * @example
+     * ```typescript
+     * if (sm.canExecute()) {
+     *   await engine.run();
+     * }
+     * ```
      */
     canExecute(): boolean;
 }
@@ -363,29 +505,81 @@ declare class StateMachine extends EventTarget {
  */
 
 /**
- * Step Executor
+ * Handles the isolated execution of a single workflow step.
  *
- * Executes individual workflow steps with retry and timeout support.
+ * The StepExecutor manages the operational aspects of step execution, including
+ * condition checking, retry logic with exponential backoff, and timeout enforcement.
+ *
+ * @example
+ * ```typescript
+ * const executor = new StepExecutor({ defaultRetries: 3 });
+ * const { result } = await executor.execute(stepDef, ctx, executionRecord);
+ * ```
  */
 declare class StepExecutor {
     private defaultRetries;
     private defaultTimeout;
     private onRetry?;
+    /**
+     * Creates a new StepExecutor with global defaults.
+     *
+     * @param options - Configuration for default behavior and lifecycle hooks.
+     */
     constructor(options?: {
         defaultRetries?: number;
         defaultTimeout?: number;
         onRetry?: (step: StepDefinition<any, any>, ctx: WorkflowContext<any, any>, error: Error, attempt: number, maxRetries: number) => void | Promise<void>;
     });
     /**
-     * Execute a step with retry and timeout
+     * Executes a step definition against a workflow context.
+     *
+     * This method performs the following sequence:
+     * 1. Evaluates the `when` condition (if present).
+     * 2. Initiates the execution loop with retries.
+     * 3. Enforces timeouts for each attempt.
+     * 4. Handles suspension signals (`flux_wait`).
+     * 5. Updates the execution history record.
+     *
+     * @param step - The definition of the step to execute.
+     * @param ctx - The current workflow context.
+     * @param execution - The current execution record for this step.
+     * @returns The result of the execution and the updated execution record.
+     *
+     * @throws {Error} If the step handler throws an unrecoverable error or times out.
+     *
+     * @example
+     * ```typescript
+     * const { result, execution } = await executor.execute(
+     *   stepDefinition,
+     *   currentContext,
+     *   currentExecution
+     * );
+     *
+     * if (!result.success) {
+     *   console.error(result.error);
+     * }
+     * ```
      */
-    execute<TInput, TData>(step: StepDefinition<TInput, TData>, ctx: WorkflowContext<TInput, TData>, execution: StepExecution): Promise<StepResult>;
+    execute<TInput, TData extends Record<string, any>>(step: StepDefinition<TInput, TData>, ctx: WorkflowContext<TInput, TData>, execution: StepExecution): Promise<{
+        result: StepResult;
+        execution: StepExecution;
+    }>;
     /**
-     * Execute handler with timeout
+     * Wraps the step handler in a timeout race.
+     *
+     * @param handler - The user-defined step handler.
+     * @param ctx - The workflow context.
+     * @param timeout - Maximum time allowed for execution in milliseconds.
+     * @returns The handler result or a suspension signal.
+     * @throws {Error} If the timeout is reached before the handler completes.
+     * @private
      */
     private executeWithTimeout;
     /**
-     * Sleep helper
+     * Pauses execution for a specified duration.
+     *
+     * @param ms - Milliseconds to sleep.
+     * @private
      */
     private sleep;
 }
@@ -399,73 +593,123 @@ declare class StepExecutor {
  */
 
 /**
- * Console Logger
+ * Console Logger implementation for FluxEngine.
  *
- * Default logger that outputs to console.
+ * Provides a standard way to output workflow execution logs to the system console
+ * with a configurable prefix for easy filtering.
  *
  * @example
  * ```typescript
- * const engine = new FluxEngine({
- *   logger: new FluxConsoleLogger()
- * })
+ * const logger = new FluxConsoleLogger('[OrderFlow]');
+ * logger.info('Workflow started', { orderId: '123' });
  * ```
  */
 declare class FluxConsoleLogger implements FluxLogger {
     private prefix;
+    /**
+     * Creates a new console logger instance.
+     *
+     * @param prefix - String prepended to every log message for identification.
+     */
     constructor(prefix?: string);
+    /**
+     * Logs fine-grained informational events that are most useful to debug an application.
+     *
+     * @param message - The primary log message.
+     * @param args - Additional metadata or objects to include in the log output.
+     */
     debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs informational messages that highlight the progress of the application at coarse-grained level.
+     *
+     * @param message - The primary log message.
+     * @param args - Additional metadata or objects to include in the log output.
+     */
     info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs potentially harmful situations that should be noted but don't stop execution.
+     *
+     * @param message - The primary log message.
+     * @param args - Additional metadata or objects to include in the log output.
+     */
     warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs error events that might still allow the application to continue running.
+     *
+     * @param message - The primary log message.
+     * @param args - Additional metadata or objects to include in the log output.
+     */
     error(message: string, ...args: unknown[]): void;
 }
 /**
- * Silent Logger
+ * Silent Logger implementation that discards all log entries.
+ *
+ * Useful for production environments where logging is handled externally,
+ * or for unit tests where console output should be suppressed.
  *
- * Logger that outputs nothing (for testing or production).
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine({
+ *   logger: new FluxSilentLogger()
+ * });
+ * ```
  */
 declare class FluxSilentLogger implements FluxLogger {
+    /** Discards debug logs. */
     debug(): void;
+    /** Discards info logs. */
     info(): void;
+    /** Discards warning logs. */
     warn(): void;
+    /** Discards error logs. */
     error(): void;
 }
 
 /**
- * OrbitFlux configuration options
+ * Configuration options for the OrbitFlux extension.
+ *
+ * Defines how the workflow engine should be initialized and integrated into the Gravito core.
  */
 interface OrbitFluxOptions {
     /**
-     * Storage driver: 'memory' | 'sqlite' | custom WorkflowStorage
-     * @default 'memory'
+     * Specifies the storage driver to use for persisting workflow states.
+     *
+     * - 'memory': Volatile in-memory storage (default).
+     * - 'sqlite': Persistent SQLite storage (Bun only).
+     * - WorkflowStorage: A custom implementation of the storage interface.
      */
     storage?: 'memory' | 'sqlite' | WorkflowStorage;
     /**
-     * SQLite database path (only used if storage is 'sqlite')
-     * @default ':memory:'
+     * The file system path for the SQLite database.
+     *
+     * Only applicable when `storage` is set to 'sqlite'.
      */
     dbPath?: string;
     /**
-     * Service name in core.services
-     * @default 'flux'
+     * The key under which the FluxEngine will be registered in the core service container.
      */
     exposeAs?: string;
     /**
-     * Custom logger
+     * A custom logger implementation for the workflow engine.
+     *
+     * If not provided, the engine will use a wrapper around the core logger.
      */
     logger?: FluxLogger;
     /**
-     * Default retry count for steps
-     * @default 3
+     * The default number of times a workflow step should be retried upon failure.
      */
     defaultRetries?: number;
     /**
-     * Default timeout for steps (ms)
-     * @default 30000
+     * The default timeout in milliseconds for workflow steps.
      */
     defaultTimeout?: number;
 }
 /**
- * OrbitFlux - Gravito Workflow Integration
+ * OrbitFlux integrates the Flux workflow engine into the Gravito Galaxy Architecture.
+ *
+ * It acts as an "Orbit" (infrastructure extension) that provides a managed `FluxEngine`
+ * instance to the core application and other satellites. It also bridges engine events
+ * to the core hook system.
  *
  * @example
  * ```typescript
@@ -473,33 +717,652 @@ interface OrbitFluxOptions {
  *
  * const core = await PlanetCore.boot({
  *   orbits: [
- *     new OrbitFlux({ storage: 'sqlite', dbPath: './data/workflows.db' })
+ *     new OrbitFlux({
+ *       storage: 'sqlite',
+ *       dbPath: './data/workflows.db'
+ *     })
  *   ]
  * })
  *
- * // Access via container
+ * // Access the engine from the container
  * const flux = core.container.make<FluxEngine>('flux')
- * await flux.execute(myWorkflow, input)
  * ```
  */
 declare class OrbitFlux implements GravitoOrbit {
     private options;
     private engine?;
+    /**
+     * Initializes a new OrbitFlux instance with the given options.
+     *
+     * @param options - Configuration for the workflow engine integration.
+     */
     constructor(options?: OrbitFluxOptions);
     /**
-     * Create OrbitFlux with configuration
+     * Static factory method to create and configure an OrbitFlux instance.
+     *
+     * @param options - Configuration for the workflow engine integration.
+     * @returns A configured OrbitFlux instance.
      */
     static configure(options?: OrbitFluxOptions): OrbitFlux;
     /**
-     * Install into PlanetCore
+     * Installs the Flux workflow engine into the Gravito core.
+     *
+     * This method resolves the storage adapter, initializes it, configures the engine
+     * with core-integrated logging and hooks, and registers the engine in the IoC container.
      *
-     * @param core - The PlanetCore instance
+     * @param core - The PlanetCore instance being booted.
+     * @throws {Error} If storage initialization fails or engine registration conflicts occur.
      */
     install(core: PlanetCore): Promise<void>;
     /**
-     * Get the FluxEngine instance
+     * Retrieves the managed FluxEngine instance.
+     *
+     * @returns The FluxEngine instance, or undefined if the orbit has not been installed.
      */
     getEngine(): FluxEngine | undefined;
+    /**
+     * Performs cleanup operations when the core is shutting down.
+     *
+     * Closes the underlying workflow engine and its storage connections.
+     *
+     * @throws {Error} If the engine fails to close cleanly.
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * @fileoverview In-memory storage adapter
+ *
+ * Simple storage for development and testing.
+ *
+ * @module @gravito/flux/storage
+ */
+
+/**
+ * MemoryStorage provides a volatile, in-memory storage backend for Flux workflows.
+ *
+ * It is primarily intended for development, testing, and ephemeral workloads where persistence
+ * across process restarts is not required.
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemoryStorage();
+ * await storage.save(workflowState);
+ * const state = await storage.load('workflow-id');
+ * ```
+ */
+declare class MemoryStorage implements WorkflowStorage {
+    private store;
+    /**
+     * Stores a workflow state in the internal Map.
+     *
+     * Automatically updates the `updatedAt` timestamp to reflect the current time.
+     *
+     * @param state - The workflow state to persist.
+     * @throws {Error} If the state object is invalid or cannot be stored.
+     */
+    save(state: WorkflowState): Promise<void>;
+    /**
+     * Retrieves a workflow state by its ID from the internal Map.
+     *
+     * @param id - The unique identifier of the workflow.
+     * @returns The workflow state if found, otherwise null.
+     */
+    load(id: string): Promise<WorkflowState | null>;
+    /**
+     * Filters and returns workflow states stored in memory.
+     *
+     * Supports filtering by name and status, and provides basic pagination.
+     * Results are sorted by creation date in descending order.
+     *
+     * @param filter - Criteria for filtering and paginating results.
+     * @returns An array of matching workflow states.
+     */
+    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
+    /**
+     * Removes a workflow state from the internal Map.
+     *
+     * @param id - The unique identifier of the workflow to delete.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Initializes the memory storage.
+     *
+     * This is a no-op for MemoryStorage but satisfies the WorkflowStorage interface.
+     */
+    init(): Promise<void>;
+    /**
+     * Clears all stored workflow states and resets the storage.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns the total number of workflow states currently stored in memory.
+     *
+     * Useful for assertions in test environments.
+     *
+     * @returns The number of entries in the store.
+     */
+    size(): number;
+}
+
+/**
+ * Configuration options for the PostgreSQL storage adapter.
+ *
+ * Defines connection parameters and database schema settings.
+ */
+interface PostgreSQLStorageOptions {
+    /** Connection string URL (e.g. "postgres://user:pass@host:5432/db"). */
+    connectionString?: string;
+    /** Database host address. */
+    host?: string;
+    /** Database port number. @default 5432 */
+    port?: number;
+    /** Database name. @default "postgres" */
+    database?: string;
+    /** Database user. */
+    user?: string;
+    /** Database password. */
+    password?: string;
+    /** Name of the table to store workflows. @default "flux_workflows" */
+    tableName?: string;
+    /** SSL configuration for secure connections. */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+    };
+}
+/**
+ * PostgreSQL storage adapter for Flux workflows.
+ *
+ * Provides persistent, reliable storage using a PostgreSQL database.
+ * Supports JSONB for efficient storage of workflow state and history.
+ *
+ * @example
+ * ```typescript
+ * const storage = new PostgreSQLStorage({
+ *   connectionString: process.env.DATABASE_URL,
+ *   tableName: 'my_workflows'
+ * });
+ * await storage.init();
+ * ```
+ */
+declare class PostgreSQLStorage implements WorkflowStorage {
+    private pool;
+    private tableName;
+    private initialized;
+    private options;
+    /**
+     * Creates a new PostgreSQL storage instance.
+     *
+     * @param options - Connection and configuration options.
+     */
+    constructor(options?: PostgreSQLStorageOptions);
+    /**
+     * Initializes the database connection pool and schema.
+     *
+     * Creates the workflow table and indexes if they do not exist.
+     * This method is idempotent.
+     *
+     * @throws {Error} If connection fails or schema creation fails.
+     */
+    init(): Promise<void>;
+    /**
+     * Persists the current state of a workflow.
+     *
+     * Uses upsert (INSERT ... ON CONFLICT) to save or update the workflow state.
+     *
+     * @param state - The workflow state to save.
+     * @throws {Error} If the database operation fails.
+     */
+    save(state: WorkflowState): Promise<void>;
+    /**
+     * Loads a workflow state by its ID.
+     *
+     * @param id - The unique identifier of the workflow.
+     * @returns The workflow state, or null if not found.
+     * @throws {Error} If the database query fails.
+     */
+    load(id: string): Promise<WorkflowState | null>;
+    /**
+     * Lists workflows matching the given filter.
+     *
+     * @param filter - Criteria to filter the results.
+     * @returns A list of matching workflow states.
+     * @throws {Error} If the database query fails.
+     */
+    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
+    /**
+     * Deletes a workflow state by its ID.
+     *
+     * @param id - The unique identifier of the workflow to delete.
+     * @throws {Error} If the database operation fails.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Closes the database connection pool.
+     *
+     * Should be called when shutting down the application.
+     */
+    close(): Promise<void>;
+    /**
+     * Converts a database row to a WorkflowState object.
+     *
+     * @param row - The raw database row.
+     * @returns The parsed workflow state.
+     */
+    private rowToState;
+    /**
+     * Returns the underlying pg.Pool instance.
+     *
+     * Useful for testing or advanced database operations.
+     *
+     * @returns The PostgreSQL connection pool.
+     */
+    getPool(): any;
+    /**
+     * Optimizes the database table by reclaiming storage and updating statistics.
+     *
+     * Runs VACUUM ANALYZE on the workflow table.
+     *
+     * @throws {Error} If the maintenance operation fails.
+     */
+    vacuum(): Promise<void>;
+}
+
+/**
+ * @fileoverview JSON file trace sink (NDJSON)
+ *
+ * Writes trace events to a newline-delimited JSON file.
+ */
+
+/**
+ * Options for configuring the `JsonFileTraceSink`.
+ *
+ * @public
+ */
+interface JsonFileTraceSinkOptions {
+    /** Absolute path where the trace file should be stored. */
+    path: string;
+    /** Whether to reset (clear) the file on initialization. @default true */
+    reset?: boolean;
+}
+/**
+ * A trace sink that writes events to a newline-delimited JSON (NDJSON) file.
+ *
+ * This sink is ideal for local development and debugging as it produces
+ * a human-readable and easily machine-parsable log of workflow events.
+ *
+ * @example
+ * ```typescript
+ * const sink = new JsonFileTraceSink({
+ *   path: './traces/workflow.jsonl',
+ *   reset: true
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class JsonFileTraceSink implements FluxTraceSink {
+    private path;
+    private ready;
+    /**
+     * Creates a new JSON file trace sink.
+     *
+     * @param options - Configuration options for the sink.
+     */
+    constructor(options: JsonFileTraceSinkOptions);
+    /**
+     * Ensures the target directory exists and optionally resets the file.
+     *
+     * @param reset - Whether to truncate the file if it already exists.
+     * @throws {Error} If directory creation or file writing fails.
+     */
+    private init;
+    /**
+     * Appends a trace event to the file in NDJSON format.
+     *
+     * Waits for initialization to complete before writing.
+     *
+     * @param event - The trace event to record.
+     * @throws {Error} If writing to the file fails.
+     *
+     * @example
+     * ```typescript
+     * await sink.emit({
+     *   type: 'step_start',
+     *   workflowId: 'wf-1',
+     *   timestamp: Date.now(),
+     *   data: { step: 'validate' }
+     * });
+     * ```
+     */
+    emit(event: FluxTraceEvent): Promise<void>;
+}
+
+/**
+ * Callback for handling recovery needed events.
+ */
+type RecoveryCallback<TInput = unknown, TData = Record<string, any>> = (ctx: WorkflowContext<TInput, TData>, stepName: string, error: Error) => Promise<void> | void;
+/**
+ * Recovery action types for manual intervention.
+ */
+type RecoveryAction = {
+    type: 'retry';
+    maxAttempts?: number;
+} | {
+    type: 'skip';
+} | {
+    type: 'manual';
+    handler: () => Promise<void>;
+} | {
+    type: 'abort';
+};
+/**
+ * Manages recovery from failed compensation actions through human intervention.
+ *
+ * When automatic retry fails, this manager allows workflows to wait for
+ * manual recovery actions before proceeding with rollback.
+ *
+ * @example
+ * ```typescript
+ * const manager = new RecoveryManager();
+ *
+ * manager.onRecoveryNeeded(async (ctx, stepName, error) => {
+ *   await notificationService.alert(
+ *     'CRITICAL: Manual recovery needed',
+ *     { workflow: ctx.id, step: stepName, error: error.message }
+ *   );
+ * });
+ *
+ * manager.registerAction('refund-payment', {
+ *   type: 'manual',
+ *   handler: async () => {
+ *     await finance.manualRefund(ctx.data.transactionId);
+ *   }
+ * });
+ * ```
+ */
+declare class RecoveryManager<TInput = unknown, TData = Record<string, any>> {
+    private recoveryCallbacks;
+    private actions;
+    private pendingRecoveries;
+    /**
+     * Registers a callback to be invoked when recovery is needed.
+     *
+     * @param callback - Function to call when a recovery event occurs.
+     *
+     * @example
+     * ```typescript
+     * manager.onRecoveryNeeded(async (ctx, stepName, error) => {
+     *   await slack.send(`#alerts`, `Workflow ${ctx.id} needs recovery at ${stepName}`);
+     * });
+     * ```
+     */
+    onRecoveryNeeded(callback: RecoveryCallback<TInput, TData>): void;
+    /**
+     * Emits a recovery needed event.
+     *
+     * @param ctx - The workflow context.
+     * @param stepName - The step that failed compensation.
+     * @param error - The error that occurred.
+     */
+    notifyRecoveryNeeded(ctx: WorkflowContext<TInput, TData>, stepName: string, error: Error): Promise<void>;
+    /**
+     * Registers a recovery action for a specific step.
+     *
+     * @param stepName - The step name to associate the action with.
+     * @param action - The recovery action to perform.
+     *
+     * @example
+     * ```typescript
+     * manager.registerAction('book-flight', {
+     *   type: 'retry',
+     *   maxAttempts: 5
+     * });
+     *
+     * manager.registerAction('charge-card', {
+     *   type: 'manual',
+     *   handler: async () => {
+     *     await accountingSystem.manualRefund(transactionId);
+     *   }
+     * });
+     * ```
+     */
+    registerAction(stepName: string, action: RecoveryAction): void;
+    /**
+     * Gets the registered recovery action for a step.
+     *
+     * @param stepName - The step name.
+     * @returns The recovery action if registered, otherwise undefined.
+     */
+    getAction(stepName: string): RecoveryAction | undefined;
+    /**
+     * Checks if a workflow has a pending recovery.
+     *
+     * @param workflowId - The workflow ID.
+     * @returns True if recovery is pending.
+     */
+    hasPendingRecovery(workflowId: string): boolean;
+    /**
+     * Gets the pending recovery details for a workflow.
+     *
+     * @param workflowId - The workflow ID.
+     * @returns The pending recovery details if any.
+     */
+    getPendingRecovery(workflowId: string): {
+        stepName: string;
+        error: Error;
+    } | undefined;
+    /**
+     * Marks a recovery as resolved.
+     *
+     * @param workflowId - The workflow ID.
+     */
+    resolveRecovery(workflowId: string): void;
+    /**
+     * Executes the registered recovery action for a step.
+     *
+     * @param stepName - The step name.
+     * @returns The recovery action result.
+     *
+     * @example
+     * ```typescript
+     * const action = manager.getAction('failed-step');
+     * if (action && action.type === 'manual') {
+     *   await manager.executeRecovery('failed-step');
+     * }
+     * ```
+     */
+    executeRecovery(stepName: string): Promise<void>;
+    /**
+     * Clears all registered actions.
+     */
+    clearActions(): void;
+    /**
+     * Clears all recovery callbacks.
+     */
+    clearCallbacks(): void;
+    /**
+     * Gets all pending recoveries.
+     *
+     * @returns A map of workflow IDs to pending recovery details.
+     */
+    getAllPendingRecoveries(): Map<string, {
+        stepName: string;
+        error: Error;
+    }>;
+    /**
+     * Clears all pending recoveries.
+     */
+    clearPendingRecoveries(): void;
+    /**
+     * Gets the count of registered callbacks.
+     * @internal For testing purposes.
+     */
+    getCallbackCount(): number;
+}
+
+/**
+ * The core execution engine for Flux workflows.
+ *
+ * FluxEngine manages the lifecycle of workflow execution, including persistence,
+ * state transitions, retries, and compensation (rollback) logic. It acts as the
+ * primary entry point for interacting with the workflow system.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine({
+ *   storage: new MemoryStorage(),
+ *   defaultRetries: 3
+ * });
+ * await engine.init();
+ * const result = await engine.execute(myWorkflow, { userId: '123' });
+ * ```
+ */
+declare class FluxEngine {
+    private storage;
+    private contextManager;
+    private traceEmitter;
+    private executor;
+    private rollbackManager;
+    private cronTrigger;
+    private dataOptimizer?;
+    constructor(config?: FluxConfig);
+    private config;
+    execute<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, input: TInput): Promise<FluxResult<TData>>;
+    executeBatch<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, inputs: TInput[], options?: BatchExecutionOptions): Promise<BatchResult<TData>>;
+    private executeWithLock;
+    resume<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, options?: {
+        fromStep?: number | string;
+    }): Promise<FluxResult<TData> | null>;
+    signal<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, signalName: string, payload?: any): Promise<FluxResult<TData>>;
+    retryStep<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, stepName: string): Promise<FluxResult<TData> | null>;
+    /**
+     * Retrieves the current state of a workflow instance from storage.
+     *
+     * @param workflowId - The unique identifier of the workflow.
+     * @returns A promise resolving to the workflow state or null if not found.
+     */
+    get<TInput = any, TData = any>(workflowId: string): Promise<WorkflowState<TInput, TData> | null>;
+    saveState<TInput, TData extends Record<string, any>>(state: WorkflowState<TInput, TData>): Promise<void>;
+    list(filter?: Parameters<WorkflowStorage['list']>[0]): Promise<WorkflowState<unknown, Record<string, any>>[]>;
+    schedule<TInput, TData extends Record<string, any>>(cron: string, workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, input: TInput, id?: string): string;
+    unschedule(id: string): void;
+    /**
+     * Lists all active workflow schedules.
+     */
+    listSchedules(): CronScheduleOptions[];
+    /**
+     * Gets the recovery manager for handling manual intervention.
+     */
+    getRecoveryManager(): RecoveryManager<unknown, Record<string, any>>;
+    /**
+     * Gets the lock provider used for cluster mode.
+     */
+    getLockProvider(): LockProvider | undefined;
+    /**
+     * Initializes the engine and its underlying storage, and starts the scheduler.
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the engine and releases storage resources.
+     */
+    close(): Promise<void>;
+    private persist;
+}
+
+/**
+ * Options for batch execution of workflows.
+ */
+interface BatchExecutionOptions {
+    /** Maximum concurrent workflow executions. @default 10 */
+    concurrency?: number;
+    /** Whether to continue on individual workflow failures. @default true */
+    continueOnError?: boolean;
+    /** Callback for progress updates */
+    onProgress?: (completed: number, total: number, result: BatchItemResult) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a single item in a batch execution.
+ */
+interface BatchItemResult<TData = any> {
+    /** Index in the batch */
+    index: number;
+    /** Input provided to this workflow */
+    input: unknown;
+    /** Execution result (null if failed before execution) */
+    result: FluxResult<TData> | null;
+    /** Error if failed */
+    error?: Error;
+    /** Whether this item succeeded */
+    success: boolean;
+}
+/**
+ * Result of a batch execution containing all individual results.
+ */
+interface BatchResult<TData = any> {
+    /** Total items in batch */
+    total: number;
+    /** Number of successful executions */
+    succeeded: number;
+    /** Number of failed executions */
+    failed: number;
+    /** Results for each item in order */
+    results: BatchItemResult<TData>[];
+    /** Total execution time in milliseconds */
+    duration: number;
+}
+/**
+ * Executes workflows in batches with controlled concurrency.
+ *
+ * BatchExecutor provides efficient parallel execution of multiple workflow instances
+ * while respecting concurrency limits, handling errors gracefully, and supporting
+ * cancellation via AbortSignal.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine()
+ * const executor = new BatchExecutor(engine)
+ *
+ * const results = await executor.execute(
+ *   myWorkflow,
+ *   [{ id: 1 }, { id: 2 }, { id: 3 }],
+ *   {
+ *     concurrency: 5,
+ *     onProgress: (completed, total) => console.log(`${completed}/${total}`)
+ *   }
+ * )
+ *
+ * console.log(`Succeeded: ${results.succeeded}, Failed: ${results.failed}`)
+ * ```
+ */
+declare class BatchExecutor {
+    private engine;
+    constructor(engine: FluxEngine);
+    /**
+     * Execute a workflow for multiple inputs with controlled concurrency.
+     *
+     * @param workflow - The workflow definition or builder to execute.
+     * @param inputs - Array of inputs, one per workflow execution.
+     * @param options - Execution options (concurrency, error handling, etc.).
+     * @returns Batch result containing all individual execution results.
+     */
+    execute<TInput, TData extends Record<string, any> = Record<string, any>>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, inputs: TInput[], options?: BatchExecutionOptions): Promise<BatchResult<TData>>;
+    /**
+     * Execute different workflows in a single batch.
+     *
+     * Unlike `execute()`, this method allows each item in the batch to use a different
+     * workflow definition, enabling heterogeneous batch processing.
+     *
+     * @param items - Array of workflow/input pairs to execute.
+     * @param options - Execution options (concurrency, error handling, etc.).
+     * @returns Batch result containing all individual execution results.
+     */
+    executeMany<TData = any>(items: Array<{
+        workflow: WorkflowDefinition<any, any>;
+        input: any;
+    }>, options?: BatchExecutionOptions): Promise<BatchResult<TData>>;
 }
 
-export { ContextManager, FluxConfig, FluxConsoleLogger, FluxEngine, FluxLogger, FluxResult, FluxSilentLogger, FluxTraceEvent, FluxTraceSink, JsonFileTraceSink, MemoryStorage, OrbitFlux, type OrbitFluxOptions, StateMachine, StepDefinition, StepExecution, StepExecutor, StepResult, WorkflowBuilder, WorkflowContext, WorkflowDefinition, WorkflowDescriptor, WorkflowFilter, WorkflowState, WorkflowStatus, WorkflowStorage, createWorkflow };
+export { type BatchExecutionOptions, BatchExecutor, type BatchItemResult, type BatchResult, ContextManager, FluxConfig, FluxConsoleLogger, FluxEngine, FluxLogger, FluxResult, FluxSilentLogger, FluxTraceEvent, FluxTraceSink, JsonFileTraceSink, Lock, LockProvider, MemoryStorage, OrbitFlux, type OrbitFluxOptions, PostgreSQLStorage, type PostgreSQLStorageOptions, type RedisClient, RedisLockProvider, type RedisLockProviderOptions, StateMachine, StepDefinition, StepExecution, StepExecutor, StepResult, WorkflowBuilder, WorkflowContext, WorkflowDefinition, WorkflowDescriptor, WorkflowFilter, WorkflowState, WorkflowStatus, WorkflowStorage, createWorkflow };