bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/client/workflow/compensationSupport.d.ts

@@ -0,0 +1,24 @@
+/** Pure record selection and context construction for saga compensation. */
+import { buildContext } from "./runner.js";
+import type { CompensationStatus, Execution, StepRecord } from "./types.js";
+import type { Workflow } from "./workflow.js";
+/**
+ * Eligible records in reverse start order. Failed records are included because their
+ * external effect may have succeeded before its response was lost.
+ */
+export declare function unwindSet(exec: Execution, wf: Workflow): [string, StepRecord][];
+export declare function settle(record: StepRecord, status: CompensationStatus, error?: string): void;
+/**
+ * Rebind a loop's bare step name to this occurrence and restore forEach item metadata.
+ */
+export declare function compensationContext(exec: Execution, baseCtx: ReturnType<typeof buildContext>, name: string, record: StepRecord): {
+    steps: {
+        [x: string]: unknown;
+    };
+    idempotencyKey: string;
+    forwardIdempotencyKey: string | undefined;
+    input: unknown;
+    signals: Readonly<Record<string, unknown>>;
+    executionId: string;
+    signal?: AbortSignal;
+};

package/dist/types/src/client/workflow/compensator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Public saga-compensation entry points.
+ *
+ * A pass is checkpointed per step, halts on an uncertain reversal, and is protected
+ * from overlapping in-process drivers. The execution mechanics live in
+ * compensationPass.ts; record selection lives in compensationSupport.ts.
+ */
+import type { LostCompensationClaim } from "./compensationClaim.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { WorkflowStore } from "./store.js";
+import type { Execution } from "./types.js";
+import type { Workflow } from "./workflow.js";
+export { AbandonedCompensationError, CommittedChildError } from "./compensationChild.js";
+/** Sentinel thrown when an execution deliberately parks for a signal. */
+export declare class WaitForSignalError extends Error {
+    readonly event: string;
+    constructor(event: string);
+}
+/**
+ * This is not a distributed lock. It prevents two local recovery/operator paths from
+ * reading the same unsettled snapshot and issuing the same reversal twice. A losing
+ * recovery path receives the current owner's completion latch and can retry safely.
+ */
+export type UnwindOutcome = 'ran' | LostCompensationClaim;
+/** Run compensation handlers in reverse start order for every eligible step. */
+export declare function runCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null, workflows?: Map<string, Workflow>, opts?: {
+    retryFailed?: boolean;
+    assertActive?: () => void;
+}): Promise<UnwindOutcome>;
+/**
+ * Give up on a parked unwind and record an explicit skipped outcome for every
+ * remaining eligible step.
+ */
+export declare function abandonCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null, assertActive?: () => void): void;

package/dist/types/src/client/workflow/definitionGuard.d.ts

@@ -0,0 +1,11 @@
+/** Runtime guard binding persisted executions to one sealed workflow graph. */
+import type { Execution } from "./types.js";
+import type { Workflow } from "./workflow.js";
+export declare class WorkflowDefinitionMismatchError extends Error {
+    constructor(executionId: string, workflowName: string);
+}
+/**
+ * Legacy rows have no hash; bind them once to the currently registered graph. New rows
+ * always arrive pre-bound by startExecution.
+ */
+export declare function bindExecutionDefinition(exec: Execution, workflow: Workflow, update: (exec: Execution) => void): void;

