bunqueue 2.8.46 → 2.8.47

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

@@ -0,0 +1,45 @@
+/**
+ * Whether a node job may run, decided as a pure function.
+ *
+ * WHY THIS FILE EXISTS. Job delivery is at-least-once, so the same node job arrives
+ * twice as a matter of course: a queue retry, a `recover()` over a run the live engine
+ * is already driving, a timeout re-check racing a signal. Three guards decide whether
+ * an arrival is the real one, and when one of them was missing a duplicate re-ran the
+ * node AND every node after it, giving one execution two independent advance chains,
+ * doubled side effects, and a final state of `completed` that hid the whole thing.
+ *
+ * That defect was found by the state-machine model after a long campaign, because the
+ * decision lived inside an async method that also read SQLite and dispatched work: the
+ * only way to observe it was to reproduce the race. As a function of its inputs it is
+ * a table, and a table can be enumerated.
+ *
+ * The three rejections are deliberately distinguished rather than collapsed into a
+ * boolean. `stale-cursor` and `already-in-flight` mean very different things to anyone
+ * reading a log: one is an arrival for work the run has already moved past, the other
+ * is a second arrival for work in progress right now.
+ */
+import type { Execution } from './types';
+export type Admission = {
+    kind: 'run';
+} | {
+    kind: 'reject';
+    /**
+     * `missing`           the execution is not in the store at all
+     * `not-live`          it is terminal, compensating or parked, so no node may run
+     * `stale-cursor`      the job names a node the run has already left
+     * `already-in-flight` this exact node is executing in this process right now
+     */
+    reason: 'missing' | 'not-live' | 'stale-cursor' | 'already-in-flight';
+};
+/** States in which a node job may execute. Anything else is not a live run. */
+export declare function isLive(state: Execution['state']): boolean;
+/**
+ * Decide whether the job for `nodeIndex` of `exec` may run.
+ *
+ * `inFlight` is the set of `<executionId>:<nodeIndex>` claims held by this process.
+ * It is passed in rather than read from module state so the decision stays a function
+ * of its arguments.
+ */
+export declare function decideAdmission(exec: Execution | null, nodeIndex: number, inFlight: ReadonlySet<string>): Admission;
+/** The claim a running node holds. One string, one place that builds it. */
+export declare function claimKey(executionId: string, nodeIndex: number): string;

package/dist/client/workflow/admission.js

