@dudousxd/nestjs-durable-core 0.81.0 → 0.83.0

package/dist/index.d.cts

@@ -1285,8 +1285,15 @@ interface StateStore {
      * acquired — so concurrent engine instances never recover the same run twice.
      */
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
-    /** Release a run's recovery lease so another instance can pick it up (e.g. once it suspends). */
-    releaseRunLock(runId: string): Promise<void>;
+    /**
+     * Release a run's recovery lease so another instance can pick it up (e.g. once it suspends).
+     *
+     * `owner`, when given, makes the release owner-scoped: clear the lease ONLY if `owner` still holds
+     * it, so an instance releasing a lease it may have lost (a drain that timed out) never frees the
+     * lease another instance took over. Without it the release is unconditional. A store that ignores
+     * the argument stays correct, only less precise in that race.
+     */
+    releaseRunLock(runId: string, owner?: string): Promise<void>;
     /**
      * Extend a run's lease to `leaseUntilMs`, but ONLY if `owner` still holds it — so a live worker
      * heartbeating its long run keeps the lease, while a dead worker's lease still expires and gets
@@ -2870,8 +2877,8 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      *
      * When the workflow declares a `@Workflow({ searchAttributes })` schema, the MERGED result (this
      * run's existing `searchAttributes` shallow-merged with `attrs`) is validated against it before the
-     * write — an invalid merge throws, naming the workflow, the offending key(s), and the schema's
-     * issues. Validation runs once, on the same first-run-only position as the write itself (skipped
+     * write — an invalid merge throws a `SchemaValidationError` (code `schema_validation`, never
+     * retried) naming the workflow, with the schema's issues. Validation runs once, on the same first-run-only position as the write itself (skipped
      * entirely on replay, so it's never a source of nondeterminism); it must be synchronous — a schema
      * whose `validate` returns a `Promise` throws instead of being awaited. No schema declared ⇒
      * unchanged, unvalidated behavior.
@@ -3820,7 +3827,10 @@ declare function liveHandoff<C extends {
     seq: number;
     name: string;
 }>(runId: string, checkpoints: readonly C[]): C | undefined;
-/** The route a failure takes: the one for its exact code, else the catch-all, else none. */
+/**
+ * The route a failure takes: the one for its exact code, else (for an `invalid_input` /
+ * `invalid_output` failure) a `schema_validation` route, else the catch-all, else none.
+ */
 declare function routeFor(routes: OnErrorRoute[] | undefined, error: StepError): OnErrorRoute | undefined;
 /** Reject two routes for one code, or two catch-alls — ambiguous config, caught at registration. */
 declare function assertRoutes(workflow: string, routes: OnErrorRoute[]): void;
@@ -4003,6 +4013,60 @@ declare class ScheduleClient {
     private write;
 }
 
+/** Default idle threshold for a stranded run: 15 minutes. */
+declare const DEFAULT_STALLED_AFTER_MS: number;
+/** The oldest unresolved remote step of a run — the lost-dispatch signature when it is old. */
+interface StalePendingStep {
+    seq: number;
+    name: string;
+    /** How many times this step has been (re-)dispatched. A lost dispatch typically sits at 1. */
+    attempts: number;
+    /** Milliseconds since the step was enqueued to the transport. */
+    ageMs: number;
+    /**
+     * The step's lease (`wakeAt`, epoch ms) when it has one: a step with a `timeoutMs`, a heartbeat
+     * renewing it, or `remoteRedispatchMs`. `null` when nothing is leasing the step.
+     */
+    leaseUntil: number | null;
+}
+/** What an `engine.onStalled` listener (and {@link findStalledRuns}) receives: a stranded run and why. */
+interface StalledRunInfo {
+    run: WorkflowRun;
+    /** Milliseconds since the run's last activity (`updatedAt`). */
+    ageMs: number;
+    /** Suspended with NO wake timer — nothing will re-drive it (the `reconcileMs: 0` hazard). */
+    wakeForever: boolean;
+    /** The oldest pending remote step with no live lease, when that is the stranding signature. */
+    stalePending: StalePendingStep | null;
+}
+/** Options for {@link findStalledRuns}. */
+interface FindStalledRunsOptions {
+    /** Idle threshold in ms. Default {@link DEFAULT_STALLED_AFTER_MS}. */
+    thresholdMs?: number | undefined;
+    /** Max candidate runs inspected (newest first). Default 1000. */
+    scan?: number | undefined;
+    /** Evaluate as of this time (epoch ms). Default `Date.now()`. */
+    now?: number | undefined;
+    /** Only runs in this namespace. Omit for every namespace. */
+    namespace?: string | undefined;
+}
+/**
+ * The stranded runs in a store right now — the query behind `engine.sweepStalled`/`onStalled`,
+ * `engine.listStalledRuns` and the CLI's `durable inspect --stale`. Works on a bare store, so an
+ * ops script or a CLI can run it without an engine.
+ *
+ * A `running`/`suspended` run qualifies when it has been untouched for `thresholdMs` AND either:
+ *
+ * - it is suspended with NO wake timer (`wakeForever`): nothing will ever re-drive it; or
+ * - its oldest pending REMOTE step is older than the threshold and has no lease in the future
+ *   (`stalePending`): the dispatch was most likely lost.
+ *
+ * Healthy long work is excluded: a long `ctx.sleep` has a future `wakeAt` and no pending step, and a
+ * remote step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` carries a future lease. Issues
+ * one `listCheckpoints` per idle candidate, bounded by `scan`: an operator read, not a hot path.
+ */
+declare function findStalledRuns(store: Pick<StateStore, 'listRuns' | 'listCheckpoints'>, options?: FindStalledRunsOptions): Promise<StalledRunInfo[]>;
+
 type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
 /**
  * Options for {@link WorkflowEngine.start}.
@@ -4179,6 +4243,14 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * How long an in-flight run must sit untouched, with the stranded signature (a wake-forever
+     * suspension, or an old pending remote step with no live lease), before the
+     * {@link WorkflowEngine.onStalled} listeners are notified. Default 900 000 (15 min); floored at
+     * 60 000. The sweep ({@link WorkflowEngine.sweepStalled}) only does work when a listener is
+     * registered.
+     */
+    stalledAfterMs?: number | undefined;
     /**
      * The most due timers one {@link WorkflowEngine.resumeDueTimers} pass loads and drives, most
      * overdue first. Every driving instance runs that pass each tick, so a wave of thousands of due
@@ -4286,6 +4358,15 @@ interface WorkflowEngineDeps {
      */
     runDispatcher?: RunDispatcher | undefined;
 }
