@dudousxd/nestjs-durable-core 0.78.0 → 0.80.0

package/dist/index.d.ts

@@ -195,6 +195,16 @@ interface WorkflowRegistration {
     /** The package that DECLARED the workflow (see `WorkflowRun.origin`). Absent = unknown; nothing
      *  ever substitutes a default, because a wrong origin is worse than no origin. */
     origin?: string;
+    /**
+     * Where the engine routes a failed run of this workflow, by error `code` (`code` absent = the
+     * catch-all): the handler workflow it starts instead of failing the run. The one announced field
+     * the engine ACTS on, for a workflow it serves by convention rather than by local registration.
+     * Absent = not stated, which routes nothing.
+     */
+    onError?: {
+        code?: string;
+        workflow: string;
+    }[];
 }
 /**
  * A worker's (or control-plane's) advertised identity, wire-protocol support, feature capabilities
@@ -509,16 +519,28 @@ interface FanPage {
     items: StepCheckpoint[];
     /** Members matching the query, across all pages. */
     total: number;
+    /** A validator for this page, when the gateway can compute one without reading the members. */
+    etag?: string | undefined;
+    /**
+     * Set when the query's `ifNoneMatch` matched {@link etag}: the page has not changed, so nothing
+     * was read. `items` is empty and `total` is 0 as placeholders, not the fan's; keep the page the
+     * caller already holds.
+     */
+    notModified?: true | undefined;
 }
 interface FanPageQuery {
     offset?: number | undefined;
     limit?: number | undefined;
     /** Only failed members (a failed step, or a child that failed). */
     failedOnly?: boolean | undefined;
+    /** An HTTP `If-None-Match` value: a page whose `etag` it names comes back `notModified`. */
+    ifNoneMatch?: string | undefined;
 }
 declare const FAN_SUMMARY_FAILURES = 20;
 /** The most children a summarized detail lists by id; `childCount` carries the rest. */
 declare const SUMMARY_CHILD_LIMIT = 200;
+/** How many children a folded `fan:` checkpoint stands for; undefined for any other checkpoint. */
+declare function foldedCount(cp: StepCheckpoint): number | undefined;
 /** A failed member: a failed step, or a child whose completion reports `ok: false`. */
 declare function isFailedMember(cp: StepCheckpoint): boolean;
 /** Summarize one fan's members (in seq order). */
@@ -534,6 +556,11 @@ declare function summarizeTimeline(timeline: StepCheckpoint[], over: number): {
 };
 /** One page of a fan's members out of a run's timeline. */
 declare function pageFan(timeline: StepCheckpoint[], group: string, query: FanPageQuery): FanPage;
+/** A {@link FanPageQuery}'s offset and limit, clamped to sane bounds. */
+declare function fanPageBounds(query: FanPageQuery): {
+    offset: number;
+    limit: number;
+};
 
 /** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
  *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
@@ -566,6 +593,16 @@ interface RunDetail {
     fans?: FanSummary[] | undefined;
     /** How many children the run has, when `children` lists only the first of them. */
     childCount?: number | undefined;
