@dudousxd/nestjs-durable-core 0.75.1 → 0.76.0

package/dist/index.d.cts

@@ -969,6 +969,16 @@ interface StateStore {
      * being a single transaction; stores without transactions cannot give the strong guarantee.
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    /**
+     * Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
+     * still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
+     * places at once (a turn stamping its redispatch deadline, and the worker's result settling it),
+     * so a blind {@link saveCheckpoint} from a row read a moment earlier can put a `completed` step
+     * back to `pending`. This is the compare-and-set that prevents it.
+     *
+     * Optional: a store that omits it falls back to {@link saveCheckpoint}, which keeps that race.
+     */
+    saveCheckpointIfPending?(checkpoint: StepCheckpoint): Promise<boolean>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
@@ -3790,6 +3800,12 @@ declare class WorkflowEngine {
     private readonly updateValidators;
     /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
     private readonly cancelRequested;
+    /**
+     * Seqs of the dispatched remote steps a turn suspended on, by run, while that turn executes on
+     * THIS instance — so the turn can re-check them once its lease is released (see
+     * {@link redriveSettledSteps}).
+     */
+    private readonly awaitedRemoteSteps;
     /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
     private readonly admission;
     /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
@@ -4300,6 +4316,16 @@ declare class WorkflowEngine {
      * itself. Only re-drives for a group with no waiter left whose checkpoints are all settled, which
      * the next turn is then guaranteed to see — so it cannot loop.
      */
+    /**
+     * Re-drive a run that just suspended on dispatched remote steps which, by now, have a result.
+     *
+     * Same race as {@link redriveSettledChildren}, for `ctx.step`: a result landing while the turn
+     * that dispatched it still holds the lease has its wake dropped by {@link execute}, and the turn
+     * then suspends with nothing left to wake it before the step's redispatch deadline. Called after
+     * the lease is released, so any later result wakes the run itself; it only re-drives for a
+     * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
+     */
+    private redriveSettledSteps;
     private redriveSettledChildren;
     /**
      * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
@@ -4817,6 +4843,8 @@ declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
+    private savePendingCheckpoint;
     /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
      *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
      *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -5492,6 +5520,9 @@ declare class CodecStateStore implements StateStore {
     /** Forwarded verbatim (deletes touch no payload). Bound only when the inner store has it, so the
      *  engine's per-run fallback still kicks in through the wrapper. */
     readonly deleteRuns?: (runIds: string[]) => Promise<void>;
+    /** Encodes like {@link saveCheckpoint}. Bound only when the inner store has it, so the engine's
+     *  plain-save fallback still kicks in through the wrapper. */
+    readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
     /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
      *  when the inner store prunes, so the retention poller still sees (and warns about) its absence. */
     readonly pruneTerminalRuns?: (policy: RetentionPolicy, nowMs: number, limit: number) => Promise<number>;
@@ -5961,6 +5992,7 @@ declare class InMemoryStateStore implements StateStore {
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;

package/dist/index.d.ts

@@ -969,6 +969,16 @@ interface StateStore {
      * being a single transaction; stores without transactions cannot give the strong guarantee.
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    /**
+     * Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
+     * still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
+     * places at once (a turn stamping its redispatch deadline, and the worker's result settling it),
+     * so a blind {@link saveCheckpoint} from a row read a moment earlier can put a `completed` step
+     * back to `pending`. This is the compare-and-set that prevents it.
+     *
+     * Optional: a store that omits it falls back to {@link saveCheckpoint}, which keeps that race.
+     */
+    saveCheckpointIfPending?(checkpoint: StepCheckpoint): Promise<boolean>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
@@ -3790,6 +3800,12 @@ declare class WorkflowEngine {
     private readonly updateValidators;
     /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
     private readonly cancelRequested;
+    /**
+     * Seqs of the dispatched remote steps a turn suspended on, by run, while that turn executes on
+     * THIS instance — so the turn can re-check them once its lease is released (see
+     * {@link redriveSettledSteps}).
+     */
+    private readonly awaitedRemoteSteps;
     /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
     private readonly admission;
     /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
@@ -4300,6 +4316,16 @@ declare class WorkflowEngine {
      * itself. Only re-drives for a group with no waiter left whose checkpoints are all settled, which
      * the next turn is then guaranteed to see — so it cannot loop.
      */
+    /**
+     * Re-drive a run that just suspended on dispatched remote steps which, by now, have a result.
+     *
+     * Same race as {@link redriveSettledChildren}, for `ctx.step`: a result landing while the turn
+     * that dispatched it still holds the lease has its wake dropped by {@link execute}, and the turn
+     * then suspends with nothing left to wake it before the step's redispatch deadline. Called after
+     * the lease is released, so any later result wakes the run itself; it only re-drives for a
+     * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
+     */
+    private redriveSettledSteps;
     private redriveSettledChildren;
     /**
      * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
@@ -4817,6 +4843,8 @@ declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
+    private savePendingCheckpoint;
     /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
      *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
      *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -5492,6 +5520,9 @@ declare class CodecStateStore implements StateStore {
     /** Forwarded verbatim (deletes touch no payload). Bound only when the inner store has it, so the
      *  engine's per-run fallback still kicks in through the wrapper. */
     readonly deleteRuns?: (runIds: string[]) => Promise<void>;
+    /** Encodes like {@link saveCheckpoint}. Bound only when the inner store has it, so the engine's
+     *  plain-save fallback still kicks in through the wrapper. */
+    readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
     /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
      *  when the inner store prunes, so the retention poller still sees (and warns about) its absence. */
     readonly pruneTerminalRuns?: (policy: RetentionPolicy, nowMs: number, limit: number) => Promise<number>;
@@ -5961,6 +5992,7 @@ declare class InMemoryStateStore implements StateStore {
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;

package/dist/index.js

@@ -3698,6 +3698,12 @@ var WorkflowEngine = class {
   updateValidators = /* @__PURE__ */ new Map();
   /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
   cancelRequested = /* @__PURE__ */ new Set();
+  /**
+  * Seqs of the dispatched remote steps a turn suspended on, by run, while that turn executes on
+  * THIS instance — so the turn can re-check them once its lease is released (see
+  * {@link redriveSettledSteps}).
+  */
+  awaitedRemoteSteps = /* @__PURE__ */ new Map();
   /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
   admission;
   /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
@@ -4172,7 +4178,18 @@ var WorkflowEngine = class {
       createdAt: now,
       updatedAt: now
     };
-    await this.store.createRun(run);
+    try {
+      await this.store.createRun(run);
+    } catch (err) {
+      const winner = await this.store.getRun(runId).catch(() => null);
+      if (!winner) throw err;
+      return {
+        runId,
+        status: winner.status,
+        output: winner.output,
+        error: winner.error
+      };
+    }
     await this.runDispatcher.dispatch(runId);
     if (this.controlPlane) {
       void this.controlPlane.publishControl({
@@ -5101,6 +5118,24 @@ var WorkflowEngine = class {
   * itself. Only re-drives for a group with no waiter left whose checkpoints are all settled, which
   * the next turn is then guaranteed to see — so it cannot loop.
   */
+  /**
+  * Re-drive a run that just suspended on dispatched remote steps which, by now, have a result.
+  *
+  * Same race as {@link redriveSettledChildren}, for `ctx.step`: a result landing while the turn
+  * that dispatched it still holds the lease has its wake dropped by {@link execute}, and the turn
+  * then suspends with nothing left to wake it before the step's redispatch deadline. Called after
+  * the lease is released, so any later result wakes the run itself; it only re-drives for a
+  * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
+  */
+  async redriveSettledSteps(runId, seqs) {
+    for (const seq of seqs) {
+      const cp = await this.store.getCheckpoint(runId, seq);
+      if (cp && (cp.status === "completed" || cp.status === "failed")) {
+        await this.resumeImplicit(runId);
+        return;
+      }
+    }
+  }
   async redriveSettledChildren(runId, fan) {
     if (!this.store.hasSignalWaiter) return;
     for (const wait of fan.waits) {
@@ -6555,6 +6590,9 @@ var WorkflowEngine = class {
     const replay = /* @__PURE__ */ new Map();
     for (const cp of snapshot) replay.set(cp.seq, cp);
     let suspendedOnFan;
+    let suspendedOnSteps = false;
+    const awaitedSteps = /* @__PURE__ */ new Set();
+    this.awaitedRemoteSteps.set(run.id, awaitedSteps);
     const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow, registered?.searchAttributesSchema);
     try {
       const output = await runInWorkflowCtx(ctx, () => fn(ctx, run.input));
@@ -6611,6 +6649,7 @@ var WorkflowEngine = class {
           wakeAt: err.wakeAt
         });
         suspendedOnFan = err.fan;
+        suspendedOnSteps = suspended.status === "suspended";
         return suspended;
       }
       if (this.cancelRequested.has(run.id)) {
@@ -6630,10 +6669,16 @@ var WorkflowEngine = class {
         error: error2
       });
     } finally {
+      if (this.awaitedRemoteSteps.get(run.id) === awaitedSteps) {
+        this.awaitedRemoteSteps.delete(run.id);
+      }
       await this.store.releaseRunLock(run.id);
       if (suspendedOnFan) {
         void this.redriveSettledChildren(run.id, suspendedOnFan).catch(() => void 0);
       }
+      if (suspendedOnSteps && awaitedSteps.size > 0) {
+        void this.redriveSettledSteps(run.id, awaitedSteps).catch(() => void 0);
+      }
     }
   }
   /**
@@ -7053,13 +7098,16 @@ var WorkflowEngine = class {
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
     if (step.timeoutMs) return this.callRemoteInMemory(runId, seq, step, input, transport, group);
     if (existing?.status === "pending") {
+      this.awaitedRemoteSteps.get(runId)?.add(seq);
       if (this.remoteRedispatchMs == null) throw new WorkflowSuspended();
       if (existing.wakeAt == null) {
         const wakeAt = this.clock() + this.remoteRedispatchMs;
-        await this.store.saveCheckpoint({
+        if (!await this.savePendingCheckpoint({
           ...existing,
           wakeAt
-        });
+        })) {
+          return this.callRemote(runId, seq, step, input, queue, transport, void 0, admission, routing);
+        }
         throw new WorkflowSuspended(wakeAt);
       }
       if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
@@ -7072,7 +7120,7 @@ var WorkflowEngine = class {
       const reAttempt = existing.attempts + 1;
       const nextDeadline = this.clock() + this.remoteRedispatchMs;
       const reEnqueuedAt = /* @__PURE__ */ new Date();
-      await this.store.saveCheckpoint({
+      const claimed = await this.savePendingCheckpoint({
         ...existing,
         attempts: reAttempt,
         wakeAt: nextDeadline,
@@ -7086,6 +7134,9 @@ var WorkflowEngine = class {
           lostStepEvent(this.clock(), reAttempt, "redispatched")
         ]
       });
+      if (!claimed) {
+        return this.callRemote(runId, seq, step, input, queue, transport, void 0, admission, routing);
+      }
       await this.dispatchRemoteTask({
         runId,
         seq,
@@ -7173,8 +7224,15 @@ var WorkflowEngine = class {
       name: step.name,
       kind: "remote"
     });
+    this.awaitedRemoteSteps.get(runId)?.add(seq);
     throw new WorkflowSuspended();
   }
+  /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
+  async savePendingCheckpoint(checkpoint) {
+    if (this.store.saveCheckpointIfPending) return this.store.saveCheckpointIfPending(checkpoint);
+    await this.store.saveCheckpoint(checkpoint);
+    return true;
+  }
   /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
   *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
   *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -7205,7 +7263,7 @@ var WorkflowEngine = class {
     if (run && (run.status === "cancelled" || run.status === "completed")) return;
     const finishedAt = /* @__PURE__ */ new Date();
     const startedAt = result.startedAt ? new Date(result.startedAt) : cp.startedAt;
-    await this.store.saveCheckpoint({
+    const claimed = await this.savePendingCheckpoint({
       ...cp,
       status: result.status,
       output: result.status === "completed" ? result.output : cp.output,
@@ -7214,6 +7272,7 @@ var WorkflowEngine = class {
       startedAt,
       finishedAt
     });
+    if (!claimed) return;
     this.emit({
       type: result.status === "completed" ? "step.completed" : "step.failed",
       runId: result.runId,
@@ -7606,6 +7665,9 @@ var CodecStateStore = class {
   /** Forwarded verbatim (deletes touch no payload). Bound only when the inner store has it, so the
   *  engine's per-run fallback still kicks in through the wrapper. */
   deleteRuns;
+  /** Encodes like {@link saveCheckpoint}. Bound only when the inner store has it, so the engine's
+  *  plain-save fallback still kicks in through the wrapper. */
+  saveCheckpointIfPending;
   /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
   *  when the inner store prunes, so the retention poller still sees (and warns about) its absence. */
   pruneTerminalRuns;
@@ -7633,6 +7695,8 @@ var CodecStateStore = class {
     if (inner.tryAdmitSingleton) this.tryAdmitSingleton = inner.tryAdmitSingleton.bind(inner);
     const deleteRuns = inner.deleteRuns;
     if (deleteRuns) this.deleteRuns = (ids) => deleteRuns.call(inner, ids);
+    const saveIfPending = inner.saveCheckpointIfPending;
+    if (saveIfPending) this.saveCheckpointIfPending = (cp) => saveIfPending.call(inner, this.encCp(cp));
     const prune = inner.pruneTerminalRuns;
     if (prune) this.pruneTerminalRuns = (policy, now, limit) => prune.call(inner, policy, now, limit);
     const count = inner.countRuns;
@@ -8196,6 +8260,14 @@ var InMemoryStateStore = class {
       ...checkpoint
     });
   }
+  async saveCheckpointIfPending(checkpoint) {
+    const key = this.key(checkpoint.runId, checkpoint.seq);
+    if (this.checkpoints.get(key)?.status !== "pending") return false;
+    this.checkpoints.set(key, {
+      ...checkpoint
+    });
+    return true;
+  }
   async listIncompleteRuns(namespace) {
     return [
       ...this.runs.values()