@dudousxd/nestjs-durable-core 0.43.0 → 0.44.0

package/dist/index.d.cts

@@ -260,6 +260,16 @@ interface WorkflowRun {
      * durable state required for correctness — a transport without priority support ignores it.
      */
     priority?: number | undefined;
+    /**
+     * REMOTE workflow turn awaiting a decision: the `taskId` of the turn the engine dispatched to a
+     * workflow worker and then SUSPENDED on. Set by the dispatch-and-suspend path; matched by
+     * {@link WorkflowEngine.completeRemoteDecision} so ONLY the decision for the currently-awaited turn
+     * is applied (a stale/duplicate/foreign decision is dropped), then cleared the moment it is applied.
+     * This is what makes a workflow-turn decision multi-instance safe: any engine instance that receives
+     * the decision looks the run up by `decision.runId` and applies it durably, instead of resolving an
+     * in-memory promise that only the dispatching instance held. Absent on non-remote / not-awaiting runs.
+     */
+    awaitingDecisionTaskId?: string | undefined;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -784,7 +794,25 @@ interface WorkflowStepEvent {
  * concerns, identical for in-process and remote workflows.
  */
 interface WorkflowExecutor {
-    advance(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * INLINE replay: advance the turn and RETURN its decision (the in-process executor runs the
+     * registered TS function synchronously). The engine awaits this under the run's lease. Provide this
+     * OR {@link dispatch} — exactly one. An executor with only `advance` is single-instance by nature
+     * (the decision is produced in-process, not delivered over a broker).
+     */
+    advance?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): dispatch the turn to a worker and
+     * return the dispatched `taskId` WITHOUT awaiting the decision. The engine then suspends the run,
+     * recording the `taskId` on it; the worker's {@link WorkflowDecision} comes back over the
+     * transport's {@link Transport.onDecision} and is applied DURABLY by whatever engine instance
+     * receives it ({@link WorkflowEngine.completeRemoteDecision} looks the run up by `decision.runId`).
+     * No in-memory await, so the decision is never lost to a point-to-point broker handing it to a
+     * non-dispatching instance. Provide this OR {@link advance} — exactly one.
+     */
+    dispatch?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
+        taskId: string;
+    }>;
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
@@ -1969,6 +1997,14 @@ declare class WorkflowEngine {
      */
     private settleRun;
     private runRemoteExecution;
+    /**
+     * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
+     * settle (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by
+     * the INLINE-advance path ({@link runRemoteExecution}, under the held lease) and the durable
+     * DISPATCH path ({@link completeRemoteDecision}, which holds the lease itself). Idempotent transitions
+     * — the caller has already ensured this is the decision for the currently-awaited turn.
+     */
+    private applyDecision;
     /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
     private remoteHistory;
     /** Apply a turn's commands: persist recorded local steps, dispatch remote calls, schedule timers.
@@ -2025,6 +2061,21 @@ declare class WorkflowEngine {
      * A no-op if the checkpoint isn't `pending` (a duplicate or late delivery).
      */
     private completeRemoteResult;
+    /**
+     * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
+     * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
+     * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
+     * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
+     * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
+     * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
+     */
+    private completeRemoteDecision;
+    /**
+     * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
+     * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
+     * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
+     */
+    private rearmDecisionDeadline;
     /**
      * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
      * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
@@ -2193,25 +2244,36 @@ declare function remoteStep<TInput, TOutput>(config: RemoteStepConfig<TInput, TO
 
 /**
  * A {@link WorkflowExecutor} backed by a {@link Transport}: it advances a remote workflow by
- * dispatching a {@link WorkflowTask} over the broker and awaiting the matching {@link WorkflowDecision}
- * (correlated by `taskId`). Pass one to `engine.registerRemote(name, version, { group, executor })` so
- * a workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ * DISPATCHING a {@link WorkflowTask} over the broker and returning the dispatched `taskId` WITHOUT
+ * awaiting the decision. Pass one to `engine.registerRemote(name, version, { group, executor })` so a
+ * workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ *
+ * Multi-instance safe by construction: the executor holds NO in-memory state correlating a dispatched
+ * turn to its decision. The engine suspends the run recording the dispatched `taskId`, and the
+ * worker's {@link import('./interfaces').WorkflowDecision} is delivered over the transport's
+ * `onDecision` and applied DURABLY (by run id) on whatever engine instance consumes it — even if that
+ * is not the instance that dispatched the turn. A point-to-point broker can therefore hand the
+ * decision to any instance without it being dropped (the bug this design fixes).
  *
- * Recovery-safe: if the engine crashes awaiting a decision, the re-drive dispatches a fresh task with
- * the same history — the worker's replay is deterministic, so it returns the same decision; a late
- * decision for the old `taskId` simply finds no waiter and is dropped.
+ * Recovery-safe: if the engine crashes (or a decision is genuinely lost because the worker died), the
+ * suspended turn's heartbeat-rearmed window (`remoteAdvanceSilenceMs`) lapses and the timer poller
+ * re-dispatches a fresh task with the same history — the worker's replay is deterministic, so it
+ * returns the same decision; a late decision for the old `taskId` no longer matches the run's
+ * currently-awaited turn and is dropped.
  */
 declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     private readonly transport;
     private readonly group;
-    private readonly opts;
-    private readonly pending;
-    private subscribed;
-    constructor(transport: Transport, group: string, opts?: {
+    constructor(transport: Transport, group: string, _opts?: {
         timeoutMs?: number;
     });
-    private ensureSubscribed;
-    advance(run: WorkflowRun, history: HistoryEvent[]): Promise<WorkflowDecision>;
+    /**
+     * Dispatch one workflow turn and return its `taskId`. Does NOT await the decision — the engine
+     * suspends the run on the returned `taskId` and applies the decision durably via `onDecision`.
+     */
+    dispatch(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
+        taskId: string;
+    }>;
 }
 
 /**

package/dist/index.d.ts

@@ -260,6 +260,16 @@ interface WorkflowRun {
      * durable state required for correctness — a transport without priority support ignores it.
      */
     priority?: number | undefined;
+    /**
+     * REMOTE workflow turn awaiting a decision: the `taskId` of the turn the engine dispatched to a
+     * workflow worker and then SUSPENDED on. Set by the dispatch-and-suspend path; matched by
+     * {@link WorkflowEngine.completeRemoteDecision} so ONLY the decision for the currently-awaited turn
+     * is applied (a stale/duplicate/foreign decision is dropped), then cleared the moment it is applied.
+     * This is what makes a workflow-turn decision multi-instance safe: any engine instance that receives
+     * the decision looks the run up by `decision.runId` and applies it durably, instead of resolving an
+     * in-memory promise that only the dispatching instance held. Absent on non-remote / not-awaiting runs.
+     */
+    awaitingDecisionTaskId?: string | undefined;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -784,7 +794,25 @@ interface WorkflowStepEvent {
  * concerns, identical for in-process and remote workflows.
  */
 interface WorkflowExecutor {
-    advance(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * INLINE replay: advance the turn and RETURN its decision (the in-process executor runs the
+     * registered TS function synchronously). The engine awaits this under the run's lease. Provide this
+     * OR {@link dispatch} — exactly one. An executor with only `advance` is single-instance by nature
+     * (the decision is produced in-process, not delivered over a broker).
+     */
+    advance?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): dispatch the turn to a worker and
+     * return the dispatched `taskId` WITHOUT awaiting the decision. The engine then suspends the run,
+     * recording the `taskId` on it; the worker's {@link WorkflowDecision} comes back over the
+     * transport's {@link Transport.onDecision} and is applied DURABLY by whatever engine instance
+     * receives it ({@link WorkflowEngine.completeRemoteDecision} looks the run up by `decision.runId`).
+     * No in-memory await, so the decision is never lost to a point-to-point broker handing it to a
+     * non-dispatching instance. Provide this OR {@link advance} — exactly one.
+     */
+    dispatch?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
+        taskId: string;
+    }>;
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
@@ -1969,6 +1997,14 @@ declare class WorkflowEngine {
      */
     private settleRun;
     private runRemoteExecution;
+    /**
+     * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
+     * settle (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by
+     * the INLINE-advance path ({@link runRemoteExecution}, under the held lease) and the durable
+     * DISPATCH path ({@link completeRemoteDecision}, which holds the lease itself). Idempotent transitions
+     * — the caller has already ensured this is the decision for the currently-awaited turn.
+     */
+    private applyDecision;
     /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
     private remoteHistory;
     /** Apply a turn's commands: persist recorded local steps, dispatch remote calls, schedule timers.
@@ -2025,6 +2061,21 @@ declare class WorkflowEngine {
      * A no-op if the checkpoint isn't `pending` (a duplicate or late delivery).
      */
     private completeRemoteResult;
+    /**
+     * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
+     * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
+     * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
+     * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
+     * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
+     * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
+     */
+    private completeRemoteDecision;
+    /**
+     * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
+     * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
+     * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
+     */
+    private rearmDecisionDeadline;
     /**
      * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
      * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
@@ -2193,25 +2244,36 @@ declare function remoteStep<TInput, TOutput>(config: RemoteStepConfig<TInput, TO
 
 /**
  * A {@link WorkflowExecutor} backed by a {@link Transport}: it advances a remote workflow by
- * dispatching a {@link WorkflowTask} over the broker and awaiting the matching {@link WorkflowDecision}
- * (correlated by `taskId`). Pass one to `engine.registerRemote(name, version, { group, executor })` so
- * a workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ * DISPATCHING a {@link WorkflowTask} over the broker and returning the dispatched `taskId` WITHOUT
+ * awaiting the decision. Pass one to `engine.registerRemote(name, version, { group, executor })` so a
+ * workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ *
+ * Multi-instance safe by construction: the executor holds NO in-memory state correlating a dispatched
+ * turn to its decision. The engine suspends the run recording the dispatched `taskId`, and the
+ * worker's {@link import('./interfaces').WorkflowDecision} is delivered over the transport's
+ * `onDecision` and applied DURABLY (by run id) on whatever engine instance consumes it — even if that
+ * is not the instance that dispatched the turn. A point-to-point broker can therefore hand the
+ * decision to any instance without it being dropped (the bug this design fixes).
  *
- * Recovery-safe: if the engine crashes awaiting a decision, the re-drive dispatches a fresh task with
- * the same history — the worker's replay is deterministic, so it returns the same decision; a late
- * decision for the old `taskId` simply finds no waiter and is dropped.
+ * Recovery-safe: if the engine crashes (or a decision is genuinely lost because the worker died), the
+ * suspended turn's heartbeat-rearmed window (`remoteAdvanceSilenceMs`) lapses and the timer poller
+ * re-dispatches a fresh task with the same history — the worker's replay is deterministic, so it
+ * returns the same decision; a late decision for the old `taskId` no longer matches the run's
+ * currently-awaited turn and is dropped.
  */
 declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     private readonly transport;
     private readonly group;
-    private readonly opts;
-    private readonly pending;
-    private subscribed;
-    constructor(transport: Transport, group: string, opts?: {
+    constructor(transport: Transport, group: string, _opts?: {
         timeoutMs?: number;
     });
-    private ensureSubscribed;
-    advance(run: WorkflowRun, history: HistoryEvent[]): Promise<WorkflowDecision>;
+    /**
+     * Dispatch one workflow turn and return its `taskId`. Does NOT await the decision — the engine
+     * suspends the run on the returned `taskId` and applies the decision durably via `onDecision`.
+     */
+    dispatch(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
+        taskId: string;
+    }>;
 }
 
 /**

package/dist/index.js

@@ -708,33 +708,18 @@ var RemoteWorkflowExecutor = class {
   }
   transport;
   group;
-  opts;
-  pending = /* @__PURE__ */ new Map();
-  subscribed = false;
-  constructor(transport, group, opts = {}) {
+  constructor(transport, group, _opts = {}) {
     this.transport = transport;
     this.group = group;
-    this.opts = opts;
-  }
-  ensureSubscribed() {
-    if (this.subscribed) return;
-    if (!this.transport.onDecision) {
-      throw new Error("transport does not support workflow decisions (onDecision)");
-    }
-    this.subscribed = true;
-    this.transport.onDecision(async (decision) => {
-      const resolve = this.pending.get(decision.taskId);
-      if (resolve) {
-        this.pending.delete(decision.taskId);
-        resolve(decision);
-      }
-    });
   }
-  async advance(run, history) {
+  /**
+  * Dispatch one workflow turn and return its `taskId`. Does NOT await the decision — the engine
+  * suspends the run on the returned `taskId` and applies the decision durably via `onDecision`.
+  */
+  async dispatch(run, history, pendingSignals) {
     if (!this.transport.dispatchWorkflowTask) {
       throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
     }
-    this.ensureSubscribed();
     taskCounter += 1;
     const taskId = `${run.id}:wf:${taskCounter}`;
     const task = {
@@ -744,23 +729,17 @@ var RemoteWorkflowExecutor = class {
       workflowVersion: run.workflowVersion,
       input: run.input,
       history,
+      ...pendingSignals ? {
+        pendingSignals
+      } : {},
       group: this.group,
       priority: run.priority,
       attempt: 1
     };
-    const decision = new Promise((resolve, reject) => {
-      this.pending.set(taskId, resolve);
-      const { timeoutMs } = this.opts;
-      if (timeoutMs) {
-        const timer = setTimeout(() => {
-          this.pending.delete(taskId);
-          reject(new RemoteWorkflowTimeout(taskId, timeoutMs));
-        }, timeoutMs);
-        timer.unref?.();
-      }
-    });
     await this.transport.dispatchWorkflowTask(task);
-    return decision;
+    return {
+      taskId
+    };
   }
 };
 
@@ -881,13 +860,16 @@ var TransportPool = class {
   /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
   *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
   *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
-  bind(onResult, onHeartbeat, onStepEvent) {
+  bind(onResult, onHeartbeat, onStepEvent, onDecision) {
     for (const { transport } of this.transports) {
       transport.onResult(onResult);
       transport.onHeartbeat(onHeartbeat);
       if (onStepEvent && transport.onStepEvent) {
         transport.onStepEvent(onStepEvent);
       }
+      if (onDecision && transport.onDecision) {
+        transport.onDecision(onDecision);
+      }
     }
   }
   /**
@@ -1645,14 +1627,27 @@ var WorkflowEngine = class {
       },
       // A heartbeat resets the liveness window for whatever it targets: an in-flight long STEP (keyed
       // by stepId, see callRemote) or — when stepId is absent — the in-flight workflow TURN (keyed by
-      // runId, see runRemoteExecution's heartbeat-rearmed advance).
+      // runId). For an INLINE-advance turn the reset is an in-memory callback; for a DISPATCH-suspend
+      // turn there is no in-memory waiter, so a run-scoped beat rearms the suspended turn's durable
+      // re-drive deadline (`wakeAt`) instead, keeping a live worker's turn from being re-dispatched.
       async (beat) => {
-        this.heartbeatResets.get(beat.stepId ?? beat.runId)?.();
+        const reset = this.heartbeatResets.get(beat.stepId ?? beat.runId);
+        if (reset) {
+          reset();
+          return;
+        }
+        if (beat.stepId === void 0) await this.rearmDecisionDeadline(beat.runId);
       },
       // A remote workflow worker streams each local step's lifecycle (running → completed/failed) so
       // it's checkpointed live, not all-at-once when the long turn ends.
       async (event) => {
         await this.persistStepEvent(event);
+      },
+      // A workflow-turn DECISION delivered over the broker — applied durably (by run id) on whatever
+      // instance consumes it, NOT correlated to an in-memory promise on the dispatcher. This is the
+      // multi-instance fix: a point-to-point broker may hand the decision to a non-dispatching instance.
+      async (decision) => {
+        await this.completeRemoteDecision(decision);
       }
     );
     this.controlPlane?.onControl((msg) => {
@@ -2281,7 +2276,7 @@ var WorkflowEngine = class {
   * `start` when a call site needs the outcome — `await start(...); const r = await waitForRun(id)`.
   */
   waitForRun(runId, opts) {
-    const isSettled = /* @__PURE__ */ __name((s) => s !== "pending" && s !== "running" && s !== "cancelling", "isSettled");
+    const isSettled = /* @__PURE__ */ __name((run) => run.status !== "pending" && run.status !== "running" && run.status !== "cancelling" && !(run.status === "suspended" && run.awaitingDecisionTaskId !== void 0), "isSettled");
     const toResult = /* @__PURE__ */ __name((run) => ({
       runId,
       status: run.status,
@@ -2307,7 +2302,7 @@ var WorkflowEngine = class {
       }, "finish");
       const check = /* @__PURE__ */ __name(() => {
         void this.store.getRun(runId).then((run) => {
-          if (run && isSettled(run.status)) finish(run);
+          if (run && isSettled(run)) finish(run);
         });
       }, "check");
       off = this.subscribe((ev) => {
@@ -2914,10 +2909,10 @@ var WorkflowEngine = class {
       });
     }
     if (registered.singleton && !await this.singletons.admit(run, registered.singleton)) {
-      const wakeAt2 = this.singletons.retryWakeAt();
+      const wakeAt = this.singletons.retryWakeAt();
       await this.store.updateRun(run.id, {
         status: "suspended",
-        wakeAt: wakeAt2,
+        wakeAt,
         updatedAt: /* @__PURE__ */ new Date()
       });
       this.emit({
@@ -2932,10 +2927,45 @@ var WorkflowEngine = class {
       };
     }
     const history = await this.remoteHistory(run.id);
+    if (remote.executor.dispatch) {
+      const { taskId } = await remote.executor.dispatch(run, history);
+      const silenceMs = this.remoteAdvanceSilenceMs;
+      const wakeAt = silenceMs != null ? this.clock() + silenceMs : void 0;
+      const fresh = await this.store.getRun(run.id);
+      if (fresh && (fresh.status === "cancelled" || fresh.status === "completed" || fresh.status === "dead")) {
+        await this.store.releaseRunLock(run.id);
+        return {
+          runId: run.id,
+          status: fresh.status,
+          output: fresh.output,
+          error: fresh.error
+        };
+      }
+      await this.store.updateRun(run.id, {
+        status: "suspended",
+        awaitingDecisionTaskId: taskId,
+        wakeAt,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.suspended",
+        runId: run.id,
+        workflow: run.workflow
+      });
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: "suspended"
+      };
+    }
+    const advanceExecutor = remote.executor.advance;
+    if (!advanceExecutor) {
+      throw new Error(`workflow ${run.workflow}@${run.workflowVersion}: executor implements neither advance nor dispatch`);
+    }
     let decision;
     try {
       const silenceMs = this.remoteAdvanceSilenceMs;
-      const advance = remote.executor.advance(run, history);
+      const advance = advanceExecutor.call(remote.executor, run, history);
       decision = silenceMs != null ? await this.awaitWithLivenessDeadline(run.id, advance, silenceMs, () => new RemoteWorkflowTimeout(run.id, silenceMs)) : await advance;
     } catch (err) {
       if (err instanceof RemoteWorkflowTimeout) {
@@ -2966,6 +2996,16 @@ var WorkflowEngine = class {
         error
       };
     }
+    return this.applyDecision(run, decision);
+  }
+  /**
+  * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
+  * settle (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by
+  * the INLINE-advance path ({@link runRemoteExecution}, under the held lease) and the durable
+  * DISPATCH path ({@link completeRemoteDecision}, which holds the lease itself). Idempotent transitions
+  * — the caller has already ensured this is the decision for the currently-awaited turn.
+  */
+  async applyDecision(run, decision) {
     if (decision.status === "completed") {
       await this.applyCommands(run, decision.commands);
       return this.settleRun(run, {
@@ -3563,6 +3603,60 @@ var WorkflowEngine = class {
     });
   }
   /**
+  * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
+  * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
+  * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
+  * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
+  * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
+  * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
+  */
+  async completeRemoteDecision(decision) {
+    const run = await this.store.getRun(decision.runId);
+    if (!run || run.awaitingDecisionTaskId !== decision.taskId) return;
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead") return;
+    if (run.namespace !== void 0 && run.namespace !== this.namespace) return;
+    const nowMs = this.clock();
+    if (!await this.store.tryLockRun(decision.runId, this.instanceId, nowMs + this.leaseMs, nowMs)) {
+      return;
+    }
+    const renew = setInterval(() => {
+      void this.store.renewRunLock(decision.runId, this.instanceId, this.clock() + this.leaseMs).catch(() => void 0);
+    }, Math.max(50, Math.floor(this.leaseMs / 2)));
+    renew.unref?.();
+    try {
+      const fresh = await this.store.getRun(decision.runId);
+      if (!fresh || fresh.awaitingDecisionTaskId !== decision.taskId) return;
+      if (fresh.status === "cancelled" || fresh.status === "completed" || fresh.status === "dead") {
+        return;
+      }
+      await this.store.updateRun(decision.runId, {
+        awaitingDecisionTaskId: void 0,
+        wakeAt: void 0,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      fresh.awaitingDecisionTaskId = void 0;
+      await this.applyDecision(fresh, decision);
+    } finally {
+      clearInterval(renew);
+      await this.store.releaseRunLock(decision.runId);
+    }
+  }
+  /**
+  * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
+  * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
+  * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
+  */
+  async rearmDecisionDeadline(runId) {
+    const silenceMs = this.remoteAdvanceSilenceMs;
+    if (silenceMs == null) return;
+    const run = await this.store.getRun(runId);
+    if (!run || run.status !== "suspended" || run.awaitingDecisionTaskId === void 0) return;
+    await this.store.updateRun(runId, {
+      wakeAt: this.clock() + silenceMs,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /**
   * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
   * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
   * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.