bunqueue 2.8.49 → 2.8.50

package/dist/client/workflow/executorNodes.js

@@ -0,0 +1,138 @@
+/** Workflow node dispatch, split from the executor's lifecycle orchestration. */
+import { clock } from './clock';
+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) {
+    if (node.type === 'step') {
+        await executeStepWithRetry(node.def, buildContext(exec), exec, {
+            emitter: deps.emitter,
+            updateFn: deps.updateFn,
+        });
+    }
+    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);
+    }
+    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);
+    }
+    else if (node.type === 'doWhile') {
+        await executeDoWhile(node.def, exec, deps.emitter, deps.updateFn);
+    }
+    else if (node.type === 'forEach') {
+        await executeForEach(node.def, exec, deps.emitter, deps.updateFn);
+    }
+    else if (node.type === 'map') {
+        await executeMap(node.def, exec, deps.emitter, deps.updateFn);
+    }
+    else if (node.type === 'pivot') {
+        // A pivot commits the saga before the cursor moves beyond it.
+        exec.committedAt = idx;
+        deps.store.update(exec);
+    }
+    else {
+        await runWaitFor(deps.waitFor, exec, node, idx, wf);
+        return;
+    }
+    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);
+    if (typeof pathName !== 'string') {
+        throw new Error(`Branch at node ${idx} returned a non-string path`);
+    }
+    const pathSteps = node.def.paths.get(pathName);
+    if (!pathSteps) {
+        throw new Error(`Branch at node ${idx} resolved unknown path "${pathName}"`);
+    }
+    const selectedNames = pathSteps.map((step) => step.name);
+    const resolved = new Set(exec.resolvedSteps ?? []);
+    const previousSize = resolved.size;
+    for (const name of selectedNames)
+        resolved.add(name);
+    if (resolved.size !== previousSize) {
+        exec.resolvedSteps = [...resolved];
+        deps.updateFn(exec);
+    }
+    for (const step of pathSteps) {
+        await executeStepWithRetry(step, buildContext(exec), exec, {
+            emitter: deps.emitter,
+            updateFn: deps.updateFn,
+        });
+    }
+}
+async function runSubWorkflow(deps, exec, node, idx) {
+    const subInput = await resolveDecision(exec, subWorkflowInputDecisionKey(idx), () => structuredClone(node.inputMapper(buildContext(exec))), deps.updateFn);
+    const recordKey = `sub:${node.name}`;
+    const childExecutionId = await adoptExistingChild(deps, exec, node.name, recordKey);
+    try {
+        const { results, executionId } = await executeSubWorkflow(node.name, subInput, async (name, input) => {
+            const handle = await deps.start(name, input, exec.id);
+            // 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);
+            return handle;
+        }, (id) => deps.store.get(id), {
+            pollIntervalMs: node.pollInterval,
+            maxWaitMs: node.timeout,
+            existingChildId: childExecutionId,
+        });
+        exec.steps[recordKey] = {
+            status: 'completed',
+            result: results,
+            completedAt: clock().now(),
+            childExecutionId: executionId,
+        };
+    }
+    catch (error) {
+        settleFailedChild(deps.store, exec, recordKey, error);
+        throw error;
+    }
+}
+async function adoptExistingChild(deps, exec, workflowName, recordKey) {
+    const claimedId = exec.steps[recordKey]?.childExecutionId;
+    const child = claimedId ? deps.store.get(claimedId) : deps.store.findChild(exec.id, workflowName);
+    if (!child)
+        return claimedId;
+    if (!claimedId) {
+        exec.steps[recordKey] = {
+            ...exec.steps[recordKey],
+            status: 'running',
+            childExecutionId: child.id,
+        };
+        deps.store.update(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')
+        await deps.enqueue(child);
+    return child.id;
+}
+function settleFailedChild(store, exec, recordKey, error) {
+    const claimed = exec.steps[recordKey];
+    if (!claimed)
+        return;
+    exec.steps[recordKey] = {
+        ...claimed,
+        status: 'failed',
+        error: describeError(error),
+        completedAt: clock().now(),
+    };
+    try {
+        store.update(exec);
+    }
+    catch {
+        // 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/identity.d.ts

@@ -18,6 +18,8 @@
  * must present the key iteration 2 already used, or the provider bills twice.
  */
 export type Direction = 'forward' | 'compensate';
+/** Opaque 128-bit execution identity, deterministic under the simulated clock. */
+export declare function newExecutionId(): string;
 export declare function idempotencyKey(runId: string, stepName: string, occurrence: number, direction: Direction): string;
 /**
  * A loop iteration record is `<step>:<digits>` and nothing else.

package/dist/client/workflow/identity.js

@@ -17,6 +17,14 @@
  * 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.
  */
+import { clock } from './clock';
+/** Opaque 128-bit execution identity, deterministic under the simulated clock. */
+export function newExecutionId() {
+    const hex = [...clock().randomBytes(16)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+    return `wf_${hex}`;
+}
 export function idempotencyKey(runId, stepName, occurrence, direction) {
     return `${runId}:${stepName}#${occurrence}:${direction}`;
 }

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, 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';
+export type { StepContext, StepHandler, TypedStepHandler, CompensateHandler, TypedCompensateHandler, StepOptions, SchemaLike, Execution, ExecutionState, ExecutionListOptions, StepState, StepRecord, RollbackStatus, CompensationStatus, CompensationOutcome, BranchCondition, WorkflowNode, EngineOptions, RunHandle, ParallelDefinition, SubWorkflowInputMapper, SubWorkflowOptions, LoopCondition, ForEachItemsExtractor, MapTransformFn, LoopDefinition, ForEachDefinition, MapDefinition, RecoverResult, CleanupOptions, WorkflowEventType, WorkflowEvent, StepEvent, WorkflowLifecycleEvent, SignalEvent, WorkflowEventListener, } from './types';

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

@@ -1,14 +1,12 @@
 /**
- * Loop & Map execution logic for the Workflow Engine
- * Handles doUntil, doWhile, forEach, and map node types.
+ * Loop execution logic for the Workflow Engine.
  */
-import type { Execution, LoopDefinition, ForEachDefinition, MapDefinition } from './types';
+import type { Execution, LoopDefinition, ForEachDefinition } from './types';
 import type { WorkflowEmitter } from './emitter';
+export { executeMap } from './mapRunner';
 /** 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>;
 /** 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>;
-/** Execute a map node: transform step results into a new value */
-export declare function executeMap(def: MapDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;

package/dist/client/workflow/loops.js

@@ -1,9 +1,9 @@
 /**
- * Loop & Map execution logic for the Workflow Engine
- * Handles doUntil, doWhile, forEach, and map node types.
+ * Loop execution logic for the Workflow Engine.
  */
 import { executeStepWithRetry, buildContext } from './runner';
-import { clock } from './clock';
+import { forEachItemsDecisionKey, loopDecisionKey, resolveDecision } from './workflowDecisions';
+export { executeMap } from './mapRunner';
 /**
  * Run one iteration of a loop body step, unless it already ran.
  *
@@ -109,14 +109,20 @@ export async function executeDoUntil(def, exec, emitter, updateFn) {
         }
         iteration++;
         const ctx = buildContext(exec);
-        shouldStop = await def.condition(ctx, iteration);
+        shouldStop = await resolveDecision(exec, loopDecisionKey('doUntil', def.steps[0].name, iteration), () => def.condition(ctx, iteration), updateFn);
+        if (typeof shouldStop !== 'boolean') {
+            throw new Error('doUntil condition must return a boolean');
+        }
     }
 }
 /** Execute a doWhile loop: check condition first, then run steps. Repeat while condition is true. */
 export async function executeDoWhile(def, exec, emitter, updateFn) {
     for (let iteration = 0;; iteration++) {
         const ctx = buildContext(exec);
-        const shouldContinue = await def.condition(ctx, iteration);
+        const shouldContinue = await resolveDecision(exec, loopDecisionKey('doWhile', def.steps[0].name, iteration), () => def.condition(ctx, iteration), updateFn);
+        if (typeof shouldContinue !== 'boolean') {
+            throw new Error('doWhile condition must return a boolean');
+        }
         if (!shouldContinue)
             break;
         if (iteration >= def.maxIterations) {
@@ -130,7 +136,7 @@ export async function executeDoWhile(def, exec, emitter, updateFn) {
 /** Execute a forEach loop: iterate over items, executing the step for each */
 export async function executeForEach(def, exec, emitter, updateFn) {
     const ctx = buildContext(exec);
-    const items = def.items(ctx);
+    const items = await resolveDecision(exec, forEachItemsDecisionKey(def.step.name), () => structuredClone(def.items(ctx)), updateFn);
     // Anything with a `length` used to be accepted, and JavaScript is generous about
     // what has one. A number iterated ZERO times and the run reported `completed`, so a
     // batch that processed nothing was indistinguishable from a batch with nothing to
@@ -145,7 +151,7 @@ export async function executeForEach(def, exec, emitter, updateFn) {
         throw new Error(`forEach items (${items.length}) exceeds maxIterations (${def.maxIterations})`);
     }
     for (let i = 0; i < items.length; i++) {
-        const item = items[i];
+        const item = structuredClone(items[i]);
         const indexedName = `${def.step.name}:${i}`;
         const indexedStep = {
             ...def.step,
@@ -159,9 +165,15 @@ export async function executeForEach(def, exec, emitter, updateFn) {
             },
         };
         // Memoised the same way as doUntil/doWhile: an item already provisioned before a
-        // crash must not be provisioned again when the node is re-entered.
-        if (exec.steps[indexedName]?.status === 'completed')
+        // crash must not be provisioned again when the node is re-entered. Restore the
+        // declared bare name too: it is the public result of the final iteration, while
+        // the indexed record remains the durable execution/compensation identity.
+        const completed = exec.steps[indexedName];
+        if (completed?.status === 'completed') {
+            exec.steps[def.step.name] = { ...completed };
+            updateFn(exec);
             continue;
+        }
         const stepCtx = buildContext(exec);
         let thrown;
         let threw = false;
@@ -188,6 +200,10 @@ export async function executeForEach(def, exec, emitter, updateFn) {
             if (record) {
                 record.loopItem = item;
                 record.loopIndex = i;
+                // Keep the documented aggregate view in sync on success and failure. The
+                // indexed record is still the authoritative unit of work; compensator.ts
+                // excludes this mirror whenever an indexed sibling exists.
+                exec.steps[def.step.name] = { ...record };
                 try {
                     updateFn(exec);
                 }
@@ -201,17 +217,3 @@ export async function executeForEach(def, exec, emitter, updateFn) {
             throw thrown;
     }
 }
-/** Execute a map node: transform step results into a new value */
-export async function executeMap(def, exec, emitter, updateFn) {
-    const ctx = buildContext(exec);
-    emitter?.emitStep('step:started', exec.id, exec.workflowName, def.name);
-    const result = await def.transform(ctx);
-    exec.steps[def.name] = {
-        status: 'completed',
-        result,
-        startedAt: clock().now(),
-        completedAt: clock().now(),
-    };
-    updateFn(exec);
-    emitter?.emitStep('step:completed', exec.id, exec.workflowName, def.name, { result });
-}

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

@@ -0,0 +1,4 @@
+import type { WorkflowEmitter } from './emitter';
+import type { Execution, MapDefinition } from './types';
+/** Execute a map node with the same durable lifecycle signals as a regular step. */
+export declare function executeMap(def: MapDefinition, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;

package/dist/client/workflow/mapRunner.js

@@ -0,0 +1,45 @@
+import { clock } from './clock';
+import { describeError } from './identity';
+import { buildContext } from './runner';
+/** Execute a map node with the same durable lifecycle signals as a regular step. */
+export async function executeMap(def, exec, emitter, updateFn) {
+    if (exec.steps[def.name]?.status === 'completed')
+        return;
+    const startedAt = clock().now();
+    exec.steps[def.name] = { status: 'running', startedAt };
+    updateFn(exec);
+    emitter?.emitStep('step:started', exec.id, exec.workflowName, def.name);
+    let result;
+    try {
+        result = await def.transform(buildContext(exec));
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new Error(describeError(error));
+        exec.steps[def.name] = {
+            status: 'failed',
+            error: describeError(failure),
+            startedAt,
+            completedAt: clock().now(),
+        };
+        try {
+            updateFn(exec);
+        }
+        catch {
+            // Preserve the transform failure; generic workflow failure handling retries the write.
+        }
+        emitter?.emitStep('step:failed', exec.id, exec.workflowName, def.name, {
+            error: describeError(failure),
+        });
+        throw failure;
+    }
+    // A completed transform whose write fails must stay completed in memory. Reclassifying
+    // that infrastructure failure as a transform failure would discard a valid result.
+    exec.steps[def.name] = {
+        status: 'completed',
+        result,
+        startedAt,
+        completedAt: clock().now(),
+    };
+    updateFn(exec);
+    emitter?.emitStep('step:completed', exec.id, exec.workflowName, def.name, { result });
+}

package/dist/client/workflow/recovery.js

@@ -10,6 +10,7 @@ import { runCompensation } from './compensator';
 import { hasSignal } from './storeSignals';
 import { clock } from './clock';
 import { decideAdmission } from './admission';
+import { bindExecutionDefinition } from './definitionGuard';
 export async function recoverExecutions(deps) {
     const { store, workflows } = deps;
     const executions = store.listRecoverable();
@@ -29,6 +30,7 @@ export async function recoverExecutions(deps) {
         const exec = store.get(snapshot.id);
         if (!exec)
             continue;
+        bindExecutionDefinition(exec, wf, (value) => store.update(value));
         if (exec.state === 'running') {
             const admission = decideAdmission(exec, exec.currentNodeIndex, deps.nodesInFlight);
             // Only `already-in-flight` is reachable here: the state is `running` by the
@@ -42,7 +44,11 @@ export async function recoverExecutions(deps) {
             await recoverWaiting(exec, wf, deps);
             result.waiting++;
         }
-        else if (exec.state === 'compensating') {
+        else if (exec.state === 'compensating' ||
+            (exec.state === 'failed' && exec.rollbackStatus === undefined)) {
+            // `runNode` persists the failure before it starts the unwind. A hard kill in
+            // between leaves a terminal-looking row with rollback still owed. Such rows are
+            // recoverable until runCompensation writes an explicit rollbackStatus.
             // A lost claim means another driver owns this unwind, so nothing happened here
             // and counting it as a recovery would overstate what recover() did.
             const outcome = await runCompensation(exec, wf, store, deps.emitter, deps.workflows);
@@ -71,8 +77,9 @@ async function recoverWaiting(exec, wf, deps) {
         await enqueueExecution(exec, deps.queue);
         return;
     }
-    // Check if signal already arrived while we were down. Key presence, not value:
-    // a payload-less signal records the key with an `undefined` value (see hasSignal).
+    // The signal may have been persisted before the crash, or accepted after this
+    // engine was recreated but before recover() reached the row. Key presence, not
+    // value: a payload-less signal records the key with an `undefined` value.
     if (hasSignal(exec.signals, node.event)) {
         exec.state = 'running';
         deps.store.update(exec);

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

@@ -4,8 +4,8 @@
 import type { StepDefinition, StepContext, Execution } from './types';
 import type { Workflow } from './workflow';
 import type { WorkflowEmitter } from './emitter';
-/** Run a promise with a timeout */
-export declare function runWithTimeout<T>(promise: Promise<T> | T, timeoutMs: number): Promise<T>;
+export { runWithTimeout } from './runnerTiming';
+export { executeSubWorkflow } from './subWorkflowRunner';
 /** Engine hooks a step needs; they always travel together. */
 export interface StepHooks {
     emitter: WorkflowEmitter | null;
@@ -15,25 +15,6 @@ export interface StepHooks {
 export declare function executeStepWithRetry(def: StepDefinition, ctx: StepContext, exec: Execution, hooks: StepHooks, occurrence?: number): Promise<void>;
 /** Execute multiple steps in parallel via Promise.allSettled */
 export declare function executeParallelSteps(steps: StepDefinition[], ctx: StepContext, exec: Execution, emitter: WorkflowEmitter | null, updateFn: (exec: Execution) => void): Promise<void>;
-/** Execute a sub-workflow by starting it and polling for completion */
-export declare function executeSubWorkflow(workflowName: string, input: unknown, startFn: (name: string, input: unknown) => Promise<{
-    id: string;
-}>, getFn: (id: string) => Execution | null, pollIntervalMs?: number, 
-/**
- * A child this node already started, from an earlier entry into the same node.
- *
- * Without it the node started a BRAND NEW child every time it was re-entered, and
- * re-entry is routine: a restart followed by `recover()` re-enqueues the parent's
- * current node. Measured across one restart, the child ran twice and both rows were
- * left `running` forever, since a child is excluded from recovery while its parent
- * exists and `cleanup`/`archive` only reap terminal states. Duplicated work, not just
- * a leaked row: a child that provisions a resource provisioned it twice
- * (`test/repro-workflow-orphan-child.test.ts`).
- */
-existingChildId?: string): Promise<{
-    results: Record<string, unknown>;
-    executionId: string;
-}>;
 /** Find a step definition by name across all node types */
 export declare function findStepDef(wf: Workflow, name: string): StepDefinition | null;
 /** Build a StepContext from the current execution state */

package/dist/client/workflow/runner.js

@@ -3,49 +3,36 @@
  */
 import { idempotencyKey, isIterationOf, describeError } from './identity';
 import { clock } from './clock';
-/** Exponential backoff with jitter */
-function backoffDelay(attempt, baseMs = 500, maxMs = 30_000) {
-    const delay = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
-    const jitter = delay * 0.5 * clock().random();
-    return delay + jitter;
-}
-/** Run a promise with a timeout */
-export function runWithTimeout(promise, timeoutMs) {
-    if (!(promise instanceof Promise))
-        return Promise.resolve(promise);
-    if (timeoutMs <= 0)
-        return promise;
-    return new Promise((resolve, reject) => {
-        const timer = clock().setTimeout(() => {
-            reject(new Error(`Step timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
-        promise.then((v) => {
-            clock().clearTimeout(timer);
-            resolve(v);
-        }, (e) => {
-            clock().clearTimeout(timer);
-            // `describeError`, not `String`: this wrapper runs BEFORE the compensator's own
-            // catch, so converting here with `String` is what destroyed a structured throw
-            // into `[object Object]` no matter how carefully the catch handled it.
-            reject(e instanceof Error ? e : new Error(describeError(e)));
-        });
-    });
-}
+import { retryBackoffDelay, runWithTimeout } from './runnerTiming';
+export { runWithTimeout } from './runnerTiming';
+export { executeSubWorkflow } from './subWorkflowRunner';
 /** Execute a step with retry logic and exponential backoff */
 export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0) {
     const { emitter, updateFn } = hooks;
     const maxAttempts = def.retry;
+    const current = exec.steps[def.name];
+    const previous = current && (current.occurrence ?? 0) === occurrence ? current : undefined;
+    const attemptsUsed = previous?.attempts ?? 0;
+    if (previous?.status === 'completed')
+        return;
+    if (previous?.status === 'failed' && attemptsUsed >= maxAttempts) {
+        throw new Error(previous.error ?? `Step "${def.name}" exhausted its retry budget`);
+    }
     let lastError;
     // Derived once, outside the retry loop, and persisted with the START record: a
     // rollback for a step whose outcome is unknown needs this key to reconcile, and by
     // then the body may never have reached the point of writing anything.
-    const forwardKey = idempotencyKey(exec.id, def.name, occurrence, 'forward');
+    const forwardKey = previous?.idempotencyKey ?? idempotencyKey(exec.id, def.name, occurrence, 'forward');
     const stepCtx = { ...ctx, idempotencyKey: forwardKey };
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const prev = exec.steps[def.name];
+    let validatedInput = stepCtx.input;
+    let inputValidationError;
+    let inputParsed = false;
+    let finalAttempt = attemptsUsed;
+    for (let attempt = attemptsUsed + 1; attempt <= maxAttempts; attempt++) {
+        finalAttempt = attempt;
         exec.steps[def.name] = {
             status: 'running',
-            startedAt: prev?.startedAt ?? clock().now(),
+            startedAt: previous?.startedAt ?? clock().now(),
             attempts: attempt,
             idempotencyKey: forwardKey,
             occurrence,
@@ -56,29 +43,28 @@ export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0
             maxAttempts,
         });
         try {
-            let input = stepCtx.input;
-            if (def.inputSchema) {
+            if (!inputParsed) {
+                inputParsed = true;
                 try {
-                    // The RETURN VALUE matters. `parse()` is the coercing entry point of every
-                    // schema library the docs point at: `.default()` fills gaps, `.transform()`
-                    // rewrites, `z.coerce.date()` builds a Date from a string. Calling it purely
-                    // for its throw validated the shape and silently dropped every coercion, so
-                    // a step declaring `.default('EUR')` ran with no currency at all
-                    // (`test/repro-workflow-gate-and-schema.test.ts`). A validator that returns
-                    // nothing is still supported: `undefined` means "I only assert", so the
-                    // original value is kept rather than blanked.
-                    const parsed = def.inputSchema.parse(stepCtx.input);
+                    // Input is immutable for one step occurrence. Parse once so coercion is
+                    // stable and handler retries do not repeat user schema side effects.
+                    const parsed = def.inputSchema?.parse(stepCtx.input);
                     if (parsed !== undefined)
-                        input = parsed;
+                        validatedInput = parsed;
                 }
-                catch (e) {
-                    throw new Error(`Input validation failed for "${def.name}": ${describeError(e)}`, {
-                        cause: e,
-                    });
+                catch (error) {
+                    inputValidationError = new Error(`Input validation failed for "${def.name}": ${describeError(error)}`, { cause: error });
                 }
             }
-            const handlerCtx = input === stepCtx.input ? stepCtx : { ...stepCtx, input };
-            let result = await runWithTimeout(def.handler(handlerCtx), def.timeout);
+            if (inputValidationError)
+                throw inputValidationError;
+            const controller = new AbortController();
+            const handlerCtx = {
+                ...stepCtx,
+                input: validatedInput,
+                signal: controller.signal,
+            };
+            let result = await runWithTimeout(def.handler(handlerCtx), def.timeout, controller);
             if (def.outputSchema) {
                 try {
                     const parsed = def.outputSchema.parse(result);
@@ -117,7 +103,7 @@ export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0
                     attempt,
                     maxAttempts,
                 });
-                await new Promise((r) => clock().setTimeout(() => r(), backoffDelay(attempt)));
+                await new Promise((r) => clock().setTimeout(() => r(), retryBackoffDelay(attempt)));
                 continue;
             }
         }
@@ -129,7 +115,7 @@ export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0
         error: String(finalError),
         startedAt: exec.steps[def.name].startedAt,
         completedAt: clock().now(),
-        attempts: maxAttempts,
+        attempts: finalAttempt,
         idempotencyKey: forwardKey,
         occurrence,
     };
@@ -154,7 +140,7 @@ export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0
     }
     emitter?.emitStep('step:failed', exec.id, exec.workflowName, def.name, {
         error: String(finalError),
-        attempt: maxAttempts,
+        attempt: finalAttempt,
         maxAttempts,
     });
     throw finalError;
@@ -168,57 +154,6 @@ export async function executeParallelSteps(steps, ctx, exec, emitter, updateFn)
         throw new AggregateError(errors, errors[0].message);
     }
 }
-/** Execute a sub-workflow by starting it and polling for completion */
-// 6 params, one over the limit. `existingChildId` is what makes re-entering this node resume
-// the child a restart already started, instead of abandoning it and provisioning a second
-// one, so it belongs in the signature where a caller cannot forget it rather than in an
-// options bag where omitting it looks deliberate.
-// biome-ignore lint/complexity/useMaxParams: see above
-export async function executeSubWorkflow(workflowName, input, startFn, getFn, pollIntervalMs = 100, 
-/**
- * A child this node already started, from an earlier entry into the same node.
- *
- * Without it the node started a BRAND NEW child every time it was re-entered, and
- * re-entry is routine: a restart followed by `recover()` re-enqueues the parent's
- * current node. Measured across one restart, the child ran twice and both rows were
- * left `running` forever, since a child is excluded from recovery while its parent
- * exists and `cleanup`/`archive` only reap terminal states. Duplicated work, not just
- * a leaked row: a child that provisions a resource provisioned it twice
- * (`test/repro-workflow-orphan-child.test.ts`).
- */
-existingChildId) {
-    // Resume the existing child when it is still there. A row that has been cleaned away
-    // cannot be resumed, so that case starts fresh.
-    const existing = existingChildId ? getFn(existingChildId) : null;
-    const handle = existing ? { id: existing.id } : await startFn(workflowName, input);
-    const maxWait = 300_000;
-    const start = clock().now();
-    while (clock().now() - start < maxWait) {
-        const subExec = getFn(handle.id);
-        if (subExec?.state === 'completed') {
-            const results = {};
-            for (const [name, record] of Object.entries(subExec.steps)) {
-                if (record.status === 'completed')
-                    results[name] = record.result;
-            }
-            return { results, executionId: handle.id };
-        }
-        if (subExec?.state === 'failed') {
-            throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) failed`);
-        }
-        // A child that parks mid-rollback is terminal FOR THIS POLL: nothing it does next
-        // happens without an operator. Waiting for it was measured at the full 300 s, after
-        // which the parent reported a timeout, which is the wrong diagnostic for precisely
-        // the scenario this module exists to handle, and it held a worker slot for five
-        // minutes to say it. The parent parks too, with the real reason.
-        if (subExec?.state === 'compensation-stuck') {
-            throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) is parked mid-rollback ` +
-                `(compensation-stuck); resolve it with resumeCompensation or abandonCompensation`);
-        }
-        await new Promise((r) => clock().setTimeout(() => r(), pollIntervalMs));
-    }
-    throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) timed out`);
-}
 /** Find a step definition by name across all node types */
 export function findStepDef(wf, name) {
     for (const node of wf.nodes) {

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

@@ -0,0 +1,14 @@
+/**
+ * Timing primitives used while running a workflow step.
+ *
+ * Kept separate from runner.ts so the runner stays focused on state transitions.
+ */
+/** Exponential retry backoff with jitter. */
+export declare function retryBackoffDelay(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Bound a value or PromiseLike without passing an overflowing delay to the runtime.
+ *
+ * Long deadlines are re-armed in platform-sized chunks. Promise.resolve is
+ * intentional: it assimilates userland thenables as well as native promises.
+ */
+export declare function runWithTimeout<T>(value: PromiseLike<T> | T, timeoutMs: number, controller?: AbortController): Promise<T>;