@dudousxd/nestjs-durable-core 0.75.2 → 0.76.1

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`. */
@@ -3796,6 +3806,12 @@ declare class WorkflowEngine {
      * {@link redriveSettledSteps}).
      */
     private readonly awaitedRemoteSteps;
+    /**
+     * When THIS instance settled a remote step from its result, by `runId:seq`. That result's resume
+     * runs here, and `execute` lets it into a lease this instance holds, so its wake is never the
+     * dropped one {@link redriveSettledSteps} recovers. Pruned by age (see {@link noteSettledHere}).
+     */
+    private readonly settledHere;
     /** 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. */
@@ -4833,6 +4849,10 @@ declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
+    private noteSettledHere;
+    /** {@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 +5528,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 +6000,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`. */
@@ -3796,6 +3806,12 @@ declare class WorkflowEngine {
      * {@link redriveSettledSteps}).
      */
     private readonly awaitedRemoteSteps;
+    /**
+     * When THIS instance settled a remote step from its result, by `runId:seq`. That result's resume
+     * runs here, and `execute` lets it into a lease this instance holds, so its wake is never the
+     * dropped one {@link redriveSettledSteps} recovers. Pruned by age (see {@link noteSettledHere}).
+     */
+    private readonly settledHere;
     /** 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. */
@@ -4833,6 +4849,10 @@ declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
+    private noteSettledHere;
+    /** {@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 +5528,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 +6000,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

@@ -3704,6 +3704,12 @@ var WorkflowEngine = class {
   * {@link redriveSettledSteps}).
   */
   awaitedRemoteSteps = /* @__PURE__ */ new Map();
+  /**
+  * When THIS instance settled a remote step from its result, by `runId:seq`. That result's resume
+  * runs here, and `execute` lets it into a lease this instance holds, so its wake is never the
+  * dropped one {@link redriveSettledSteps} recovers. Pruned by age (see {@link noteSettledHere}).
+  */
+  settledHere = /* @__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. */
@@ -4178,7 +4184,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({
@@ -5120,6 +5137,16 @@ var WorkflowEngine = class {
     for (const seq of seqs) {
       const cp = await this.store.getCheckpoint(runId, seq);
       if (cp && (cp.status === "completed" || cp.status === "failed")) {
+        if (this.settledHere.has(`${runId}:${seq}`)) return;
+        const nowMs = this.clock();
+        if (!await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs)) {
+          return;
+        }
+        const run = await this.store.getRun(runId);
+        if (run?.status !== "suspended") {
+          await this.store.releaseRunLock(runId);
+          return;
+        }
         await this.resumeImplicit(runId);
         return;
       }
@@ -7091,10 +7118,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 +7136,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 +7150,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 +7243,21 @@ var WorkflowEngine = class {
     this.awaitedRemoteSteps.get(runId)?.add(seq);
     throw new WorkflowSuspended();
   }
+  /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
+  noteSettledHere(key) {
+    const now = this.clock();
+    this.settledHere.set(key, now);
+    if (this.settledHere.size < 1024) return;
+    for (const [k, at] of this.settledHere) {
+      if (now - at > this.leaseMs) this.settledHere.delete(k);
+    }
+  }
+  /** {@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 +7288,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 +7297,8 @@ var WorkflowEngine = class {
       startedAt,
       finishedAt
     });
+    if (!claimed) return;
+    this.noteSettledHere(`${result.runId}:${result.seq}`);
     this.emit({
       type: result.status === "completed" ? "step.completed" : "step.failed",
       runId: result.runId,
@@ -7642,6 +7691,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 +7721,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 +8286,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()