+    /**
+     * A validator for this detail, when the gateway can compute one without reading the timeline:
+     * it changes whenever the run or any of its checkpoints does. Absent when it cannot.
+     */
+    etag?: string | undefined;
+    /**
+     * Set when {@link RunDetailOptions.ifNoneMatch} matched {@link etag}: nothing changed, so only
+     * `run` was read — `timeline` and `children` are empty, not the run's.
+     */
+    notModified?: true | undefined;
 }
 /** How to shape a {@link RunDetail}. */
 interface RunDetailOptions {
@@ -575,6 +612,11 @@ interface RunDetailOptions {
      * with a wide fan should set it: the full detail of a 40k-member fan is megabytes.
      */
     summarizeFansOver?: number | undefined;
+    /**
+     * An HTTP `If-None-Match` value. When it names the detail's current {@link RunDetail.etag}, the
+     * gateway answers `notModified` without reading the timeline. A gateway that cannot tell ignores it.
+     */
+    ifNoneMatch?: string | undefined;
 }
 /**
  * Maps every `Date` (and `Date | undefined`) field of `T` to its ISO-string wire form — the shape a
@@ -1101,6 +1143,9 @@ interface StepError {
     message: string;
     /** Optional machine-readable code, e.g. `declined`, `timeout`. */
     code?: string | undefined;
+    /** Structured, JSON-serializable detail of the failure (e.g. validation issues), from
+     *  `FatalError`'s third argument or a `details` on what a step handler threw. */
+    details?: unknown;
     /** Whether the engine should treat this as retryable. */
     retryable?: boolean | undefined;
     stack?: string | undefined;
@@ -1124,6 +1169,21 @@ interface StateStore {
     tryAdmitSingleton?(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    /**
+     * {@link updateRun}, but only if the run's CURRENT status is one of `expectedStatuses`: a
+     * compare-and-set on the status. Resolves whether the patch applied; never throws on a mismatch or
+     * a missing run (both resolve `false`). The engine settles a turn's outcome (completed, failed,
+     * suspended, blocked) through it, so a run that reached `cancelled`/`completed`/`dead` through
+     * another path while the turn executed (an operator's `cancel()`, a timeout sweep, a dead-letter)
+     * is never overwritten by the turn's stale outcome.
+     *
+     * For a SQL store the predicate must be part of the `UPDATE ... WHERE` itself; a read-then-write
+     * in application code reintroduces the race this exists to close.
+     *
+     * Optional: a store that omits it gets the engine's read-then-write fallback, which narrows the
+     * race to the gap between that read and the write but cannot close it.
+     */
+    updateRunIf?(runId: string, expectedStatuses: RunStatus[], patch: Partial<WorkflowRun>): Promise<boolean>;
     getRun(runId: string): Promise<WorkflowRun | null>;
     /**
      * Hard-delete a run and all of its rows — the run plus its checkpoints, signal waiters, and
@@ -1171,8 +1231,28 @@ interface StateStore {
      * Optional: a store that omits it falls back to {@link saveCheckpoint}, which keeps that race.
      */
     saveCheckpointIfPending?(checkpoint: StepCheckpoint): Promise<boolean>;
+    /**
+     * {@link saveCheckpointIfPending} for many checkpoints in one call: resolves, per entry and in
+     * input order, whether it wrote. Same result as calling it on each entry in turn (a later entry for
+     * the same `(runId, seq)` is compared against the earlier one's write), with each row's
+     * compare-and-set still atomic. The call as a whole is atomic too: if it rejects, nothing was
+     * written. The engine settles a batch of one run's step results through it, one call per batch.
+     *
+     * Optional: a store that omits it gets one {@link saveCheckpointIfPending} per entry.
+     */
+    saveCheckpointsIfPending?(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    /**
+     * The ORPHANS a periodic recovery pass should reclaim: {@link listIncompleteRuns}'s runs
+     * (`running` or `cancelling`) whose lease is free (`lockedUntil` unset or `<= nowMs`), oldest
+     * (`createdAt`) first, at most `limit`. When `namespace` is given, restricted to that partition.
+     *
+     * Optional but recommended: without it the engine lists every incomplete run and filters the
+     * leases in process, which on a busy fleet reads every healthy running run once per tick per
+     * worker.
+     */
+    listOrphanedRuns?(nowMs: number, limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /**
@@ -1380,6 +1460,72 @@ interface StateStore {
      * and counts in JS, which loads the whole run on every result of a fan.
      */
     countCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
+    /**
+     * The run's checkpoints aggregated into {@link CheckpointStat} buckets — one per
+     * `(parallelGroup, status, nameKind)` present — with `opts.group` narrowing it to one group. A
+     * `GROUP BY`, not a load: it is what lets a run detail draw a 40,000-member fan from a few rows.
+     * Ungrouped checkpoints come back under `group: null`. Bucket order is unspecified.
+     *
+     * Optional: a store that omits it still works — the console's run detail then loads every
+     * checkpoint and summarizes it in JS (`summarizeTimeline`), which is the same answer read the
+     * expensive way. A store that implements it must implement {@link queryCheckpoints} too.
+     */
+    checkpointStats?(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /**
+     * The run's checkpoints that match `query`, in `seq` order (the order of {@link listCheckpoints}),
+     * paged by `offset`/`limit`. Every filter is optional; an absent one does not narrow. An EMPTY
+     * `statuses` or `namePrefixes` matches nothing; an empty `excludeGroups` excludes nothing.
+     *
+     * Optional, paired with {@link checkpointStats}: the run detail reads a fan's failures, its folded
+     * checkpoints and one page of its members through it, instead of the run's whole history.
+     */
+    queryCheckpoints?(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
+}
+/**
+ * How a checkpoint's name classifies it, for {@link CheckpointStat}: an awaited child's
+ * `signal:child:` checkpoint, a folded `fan:` checkpoint standing for many children, a `spawn:`
+ * edge to a fire-and-forget child, or any other step.
+ */
+type CheckpointNameKind = 'child' | 'folded' | 'spawn' | 'step';
+/** The {@link CheckpointNameKind} of a checkpoint name — what a store's SQL `CASE` must agree with. */
+declare function checkpointNameKind(name: string): CheckpointNameKind;
+/**
+ * One bucket of {@link StateStore.checkpointStats}: the checkpoints of one run sharing a
+ * `parallelGroup`, a `status` and a {@link CheckpointNameKind}, reduced to aggregates.
+ */
+interface CheckpointStat {
+    /** The bucket's `parallelGroup`, or `null` for ungrouped checkpoints. */
+    group: string | null;
+    status: StepCheckpoint['status'];
+    nameKind: CheckpointNameKind;
+    /** Rows in the bucket (at least 1). */
+    count: number;
+    minSeq: number;
+    maxSeq: number;
+    /** Smallest and largest `name`, by the database's string order. Equal when every row shares one. */
+    minName: string;
+    maxName: string;
+    /** Earliest `enqueuedAt`, read as {@link StateStore.listCheckpoints} reads it (falling back to `startedAt`). */
+    minEnqueuedAt: Date;
+    minStartedAt: Date;
+    maxStartedAt: Date;
+    maxFinishedAt: Date;
+    /** Sum of `attempts` — moves when a step is retried in place, so a change marker sees it. */
+    sumAttempts: number;
+}
+/** What {@link StateStore.queryCheckpoints} selects. */
+interface CheckpointQuery {
+    /** Only this `parallelGroup`'s checkpoints. */
+    group?: string | undefined;
+    /** Leave out these groups' checkpoints (ungrouped checkpoints are kept). */
+    excludeGroups?: string[] | undefined;
+    statuses?: StepCheckpoint['status'][] | undefined;
+    /** Only names starting with one of these. */
+    namePrefixes?: string[] | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
 }
 /**
  * A persisted schedule as the STORE sees it: a handful of queryable columns plus two JSON documents
@@ -1705,6 +1851,26 @@ interface AllStepsOptions extends Omit<StepDispatchOpts, 'queue' | 'timeoutMs'>
      */
     concurrency?: number;
 }
+/** Options for {@link WorkflowCtx.allSettled} over child workflows: {@link AllOptions} without `mode`. */
+type AllSettledOptions = Omit<AllOptions, 'mode'>;
+/** Options for {@link WorkflowCtx.allSettled} over a `@Step`: {@link AllStepsOptions} without `mode`. */
+type AllStepsSettledOptions = Omit<AllStepsOptions, 'mode'>;
+/**
+ * One item of a {@link WorkflowCtx.allSettled} fan, in input order. `id` is the child run id (child
+ * fan) or the step id (step fan); `error` is the failure message the child or step settled with.
+ */
+type Settled<T> = {
+    status: 'fulfilled';
+    value: T;
+} | {
+    status: 'rejected';
+    id: string;
+    error: string;
+    /** The failure's `code` (e.g. a `FatalError`'s), so a parent can tell its kinds apart. */
+    code?: string | undefined;
+    /** The failure's structured `details`, when it carried any. */
+    details?: unknown;
+};
 /** One child of a fan as {@link StateStore.registerChildWaits} writes it. */
 interface ChildWait {
     waiter: SignalWaiter;
@@ -2595,6 +2761,17 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      */
     all<TInput, TOutput>(step: StepRef<TInput, TOutput>, inputs: TInput[], opts?: AllStepsOptions): Promise<TOutput[]>;
     all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: AllOptions): Promise<TOutput[]>;
+    /**
+     * {@link all} that never throws for a failed item: waits for every child (or step) to settle, then
+     * resolves with one {@link Settled} per input, in **input order** — the durable
+     * `Promise.allSettled`. Same fan as `all` in `waitAll` mode (ids, `parallelGroup`, `concurrency`
+     * waves, one parent turn per settled wave); only the ending differs. Use it when one item failing
+     * is an expected outcome the parent handles (record it, dead-letter it) rather than a reason to
+     * fail the whole run. Cancelling the parent still propagates.
+     */
+    allSettled<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: AllSettledOptions): Promise<Settled<WorkflowOutputOf<C>>[]>;
+    allSettled<TInput, TOutput>(step: StepRef<TInput, TOutput>, inputs: TInput[], opts?: AllStepsSettledOptions): Promise<Settled<TOutput>[]>;
+    allSettled<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: AllSettledOptions): Promise<Settled<TOutput>[]>;
     /**
      * Pause the run at this point until a human resumes it from the dashboard (or
      * `engine.continue(runId)`). Records a visible `pending` checkpoint so the breakpoint shows up
@@ -2687,8 +2864,8 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
     localStep<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): Promise<TOutput>;
 }
 /**
- * {@link WorkflowCtx} with ONE signature per method: the string-addressed forms of the four overloaded
- * methods (`step`, `child`, `startChild`, `all`), everything else unchanged.
+ * {@link WorkflowCtx} with ONE signature per method: the string-addressed forms of the five overloaded
+ * methods (`step`, `child`, `startChild`, `all`, `allSettled`), everything else unchanged.
  *
  * For code that drives the ctx DYNAMICALLY — an interpreter that runs a user-defined graph and only
  * ever knows workflow/step names as strings — and for test fakes. An overloaded method is awkward to
@@ -2707,7 +2884,7 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
  * Every `WorkflowCtx<A>` is assignable to `DynamicWorkflowCtx<A>` (guarded by
  * `dynamic-workflow-ctx.type-test.ts`), and a `Pick` of it is a plain object literal in a test.
  */
-interface DynamicWorkflowCtx<A extends SearchAttributes = SearchAttributes> extends Omit<WorkflowCtx<A>, 'step' | 'child' | 'startChild' | 'all'> {
+interface DynamicWorkflowCtx<A extends SearchAttributes = SearchAttributes> extends Omit<WorkflowCtx<A>, 'step' | 'child' | 'startChild' | 'all' | 'allSettled'> {
     /** {@link WorkflowCtx.step} by step name (a cross-runtime handler, or a `@Step` by its name). */
     step<TOutput = unknown, TInput = unknown>(name: string, input: TInput, opts?: StepDispatchOpts & {
         compensate?: string;
@@ -2718,6 +2895,8 @@ interface DynamicWorkflowCtx<A extends SearchAttributes = SearchAttributes> exte
     startChild(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<string>;
     /** {@link WorkflowCtx.all} by workflow name. */
     all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: AllOptions): Promise<TOutput[]>;
+    /** {@link WorkflowCtx.allSettled} by workflow name. */
+    allSettled<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: AllSettledOptions): Promise<Settled<TOutput>[]>;
 }
 /** Result of executing or resuming a workflow run. */
 interface RunResult {
@@ -2740,7 +2919,7 @@ type UpdateResult = {
     accepted: true;
     run: RunResult | null;
 };
-type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress' | 'run.blocked';
+type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress' | 'run.blocked' | 'run.routed' | 'run.unrouted';
 /**
  * A lifecycle event emitted by the engine. The observability surfaces (dashboard, OTel, the
  * Telescope integration) all subscribe to these rather than reaching into the store.
@@ -2780,6 +2959,8 @@ interface EngineEvent {
      *  gap fired, how many live workers were considered, and both descriptors — enough for the health
      *  panel/telescope to render the reason. Absent on all other event types. */
     diagnostics?: DispatchDiagnostics | undefined;
+    /** Why a `run.unrouted` run's onError routes were not applied. */
+    reason?: string | undefined;
     at: Date;
 }
 type EngineListener = (event: EngineEvent) => void;
@@ -3180,7 +3361,7 @@ interface WorkflowAnnouncement extends WorkflowRegistration {
 /** An axis on which the live announcers of one workflow do not agree. `values` holds every distinct
  *  DECLARED value (sorted); an announcer that stated nothing on the axis contributes nothing. */
 interface Disagreement {
-    axis: 'group' | 'origin' | 'requires';
+    axis: 'group' | 'origin' | 'requires' | 'onError';
     values: string[];
 }
 /**
@@ -3216,6 +3397,12 @@ interface AnnouncedWorkflow {
     /** Every distinct capability demand announced, each de-duplicated + sorted. Empty = nobody stated
      *  one. Two entries here means two workers demand different capabilities for the same version. */
     requires: string[][];
+    /** Every distinct set of `onError` routes announced, each in canonical order. Empty = nobody stated
+     *  one. Two entries here means the live workers route this workflow's failures differently. */
+    onError: {
+        code?: string;
+        workflow: string;
+    }[][];
     /** Runtimes of the live announcers (sorted, de-duplicated). EMPTY on an `'observed'` entry: a
      *  heartbeat does not say what runtime wrote it, and the instance id's shape is a convention, not
      *  a statement, so it is not read as one. */
@@ -3529,6 +3716,64 @@ type RoutingResolution = RoutableResolution | BlockedResolution;
  */
 declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
 
+/**
+ * Routes a failed run to a handler workflow instead of failing it: when a run of the workflow ends
+ * `failed` with an error whose `code` matches (or with any error, for the route without a `code`), the
+ * engine starts `workflow` with an {@link OnErrorInput} and the failed run waits for it. The run then
+ * settles with the handler's outcome: its output on success, its error on failure.
+ */
+interface OnErrorRoute {
+    /** The error `code` to route. Omitted: routes any failure no other route's `code` matches. */
+    code?: string | undefined;
+    /** The registered handler workflow's name. */
+    workflow: string;
+}
+/** The input an {@link OnErrorRoute} handler workflow is started with. */
+interface OnErrorInput<TInput = unknown> {
+    /** The run that failed; it completes with this handler's output. */
+    runId: string;
+    /** The failed run's workflow. */
+    workflow: string;
+    /** The failed run's input. */
+    input: TInput;
+    /** The failure, as the run recorded it. */
+    error: StepError;
+}
+/**
+ * Handoff checkpoints live at seqs from here up, one per handoff, so a body that runs again after a
+ * retry can never reach one. Fits a 32-bit `seq` column.
+ */
+declare const HANDOFF_SEQ_BASE = 1000000000;
+/** The id of the handler run of a run's `attempt`-th handoff. */
+declare const onErrorRunId: (runId: string, attempt: number) => string;
+/** The waiter checkpoint a run waits on its handler under; renamed {@link retiredHandoffName} on retry. */
+declare const handoffName: (handlerId: string) => string;
+/** What a retry renames a handoff checkpoint to: kept in the timeline, never followed again. */
+declare const retiredHandoffName: (handlerId: string) => string;
+/** The handler run id a live handoff checkpoint of `runId` names, or undefined for any other one. */
+declare function handoffHandlerId(runId: string, cp: {
+    seq: number;
+    name: string;
+}): string | undefined;
+/** The run's live handoff (its latest, unretired one), if it handed a failure off. */
+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. */
+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;
+/** The `code` carried by a thrown value: its own, a dispatched step's, or a thin-worker step's. */
+declare function codeOf(err: unknown): string | undefined;
+/** The `details` carried by a thrown value, from the same places as {@link codeOf}. */
+declare function detailsOf(err: unknown): unknown;
+/** `code` and `details` as optional keys, so an absent one is not written as `undefined`. */
+declare function codeAndDetails(err: unknown): {
+    code?: string;
+    details?: unknown;
+};
+
 /**
  * A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
  * runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
@@ -3749,6 +3994,18 @@ interface StartOptions {
      * workflow's registered `concurrency`. See {@link ConcurrencyQuota}.
      */
     concurrency?: ConcurrencyQuota | undefined;
+    /**
+     * Delayed start: don't execute before this time (epoch ms, or a `Date`), compared against the
+     * engine's clock. The run is created `suspended` with its `wakeAt` set to it, which is the same
+     * durable timer a `ctx.sleep` parks on: nothing is held in memory, it survives restarts, and the
+     * timer poller (`resumeDueTimers`) starts it once due, on any instance. A time that is not in the
+     * future starts the run at once, as if it were omitted.
+     *
+     * A delayed run reads `suspended` until it fires (so `start` returns `suspended`, and `waitForRun`
+     * settles on that right away), and skips the `run.started` event's `pending → running` hop. It
+     * counts as in flight for singleton back-pressure and concurrency quotas while it waits.
+     */
+    startAt?: number | Date | undefined;
 }
 /**
  * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
@@ -4042,6 +4299,8 @@ declare class WorkflowEngine {
     private readonly updateValidators;
     /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
     private readonly cancelRequested;
+    /** {@link announcedRoutes} reads, by group + workflow + version. */
+    private readonly announcedRoutesCache;
     /**
      * Seqs of the dispatched remote steps a turn suspended on, by run, while that turn executes on
      * THIS instance — so the turn can re-check them once its lease is released (see
@@ -4061,8 +4320,22 @@ declare class WorkflowEngine {
     private readonly awaitedStepFans;
     /** Step fans whose join barrier this instance opened, by `runId:firstSeq` — see {@link settledHere}. */
     private readonly stepFansFiredHere;
+    /**
+     * 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}.
+     *
+     * The run lease is keyed by engine instance, so it fences OTHER processes only: to the store, a
+     * second execution in this same process holds the very same lease (and {@link execute} skips
+     * `tryLockRun` when its snapshot says this instance holds it). Without this gate, a resume landing
+     * while this process was still executing the run (a signal, a late step result, a child wake, an
+     * explicit `resume()`) went straight past the lease and ran the body concurrently: a
+     * not-yet-checkpointed step executed twice.
+     */
+    private readonly runGates;
     /** The tail of each run's queue of results being handled on this instance — see {@link serializedPerRun}. */
     private readonly resultChains;
+    /** Each run's results waiting to be settled on this instance — see {@link completeRemoteResult}. */
+    private readonly resultQueues;
     /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
     private readonly admission;
     /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
@@ -4137,6 +4410,8 @@ declare class WorkflowEngine {
          *  when it cannot be derived with confidence: absent means UNKNOWN, and an absent origin is far
          *  cheaper to live with than a wrong one. */
         origin?: string | undefined;
+        /** Handler workflows a matching failure is routed to — see {@link OnErrorRoute}. */
+        onError?: OnErrorRoute[] | undefined;
     }): void;
     /**
      * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
@@ -4166,6 +4441,8 @@ declare class WorkflowEngine {
         validateInput?: (input: unknown) => void | Promise<void>;
         /** Capabilities a live worker must advertise to run this remote workflow's turns (handshake §7.5). */
         requires?: string[];
+        /** Handler workflows a matching failure is routed to — see {@link OnErrorRoute}. */
+        onError?: OnErrorRoute[];
     }): void;
     /**
      * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
@@ -4192,6 +4469,8 @@ declare class WorkflowEngine {
         validateInput?: (input: unknown) => void | Promise<void>;
         /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5). */
         requires?: string[];
+        /** Handler workflows a matching failure is routed to — see {@link OnErrorRoute}. */
+        onError?: OnErrorRoute[];
     }): void;
     /**
      * Register a flow-control queue referenced by `ctx.step(step, input, { queue })`. Caps concurrent
@@ -4257,7 +4536,49 @@ declare class WorkflowEngine {
      * stale waiter or a late result left behind by a failed run silently re-executes its body.
      */
     private resumeImplicit;
