bunqueue-client 0.1.8 → 0.2.0

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

@@ -0,0 +1,14 @@
+/**
+ * Timing primitives used while running a workflow step.
+ *
+ * Kept separate from runner.ts so the runner stays focused on state transitions.
+ */
+/** Exponential retry backoff with jitter. */
+export declare function retryBackoffDelay(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Bound a value or PromiseLike without passing an overflowing delay to the runtime.
+ *
+ * Long deadlines are re-armed in platform-sized chunks. Promise.resolve is
+ * intentional: it assimilates userland thenables as well as native promises.
+ */
+export declare function runWithTimeout<T>(value: PromiseLike<T> | T, timeoutMs: number, controller?: AbortController): Promise<T>;

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

@@ -0,0 +1,171 @@
+/** Workflow handler, definition, and graph types. */
+/** Context passed to step handlers */
+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<TSteps>;
+    /** Signals received via engine.signal() */
+    readonly signals: Readonly<Record<string, unknown>>;
+    /** Current execution ID */
+    readonly executionId: string;
+    /**
+     * Aborted when this handler attempt reaches its timeout.
+     *
+     * Handlers that support cooperative cancellation should pass this signal to
+     * downstream I/O so timed-out work does not continue after the workflow moves on.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Idempotency key for THIS execution of the step. Stable across automatic retries
+     * and across crash-resume; different for a different run. Pass it straight to the
+     * provider so a repeat lands on the same operation instead of a new one.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Compensation only: the key the FORWARD step used. When the forward outcome is
+     * in doubt, this is what lets a rollback ask the provider "did this actually
+     * happen?" instead of depending on an output that may never have been persisted.
+     */
+    readonly forwardIdempotencyKey?: string;
+}
+/** 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.
+ *
+ * `TSteps` is part of the signature for source compatibility and for symmetry with
+ * `TypedStepHandler`, even though `compensate` no longer narrows on it (see below).
+ * Removing the parameter would break every explicit `StepOptions<In, Steps>` in
+ * user code.
+ */
+export interface StepOptions<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
+    retry?: number;
+    timeout?: number;
+    /**
+     * A METHOD taking a permissively-typed context, and every part of that is load
+     * bearing. Three forms were measured against real handler shapes:
+     *
+     *   shape                                     union   method<TSteps>   method<any>
+     *   compensate: async (ctx) => ...            TS7006  ok               ok
+     *   annotated with steps it reads             ok      ok               ok
+     *   annotated with a step that does not exist ok      TS2322           ok
+     *   CompensateHandler<TInput> alias           ok      ok               ok
+     *
+     * Not a union (`TypedCompensateHandler | CompensateHandler`): TypeScript cannot
+     * contextually type a parameter against a union of signatures, so the inline arrow
+     * every documented example uses was an implicit `any` and failed `noImplicitAny`.
+     *
+     * A method rather than a property so parameters stay bivariant under
+     * `strictFunctionTypes`, which is what lets an explicitly annotated handler through.
+     *
+     * `any` rather than `TSteps` for the step map, deliberately: with `TSteps` an
+     * annotation naming a step this workflow does not declare is rejected, and the
+     * published union accepted it. Keeping the looser map costs typed access to
+     * `ctx.steps` inside a rollback, which handlers already narrow with a cast in
+     * practice, and buys source compatibility with every handler written before.
+     */
+    compensate?(ctx: StepContext<TInput, TSteps extends never ? never : any>): Promise<void> | void;
+    /** Validate step input before execution */
+    inputSchema?: SchemaLike;
+    /** Validate step output after execution */
+    outputSchema?: SchemaLike;
+}
+/** Internal step definition */
+export interface StepDefinition {
+    name: string;
+    handler: StepHandler;
+    compensate?: CompensateHandler;
+    retry: number;
+    timeout: number;
+    inputSchema?: SchemaLike;
+    outputSchema?: SchemaLike;
+}
+/** Branch condition function */
+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<any, any>;
+    paths: Map<string, StepDefinition[]>;
+}
+/** Definition of a parallel step group */
+export interface ParallelDefinition {
+    steps: StepDefinition[];
+}
+/** Input mapper for sub-workflows */
+export type SubWorkflowInputMapper<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown;
+/** Bounds for polling a child workflow. */
+export interface SubWorkflowOptions {
+    /** Maximum time to wait for the child. Defaults to five minutes. */
+    timeout?: number;
+    /** Delay between durable child-state reads. Defaults to 100ms. */
+    pollInterval?: number;
+}
+/** Loop condition: receives context + iteration count, returns boolean */
+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<any, any>;
+    steps: StepDefinition[];
+    maxIterations: number;
+}
+/** Item extractor for forEach */
+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<any, any>;
+    step: StepDefinition;
+    maxIterations: number;
+}
+/** Transform function for map */
+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<any, any>;
+}
+/** Workflow node (discriminated union) */
+export type WorkflowNode = {
+    type: 'step';
+    def: StepDefinition;
+} | {
+    type: 'branch';
+    def: BranchDefinition;
+} | {
+    type: 'waitFor';
+    event: string;
+    timeout?: number;
+} | {
+    type: 'parallel';
+    def: ParallelDefinition;
+} | {
+    type: 'subWorkflow';
+    name: string;
+    inputMapper: SubWorkflowInputMapper<any, any>;
+    timeout: number;
+    pollInterval: number;
+} | {
+    type: 'doUntil';
+    def: LoopDefinition;
+} | {
+    type: 'doWhile';
+    def: LoopDefinition;
+} | {
+    type: 'forEach';
+    def: ForEachDefinition;
+} | {
+    type: 'map';
+    def: MapDefinition;
+} | {
+    type: 'pivot';
+};

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

