@dudousxd/nestjs-durable-core 0.44.0 → 0.45.0

package/dist/index.d.cts

@@ -802,17 +802,17 @@ interface WorkflowExecutor {
      */
     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;
-    }>;
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): enqueue the turn to a worker under the
+     * ENGINE-SUPPLIED `taskId`, WITHOUT awaiting the decision. The engine generates `taskId`, records it
+     * on the run as the awaited marker, AND releases the run's lease — all BEFORE calling this — so the
+     * worker's {@link WorkflowDecision} (delivered over {@link Transport.onDecision} and applied DURABLY
+     * by {@link WorkflowEngine.completeRemoteDecision}, which looks the run up by `decision.runId`) can
+     * never arrive ahead of its marker or contend with a still-held lease and be dropped. This method
+     * therefore ONLY enqueues — it owns no taskId generation and returns nothing. 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[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
@@ -840,6 +840,13 @@ interface Transport {
     onResult(handler: (result: StepResult) => Promise<void>): void;
     /** worker → engine: liveness signal for an in-flight long step. */
     onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /**
+     * Partition this transport's queues/keys by `namespace` (matching the engine's store namespace), so
+     * multiple logical deployments can share one broker. Idempotent. An explicit namespace passed to the
+     * transport's constructor TAKES PRECEDENCE over this. No-op when `namespace === "default"`. Optional —
+     * transports that don't partition simply omit it.
+     */
+    useNamespace?(namespace: string): void;
     /** Release the transport's resources (broker workers, queues, connections) for a clean shutdown.
      *  Optional — an in-process transport has nothing to close. Called on `onApplicationShutdown`
      *  after the engine drains, so a deploy hands off instead of leaving the broker to time out. */
@@ -2244,15 +2251,16 @@ 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 returning the dispatched `taskId` WITHOUT
+ * DISPATCHING a {@link WorkflowTask} over the broker under the ENGINE-SUPPLIED `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
+ * turn to its decision. The engine records the `taskId` on the run as the awaited marker AND releases
+ * the run's lease BEFORE calling `dispatch`, so the worker's {@link import('./interfaces').WorkflowDecision},
+ * delivered over the transport's `onDecision` and applied DURABLY (by run id) on whatever engine
+ * instance consumes it — even one that did not dispatch the turn — can never arrive ahead of its marker
+ * or contend with a still-held lease and be dropped. 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 (or a decision is genuinely lost because the worker died), the
@@ -2268,12 +2276,10 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
         timeoutMs?: number;
     });
     /**
-     * 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`.
+     * Enqueue one workflow turn under the engine-supplied `taskId`. Does NOT await the decision — the
+     * engine has already suspended the run on `taskId` and applies the decision durably via `onDecision`.
      */
-    dispatch(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
-        taskId: string;
-    }>;
+    dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
 /**

package/dist/index.d.ts

@@ -802,17 +802,17 @@ interface WorkflowExecutor {
      */
     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;
-    }>;
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): enqueue the turn to a worker under the
+     * ENGINE-SUPPLIED `taskId`, WITHOUT awaiting the decision. The engine generates `taskId`, records it
+     * on the run as the awaited marker, AND releases the run's lease — all BEFORE calling this — so the
+     * worker's {@link WorkflowDecision} (delivered over {@link Transport.onDecision} and applied DURABLY
+     * by {@link WorkflowEngine.completeRemoteDecision}, which looks the run up by `decision.runId`) can
+     * never arrive ahead of its marker or contend with a still-held lease and be dropped. This method
+     * therefore ONLY enqueues — it owns no taskId generation and returns nothing. 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[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
@@ -840,6 +840,13 @@ interface Transport {
     onResult(handler: (result: StepResult) => Promise<void>): void;
     /** worker → engine: liveness signal for an in-flight long step. */
     onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /**
+     * Partition this transport's queues/keys by `namespace` (matching the engine's store namespace), so
+     * multiple logical deployments can share one broker. Idempotent. An explicit namespace passed to the
+     * transport's constructor TAKES PRECEDENCE over this. No-op when `namespace === "default"`. Optional —
+     * transports that don't partition simply omit it.
+     */
+    useNamespace?(namespace: string): void;
     /** Release the transport's resources (broker workers, queues, connections) for a clean shutdown.
      *  Optional — an in-process transport has nothing to close. Called on `onApplicationShutdown`
      *  after the engine drains, so a deploy hands off instead of leaving the broker to time out. */
@@ -2244,15 +2251,16 @@ 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 returning the dispatched `taskId` WITHOUT
+ * DISPATCHING a {@link WorkflowTask} over the broker under the ENGINE-SUPPLIED `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
+ * turn to its decision. The engine records the `taskId` on the run as the awaited marker AND releases
+ * the run's lease BEFORE calling `dispatch`, so the worker's {@link import('./interfaces').WorkflowDecision},
+ * delivered over the transport's `onDecision` and applied DURABLY (by run id) on whatever engine
+ * instance consumes it — even one that did not dispatch the turn — can never arrive ahead of its marker
+ * or contend with a still-held lease and be dropped. 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 (or a decision is genuinely lost because the worker died), the
@@ -2268,12 +2276,10 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
         timeoutMs?: number;
     });
     /**
-     * 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`.
+     * Enqueue one workflow turn under the engine-supplied `taskId`. Does NOT await the decision — the
+     * engine has already suspended the run on `taskId` and applies the decision durably via `onDecision`.
      */
-    dispatch(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<{
-        taskId: string;
-    }>;
+    dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
 /**

package/dist/index.js

@@ -701,7 +701,6 @@ function eventMatches(payload, match) {
 __name(eventMatches, "eventMatches");
 
 // src/remote-workflow-executor.ts
-var taskCounter = 0;
 var RemoteWorkflowExecutor = class {
   static {
     __name(this, "RemoteWorkflowExecutor");
@@ -713,15 +712,13 @@ var RemoteWorkflowExecutor = class {
     this.group = group;
   }
   /**
-  * 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`.
+  * Enqueue one workflow turn under the engine-supplied `taskId`. Does NOT await the decision — the
+  * engine has already suspended the run on `taskId` and applies the decision durably via `onDecision`.
   */
-  async dispatch(run, history, pendingSignals) {
+  async dispatch(run, history, taskId, pendingSignals) {
     if (!this.transport.dispatchWorkflowTask) {
       throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
     }
-    taskCounter += 1;
-    const taskId = `${run.id}:wf:${taskCounter}`;
     const task = {
       taskId,
       runId: run.id,
@@ -737,9 +734,6 @@ var RemoteWorkflowExecutor = class {
       attempt: 1
     };
     await this.transport.dispatchWorkflowTask(task);
-    return {
-      taskId
-    };
   }
 };
 
@@ -919,6 +913,17 @@ var TransportPool = class {
       ...groups
     ];
   }
+  /**
+  * Propagate the engine's `namespace` to every transport that partitions by it — so the same
+  * namespace that scopes the store also scopes each transport's queues/keys. A transport that
+  * doesn't partition (no `useNamespace`) is skipped. Idempotent; a transport given an explicit
+  * namespace at construction ignores this (see {@link Transport.useNamespace}).
+  */
+  useNamespace(namespace) {
+    for (const { transport } of this.transports) {
+      transport.useNamespace?.(namespace);
+    }
+  }
   /** Pinned `preferId` first, then the rest (failover order). */
   ordered(preferId) {
     if (!preferId) return this.transports;
@@ -1586,6 +1591,7 @@ var WorkflowEngine = class {
     this.admission.onFreed?.((queue) => this.wakeQueueWaiters(queue));
     this.instanceId = deps.instanceId ?? globalThis.crypto.randomUUID();
     this.namespace = deps.namespace ?? "default";
+    this.pool.useNamespace(this.namespace);
     this.leaseMs = deps.leaseMs ?? 3e4;
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
@@ -2928,19 +2934,9 @@ var WorkflowEngine = class {
     }
     const history = await this.remoteHistory(run.id);
     if (remote.executor.dispatch) {
-      const { taskId } = await remote.executor.dispatch(run, history);
+      const taskId = `${run.id}:wf:${globalThis.crypto.randomUUID().slice(0, 8)}`;
       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,
@@ -2953,6 +2949,7 @@ var WorkflowEngine = class {
         workflow: run.workflow
       });
       await this.store.releaseRunLock(run.id);
+      await remote.executor.dispatch(run, history, taskId);
       return {
         runId: run.id,
         status: "suspended"