@adonis-agora/durable 0.49.0 → 0.50.0

package/dist/src/engine.d.ts

@@ -2,16 +2,31 @@ import { type AdmissionBackend } from './admission.js';
 import { type ConcurrencyConfig, type ConcurrencyQuota } from './concurrency.js';
 import { type EntityConfig } from './entities.js';
 import { type EventBatchConfig } from './event-accumulators.js';
-import type { ControlPlane, EngineListener, GroupHealth, NamedTransport, RunDispatcher, RunFacetQuery, RunQuery, RunResult, RunScope, RunStatus, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScopedRetentionPolicy, SearchAttributes, SignalWaiter, StateStore, StepCheckpoint, StepError, StepInterceptor, Transport, UpdateResult, UpdateValidator, WorkflowCtx, WorkflowExecutor, WorkflowRun } from './interfaces.js';
+import { type AnnouncedWorkflow } from './handshake/announced.js';
+import { type WorkflowDirectory } from './handshake/directory.js';
+import type { ControlPlane, EngineListener, GroupHealth, NamedTransport, RunDispatcher, RunFacetQuery, RunFacetRow, RunQuery, RunResult, RunScope, RunStatus, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScopedRetentionPolicy, SearchAttributes, SearchAttributesSchema, SignalWaiter, StateStore, StepCheckpoint, StepError, StepInterceptor, Transport, UpdateResult, UpdateValidator, WorkflowCtx, WorkflowExecutor, WorkflowRun } from './interfaces.js';
 import { type OnErrorRoute } from './on-error.js';
+import { type StepHandler } from './protocol.js';
 import type { QueueConfig } from './queue.js';
+import { type FanPage, type FanPageQuery, type RunDetail, type RunDetailOptions } from './run-detail-summary.js';
 import { type ScheduledWorkflow } from './scheduler.js';
 import { ScheduleClient } from './schedules.js';