@@ -0,0 +1,83 @@
+/**
+ * WorkflowStore - SQLite persistence for workflow executions
+ */
+import type { Execution, ExecutionListOptions, ExecutionState, ParkOutcome, SignalOutcome } from "./types.js";
+export declare class WorkflowStore {
+    private readonly db;
+    private readonly stmts;
+    /** Sole owner of the `signals` column — see storeSignals.ts */
+    private readonly signals;
+    private readonly listing;
+    constructor(dbPath?: string);
+    /**
+     * Insert a fresh execution. A plain INSERT exposes id collisions instead of
+     * replacing live runs. This is the only signal writer outside SignalCoordinator and
+     * is safe because callers pass a new execution with no signals.
+     */
+    save(exec: Execution): void;
+    get(id: string): Execution | null;
+    findChild(parentExecutionId: string, workflowName: string): Execution | null;
+    /** Remove an execution whose initial queue publication failed. */
+    remove(id: string): boolean;
+    /**
+     * Persist the step-level columns of an execution.
+     *
+     * Deliberately does NOT write `signals`. A worker holds one in-memory `Execution`
+     * for the whole duration of a node, so its `signals` snapshot goes stale as soon as
+     * `recordSignal()` writes to the row. Rewriting the column from that stale snapshot
+     * silently destroyed signals delivered mid-step and parked the run forever
+     * (`test/repro-workflow-signal-lost-update.test.ts`). Signal payloads are owned
+     * exclusively by `recordSignal()`/`parkForSignal()`, which read-modify-write the
+     * column inside a transaction.
+     */
+    update(exec: Execution): void;
+    /**
+     * Record a signal payload and, if the run is parked at a `waitFor`, atomically
+     * claim the single resume for this caller.
+     */
+    recordSignal(id: string, event: string, payload: unknown): SignalOutcome;
+    /**
+     * Restore the wait claim if publishing its resume job failed.
+     *
+     * The signal remains durable, so recover() can publish the resume again.
+     */
+    restoreSignalWait(id: string, event: string, nodeIndex: number): boolean;
+    /**
+     * Park a running execution at a `waitFor`, unless the awaited signal has already
+     * been recorded (in which case the caller must advance instead).
+     */
+    parkForSignal(id: string, event: string): ParkOutcome;
+    list(workflowName?: string, state?: ExecutionState, options?: ExecutionListOptions): Execution[];
+    /** Runs whose registered definition must remain available and structurally stable. */
+    listActive(workflowName: string): Execution[];
+    /**
+     * Executions in a recoverable state that recovery may drive ON ITS OWN.
+     *
+     * A `subWorkflow` child is a row like any other, so the state filter alone offered
+     * it to `recover()` as if it were a top-level run. Driving it independently re-ran
+     * its steps and produced fresh records with no `compensation`, which defeats the
+     * "a step that already carries an outcome is not re-run" guard: the parent's later
+     * unwind dispatched the child's reversal a SECOND time, against a provider that had
+     * already been refunded (`test/repro-model-child-recovered-alone.test.ts`; found by
+     * the state-machine model, seed 1267197984).
+     *
+     * A child's lifecycle belongs to its parent, which unwinds it through `unwindChild`.
+     * One exception: if the parent row is gone, nothing owns the child any more, so it
+     * is returned rather than stranded forever in a non-terminal state.
+     */
+    listRecoverable(): Execution[];
+    /**
+     * Delete executions at least `maxAgeMs` old in terminal states.
+     *
+     * The cutoff is INCLUSIVE. A strict `<` makes `cleanup(0)`, the documented way to
+     * flush everything terminal right now, skip every row whose `updated_at` lands on
+     * the current millisecond, which is precisely where a run that just finished lands
+     * (`test/repro-workflow-archive-boundary.test.ts`).
+     */
+    cleanup(maxAgeMs: number, states?: string[]): number;
+    /** Archive executions at least `maxAgeMs` old to the archive table. Cutoff inclusive, as in `cleanup`. */
+    archive(maxAgeMs: number, states?: string[]): number;
+    /** Get archived execution count */
+    getArchivedCount(): number;
+    close(): void;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * msgpack codec shared by the workflow store and its signal coordinator.
+ * Kept in its own module so both can encode blobs identically without either
+ * owning the packer.
+ */
+export declare function pack(data: unknown): Uint8Array;
+export declare function unpack(buf: Uint8Array | null | undefined): unknown;

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

@@ -0,0 +1,11 @@
+import type { Execution } from "./types.js";
+export interface ExecutionMeta {
+    rollbackStatus?: Execution['rollbackStatus'];
+    failureReason?: string;
+    committedAt?: number;
+    parentExecutionId?: string;
+    decisions?: Record<string, unknown>;
+    definitionHash?: string;
+}
+export declare function packExecutionMeta(exec: Execution): Uint8Array | null;
+export declare function decodeExecution(row: Record<string, unknown>): Execution;

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

@@ -0,0 +1,11 @@
+import type { Database } from "../../../sdk/typescript/src/canonical-transport/bun-sqlite-types.js";
+import type { Execution, ExecutionListOptions, ExecutionState } from "./types.js";
+/** Prepared, consistently ordered execution-list queries. */
+export declare class ExecutionListing {
+    private readonly all;
+    private readonly byName;
+    private readonly byState;
+    private readonly byBoth;
+    constructor(db: Database);
+    list(workflowName?: string, state?: ExecutionState, options?: ExecutionListOptions): Execution[];
+}

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

@@ -0,0 +1,4 @@
+import type { Database } from "../../../sdk/typescript/src/canonical-transport/bun-sqlite-types.js";
+export declare function cleanupExecutions(db: Database, maxAgeMs: number, states?: string[]): number;
+export declare function archiveExecutions(db: Database, maxAgeMs: number, states?: string[]): number;
+export declare function archivedExecutionCount(db: Database): number;

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

@@ -0,0 +1,70 @@
+/**
+ * SignalCoordinator — sole owner of the `signals` column.
+ *
+ * Signal payloads cannot be persisted the way step state is. A worker holds one
+ * in-memory `Execution` for the whole duration of a node, so any full-row write from
+ * that snapshot silently reverts a signal that landed while the node was running —
+ * the approval disappears and the run parks forever
+ * (test/repro-workflow-signal-lost-update.test.ts).
+ *
+ * So every mutation of `signals` goes through here instead: read-modify-write inside
+ * a transaction, and the two state transitions that pair with it ('waiting' ->
+ * 'running' on resume, 'running' -> 'waiting' on park) expressed as conditional
+ * UPDATEs. Making those conditional is also what collapses duplicate or concurrent
+ * signals to exactly one resume, at the database rather than relying on the event
+ * loop never yielding at the right moment.
+ */
+import type { Database } from "../../../sdk/typescript/src/canonical-transport/bun-sqlite-types.js";
+import type { ParkOutcome, SignalOutcome } from "./types.js";
+/**
+ * Has this signal arrived? A KEY test, deliberately not a value test.
+ *
+ * `payload` is optional on `Engine.signal()`, so "the human said go" with nothing to
+ * carry is recorded as `signals[event] = undefined`. The codec is configured with
+ * `structuredClone: true` and round-trips that faithfully — the key is present, the
+ * value is `undefined` — so `signals[event] !== undefined` answers "did it arrive?"
+ * with NO for the most idiomatic call in the whole human-in-the-loop API.
+ *
+ * That disagreed with `record()`, which claims the resume without inspecting the
+ * payload: the run resumed, re-entered the waitFor, was told no signal had arrived,
+ * and parked again. With a timeout it then expired and compensated work the approver
+ * had just authorised (`test/repro-workflow-signal-no-payload.test.ts`).
+ *
+ * The predicate itself is `Object.hasOwn`, and an earlier revision of this comment
+ * claimed `in` was safe here because the object is always a fresh decode. That was
+ * wrong twice over: `in` walks the prototype chain regardless of where the object came
+ * from, and the EVENT NAME is user-supplied even when the object is not.
+ */
+export declare function hasSignal(signals: Record<string, unknown>, event: string): boolean;
+export declare class SignalCoordinator {
+    private readonly db;
+    private readonly read;
+    private readonly write;
+    private readonly claimResume;
+    private readonly restoreWait;
+    private readonly claimPark;
+    constructor(db: Database);
+    /**
+     * Record a signal payload and, if the run is parked at a `waitFor`, atomically
+     * claim the single resume for this caller.
+     */
+    record(id: string, event: string, payload: unknown): SignalOutcome;
+    /**
+     * Put a claimed wait back when publishing its resume job failed.
+     *
+     * The signal stays recorded: recovery sees the waiting row plus the signal key and
+     * retries the resume. The cursor predicate prevents a delayed enqueue rejection
+     * from parking an execution that another driver has already advanced.
+     */
+    restoreWaiting(id: string, event: string, nodeIndex: number): boolean;
+    /**
+     * Park a running execution at a `waitFor`, unless the awaited signal has already
+     * been recorded.
+     *
+     * Closes the window where a signal lands after `runWaitFor` read its in-memory
+     * snapshot but before the run reaches state `waiting`: without the re-check the
+     * payload is stored, nobody claims the resume, and the run hangs.
+     */
+    park(id: string, event: string): ParkOutcome;
+    private decode;
+}

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

@@ -0,0 +1,14 @@
+import type { Execution } from "./types.js";
+export interface SubWorkflowRunOptions {
+    pollIntervalMs?: number;
+    maxWaitMs?: number;
+    existingChildId?: string;
+    assertActive?: () => void;
+}
+/** Start or resume a child execution and poll its durable terminal state. */
+export declare function executeSubWorkflow(workflowName: string, input: unknown, startFn: (name: string, input: unknown) => Promise<{
+    id: string;
+}>, getFn: (id: string) => Execution | null, options?: SubWorkflowRunOptions): Promise<{
+    results: Record<string, unknown>;
+    executionId: string;
+}>;

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

@@ -0,0 +1,4 @@
+/** Stable public barrel for workflow types. */
+export type * from "./stepTypes.js";
+export type * from "./executionTypes.js";
+export type * from "./eventTypes.js";

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

@@ -0,0 +1,87 @@
+/**
+ * What the unwind should DO with each eligible record, decided as a pure function.
+ *
+ * WHY THIS FILE EXISTS. Every rollback defect this engine shipped lived in the four
+ * lines that decide whether a record is skipped, halted on, or reversed: a loop
+ * mirror compensated twice, a step called `charge:extra` resolved to the loop `charge`,
+ * a renamed step dropped so the unwind reported a clean rollback over money that was
+ * never refunded. None of those are I/O bugs. They are decisions, and while they lived
+ * inside a 90-line async function that also wrote to SQLite and emitted events, the
+ * only way to test them was to stand up an Engine, a database and a real failure, and
+ * then infer the decision from its side effects.
+ *
+ * Here the decision is a value. It takes data and returns what to do, so it can be
+ * exercised with generated inputs in microseconds and read without tracing an await.
+ * The impure loop in `compensator.ts` becomes what it should be: a dispatcher that
+ * performs the actions this file names.
+ *
+ * The ORDER of the checks is load-bearing and each one earned its place by breaking:
+ *
+ *   1. vanished  before  settled  — a record settled by an earlier attempt whose step
+ *      no longer resolves must halt, and the settled check would have skipped it.
+ *   2. settled   before  halted   — "never twice" outranks "stop after a failure": a
+ *      record already carrying an outcome is never re-run, halted or not.
+ *   3. halted    before  owes     — once something has failed definitively the rest
+ *      are left WITHOUT an outcome on purpose, so a resume can still reach them.
+ */
+import type { Execution, StepRecord } from "./types.js";
+import type { Workflow } from "./workflow.js";
+/** What to do with one eligible record. */
+export type UnwindAction = 
+/** Already has an outcome, or owes none. Move on, nothing to record. */
+{
+    kind: 'skip';
+    reason: 'already-settled' | 'owes-no-outcome';
+}
+/** A previous failure stopped the chain. Leave the rest untouched. */
+ | {
+    kind: 'stop';
+}
+/**
+ * This record already FAILED and is not being retried. The chain is still blocked
+ * here, so the pass must stop rather than walk past it.
+ */
+ | {
+    kind: 'halt-failed';
+}
+/** The step is gone from the workflow. Record why and stop the chain. */
+ | {
+    kind: 'halt-vanished';
+    error: string;
+}
+/** Roll back a nested workflow by running the child's own unwind. */
+ | {
+    kind: 'unwind-child';
+}
+/** Run this step's compensate handler, bounded by `timeoutMs`. */
+ | {
+    kind: 'compensate';
+    timeoutMs: number;
+};
+/** Bound applied to a reversal whose step declined to set one (`timeout: 0`). */
+export declare const DEFAULT_COMPENSATE_TIMEOUT_MS = 30000;
+/**
+ * Decide what to do with `record`, named `name`, in workflow `wf`.
+ *
+ * `halted` is whether an earlier record in this same pass already failed definitively.
+ */
+export declare function decideUnwindAction(wf: Workflow, name: string, record: StepRecord, halted: boolean, 
+/**
+ * An operator resume. A record that FAILED is retried instead of skipped.
+ *
+ * This replaced wiping the failed outcome before the pass. The wipe worked and cost
+ * more than it bought: the operator's `compensation-failed` record was destroyed on
+ * the way in, so a resume that then hit a failing store left a run with the
+ * diagnostic gone from disk and nothing saying which reversal had failed. Retrying
+ * from a flag leaves the record in place until a real outcome replaces it.
+ */
+retryFailed?: boolean): UnwindAction;
+/**
+ * Does this step still owe an outcome when the run terminates?
+ *
+ * Used by `abandonCompensation` to discharge "exactly one outcome per eligible step,
+ * never zero" for everything the unwind never reached.
+ */
+export declare function owesOutcome(wf: Workflow, name: string, record?: StepRecord): boolean;
+/** Is the pivot committed, making the whole run ineligible for rollback? */
+export declare function isCommitted(exec: Execution): boolean;

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

@@ -0,0 +1,56 @@
+/**
+ * waitFor node execution — parking a run for a human/external signal, and the
+ * timeout timers that bound the wait.
+ *
+ * Split out of the executor because parking is the one node type with a genuinely
+ * concurrent counterpart: `signal()` mutates the same row from outside the worker,
+ * so every transition here has to be expressed as a claim against the store rather
+ * than an in-memory state change. See storeSignals.ts for the ownership rules.
+ */
+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, WorkflowNode } from "./types.js";
+import { type TimerHandle } from "./clock.js";
+/** Largest delay setTimeout accepts before wrapping (2**31-1 ms, ~24.8 days) */
+export declare const MAX_TIMER_MS = 2147483647;
+export interface TimerDeps {
+    queue: Queue;
+    timers: Map<string, TimerHandle>;
+    assertActive: () => void;
+    isActive: () => boolean;
+}
+export interface WaitForDeps {
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    advance: (exec: Execution, nextIdx: number, wf: Workflow) => Promise<void>;
+    compensate: (exec: Execution, wf: Workflow) => Promise<void>;
+    scheduleTimeoutCheck: (execId: string, workflowName: string, nodeIdx: number, ms: number) => void;
+    updateFn: (exec: Execution) => void;
+    assertActive: () => void;
+}
+/**
+ * Arm the timer that re-enters a parked node once its wait budget elapses.
+ *
+ * setTimeout takes a 32-bit signed delay; anything larger wraps to 1ms and fires
+ * immediately (`TimeoutOverflowWarning`). Clamping and letting the re-check job
+ * re-arm for whatever remains is what makes multi-week approval windows survive
+ * (test/repro-workflow-timeout-overflow.test.ts).
+ */
+export declare function scheduleTimeoutCheck(deps: TimerDeps, execId: string, workflowName: string, nodeIdx: number, ms: number): void;
+/**
+ * Cancel every armed wait timer. Called on engine shutdown: `unref` alone lets a
+ * process exit, but a still-armed timer can also fire into a queue that is closing,
+ * and a caller that shuts one engine down while keeping the process alive has no
+ * other way to release them.
+ */
+export declare function clearTimers(timers: Map<string, TimerHandle>): void;
+/**
+ * Execute a `waitFor` node: advance if the signal is already there, fail if the wait
+ * has expired, otherwise park the run and throw the sentinel so processStep
+ * short-circuits without treating the pause as an error.
+ */
+export declare function runWaitFor(deps: WaitForDeps, exec: Execution, node: Extract<WorkflowNode, {
+    type: 'waitFor';
+}>, idx: number, wf: Workflow): Promise<void>;

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

