bunqueue 2.8.49 → 2.8.50

package/dist/client/workflow/compensationPass.js

@@ -0,0 +1,96 @@
+/** One checkpointed compensation pass. */
+import { compensationContext, settle } from './compensationSupport';
+import { unwindChild } from './compensationChild';
+import { describeError } from './identity';
+import { buildContext, findStepDef, runWithTimeout } from './runner';
+import { decideUnwindAction } from './unwindPlan';
+export async function unwind(pass, runChild) {
+    const { exec, wf, store, emitter, eligible, workflows, retryFailed } = pass;
+    const baseCtx = buildContext(exec);
+    let haltedAt = null;
+    let writeFailure;
+    exec.state = 'compensating';
+    try {
+        store.update(exec);
+    }
+    catch (error) {
+        // Nothing ran, so park the owed unwind and retain the original store error.
+        writeFailure = error;
+        haltedAt = '(the compensating transition)';
+    }
+    if (writeFailure === undefined) {
+        emitter?.emitWorkflow('workflow:compensating', exec.id, exec.workflowName, 'compensating');
+    }
+    for (const [name, record] of eligible) {
+        if (writeFailure !== undefined)
+            break;
+        const action = decideUnwindAction(wf, name, record, haltedAt !== null, retryFailed);
+        if (action.kind === 'stop')
+            break;
+        if (action.kind === 'skip')
+            continue;
+        if (action.kind === 'halt-failed') {
+            haltedAt = name;
+            continue;
+        }
+        if (action.kind === 'halt-vanished') {
+            haltedAt = name;
+            settle(record, 'compensation-failed', action.error);
+            emitter?.emitStep('compensation:failed', exec.id, exec.workflowName, name, {
+                error: 'step no longer declared',
+            });
+            continue;
+        }
+        emitter?.emitStep('compensation:started', exec.id, exec.workflowName, name);
+        try {
+            if (action.kind === 'unwind-child') {
+                await unwindChild({ record, store, emitter, workflows, runChild, retryFailed });
+            }
+            else {
+                const def = findStepDef(wf, name);
+                const controller = new AbortController();
+                const context = {
+                    ...compensationContext(exec, baseCtx, name, record),
+                    signal: controller.signal,
+                };
+                await runWithTimeout(def?.compensate?.(context), action.timeoutMs, controller);
+            }
+            settle(record, 'compensated');
+            emitter?.emitStep('compensation:completed', exec.id, exec.workflowName, name);
+        }
+        catch (error) {
+            const message = describeError(error);
+            settle(record, 'compensation-failed', message);
+            emitter?.emitStep('compensation:failed', exec.id, exec.workflowName, name, {
+                error: message,
+            });
+            haltedAt = name;
+        }
+        try {
+            store.update(exec);
+        }
+        catch (error) {
+            // An unpersisted reversal could run twice on recovery; stop immediately.
+            writeFailure = error;
+            haltedAt = name;
+            break;
+        }
+    }
+    if (haltedAt !== null) {
+        exec.state = 'compensation-stuck';
+        exec.rollbackStatus = 'stuck';
+    }
+    else {
+        exec.state = 'failed';
+        exec.rollbackStatus = 'completed';
+    }
+    try {
+        store.update(exec);
+    }
+    catch (error) {
+        if (writeFailure === undefined)
+            throw error;
+    }
+    if (writeFailure !== undefined)
+        throw writeFailure;
+}

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

@@ -0,0 +1,24 @@
+/** Pure record selection and context construction for saga compensation. */
+import { buildContext } from './runner';
+import type { CompensationStatus, Execution, StepRecord } from './types';
+import type { Workflow } from './workflow';
+/**
+ * Eligible records in reverse start order. Failed records are included because their
+ * external effect may have succeeded before its response was lost.
+ */
+export declare function unwindSet(exec: Execution, wf: Workflow): [string, StepRecord][];
+export declare function settle(record: StepRecord, status: CompensationStatus, error?: string): void;
+/**
+ * Rebind a loop's bare step name to this occurrence and restore forEach item metadata.
+ */
+export declare function compensationContext(exec: Execution, baseCtx: ReturnType<typeof buildContext>, name: string, record: StepRecord): {
+    steps: {
+        [x: string]: unknown;
+    };
+    idempotencyKey: string;
+    forwardIdempotencyKey: string | undefined;
+    input: unknown;
+    signals: Readonly<Record<string, unknown>>;
+    executionId: string;
+    signal?: AbortSignal;
+};