+    /**
+     * One execution of a run at a time in this process. A resume that lands while the run executes
+     * here neither joins that execution (the double-run) nor no-ops against its held lease (a lost
+     * wake: its checkpoint may postdate the running turn's snapshot): it is QUEUED, and re-drives the
+     * run once the running execution has settled and released its lease, re-reading the run then
+     * (terminal: echoed, never re-executed). Resumes landing while one is already queued coalesce
+     * into it: it has not started yet, so it will observe every write they made. Their callers get
+     * the queued execution's result, i.e. the run's state after their own wake was applied.
+     *
+     * Across processes, exclusion stays the lease's job: {@link execute} still `tryLockRun`s when it
+     * does not hold the lease.
+     */
     private resumeRun;
+    /** Drop `gate` once `tail` settles, unless another execution queued behind it meanwhile. */
+    private closeGateAfter;
+    /**
+     * Release a run's lease AFTER its outcome is decided (persisted, or about to be returned). Best
+     * effort, and that matters most on the failure path: the thing that failed the run is frequently
+     * the very store this release talks to (a step that violated a DB constraint leaves Postgres
+     * refusing every further statement on that connection), so the release throws too. A throwing
+     * release in a `finally` REPLACES the run's real outcome with a lease write nobody asked about,
+     * skips the post-turn re-drives after it, and, for a turn driven as a background resume, surfaces
+     * as an unhandled rejection instead of a failed run.
+     *
+     * Letting it go is safe: the lease expires on its own and `recoverIncomplete` re-drives whatever
+     * is still held. A lost release costs one lease window of latency; a masked error costs the
+     * diagnosis.
+     */
+    private releaseLeaseBestEffort;
+    /**
+     * The run's persisted state as a {@link RunResult}, without executing anything: the answer to a
+     * resume issued from inside the run's own execution, and to a settle whose compare-and-set lost
+     * (the path that won already emitted and notified). A run that is gone reads as `cancelled`, the
+     * safest terminal reading, never a fabricated success.
+     */
+    private echoCurrentStatus;
+    /**
+     * The engine's stand-in for {@link StateStore.updateRunIf} on a store without it, called with the
+     * store as `this`: read-then-write, which narrows the race to the gap between the read and the
+     * write (the pre-CAS behavior, now applied to every settle) but cannot close it.
+     */
+    private updateRunIfFallback;
+    private resumeRunNow;
     /**
      * The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
      * `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
@@ -4386,6 +4707,16 @@ declare class WorkflowEngine {
      * replay from their checkpoints, so only the work that had not finished runs again.
      */
     recoverIncomplete(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * The runs {@link recoverIncomplete} should try to reclaim: incomplete runs whose lease is free or
+     * expired, never the healthy ones a live turn is renewing. Every worker runs recovery on every
+     * timer tick, so listing every running run and lock-probing each (one doomed UPDATE per healthy
+     * run per worker per tick) was pure database load. The store answers it directly when it can
+     * ({@link StateStore.listOrphanedRuns}, bounded by {@link RECOVERY_BATCH}); else the full list is
+     * filtered here, which still spares the probes. Shuffled, like the due-timer pass, so instances
+     * recovering at once spread over the batch instead of contending for the same leases.
+     */
+    private orphanedRuns;
     /**
      * The remote step this run dispatched and is still awaiting a result for, if any — the signature
      * that tells {@link recoverIncomplete} "this run's work is ON THE TRANSPORT, not in a crashed
@@ -4842,6 +5173,47 @@ declare class WorkflowEngine {
      * {@link runExecution}'s settle/suspend; the lease is held by {@link execute}. The result that lands
      * us back here (a remote step finished, a timer fired) goes through `resume` like any TS workflow.
      */
+    /**
+     * The registered onError routes whose handler workflow nothing can run: not registered on this
+     * engine, and no live worker group serves it. Meant for a boot-time warning: a typo in a handler's
+     * name would otherwise surface only when the first run fails.
+     */
+    unservedOnErrorRoutes(): Promise<{
+        workflow: string;
+        route: OnErrorRoute;
+    }[]>;
+    /** Validate a workflow's {@link OnErrorRoute}s at registration. */
+    private checkedRoutes;
+    /**
+     * Route a failed run to its {@link OnErrorRoute} handler, read from the workflow's local registration
+     * or, for one served by convention, from what its live workers announce. Starts the handler run and
+     * waits for it the way a parent waits for a `ctx.child`: a `child:<handlerId>` waiter plus a
+     * `running` placeholder checkpoint carrying the handler's name and input, so the handler's terminal
+     * state wakes the run (buffered and reconciled like any child). From then on every execution of the
+     * run only follows the handler ({@link followHandoff}); the body never runs again. Undefined when no
+     * route matches: the run fails as usual.
+     *
+     * The placeholder sits past every seq the body used and is left out of {@link remoteHistory}.
+     */
+    private routeFailure;
+    /** A run's handoff checkpoints, live and retired: the only ones at {@link HANDOFF_SEQ_BASE} and up. */
+    private handoffCheckpoints;
+    /**
+     * Where a run that handed its failure off stands: the handler's outcome once it settled (from the
+     * wake's checkpoint, or off the handler run when the wake never arrived), else still waiting. Starts
+     * the handler if the turn that handed off crashed before its deferred start ran.
+     */
+    private followHandoff;
+    /**
+     * The onError routes the live workers announce for a workflow the engine serves by convention: the
+     * one set they agree on, or none when they state none or cannot be read. Workers that announce
+     * different sets (a rollout in progress) route nothing, and the run's failure is reported as a
+     * `run.unrouted` event. Announcers of another version of the workflow are ignored. The read is
+     * cached for {@link ANNOUNCED_ROUTES_TTL_MS}, so a burst of failures costs one descriptor read.
+     */
+    private announcedRoutes;
+    /** Every distinct onError route set the live workers of `group` announce for the run's workflow. */
+    private readAnnouncedRoutes;
     /**
      * Apply a terminal/suspended transition once: persist the new run status, emit the matching
      * lifecycle event, and (on completion/failure) wake a waiting parent. Both the TS and remote
@@ -5127,6 +5499,13 @@ declare class WorkflowEngine {
     private noteRecent;
     /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
     private savePendingCheckpoint;
+    /**
+     * {@link savePendingCheckpoint} for checkpoints at distinct seqs of one run: one
+     * {@link StateStore.saveCheckpointsIfPending} call when the store has it, else one write each.
+     * Never rejects as a whole: a write that failed 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;
     /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
      *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
      *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -5143,15 +5522,33 @@ declare class WorkflowEngine {
      * result (the dispatching one may be gone), so the run is crash/scale-safe. Resolves whether the
      * run should now be resumed: not for a duplicate or late delivery (the checkpoint isn't `pending`),
      * a run already finished, or a step fan whose barrier is still closed.
+     *
+     * Results of one run are settled in batches: the first starts a batch, and the ones that arrive
+     * while it is being written form the next. Under load a wide fan's results are written by one
+     * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked once
+     * per batch, not once per result. A result resolves only once its own write has committed, so the
+     * transport acknowledges nothing that is not durable yet.
      */
     private completeRemoteResult;
+    /** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
+    private drainResultQueue;
+    /**
+     * Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
+     * that resume replays every write of the batch, so a second would only replay it again. A result
+     * whose read or write failed resolves its error, and the transport redelivers just that one.
+     */
+    private completeRemoteResults;
     /**
      * 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
      * retry needs the parent to schedule it). Without it every result would replay the whole parent,
-     * which makes a fan of N steps cost O(N²) checkpoint reads.
+     * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
+     * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
+     * re-suspends, a lost one strands the run.
      */
     private stepFanStillRunning;
+    /** How many steps of a step fan's seq range are still `pending`. */
+    private stepFanPending;
     /**
      * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
      * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
@@ -5205,6 +5602,8 @@ declare class RemoteStepError extends Error {
     readonly stepError?: StepError | undefined;
     constructor(stepError?: StepError);
 }
+/** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
+declare const CHILD_EDGE_PREFIXES: string[];
 /** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
 declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
 
@@ -5288,7 +5687,12 @@ declare function parseDuration(duration: string | number): number;
  */
 declare class FatalError extends Error {
     readonly code?: string | undefined;
-    constructor(message: string, code?: string);
+    /** Structured, JSON-serializable detail (e.g. validation issues). It travels with the failure to
+     *  the run's error, a parent's `allSettled` item and an onError handler's input. */
+    readonly details?: unknown;
+    /** Read by the step result builders, so a dispatched step's retry policy honours it too. */
+    readonly retryable = false;
+    constructor(message: string, code?: string, details?: unknown);
 }
 /**
  * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
@@ -5366,6 +5770,8 @@ declare class RemoteWorkflowTimeout extends Error {
  * breaking changes (old runs finish on the version they started on).
  */
 declare class NonDeterminismError extends Error {
+    /** Marks the failure as a broken deploy, which an `onError` route never takes. */
+    readonly code = "non_determinism";
     readonly runId: string;
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
@@ -5396,17 +5802,17 @@ declare class NestedWorkflowCallError extends FatalError {
  * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
  * the Python SDK's `GatherFailed`.
  */
+/** One failed item of a fan: its input index, the child run or step id, and its failure. */
+interface GatherItemFailure {
+    index: number;
+    id: string;
+    error: string;
+    code?: string | undefined;
+    details?: unknown;
+}
 declare class GatherError extends Error {
-    readonly failures: {
-        index: number;
-        id: string;
-        error: string;
-    }[];
-    constructor(failures: {
-        index: number;
-        id: string;
-        error: string;
-    }[], total?: number);
+    readonly failures: GatherItemFailure[];
+    constructor(failures: GatherItemFailure[], total?: number);
 }
 declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
@@ -5637,6 +6043,49 @@ declare function mergeRunValueFacetRows(rows: readonly {
  */
 declare function runValueFacetsFromRuns(runs: readonly WorkflowRun[], axis: RunValueAxis, opts?: RunValueFacetOptions): RunValueFacetRow[];
 
+/** A store that aggregates checkpoints itself: both halves of the pair are present. */
+type CheckpointAggregatingStore = StateStore & Required<Pick<StateStore, 'checkpointStats' | 'queryCheckpoints'>>;
+declare function aggregatesCheckpoints(store: StateStore): store is CheckpointAggregatingStore;
+/**
+ * {@link StateStore.checkpointStats} over checkpoints already in memory — the reference a store's
+ * `GROUP BY` must agree with, and the in-memory store's implementation.
+ */
+declare function checkpointStatsOf(checkpoints: StepCheckpoint[], opts?: {
+    group?: string | undefined;
+}): CheckpointStat[];
+/** {@link StateStore.queryCheckpoints} over checkpoints already in memory, sorted by `seq` here. */
+declare function queryCheckpointsOf(checkpoints: StepCheckpoint[], query: CheckpointQuery): StepCheckpoint[];
+/**
+ * What `summarizeTimeline` plus `childIdsOf` make of a run's whole checkpoint list, read through the
+ * store's aggregates instead: the checkpoints outside wide fans, one {@link FanSummary} per wide fan,
+ * and the run's children capped at {@link SUMMARY_CHILD_LIMIT} with their count.
+ *
+ * What it reads besides the aggregates: the rows outside wide fans, every folded `fan:` checkpoint
+ * (one per settled wave), up to {@link FAN_SUMMARY_FAILURES} failed rows per wide fan, the first
+ * child-edge rows, and — while a wide child fan is in flight — that fan's completed `signal:child:`
+ * rows, whose `ok: false` payload is what marks a failed child.
+ *
+ * `childCount` counts each `spawn:` checkpoint as one child: the engine always writes the child's id
+ * as its output, which is what `childIdsOf` reads.
+ */
+declare function summarizeRunFromStore(store: CheckpointAggregatingStore, runId: string, over: number, stats?: CheckpointStat[]): Promise<{
+    timeline: StepCheckpoint[];
+    fans: FanSummary[];
+    children: string[];
+    childCount: number;
+}>;
+/** What `pageFan` makes of a run's whole checkpoint list, read one page at a time from the store. */
+declare function pageFanFromStore(store: CheckpointAggregatingStore, runId: string, group: string, query: FanPageQuery, stats?: CheckpointStat[]): Promise<FanPage>;
+/**
+ * The ETag of a summarized run detail: the run row as read (so any run field that changes shows)
+ * plus its checkpoint buckets, and the threshold it was summarized with.
+ */
+declare function runDetailEtag(run: WorkflowRun, stats: CheckpointStat[], over: number): string;
+/** The ETag of one page of a fan: its group's buckets and the page asked for. */
+declare function fanPageEtag(group: string, stats: CheckpointStat[], query: FanPageQuery): string;
+/** Whether an `If-None-Match` header value names `etag` (weak comparison, as RFC 9110 asks for). */
+declare function etagMatches(ifNoneMatch: string | undefined, etag: string): boolean;
+
 /**
  * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
  * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
@@ -5668,9 +6117,10 @@ declare function indexWaitersByRun(waiters: readonly SignalWaiter[]): Map<string
 
 /**
  * The parent of a child run whose id the engine minted: a `ctx.all` child
- * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit) or a `ctx.child` /
- * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`). Undefined for any other
- * run, including a child started with a caller-chosen id.
+ * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit), a `ctx.child` /
+ * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`), or the onError handler of
+ * a failed run (`<parent>.onError.<attempt>`). Undefined for any other run, including a child started with a
+ * caller-chosen id.
  */
 declare function parentRunIdOf(runId: string): string | undefined;
 
@@ -5714,14 +6164,30 @@ declare class CodecStateStore implements StateStore {
     /** Forwarded verbatim (deletes touch no payload). Bound only when the inner store has it, so the
      *  engine's per-run fallback still kicks in through the wrapper. */
     readonly deleteRuns?: (runIds: string[]) => Promise<void>;
+    /** Decodes the runs like {@link listIncompleteRuns}. Bound only when the inner store has it, so
+     *  the engine's list-and-filter fallback still kicks in through the wrapper. */
+    readonly listOrphanedRuns?: (nowMs: number, limit: number, namespace?: string) => Promise<WorkflowRun[]>;
+    /** Encodes the patch like {@link updateRun}. Bound only when the inner store has it, so the
+     *  engine's read-then-write fallback still kicks in through the wrapper. */
+    readonly updateRunIf?: (runId: string, expectedStatuses: RunStatus[], patch: Partial<WorkflowRun>) => Promise<boolean>;
     /** Encodes like {@link saveCheckpoint}. Bound only when the inner store has it, so the engine's
      *  plain-save fallback still kicks in through the wrapper. */
     readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
+    /** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
+    readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
     /** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
     readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
     /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
      *  when the inner store prunes, so the retention poller still sees (and warns about) its absence. */
     readonly pruneTerminalRuns?: (policy: RetentionPolicy, nowMs: number, limit: number) => Promise<number>;
+    /** Forwarded verbatim — the buckets aggregate names, statuses and timestamps, never a payload.
+     *  Bound only when the inner store aggregates, so the run detail's fallback still applies. */
+    readonly checkpointStats?: (runId: string, opts?: {
+        group?: string | undefined;
+    }) => Promise<CheckpointStat[]>;
+    /** Filters on unencoded columns, then decodes the rows like {@link listCheckpoints}. Bound only
+     *  when the inner store has it. */
+    readonly queryCheckpoints?: (runId: string, query: CheckpointQuery) => Promise<StepCheckpoint[]>;
     /** Forwarded verbatim — a count reads no payload. Bound only when the inner store counts, so the
      *  engine's facet/listing fallback still applies through the wrapper. */
     readonly countRuns?: (query: Omit<RunQuery, 'limit' | 'offset'>) => Promise<number>;
@@ -5753,6 +6219,7 @@ declare class CodecStateStore implements StateStore {
     ensureSchema(): Promise<void>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    private encRunPatch;
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
@@ -5821,12 +6288,17 @@ declare function eventMatchOf(token: string): Record<string, unknown>;
 declare function eventMatches(payload: unknown, match: Record<string, unknown>): boolean;
 
 interface MetricsSnapshot {
+    /** `routed`: failures handed to an onError handler; `unrouted`: routes the engine could not apply. */
     runs: {
         started: number;
         completed: number;
         failed: number;
         suspended: number;
+        routed: number;
+        unrouted: number;
     };
+    /** Routed failures by error code (`*` for a failure without one). */
+    routedByCode: Record<string, number>;
     steps: {
         started: number;
         completed: number;
@@ -6176,12 +6648,19 @@ declare class InMemoryStateStore implements StateStore {
      * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
      */
     lastCheckpointRowsRead: number;
+    /**
+     * Test/observability hook: checkpoint rows materialized since construction, across every
+     * checkpoint read that returns rows — what a run-detail benchmark compares between paths.
+     */
+    checkpointRowsRead: number;
     private key;
     /** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
     private reindexAttributes;
     tryAdmitSingleton(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, inputPatch: Partial<WorkflowRun>): Promise<void>;
+    updateRunIf(runId: string, expectedStatuses: RunStatus[], patch: Partial<WorkflowRun>): Promise<boolean>;
+    private applyRunPatch;
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
     deleteRuns(runIds: string[]): Promise<void>;
@@ -6189,6 +6668,8 @@ declare class InMemoryStateStore implements StateStore {
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
+    saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
+    listOrphanedRuns(nowMs: number, limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
@@ -6250,6 +6731,11 @@ declare class InMemoryStateStore implements StateStore {
     deleteSchedule(id: string): Promise<boolean>;
     listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    private runCheckpoints;
+    checkpointStats(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    queryCheckpoints(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     countCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -6295,4 +6781,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllStepsOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, GatherError, type GroupHealth, 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 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, 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, 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, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, listSignalWaitersOfRuns, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, pageFan, parentRunIdOf, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeTimeline, tenantGroup, useDurableExecution, warn, 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 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, 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 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, 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, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, partitionOfToken, planDispatch, 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, workflowName };