@dudousxd/nestjs-durable-core 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1244,7 +1244,7 @@ declare namespace StandardSchemaV1 {
1244
1244
  * (pnpm peer-dependency multiplexing, or a dual ESM/CJS load) still reads the SAME key. A plain
1245
1245
  * `Symbol()` would mint a distinct token per copy, so a decorator running against one core instance
1246
1246
  * could stamp a name core's `ctx.step` (a different instance) can never read back. Mirrors the
1247
- * `STATE_STORE` token fix in `./tokens.ts`.
1247
+ * DI token fix in `./tokens.ts`.
1248
1248
  */
1249
1249
  declare const DURABLE_STEP_NAME: unique symbol;
1250
1250
  /**
@@ -4137,13 +4137,6 @@ declare function countRuns(store: StateStore, query: Omit<RunQuery, 'limit' | 'o
4137
4137
  */
4138
4138
  declare function assertConcurrency(store: StateStore, workflow: string, quota: ConcurrencyQuota): Promise<void>;
4139
4139
 
4140
- /**
4141
- * Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
4142
- * used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
4143
- * nothing; it is kept only so internal consumers (the durable-entity runner) keep compiling.
4144
- */
4145
- type InternalWorkflowCtx = WorkflowCtx;
4146
-
4147
4140
  /** One operation on a durable entity: mutate `state` in place and/or return a result. */
4148
4141
  type EntityHandler<S = unknown> = (state: S, arg: unknown) => unknown | Promise<unknown>;
4149
4142
  /** A durable keyed entity (a virtual object): per-key serialized handlers over durable state. */
@@ -4155,7 +4148,7 @@ interface EntityConfig<S = unknown> {
4155
4148
  }
4156
4149
  /** The slice of the engine the entity subsystem needs (so it stays a standalone module). */
4157
4150
  interface EntityHost {
4158
- register(name: string, version: string, fn: (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>, opts?: {
4151
+ register(name: string, version: string, fn: (ctx: WorkflowCtx, input: unknown) => Promise<unknown>, opts?: {
4159
4152
  origin?: string | undefined;
4160
4153
  }): void;
4161
4154
  signalWithStart(workflow: string, input: unknown, runId: string, signal: {
@@ -5283,7 +5276,7 @@ declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerif
5283
5276
  /** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
5284
5277
  declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
5285
5278
 
5286
- type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
5279
+ type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
5287
5280
  /**
5288
5281
  * Options for {@link WorkflowEngine.start}.
5289
5282
  *
@@ -5583,7 +5576,7 @@ interface WorkflowEngineDeps {
5583
5576
  */
5584
5577
  context?: (() => Record<string, unknown> | undefined) | undefined;
5585
5578
  /**
5586
- * Re-hydrate the originating context around a LOCAL step body, so a `@DurableStep` reader sees the
5579
+ * Re-hydrate the originating context around a LOCAL step body, so a `@Step` reader sees the
5587
5580
  * tenant / user / correlation ids that were live when the run was started — even on a path the
5588
5581
  * engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
5589
5582
  * Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
@@ -7306,7 +7299,7 @@ declare class WorkflowEngine {
7306
7299
  /** {@link getRunChildren} without the tenancy check (the engine's own subtree walks). */
7307
7300
  private runChildrenUnchecked;
7308
7301
  /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
7309
- * `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
7302
+ * `extra` the caller declares. Local-step groups (a group consumed by in-process `@Step`
7310
7303
  * workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
7311
7304
  * with backlog and ZERO workers is still reported (the alert case has no heartbeat to discover). */
7312
7305
  knownGroups(extra?: string[]): string[];
@@ -7395,6 +7388,25 @@ declare class WorkflowEngine {
7395
7388
  private markStarted;
7396
7389
  private singletonWaitResult;
7397
7390
  private execute;
7391
+ /**
7392
+ * A wake that found `run`'s lease held by another execution: keep it for that execution to honor
7393
+ * once it releases the lease, and answer with the run's status as read.
7394
+ */
7395
+ private keepWakeForHeldLease;
7396
+ /**
7397
+ * Take `runId`'s lease for an explicit retry of a `failed` run that found it held: the turn that
7398
+ * failed the run has not released it yet, or another instance holds it for a moment. Polls the
7399
+ * lease with the usual fenced take ({@link StateStore.tryLockRun}, which also takes over a lease
7400
+ * that expired; the old holder's renewal then fences it) until it is free. Returns the run, read
7401
+ * under the lease, while it is still `failed`; or the run's state when something else moved it on
7402
+ * meanwhile (nothing to retry). Throws when the lease stays held by a live execution for longer
7403
+ * than one lease period, or the engine starts draining: the retry is refused, never dropped.
7404
+ */
7405
+ private takeLeaseForRetry;
7406
+ /** `run` as a {@link RunResult}. */
7407
+ private resultOf;
7408
+ /** The body of {@link execute} once this instance holds `run`'s lease. */
7409
+ private executeLeased;
7398
7410
  /**
7399
7411
  * Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
7400
7412
  * runs again once it ends instead of suspending on a snapshot that predates what the wake brought
@@ -8980,11 +8992,6 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
8980
8992
  * `Math.random`; overridden in tests so jitter is deterministic. */
8981
8993
  interface RunSchedulesOptions {
8982
8994
  random?: () => number;
8983
- /**
8984
- * @deprecated No longer called: jitter defers a window to a later tick instead of sleeping inside
8985
- * this one. Kept so existing callers still type-check.
8986
- */
8987
- sleep?: (ms: number) => Promise<void>;
8988
8995
  }
8989
8996
  /** Deterministic run id for a fixed-interval schedule's current time window. */
8990
8997
  declare function scheduledRunId(key: string, everyMs: number, nowMs: number): string;
@@ -9156,35 +9163,33 @@ declare function sanitizeQueueToken(name: string): string;
9156
9163
  * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
9157
9164
  * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
9158
9165
  * (injector) could resolve different symbols → Nest can't satisfy the dependency
9159
- * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
9166
+ * (`<token> is not available in the DurableApiModule context`). A registered symbol collapses
9160
9167
  * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
9161
9168
  */
9162
9169
  /**
9163
- * @deprecated Use {@link STATE_STORE_CANONICAL} (`@dudousxd/nestjs-durable:state-store`). The legacy
9164
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9170
+ * The durable DI tokens, following the ecosystem capability naming `@dudousxd/nestjs-durable:<name>`
9171
+ * (identical to `capability('durable', <name>)`), so an external library can resolve durable's
9172
+ * store/transport/options by name without importing durable internals. Bare `Symbol.for` keeps
9173
+ * `core` free of any `@dudousxd/nestjs-diagnostics` runtime dependency.
9174
+ */
9175
+ declare const STATE_STORE_CANONICAL: unique symbol;
9176
+ declare const TRANSPORT_CANONICAL: unique symbol;
9177
+ declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
9178
+ /**
9179
+ * @deprecated Use {@link STATE_STORE_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9180
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9165
9181
  */
9166
9182
  declare const STATE_STORE: unique symbol;
9167
9183
  /**
9168
- * @deprecated Use {@link TRANSPORT_CANONICAL} (`@dudousxd/nestjs-durable:transport`). The legacy
9169
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9184
+ * @deprecated Use {@link TRANSPORT_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9185
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9170
9186
  */
9171
9187
  declare const TRANSPORT: unique symbol;
9172
9188
  /**
9173
- * @deprecated Use {@link DURABLE_OPTIONS_CANONICAL} (`@dudousxd/nestjs-durable:options`). The legacy
9174
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9189
+ * @deprecated Use {@link DURABLE_OPTIONS_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9190
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9175
9191
  */
9176
9192
  declare const DURABLE_OPTIONS: unique symbol;
9177
- /**
9178
- * Canonical, cross-lib-discoverable aliases of the durable DI tokens, following the ecosystem
9179
- * capability naming `@dudousxd/nestjs-durable:<name>` (identical to `capability('durable', <name>)`).
9180
- * `DurableModule` binds these alongside the legacy tokens (dual-bind), so an external library can
9181
- * resolve durable's store/transport/options by the canonical name without importing durable
9182
- * internals. Bare `Symbol.for` (same cross-copy-stability rationale as the legacy tokens above)
9183
- * keeps `core` free of any `@dudousxd/nestjs-diagnostics` runtime dependency.
9184
- */
9185
- declare const STATE_STORE_CANONICAL: unique symbol;
9186
- declare const TRANSPORT_CANONICAL: unique symbol;
9187
- declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
9188
9193
 
9189
9194
  /**
9190
9195
  * The OPT-IN declaration-site contract for a `@Workflow` class: `implements WorkflowHandler<TInput,
package/dist/index.d.ts CHANGED
@@ -1244,7 +1244,7 @@ declare namespace StandardSchemaV1 {
1244
1244
  * (pnpm peer-dependency multiplexing, or a dual ESM/CJS load) still reads the SAME key. A plain
1245
1245
  * `Symbol()` would mint a distinct token per copy, so a decorator running against one core instance
1246
1246
  * could stamp a name core's `ctx.step` (a different instance) can never read back. Mirrors the
1247
- * `STATE_STORE` token fix in `./tokens.ts`.
1247
+ * DI token fix in `./tokens.ts`.
1248
1248
  */
1249
1249
  declare const DURABLE_STEP_NAME: unique symbol;
1250
1250
  /**
@@ -4137,13 +4137,6 @@ declare function countRuns(store: StateStore, query: Omit<RunQuery, 'limit' | 'o
4137
4137
  */
4138
4138
  declare function assertConcurrency(store: StateStore, workflow: string, quota: ConcurrencyQuota): Promise<void>;
4139
4139
 
4140
- /**
4141
- * Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
4142
- * used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
4143
- * nothing; it is kept only so internal consumers (the durable-entity runner) keep compiling.
4144
- */
4145
- type InternalWorkflowCtx = WorkflowCtx;
4146
-
4147
4140
  /** One operation on a durable entity: mutate `state` in place and/or return a result. */
4148
4141
  type EntityHandler<S = unknown> = (state: S, arg: unknown) => unknown | Promise<unknown>;
4149
4142
  /** A durable keyed entity (a virtual object): per-key serialized handlers over durable state. */
@@ -4155,7 +4148,7 @@ interface EntityConfig<S = unknown> {
4155
4148
  }
4156
4149
  /** The slice of the engine the entity subsystem needs (so it stays a standalone module). */
4157
4150
  interface EntityHost {
4158
- register(name: string, version: string, fn: (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>, opts?: {
4151
+ register(name: string, version: string, fn: (ctx: WorkflowCtx, input: unknown) => Promise<unknown>, opts?: {
4159
4152
  origin?: string | undefined;
4160
4153
  }): void;
4161
4154
  signalWithStart(workflow: string, input: unknown, runId: string, signal: {
@@ -5283,7 +5276,7 @@ declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerif
5283
5276
  /** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
5284
5277
  declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
5285
5278
 
5286
- type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
5279
+ type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
5287
5280
  /**
5288
5281
  * Options for {@link WorkflowEngine.start}.
5289
5282
  *
@@ -5583,7 +5576,7 @@ interface WorkflowEngineDeps {
5583
5576
  */
5584
5577
  context?: (() => Record<string, unknown> | undefined) | undefined;
5585
5578
  /**
5586
- * Re-hydrate the originating context around a LOCAL step body, so a `@DurableStep` reader sees the
5579
+ * Re-hydrate the originating context around a LOCAL step body, so a `@Step` reader sees the
5587
5580
  * tenant / user / correlation ids that were live when the run was started — even on a path the
5588
5581
  * engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
5589
5582
  * Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
@@ -7306,7 +7299,7 @@ declare class WorkflowEngine {
7306
7299
  /** {@link getRunChildren} without the tenancy check (the engine's own subtree walks). */
7307
7300
  private runChildrenUnchecked;
7308
7301
  /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
7309
- * `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
7302
+ * `extra` the caller declares. Local-step groups (a group consumed by in-process `@Step`
7310
7303
  * workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
7311
7304
  * with backlog and ZERO workers is still reported (the alert case has no heartbeat to discover). */
7312
7305
  knownGroups(extra?: string[]): string[];
@@ -7395,6 +7388,25 @@ declare class WorkflowEngine {
7395
7388
  private markStarted;
7396
7389
  private singletonWaitResult;
7397
7390
  private execute;
7391
+ /**
7392
+ * A wake that found `run`'s lease held by another execution: keep it for that execution to honor
7393
+ * once it releases the lease, and answer with the run's status as read.
7394
+ */
7395
+ private keepWakeForHeldLease;
7396
+ /**
7397
+ * Take `runId`'s lease for an explicit retry of a `failed` run that found it held: the turn that
7398
+ * failed the run has not released it yet, or another instance holds it for a moment. Polls the
7399
+ * lease with the usual fenced take ({@link StateStore.tryLockRun}, which also takes over a lease
7400
+ * that expired; the old holder's renewal then fences it) until it is free. Returns the run, read
7401
+ * under the lease, while it is still `failed`; or the run's state when something else moved it on
7402
+ * meanwhile (nothing to retry). Throws when the lease stays held by a live execution for longer
7403
+ * than one lease period, or the engine starts draining: the retry is refused, never dropped.
7404
+ */
7405
+ private takeLeaseForRetry;
7406
+ /** `run` as a {@link RunResult}. */
7407
+ private resultOf;
7408
+ /** The body of {@link execute} once this instance holds `run`'s lease. */
7409
+ private executeLeased;
7398
7410
  /**
7399
7411
  * Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
7400
7412
  * runs again once it ends instead of suspending on a snapshot that predates what the wake brought
@@ -8980,11 +8992,6 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
8980
8992
  * `Math.random`; overridden in tests so jitter is deterministic. */
8981
8993
  interface RunSchedulesOptions {
8982
8994
  random?: () => number;
8983
- /**
8984
- * @deprecated No longer called: jitter defers a window to a later tick instead of sleeping inside
8985
- * this one. Kept so existing callers still type-check.
8986
- */
8987
- sleep?: (ms: number) => Promise<void>;
8988
8995
  }
8989
8996
  /** Deterministic run id for a fixed-interval schedule's current time window. */
8990
8997
  declare function scheduledRunId(key: string, everyMs: number, nowMs: number): string;
@@ -9156,35 +9163,33 @@ declare function sanitizeQueueToken(name: string): string;
9156
9163
  * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
9157
9164
  * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
9158
9165
  * (injector) could resolve different symbols → Nest can't satisfy the dependency
9159
- * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
9166
+ * (`<token> is not available in the DurableApiModule context`). A registered symbol collapses
9160
9167
  * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
9161
9168
  */
9162
9169
  /**
9163
- * @deprecated Use {@link STATE_STORE_CANONICAL} (`@dudousxd/nestjs-durable:state-store`). The legacy
9164
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9170
+ * The durable DI tokens, following the ecosystem capability naming `@dudousxd/nestjs-durable:<name>`
9171
+ * (identical to `capability('durable', <name>)`), so an external library can resolve durable's
9172
+ * store/transport/options by name without importing durable internals. Bare `Symbol.for` keeps
9173
+ * `core` free of any `@dudousxd/nestjs-diagnostics` runtime dependency.
9174
+ */
9175
+ declare const STATE_STORE_CANONICAL: unique symbol;
9176
+ declare const TRANSPORT_CANONICAL: unique symbol;
9177
+ declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
9178
+ /**
9179
+ * @deprecated Use {@link STATE_STORE_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9180
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9165
9181
  */
9166
9182
  declare const STATE_STORE: unique symbol;
9167
9183
  /**
9168
- * @deprecated Use {@link TRANSPORT_CANONICAL} (`@dudousxd/nestjs-durable:transport`). The legacy
9169
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9184
+ * @deprecated Use {@link TRANSPORT_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9185
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9170
9186
  */
9171
9187
  declare const TRANSPORT: unique symbol;
9172
9188
  /**
9173
- * @deprecated Use {@link DURABLE_OPTIONS_CANONICAL} (`@dudousxd/nestjs-durable:options`). The legacy
9174
- * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
9189
+ * @deprecated Use {@link DURABLE_OPTIONS_CANONICAL}. Kept because published `@dudousxd/nestjs-durable`
9190
+ * releases import it from core; `DurableModule` binds it to the same instance as the canonical token.
9175
9191
  */
9176
9192
  declare const DURABLE_OPTIONS: unique symbol;
9177
- /**
9178
- * Canonical, cross-lib-discoverable aliases of the durable DI tokens, following the ecosystem
9179
- * capability naming `@dudousxd/nestjs-durable:<name>` (identical to `capability('durable', <name>)`).
9180
- * `DurableModule` binds these alongside the legacy tokens (dual-bind), so an external library can
9181
- * resolve durable's store/transport/options by the canonical name without importing durable
9182
- * internals. Bare `Symbol.for` (same cross-copy-stability rationale as the legacy tokens above)
9183
- * keeps `core` free of any `@dudousxd/nestjs-diagnostics` runtime dependency.
9184
- */
9185
- declare const STATE_STORE_CANONICAL: unique symbol;
9186
- declare const TRANSPORT_CANONICAL: unique symbol;
9187
- declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
9188
9193
 
9189
9194
  /**
9190
9195
  * The OPT-IN declaration-site contract for a `@Workflow` class: `implements WorkflowHandler<TInput,
package/dist/index.js CHANGED
@@ -6413,6 +6413,7 @@ var PARENT_NOTIFY_BACKOFF_MS = 250;
6413
6413
  var LEASE_RECHECK_MAX_MS = 2e3;
6414
6414
  var LEASE_RECHECK_SLACK_MS = 100;
6415
6415
  var LEASE_RECHECK_ATTEMPTS = 30;
6416
+ var RETRY_LEASE_POLL_MS = 100;
6416
6417
  function wakeSeen(request, settledFans, served) {
6417
6418
  if (request.id !== void 0 && served.has(request.id)) return true;
6418
6419
  return isFanWakeRequest(request.payload) && request.payload.fans.every(([first, seq]) => (settledFans.get(first) ?? -1) >= seq);
@@ -11255,7 +11256,7 @@ var WorkflowEngine = class _WorkflowEngine {
11255
11256
  ];
11256
11257
  }
11257
11258
  /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
11258
- * `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
11259
+ * `extra` the caller declares. Local-step groups (a group consumed by in-process `@Step`
11259
11260
  * workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
11260
11261
  * with backlog and ZERO workers is still reported (the alert case has no heartbeat to discover). */
11261
11262
  knownGroups(extra = []) {
@@ -11579,26 +11580,87 @@ var WorkflowEngine = class _WorkflowEngine {
11579
11580
  const reentered = run.lockedBy === this.instanceId && (run.lockedUntil ?? 0) > lockNow && (lockedForTurn || await this.proveOwnLease(run.id, lockNow));
11580
11581
  if (!reentered) {
11581
11582
  if (!await this.store.tryLockRun(run.id, this.instanceId, lockNow + this.leaseMs, lockNow)) {
11582
- if (reason.generic) {
11583
- if (!this.genericWakeRequested.has(run.id)) {
11584
- this.genericWakeRequested.add(run.id);
11585
- this.inBackground(this.requestWakeAfterTurn(run.id, null));
11586
- }
11587
- } else {
11588
- const fans = {
11589
- fans: [
11590
- ...reason.fans
11591
- ]
11592
- };
11593
- this.inBackground(this.requestWakeAfterTurn(run.id, fans));
11583
+ if (run.status === "failed") {
11584
+ const taken = await this.takeLeaseForRetry(run.id);
11585
+ if ("result" in taken) return taken.result;
11586
+ return this.executeLeased(taken.run, fn, registered);
11594
11587
  }
11595
- this.recheckAfterLease(run.id, run.lockedUntil);
11588
+ return this.keepWakeForHeldLease(run, reason);
11589
+ }
11590
+ }
11591
+ return this.executeLeased(run, fn, registered);
11592
+ }
11593
+ /**
11594
+ * A wake that found `run`'s lease held by another execution: keep it for that execution to honor
11595
+ * once it releases the lease, and answer with the run's status as read.
11596
+ */
11597
+ keepWakeForHeldLease(run, reason) {
11598
+ if (reason.generic) {
11599
+ if (!this.genericWakeRequested.has(run.id)) {
11600
+ this.genericWakeRequested.add(run.id);
11601
+ this.inBackground(this.requestWakeAfterTurn(run.id, null));
11602
+ }
11603
+ } else {
11604
+ const fans = {
11605
+ fans: [
11606
+ ...reason.fans
11607
+ ]
11608
+ };
11609
+ this.inBackground(this.requestWakeAfterTurn(run.id, fans));
11610
+ }
11611
+ this.recheckAfterLease(run.id, run.lockedUntil);
11612
+ return {
11613
+ runId: run.id,
11614
+ status: run.status
11615
+ };
11616
+ }
11617
+ /**
11618
+ * Take `runId`'s lease for an explicit retry of a `failed` run that found it held: the turn that
11619
+ * failed the run has not released it yet, or another instance holds it for a moment. Polls the
11620
+ * lease with the usual fenced take ({@link StateStore.tryLockRun}, which also takes over a lease
11621
+ * that expired; the old holder's renewal then fences it) until it is free. Returns the run, read
11622
+ * under the lease, while it is still `failed`; or the run's state when something else moved it on
11623
+ * meanwhile (nothing to retry). Throws when the lease stays held by a live execution for longer
11624
+ * than one lease period, or the engine starts draining: the retry is refused, never dropped.
11625
+ */
11626
+ async takeLeaseForRetry(runId) {
11627
+ const giveUpAt = Date.now() + this.leaseMs + LEASE_RECHECK_MAX_MS;
11628
+ for (; ; ) {
11629
+ const current = await this.store.getRun(runId);
11630
+ if (!current) throw new Error(`run ${runId} not found`);
11631
+ if (current.status !== "failed") return {
11632
+ result: this.resultOf(current)
11633
+ };
11634
+ const nowMs = this.clock();
11635
+ if (await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs)) {
11636
+ const fresh = await this.store.getRun(runId);
11637
+ if (fresh?.status === "failed") return {
11638
+ run: fresh
11639
+ };
11640
+ await this.releaseLeaseBestEffort(runId);
11596
11641
  return {
11597
- runId: run.id,
11598
- status: run.status
11642
+ result: fresh ? this.resultOf(fresh) : await this.echoCurrentStatus(runId)
11599
11643
  };
11600
11644
  }
11645
+ if (this.draining || Date.now() >= giveUpAt) {
11646
+ throw new Error(`run ${runId} could not be retried: its lease is held by ${current.lockedBy ?? "another execution"}${this.draining ? " and this engine is draining" : ""}; resume it again once that execution settles`);
11647
+ }
11648
+ const leaseLeft = (current.lockedUntil ?? nowMs) - nowMs;
11649
+ const wait = Math.min(RETRY_LEASE_POLL_MS, Math.max(10, leaseLeft + LEASE_RECHECK_SLACK_MS));
11650
+ await new Promise((resolve) => setTimeout(resolve, wait));
11601
11651
  }
11652
+ }
11653
+ /** `run` as a {@link RunResult}. */
11654
+ resultOf(run) {
11655
+ return {
11656
+ runId: run.id,
11657
+ status: run.status,
11658
+ output: run.output,
11659
+ error: run.error
11660
+ };
11661
+ }
11662
+ /** The body of {@link execute} once this instance holds `run`'s lease. */
11663
+ async executeLeased(run, fn, registered) {
11602
11664
  const settledFans = /* @__PURE__ */ new Map();
11603
11665
  this.turnSettledFans.set(run.id, settledFans);
11604
11666
  const held = this.holdExecutionLease(run.id);
@@ -15964,12 +16026,12 @@ function readSearchAttributes(schema, run) {
15964
16026
  __name(readSearchAttributes, "readSearchAttributes");
15965
16027
 
15966
16028
  // src/tokens.ts
15967
- var STATE_STORE = Symbol.for("nestjs-durable:STATE_STORE");
15968
- var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
15969
- var DURABLE_OPTIONS = Symbol.for("nestjs-durable:DURABLE_OPTIONS");
15970
16029
  var STATE_STORE_CANONICAL = Symbol.for("@dudousxd/nestjs-durable:state-store");
15971
16030
  var TRANSPORT_CANONICAL = Symbol.for("@dudousxd/nestjs-durable:transport");
15972
16031
  var DURABLE_OPTIONS_CANONICAL = Symbol.for("@dudousxd/nestjs-durable:options");
16032
+ var STATE_STORE = Symbol.for("nestjs-durable:STATE_STORE");
16033
+ var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
16034
+ var DURABLE_OPTIONS = Symbol.for("nestjs-durable:DURABLE_OPTIONS");
15973
16035
 
15974
16036
  // src/testing/in-memory-state-store.ts
15975
16037
  var RETENTION_EXCLUDED = [