@dudousxd/nestjs-durable-core 0.75.2 → 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`. */
@@ -4833,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. */
@@ -5508,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>;
@@ -5977,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`. */
@@ -4833,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. */
@@ -5508,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>;
@@ -5977,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

@@ -4178,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({
@@ -7091,10 +7102,12 @@ var WorkflowEngine = class {
       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);
@@ -7107,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,
@@ -7121,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,
@@ -7211,6 +7227,12 @@ var WorkflowEngine = class {
     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. */
@@ -7241,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,
@@ -7250,6 +7272,7 @@ var WorkflowEngine = class {
       startedAt,
       finishedAt
     });
+    if (!claimed) return;
     this.emit({
       type: result.status === "completed" ? "step.completed" : "step.failed",
       runId: result.runId,
@@ -7642,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;
@@ -7669,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;
@@ -8232,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()