@@ -0,0 +1,70 @@
+/**
+ * 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, StepOptions, StepContext, BranchCondition, SubWorkflowOptions, LoopCondition, ForEachItemsExtractor, TypedStepHandler } from "./types.js";
+export { assertNoDuplicateWaitFor, assertNoIndexCollision, unusableEventName, } from "./workflowValidation.js";
+export declare class Workflow<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    /**
+     * Explicit semantic revision. Bump it when handler or condition behavior changes
+     * incompatibly without changing the graph shape.
+     */
+    readonly revision: string;
+    readonly nodes: WorkflowNode[];
+    private sealed;
+    private sealedHash?;
+    constructor(name: string, options?: {
+        revision?: string | number;
+    });
+    /** Freeze this definition and return its durable structural identity. */
+    seal(): string;
+    private assertMutable;
+    /** 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 & Record<TName, Awaited<TResult>>>): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
+    /** Add a branch point — call .path() after this to define paths */
+    branch(condition: BranchCondition<TInput, TSteps>): this;
+    /** Define a branch path (must follow a .branch() call) */
+    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<TName extends string>(name: TName, inputMapper: (ctx: StepContext<TInput, TSteps>) => unknown, options?: SubWorkflowOptions): 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<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<TInput, TSteps>, builder: (w: Workflow<TInput, TSteps>) => Workflow<TInput, any>, options?: {
+        maxIterations?: number;
+    }): this;
+    /** Iterate over items, executing a step for each */
+    forEach<TName extends string, TResult>(items: ForEachItemsExtractor<TInput, TSteps>, name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps> & {
+        maxIterations?: number;
+    }): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
+    /** Transform step results into a new value stored under the given name */
+    map<TName extends string, TResult>(name: TName, transform: (ctx: StepContext<TInput, TSteps>) => TResult): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
+    /**
+     * Mark the point of no return.
+     *
+     * Everything before it stays compensatable; everything after is committed and is
+     * never rolled back, however the run ends. Past the pivot the only correct
+     * recovery is forward — retry, alert, fix — because there is no semantic inverse
+     * for "the welcome email was sent". Declare it explicitly; it is never inferred.
+     */
+    pivot(): this;
+    /**
+     * Step names that generate indexed per-iteration records (`name:0`, `name:1`, ...).
+     * Loop bodies and forEach steps both do; a plain step never does.
+     */
+    getIndexedStepNames(): string[];
+    /** Get flat list of step names for validation */
+    getStepNames(): string[];
+}

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

