bunqueue 2.8.0 → 2.8.2

package/dist/client/workflow/executor.js

@@ -1,22 +1,21 @@
-import { executeStepWithRetry, executeParallelSteps, executeSubWorkflow, findStepDef, buildContext, } from './runner';
+import { executeStepWithRetry, executeParallelSteps, executeSubWorkflow, buildContext, } from './runner';
 import { executeDoUntil, executeDoWhile, executeForEach, executeMap } from './loops';
-class WaitForSignalError extends Error {
-    event;
-    constructor(event) {
-        super(`Waiting for signal: ${event}`);
-        this.event = event;
-    }
-}
+import { WaitForSignalError, runCompensation } from './compensator';
+import { recoverExecutions } from './recovery';
 export class WorkflowExecutor {
     store;
     queue;
     emitter;
     workflows = new Map();
     timeoutTimers = new Map();
+    updateFn;
     constructor(store, queue, emitter = null) {
         this.store = store;
         this.queue = queue;
         this.emitter = emitter;
+        this.updateFn = (e) => {
+            this.store.update(e);
+        };
     }
     register(workflow) {
         const names = workflow.getStepNames();
@@ -33,8 +32,9 @@ export class WorkflowExecutor {
         if (wf.nodes.length === 0)
             throw new Error(`Workflow "${workflowName}" has no steps`);
         const now = Date.now();
+        const id = `wf_${now}_${Math.random().toString(36).slice(2, 10)}`;
         const exec = {
-            id: `wf_${now}_${Math.random().toString(36).slice(2, 10)}`,
+            id,
             workflowName,
             state: 'running',
             input,
@@ -45,9 +45,9 @@ export class WorkflowExecutor {
             updatedAt: now,
         };
         this.store.save(exec);
-        this.emitter?.emitWorkflow('workflow:started', exec.id, workflowName, 'running', { input });
+        this.emitter?.emitWorkflow('workflow:started', id, workflowName, 'running', { input });
         await this.enqueue(exec);
-        return { id: exec.id, workflowName };
+        return { id, workflowName };
     }
     async processStep(data) {
         const exec = this.store.get(data.executionId);
@@ -84,7 +84,6 @@ export class WorkflowExecutor {
         const exec = this.store.get(executionId);
         if (!exec)
             throw new Error(`Execution "${executionId}" not found`);
-        // Cancel any pending timeout timer for this execution
         const timer = this.timeoutTimers.get(executionId);
         if (timer) {
             clearTimeout(timer);
@@ -99,8 +98,8 @@ export class WorkflowExecutor {
     getExecution(id) {
         return this.store.get(id);
     }
-    listExecutions(workflowName, state) {
-        return this.store.list(workflowName, state);
+    listExecutions(wfName, state) {
+        return this.store.list(wfName, state);
     }
     async executeNode(exec, node, idx, wf) {
         if (node.type === 'step')
@@ -124,9 +123,7 @@ export class WorkflowExecutor {
     }
     async runStep(exec, def, idx, wf) {
         const ctx = buildContext(exec);
-        await executeStepWithRetry(def, ctx, exec, this.emitter, (e) => {
-            this.store.update(e);
-        });
+        await executeStepWithRetry(def, ctx, exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async runBranch(exec, node, idx, wf) {
@@ -134,17 +131,13 @@ export class WorkflowExecutor {
         const pathSteps = node.def.paths.get(pathName);
         if (pathSteps && pathSteps.length > 0) {
             for (const step of pathSteps) {
-                await executeStepWithRetry(step, buildContext(exec), exec, this.emitter, (e) => {
-                    this.store.update(e);
-                });
+                await executeStepWithRetry(step, buildContext(exec), exec, this.emitter, this.updateFn);
             }
         }
         await this.advance(exec, idx + 1, wf);
     }
     async runParallel(exec, node, idx, wf) {
-        await executeParallelSteps(node.def.steps, buildContext(exec), exec, this.emitter, (e) => {
-            this.store.update(e);
-        });
+        await executeParallelSteps(node.def.steps, buildContext(exec), exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async runSubWorkflow(exec, node, idx, wf) {
@@ -162,24 +155,26 @@ export class WorkflowExecutor {
         if (node.timeout !== undefined) {
             const existing = exec.steps[waitKey];
             const waitingSince = existing?.startedAt ?? Date.now();
-            if (!existing) {
+            if (!existing)
                 exec.steps[waitKey] = { status: 'running', startedAt: waitingSince };
-            }
             if (Date.now() - waitingSince >= node.timeout) {
                 this.emitter?.emitSignal('signal:timeout', exec.id, exec.workflowName, node.event);
                 exec.steps[waitKey] = {
                     status: 'failed',
-                    error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
                     startedAt: waitingSince,
                     completedAt: Date.now(),
+                    error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
                 };
                 exec.state = 'failed';
                 this.store.update(exec);
+                // Compensate here, then signal completion via the WaitForSignalError
+                // sentinel so processStep short-circuits (return null) instead of
+                // re-running compensation through its generic catch path.
                 await this.compensate(exec, wf);
-                throw new Error(`Signal "${node.event}" timed out`);
+                this.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
+                throw new WaitForSignalError(node.event);
             }
             this.store.update(exec);
-            // Schedule a timer to re-check after timeout
             const remaining = node.timeout - (Date.now() - waitingSince);
             this.scheduleTimeoutCheck(exec.id, exec.workflowName, exec.currentNodeIndex, remaining);
         }
@@ -189,21 +184,15 @@ export class WorkflowExecutor {
         throw new WaitForSignalError(node.event);
     }
     async runLoop(exec, node, idx, wf, loopFn) {
-        await loopFn(node.def, exec, this.emitter, (e) => {
-            this.store.update(e);
-        });
+        await loopFn(node.def, exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async runForEach(exec, node, idx, wf) {
-        await executeForEach(node.def, exec, this.emitter, (e) => {
-            this.store.update(e);
-        });
+        await executeForEach(node.def, exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async runMap(exec, node, idx, wf) {
-        await executeMap(node.def, exec, (e) => {
-            this.store.update(e);
-        });
+        await executeMap(node.def, exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async advance(exec, nextIdx, wf) {
@@ -230,33 +219,26 @@ export class WorkflowExecutor {
         const timer = setTimeout(() => {
             this.timeoutTimers.delete(execId);
             const jobData = { executionId: execId, workflowName, nodeIndex: nodeIdx };
-            this.queue.add('wf:step', jobData).catch(() => { }); // Queue may be closed
+            this.queue.add('wf:step', jobData).catch(() => {
+                /* Queue may be closed */
+            });
         }, ms);
         this.timeoutTimers.set(execId, timer);
     }
     async compensate(exec, wf) {
-        const completed = Object.entries(exec.steps)
-            .filter(([name, s]) => s.status === 'completed' && !name.startsWith('__'))
-            .reverse();
-        if (completed.length === 0)
-            return;
-        exec.state = 'compensating';
-        this.store.update(exec);
-        this.emitter?.emitWorkflow('workflow:compensating', exec.id, exec.workflowName, 'compensating');
-        const ctx = buildContext(exec);
-        for (const [name] of completed) {
-            const def = findStepDef(wf, name);
-            if (def?.compensate) {
-                try {
-                    await def.compensate(ctx);
-                }
-                catch {
-                    // Compensation errors don't stop the chain
-                }
-            }
-        }
-        exec.state = 'failed';
-        this.store.update(exec);
+        await runCompensation(exec, wf, this.store, this.emitter);
+    }
+    /** Recover orphaned executions after a crash/restart */
+    async recover() {
+        return recoverExecutions({
+            store: this.store,
+            queue: this.queue,
+            workflows: this.workflows,
+            emitter: this.emitter,
+            timeoutTimers: this.timeoutTimers,
+            scheduleTimeoutCheck: (id, name, idx, ms) => {
+                this.scheduleTimeoutCheck(id, name, idx, ms);
+            },
+        });
     }
 }
-//# sourceMappingURL=executor.js.map

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

@@ -19,5 +19,4 @@
 export { Workflow } from './workflow';
 export { Engine } from './engine';
 export { WorkflowEmitter } from './emitter';
-export type { StepContext, StepHandler, CompensateHandler, StepOptions, SchemaLike, Execution, ExecutionState, StepState, StepRecord, EngineOptions, RunHandle, ParallelDefinition, SubWorkflowInputMapper, LoopCondition, ForEachItemsExtractor, MapTransformFn, LoopDefinition, ForEachDefinition, MapDefinition, CleanupOptions, WorkflowEventType, WorkflowEvent, StepEvent, WorkflowLifecycleEvent, SignalEvent, WorkflowEventListener, } from './types';
-//# sourceMappingURL=index.d.ts.map
+export type { StepContext, StepHandler, TypedStepHandler, CompensateHandler, TypedCompensateHandler, StepOptions, SchemaLike, Execution, ExecutionState, StepState, StepRecord, EngineOptions, RunHandle, ParallelDefinition, SubWorkflowInputMapper, LoopCondition, ForEachItemsExtractor, MapTransformFn, LoopDefinition, ForEachDefinition, MapDefinition, RecoverResult, CleanupOptions, WorkflowEventType, WorkflowEvent, StepEvent, WorkflowLifecycleEvent, SignalEvent, WorkflowEventListener, } from './types';

package/dist/client/workflow/index.js

@@ -19,4 +19,3 @@
 export { Workflow } from './workflow';
 export { Engine } from './engine';
 export { WorkflowEmitter } from './emitter';
-//# sourceMappingURL=index.js.map

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

@@ -11,5 +11,4 @@ export declare function executeDoWhile(def: LoopDefinition, exec: Execution, emi
 /** Execute a forEach loop: iterate over items, executing the step for each */
 export declare function executeForEach(def: ForEachDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;
 /** Execute a map node: transform step results into a new value */
-export declare function executeMap(def: MapDefinition, exec: Execution, updateFn: (exec: Execution) => void): Promise<void>;
-//# sourceMappingURL=loops.d.ts.map
+export declare function executeMap(def: MapDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;

package/dist/client/workflow/loops.js

@@ -59,11 +59,19 @@ export async function executeForEach(def, exec, emitter, updateFn) {
         };
         const stepCtx = buildContext(exec);
         await executeStepWithRetry(indexedStep, stepCtx, exec, emitter, updateFn);
+        // Persist this iteration's __item/__index alongside the step record so
+        // saga compensation can restore the correct per-iteration context later.
+        // executeStepWithRetry has just written this record (it throws otherwise).
+        const record = exec.steps[indexedName];
+        record.loopItem = item;
+        record.loopIndex = i;
+        updateFn(exec);
     }
 }
 /** Execute a map node: transform step results into a new value */
-export async function executeMap(def, exec, updateFn) {
+export async function executeMap(def, exec, emitter, updateFn) {
     const ctx = buildContext(exec);
+    emitter?.emitStep('step:started', exec.id, exec.workflowName, def.name);
     const result = await def.transform(ctx);
     exec.steps[def.name] = {
         status: 'completed',
@@ -72,5 +80,5 @@ export async function executeMap(def, exec, updateFn) {
         completedAt: Date.now(),
     };
     updateFn(exec);
+    emitter?.emitStep('step:completed', exec.id, exec.workflowName, def.name, { result });
 }
-//# sourceMappingURL=loops.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * 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';
+import type { Workflow } from './workflow';
+import type { WorkflowStore } from './store';
+import type { WorkflowEmitter } from './emitter';
+import type { RecoverResult } from './types';
+export interface RecoverDeps {
+    store: WorkflowStore;
+    queue: Queue;
+    workflows: Map<string, Workflow>;
+    emitter: WorkflowEmitter | null;
+    timeoutTimers: Map<string, ReturnType<typeof setTimeout>>;
+    scheduleTimeoutCheck: (id: string, wfName: string, nodeIdx: number, ms: number) => void;
+}
+export declare function recoverExecutions(deps: RecoverDeps): Promise<RecoverResult>;

package/dist/client/workflow/recovery.js

@@ -0,0 +1,73 @@
+/**
+ * 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 { runCompensation } from './compensator';
+export async function recoverExecutions(deps) {
+    const { store, workflows } = deps;
+    const executions = store.listRecoverable();
+    const result = { running: 0, waiting: 0, compensating: 0, total: 0 };
+    for (const exec of executions) {
+        const wf = workflows.get(exec.workflowName);
+        if (!wf)
+            continue;
+        if (exec.state === 'running') {
+            await enqueueExecution(exec, deps.queue);
+            result.running++;
+        }
+        else if (exec.state === 'waiting') {
+            await recoverWaiting(exec, wf, deps);
+            result.waiting++;
+        }
+        else if (exec.state === 'compensating') {
+            await runCompensation(exec, wf, store, deps.emitter);
+            result.compensating++;
+        }
+    }
+    result.total = result.running + result.waiting + result.compensating;
+    return result;
+}
+async function enqueueExecution(exec, queue) {
+    const jobData = {
+        executionId: exec.id,
+        workflowName: exec.workflowName,
+        nodeIndex: exec.currentNodeIndex,
+    };
+    await queue.add('wf:step', jobData);
+}
+async function recoverWaiting(exec, wf, deps) {
+    const node = wf.nodes[exec.currentNodeIndex];
+    if (node?.type !== 'waitFor') {
+        await enqueueExecution(exec, deps.queue);
+        return;
+    }
+    // Check if signal already arrived while we were down
+    if (exec.signals[node.event] !== undefined) {
+        exec.state = 'running';
+        deps.store.update(exec);
+        await enqueueExecution(exec, deps.queue);
+        return;
+    }
+    // Re-arm timeout if configured
+    if (node.timeout !== undefined) {
+        if (deps.timeoutTimers.has(exec.id))
+            return;
+        const waitKey = `__waitFor:${node.event}`;
+        const waitRecord = exec.steps[waitKey];
+        const waitingSince = waitRecord?.startedAt ?? exec.updatedAt;
+        const elapsed = Date.now() - waitingSince;
+        const remaining = node.timeout - elapsed;
+        if (remaining <= 0) {
+            exec.state = 'running';
+            deps.store.update(exec);
+            await enqueueExecution(exec, deps.queue);
+        }
+        else {
+            deps.scheduleTimeoutCheck(exec.id, exec.workflowName, exec.currentNodeIndex, remaining);
+        }
+    }
+}

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

@@ -18,4 +18,3 @@ export declare function executeSubWorkflow(workflowName: string, input: unknown,
 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;
-//# sourceMappingURL=runner.d.ts.map

package/dist/client/workflow/runner.js

@@ -109,9 +109,8 @@ export async function executeParallelSteps(steps, ctx, exec, emitter, updateFn)
     const results = await Promise.allSettled(steps.map((def) => executeStepWithRetry(def, ctx, exec, emitter, updateFn)));
     const failed = results.filter((r) => r.status === 'rejected');
     if (failed.length > 0) {
-        throw failed[0].reason instanceof Error
-            ? failed[0].reason
-            : new Error(String(failed[0].reason));
+        const errors = failed.map((r) => r.reason instanceof Error ? r.reason : new Error(String(r.reason)));
+        throw new AggregateError(errors, errors[0].message);
     }
 }
 /** Execute a sub-workflow by starting it and polling for completion */
@@ -158,8 +157,11 @@ export function findStepDef(wf, name) {
             if (found)
                 return found;
         }
-        if (node.type === 'forEach' && node.def.step.name === name)
-            return node.def.step;
+        if (node.type === 'forEach') {
+            if (node.def.step.name === name || name.startsWith(node.def.step.name + ':')) {
+                return node.def.step;
+            }
+        }
     }
     return null;
 }
@@ -177,4 +179,3 @@ export function buildContext(exec) {
         executionId: exec.id,
     };
 }
-//# sourceMappingURL=runner.js.map

package/dist/client/workflow/store.d.ts

@@ -10,6 +10,8 @@ export declare class WorkflowStore {
     get(id: string): Execution | null;
     update(exec: Execution): void;
     list(workflowName?: string, state?: ExecutionState): Execution[];
+    /** List all executions in recoverable states (running, waiting, compensating) */
+    listRecoverable(): Execution[];
     /** Delete executions older than maxAge in terminal states */
     cleanup(maxAgeMs: number, states?: string[]): number;
     /** Archive executions older than maxAge to the archive table */
@@ -19,4 +21,3 @@ export declare class WorkflowStore {
     close(): void;
     private rowToExecution;
 }
-//# sourceMappingURL=store.d.ts.map

package/dist/client/workflow/store.js

@@ -68,6 +68,7 @@ export class WorkflowStore {
             listByName: this.db.prepare(`SELECT * FROM workflow_executions WHERE workflow_name = ? ORDER BY created_at DESC LIMIT 100`),
             listByState: this.db.prepare(`SELECT * FROM workflow_executions WHERE state = ? ORDER BY created_at DESC LIMIT 100`),
             listByBoth: this.db.prepare(`SELECT * FROM workflow_executions WHERE workflow_name = ? AND state = ? ORDER BY created_at DESC LIMIT 100`),
+            listRecoverable: this.db.prepare(`SELECT * FROM workflow_executions WHERE state IN ('running', 'waiting', 'compensating') ORDER BY updated_at ASC`),
         };
     }
     save(exec) {
@@ -97,6 +98,11 @@ export class WorkflowStore {
         }
         return rows.map((r) => this.rowToExecution(r));
     }
+    /** List all executions in recoverable states (running, waiting, compensating) */
+    listRecoverable() {
+        const rows = this.stmts.listRecoverable.all();
+        return rows.map((r) => this.rowToExecution(r));
+    }
     /** Delete executions older than maxAge in terminal states */
     cleanup(maxAgeMs, states = ['completed', 'failed']) {
         const cutoff = Date.now() - maxAgeMs;
@@ -157,4 +163,3 @@ export class WorkflowStore {
         };
     }
 }
-//# sourceMappingURL=store.js.map

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

@@ -3,29 +3,33 @@
  */
 import type { ConnectionOptions } from '../types';
 /** Context passed to step handlers */
-export interface StepContext<TInput = unknown> {
+export interface StepContext<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
     /** Original workflow input */
     readonly input: TInput;
     /** Results from completed steps (step name → result) */
-    readonly steps: Readonly<Record<string, unknown>>;
+    readonly steps: Readonly<TSteps>;
     /** Signals received via engine.signal() */
     readonly signals: Readonly<Record<string, unknown>>;
     /** Current execution ID */
     readonly executionId: string;
 }
-/** Step handler function */
-export type StepHandler<TInput = unknown, TResult = unknown> = (ctx: StepContext<TInput>) => Promise<TResult> | TResult;
-/** Compensate handler (rollback on failure) */
-export type CompensateHandler<TInput = unknown> = (ctx: StepContext<TInput>) => Promise<void> | void;
+/** Step handler function (type-erased for internal storage) */
+export type StepHandler<TInput = unknown, TResult = unknown> = (ctx: StepContext<TInput, any>) => Promise<TResult> | TResult;
+/** Typed step handler — preserves accumulated step types */
+export type TypedStepHandler<TInput, TSteps extends Record<string, unknown>, TResult> = (ctx: StepContext<TInput, TSteps>) => Promise<TResult> | TResult;
+/** Compensate handler (type-erased for internal storage) */
+export type CompensateHandler<TInput = unknown> = (ctx: StepContext<TInput, any>) => Promise<void> | void;
+/** Typed compensate handler — preserves accumulated step types */
+export type TypedCompensateHandler<TInput, TSteps extends Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => Promise<void> | void;
 /** Schema-like object — any object with a .parse() method (Zod, ArkType, Valibot, etc.) */
 export interface SchemaLike {
     parse(data: unknown): unknown;
 }
 /** Options for a single step */
-export interface StepOptions<TInput = unknown> {
+export interface StepOptions<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
     retry?: number;
     timeout?: number;
-    compensate?: CompensateHandler<TInput>;
+    compensate?: TypedCompensateHandler<TInput, TSteps> | CompensateHandler<TInput>;
     /** Validate step input before execution */
     inputSchema?: SchemaLike;
     /** Validate step output after execution */
@@ -42,10 +46,10 @@ export interface StepDefinition {
     outputSchema?: SchemaLike;
 }
 /** Branch condition function */
-export type BranchCondition = (ctx: StepContext) => string;
-/** Internal branch definition */
+export type BranchCondition<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => string;
+/** Internal branch definition (type-erased) */
 export interface BranchDefinition {
-    condition: BranchCondition;
+    condition: BranchCondition<any, any>;
     paths: Map<string, StepDefinition[]>;
 }
 /** Definition of a parallel step group */
@@ -53,29 +57,29 @@ export interface ParallelDefinition {
     steps: StepDefinition[];
 }
 /** Input mapper for sub-workflows */
-export type SubWorkflowInputMapper = (ctx: StepContext) => unknown;
+export type SubWorkflowInputMapper<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown;
 /** Loop condition: receives context + iteration count, returns boolean */
-export type LoopCondition = (ctx: StepContext, iteration: number) => boolean | Promise<boolean>;
-/** Definition of a doUntil/doWhile loop */
+export type LoopCondition<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>, iteration: number) => boolean | Promise<boolean>;
+/** Definition of a doUntil/doWhile loop (type-erased) */
 export interface LoopDefinition {
-    condition: LoopCondition;
+    condition: LoopCondition<any, any>;
     steps: StepDefinition[];
     maxIterations: number;
 }
 /** Item extractor for forEach */
-export type ForEachItemsExtractor = (ctx: StepContext) => unknown[];
-/** Definition of a forEach loop */
+export type ForEachItemsExtractor<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown[];
+/** Definition of a forEach loop (type-erased) */
 export interface ForEachDefinition {
-    items: ForEachItemsExtractor;
+    items: ForEachItemsExtractor<any, any>;
     step: StepDefinition;
     maxIterations: number;
 }
 /** Transform function for map */
-export type MapTransformFn = (ctx: StepContext) => unknown;
-/** Definition of a map node */
+export type MapTransformFn<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown;
+/** Definition of a map node (type-erased) */
 export interface MapDefinition {
     name: string;
-    transform: MapTransformFn;
+    transform: MapTransformFn<any, any>;
 }
 /** Workflow node (discriminated union) */
 export type WorkflowNode = {
@@ -94,7 +98,7 @@ export type WorkflowNode = {
 } | {
     type: 'subWorkflow';
     name: string;
-    inputMapper: SubWorkflowInputMapper;
+    inputMapper: SubWorkflowInputMapper<any, any>;
 } | {
     type: 'doUntil';
     def: LoopDefinition;
@@ -120,6 +124,10 @@ export interface StepRecord {
     startedAt?: number;
     completedAt?: number;
     attempts?: number;
+    /** forEach iteration item — persisted so compensation can restore __item */
+    loopItem?: unknown;
+    /** forEach iteration index — persisted so compensation can restore __index */
+    loopIndex?: number;
 }
 /** Full execution state */
 export interface Execution {
@@ -187,9 +195,19 @@ export interface StepJobData {
     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;
+}
 /** Options for cleanup */
 export interface CleanupOptions {
     maxAge: number;
     states?: ExecutionState[];
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/client/workflow/types.js

@@ -2,4 +2,3 @@
  * Workflow Engine Types
  */
 export {};
-//# sourceMappingURL=types.js.map

package/dist/client/workflow/workflow.d.ts

@@ -1,41 +1,43 @@
 /**
  * Workflow - DSL builder for defining workflow step graphs
  * Pure data structure, no side effects.
+ *
+ * Supports type-safe step chaining: each .step() narrows the return type
+ * so subsequent steps can access previous results without casting.
  */
-import type { WorkflowNode, StepHandler, StepOptions, StepContext, BranchCondition, LoopCondition, ForEachItemsExtractor, MapTransformFn } from './types';
-export declare class Workflow<TInput = unknown> {
+import type { WorkflowNode, StepOptions, StepContext, BranchCondition, LoopCondition, ForEachItemsExtractor, TypedStepHandler } from './types';
+export declare class Workflow<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
     readonly name: string;
     readonly nodes: WorkflowNode[];
     constructor(name: string);
-    /** Add a step to the workflow */
-    step(name: string, handler: StepHandler<TInput>, options?: StepOptions<TInput>): this;
+    /** Add a step to the workflow — return type accumulates into TSteps */
+    step<TName extends string, TResult>(name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps>): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Add a branch point — call .path() after this to define paths */
-    branch(condition: BranchCondition): this;
+    branch(condition: BranchCondition<TInput, TSteps>): this;
     /** Define a branch path (must follow a .branch() call) */
-    path(name: string, builder: (w: Workflow<TInput>) => Workflow<TInput>): this;
-    /** Run multiple steps in parallel */
-    parallel(builder: (w: Workflow<TInput>) => Workflow<TInput>): this;
+    path(name: string, builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, any>): this;
+    /** Run multiple steps in parallel — accumulated types from sub-builder merge into TSteps */
+    parallel<TNewSteps extends Record<string, unknown>>(builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, TSteps & TNewSteps>): Workflow<TInput, TSteps & TNewSteps>;
     /** Call another registered workflow as a step */
-    subWorkflow(name: string, inputMapper: (ctx: StepContext<TInput>) => unknown): this;
+    subWorkflow<TName extends string>(name: TName, inputMapper: (ctx: StepContext<TInput, TSteps>) => unknown): Workflow<TInput, TSteps & Record<`sub:${TName}`, Record<string, unknown>>>;
     /** Wait for an external signal before continuing */
     waitFor(event: string, options?: {
         timeout?: number;
     }): this;
     /** Repeat steps until condition returns true (checked after each iteration) */
-    doUntil(condition: LoopCondition, builder: (w: Workflow<TInput>) => Workflow<TInput>, options?: {
+    doUntil(condition: LoopCondition<TInput, TSteps>, builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, any>, options?: {
         maxIterations?: number;
     }): this;
     /** Repeat steps while condition returns true (checked before each iteration) */
-    doWhile(condition: LoopCondition, builder: (w: Workflow<TInput>) => Workflow<TInput>, options?: {
+    doWhile(condition: LoopCondition<TInput, TSteps>, builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, any>, options?: {
         maxIterations?: number;
     }): this;
     /** Iterate over items, executing a step for each */
-    forEach(items: ForEachItemsExtractor, name: string, handler: StepHandler<TInput>, options?: StepOptions<TInput> & {
+    forEach<TName extends string, TResult>(items: ForEachItemsExtractor<TInput, TSteps>, name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps> & {
         maxIterations?: number;
-    }): this;
+    }): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Transform step results into a new value stored under the given name */
-    map(name: string, transform: MapTransformFn): this;
+    map<TName extends string, TResult>(name: TName, transform: (ctx: StepContext<TInput, TSteps>) => TResult): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Get flat list of step names for validation */
     getStepNames(): string[];
 }
-//# sourceMappingURL=workflow.d.ts.map