@dudousxd/nestjs-durable-core 0.42.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
@@ -1636,6 +1664,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
@@ -1946,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.
@@ -2002,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
@@ -2170,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
@@ -1636,6 +1664,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
@@ -1946,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.
@@ -2002,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
@@ -2170,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;
+    }>;
 }
 
 /**