@dudousxd/nestjs-durable-core 0.49.0 → 0.49.2

package/dist/index.d.cts

@@ -1113,6 +1113,16 @@ interface GroupHealth {
     depth: number;
     /** Workers with a non-expired heartbeat for this group. */
     liveWorkers: WorkerHeartbeat[];
+    /**
+     * Whether this group serves a `@Workflow` body or a `@Step`/handler — route-by-handler gives each
+     * its own queue, so a health list mixes both. Classified by the CONTROL PLANE from its authoritative
+     * registry (`workerHealth()`): a group whose base name is a registered workflow is `'workflow'`,
+     * everything else (in-process steps, remote `handle_*`) is `'step'`. `undefined` only when no
+     * control-plane registry was available to classify (e.g. a transport that reports health with no
+     * engine). Lets a dashboard summarise the fleet in domain terms ("N workflows · M steps") instead of
+     * leaking the raw queue count.
+     */
+    kind?: 'workflow' | 'step';
 }
 /**
  * The **control plane** — a broadcast pub/sub across ALL engine instances (every pod), separate
@@ -1774,6 +1784,19 @@ interface WorkflowEngineDeps {
      * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
      */
     remoteAdvanceSilenceMs?: number | undefined;
+    /**
+     * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
+     * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
+     * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
+     * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
+     * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
+     * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
+     * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
+     * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
+     * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
+     * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
+     */
+    reconcileMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1849,6 +1872,7 @@ declare class WorkflowEngine {
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
+    private readonly reconcileMs;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2314,6 +2338,13 @@ declare class WorkflowEngine {
      * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
      */
     private settleRun;
+    /**
+     * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+     * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+     * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+     * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+     */
+    private reconcileWakeAt;
     private runRemoteExecution;
     /**
      * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then

package/dist/index.d.ts

@@ -1113,6 +1113,16 @@ interface GroupHealth {
     depth: number;
     /** Workers with a non-expired heartbeat for this group. */
     liveWorkers: WorkerHeartbeat[];
+    /**
+     * Whether this group serves a `@Workflow` body or a `@Step`/handler — route-by-handler gives each
+     * its own queue, so a health list mixes both. Classified by the CONTROL PLANE from its authoritative
+     * registry (`workerHealth()`): a group whose base name is a registered workflow is `'workflow'`,
+     * everything else (in-process steps, remote `handle_*`) is `'step'`. `undefined` only when no
+     * control-plane registry was available to classify (e.g. a transport that reports health with no
+     * engine). Lets a dashboard summarise the fleet in domain terms ("N workflows · M steps") instead of
+     * leaking the raw queue count.
+     */
+    kind?: 'workflow' | 'step';
 }
 /**
  * The **control plane** — a broadcast pub/sub across ALL engine instances (every pod), separate
@@ -1774,6 +1784,19 @@ interface WorkflowEngineDeps {
      * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
      */
     remoteAdvanceSilenceMs?: number | undefined;
+    /**
+     * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
+     * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
+     * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
+     * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
+     * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
+     * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
+     * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
+     * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
+     * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
+     * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
+     */
+    reconcileMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1849,6 +1872,7 @@ declare class WorkflowEngine {
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
+    private readonly reconcileMs;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2314,6 +2338,13 @@ declare class WorkflowEngine {
      * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
      */
     private settleRun;
+    /**
+     * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+     * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+     * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+     * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+     */
+    private reconcileWakeAt;
     private runRemoteExecution;
     /**
      * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then

package/dist/index.js

@@ -1720,6 +1720,7 @@ var WorkflowEngine = class {
   leaseMs;
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
+  reconcileMs;
   webhookUrl;
   traceparent;
   context;
@@ -1790,6 +1791,7 @@ var WorkflowEngine = class {
     this.leaseMs = deps.leaseMs ?? 3e4;
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
+    this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -2879,10 +2881,21 @@ var WorkflowEngine = class {
       ...this.knownGroups(extra),
       ...await this.pool.listWorkerGroups()
     ]);
+    const workflowTokens = /* @__PURE__ */ new Set();
+    for (const def of this.workflows.values()) {
+      workflowTokens.add(sanitizeQueueToken(def.name));
+      if (def.remote?.group) workflowTokens.add(def.remote.group);
+    }
     const out = [];
     for (const group of groups) {
       const health = await this.pool.groupHealth(group);
-      if (health) out.push(health);
+      if (!health) continue;
+      const at = group.lastIndexOf("@");
+      const baseToken = at === -1 ? group : group.slice(0, at);
+      out.push({
+        ...health,
+        kind: workflowTokens.has(baseToken) ? "workflow" : "step"
+      });
     }
     return out;
   }
@@ -3123,7 +3136,7 @@ var WorkflowEngine = class {
     }
     await this.store.updateRun(run.id, {
       status: "suspended",
-      wakeAt: outcome.wakeAt,
+      wakeAt: this.reconcileWakeAt(outcome.wakeAt),
       updatedAt
     });
     this.emit({
@@ -3137,6 +3150,16 @@ var WorkflowEngine = class {
       status: "suspended"
     };
   }
+  /**
+  * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+  * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+  * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+  * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+  */
+  reconcileWakeAt(wakeAt) {
+    if (wakeAt != null) return wakeAt;
+    return this.reconcileMs != null ? this.clock() + this.reconcileMs : void 0;
+  }
   async runRemoteExecution(run, registered) {
     if (run.status === "cancelling") {
       const error = {