bunqueue 2.8.46 → 2.8.48

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

@@ -0,0 +1,61 @@
+/**
+ * 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 'bun:sqlite';
+import type { ParkOutcome, SignalOutcome } from './types';
+/**
+ * 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 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;
+    /**
+     * 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/client/workflow/storeSignals.js

@@ -0,0 +1,118 @@
+/**
+ * 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 { pack, unpack } from './storeCodec';
+import { clock } from './clock';
+/**
+ * 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 function hasSignal(signals, event) {
+    // `Object.hasOwn`, not `in`, and not `signals[event] !== undefined`. All three read
+    // like the same question and only one of them asks it.
+    //
+    // `signals` is a plain object used as a map, so `in` walks the prototype chain:
+    // `'toString' in {}` is true, and a gate named `toString`, `constructor`, `valueOf`
+    // or `hasOwnProperty` opened the instant it parked, with nobody having signalled
+    // anything. The value test that preceded it failed identically, because
+    // `signals['toString']` is the inherited function and not `undefined`.
+    //
+    // The names are not exotic in a real vocabulary, and an event name read from config
+    // or user input is attacker-influenced. The failure is silent and it opens the one
+    // control that exists to stop things
+    // (`test/repro-workflow-prototype-gate.test.ts`, found by the generated-input suite
+    // in `test/workflow-properties.test.ts`).
+    return Object.hasOwn(signals, event);
+}
+export class SignalCoordinator {
+    db;
+    read;
+    write;
+    claimResume;
+    claimPark;
+    constructor(db) {
+        this.db = db;
+        this.read = db.prepare(`SELECT workflow_name, state, current_node_index, signals FROM workflow_executions WHERE id = ?`);
+        this.write = db.prepare(`UPDATE workflow_executions SET signals = ?, updated_at = ? WHERE id = ?`);
+        this.claimResume = db.prepare(`UPDATE workflow_executions SET state = 'running', updated_at = ? WHERE id = ? AND state = 'waiting'`);
+        // 'waiting' is accepted as a source state so re-parking is idempotent: a clamped
+        // or partial timeout re-arm re-enters the same waitFor node while the row is
+        // still 'waiting', and must be allowed to park (and re-arm) again.
+        this.claimPark = db.prepare(`UPDATE workflow_executions SET state = 'waiting', updated_at = ? WHERE id = ? AND state IN ('running', 'waiting')`);
+    }
+    /**
+     * Record a signal payload and, if the run is parked at a `waitFor`, atomically
+     * claim the single resume for this caller.
+     */
+    record(id, event, payload) {
+        const tx = this.db.transaction(() => {
+            const row = this.read.get(id);
+            if (!row)
+                return { found: false, resumed: false, workflowName: '', currentNodeIndex: 0 };
+            const signals = this.decode(row);
+            signals[event] = payload;
+            const now = clock().now();
+            this.write.run(pack(signals), now, id);
+            const claimed = this.claimResume.run(now, id);
+            return {
+                found: true,
+                resumed: claimed.changes === 1,
+                workflowName: row.workflow_name,
+                currentNodeIndex: row.current_node_index,
+            };
+        });
+        return tx();
+    }
+    /**
+     * 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, event) {
+        const tx = this.db.transaction(() => {
+            const row = this.read.get(id);
+            const signals = this.decode(row);
+            if (!row)
+                return { signalPresent: false, parked: false, signals };
+            if (hasSignal(signals, event))
+                return { signalPresent: true, parked: false, signals };
+            const claimed = this.claimPark.run(clock().now(), id);
+            return { signalPresent: false, parked: claimed.changes === 1, signals };
+        });
+        return tx();
+    }
+    decode(row) {
+        return unpack(row?.signals) ?? {};
+    }
+}

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

@@ -12,6 +12,18 @@ export interface StepContext<TInput = unknown, TSteps extends Record<string, unk
     readonly signals: Readonly<Record<string, unknown>>;
     /** Current execution ID */
     readonly executionId: string;
+    /**
+     * 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;
@@ -25,11 +37,41 @@ export type TypedCompensateHandler<TInput, TSteps extends Record<string, unknown
 export interface SchemaLike {
     parse(data: unknown): unknown;
 }
-/** Options for a single step */
+/**
+ * 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;
-    compensate?: TypedCompensateHandler<TInput, TSteps> | CompensateHandler<TInput>;
+    /**
+     * 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 */
@@ -111,9 +153,35 @@ export type WorkflowNode = {
 } | {
     type: 'map';
     def: MapDefinition;
+} | {
+    type: 'pivot';
 };
 /** Execution state */