@@ -0,0 +1,50 @@
+/**
+ * Whether a node job may run, decided as a pure function.
+ *
+ * WHY THIS FILE EXISTS. Job delivery is at-least-once, so the same node job arrives
+ * twice as a matter of course: a queue retry, a `recover()` over a run the live engine
+ * is already driving, a timeout re-check racing a signal. Three guards decide whether
+ * an arrival is the real one, and when one of them was missing a duplicate re-ran the
+ * node AND every node after it, giving one execution two independent advance chains,
+ * doubled side effects, and a final state of `completed` that hid the whole thing.
+ *
+ * That defect was found by the state-machine model after a long campaign, because the
+ * decision lived inside an async method that also read SQLite and dispatched work: the
+ * only way to observe it was to reproduce the race. As a function of its inputs it is
+ * a table, and a table can be enumerated.
+ *
+ * The three rejections are deliberately distinguished rather than collapsed into a
+ * boolean. `stale-cursor` and `already-in-flight` mean very different things to anyone
+ * reading a log: one is an arrival for work the run has already moved past, the other
+ * is a second arrival for work in progress right now.
+ */
+const RUN = { kind: 'run' };
+/** States in which a node job may execute. Anything else is not a live run. */
+export function isLive(state) {
+    return state === 'running' || state === 'waiting';
+}
+/**
+ * Decide whether the job for `nodeIndex` of `exec` may run.
+ *
+ * `inFlight` is the set of `<executionId>:<nodeIndex>` claims held by this process.
+ * It is passed in rather than read from module state so the decision stays a function
+ * of its arguments.
+ */
+export function decideAdmission(exec, nodeIndex, inFlight) {
+    if (!exec)
+        return { kind: 'reject', reason: 'missing' };
+    if (!isLive(exec.state))
+        return { kind: 'reject', reason: 'not-live' };
+    // `currentNodeIndex` is the execution's own cursor, so a job for any other index is
+    // by definition an arrival for work this run has already moved past.
+    if (nodeIndex !== exec.currentNodeIndex)
+        return { kind: 'reject', reason: 'stale-cursor' };
+    if (inFlight.has(claimKey(exec.id, nodeIndex))) {
+        return { kind: 'reject', reason: 'already-in-flight' };
+    }
+    return RUN;
+}
+/** The claim a running node holds. One string, one place that builds it. */
+export function claimKey(executionId, nodeIndex) {
+    return `${executionId}:${nodeIndex}`;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The engine's only source of time and randomness.
+ *
+ * WHY THIS EXISTS. Every defect this engine has shipped in a crash or concurrency
+ * window took a property-based campaign roughly one run in eleven to surface, and the
+ * seed that produced it did NOT reproduce it: the seed drove the sequence of commands,
+ * while the interleaving came from real timers and real process death. A failing seed
+ * you cannot replay is a bug report you cannot act on.
+ *
+ * With every `Date.now()`, `Math.random()` and `setTimeout` routed through here, a
+ * simulated clock makes a seed drive the interleaving too, so a failure replays
+ * exactly, every time, and a fix can be proven rather than hoped for.
+ *
+ * WHAT THIS IS NOT. It does not make the engine deterministic on its own: SQLite, the
+ * queue's own worker loop and the OS scheduler are still outside. It removes the
+ * engine's own contribution, which is the part the engine can be held responsible for.
+ *
+ * The default is the real clock, and it is installed by default, so nothing changes
+ * for anyone who does not ask for a simulated one.
+ */
+export interface Clock {
+    /** Milliseconds since the epoch. */
+    now(): number;
+    /** Schedule `fn` after `ms`. The handle is whatever `clear` accepts. */
+    setTimeout(fn: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    /** A number in [0, 1). Used for retry jitter and execution ids. */
+    random(): number;
+}
+export interface TimerHandle {
+    /** Real timers can be unref'd so a pending one does not hold the process open. */
+    unref?(): void;
+}
+/** The clock the engine reads. Real unless a simulation installed its own. */
+export declare function clock(): Clock;
+/**
+ * Install a clock, returning the previous one so a test can restore it.
+ *
+ * Deliberately process-global rather than threaded through every call site: the
+ * alternative is a `Clock` parameter on roughly forty internal functions, which is a
+ * large diff through code whose correctness was hard-won, for no gain in a runtime
+ * that already keeps one engine per process.
+ */
+export declare function setClock(next: Clock): Clock;
+/** Restore the real clock. */
+export declare function resetClock(): void;
+/**
+ * A clock where time only moves when the simulation says so.
+ *
+ * `advance` fires every timer due at or before the new instant, in due order, and
+ * timers scheduled BY those callbacks are picked up in the same advance, so a chain of
+ * re-armed timeouts settles the way it would in real time rather than needing one
+ * `advance` per link. Ties break by insertion order, so a seed replays identically.
+ */
+export declare function simulatedClock(seed: number, startAt?: number): Clock & {
+    advance(ms: number): number;
+    pending(): number;
+};

package/dist/client/workflow/clock.js

@@ -0,0 +1,104 @@
+/**
+ * The engine's only source of time and randomness.
+ *
+ * WHY THIS EXISTS. Every defect this engine has shipped in a crash or concurrency
+ * window took a property-based campaign roughly one run in eleven to surface, and the
+ * seed that produced it did NOT reproduce it: the seed drove the sequence of commands,
+ * while the interleaving came from real timers and real process death. A failing seed
+ * you cannot replay is a bug report you cannot act on.
+ *
+ * With every `Date.now()`, `Math.random()` and `setTimeout` routed through here, a
+ * simulated clock makes a seed drive the interleaving too, so a failure replays
+ * exactly, every time, and a fix can be proven rather than hoped for.
+ *
+ * WHAT THIS IS NOT. It does not make the engine deterministic on its own: SQLite, the
+ * queue's own worker loop and the OS scheduler are still outside. It removes the
+ * engine's own contribution, which is the part the engine can be held responsible for.
+ *
+ * The default is the real clock, and it is installed by default, so nothing changes
+ * for anyone who does not ask for a simulated one.
+ */
+const realClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (h) => globalThis.clearTimeout(h),
+    random: () => Math.random(),
+};
+let current = realClock;
+/** The clock the engine reads. Real unless a simulation installed its own. */
+export function clock() {
+    return current;
+}
+/**
+ * Install a clock, returning the previous one so a test can restore it.
+ *
+ * Deliberately process-global rather than threaded through every call site: the
+ * alternative is a `Clock` parameter on roughly forty internal functions, which is a
+ * large diff through code whose correctness was hard-won, for no gain in a runtime
+ * that already keeps one engine per process.
+ */
+export function setClock(next) {
+    const previous = current;
+    current = next;
+    return previous;
+}
+/** Restore the real clock. */
+export function resetClock() {
+    current = realClock;
+}
+/**
+ * A clock where time only moves when the simulation says so.
+ *
+ * `advance` fires every timer due at or before the new instant, in due order, and
+ * timers scheduled BY those callbacks are picked up in the same advance, so a chain of
+ * re-armed timeouts settles the way it would in real time rather than needing one
+ * `advance` per link. Ties break by insertion order, so a seed replays identically.
+ */
+export function simulatedClock(seed, startAt = 1_700_000_000_000) {
+    let time = startAt;
+    let sequence = 0;
+    let state = seed >>> 0 || 0x9e3779b9;
+    const timers = new Map();
+    const random = () => {
+        // xorshift32: small, seeded, and identical across runs and platforms.
+        state ^= state << 13;
+        state ^= state >>> 17;
+        state ^= state << 5;
+        return ((state >>> 0) % 1_000_000) / 1_000_000;
+    };
+    return {
+        now: () => time,
+        random,
+        setTimeout(fn, ms) {
+            const id = sequence++;
+            timers.set(id, { at: time + Math.max(0, ms), order: id, fn });
+            return { unref() { }, __id: id };
+        },
+        clearTimeout(handle) {
+            const id = handle?.__id;
+            if (id !== undefined)
+                timers.delete(id);
+        },
+        pending: () => timers.size,
+        advance(ms) {
+            const target = time + ms;
+            let fired = 0;
+            for (;;) {
+                const due = [...timers.entries()]
+                    .filter(([, t]) => t.at <= target)
+                    .sort((a, b) => a[1].at - b[1].at || a[1].order - b[1].order);
+                const next = due[0];
+                if (!next)
+                    break;
+                timers.delete(next[0]);
+                time = Math.max(time, next[1].at);
+                next[1].fn();
+                fired++;
+                if (fired > 100_000)
+                    throw new Error('simulatedClock: timer storm, over 100000 firings');
+            }
+            time = target;
+            return fired;
+        },
+    };
+}

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

@@ -1,5 +1,23 @@
 /**
- * Compensation logic - runs compensate handlers in reverse order on failure
+ * Saga rollback — runs compensate handlers in reverse start order.
+ *
+ * Four properties this file is responsible for, each of which used to be violated:
+ *
+ *  - EXACTLY ONE OUTCOME per eligible step. Success is recorded as loudly as
+ *    failure, and a step the unwind never reached is recorded as skipped rather
+ *    than left blank. "Never zero, never two" is not checkable otherwise.
+ *  - NEVER TWICE. A step that already carries an outcome is not re-run, so an
+ *    unwind interrupted by a crash resumes where it stopped instead of replaying
+ *    reversals from the top.
+ *  - HALT, NOT PLOUGH ON. A compensation that fails definitively stops the chain:
+ *    continuing past it would undo things whose dependencies are still standing.
+ *    The remaining eligible steps are marked skipped so the gap is visible.
+ *  - PIVOT. Past `.pivot()` the saga is committed; those steps are never eligible.
+ *
+ * `rollbackStatus` on the execution is a separate axis from the failure reason. The
+ * rollback is what the engine did *after* the failure, not why it failed, and an
+ * operator needs to alert on "the refund never went through" independently of "the
+ * payment failed".
  */
 import type { Execution } from './types';
 import type { Workflow } from './workflow';
@@ -10,5 +28,40 @@ export declare class WaitForSignalError extends Error {
     readonly event: string;
     constructor(event: string);
 }
-/** Run compensation handlers in reverse order for all completed steps */
-export declare function runCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null): Promise<void>;
+/**
+ * Deliberately NOT exported, and deliberately never bulk-cleared.
+ *
+ * `Engine.close()` used to call a `releaseUnwindClaim()` that emptied this set. The
+ * set is process-global, so closing ANY engine dropped the claim protecting an unwind
+ * still running under a DIFFERENT one, and the next caller re-dispatched compensate
+ * handlers that were mid-flight: the duplicate refund this claim exists to stop.
+ *
+ * Nothing needs to clear it. `runCompensation` releases in a `finally`, so a claim
+ * outlives its unwind by nothing, bounded by the step's own `timeout` even if the
+ * handler wedges. If the process dies the module state dies with it.
+ */
+/**
+ * Outcome of asking for an unwind. `claim-lost` means another unwind of the same
+ * execution is already in flight, so THIS call did nothing and its caller must not
+ * treat the rollback as done.
+ */
+export type UnwindOutcome = 'ran' | 'claim-lost';
+/** Run compensation handlers in reverse start order for every eligible step. */
+export declare function runCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null, workflows?: Map<string, Workflow>, opts?: {
+    retryFailed?: boolean;
+}): Promise<UnwindOutcome>;
+/**
+ * Give up on a parked unwind: every eligible step still without an outcome is
+ * recorded as skipped, and the run becomes terminal. This is where "exactly one
+ * outcome per eligible step" is finally discharged.
+ */
+export declare function abandonCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null): void;
+/**
+ * A sub-workflow that passed its own pivot cannot be rolled back. Distinct from a
+ * handler failure so the parent's record carries the reason rather than a generic
+ * error, and so the parent parks (operator decision) instead of silently claiming
+ * success.
+ */
+export declare class CommittedChildError extends Error {
+    constructor(workflowName: string, executionId: string);
+}