@@ -0,0 +1,11 @@
+/** Durable control-flow decision journal. */
+import type { Execution } from "./types.js";
+/**
+ * Return an already persisted decision, or evaluate and persist it before the caller
+ * performs any effects selected by that decision.
+ */
+export declare function resolveDecision<T>(exec: Execution, key: string, evaluate: () => T | Promise<T>, updateFn: (exec: Execution) => void, assertActive: () => void): Promise<T>;
+export declare function branchDecisionKey(nodeIndex: number): string;
+export declare function forEachItemsDecisionKey(stepName: string): string;
+export declare function loopDecisionKey(kind: 'doUntil' | 'doWhile', firstStepName: string, iteration: number): string;
+export declare function subWorkflowInputDecisionKey(nodeIndex: number): string;

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

@@ -0,0 +1,16 @@
+/**
+ * Stable workflow-definition identity and sealing.
+ *
+ * Executions persist the hash produced here. It describes the durable graph, while
+ * `revision` lets callers explicitly mark handler/condition changes that cannot be
+ * inferred safely from closures.
+ */
+import type { WorkflowNode } from "./types.js";
+interface WorkflowDefinitionSource {
+    readonly name: string;
+    readonly revision: string;
+    readonly nodes: WorkflowNode[];
+}
+export declare function workflowDefinitionHash(workflow: WorkflowDefinitionSource): string;
+export declare function sealWorkflowDefinition(workflow: WorkflowDefinitionSource): string;
+export {};

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

@@ -0,0 +1,5 @@
+import type { WorkflowNode } from "./types.js";
+/** Names that produce indexed records such as `name:0`. */
+export declare function indexedStepNames(nodes: readonly WorkflowNode[]): string[];
+/** Every record name declared by a workflow graph. */
+export declare function stepNames(nodes: readonly WorkflowNode[]): string[];