-export type ExecutionState = 'running' | 'waiting' | 'completed' | 'failed' | 'compensating';
+export type ExecutionState = 'running' | 'waiting' | 'completed' | 'failed' | 'compensating'
+/**
+ * A compensation failed definitively and the unwind stopped. Deliberately NOT
+ * terminal: halting and calling it done leaves the operator nothing to act on,
+ * and ploughing on would undo work whose dependencies are still standing. The run
+ * parks here until someone retries the failed handler or abandons the unwind.
+ */
+ | 'compensation-stuck';
+/**
+ * What the engine did AFTER a failure. Deliberately a separate axis from the
+ * failure reason: the rollback is not the cause of the failure, and collapsing the
+ * two makes it impossible to alert on the right thing — "the payment failed" and
+ * "the refund never went through" need different pagers.
+ *
+ * Absent means no unwind was attempted, which is the case for a run that has not
+ * failed. There is deliberately no `'not-started'` member: it was documented in three
+ * places and never once assigned, so anything branching on it was dead code.
+ */
+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; the remaining ones were not attempted. */
+ | 'stuck';
 /** Step execution state */
 export type StepState = 'pending' | 'running' | 'completed' | 'failed';
 /** Record of a step's execution */
@@ -124,10 +192,45 @@ export interface StepRecord {
     startedAt?: number;
     completedAt?: number;
     attempts?: number;
+    /**
+     * Did this step declare a `compensate` handler when it ran?
+     *
+     * Persisted because a later deploy can remove or rename the step, and then nothing
+     * else can tell "this step never owed a reversal" from "this step owed one and the
+     * handler is gone". Without it a renamed step that had not been reversed yet was
+     * silently dropped from the unwind and the run reported a clean rollback.
+     */
+    compensatable?: boolean;
     /** forEach iteration item — persisted so compensation can restore __item */
     loopItem?: unknown;
     /** forEach iteration index — persisted so compensation can restore __index */
     loopIndex?: number;
+    /**
+     * Outcome of this step's rollback. Written exactly once per unwind, for every
+     * eligible step — including the ones the unwind never reached, which are recorded
+     * as 'compensation-skipped' rather than left blank. "Never zero, never two" is
+     * only checkable if success is recorded as loudly as failure.
+     */
+    compensation?: CompensationOutcome;
+    /** Idempotency key of the FORWARD execution, persisted before the body runs. */
+    idempotencyKey?: string;
+    /**
+     * For a `sub:<name>` record: the child execution this step started. Rolling back a
+     * nested workflow means running the CHILD's own unwind, so the parent has to keep
+     * a handle on it — otherwise a child that succeeded before the parent failed is
+     * left standing, with every resource it created orphaned.
+     */
+    childExecutionId?: string;
+    /** Occurrence of this step name within the run — loops reuse a single name. */
+    occurrence?: number;
+}
+/** 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;
 }
 /** Full execution state */
 export interface Execution {
@@ -139,12 +242,34 @@ export interface Execution {
     currentNodeIndex: number;
     /** Flattened step list for branch resolution */
     resolvedSteps?: 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, if it was reached.
+     *
+     * Once set, the saga is committed and backward recovery is OFF ENTIRELY — not just
+     * for the steps after it. That is what "point of no return" means: releasing the
+     * subdomain of a tenant who has already been sent a welcome email is precisely the
+     * outcome the pivot exists to prevent. After it, the only correct recovery is
+     * forward.
+     */
+    committedAt?: number;
     signals: Record<string, unknown>;
+    /**
+     * Set when this run was started BY a `subWorkflow` node, naming the parent that owns
+     * it. A child is a row like any other, so without this nothing distinguishes it from
+     * a top-level run and `recover()` drives it on its own, re-running its steps and
+     * re-arming its rollback behind the parent's back
+     * (`test/repro-model-child-recovered-alone.test.ts`).
+     */
+    parentExecutionId?: string;
     createdAt: number;
     updatedAt: number;
 }
 /** 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';
+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;
@@ -206,6 +331,24 @@ export interface RecoverResult {
     /** 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;

package/dist/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';
+import type { Workflow } from './workflow';
+/** 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/client/workflow/unwindPlan.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { findStepDef } from './runner';
+/** Bound applied to a reversal whose step declined to set one (`timeout: 0`). */
+export const DEFAULT_COMPENSATE_TIMEOUT_MS = 30_000;
+/**
+ * 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 function decideUnwindAction(wf, name, record, halted, 
+/**
+ * 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 = false) {
+    const isChild = name.startsWith('sub:');
+    const def = isChild ? null : findStepDef(wf, name);
+    // 1. The step is gone from the workflow, and this record is owed a reversal that can
+    //    no longer be produced. Checked FIRST, because the settled check below would skip
+    //    it and the pass would reach its end and call itself clean over a step nobody
+    //    reversed.
+    //
+    //    Exactly two shapes are owed one. A reversal that already FAILED is still
+    //    outstanding. And a record with no outcome that ran WITH a `compensate` handler
+    //    was going to be reversed and now cannot be, which is the likelier rename case:
+    //    the unwind had simply not reached it yet.
+    //
+    //    A record settled `compensated` or `compensation-skipped` is emphatically not
+    //    owed anything, and an earlier version of this check caught it too. The
+    //    dispatcher then wrote `compensation-failed` OVER a reversal that had provably
+    //    run and succeeded, emitted a `compensation:failed` for it, and halted there for
+    //    good, so the record that actually failed was never retried. An operator acting
+    //    on that would release the same stock twice, which is precisely the "never twice"
+    //    this module exists to guarantee.
+    if (!isChild && !def) {
+        const failedBefore = record.compensation?.status === 'compensation-failed';
+        const owedAndUnreached = record.compensation === undefined && record.compensatable === true;
+        if (failedBefore || owedAndUnreached) {
+            return {
+                kind: 'halt-vanished',
+                error: `step "${name}" is no longer declared by workflow "${wf.name}", so its rollback cannot run`,
+            };
+        }
+    }
+    // 2. Never twice. An unwind interrupted by a crash resumes where it stopped. The one
+    //    exception is an operator explicitly retrying a reversal that FAILED: a success
+    //    or a skip is never re-run, whatever was asked.
+    if (record.compensation) {
+        if (record.compensation.status === 'compensation-failed') {
+            // An UNRESOLVED failure. Skipping it is how a run that had a refused refund came
+            // back from `recover()` after a crash mid-unwind, walked past the reversal that
+            // had failed, reached the end and wrote `rollbackStatus: 'completed'` over money
+            // nobody had returned. The chain stopped here before and it still stops here,
+            // unless an operator explicitly asked for the retry.
+            if (!retryFailed)
+                return { kind: 'halt-failed' };
+        }
+        else {
+            // `compensated` or `compensation-skipped`: settled for good, never re-run.
+            return { kind: 'skip', reason: 'already-settled' };
+        }
+    }
+    // 3. Stop at the first definitive failure. The rest are deliberately left WITHOUT an
+    //    outcome: the run is parked, not finished, and pre-marking them skipped would
+    //    make a later resume believe they were already dealt with.
+    if (halted)
+        return { kind: 'stop' };
+    // 4. A nested workflow is reversed by running the child's own unwind, so the parent
+    //    needs no handler of its own.
+    if (isChild)
+        return { kind: 'unwind-child' };
+    // 5. No handler registered: not part of the unwind set, so no outcome is owed.
+    if (!def?.compensate)
+        return { kind: 'skip', reason: 'owes-no-outcome' };
+    // `timeout: 0` means "no bound" on the forward path, and that is the caller's choice
+    // to make. A reversal is not the same case: it holds the engine's in-flight claim,
+    // so one that never settles locks the run out of every operator exit for the life of
+    // the process. When the step declines to say what bounds it, the default applies.
+    return {
+        kind: 'compensate',
+        timeoutMs: def.timeout > 0 ? def.timeout : DEFAULT_COMPENSATE_TIMEOUT_MS,
+    };
+}
+/**
+ * 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 function owesOutcome(wf, name, record) {
+    if (name.startsWith('sub:'))
+        return true;
+    const def = findStepDef(wf, name);
+    // A step that is still declared owes an outcome only if it declared a handler.
+    // `unwindSet` admits EVERY step with a definition, so this is the gate that keeps
+    // `abandonCompensation` from inventing outcomes for steps that were never part of the
+    // unwind.
+    if (def)
+        return def.compensate !== undefined;
+    // The definition is gone, and here the two gates used to disagree. `unwindSet` keeps
+    // such a record when it already carries an outcome or ran WITH a handler; this one
+    // answered from the definition alone and so returned false for exactly the record
+    // `unwindSet` had gone out of its way to admit. `abandonCompensation` walked past it,
+    // and a renamed step ended a TERMINAL run with no outcome at all, in the function that
+    // exists to discharge "exactly one outcome per eligible step, never zero"
+    // (`test/repro-workflow-abandon-vanished.test.ts`).
+    return record?.compensation !== undefined || record?.compensatable === true;
+}
+/** Is the pivot committed, making the whole run ineligible for rollback? */
+export function isCommitted(exec) {
+    return exec.committedAt !== undefined;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 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';
+import type { Workflow } from './workflow';
+import type { WorkflowStore } from './store';
+import type { WorkflowEmitter } from './emitter';
+import type { Execution, WorkflowNode } from './types';
+import { type TimerHandle } from './clock';
+/** 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>;
+}
+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;
+}
+/**
+ * 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>;