package/dist/types/src/client/workflow/emitter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WorkflowEmitter - Typed event system for workflow observability
+ */
+import type { WorkflowEventType, StepEvent, WorkflowLifecycleEvent, WorkflowEventListener, ExecutionState } from "./types.js";
+export declare class WorkflowEmitter {
+    private readonly listeners;
+    private readonly globalListeners;
+    on(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    onAny(listener: WorkflowEventListener): this;
+    off(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    offAny(listener: WorkflowEventListener): this;
+    emitStep(type: 'step:started' | 'step:completed' | 'step:failed' | 'step:retry' | 'compensation:started' | 'compensation:completed' | 'compensation:failed' | 'compensation:skipped', executionId: string, workflowName: string, stepName: string, extra?: Partial<Omit<StepEvent, 'type' | 'executionId' | 'workflowName' | 'timestamp' | 'stepName'>>): void;
+    emitWorkflow(type: 'workflow:started' | 'workflow:completed' | 'workflow:failed' | 'workflow:compensating' | 'workflow:waiting', executionId: string, workflowName: string, state: ExecutionState, extra?: Partial<Omit<WorkflowLifecycleEvent, 'type' | 'executionId' | 'workflowName' | 'timestamp' | 'state'>>): void;
+    emitSignal(type: 'signal:received' | 'signal:timeout', executionId: string, workflowName: string, event: string, payload?: unknown): void;
+    removeAllListeners(): void;
+    private dispatch;
+}

package/dist/types/src/client/workflow/engine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Engine - Public facade for the workflow engine
+ * Manages lifecycle of internal Queue, Worker, and Store.
+ */
+import type { Workflow } from "./workflow.js";
+import type { EngineOptions, RunHandle, Execution, ExecutionState, ExecutionListOptions, RecoverResult, WorkflowEventType, WorkflowEventListener } from "./types.js";
+export declare class Engine {
+    private readonly queue;
+    private readonly worker;
+    private readonly store;
+    private readonly executor;
+    private readonly emitter;
+    constructor(opts?: EngineOptions);
+    /** Register a workflow definition */
+    register(workflow: Workflow): this;
+    /** Start a new workflow execution */
+    start(workflowName: string, input?: unknown): Promise<RunHandle>;
+    /** Get execution state by ID */
+    getExecution(id: string): Execution | null;
+    /** List executions with optional filters */
+    listExecutions(workflowName?: string, state?: ExecutionState, options?: ExecutionListOptions): Execution[];
+    /**
+     * Retry the compensation that parked a `compensation-stuck` run and continue the
+     * unwind. Use once the cause of the failed reversal has been fixed.
+     */
+    resumeCompensation(executionId: string): Promise<void>;
+    /**
+     * Abandon a parked unwind: the steps still un-compensated are recorded as skipped
+     * and the run becomes terminal. Partial, but explicitly so.
+     */
+    /**
+     * `async` on purpose, even though the work is synchronous: `resumeCompensation` is
+     * async, and an operator writing recovery code under pressure reaches for
+     * `Promise.allSettled([resume(id), abandon(id)])`. With a sync throw that expression
+     * throws before `allSettled` is ever called, so the defensive form is the one that
+     * blows up. Matching the sibling costs nothing while the API is experimental.
+     */
+    abandonCompensation(executionId: string): Promise<void>;
+    /** Send a signal to a waiting execution */
+    signal(executionId: string, event: string, payload?: unknown): Promise<void>;
+    /**
+     * Recover orphaned executions after a crash/restart.
+     * - 'running' executions: re-enqueued at their current step
+     * - 'waiting' executions: timeout timers re-armed (or resumed if signal arrived)
+     * - 'compensating' executions: compensation re-run (handlers must be idempotent)
+     */
+    recover(): Promise<RecoverResult>;
+    /** Subscribe to a specific workflow event type */
+    on(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    /** Subscribe to all workflow events */
+    onAny(listener: WorkflowEventListener): this;
+    /** Unsubscribe from a specific event type */
+    off(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    /** Unsubscribe a catch-all listener */
+    offAny(listener: WorkflowEventListener): this;
+    /** Subscribe to all events for a specific execution */
+    subscribe(executionId: string, callback: WorkflowEventListener): () => void;
+    /** Remove old completed/failed executions */
+    cleanup(maxAgeMs: number, states?: ExecutionState[]): number;
+    /** Archive old executions to a separate table */
+    archive(maxAgeMs: number, states?: ExecutionState[]): number;
+    /** Get archived execution count */
+    getArchivedCount(): number;
+    /** Shut down the engine */
+    close(force?: boolean): Promise<void>;
+}

package/dist/types/src/client/workflow/eventTypes.d.ts

@@ -0,0 +1,44 @@
+/** Workflow event and engine configuration types. */
+import type { ConnectionOptions } from "../types.js";
+import type { ExecutionState } from "./executionTypes.js";
+/** All workflow event types */
+export type WorkflowEventType = 'step:started' | 'step:completed' | 'step:failed' | 'step:retry' | 'workflow:started' | 'workflow:completed' | 'workflow:failed' | 'workflow:compensating' | 'workflow:waiting' | 'signal:received' | 'signal:timeout' | 'compensation:started' | 'compensation:completed' | 'compensation:failed' | 'compensation:skipped';
+/** Base event payload */
+export interface WorkflowEvent {
+    type: WorkflowEventType;
+    executionId: string;
+    workflowName: string;
+    timestamp: number;
+}
+/** Step-level event payload */
+export interface StepEvent extends WorkflowEvent {
+    stepName: string;
+    result?: unknown;
+    error?: string;
+    attempt?: number;
+    maxAttempts?: number;
+}
+/** Workflow lifecycle event payload */
+export interface WorkflowLifecycleEvent extends WorkflowEvent {
+    state: ExecutionState;
+    input?: unknown;
+}
+/** Signal event payload */
+export interface SignalEvent extends WorkflowEvent {
+    event: string;
+    payload?: unknown;
+}
+/** Event listener function */
+export type WorkflowEventListener = (event: WorkflowEvent | StepEvent | WorkflowLifecycleEvent | SignalEvent) => void;
+/** Engine configuration */
+export interface EngineOptions {
+    embedded?: boolean;
+    dataPath?: string;
+    connection?: ConnectionOptions;
+    /** Internal queue name (default: __wf:steps) */
+    queueName?: string;
+    /** Worker concurrency (default: 5) */
+    concurrency?: number;
+    /** Global event listener for observability */
+    onEvent?: WorkflowEventListener;
+}

package/dist/types/src/client/workflow/executionFence.d.ts

@@ -0,0 +1,15 @@
+/** Lifecycle fence shared by every asynchronous workflow execution path. */
+/** Internal control-flow signal used to abandon work owned by a closed Engine. */
+export declare class WorkflowExecutionClosedError extends Error {
+    constructor();
+}
+export declare function isWorkflowExecutionClosed(error: unknown): boolean;
+/** A graceful close leaves this active; only close(true) aborts in-flight control flow. */
+export declare class WorkflowExecutionFence {
+    private readonly controller;
+    readonly assertActive: () => void;
+    isActive(): boolean;
+    close(force: boolean): void;
+}
+/** Default for isolated runner tests that do not own an Engine lifecycle. */
+export declare const assertWorkflowActive: () => void;

package/dist/types/src/client/workflow/executionTypes.d.ts

@@ -0,0 +1,133 @@
+/** Persisted workflow execution, step outcome, and store coordination types. */
+/** Execution state */
+export type ExecutionState = 'running' | 'waiting' | 'completed' | 'failed' | 'compensating'
+/**
+ * A compensation failed definitively and the unwind stopped. Deliberately NOT
+ * terminal: the run parks until an operator retries or abandons the unwind.
+ */
+ | 'compensation-stuck';
+/** What the engine did after a failure, independently of the failure reason. */
+export type RollbackStatus = 
+/** Every eligible step was compensated successfully. */
+'completed'
+/** The unwind ran past the pivot cutoff or had nothing left to do. */
+ | 'not-applicable'
+/** A compensation failed definitively; remaining reversals were not attempted. */
+ | 'stuck';
+/** Step execution state */
+export type StepState = 'pending' | 'running' | 'completed' | 'failed';
+/** Terminal outcome of one step's rollback. */
+export type CompensationStatus = 'compensated' | 'compensation-failed' | 'compensation-skipped';
+export interface CompensationOutcome {
+    status: CompensationStatus;
+    at: number;
+    /** Why it failed, or why it was skipped. */
+    error?: string;
+}
+/** Record of a step's execution */
+export interface StepRecord {
+    status: StepState;
+    result?: unknown;
+    error?: string;
+    startedAt?: number;
+    completedAt?: number;
+    attempts?: number;
+    /**
+     * Whether this step declared a compensate handler when it ran. This survives a
+     * deployment that removes or renames the definition.
+     */
+    compensatable?: boolean;
+    /** forEach iteration item — persisted so compensation can restore __item */
+    loopItem?: unknown;
+    /** forEach iteration index — persisted so compensation can restore __index */
+    loopIndex?: number;
+    /** Exactly one terminal compensation outcome for every eligible step. */
+    compensation?: CompensationOutcome;
+    /** Idempotency key of the forward execution, persisted before the body runs. */
+    idempotencyKey?: string;
+    /** Child execution owned by a sub-workflow record. */
+    childExecutionId?: string;
+    /** Occurrence of this step name within the run — loops reuse a single name. */
+    occurrence?: number;
+}
+/** Full persisted execution state */
+export interface Execution {
+    id: string;
+    workflowName: string;
+    state: ExecutionState;
+    input: unknown;
+    steps: Record<string, StepRecord>;
+    currentNodeIndex: number;
+    /** Flattened names selected by resolved branch paths. */
+    resolvedSteps?: string[];
+    /** Durable results of control-flow decisions, keyed by node/iteration identity. */
+    decisions?: Record<string, unknown>;
+    /** Structural identity of the sealed workflow definition that started this run. */
+    definitionHash?: string;
+    /** What happened to the rollback. Independent of `failureReason`. */
+    rollbackStatus?: RollbackStatus;
+    /** Why the run failed. Independent of `rollbackStatus`. */
+    failureReason?: string;
+    /**
+     * Node index at which `.pivot()` committed. Once set, backward recovery is off for
+     * the whole saga and recovery is forward-only.
+     */
+    committedAt?: number;
+    signals: Record<string, unknown>;
+    /** Parent execution that owns this sub-workflow child. */
+    parentExecutionId?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Handle returned from engine.start() */
+export interface RunHandle {
+    id: string;
+    workflowName: string;
+}
+/** Stable, bounded pagination for execution listings. */
+export interface ExecutionListOptions {
+    /** Page size. Defaults to 100 and is capped at 1000. */
+    limit?: number;
+    /** Number of rows to skip in the deterministic createdAt/id order. */
+    offset?: number;
+}
+/** Internal job data for step execution */
+export interface StepJobData {
+    executionId: string;
+    workflowName: string;
+    nodeIndex: number;
+}
+/** Result of engine.recover() */
+export interface RecoverResult {
+    /** Number of running executions re-enqueued */
+    running: number;
+    /** Number of waiting executions with re-armed timers */
+    waiting: number;
+    /** Number of compensating executions re-run */
+    compensating: number;
+    /** Total recovered */
+    total: number;
+}
+/** Result of WorkflowStore.recordSignal() */
+export interface SignalOutcome {
+    /** Whether the execution row exists */
+    found: boolean;
+    /** True for the single caller that claimed the resume of a parked run */
+    resumed: boolean;
+    workflowName: string;
+    currentNodeIndex: number;
+}
+/** Result of WorkflowStore.parkForSignal() */
+export interface ParkOutcome {
+    /** The awaited signal was already recorded — advance instead of parking */
+    signalPresent: boolean;
+    /** This caller transitioned the run to 'waiting' */
+    parked: boolean;
+    /** Signals as persisted, for refreshing a stale in-memory snapshot */
+    signals: Record<string, unknown>;
+}
+/** Options for cleanup */
+export interface CleanupOptions {
+    maxAge: number;
+    states?: ExecutionState[];
+}

package/dist/types/src/client/workflow/executor.d.ts

@@ -0,0 +1,52 @@
+/** WorkflowExecutor - Core execution logic */
+import type { Queue } from "../queue/queue.js";
+import type { Workflow } from "./workflow.js";
+import type { WorkflowStore } from "./store.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { Execution, ExecutionListOptions, StepJobData, RunHandle, RecoverResult } from "./types.js";
+export declare class WorkflowExecutor {
+    private readonly store;
+    private readonly queue;
+    private readonly emitter;
+    private readonly workflows;
+    private readonly timeoutTimers;
+    private readonly fence;
+    /**
+     * Release every armed waitFor timer. The engine owns the executor's lifetime, so
+     * `Engine.close()` must call this: an armed timer would otherwise fire into a
+     * closing queue, and a caller that keeps the process alive after closing one engine
+     * has no other handle on them.
+     */
+    close(force?: boolean): void;
+    private readonly updateFn;
+    constructor(store: WorkflowStore, queue: Queue, emitter?: WorkflowEmitter | null);
+    register(workflow: Workflow): void;
+    start(workflowName: string, input: unknown, parentExecutionId?: string): Promise<RunHandle>;
+    /**
+     * Nodes this process is currently executing, keyed `<execution>:<nodeIndex>`.
+     *
+     * The cursor rejects stale jobs but not two overlapping deliveries for the current
+     * node. This process-local claim drops that overlap. Queue-level dedup is unsuitable:
+     * a retained ID can swallow a legitimate recovery enqueue and wedge the run.
+     */
+    private readonly nodesInFlight;
+    processStep(data: StepJobData): Promise<unknown>;
+    private runNode;
+    signal(executionId: string, event: string, payload: unknown): Promise<void>;
+    private get lifecycleDeps();
+    /** Retry the compensation that parked the run, then finish the unwind. */
+    resumeCompensation(executionId: string): Promise<void>;
+    /** Give up on a parked unwind, recording the outstanding steps as skipped. */
+    abandonCompensation(executionId: string): void;
+    private get rollbackDeps();
+    getExecution(id: string): Execution | null;
+    listExecutions(wfName?: string, state?: Execution['state'], options?: ExecutionListOptions): Execution[];
+    private get nodeDeps();
+    private advance;
+    private enqueue;
+    private get waitForDeps();
+    private scheduleTimeoutCheck;
+    private compensate;
+    /** Recover orphaned executions after a crash/restart */
+    recover(): Promise<RecoverResult>;
+}

package/dist/types/src/client/workflow/executorLifecycle.d.ts

@@ -0,0 +1,19 @@
+/** Durable start and signal publication for WorkflowExecutor. */
+import type { Queue } from "../queue/queue.js";
+import { type TimerHandle } from "./clock.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { WorkflowStore } from "./store.js";
+import type { Execution, RunHandle } from "./types.js";
+import type { Workflow } from "./workflow.js";
+interface LifecycleDeps {
+    store: WorkflowStore;
+    queue: Queue;
+    workflows: ReadonlyMap<string, Workflow>;
+    emitter: WorkflowEmitter | null;
+    timers: Map<string, TimerHandle>;
+    enqueue: (exec: Execution) => Promise<void>;
+    assertActive: () => void;
+}
+export declare function startExecution(deps: LifecycleDeps, workflowName: string, input: unknown, parentExecutionId?: string): Promise<RunHandle>;
+export declare function signalExecution(deps: LifecycleDeps, executionId: string, event: string, payload: unknown): Promise<void>;
+export {};

package/dist/types/src/client/workflow/executorNodes.d.ts

@@ -0,0 +1,18 @@
+/** Workflow node dispatch, split from the executor's lifecycle orchestration. */
+import type { WorkflowEmitter } from "./emitter.js";
+import type { WorkflowStore } from "./store.js";
+import type { Execution, RunHandle, WorkflowNode } from "./types.js";
+import { type WaitForDeps } from "./waitFor.js";
+import type { Workflow } from "./workflow.js";
+interface NodeExecutionDeps {
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    updateFn: (exec: Execution) => void;
+    advance: (exec: Execution, nextIdx: number, workflow: Workflow) => Promise<void>;
+    start: (name: string, input: unknown, parentId: string) => Promise<RunHandle>;
+    enqueue: (exec: Execution) => Promise<void>;
+    waitFor: WaitForDeps;
+    assertActive: () => void;
+}
+export declare function executeWorkflowNode(deps: NodeExecutionDeps, exec: Execution, node: WorkflowNode, idx: number, wf: Workflow): Promise<void>;
+export {};

package/dist/types/src/client/workflow/executorQueue.d.ts

@@ -0,0 +1,9 @@
+/** Durable workflow-node publication shared by execution and recovery. */
+import type { Queue } from "../queue/queue.js";
+import type { Execution } from "./types.js";
+/**
+ * Publish one node without a deterministic job ID. The cursor and in-flight guards
+ * discard overlapping duplicates, while queue-level dedup could suppress a legitimate
+ * re-enqueue after recovery and wedge the execution permanently.
+ */
+export declare function enqueueWorkflowStep(queue: Queue, exec: Execution, assertActive: () => void): Promise<void>;

package/dist/types/src/client/workflow/forEachRunner.d.ts

@@ -0,0 +1,4 @@
+/** Durable forEach execution, split from conditional loop runners. */
+import type { Execution, ForEachDefinition } from "./types.js";
+import type { WorkflowEmitter } from "./emitter.js";
+export declare function executeForEach(def: ForEachDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;

package/dist/types/src/client/workflow/identity.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Idempotency identity for saga steps.
+ *
+ * The key is a function of (run, step name, occurrence, direction) and deliberately
+ * NOT of the attempt number. That is the single most common way to get this wrong:
+ * derive it from the attempt and every automatic retry asks the provider for a
+ * brand-new charge instead of being deduplicated into the first one.
+ *
+ * The three retry semantics collapse into two key behaviours:
+ *
+ *   automatic retry after a transient error -> SAME key (we do not know whether the
+ *   crash-and-resume of the same run       -> SAME key  effect landed; we want dedup)
+ *   a different run of the same logic       -> different key (different run id)
+ *
+ * `occurrence` exists because loop bodies reuse one step name. It is taken from the
+ * loop's iteration index rather than a running counter precisely so that it stays
+ * stable when a resumed loop replays its earlier iterations: replaying iteration 2
+ * must present the key iteration 2 already used, or the provider bills twice.
+ */
+export type Direction = 'forward' | 'compensate';
+/** Opaque 128-bit execution identity, deterministic under the simulated clock. */
+export declare function newExecutionId(): string;
+export declare function idempotencyKey(runId: string, stepName: string, occurrence: number, direction: Direction): string;
+/**
+ * A loop iteration record is `<step>:<digits>` and nothing else.
+ *
+ * Three separate defects came from treating "contains a colon" as the test: a step
+ * legitimately named `charge:extra` was resolved to a loop body called `charge`, was
+ * dropped from the unwind set, and had its compensate context rebound to another
+ * step's result. A colon is a legal character in a user-chosen step name; only the
+ * numeric suffix this engine appends is structural.
+ */
+export declare const LOOP_ITERATION_SUFFIX: RegExp;
+/** Is `name` an iteration record of the loop body step `base`? */
+export declare function isIterationOf(name: string, base: string): boolean;
+/** `charge:2` -> `charge`; `charge:extra` -> `charge:extra` (not an iteration). */
+export declare function loopBaseName(name: string): string;
+/**
+ * A human-readable description of anything that was thrown.
+ *
+ * `String(err)` is what this replaced, and for the shape an HTTP client throws most
+ * often, a structured object, it yields `"[object Object]"`. That string was then
+ * persisted as the diagnostic on a run parked in `compensation-stuck`, which is the
+ * state that exists so an operator has something to act on. They were handed a
+ * sentence that says nothing about a refund that did not go through
+ * (`test/repro-workflow-operator-signal.test.ts`).
+ */
+export declare function describeError(err: unknown): string;

package/dist/types/src/client/workflow/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * bunqueue Workflow Engine
+ *
+ * Lightweight workflow orchestration built on top of bunqueue.
+ *
+ * @example
+ * ```typescript
+ * import { Workflow, Engine } from 'bunqueue/workflow';
+ *
+ * const flow = new Workflow('onboarding')
+ *   .step('create', async (ctx) => { ... })
+ *   .step('notify', async (ctx) => { ... });
+ *
+ * const engine = new Engine({ embedded: true });
+ * engine.register(flow);
+ * const run = await engine.start('onboarding', { email: 'user@test.com' });
+ * ```
+ */
+import "../../require-bun.js";
+export { Workflow } from "./workflow.js";
+export { Engine } from "./engine.js";
+export { WorkflowEmitter } from "./emitter.js";
+export type { StepContext, StepHandler, TypedStepHandler, CompensateHandler, TypedCompensateHandler, StepOptions, SchemaLike, Execution, ExecutionState, ExecutionListOptions, StepState, StepRecord, RollbackStatus, CompensationStatus, CompensationOutcome, BranchCondition, WorkflowNode, EngineOptions, RunHandle, ParallelDefinition, SubWorkflowInputMapper, SubWorkflowOptions, LoopCondition, ForEachItemsExtractor, MapTransformFn, LoopDefinition, ForEachDefinition, MapDefinition, RecoverResult, CleanupOptions, WorkflowEventType, WorkflowEvent, StepEvent, WorkflowLifecycleEvent, SignalEvent, WorkflowEventListener, } from "./types.js";

package/dist/types/src/client/workflow/loops.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Loop execution logic for the Workflow Engine.
+ */
+import type { Execution, LoopDefinition } from "./types.js";
+import type { WorkflowEmitter } from "./emitter.js";
+export { executeMap } from "./mapRunner.js";
+export { executeForEach } from "./forEachRunner.js";
+/** Execute a doUntil loop: run steps, then check condition. Repeat until condition returns true. */
+export declare function executeDoUntil(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;
+/** Execute a doWhile loop: check condition first, then run steps. Repeat while condition is true. */
+export declare function executeDoWhile(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;

package/dist/types/src/client/workflow/mapRunner.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowEmitter } from "./emitter.js";
+import type { Execution, MapDefinition } from "./types.js";
+/** Execute a map node with the same durable lifecycle signals as a regular step. */
+export declare function executeMap(def: MapDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;

package/dist/types/src/client/workflow/recovery.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Recovery logic for orphaned workflow executions after crash/restart
+ *
+ * Handles three states:
+ * - 'running': re-enqueue the step at currentNodeIndex
+ * - 'waiting': re-arm timeout timer or resume if signal already arrived
+ * - 'compensating': re-run compensation from the beginning (must be idempotent)
+ */
+import type { Queue } from "../queue/queue.js";
+import type { Workflow } from "./workflow.js";
+import type { WorkflowStore } from "./store.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { RecoverResult } from "./types.js";
+import { type TimerHandle } from "./clock.js";
+export interface RecoverDeps {
+    store: WorkflowStore;
+    queue: Queue;
+    workflows: Map<string, Workflow>;
+    emitter: WorkflowEmitter | null;
+    timeoutTimers: Map<string, TimerHandle>;
+    scheduleTimeoutCheck: (id: string, wfName: string, nodeIdx: number, ms: number) => void;
+    /**
+     * Nodes this engine is executing right now. Recovery consults it for the same reason
+     * the `compensating` branch consults the unwind claim: re-enqueueing a node that is
+     * already in flight produces a job the admission check will reject, and counting it
+     * as a recovery reports work that did not happen. A step running without a bound is
+     * the ordinary way to reach this.
+     */
+    nodesInFlight: ReadonlySet<string>;
+    assertActive: () => void;
+}
+export declare function recoverExecutions(deps: RecoverDeps): Promise<RecoverResult>;

package/dist/types/src/client/workflow/rollbackControl.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Operator actions on a parked unwind.
+ *
+ * A `compensation-stuck` run is waiting for a human decision, which is why the state
+ * is not terminal: the engine has done everything it safely can, and the remaining
+ * choice, was the reversal fixed or do we accept a partial rollback, is not one it can
+ * make. Both exits are explicit, and both leave the execution record saying exactly
+ * what happened.
+ */
+import type { Workflow } from "./workflow.js";
+import type { WorkflowStore } from "./store.js";
+import type { WorkflowEmitter } from "./emitter.js";
+export interface RollbackDeps {
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    workflows: Map<string, Workflow>;
+    assertActive: () => void;
+}
+/**
+ * Retry the compensation that parked the run, then carry on with the rest.
+ *
+ * The retry is asked for with a FLAG rather than by clearing the failed outcome first.
+ * Clearing worked, and it cost more than it bought: it wiped the operator's
+ * `compensation-failed` record in memory and persisted that wipe BEFORE running
+ * anything, so a resume that then met a failing store left a run whose durable row had
+ * lost the very diagnostic the operator was acting on, sitting in `compensating` and
+ * therefore handed back by `listRecoverable()` at every subsequent startup. Guarding
+ * that needed a deep snapshot, a restore path, and a second write which could itself
+ * throw and mask the original error.
+ *
+ * None of that machinery is needed if nothing is destroyed in the first place. The
+ * record stays until a real outcome replaces it, and a store that fails simply leaves
+ * the parked run exactly as the operator found it.
+ */
+export declare function resumeCompensation(deps: RollbackDeps, executionId: string): Promise<void>;
+/** Accept a partial rollback: the outstanding steps are recorded as skipped. */
+export declare function abandonParkedCompensation(deps: RollbackDeps, executionId: string): void;

package/dist/types/src/client/workflow/runner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WorkflowRunner - Step execution with retry, parallel execution, sub-workflow dispatch
+ */
+import type { StepDefinition, StepContext, Execution } from "./types.js";
+import type { Workflow } from "./workflow.js";
+import type { WorkflowEmitter } from "./emitter.js";
+export { runWithTimeout } from "./runnerTiming.js";
+export { executeSubWorkflow } from "./subWorkflowRunner.js";
+/** Engine hooks a step needs; they always travel together. */
+export interface StepHooks {
+    emitter: WorkflowEmitter | null;
+    updateFn: (exec: Execution) => void;
+    assertActive?: () => void;
+}
+export { isWorkflowExecutionClosed, WorkflowExecutionClosedError } from "./executionFence.js";
+/** Execute a step with retry logic and exponential backoff */
+export declare function executeStepWithRetry(def: StepDefinition, ctx: StepContext, exec: Execution, hooks: StepHooks, occurrence?: number): Promise<void>;
+/** Execute multiple steps in parallel via Promise.allSettled */
+export declare function executeParallelSteps(steps: StepDefinition[], ctx: StepContext, exec: Execution, hooks: StepHooks): Promise<void>;
+/** Find a step definition by name across all node types */
+export declare function findStepDef(wf: Workflow, name: string): StepDefinition | null;
+/** Build a StepContext from the current execution state */
+export declare function buildContext(exec: Execution): StepContext;