bunqueue 2.8.59 → 2.9.0

package/dist/client/workflow/executor.js

@@ -8,19 +8,23 @@ import { claimKey, decideAdmission } from './admission';
 import { signalExecution, startExecution } from './executorLifecycle';
 import { executeWorkflowNode } from './executorNodes';
 import { bindExecutionDefinition, WorkflowDefinitionMismatchError } from './definitionGuard';
+import { isWorkflowExecutionClosed, WorkflowExecutionFence } from './executionFence';
+import { enqueueWorkflowStep } from './executorQueue';
 export class WorkflowExecutor {
     store;
     queue;
     emitter;
     workflows = new Map();
     timeoutTimers = new Map();
+    fence = new WorkflowExecutionFence();
     /**
      * 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() {
+    close(force = false) {
+        this.fence.close(force);
         clearTimers(this.timeoutTimers);
     }
     updateFn;
@@ -29,10 +33,12 @@ export class WorkflowExecutor {
         this.queue = queue;
         this.emitter = emitter;
         this.updateFn = (e) => {
+            this.fence.assertActive();
             this.store.update(e);
         };
     }
     register(workflow) {
+        this.fence.assertActive();
         if (this.workflows.has(workflow.name)) {
             throw new Error(`Workflow "${workflow.name}" is already registered`);
         }
@@ -58,31 +64,21 @@ export class WorkflowExecutor {
         this.workflows.set(workflow.name, workflow);
     }
     async start(workflowName, input, parentExecutionId) {
+        this.fence.assertActive();
         return await startExecution(this.lifecycleDeps, workflowName, input, parentExecutionId);
     }
     /**
      * 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.
+     * The cursor rejects stale jobs but not two overlapping deliveries for the current
+     * node. This process-local claim drops that overlap. Queue-level dedup is unsuitable:
+     * a retained ID can swallow a legitimate recovery enqueue and wedge the run.
      */
     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.
+        if (!this.fence.isActive())
+            return null;
+        // Admission is pure; this method only owns the in-flight claim and dispatch.
         const exec = this.store.get(data.executionId);
         const admission = decideAdmission(exec, data.nodeIndex, this.nodesInFlight);
         if (admission.kind === 'reject' || !exec)
@@ -106,8 +102,9 @@ export class WorkflowExecutor {
             exec.state = 'running';
         const node = wf.nodes[data.nodeIndex];
         if (!node) {
+            this.fence.assertActive();
             exec.state = 'completed';
-            this.store.update(exec);
+            this.updateFn(exec);
             this.emitter?.emitWorkflow('workflow:completed', exec.id, exec.workflowName, 'completed');
             return null;
         }
@@ -115,26 +112,27 @@ export class WorkflowExecutor {
             await executeWorkflowNode(this.nodeDeps, exec, node, data.nodeIndex, wf);
         }
         catch (err) {
+            if (!this.fence.isActive() || isWorkflowExecutionClosed(err))
+                return null;
             if (err instanceof WaitForSignalError)
                 return null;
+            this.fence.assertActive();
             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);
+            // A failed transition must persist before compensation starts. If the guarded
+            // write fails, recovery sees the old running row and re-drives this node.
+            this.updateFn(exec);
             this.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
+            if (!this.fence.isActive())
+                return null;
             await this.compensate(exec, wf);
             throw err;
         }
         return null;
     }
     async signal(executionId, event, payload) {
+        this.fence.assertActive();
         await signalExecution(this.lifecycleDeps, executionId, event, payload);
     }
     get lifecycleDeps() {
@@ -145,14 +143,17 @@ export class WorkflowExecutor {
             emitter: this.emitter,
             timers: this.timeoutTimers,
             enqueue: (exec) => this.enqueue(exec),
+            assertActive: this.fence.assertActive,
         };
     }
     /** Retry the compensation that parked the run, then finish the unwind. */
     async resumeCompensation(executionId) {
+        this.fence.assertActive();
         await resumeCompensation(this.rollbackDeps, executionId);
     }
     /** Give up on a parked unwind, recording the outstanding steps as skipped. */
     abandonCompensation(executionId) {
+        this.fence.assertActive();
         abandonParkedCompensation(this.rollbackDeps, executionId);
     }
     get rollbackDeps() {
@@ -160,6 +161,7 @@ export class WorkflowExecutor {
             store: this.store,
             emitter: this.emitter,
             workflows: this.workflows,
+            assertActive: this.fence.assertActive,
         };
     }
     getExecution(id) {
@@ -177,14 +179,16 @@ export class WorkflowExecutor {
             start: (name, input, parentId) => this.start(name, input, parentId),
             enqueue: (exec) => this.enqueue(exec),
             waitFor: this.waitForDeps,
+            assertActive: this.fence.assertActive,
         };
     }
     async advance(exec, nextIdx, wf) {
+        this.fence.assertActive();
         exec.currentNodeIndex = nextIdx;
-        this.store.update(exec);
+        this.updateFn(exec);
         if (nextIdx >= wf.nodes.length) {
             exec.state = 'completed';
-            this.store.update(exec);
+            this.updateFn(exec);
             this.emitter?.emitWorkflow('workflow:completed', exec.id, exec.workflowName, 'completed');
         }
         else {
@@ -192,22 +196,7 @@ export class WorkflowExecutor {
         }
     }
     async enqueue(exec) {
-        const jobData = {
-            executionId: exec.id,
-            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);
+        await enqueueWorkflowStep(this.queue, exec, this.fence.assertActive);
     }
     get waitForDeps() {
         return {
@@ -215,19 +204,30 @@ export class WorkflowExecutor {
             emitter: this.emitter,
             advance: (e, next, w) => this.advance(e, next, w),
             compensate: (e, w) => this.compensate(e, w),
+            updateFn: this.updateFn,
+            assertActive: this.fence.assertActive,
             scheduleTimeoutCheck: (id, name, i, ms) => {
                 this.scheduleTimeoutCheck(id, name, i, ms);
             },
         };
     }
     scheduleTimeoutCheck(execId, workflowName, nodeIdx, ms) {
-        scheduleTimeoutCheck({ queue: this.queue, timers: this.timeoutTimers }, execId, workflowName, nodeIdx, ms);
+        scheduleTimeoutCheck({
+            queue: this.queue,
+            timers: this.timeoutTimers,
+            assertActive: this.fence.assertActive,
+            isActive: () => this.fence.isActive(),
+        }, execId, workflowName, nodeIdx, ms);
     }
     async compensate(exec, wf) {
-        await runCompensation(exec, wf, this.store, this.emitter, this.workflows);
+        this.fence.assertActive();
+        await runCompensation(exec, wf, this.store, this.emitter, this.workflows, {
+            assertActive: this.fence.assertActive,
+        });
     }
     /** Recover orphaned executions after a crash/restart */
     async recover() {
+        this.fence.assertActive();
         return await recoverExecutions({
             store: this.store,
             queue: this.queue,
@@ -235,6 +235,7 @@ export class WorkflowExecutor {
             emitter: this.emitter,
             timeoutTimers: this.timeoutTimers,
             nodesInFlight: this.nodesInFlight,
+            assertActive: this.fence.assertActive,
             scheduleTimeoutCheck: (id, name, idx, ms) => {
                 this.scheduleTimeoutCheck(id, name, idx, ms);
             },

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

@@ -12,6 +12,7 @@ interface LifecycleDeps {
     emitter: WorkflowEmitter | null;
     timers: Map<string, TimerHandle>;
     enqueue: (exec: Execution) => Promise<void>;
+    assertActive: () => void;
 }
 export declare function startExecution(deps: LifecycleDeps, workflowName: string, input: unknown, parentExecutionId?: string): Promise<RunHandle>;
 export declare function signalExecution(deps: LifecycleDeps, executionId: string, event: string, payload: unknown): Promise<void>;

package/dist/client/workflow/executorLifecycle.js

@@ -3,6 +3,7 @@ import { clock } from './clock';
 import { unusableEventName } from './workflow';
 import { newExecutionId } from './identity';
 export async function startExecution(deps, workflowName, input, parentExecutionId) {
+    deps.assertActive();
     const wf = deps.workflows.get(workflowName);
     if (!wf)
         throw new Error(`Workflow "${workflowName}" not registered`);
@@ -23,20 +24,36 @@ export async function startExecution(deps, workflowName, input, parentExecutionI
         createdAt: now,
         updatedAt: now,
     };
+    deps.assertActive();
     deps.store.save(exec);
-    deps.emitter?.emitWorkflow('workflow:started', id, workflowName, 'running', { input });
     try {
+        deps.emitter?.emitWorkflow('workflow:started', id, workflowName, 'running', { input });
+        deps.assertActive();
         await deps.enqueue(exec);
+        deps.assertActive();
     }
     catch (error) {
         // start() cannot return an id when publication fails. Removing the row keeps both
         // top-level starts and sub-workflow starts from creating an unreachable orphan.
-        deps.store.remove(id);
-        throw error;
+        let failure = error;
+        try {
+            deps.assertActive();
+        }
+        catch (closedError) {
+            failure = closedError;
+        }
+        try {
+            deps.store.remove(id);
+        }
+        catch {
+            // If shutdown already closed SQLite, recovery owns the still-running row.
+        }
+        throw failure;
     }
     return { id, workflowName };
 }
 export async function signalExecution(deps, executionId, event, payload) {
+    deps.assertActive();
     const bad = unusableEventName(event);
     if (bad)
         throw new Error(`Cannot signal an event ${bad}`);
@@ -48,22 +65,36 @@ export async function signalExecution(deps, executionId, event, payload) {
     deps.emitter?.emitSignal('signal:received', executionId, outcome.workflowName, event, payload);
     if (!outcome.resumed)
         return;
-    const timer = deps.timers.get(executionId);
-    if (timer) {
-        clock().clearTimeout(timer);
-        deps.timers.delete(executionId);
-    }
     try {
+        deps.assertActive();
+        const timer = deps.timers.get(executionId);
+        if (timer) {
+            clock().clearTimeout(timer);
+            deps.timers.delete(executionId);
+        }
         await deps.queue.add('wf:step', {
             executionId,
             workflowName: outcome.workflowName,
             nodeIndex: outcome.currentNodeIndex,
         });
+        deps.assertActive();
     }
     catch (error) {
         // Preserve the accepted payload but release the publication claim. Recovery sees
         // a waiting execution with its signal present and republishes the same node.
-        deps.store.restoreSignalWait(executionId, event, outcome.currentNodeIndex);
-        throw error;
+        let failure = error;
+        try {
+            deps.assertActive();
+        }
+        catch (closedError) {
+            failure = closedError;
+        }
+        try {
+            deps.store.restoreSignalWait(executionId, event, outcome.currentNodeIndex);
+        }
+        catch {
+            // A closed store leaves a recoverable running row with its signal preserved.
+        }
+        throw failure;
     }
 }

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

@@ -12,6 +12,7 @@ interface NodeExecutionDeps {
     start: (name: string, input: unknown, parentId: string) => Promise<RunHandle>;
     enqueue: (exec: Execution) => Promise<void>;
     waitFor: WaitForDeps;
+    assertActive: () => void;
 }
 export declare function executeWorkflowNode(deps: NodeExecutionDeps, exec: Execution, node: WorkflowNode, idx: number, wf: Workflow): Promise<void>;
 export {};

package/dist/client/workflow/executorNodes.js

@@ -1,51 +1,61 @@
 /** Workflow node dispatch, split from the executor's lifecycle orchestration. */
 import { clock } from './clock';
+import { isWorkflowExecutionClosed } from './executionFence';
 import { describeError } from './identity';
 import { executeDoUntil, executeDoWhile, executeForEach, executeMap } from './loops';
 import { buildContext, executeParallelSteps, executeStepWithRetry, executeSubWorkflow, } from './runner';
 import { runWaitFor } from './waitFor';
 import { branchDecisionKey, resolveDecision, subWorkflowInputDecisionKey, } from './workflowDecisions';
 export async function executeWorkflowNode(deps, exec, node, idx, wf) {
+    deps.assertActive();
     if (node.type === 'step') {
         await executeStepWithRetry(node.def, buildContext(exec), exec, {
             emitter: deps.emitter,
             updateFn: deps.updateFn,
+            assertActive: deps.assertActive,
         });
     }
     else if (node.type === 'branch') {
         await runBranch(deps, exec, node, idx);
     }
     else if (node.type === 'parallel') {
-        await executeParallelSteps(node.def.steps, buildContext(exec), exec, deps.emitter, deps.updateFn);
+        await executeParallelSteps(node.def.steps, buildContext(exec), exec, {
+            emitter: deps.emitter,
+            updateFn: deps.updateFn,
+            assertActive: deps.assertActive,
+        });
     }
     else if (node.type === 'subWorkflow') {
         await runSubWorkflow(deps, exec, node, idx);
     }
     else if (node.type === 'doUntil') {
-        await executeDoUntil(node.def, exec, deps.emitter, deps.updateFn);
+        await executeDoUntil(node.def, exec, deps.emitter, deps.updateFn, deps.assertActive);
     }
     else if (node.type === 'doWhile') {
-        await executeDoWhile(node.def, exec, deps.emitter, deps.updateFn);
+        await executeDoWhile(node.def, exec, deps.emitter, deps.updateFn, deps.assertActive);
     }
     else if (node.type === 'forEach') {
-        await executeForEach(node.def, exec, deps.emitter, deps.updateFn);
+        await executeForEach(node.def, exec, deps.emitter, deps.updateFn, deps.assertActive);
     }
     else if (node.type === 'map') {
-        await executeMap(node.def, exec, deps.emitter, deps.updateFn);
+        await executeMap(node.def, exec, deps.emitter, deps.updateFn, deps.assertActive);
     }
     else if (node.type === 'pivot') {
         // A pivot commits the saga before the cursor moves beyond it.
         exec.committedAt = idx;
-        deps.store.update(exec);
+        deps.updateFn(exec);
     }
     else {
         await runWaitFor(deps.waitFor, exec, node, idx, wf);
         return;
     }
+    deps.assertActive();
     await deps.advance(exec, idx + 1, wf);
 }
 async function runBranch(deps, exec, node, idx) {
-    const pathName = await resolveDecision(exec, branchDecisionKey(idx), () => node.def.condition(buildContext(exec)), deps.updateFn);
+    deps.assertActive();
+    const pathName = await resolveDecision(exec, branchDecisionKey(idx), () => node.def.condition(buildContext(exec)), deps.updateFn, deps.assertActive);
+    deps.assertActive();
     if (typeof pathName !== 'string') {
         throw new Error(`Branch at node ${idx} returned a non-string path`);
     }
@@ -66,26 +76,37 @@ async function runBranch(deps, exec, node, idx) {
         await executeStepWithRetry(step, buildContext(exec), exec, {
             emitter: deps.emitter,
             updateFn: deps.updateFn,
+            assertActive: deps.assertActive,
         });
+        deps.assertActive();
     }
 }
 async function runSubWorkflow(deps, exec, node, idx) {
-    const subInput = await resolveDecision(exec, subWorkflowInputDecisionKey(idx), () => structuredClone(node.inputMapper(buildContext(exec))), deps.updateFn);
+    deps.assertActive();
+    const subInput = await resolveDecision(exec, subWorkflowInputDecisionKey(idx), () => structuredClone(node.inputMapper(buildContext(exec))), deps.updateFn, deps.assertActive);
+    deps.assertActive();
     const recordKey = `sub:${node.name}`;
     const childExecutionId = await adoptExistingChild(deps, exec, node.name, recordKey);
+    deps.assertActive();
     try {
         const { results, executionId } = await executeSubWorkflow(node.name, subInput, async (name, input) => {
             const handle = await deps.start(name, input, exec.id);
+            deps.assertActive();
             // Claim the child before polling it. A restart can then resume the existing
             // child instead of starting another one.
             exec.steps[recordKey] = { status: 'running', childExecutionId: handle.id };
-            deps.store.update(exec);
+            deps.updateFn(exec);
             return handle;
-        }, (id) => deps.store.get(id), {
+        }, (id) => {
+            deps.assertActive();
+            return deps.store.get(id);
+        }, {
             pollIntervalMs: node.pollInterval,
             maxWaitMs: node.timeout,
             existingChildId: childExecutionId,
+            assertActive: deps.assertActive,
         });
+        deps.assertActive();
         exec.steps[recordKey] = {
             status: 'completed',
             result: results,
@@ -94,11 +115,15 @@ async function runSubWorkflow(deps, exec, node, idx) {
         };
     }
     catch (error) {
-        settleFailedChild(deps.store, exec, recordKey, error);
+        if (isWorkflowExecutionClosed(error))
+            throw error;
+        deps.assertActive();
+        settleFailedChild(deps.updateFn, exec, recordKey, error);
         throw error;
     }
 }
 async function adoptExistingChild(deps, exec, workflowName, recordKey) {
+    deps.assertActive();
     const claimedId = exec.steps[recordKey]?.childExecutionId;
     const child = claimedId ? deps.store.get(claimedId) : deps.store.findChild(exec.id, workflowName);
     if (!child)
@@ -109,16 +134,18 @@ async function adoptExistingChild(deps, exec, workflowName, recordKey) {
             status: 'running',
             childExecutionId: child.id,
         };
-        deps.store.update(exec);
+        deps.updateFn(exec);
     }
     // The child row is durable before its initial queue publication. A crash in that
     // gap leaves it running but undelivered; duplicate publication is safe because node
     // admission and persisted outcomes make it idempotent.
-    if (child.state === 'running')
+    if (child.state === 'running') {
         await deps.enqueue(child);
+        deps.assertActive();
+    }
     return child.id;
 }
-function settleFailedChild(store, exec, recordKey, error) {
+function settleFailedChild(updateFn, exec, recordKey, error) {
     const claimed = exec.steps[recordKey];
     if (!claimed)
         return;
@@ -129,9 +156,11 @@ function settleFailedChild(store, exec, recordKey, error) {
         completedAt: clock().now(),
     };
     try {
-        store.update(exec);
+        updateFn(exec);
     }
-    catch {
+    catch (writeError) {
+        if (isWorkflowExecutionClosed(writeError))
+            throw writeError;
         // The generic failure path persists this in-memory record. Do not replace the
         // child's diagnostic with an incidental write error.
     }

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

@@ -0,0 +1,9 @@
+/** Durable workflow-node publication shared by execution and recovery. */
+import type { Queue } from '../queue/queue';
+import type { Execution } from './types';
+/**
+ * Publish one node without a deterministic job ID. The cursor and in-flight guards
+ * discard overlapping duplicates, while queue-level dedup could suppress a legitimate
+ * re-enqueue after recovery and wedge the execution permanently.
+ */
+export declare function enqueueWorkflowStep(queue: Queue, exec: Execution, assertActive: () => void): Promise<void>;

package/dist/client/workflow/executorQueue.js

@@ -0,0 +1,15 @@
+/** Durable workflow-node publication shared by execution and recovery. */
+/**
+ * Publish one node without a deterministic job ID. The cursor and in-flight guards
+ * discard overlapping duplicates, while queue-level dedup could suppress a legitimate
+ * re-enqueue after recovery and wedge the execution permanently.
+ */
+export async function enqueueWorkflowStep(queue, exec, assertActive) {
+    assertActive();
+    const jobData = {
+        executionId: exec.id,
+        workflowName: exec.workflowName,
+        nodeIndex: exec.currentNodeIndex,
+    };
+    await queue.add('wf:step', jobData);
+}

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

@@ -0,0 +1,4 @@
+/** Durable forEach execution, split from conditional loop runners. */
+import type { Execution, ForEachDefinition } from './types';
+import type { WorkflowEmitter } from './emitter';
+export declare function executeForEach(def: ForEachDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;

package/dist/client/workflow/forEachRunner.js

@@ -0,0 +1,70 @@
+/** Durable forEach execution, split from conditional loop runners. */
+import { assertWorkflowActive, isWorkflowExecutionClosed } from './executionFence';
+import { buildContext, executeStepWithRetry } from './runner';
+import { forEachItemsDecisionKey, resolveDecision } from './workflowDecisions';
+export async function executeForEach(def, exec, emitter, updateFn, assertActive = assertWorkflowActive) {
+    assertActive();
+    const items = await resolveDecision(exec, forEachItemsDecisionKey(def.step.name), () => structuredClone(def.items(buildContext(exec))), updateFn, assertActive);
+    assertActive();
+    // Array-likes used to report success while doing the wrong amount of work: a number
+    // ran zero items and a string ran one item per character.
+    if (!Array.isArray(items)) {
+        throw new Error(`forEach items must be an array, got ${items === null ? 'null' : typeof items}`);
+    }
+    if (items.length > def.maxIterations) {
+        throw new Error(`forEach items (${items.length}) exceeds maxIterations (${def.maxIterations})`);
+    }
+    for (let i = 0; i < items.length; i++) {
+        assertActive();
+        const item = structuredClone(items[i]);
+        const indexedName = `${def.step.name}:${i}`;
+        const indexedStep = {
+            ...def.step,
+            name: indexedName,
+            handler: (stepCtx) => def.step.handler({
+                ...stepCtx,
+                steps: { ...stepCtx.steps, __item: item, __index: i },
+            }),
+        };
+        // A completed item is memoised; the bare name remains the aggregate view of the
+        // last iteration for loop conditions and downstream steps.
+        const completed = exec.steps[indexedName];
+        if (completed?.status === 'completed') {
+            exec.steps[def.step.name] = { ...completed };
+            updateFn(exec);
+            continue;
+        }
+        let thrown;
+        let threw = false;
+        try {
+            await executeStepWithRetry(indexedStep, buildContext(exec), exec, { emitter, updateFn, assertActive }, i);
+            assertActive();
+        }
+        catch (error) {
+            if (isWorkflowExecutionClosed(error))
+                throw error;
+            assertActive();
+            thrown = error;
+            threw = true;
+        }
+        // Persist the item identity on both success and failure. A failed provider call
+        // can still need compensation, and its reversal needs the original item/index.
+        const record = exec.steps[indexedName];
+        if (record) {
+            record.loopItem = item;
+            record.loopIndex = i;
+            exec.steps[def.step.name] = { ...record };
+            try {
+                updateFn(exec);
+            }
+            catch (writeError) {
+                if (isWorkflowExecutionClosed(writeError))
+                    throw writeError;
+                if (!threw)
+                    throw writeError;
+            }
+        }
+        if (threw)
+            throw thrown;
+    }
+}

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

@@ -1,12 +1,11 @@
 /**
  * Loop execution logic for the Workflow Engine.
  */
-import type { Execution, LoopDefinition, ForEachDefinition } from './types';
+import type { Execution, LoopDefinition } from './types';
 import type { WorkflowEmitter } from './emitter';
 export { executeMap } from './mapRunner';
+export { executeForEach } from './forEachRunner';
 /** Execute a doUntil loop: run steps, then check condition. Repeat until condition returns true. */
-export declare function executeDoUntil(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;
+export declare function executeDoUntil(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;
 /** Execute a doWhile loop: check condition first, then run steps. Repeat while condition is true. */
-export declare function executeDoWhile(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;
-/** Execute a forEach loop: iterate over items, executing the step for each */
-export declare function executeForEach(def: ForEachDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;
+export declare function executeDoWhile(def: LoopDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void, assertActive?: () => void): Promise<void>;