+/** Options for {@link WorkflowEngine.listStalledRuns}. */
+interface ListStalledRunsOptions {
+    /** Idle threshold in ms. Defaults to the engine's `stalledAfterMs` (15 min). */
+    thresholdMs?: number | undefined;
+    /** Max candidate runs inspected (newest first). Default 1000. */
+    scan?: number | undefined;
+    /** Evaluate as of this clock time. Defaults to the engine clock. */
+    now?: number | undefined;
+}
 /**
  * The orchestrator. Owns workflow state and replays runs deterministically: each step's
  * result is checkpointed, so on resume a completed step returns its saved output instead of
@@ -4410,6 +4491,18 @@ declare class WorkflowEngine {
     private readonly stepQueue;
     /** Executions currently in flight, so a graceful shutdown can wait for them to settle. */
     private readonly inflight;
+    /**
+     * The run lease of each execution in flight on THIS instance, by run id — renewed while it runs
+     * and checked by every settle (the zombie fence, see {@link ExecutionLease}). Also what `drain()`
+     * releases when its budget runs out.
+     */
+    private readonly executionLeases;
+    /** Pager hooks for stranded runs (see {@link onStalled}). */
+    private readonly stalledListeners;
+    /** Runs already paged about, by id → the `updatedAt` of the paged episode (see {@link sweepStalled}). */
+    private readonly notifiedStalled;
+    private lastStalledSweepAt;
+    private readonly stalledAfterMs;
     private draining;
     /** Wait already spent on this shutdown before `drain()` (see `beginDrain`). */
     private drainSpentMs;
