bunqueue 2.8.46 → 2.8.47

package/dist/client/workflow/executor.js

@@ -1,13 +1,28 @@
+import { assertNoIndexCollision, assertNoDuplicateWaitFor, unusableEventName } from './workflow';
 import { executeStepWithRetry, executeParallelSteps, executeSubWorkflow, buildContext, } from './runner';
 import { executeDoUntil, executeDoWhile, executeForEach, executeMap } from './loops';
 import { WaitForSignalError, runCompensation } from './compensator';
+import { abandonParkedCompensation, resumeCompensation, } from './rollbackControl';
 import { recoverExecutions } from './recovery';
+import { clearTimers, runWaitFor, scheduleTimeoutCheck } from './waitFor';
+import { clock } from './clock';
+import { describeError } from './identity';
+import { claimKey, decideAdmission } from './admission';
 export class WorkflowExecutor {
     store;
     queue;
     emitter;
     workflows = new Map();
     timeoutTimers = new Map();
+    /**
+     * Release every armed waitFor timer. The engine owns the executor's lifetime, so
+     * `Engine.close()` must call this: an armed timer would otherwise fire into a
+     * closing queue, and a caller that keeps the process alive after closing one engine
+     * has no other handle on them.
+     */
+    close() {
+        clearTimers(this.timeoutTimers);
+    }
     updateFn;
     constructor(store, queue, emitter = null) {
         this.store = store;
@@ -23,16 +38,18 @@ export class WorkflowExecutor {
         if (dupes.length > 0) {
             throw new Error(`Duplicate step names in "${workflow.name}": ${dupes.join(', ')}`);
         }
+        assertNoIndexCollision(workflow);
+        assertNoDuplicateWaitFor(workflow);
         this.workflows.set(workflow.name, workflow);
     }
-    async start(workflowName, input) {
+    async start(workflowName, input, parentExecutionId) {
         const wf = this.workflows.get(workflowName);
         if (!wf)
             throw new Error(`Workflow "${workflowName}" not registered`);
         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 now = clock().now();
+        const id = `wf_${now}_${clock().random().toString(36).slice(2, 10)}`;
         const exec = {
             id,
             workflowName,
@@ -41,6 +58,7 @@ export class WorkflowExecutor {
             steps: {},
             currentNodeIndex: 0,
             signals: {},
+            ...(parentExecutionId ? { parentExecutionId } : {}),
             createdAt: now,
             updatedAt: now,
         };
@@ -49,10 +67,43 @@ export class WorkflowExecutor {
         await this.enqueue(exec);
         return { id, workflowName };
     }
+    /**
+     * Nodes this process is currently executing, keyed `<execution>:<nodeIndex>`.
+     *
+     * The cursor guard below rejects a job for a node the run has already left, but not
+     * a SECOND job for the node it is on right now: both carry the same index. That is
+     * the reachable duplicate, because `recover()` re-enqueues the current node of every
+     * `running` execution and is documented as callable on a live engine. Without this
+     * claim the node runs twice and each copy advances the run independently, doubling
+     * every side effect after it while the run still ends `completed`.
+     *
+     * A claim, not a queue-level dedup: a deterministic `jobId` was tried and could
+     * swallow a LEGITIMATE later re-enqueue of the same node, wedging the run forever.
+     * This drops only a duplicate that overlaps in time.
+     */
+    nodesInFlight = new Set();
     async processStep(data) {
+        // The admission DECISION lives in `admission.ts` as a pure function; this method
+        // only carries it out. Delivery is at-least-once, so the same node job arrives
+        // twice routinely, and when one of the three guards was missing a duplicate re-ran
+        // the node and every node after it: two advance chains on one execution, doubled
+        // side effects, and a final `completed` that hid it. That took a long model
+        // campaign to find because the reasoning was buried in a method that also read
+        // SQLite and dispatched work.
         const exec = this.store.get(data.executionId);
-        if (!exec || (exec.state !== 'running' && exec.state !== 'waiting'))
+        const admission = decideAdmission(exec, data.nodeIndex, this.nodesInFlight);
+        if (admission.kind === 'reject' || !exec)
             return null;
+        const claim = claimKey(data.executionId, data.nodeIndex);
+        this.nodesInFlight.add(claim);
+        try {
+            return await this.runNode(data, exec);
+        }
+        finally {
+            this.nodesInFlight.delete(claim);
+        }
+    }
+    async runNode(data, exec) {
         // If waiting, set back to running for timeout re-check
         if (exec.state === 'waiting')
             exec.state = 'running';
@@ -73,6 +124,15 @@ export class WorkflowExecutor {
             if (err instanceof WaitForSignalError)
                 return null;
             exec.state = 'failed';
+            // Why the run failed — kept distinct from what the rollback then did.
+            exec.failureReason = describeError(err);
+            // Deliberately UNGUARDED, unlike the writes on the throwing paths in `runner.ts` and
+            // `runSubWorkflow`. A throw here skips `compensate()` below, which sounds worse and
+            // is not: disk still says `running`, `listRecoverable()` covers `running`, so the
+            // next `recover()` re-drives this node and the unwind happens then. Swallowing it
+            // would instead leave a run that looks failed and was never rolled back, with
+            // nothing scheduled to notice. Guard this only alongside a durable signal that the
+            // rollback is still owed.
             this.store.update(exec);
             this.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
             await this.compensate(exec, wf);
@@ -81,32 +141,63 @@ export class WorkflowExecutor {
         return null;
     }
     async signal(executionId, event, payload) {
-        const exec = this.store.get(executionId);
-        if (!exec)
-            throw new Error(`Execution "${executionId}" not found`);
+        // Same predicate as registration. A name that cannot be stored has to fail here
+        // too: a caller who signals it would otherwise get a clean return for a delivery
+        // that went nowhere.
+        const bad = unusableEventName(event);
+        if (bad)
+            throw new Error(`Cannot signal an event ${bad}`);
+        // A finished run cannot receive anything. Accepting it wrote the payload into the
+        // persisted row and emitted `signal:received`, so a dashboard reported an approval
+        // against a run that had already ended and a closed audit record was mutated after
+        // the fact, while the caller got a clean return for a delivery that did nothing.
+        // A signal racing a run to its end is real, and rejecting is how the caller finds
+        // out (`test/repro-workflow-operator-signal.test.ts`).
+        const current = this.store.get(executionId);
+        if (current && current.state !== 'running' && current.state !== 'waiting') {
+            throw new Error(`Execution "${executionId}" is "${current.state}" and cannot receive the signal "${event}"`);
+        }
         const timer = this.timeoutTimers.get(executionId);
         if (timer) {
-            clearTimeout(timer);
+            clock().clearTimeout(timer);
             this.timeoutTimers.delete(executionId);
         }
-        // Always record the payload (idempotent) and notify listeners. A signal that
-        // lands before the run parks at its waitFor is still consumed there, via the
-        // `signals[event] !== undefined` gate in runWaitFor.
-        exec.signals[event] = payload;
-        this.emitter?.emitSignal('signal:received', exec.id, exec.workflowName, event, payload);
-        // Resume only a genuinely-parked run (state 'waiting'), and only once. The state
-        // check and the flip to 'running' are synchronous — no `await` between them — so a
-        // second concurrent/duplicate signal() (which can only run after the first yields
-        // at `await this.enqueue`, by which point `store.update` has persisted 'running')
-        // observes 'running' and returns early. This collapses duplicate/concurrent
-        // signals to a single resume, so every step after the waitFor runs exactly once.
-        if (exec.state !== 'waiting') {
-            this.store.update(exec);
+        // Record the payload and claim the resume in a single transaction that touches
+        // only the `signals` and `state` columns. Writing through the store — rather than
+        // mutating a snapshot and calling update() — is what keeps a concurrently
+        // executing step from overwriting the payload with its own stale `signals`
+        // (test/repro-workflow-signal-lost-update.test.ts).
+        //
+        // The claim is a conditional `state = 'waiting'` UPDATE, so duplicate or
+        // concurrent signals collapse to exactly one resume and every step after the
+        // waitFor runs exactly once. A signal that lands before the run parks records
+        // its payload and returns; runWaitFor then consumes it via parkForSignal().
+        const outcome = this.store.recordSignal(executionId, event, payload);
+        if (!outcome.found)
+            throw new Error(`Execution "${executionId}" not found`);
+        this.emitter?.emitSignal('signal:received', executionId, outcome.workflowName, event, payload);
+        if (!outcome.resumed)
             return;
-        }
-        exec.state = 'running';
-        this.store.update(exec);
-        await this.enqueue(exec);
+        await this.queue.add('wf:step', {
+            executionId,
+            workflowName: outcome.workflowName,
+            nodeIndex: outcome.currentNodeIndex,
+        });
+    }
+    /** Retry the compensation that parked the run, then finish the unwind. */
+    async resumeCompensation(executionId) {
+        await resumeCompensation(this.rollbackDeps, executionId);
+    }
+    /** Give up on a parked unwind, recording the outstanding steps as skipped. */
+    abandonCompensation(executionId) {
+        abandonParkedCompensation(this.rollbackDeps, executionId);
+    }
+    get rollbackDeps() {
+        return {
+            store: this.store,
+            emitter: this.emitter,
+            workflows: this.workflows,
+        };
     }
     getExecution(id) {
         return this.store.get(id);
@@ -124,19 +215,21 @@ export class WorkflowExecutor {
         else if (node.type === 'subWorkflow')
             await this.runSubWorkflow(exec, node, idx, wf);
         else if (node.type === 'doUntil')
-            await this.runLoop(exec, node, idx, wf, executeDoUntil);
+            await this.runBody(exec, idx, wf, executeDoUntil, node.def);
         else if (node.type === 'doWhile')
-            await this.runLoop(exec, node, idx, wf, executeDoWhile);
+            await this.runBody(exec, idx, wf, executeDoWhile, node.def);
         else if (node.type === 'forEach')
-            await this.runForEach(exec, node, idx, wf);
+            await this.runBody(exec, idx, wf, executeForEach, node.def);
         else if (node.type === 'map')
-            await this.runMap(exec, node, idx, wf);
+            await this.runBody(exec, idx, wf, executeMap, node.def);
+        else if (node.type === 'pivot')
+            await this.runPivot(exec, idx, wf);
         else
-            await this.runWaitFor(exec, node, idx, wf);
+            await runWaitFor(this.waitForDeps, exec, node, idx, wf);
     }
     async runStep(exec, def, idx, wf) {
         const ctx = buildContext(exec);
-        await executeStepWithRetry(def, ctx, exec, this.emitter, this.updateFn);
+        await executeStepWithRetry(def, ctx, exec, { emitter: this.emitter, updateFn: this.updateFn });
         await this.advance(exec, idx + 1, wf);
     }
     async runBranch(exec, node, idx, wf) {
@@ -144,7 +237,10 @@ 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, this.updateFn);
+                await executeStepWithRetry(step, buildContext(exec), exec, {
+                    emitter: this.emitter,
+                    updateFn: this.updateFn,
+                });
             }
         }
         await this.advance(exec, idx + 1, wf);
@@ -155,57 +251,90 @@ export class WorkflowExecutor {
     }
     async runSubWorkflow(exec, node, idx, wf) {
         const subInput = node.inputMapper(buildContext(exec));
-        const result = await executeSubWorkflow(node.name, subInput, (name, input) => this.start(name, input), (id) => this.store.get(id));
-        exec.steps[`sub:${node.name}`] = { status: 'completed', result, completedAt: Date.now() };
-        await this.advance(exec, idx + 1, wf);
-    }
-    async runWaitFor(exec, node, idx, wf) {
-        if (exec.signals[node.event] !== undefined) {
-            await this.advance(exec, idx + 1, wf);
-            return;
+        const recordKey = `sub:${node.name}`;
+        try {
+            const { results, executionId } = await executeSubWorkflow(node.name, subInput, 
+            // The child must record who owns it: without this, recovery treats it as a
+            // top-level run and drives it behind this parent's back.
+            async (name, input) => {
+                const handle = await this.start(name, input, exec.id);
+                // Claim it in the parent's record BEFORE waiting on it. The record used to be
+                // written only on completion, so a re-entry after a restart found nothing to
+                // resume and started a second child.
+                //
+                // Awaited rather than done on a side branch: a detached `.then()` on a start
+                // that REJECTS, which is what an unregistered child does, leaves an unhandled
+                // rejection even though the caller handles the same rejection properly.
+                exec.steps[recordKey] = { status: 'running', childExecutionId: handle.id };
+                this.store.update(exec);
+                return handle;
+            }, (id) => this.store.get(id), undefined, exec.steps[recordKey]?.childExecutionId);
+            exec.steps[recordKey] = {
+                status: 'completed',
+                result: results,
+                completedAt: clock().now(),
+                childExecutionId: executionId,
+            };
         }
-        const waitKey = `__waitFor:${node.event}`;
-        if (node.timeout !== undefined) {
-            const existing = exec.steps[waitKey];
-            const waitingSince = existing?.startedAt ?? Date.now();
-            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] = {
+        catch (error) {
+            // Settle the record before letting the failure through.
+            //
+            // Only the success write existed, so every interesting outcome — the child failed,
+            // parked in `compensation-stuck`, or timed out — left the record `running`.
+            // `unwindSet` drops anything that is neither `completed` nor `failed` one line
+            // before the `sub:` branch can admit it, so `unwindChild` was never called: a
+            // parent whose child was parked with stock still reserved reversed its own steps,
+            // reached the end of the pass and reported `rollbackStatus: 'completed'`
+            // (`test/repro-workflow-child-park-inherit.test.ts`).
+            //
+            // It is also the truthful record on its own terms. A `sub:` step left `running`
+            // after the parent has failed reads on a dashboard as a child still in flight.
+            const claimed = exec.steps[recordKey];
+            if (claimed) {
+                exec.steps[recordKey] = {
+                    ...claimed,
                     status: 'failed',
-                    startedAt: waitingSince,
-                    completedAt: Date.now(),
-                    error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
+                    error: describeError(error),
+                    completedAt: clock().now(),
                 };
-                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);
-                this.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
-                throw new WaitForSignalError(node.event);
+                // Guarded for the same reason as the failure write in `runner.ts`: `error` below
+                // carries the real cause, and letting a write failure propagate instead replaced
+                // it. The child's own diagnostic is what the rollback guide's field table points
+                // an operator at, `... timed out` or `... is parked mid-rollback; resolve it with
+                // resumeCompensation or abandonCompensation`, so destroying it takes away the
+                // pointer to the child.
+                //
+                // This one does not self-heal, which is what made it worth guarding rather than
+                // commenting: the next write succeeds, persists the wrong diagnostic, and the run
+                // goes terminal carrying it
+                // (`test/repro-workflow-step-error-masking.test.ts`).
+                try {
+                    this.store.update(exec);
+                }
+                catch {
+                    // Deliberately swallowed; the in-memory record still settles the `sub:` step, and
+                    // `runNode` re-persists the whole execution one frame up.
+                }
             }
-            this.store.update(exec);
-            const remaining = node.timeout - (Date.now() - waitingSince);
-            this.scheduleTimeoutCheck(exec.id, exec.workflowName, exec.currentNodeIndex, remaining);
+            throw error;
         }
-        exec.state = 'waiting';
-        this.store.update(exec);
-        this.emitter?.emitWorkflow('workflow:waiting', exec.id, exec.workflowName, 'waiting');
-        throw new WaitForSignalError(node.event);
-    }
-    async runLoop(exec, node, idx, wf, loopFn) {
-        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, this.updateFn);
+    /**
+     * Commit the saga. From here the run can still fail, but it can no longer be
+     * rolled back: recovery past this point is forward-only.
+     */
+    async runPivot(exec, idx, wf) {
+        exec.committedAt = idx;
+        this.store.update(exec);
         await this.advance(exec, idx + 1, wf);
     }
-    async runMap(exec, node, idx, wf) {
-        await executeMap(node.def, exec, this.emitter, this.updateFn);
+    /**
+     * Run a node body that manages its own step records (loops, forEach, map), then
+     * move on. These differ only in which executor they delegate to.
+     */
+    async runBody(exec, idx, wf, run, def) {
+        await run(def, exec, this.emitter, this.updateFn);
         await this.advance(exec, idx + 1, wf);
     }
     async advance(exec, nextIdx, wf) {
@@ -226,20 +355,34 @@ export class WorkflowExecutor {
             workflowName: exec.workflowName,
             nodeIndex: exec.currentNodeIndex,
         };
+        // Deliberately NO deterministic jobId here.
+        //
+        // `<execution>:<nodeIndex>` was tried, to let the queue's custom-id dedup collapse
+        // a duplicate enqueue. It buys nothing the cursor guard in processStep does not
+        // already provide (a duplicate job is ignored there), and it introduces a liveness
+        // risk in exchange: if the custom-id entry outlives the job it names, a legitimate
+        // re-enqueue of the same node is swallowed and the run wedges permanently. A
+        // generated model campaign produced exactly one unexplained `execution wedged in
+        // "running"` with it enabled and none without. A duplicate job that is ignored is
+        // strictly safer than a missing job that never arrives.
         await this.queue.add('wf:step', jobData);
     }
+    get waitForDeps() {
+        return {
+            store: this.store,
+            emitter: this.emitter,
+            advance: (e, next, w) => this.advance(e, next, w),
+            compensate: (e, w) => this.compensate(e, w),
+            scheduleTimeoutCheck: (id, name, i, ms) => {
+                this.scheduleTimeoutCheck(id, name, i, ms);
+            },
+        };
+    }
     scheduleTimeoutCheck(execId, workflowName, nodeIdx, ms) {
-        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 */
-            });
-        }, ms);
-        this.timeoutTimers.set(execId, timer);
+        scheduleTimeoutCheck({ queue: this.queue, timers: this.timeoutTimers }, execId, workflowName, nodeIdx, ms);
     }
     async compensate(exec, wf) {
-        await runCompensation(exec, wf, this.store, this.emitter);
+        await runCompensation(exec, wf, this.store, this.emitter, this.workflows);
     }
     /** Recover orphaned executions after a crash/restart */
     async recover() {
@@ -249,6 +392,7 @@ export class WorkflowExecutor {
             workflows: this.workflows,
             emitter: this.emitter,
             timeoutTimers: this.timeoutTimers,
+            nodesInFlight: this.nodesInFlight,
             scheduleTimeoutCheck: (id, name, idx, ms) => {
                 this.scheduleTimeoutCheck(id, name, idx, ms);
             },

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

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

package/dist/client/workflow/identity.js

@@ -0,0 +1,93 @@
+/**
+ * Idempotency identity for saga steps.
+ *
+ * The key is a function of (run, step name, occurrence, direction) and deliberately
+ * NOT of the attempt number. That is the single most common way to get this wrong:
+ * derive it from the attempt and every automatic retry asks the provider for a
+ * brand-new charge instead of being deduplicated into the first one.
+ *
+ * The three retry semantics collapse into two key behaviours:
+ *
+ *   automatic retry after a transient error -> SAME key (we do not know whether the
+ *   crash-and-resume of the same run       -> SAME key  effect landed; we want dedup)
+ *   a different run of the same logic       -> different key (different run id)
+ *
+ * `occurrence` exists because loop bodies reuse one step name. It is taken from the
+ * loop's iteration index rather than a running counter precisely so that it stays
+ * stable when a resumed loop replays its earlier iterations: replaying iteration 2
+ * must present the key iteration 2 already used, or the provider bills twice.
+ */
+export function idempotencyKey(runId, stepName, occurrence, direction) {
+    return `${runId}:${stepName}#${occurrence}:${direction}`;
+}
+/**
+ * A loop iteration record is `<step>:<digits>` and nothing else.
+ *
+ * Three separate defects came from treating "contains a colon" as the test: a step
+ * legitimately named `charge:extra` was resolved to a loop body called `charge`, was
+ * dropped from the unwind set, and had its compensate context rebound to another
+ * step's result. A colon is a legal character in a user-chosen step name; only the
+ * numeric suffix this engine appends is structural.
+ */
+export const LOOP_ITERATION_SUFFIX = /:\d+$/;
+/**
+ * What is left of an iteration record once its base name is removed: `:` then digits
+ * and NOTHING else.
+ *
+ * Anchoring at both ends is the whole point. Testing the unanchored
+ * `LOOP_ITERATION_SUFFIX` against the remainder only checks that the name ENDS in a
+ * numeric segment, so a loop body whose own name contains a colon collides with a
+ * shorter one: `charge:extra:1` matched base `charge`, leaving remainder `:extra:1`,
+ * which ends in `:1`. `findStepDef` then handed every `charge:extra` iteration the
+ * `charge` handler — `charge`'s reversal ran twice per iteration, `charge:extra`'s
+ * never ran, and the run still reported `rollbackStatus: 'completed'`.
+ */
+const EXACT_ITERATION_REMAINDER = /^:\d+$/;
+/** Is `name` an iteration record of the loop body step `base`? */
+export function isIterationOf(name, base) {
+    return name.startsWith(`${base}:`) && EXACT_ITERATION_REMAINDER.test(name.slice(base.length));
+}
+/** `charge:2` -> `charge`; `charge:extra` -> `charge:extra` (not an iteration). */
+export function loopBaseName(name) {
+    return LOOP_ITERATION_SUFFIX.test(name) ? name.replace(LOOP_ITERATION_SUFFIX, '') : name;
+}
+/**
+ * A human-readable description of anything that was thrown.
+ *
+ * `String(err)` is what this replaced, and for the shape an HTTP client throws most
+ * often, a structured object, it yields `"[object Object]"`. That string was then
+ * persisted as the diagnostic on a run parked in `compensation-stuck`, which is the
+ * state that exists so an operator has something to act on. They were handed a
+ * sentence that says nothing about a refund that did not go through
+ * (`test/repro-workflow-operator-signal.test.ts`).
+ */
+export function describeError(err) {
+    // An AggregateError carries every failure of a `parallel()` group, and taking only
+    // `.message` reported the FIRST one: two steps failed, the persisted
+    // `failureReason` named one, and whoever read it went looking for a single cause
+    // that was not the only cause.
+    if (err instanceof AggregateError && Array.isArray(err.errors) && err.errors.length > 0) {
+        // Recursive, not `String(e)`: a user-thrown aggregate can carry plain objects, and
+        // `String({...})` is the `[object Object]` this function exists to kill.
+        const parts = err.errors.map((e) => describeError(e));
+        return parts.length === 1 ? parts[0] : `${parts.length} failures: ${parts.join('; ')}`;
+    }
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'object' && err !== null) {
+        try {
+            const json = JSON.stringify(err);
+            // A class instance with no enumerable fields serialises to `{}`, which is as
+            // useless as the string it replaced; fall back to the constructor name.
+            if (json && json !== '{}')
+                return json;
+            const name = err.constructor?.name;
+            return name && name !== 'Object' ? `${name} (no serialisable detail)` : String(err);
+        }
+        catch {
+            // Circular, or a throwing getter. The type is still more than nothing.
+            return `${err.constructor?.name ?? 'object'} (not serialisable)`;
+        }
+    }
+    return String(err);
+}

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

@@ -20,4 +20,4 @@ import '../../require-bun';
 export { Workflow } from './workflow';
 export { Engine } from './engine';
 export { WorkflowEmitter } from './emitter';
-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';
+export type { StepContext, StepHandler, TypedStepHandler, CompensateHandler, TypedCompensateHandler, StepOptions, SchemaLike, Execution, ExecutionState, StepState, StepRecord, RollbackStatus, CompensationStatus, CompensationOutcome, BranchCondition, WorkflowNode, EngineOptions, RunHandle, ParallelDefinition, SubWorkflowInputMapper, LoopCondition, ForEachItemsExtractor, MapTransformFn, LoopDefinition, ForEachDefinition, MapDefinition, RecoverResult, CleanupOptions, WorkflowEventType, WorkflowEvent, StepEvent, WorkflowLifecycleEvent, SignalEvent, WorkflowEventListener, } from './types';