+import { type StandardSchemaV1 } from './standard-schema.js';
 import type { NormalizedEventTrigger } from './workflow-events.js';
 import { type WorkflowClass, type WorkflowInputOf, type WorkflowRef } from './workflow-ref.js';
 type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
 /** Options for {@link WorkflowEngine.start}. */
 export interface StartOptions {
+    /**
+     * Pin the run to this registered version of the workflow instead of the newest one. Resolved
+     * against the name@version registry ({@link WorkflowEngine.register}, `registerRemote`,
+     * {@link WorkflowEngine.remote}); a version that is not registered throws before any run row is
+     * created and never falls back to the newest (a caller that asked for `name@3` and silently got
+     * `name@4` could not tell). Not honoured by convention routing (an unregistered name routed to a
+     * live worker group), which invents its version: a pinned start there throws instead. Absent →
+     * the newest registered version, as before.
+     */
+    version?: string | undefined;
     /** Run-scoped tags, merged with the workflow's static `workflow` config `tags` onto the run. */
     tags?: string[] | undefined;
     /** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
@@ -90,8 +105,9 @@ export interface StalledRunInfo {
 /**
  * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
  * Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
- * admission on a timer until a slot frees. Race-free on a consistent store (admission order is the
- * same `(createdAt, id)` view for every instance).
+ * admission on a timer until a slot frees. The store claims slots atomically
+ * ({@link StateStore.tryAdmitSingleton}) and records them durably on the run, so concurrent
+ * replicas can't over-admit and a later (or same-millisecond) start can't displace a holder.
  */
 export interface SingletonConfig {
     /** Derive the serialization key from the workflow input. */
@@ -102,7 +118,7 @@ export interface SingletonConfig {
      * Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
      * set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
      * `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
-     * default unbounded queue. Counts `pending`/`running`/`suspended` runs sharing the key.
+     * default unbounded queue. Counts `pending`/`running`/`suspended`/`blocked` runs sharing the key.
      */
     maxQueueDepth?: number;
 }
@@ -135,12 +151,17 @@ export interface WorkflowEngineDeps {
      * (`runPending` / `recoverIncomplete` / `resumeDueTimers` / `sweepTimeouts`) only act on runs in
      * this namespace, and `resume` of a foreign run throws {@link NamespaceMismatch}.
      *
-     * **Leaving it UNSET makes this engine an operator**: it drives, recovers and resumes runs of EVERY
+     * **`undefined` here makes this engine an operator**: it drives, recovers and resumes runs of EVERY
      * namespace (the store's poll filters no-op on `undefined`) and leaves its transports on their bare
      * prefix. That is what lets one control plane serve many tenant pools — the queue a step lands on
      * is derived from the RUN's namespace, not this engine's. Set a value to scope the instance to one
      * pool instead, so ONE state store can be shared across non-interchangeable pools (e.g. local dev
      * vs a cluster). `'default'` and `''` are the bare pool, byte-identical to a single-pool deployment.
+     *
+     * The AdonisJS provider maps `config/durable.ts` onto this: an absent `namespace` is `'default'` on
+     * a `standalone` engine (it drives only the default pool, legacy rows included), and stays
+     * `undefined` — the operator — only on a `role: 'control-plane'` engine. Constructing the engine by
+     * hand keeps the raw meaning above.
      */
     namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
@@ -168,6 +189,7 @@ export interface WorkflowEngineDeps {
      * 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).
+     * A non-finite or negative value falls back to the default.
      */
     reconcileMs?: number | undefined;
     /**
@@ -178,6 +200,14 @@ export interface WorkflowEngineDeps {
      * falls back to the default. Default 500.
      */
     timerBatchSize?: number | undefined;
+    /**
+     * How long (ms) a BUFFERED event that no `waitForEvent` claimed is kept (see
+     * {@link WorkflowEngine.publishEvent}'s buffering). Default `undefined`: kept until consumed, like a
+     * buffered signal. When set, a `waitForEvent` skips (and removes) a candidate older than this, and
+     * the worker tick's retention phase deletes expired rows across every name in bounded batches
+     * (through {@link StateStore.pruneBufferedEvents}, when the store has it).
+     */
+    eventBufferTtlMs?: number | undefined;
     /**
      * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
      * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
@@ -193,12 +223,33 @@ export interface WorkflowEngineDeps {
      * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
      */
     remoteRedispatchMs?: number | undefined;
+    /**
+     * Minimum gap (ms) between two persisted heartbeats of one step (see `persistHeartbeat`). Default
+     * 10s: beats can arrive every few seconds from a hot loop, and liveness observability must not
+     * become a per-item UPDATE storm. It is also how stale a beat persisted by ANOTHER instance can be
+     * when a step's dispatcher reads it, so the dispatcher allows this much extra silence once it sees
+     * beats landing elsewhere. Mostly a testing knob.
+     */
+    heartbeatPersistThrottleMs?: number | undefined;
     /**
      * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
      * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
      * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
      */
     remoteRedispatchMax?: number | undefined;
+    /**
+     * Opt-in liveness window (ms) for a remote workflow TURN. A dispatched turn whose decision has not
+     * landed, and whose worker has sent no run-scoped {@link Heartbeat}, within this window is presumed
+     * lost: the timer poller re-drives the run by dispatching a fresh turn (new `taskId`, same history —
+     * the worker's replay is deterministic), and a late decision for the old turn is dropped. Each
+     * run-scoped beat pushes the deadline forward (throttled to one write per half window), so a worker
+     * still replaying a long turn is never re-driven. For an INLINE executor (one that returns its
+     * decision in-process) a lapsed window releases the run lease and leaves the run to crash recovery
+     * instead of failing it. A `RemoteWorkflowExecutor`'s own `timeoutMs` is the per-workflow version of
+     * this window; when both are set the shorter wins. Unset (the default) waits for the decision with
+     * no deadline.
+     */
+    remoteAdvanceSilenceMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -264,6 +315,14 @@ export interface WorkflowEngineDeps {
      * rule matching a run wins, since every rule is applied.
      */
     retentionPolicies?: ScopedRetentionPolicy[] | undefined;
+    /**
+     * The fleet-default dead-letter workflow: a run that goes `dead` (past `maxRecoveryAttempts`) is
+     * handed to it — started with a {@link DeadLetter} input under the run id `dlq:<deadRunId>`, in the
+     * dead run's namespace. A workflow's own `deadLetterWorkflow` (register option / static config)
+     * wins. Idempotent by that run id, so a run dead-lettered twice is handled once. A handler run
+     * (`dlq:…`) that itself goes dead is not routed again.
+     */
+    deadLetterWorkflow?: WorkflowRef | undefined;
     /**
      * How long an in-flight run must sit untouched — with the stranded signature (a wake-forever
      * suspension, or an old pending remote step whose worker heartbeat is silent) — before the
@@ -307,7 +366,7 @@ export interface WorkflowEngineDeps {
      * How long (ms) a run parked `blocked` (no capable/compatible worker, design §7.5) waits before the
      * blocked-recovery poll re-drives it to re-check the live fleet. Default 5000. The run proceeds the
      * moment a capable+compatible worker appears on the next poll; a lower value trades broker SCANs for
-     * faster pickup.
+     * faster pickup. A non-finite or sub-1 value falls back to the default.
      */
     blockedPollMs?: number | undefined;
     /**
@@ -350,11 +409,21 @@ export declare class WorkflowEngine {
     /** Whether the worker tick fires {@link schedules} (the `persistedSchedules` option). */
     readonly persistedSchedulesEnabled: boolean;
     private readonly leaseMs;
+    /**
+     * The engine clock when this instance was constructed. Every lease THIS incarnation writes ends at
+     * or after `bootedAt + leaseMs`; a lease held under {@link instanceId} that ends before that was
+     * written by a previous process that ran under the same id (a pod restarted after a crash) — see
+     * {@link selfReclaimable}.
+     */
+    private readonly bootedAt;
     private readonly maxRecoveryAttempts?;
     private readonly reconcileMs;
+    private readonly heartbeatPersistThrottleMs;
     private readonly timerBatchSize;
+    private readonly eventBufferTtlMs;
     private readonly remoteRedispatchMs;
     private readonly remoteRedispatchMax;
+    private readonly remoteAdvanceSilenceMs;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -400,7 +469,10 @@ export declare class WorkflowEngine {
     private readonly accumulators;
     /** In-flight remote steps awaiting a worker result, keyed by stepId. */
     private readonly pending;
-    /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+    /** Each run's step results waiting to be settled on this instance — see {@link completeRemoteResult}. */
+    private readonly resultQueues;
+    /** Per-step "reset the liveness timer" callbacks, called with the beat's worker timestamp when a
+     *  heartbeat arrives. */
     private readonly heartbeatResets;
     private readonly listeners;
     /** Step interceptors (onion middleware around real local-step execution), first = outermost. */
@@ -411,6 +483,8 @@ export declare class WorkflowEngine {
     private readonly enqueuedListeners;
     /** Notified when a run is dead-lettered (moved to `dead`) — a hook for a DLQ handler. */
     private readonly deadListeners;
+    /** The fleet-default dead-letter workflow's name — see {@link WorkflowEngineDeps.deadLetterWorkflow}. */
+    private readonly deadLetterWorkflow;
     /** Validators gating `engine.update`, keyed by `<workflow>:<updateName>`. */
     private readonly updateValidators;
     /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
@@ -433,6 +507,20 @@ export declare class WorkflowEngine {
      * writes. `settleRun` checks this and degrades to an echo; `execute`'s finally clears the mark.
      */
     private readonly leaseLostRuns;
+    /**
+     * The lease handle of each execution in flight in this process, by run id. A path that gives the run
+     * lease away mid-execution on purpose (a remote turn suspending on its dispatched decision, see
+     * {@link releaseTurnLease}) flags it, so the execution's renew loop stops renewing and never reads its
+     * own release as a takeover: a late `false` renew would otherwise fence whoever applies the decision.
+     */
+    private readonly executionLeases;
+    /** Stable decision handler subscribed on every remote executor's transport (see registerRemote). */
+    private readonly decisionHandler;
+    /** Earliest clock time an awaited turn's deadline is worth reading again (`runId` → clock ms), the
+     *  read throttle for {@link rearmDecisionDeadline}. */
+    private readonly decisionDeadlineRearms;
+    /** Whether any registered remote executor carries its own turn window (`decisionTimeoutMs`). */
+    private anyDecisionTimeout;
     /**
      * The in-process execution gate, by run id: the execution of the run currently in flight in THIS
      * process (`tail`), and at most one resume queued behind it (`queued`). See {@link resumeRun}.
@@ -456,6 +544,10 @@ export declare class WorkflowEngine {
      */
     private readonly postSettle;
     private draining;
+    /** Shutdown wait already spent before/alongside {@link drain} (see {@link beginDrain}). */
+    private drainSpentMs;
+    /** Re-arms the deadline of every {@link drain} currently waiting, when more wait is reported. */
+    private readonly drainRearms;
     constructor(deps: WorkflowEngineDeps);
     /**
      * Register a **durable entity** (a virtual object): a keyed actor whose `handlers` run **serialized
@@ -511,6 +603,18 @@ export declare class WorkflowEngine {
     /** Send an operation to an entity (fire-and-forget). Ordered + exactly-once per key. */
     signalEntity(name: string, key: string, op: string, arg?: unknown): Promise<void>;
     /** Read an entity's current durable state (published after each op), or undefined if it has none yet. */
+    /**
+     * The entity lost-wake reconcile: wake (start, if need be) every entity that has ops sitting in its
+     * buffer, up to `limit` of them. A workflow-side send stores the op and THEN wakes the entity, so a
+     * process that dies in between leaves the op buffered while the entity sleeps; this pass is what
+     * applies it. Idempotent — a wake carries a no-op nudge, and the entity reads its buffer in arrival
+     * order, consuming each op once (an op with a stable id is skipped if already applied). The worker
+     * tick runs it, throttled to one pass a minute. Returns how many entities were woken. A no-op on a
+     * store without `listBufferedSignalTokens`.
+     */
+    reconcileEntityWakes(limit?: number): Promise<number>;
+    /** {@link reconcileEntityWakes}, at most once a minute — the worker tick's entry point. */
+    sweepEntityWakes(now?: number): Promise<number>;
     getEntityState<S = unknown>(name: string, key: string): Promise<S | undefined>;
     /**
      * Be notified when a run is enqueued on ANOTHER instance (via the control plane), so a worker can
@@ -532,6 +636,10 @@ export declare class WorkflowEngine {
         concurrency?: ConcurrencyConfig | undefined;
         executionTimeout?: string | number | undefined;
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+        /** Standard Schema validated at start, before `validateInput` — see `RegisteredWorkflow.inputSchema`. */
+        inputSchema?: StandardSchemaV1 | undefined;
+        /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
+        searchAttributesSchema?: SearchAttributesSchema | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
         requires?: string[] | undefined;
@@ -539,6 +647,8 @@ export declare class WorkflowEngine {
         origin?: string | undefined;
         /** Handler workflows a matching failure is routed to — see {@link OnErrorRoute}. */
         onError?: OnErrorRoute[] | undefined;
+        /** Where a `dead` run of this workflow is handed (overrides the engine's default). */
+        deadLetterWorkflow?: WorkflowRef | undefined;
     }): void;
     /**
      * Register a workflow whose body runs in another SDK (e.g. Python). The engine owns the run exactly
@@ -554,18 +664,37 @@ export declare class WorkflowEngine {
         concurrency?: ConcurrencyConfig;
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
+        /** Standard Schema validated at start, before `validateInput` — see `RegisteredWorkflow.inputSchema`. */
+        inputSchema?: StandardSchemaV1;
         requires?: string[];
         /** Handler workflows a matching failure is routed to — see {@link OnErrorRoute}. */
         onError?: OnErrorRoute[];
+        /** Where a `dead` run of this workflow is handed (overrides the engine's default). */
+        deadLetterWorkflow?: WorkflowRef;
     }): void;
     /**
-     * Convention-dispatch resolution: when `name` isn't locally registered but a LIVE worker group of
-     * the same name exists, auto-register a remote workflow routed to that group (bare group, no
-     * partition) so its runs advance over the broker like any `registerRemote`'d one. Always on — the
-     * queue name IS the routing, exactly as the aviary engine does — so a Python/NestJS/thin-worker
-     * workflow is reached by NAME with no `registerRemote` boilerplate. Returns whether `name` is
-     * registered afterwards. A no-op (returns `false`) when no transport is wired (nothing to route
-     * over) or no matching worker group is live (then `start`/`resume` throws `is not registered`).
+     * Register a workflow whose body runs in another SDK, routed to worker `group` — {@link
+     * registerRemote} with the executor built for you over this engine's primary transport. `version`
+     * defaults to `'1'`; register `name` at a version explicitly to pin starts to it
+     * ({@link StartOptions.version}).
+     */
+    remote(name: string, opts: Omit<Parameters<WorkflowEngine['registerRemote']>[2], 'executor'> & {
+        version?: string | undefined;
+    }): void;
+    /**
+     * Convention-dispatch resolution: when `name` isn't locally registered but a LIVE worker group for
+     * it exists, auto-register a remote workflow routed to that group so its runs advance over the
+     * broker like any `registerRemote`'d one. Always on — the queue name IS the routing, exactly as the
+     * aviary engine does — so a Python/NestJS/thin-worker workflow is reached by NAME with no
+     * `registerRemote` boilerplate. Returns whether `name` is registered (and routable for `namespace`)
+     * afterwards. A no-op (returns `false`) when no transport is wired (nothing to route over) or no
+     * matching worker group is live (then `start`/`resume` throws `is not registered`).
+     *
+     * TENANT-AWARE, per run: the group is the one the RUN's namespace routes to,
+     * `<name>@<namespace>` (bare for an absent/`default` namespace) — the token a tenant worker
+     * (`partition: <tenant>`) serves, and the same rule steps follow ({@link stepGroup}). So an operator
+     * starting a tenant's run reaches the tenant's live `<name>@<tenant>` group, not the bare one, and a
+     * convention workflow is re-checked for the namespace of every start.
      */
     private ensureConventionWorkflow;
     /**
@@ -579,7 +708,7 @@ export declare class WorkflowEngine {
     private readonly heartbeatPersists;
     /**
      * Persist a worker heartbeat on its step's checkpoint (see {@link StepCheckpoint.lastHeartbeatAt}),
-     * best-effort and THROTTLED per step (≥10s between writes) — beats may arrive every few seconds
+     * best-effort and THROTTLED per step (≥ `heartbeatPersistThrottleMs`, default 10s, between writes) — beats may arrive every few seconds
      * from a hot batch loop, and liveness observability must not turn into a per-item UPDATE storm.
      * One exemption: a beat CARRYING progress punches through when the last persisted one had none —
      * the automatic pickup beat lands first (no payload) and must not shadow the handler's first real
@@ -596,6 +725,22 @@ export declare class WorkflowEngine {
      * never defer (in-process transports, or a broker transport left eager).
      */
     startConsumers(): void;
+    /**
+     * Serve a step body by name on this engine's primary transport — the same
+     * `transport.handle(name, fn)` the provider calls for every `stepsPath` handler. It makes the
+     * engine a {@link import('./step-discovery.js').StepServer}, so app code can serve steps from an
+     * extra directory without reaching for the (provider-private) transport:
+     *
+     * ```ts
+     * // start/durable.ts (a preload)
+     * import engine from '@adonis-agora/durable/services/main'
+     * import { registerStepsFromDir } from '@adonis-agora/durable'
+     * await registerStepsFromDir(engine, app.makePath('app/engine/steps'))
+     * ```
+     *
+     * Throws when no transport is wired or the wired one can't serve handlers (no `handle`).
+     */
+    handle(name: string, fn: StepHandler): void;
     /** Subscribe to lifecycle events. Returns an unsubscribe function. */
     subscribe(listener: EngineListener): () => void;
     /**
@@ -628,6 +773,15 @@ export declare class WorkflowEngine {
      */
     onDead(listener: (run: WorkflowRun) => void): () => void;
     private notifyDead;
+    /**
+     * Hand a `dead` run to its dead-letter workflow, when one is configured: the workflow's own
+     * `deadLetterWorkflow`, else the engine's default. Started as `dlq:<runId>` (idempotent: a run
+     * dead-lettered twice is handled once; the dashboard links the pair by that id) in the dead run's
+     * namespace, with a {@link DeadLetter} input. Tracked, so a drain waits for the start; a failure
+     * (e.g. the handler is not registered here) is warned, never thrown into recovery. A handler run
+     * that itself goes dead is not routed again — no `dlq:dlq:…` chain.
+     */
+    private routeDeadLetter;
     /** 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. */
     private emit;
@@ -681,6 +835,20 @@ export declare class WorkflowEngine {
     runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /** List a run's step checkpoints (its timeline). Part of the engine's read API; see {@link listRuns}. */
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    /**
+     * How the runs matching `query` split across `(status, origin)`, in one aggregate when the store
+     * has {@link StateStore.runFacets} (else counted over a listing). Part of the engine's read API.
+     */
+    runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * A run's detail (see `loadRunDetail`), built from the store's checkpoint aggregates when it has
+     * `checkpointStats` + `queryCheckpoints` — a summarized detail then reads a few rows per wide fan
+     * instead of the whole history, and carries an `etag` that `options.ifNoneMatch` can match.
+     */
+    getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /** One page of a summarized fan's members (see `loadFanMembers`), versioned like {@link getRunDetail}. */
+    getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
+    private detailSource;
     /**
      * Hard-delete a run and its whole child subtree from the store, returning the number of runs
      * removed (0 if `runId` is unknown). Children are collected BEFORE this run's checkpoints are
@@ -720,6 +888,21 @@ export declare class WorkflowEngine {
      * parents.
      */
     sweepRetention(now?: number): Promise<number>;
+    /**
+     * The {@link eventBufferTtlMs} prune: delete buffered events older than the TTL, a bounded batch
+     * at a time, through the store's `pruneBufferedEvents`. Runs in {@link sweepRetention}'s pass.
+     * Best-effort — a failure is warned and retried on the next pass.
+     */
+    private pruneExpiredBufferedEvents;
+    /**
+     * Delete the runs `rootIds` and their child subtrees: the ids are collected children-first (the
+     * edge is read from the parent's checkpoints, so before anything is deleted), deleted in one
+     * {@link deleteRunIds} batch, then each one's token-keyed buffered signals are swept like
+     * {@link deleteRun} does. Returns how many runs were deleted.
+     */
+    private deleteRunTrees;
+    /** Bulk-delete through the store's `deleteRuns`, or one `deleteRun` per id when it has none. */
+    private deleteRunIds;
     deleteRun(runId: string): Promise<number>;
     /**
      * Sweep a deleted run's token-keyed buffered signals — they are not run-scoped rows, so the store's
@@ -807,7 +990,15 @@ export declare class WorkflowEngine {
     private recheckStepFans;
     /** {@link StateStore.countCheckpoints} of `pending` steps, or a JS count on a store without it. */
     private countPendingSteps;
-    /** Track an in-flight execution so {@link drain} can wait for it. */
+    /**
+     * Track an in-flight execution so {@link drain} can wait for it.
+     *
+     * The bookkeeping chain must not re-raise: `p.finally(...)` returns a NEW promise that rejects
+     * whenever `p` does, and nothing awaits it. So a turn whose store write failed (a dropped
+     * connection, a missing table) became a process-level unhandled rejection even though the caller
+     * awaiting `p` handled the very same error — fatal under Node's default `--unhandled-rejections`.
+     * The rejection is reported once, to the caller that owns `p`.
+     */
     private track;
     /**
      * Track a post-settle side effect (parent notify, singleton wake) so {@link drain} waits for it,
@@ -822,8 +1013,14 @@ export declare class WorkflowEngine {
      * (and their per-run lock loops) start nothing once this is called, and {@link runOne} refuses
      * broker-delivered runs. Runs already started finish. {@link drain} calls it first; the worker loop
      * calls it the moment a stop is requested, so a tick still in flight stops leasing a backlog.
+     *
+     * `spentMs` is wait time ALREADY spent on this shutdown (the worker loop waiting for its in-flight
+     * tick). It is deducted from the budget of a later {@link drain}, so that wait plus the drain stay
+     * within one `drainTimeoutMs`; a drain already waiting is shortened. Only time actually spent
+     * waiting is charged, and reports add up. Non-finite or negative values are ignored, so one bad
+     * report can't turn every later drain into a 0 ms wait.
      */
-    beginDrain(): void;
+    beginDrain(spentMs?: number): void;
     /** True once {@link beginDrain} (or {@link drain}) has been called. */
     isDraining(): boolean;
     /**
@@ -844,8 +1041,14 @@ export declare class WorkflowEngine {
      * process is going away, so a held lease would only delay the next pod's `recoverIncomplete` until
      * expiry; after release the next pod replays deterministically (a pending step re-dispatches the same
      * `stepId`, idempotent by the durable contract; a completed step short-circuits).
+     *
+     * `timeoutMs` is the TOTAL shutdown budget: wait already reported through {@link beginDrain}
+     * (`spentMs`) is deducted, so a worker that first waited for its in-flight tick drains only for
+     * what is left. With nothing reported, the full `timeoutMs` applies.
      */
     drain(timeoutMs?: number): Promise<void>;
+    /** The {@link drain} wait loop, bounded by `timer`. */
+    private drainUntil;
     /**
      * Best-effort release of the recovery locks still held by in-flight executions. Called on `drain()`
      * return so a shutting-down process hands off fast. Never throws (swallowed per-run).
@@ -862,6 +1065,33 @@ export declare class WorkflowEngine {
      * replay from their checkpoints, so only the work that had not finished runs again.
      */
     recoverIncomplete(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Whether a lease held under this engine's own {@link instanceId} was left behind by a previous
+     * process that ran under the same id, rather than held by this one. Both must hold:
+     *  - nothing in this process executes the run: no execution in its run gate and no execution lease
+     *    tracked for it;
+     *  - the lease was written before this engine booted: every lease this process writes (acquire or
+     *    renew) ends at `clock() + leaseMs >= bootedAt + leaseMs`, so an earlier end proves an earlier
+     *    writer. This also covers the brief windows where a path of this process holds the lease
+     *    without having entered the run gate yet (a sweep between `tryLockRun` and the resume).
+     *
+     * Sound only when no two LIVE processes share an instance id — the documented requirement.
+     */
+    private selfReclaimable;
+    /**
+     * Release a lease this instance's previous incarnation left on `listed` (see {@link selfReclaimable}),
+     * so the recovery sweep can take the run like any orphan. The release runs inside the run's
+     * in-process gate, so a resume landing meanwhile here queues behind it instead of executing on the
+     * lease being given up; the run is re-read there and only released if it is still a stale `running`
+     * self-lease. Returns whether the lease was released.
+     */
+    private releaseStaleSelfLease;
+    /**
+     * The remote step this run dispatched and still awaits a result for, if any — the durable marker
+     * that tells {@link recoverIncomplete} "this run's work is on the transport, not in a crashed
+     * process". A `pending` remote checkpoint is written before the dispatch and settled by the result.
+     */
+    private inFlightRemoteStep;
     /**
      * Per-recovery bookkeeping (called once the lease is held): count the attempt, or — past
      * `maxRecoveryAttempts` — move a poison pill to the `dead` dead-letter state. Returns a terminal
@@ -904,8 +1134,9 @@ export declare class WorkflowEngine {
      * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
      * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
      * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
-     * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
-     * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+     * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` parks a run with an
+     * in-flight `pending` remote step back to `suspended` instead of re-driving it, and `requeue` just
+     * replays back to the pending guard. This re-enqueues the same `stepId` so the
      * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
      * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
      * run's current status (with the count re-dispatched), or null if the run is unknown.
@@ -946,6 +1177,12 @@ export declare class WorkflowEngine {
     /**
      * Resume each run only if this instance can acquire its recovery lease — so when several
      * replicas recover or poll at once, each run is picked up by exactly one of them.
+     *
+     * A run this instance cannot resume is SKIPPED (and logged), never allowed to abort the batch: a
+     * leased batch is a mixed bag during a rolling deploy (a pod without a run's workflow throws for
+     * it by design) and a store hiccup can fail one row, but the rest of the batch is runs it can drive
+     * — and every caller is a recovery/poll sweep. The skipped run stays locked only until its lease
+     * expires, then another instance (or a later tick) picks it up.
      */
     private resumeLeased;
     /**
@@ -1021,6 +1258,13 @@ export declare class WorkflowEngine {
      * side's write, and the destructive `take*` ops arbitrate so a signal is never delivered twice.
      */
     signal(token: string, payload: unknown): Promise<RunResult | null>;
+    /**
+     * Wake the run parked on `token` with `payload`, if there is one; otherwise do nothing — unlike
+     * {@link signal}, it never buffers. For a wake-up whose real payload is ALREADY buffered on the
+     * token (an entity op, see `Entities.kick`): a run that isn't parked reads that buffer at its next
+     * wait, so there is nothing to keep.
+     */
+    private wakeSignalWaiter;
     /**
      * Ensure a run exists for `runId`, then deliver a signal to it — atomically race-free thanks to
      * signal buffering: if the run is new (or busy / not yet waiting), the signal is buffered and
@@ -1131,6 +1375,21 @@ export declare class WorkflowEngine {
      * the full listing for a store without one.
      */
     countRuns(query: Omit<RunQuery, 'page' | 'size'>): Promise<number>;
+    /**
+     * Every workflow the live fleet can execute in this engine's partition: what workers DECLARE in
+     * their descriptors, plus the live routing tokens no descriptor explains (a worker too old to
+     * describe itself). Each entry says which kind of evidence it rests on. See
+     * {@link workflowDirectory} for why the list is the length it is.
+     */
+    announcedWorkflows(): Promise<AnnouncedWorkflow[]>;
+    /**
+     * {@link announcedWorkflows}, plus why it is empty when it is: no transport here can read the fleet
+     * (`supported: false`), nothing is live, or workers are live only on OTHER partitions
+     * (`otherPartitions`), which otherwise reads exactly like an empty fleet. Two live reads, neither
+     * retained: the descriptor advertisement and the heartbeat keyspace. Only the BullMQ transport reads
+     * them today.
+     */
+    workflowDirectory(): Promise<WorkflowDirectory>;
     /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
      *  `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
      *  workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
@@ -1140,7 +1399,7 @@ export declare class WorkflowEngine {
      *  (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
      *  groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
      *  from registrations, shows once its workers beat). Empty when no transport can introspect health
-     *  (only the BullMQ transport implements `groupHealth`). */
+     *  (only the BullMQ, queue and db transports implement `groupHealth`). */
     workerHealth(extra?: string[]): Promise<GroupHealth[]>;
     /**
      * Persist a streamed local-step lifecycle event from a remote workflow worker (see
@@ -1231,7 +1490,101 @@ export declare class WorkflowEngine {
      * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
      */
     private reconcileWakeAt;
+    /**
+     * The result of a turn the singleton gate denied. The store already parked the run `suspended` on
+     * its retry timer INSIDE the admission claim (or left it alone, when a concurrent cancel had
+     * settled it), so report what is persisted rather than writing over it.
+     */
+    /**
+     * A run's first execution: `pending` -> `running`. A singleton run not yet admitted is stamped
+     * {@link SINGLETON_TRACKED_TAG} in the same write, BEFORE it competes for a slot, so a run this
+     * replica is about to admit or deny is never mistaken for a holder admitted by a replica older than
+     * 0.51 (see `legacySingletonHolders`).
+     */
+    private markStarted;
+    private singletonWaitResult;
     private runRemoteExecution;
+    /**
+     * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then settle
+     * (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by the
+     * INLINE advance path ({@link runRemoteExecution}, under the execution's lease) and the dispatched
+     * path ({@link completeRemoteDecision}, which holds the lease itself and has already checked that
+     * this is the decision of the turn the run awaits).
+     */
+    private applyDecision;
+    /**
+     * The dispatched-turn path of {@link runRemoteExecution}: SUSPEND, then ENQUEUE. The engine mints a
+     * globally unique turn `taskId`, records it on the run as the awaited marker, and releases the lease,
+     * all BEFORE the turn is enqueued, so a worker's decision, however fast and on whichever replica it
+     * lands, always finds both its marker and a free lease (see {@link completeRemoteDecision}). The
+     * deadline is the turn's liveness window ({@link decisionWindowMs}); when it lapses with no decision
+     * and no run-scoped heartbeat, the timer poller re-drives the run, which dispatches a fresh turn.
+     */
+    private dispatchRemoteTurn;
+    /**
+     * The turn could not be enqueued (the transport cannot carry workflow turns, or the broker refused the
+     * write): fail the run, as an advance that throws does — but only while it still awaits THIS turn, so
+     * a cancel or a re-drive that landed meanwhile wins.
+     */
+    private failUndispatchedTurn;
+    /**
+     * Give the run lease away mid-execution on purpose: stop the execution's renew loop from renewing it
+     * (or reading the release as a takeover), then release it. Owner-scoped, so a lease another instance
+     * already holds is left alone.
+     */
+    private releaseTurnLease;
+    /**
+     * The liveness window of a dispatched turn: the engine's `remoteAdvanceSilenceMs` and the executor's
+     * own `decisionTimeoutMs` (a `RemoteWorkflowExecutor`'s `timeoutMs`), the shorter of the two when both
+     * are set. `undefined` = no deadline: the run waits for its decision.
+     */
+    private decisionWindowMs;
+    /**
+     * Await an INLINE advance, rejecting with {@link RemoteWorkflowTimeout} once `silenceMs` passes with
+     * neither a decision nor a run-scoped heartbeat for `runId`. Each beat rearms the window. The beat
+     * hook is registered before this returns, so a beat can't slip in unseen.
+     */
+    private awaitTurnWithSilence;
+    /** Whether `run` is awaiting exactly `decision`'s turn (and so may still apply it). */
+    private awaitsDecision;
+    /**
+     * Apply a remote workflow-turn {@link WorkflowDecision} durably, on WHICHEVER replica consumes it: the
+     * dispatching replica may be gone, or a point-to-point decisions queue handed the decision to a
+     * sibling. The durable twin of {@link completeRemoteResult} for a workflow TURN: look the run up by
+     * `decision.runId`, check that it still awaits this `taskId` (a stale, duplicate, foreign or
+     * superseded decision is dropped, so a decision applies at most once), lease it, and apply it.
+     * Serialized with this replica's own executions of the run through the run gate.
+     */
+    private completeRemoteDecision;
+    /**
+     * Run `fn` in the run's in-process execution gate (see {@link resumeRun}): after the execution in
+     * flight here, before any resume that lands later. A resume already queued (not started) runs first.
+     */
+    private serializeOnRun;
+    /** {@link completeRemoteDecision} inside the run gate: lease, re-check, claim the turn, apply. */
+    private applyRemoteDecision;
+    /**
+     * Acquire the run lease to apply `decision`. The dispatcher released it before enqueueing, so this
+     * normally succeeds at once; another replica may still hold it briefly (its wake found the turn in
+     * flight and is releasing), so retry until the lease frees, the run stops awaiting this turn, or one
+     * lease window passes (a crashed holder's lease expires within it). A lease THIS instance holds is
+     * reused: we are inside the run gate, so no execution of it is running here.
+     */
+    private leaseForDecision;
+    /**
+     * A run-scoped heartbeat for a run awaiting a dispatched turn's decision: push its re-drive deadline
+     * (`wakeAt`) forward so a worker still replaying the turn is not re-driven. The durable counterpart
+     * of an inline advance's in-memory rearm, and the run-scoped sibling of {@link rearmStepLease}.
+     *
+     * Throttled the same way: a renewal buys at most one window, so it is only worth a write once the
+     * window is half spent. A beat that finds more than half of it left writes nothing and records the
+     * half-spent mark, so later beats skip even the read until then. That bounds the cost at one read and
+     * one write per half window per awaited turn, whatever the beat cadence. The mark is in memory only
+     * (cold on another replica, which re-derives the same answer from the run's `wakeAt`). Best-effort:
+     * it runs inside the transport's serial beat handler, so a store error is swallowed, and the mark only
+     * moves after a write commits, so the next beat retries.
+     */
+    private rearmDecisionDeadline;
     /**
      * A polyglot workflow's re-emitted `call` whose checkpoint already exists: decide whether the step is
      * still out for delivery, or whether its dispatch was LOST and has to be re-driven. Returns the
@@ -1314,6 +1667,22 @@ export declare class WorkflowEngine {
      *  {@link redriveLostCall}). A terminal turn (completed/failed/cancelled) applies its commands only to
      *  record what already ran, and must never dispatch anything new. */
     private applyCommands;
+    /**
+     * Whether a compensating cancel is pending for this run, consuming the in-memory flag. The intent
+     * lives in TWO places: the in-memory `cancelRequested` fast path (same pod, same boot), and the
+     * DURABLE buffered `cancel:<id>` marker `cancel()` persisted — so a crash or a cross-pod handoff
+     * mid-cancellation can't silently forget the cancel. The marker is peeked (take + re-buffer), not
+     * consumed: it must survive a crash mid-unwind; {@link compensateAndCancel} drains it once
+     * `cancelled` is durably recorded.
+     */
+    private takeCancelIntent;
+    /**
+     * Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
+     * exit of a turn with a compensating cancel pending — the body returned, suspended, hit
+     * continue-as-new or threw — so the cancel is never lost because the body didn't stop at a
+     * suspension point.
+     */
+    private compensateAndCancel;
     /** The run body, lease held + renewed by {@link execute}. */
     private runExecution;
     /**
@@ -1459,7 +1828,36 @@ export declare class WorkflowEngine {
      */
     /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
     private savePendingCheckpoint;
+    /**
+     * Settle a durable step result and (barrier permitting) resume its run in the background.
+     *
+     * One run's results are settled in batches: the first starts a batch, and the ones that arrive
+     * while it is being written (with `resultConcurrency > 1`) form the next, up to
+     * {@link RESULT_BATCH_MAX}. A batch of several claims its checkpoints with one
+     * {@link StateStore.saveCheckpointsIfPending} call, asks each step fan's barrier once, and resumes
+     * the run at most once; a batch of one takes the single-result path unchanged. A result resolves
+     * only once its own write committed, so the transport acknowledges nothing that is not durable.
+     */
     private completeRemoteResult;
+    /** Settle `queue` (one run's queued results) batch by batch until it is empty, then retire it. */
+    private drainResultQueue;
+    /** The single-result path: settle `result`, then resume its run unless its fan is still running. */
+    private completeOneRemoteResult;
+    private resumeInBackground;
+    /**
+     * Settle a batch of one run's step results; per result, `true` (settled or dropped) or the error
+     * that kept it from settling, which the transport then redelivers. Same outcome per result as
+     * {@link completeOneRemoteResult} on each in turn, with one resume for the batch: that resume
+     * replays every write of the batch, so a second would only replay it again.
+     */
+    private completeRemoteResults;
+    /**
+     * {@link savePendingCheckpoint} for checkpoints at distinct seqs: one
+     * {@link StateStore.saveCheckpointsIfPending} call when the store has it, else one write each.
+     * Never rejects as a whole: a failed write is reported as that entry's error, and the batch call
+     * rejecting means it wrote nothing, so the entries are then written one by one.
+     */
+    private savePendingCheckpoints;
     /**
      * The join barrier of a step fan: a result for one of its steps resumes the parent only once no
      * step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a