package/dist/client/workflow/compensationSupport.js

@@ -0,0 +1,57 @@
+/** Pure record selection and context construction for saga compensation. */
+import { clock } from './clock';
+import { idempotencyKey, loopBaseName } from './identity';
+import { findStepDef } from './runner';
+/**
+ * Eligible records in reverse start order. Failed records are included because their
+ * external effect may have succeeded before its response was lost.
+ */
+export function unwindSet(exec, wf) {
+    if (exec.committedAt !== undefined)
+        return [];
+    return Object.entries(exec.steps)
+        .filter(([name, record]) => {
+        if (name.startsWith('__'))
+            return false;
+        if (record.status !== 'completed' && record.status !== 'failed')
+            return false;
+        // Indexed loop records are authoritative; the bare name is only the last-result
+        // mirror and compensating both would undo the final iteration twice.
+        if (isLoopBody(wf, name) && exec.steps[`${name}:0`] !== undefined)
+            return false;
+        if (name.startsWith('sub:'))
+            return record.childExecutionId !== undefined;
+        if (findStepDef(wf, name) !== null)
+            return true;
+        // A removed definition must halt rather than disappear from an unwind it owed.
+        return record.compensation !== undefined || record.compensatable === true;
+    })
+        .reverse();
+}
+export function settle(record, status, error) {
+    record.compensation = { status, at: clock().now(), ...(error ? { error } : {}) };
+}
+/**
+ * Rebind a loop's bare step name to this occurrence and restore forEach item metadata.
+ */
+export function compensationContext(exec, baseCtx, name, record) {
+    const occurrence = record.occurrence ?? 0;
+    const base = loopBaseName(name);
+    const ctx = {
+        ...baseCtx,
+        steps: { ...baseCtx.steps, [base]: record.result, [name]: record.result },
+        idempotencyKey: idempotencyKey(exec.id, name, occurrence, 'compensate'),
+        forwardIdempotencyKey: record.idempotencyKey,
+    };
+    if (record.loopIndex === undefined)
+        return ctx;
+    return {
+        ...ctx,
+        steps: { ...ctx.steps, __item: record.loopItem, __index: record.loopIndex },
+    };
+}
+function isLoopBody(wf, name) {
+    return wf.nodes.some((node) => ((node.type === 'doUntil' || node.type === 'doWhile') &&
+        node.def.steps.some((step) => step.name === name)) ||
+        (node.type === 'forEach' && node.def.step.name === name));
+}

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

@@ -1,67 +1,28 @@
 /**
- * Saga rollback — runs compensate handlers in reverse start order.
+ * Public saga-compensation entry points.
  *
- * 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".
+ * A pass is checkpointed per step, halts on an uncertain reversal, and is protected
+ * from overlapping in-process drivers. The execution mechanics live in
+ * compensationPass.ts; record selection lives in compensationSupport.ts.
  */
+import type { WorkflowEmitter } from './emitter';
+import type { WorkflowStore } from './store';
 import type { Execution } from './types';
 import type { Workflow } from './workflow';
-import type { WorkflowStore } from './store';
-import type { WorkflowEmitter } from './emitter';
-/** Sentinel error thrown when execution must pause for a signal */
+export { AbandonedCompensationError, CommittedChildError } from './compensationChild';
+/** Sentinel thrown when an execution deliberately parks for a signal. */
 export declare class WaitForSignalError extends Error {
     readonly event: string;
     constructor(event: string);
 }
-/**
- * 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.
- */
+/** `claim-lost` means another local driver owns the unwind and this call did nothing. */
 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.
+ * Give up on a parked unwind and record an explicit skipped outcome for every
+ * remaining eligible step.
  */
 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);
-}