@@ -4575,6 +4668,33 @@ declare class WorkflowEngine {
      * Returns an unsubscribe function.
      */
     onDead(listener: (run: WorkflowRun) => void): () => void;
+    /**
+     * Register a pager hook for STRANDED runs: an in-flight run untouched past `stalledAfterMs` that is
+     * either suspended with NO wake timer (wake-forever: nothing will ever re-drive it) or parked on an
+     * old pending remote step with no live lease (dispatched and, most likely, lost). The timer poller
+     * sweeps for these ({@link sweepStalled}, throttled to one pass a minute) and notifies each episode
+     * ONCE per instance: a run is paged again only after it makes progress and strands again. Wire your
+     * alerting here like {@link onDead}. A listener that throws never breaks the sweep. Returns an
+     * unsubscribe function.
+     */
+    onStalled(listener: (info: StalledRunInfo) => void): () => void;
+    /**
+     * Detect stranded in-flight runs and notify the {@link onStalled} listeners. Self-throttled to one
+     * pass a minute, skipped while draining, and a no-op without listeners — call it every tick (the
+     * NestJS timer poller does). Scoped to this engine's `namespace` (an operator engine with no
+     * namespace sweeps every namespace). Returns the runs notified THIS pass.
+     */
+    sweepStalled(now?: number): Promise<StalledRunInfo[]>;
+    /**
+     * The stranded runs right now, without notifying anyone: the query behind {@link sweepStalled} and
+     * the CLI's `durable inspect --stale`. A `running`/`suspended` run qualifies when it has been
+     * untouched for `thresholdMs` (default `stalledAfterMs`) AND either it is suspended with no wake
+     * timer, or its oldest pending remote step is older than the threshold with no lease in the future
+     * (a step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` keeps a lease; a long
+     * `ctx.sleep` has a future `wakeAt`; neither is stranded). Scans up to `scan` candidates (default
+     * 1000), newest first, in this engine's namespace.
+     */
+    listStalledRuns(options?: ListStalledRunsOptions): Promise<StalledRunInfo[]>;
     private notifyDead;
     /** Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the
      *  control plane so other instances (e.g. a dashboard pod) can live-tail this run. */
@@ -4586,6 +4706,9 @@ declare class WorkflowEngine {
     start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
     getRun(runId: string): Promise<WorkflowRun | null>;
+    /** A run's full checkpoint timeline, ordered by seq. A thin pass-through to the store (it is what
+     *  the testing kit's `captureHistory` reads, next to {@link getRun}). */
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     /**
      * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
      * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
@@ -4727,6 +4850,8 @@ declare class WorkflowEngine {
      * between this call and `drain()` (other hooks, the HTTP server closing) never is. Calls add up.
      */
     beginDrain(spentMs?: number): void;
+    /** True once {@link beginDrain} (or {@link drain}) has been called. */
+    isDraining(): boolean;
     /**
      * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
      * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
@@ -4737,6 +4862,16 @@ declare class WorkflowEngine {
      * for part of it waits only for the remainder. With nothing reported, the full `timeoutMs` applies.
      */
     drain(timeoutMs?: number): Promise<void>;
+    /**
+     * The drain budget ran out with executions still in flight: release their recovery leases so
+     * another instance re-drives those runs on its next recovery pass, instead of waiting out
+     * `leaseMs` after this process exits. Each still-running turn is FENCED first, so whatever it
+     * computes after this point is never written over the new owner's work (see settleRun). Its
+     * completed steps are checkpointed, so the new owner replays them; a step still executing here
+     * may run again there, exactly as after a crash. The release is owner-scoped where the store
+     * supports it (only a lease this instance still holds is cleared). Best effort: never throws.
+     */
+    private releaseInflightLeases;
     /**
      * Cancel in-flight runs that have outlived their workflow's `executionTimeout`. Call it from the
      * timer poller alongside {@link resumeDueTimers}. A timed-out run is moved to `cancelled` with an
@@ -5281,6 +5416,26 @@ declare class WorkflowEngine {
     private markStarted;
     private singletonWaitResult;
     private execute;
+    /**
+     * Renew `runId`'s lease for as long as this execution holds it, and register it in
+     * {@link executionLeases} so settles can check the zombie fence and `drain()` can release it.
+     *
+     * A renewal that returns `false` means the lease is gone: this turn stalled past `leaseMs` and
+     * another instance reclaimed the run, so this executor is now a zombie. It is FENCED (`lost`): its
+     * settles degrade to an echo of the store's state instead of clobbering the new owner's writes, and
+     * its own lease release is skipped (it would free the new owner's lease). A renewal that THROWS (a
+     * transient store error) is not evidence of a takeover, so it stays swallowed and the next
+     * interval retries. A lease this execution released on purpose (`handedOff`) is not renewed, and a
+     * renewal resolving after the execution ended (`done`) fences nothing.
+     */
+    private holdExecutionLease;
+    /** Whether `runId`'s execution on this instance lost its lease (see {@link holdExecutionLease}). */
+    private isFenced;
+    /**
+     * Mark `runId`'s lease as given away on purpose by its own execution (released mid-turn), so a
+     * renewal that now fails is not read as a takeover.
+     */
+    private handOffLease;
     /**
      * Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
      * a workflow task to the worker and awaits its replay) and apply the decision. Mirrors
@@ -5794,6 +5949,14 @@ declare class DurableWorkflow {
  */
 declare function parseDuration(duration: string | number): number;
 
+/**
+ * Format marker of a run-history replay fixture (`{ version, run, checkpoints }`). Written by the
+ * testing kit's `serializeRunHistory` and the CLI's `durable export`, checked by `parseRunHistory`.
+ * Lives in core so both writers (which already depend on core, not on each other) share one value.
+ * Bump it only when the fixture shape changes incompatibly.
+ */
+declare const RUN_HISTORY_FIXTURE_VERSION = 1;
+
 /**
  * Thrown inside a step to signal an unrecoverable failure: the engine will NOT retry it,
  * regardless of the step's `retries` setting, and fails the run immediately. Use it for
@@ -5808,6 +5971,44 @@ declare class FatalError extends Error {
     readonly retryable = false;
     constructor(message: string, code?: string, details?: unknown);
 }
+/** One schema issue in JSON-safe form: its message and the path segments, as strings. */
+interface SchemaIssue {
+    message: string;
+    path: string[];
+}
+/**
+ * The code a {@link SchemaValidationError} carries: `invalid_input` for an input schema (a
+ * workflow's or a step's), `invalid_output` for an output schema, `schema_validation` for anything
+ * else (a typed `searchAttributes` write). The same codes `@adonis-agora/durable` uses.
+ */
+type SchemaValidationCode = 'invalid_input' | 'invalid_output' | 'schema_validation';
+/**
+ * Thrown when a value fails a schema the app declared: `@Workflow({ input, output })`,
+ * `@Step({ input, output })`, or the workflow's typed `searchAttributes`. A {@link FatalError}, so it
+ * is NOT retried — retrying cannot fix a value that doesn't match its schema. Its `code` says which
+ * schema rejected the value ({@link SchemaValidationCode}). `issues` (also `details.issues`, so it
+ * survives the transport to the run's error and an onError handler's input) lists every issue with
+ * a JSON-safe `path`. Route one code with `onError: [{ code: 'invalid_input', workflow }]`, or all
+ * three with `onError: [{ code: SchemaValidationError, workflow }]`: its `static code`,
+ * `schema_validation`, also catches an `invalid_input` or `invalid_output` no route of its own
+ * matches. Same class, codes, message and `details` as `@adonis-agora/durable`.
+ */
+declare class SchemaValidationError extends FatalError {
+    static readonly code = "schema_validation";
+    readonly issues: SchemaIssue[];
+    /**
+     * @param label What was validated, e.g. `workflow "checkout" input`; the message is
+     *   `invalid <label>: <path>: <message>; …`.
+     * @param summary Overrides the `<path>: <message>; …` part, for issues whose messages already
+     *   name their field (class-validator's `orderId must be a string`).
+     */
+    constructor(label: string, issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }> | undefined;
+    }>, code?: SchemaValidationCode, summary?: string);
+}
 /**
  * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
  * `key` are already in flight (in the quota's counted statuses) and the `limit` is `limit`. Nothing
@@ -6256,26 +6457,45 @@ interface PayloadCodec {
     encode(value: unknown): unknown;
     decode(value: unknown): unknown;
 }
+/** What {@link CodecStateStore} runs through the codec. */
+interface CodecStateStoreOptions {
+    /**
+     * `'payloads'` (default, the historical behaviour): run/step `input` + `output` only (plus a
+     * schedule's `input` and buffered signal/event payloads, which are always encoded). **Know what
+     * that leaves in the clear**: step `events` (everything step code passes to `ctx.log` and every
+     * sub-step outcome) and the structured step/run `error` (message, stack, details). A deployment
+     * sold as "encrypted payloads" still leaks whatever its steps log or throw.
+     *
+     * `'extended'`: also encode step `events`, step `error` and run `error`. Searchable metadata (ids,
+     * status, workflow, tags, search attributes, namespace, origin, timestamps) stays clear — it must
+     * remain queryable. ONLY enable on a FRESH table, or with a codec whose `decode` recognizes its own
+     * ciphertext and passes other values through: rows written before the switch hold those fields as
+     * plaintext, and a decode that can't tell would garble them.
+     */
+    coverage?: 'payloads' | 'extended';
+}
 /**
- * A `StateStore` decorator that runs run/step **payloads** (input + output) through a
- * {@link PayloadCodec} — encoded on write, decoded on read — so they're never stored in the clear.
- * Adapter-agnostic: wrap any store. Searchable metadata (id, status, workflow, tags, timestamps) and
- * the structured `error` are left untouched so the dashboard, queries, and recovery still work.
+ * A `StateStore` decorator that runs run/step **payloads** through a {@link PayloadCodec} — encoded
+ * on write, decoded on read — so they're never stored in the clear. Adapter-agnostic: wrap any
+ * store. Searchable metadata (id, status, workflow, tags, timestamps) is left untouched so the
+ * dashboard, queries, and recovery still work. See {@link CodecStateStoreOptions.coverage} for
+ * exactly which fields are covered — the default covers `input`/`output` only.
  *
  * ```ts
- * const store = new CodecStateStore(new TypeOrmStateStore(ds), aesCodec);
+ * const store = new CodecStateStore(new TypeOrmStateStore(ds), aesCodec, { coverage: 'extended' });
  * ```
  */
 declare class CodecStateStore implements StateStore {
     private readonly inner;
     private readonly codec;
+    private readonly extended;
     /** Atomic claims touch only searchable metadata and bypass payload encoding. */
     readonly tryAdmitSingleton?: (runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number) => Promise<boolean>;
     /**
      * Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
-     * (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
-     * actually aggregates, so `store.runFacets?.()` still reports absence through the wrapper instead
-     * of resolving to a silently wrong empty result.
+     * (it encodes payloads: input/output, plus events/error under `extended` coverage). Bound as a
+     * PROPERTY, and only when the inner store actually aggregates, so `store.runFacets?.()` still
+     * reports absence through the wrapper instead of resolving to a silently wrong empty result.
      */
     readonly runFacets?: (query: RunFacetQuery) => Promise<RunFacetRow[]>;
     /**
@@ -6329,7 +6549,7 @@ declare class CodecStateStore implements StateStore {
     readonly updateSchedule?: (id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null) => Promise<boolean>;
     readonly deleteSchedule?: (id: string) => Promise<boolean>;
     readonly listSchedules?: (query: ScheduleQuery) => Promise<ScheduleRecord[]>;
-    constructor(inner: StateStore, codec: PayloadCodec);
+    constructor(inner: StateStore, codec: PayloadCodec, options?: CodecStateStoreOptions);
     private enc;
     private dec;
     private encRun;
@@ -6355,7 +6575,7 @@ declare class CodecStateStore implements StateStore {
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
-    releaseRunLock(runId: string): Promise<void>;
+    releaseRunLock(runId: string, owner?: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
@@ -6457,11 +6677,20 @@ type Subscribable = {
  */
 declare function collectMetrics(engine: Subscribable): MetricsCollector;
 
-interface ScheduledWorkflow {
+/**
+ * A recurring start of `workflow`, fired on a fixed interval or a cron.
+ *
+ * `workflow` is a registered name or a `@Workflow` class. A class types `input` against its `run`;
+ * annotate the schedule to get that check, as in
+ * `const nightly: ScheduledWorkflow<typeof ReportWorkflow> = { workflow: ReportWorkflow, … }`.
+ */
+interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     /** Stable key identifying this schedule — part of the deterministic run id. */
     key: string;
-    workflow: string;
-    input?: unknown;
+    /** The workflow to start: a registered name (any runtime) or a `@Workflow` class. */
+    workflow: W;
+    /** The input every run starts with — typed against `run` when `workflow` is a class. */
+    input?: WorkflowInputOf<W>;
     /** Start one run every `everyMs`. Mutually exclusive with `cron`. */
     everyMs?: number;
     /**
@@ -6499,6 +6728,16 @@ interface ScheduledWorkflow {
     backfill?: {
         maxCatchup: number;
     };
+    /**
+     * The namespace this schedule's runs are stamped with, overriding the ticking engine's own. Opt-in;
+     * absent = the run gets the namespace of whichever engine fired it.
+     *
+     * The run id is a time bucket, so the instance that wins the race to fire a window decides which
+     * namespace (worker pool) the run lands in. When the workflow can only run in one pool — its steps
+     * need a capability only that pool's workers have — pin it here, so whoever fires the window, the
+     * run is stamped for (and only picked up by) that pool.
+     */
+    namespace?: string;
 }
 /** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
  *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
@@ -6520,14 +6759,23 @@ declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string):
  * schedule is next due.
  */
 declare function nextCronFireMs(expr: string, afterMs: number, timezone?: string): number;
+/**
+ * The deterministic, idempotent run id for a schedule at `nowMs` — its current fire window
+ * (`sched:<key>:<bucket>`, the bucket being a fixed-interval index or the cron fire time). Pass the
+ * same `ScheduledWorkflow` you registered to look a window's run up, e.g.
+ * `engine.getRun(scheduleRunIdAt(dailyReport, Date.now()))`, rather than rebuilding the id by hand.
+ */
+declare function scheduleRunIdAt(s: ScheduledWorkflow, nowMs: number): string;
 /**
  * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
  * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
  * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
- * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
- * current windows.
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids this call
+ * started: a window that already has a run is not started or returned again, and once this process
+ * has seen a window's run exist, later calls in that window skip it without a store read or a
+ * jitter sleep.
  */
-declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
+declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining'>>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 
 /**
  * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
@@ -6797,7 +7045,7 @@ declare class InMemoryStateStore implements StateStore {
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
-    releaseRunLock(runId: string): Promise<void>;
+    releaseRunLock(runId: string, owner?: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
@@ -6940,4 +7188,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDetailOptions, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };