@dudousxd/nestjs-durable-core 0.77.0 → 0.79.0

package/dist/index.d.cts

@@ -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
@@ -474,6 +484,230 @@ declare class WorkflowBlocked extends Error {
  */
 declare function planDispatch(requires: string[], liveDescriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[], cp: WorkerDescriptor, token: string): DispatchPlan;
 
+/**
+ * A parallel fan (a `ctx.all`, a step fan, a polyglot `gather`) reduced to what a detail view needs
+ * to draw it: one node, its progress and its failures. A run detail with a 40,000-item fan otherwise
+ * carries every member — megabytes of JSON, and one rendered row (or fetched child) per member.
+ */
+interface FanSummary {
+    /** The fan's `parallelGroup`. */
+    group: string;
+    /** The members' common step name, or `child runs` for a fan of child workflows. */
+    label: string;
+    firstSeq: number;
+    lastSeq: number;
+    /** Members started so far: steps, or child runs (a folded checkpoint counts as the children it stands for). */
+    size: number;
+    /**
+     * The fan's declared size, when its group carries it. More than `size` while waves are still to
+     * be sent (`concurrency`), and for good when a failFast fan stopped early.
+     */
+    total?: number | undefined;
+    /** `total - size`: members never started yet — or never to start, once the run has finished. */
+    notStarted?: number | undefined;
+    /** The fan stops at its first failure. */
+    failFast: boolean;
+    /** Members by status. A child that failed counts as `failed`, though its checkpoint is `completed`. */
+    counts: Partial<Record<StepCheckpoint['status'], number>>;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    /** The first {@link FAN_SUMMARY_FAILURES} failed members, so a failure shows without paging. */
+    failures: StepCheckpoint[];
+}
+/** A page of one fan's members, in seq order. */
+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). */
+declare function summarizeFan(group: string, members: StepCheckpoint[]): FanSummary;
+/**
+ * Split a run's timeline into the checkpoints a detail view lists one by one and the fans it draws as
+ * one node each: every `parallelGroup` with more than `over` members, or declared wider than that,
+ * becomes a {@link FanSummary}, and its members leave the timeline. Smaller groups and ungrouped steps stay as they are.
+ */
+declare function summarizeTimeline(timeline: StepCheckpoint[], over: number): {
+    timeline: StepCheckpoint[];
+    fans: FanSummary[];
+};
+/** 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
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
+/** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
+ *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
+ *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
+interface DurableTopology {
+    role: 'control-plane' | 'tenant';
+    /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
+    tenant?: string;
+}
+/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
+ *  re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
+ *  it via {@link WireDates} instead of hand-mirroring field by field. */
+interface RunDetail {
+    run: WorkflowRun;
+    /**
+     * Steps in execution order (local + remote). With {@link RunDetailOptions.summarizeFansOver}, the
+     * members of a summarized fan are left out — see {@link fans}.
+     */
+    timeline: StepCheckpoint[];
+    /** Ids of runs this run spawned (parent→children tree). Capped when summarized — see {@link childCount}. */
+    children: string[];
+    /** The fans drawn as one node each, when the detail was asked to summarize them. */
+    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 {
+    /**
+     * Summarize every fan with more than this many members into a {@link FanSummary} instead of
+     * listing them, and cap `children`. Unset returns the full timeline, as before. A view of a run
+     * 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
+ * JSON response actually carries once dates cross the wire (`JSON.stringify` already does this
+ * coercion; this just types it). Homomorphic: each field keeps its own optional modifier, so a
+ * required `Date` becomes a required `string` and an optional one stays optional. Lets a consumer
+ * derive its own wire-facing client type from a core server type (e.g. the dashboard's SPA `WorkflowRun`/
+ * `StepCheckpoint`/`RunDetail`) instead of hand-mirroring it field by field and drifting.
+ */
+type WireDates<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
+};
+/**
+ * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
+ * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
+ * a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
+ * (no metrics/bulk/update/signal) — those stay control-plane-only. `workerHealth` IS on the port: the
+ * operator answers it scoped to the requester's own groups, so a tenant's Workers panel works too.
+ *
+ * Declared as an **abstract class** rather than an interface so it doubles as its own NestJS DI token
+ * (the idiomatic inject-by-type pattern): providers bind `{ provide: RunGateway, useClass/useFactory }`
+ * and consumers inject `constructor(private readonly gateway: RunGateway)` with no string/symbol token.
+ * `StoreRunGateway`/`ProxyRunGateway` `implements RunGateway`; abstract methods carry no body, so the
+ * emitted runtime class is an empty, non-instantiable shell used only as the token.
+ */
+declare abstract class RunGateway {
+    /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
+    abstract topology(): DurableTopology;
+    abstract getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /**
+     * One page of a fan's members, for a view that drew the fan from its {@link FanSummary}. Optional:
+     * a gateway without it serves summarized details whose fans cannot be expanded.
+     */
+    getFanMembers?(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
+    /**
+     * The run alone, without its timeline. Optional: a caller that only needs the run (an ownership
+     * check) falls back to {@link getRunDetail}, which reads every checkpoint.
+     */
+    getRun?(runId: string): Promise<WorkflowRun | null>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    abstract listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Counts of the runs matching `query`, grouped by `(status, origin)` — what a console's status and
+     * origin chips display. Separate from {@link listRuns} precisely so the list can be PAGINATED: the
+     * page bounds what is rendered, these counts stay whole-set exact. Zero-count cells are absent.
+     */
+    abstract runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * The distinct values of one filter axis over the runs matching `query`, with counts — what fills a
+     * console's tenant/tag/attribute pickers. On the port (not control-plane-only) because the pickers
+     * belong to the same panel as {@link listRuns}: a tenant that can list its runs has to be able to
+     * see what it may filter them by, or its console offers a blank dropdown.
+     *
+     * Returns `[]` when the underlying store does not implement the enumeration — an empty picker with
+     * free-text entry still standing, not an error.
+     */
+    abstract runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
+    /**
+     * Bulk-resolve {@link RunWaiting} for an arbitrary set of run ids — for a consumer with its OWN
+     * filtered/paginated run listing (so it isn't just `listRuns` under another name) that needs to know
+     * which of ITS runs are parked on a breakpoint (or any other event wait) without re-deriving the bulk
+     * waiter scan itself or reaching for raw SQL against `durable_step_checkpoints`. A `Record` (not a
+     * `Map`) because `ProxyRunGateway` serialises the reply over the transport as plain JSON. Entries are
+     * present ONLY for runs currently waiting — an unknown id, a non-suspended id, and a suspended id
+     * parked on something non-event (a bare `ctx.sleep`, an in-flight step) are simply absent, same as a
+     * `listRuns` row with no `waiting`.
+     */
+    abstract waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
+    /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
+     *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
+    abstract workerHealth(): Promise<GroupHealth[]>;
+    abstract cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    abstract retry(runId: string): Promise<RunResult | null>;
+    abstract continue(runId: string): Promise<RunResult | null>;
+    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     *  plus how many steps were re-dispatched, or null if the run is unknown. */
+    abstract redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
+    abstract retryWithInput(runId: string, input: unknown): Promise<{
+        runId: string;
+    } | null>;
+    /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
+    abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+
 /**
  * Vendored subset of the Standard Schema spec (https://standardschema.dev) — the `~standard`
  * property protocol implemented by zod 3.24+, valibot, arktype, and others. Vendored (rather than
@@ -909,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;
@@ -979,6 +1216,16 @@ 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 oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
@@ -1188,6 +1435,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
@@ -1513,6 +1826,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;
@@ -1569,6 +1902,12 @@ interface RunRequest {
 type RunRequestKind = {
     kind: 'getRunDetail';
     runId: string;
+    options?: RunDetailOptions | undefined;
+} | {
+    kind: 'getFanMembers';
+    runId: string;
+    group: string;
+    query: FanPageQuery;
 } | {
     kind: 'listRuns';
     query: RunQuery;
@@ -2397,6 +2736,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
@@ -2489,8 +2839,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
@@ -2509,7 +2859,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;
@@ -2520,6 +2870,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 {
@@ -2542,7 +2894,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.
@@ -2582,6 +2934,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;
@@ -2982,7 +3336,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[];
 }
 /**
@@ -3018,6 +3372,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. */
@@ -3331,6 +3691,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
@@ -3844,6 +4262,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
@@ -3865,6 +4285,8 @@ declare class WorkflowEngine {
     private readonly stepFansFiredHere;
     /** 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. */
@@ -3939,6 +4361,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
@@ -3968,6 +4392,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
@@ -3994,6 +4420,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
@@ -4644,6 +5072,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
@@ -4929,6 +5398,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. */
@@ -4945,15 +5421,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
@@ -5007,6 +5501,10 @@ 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[];
 
 /**
  * What the class-first statics need from whoever registered the workflow class: the engine, or a
@@ -5088,7 +5586,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
@@ -5166,6 +5669,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);
@@ -5196,17 +5701,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. */
@@ -5437,110 +5942,48 @@ declare function mergeRunValueFacetRows(rows: readonly {
  */
 declare function runValueFacetsFromRuns(runs: readonly WorkflowRun[], axis: RunValueAxis, opts?: RunValueFacetOptions): RunValueFacetRow[];
 
-/** 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
- *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
- *  on a non-parked run and on gateways/versions that don't compute it. */
-type RunListItem = WorkflowRun & {
-    waiting?: RunWaiting | undefined;
-};
-/** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
- *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
- *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
-interface DurableTopology {
-    role: 'control-plane' | 'tenant';
-    /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
-    tenant?: string;
-}
-/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
- *  re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
- *  it via {@link WireDates} instead of hand-mirroring field by field. */
-interface RunDetail {
-    run: WorkflowRun;
-    /** Steps in execution order (local + remote). */
-    timeline: StepCheckpoint[];
-    /** Ids of runs this run spawned (parent→children tree). */
-    children: string[];
-}
+/** 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;
 /**
- * Maps every `Date` (and `Date | undefined`) field of `T` to its ISO-string wire form — the shape a
- * JSON response actually carries once dates cross the wire (`JSON.stringify` already does this
- * coercion; this just types it). Homomorphic: each field keeps its own optional modifier, so a
- * required `Date` becomes a required `string` and an optional one stays optional. Lets a consumer
- * derive its own wire-facing client type from a core server type (e.g. the dashboard's SPA `WorkflowRun`/
- * `StepCheckpoint`/`RunDetail`) instead of hand-mirroring it field by field and drifting.
+ * {@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.
  */
-type WireDates<T> = {
-    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
-};
+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[];
 /**
- * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
- * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
- * a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
- * (no metrics/bulk/update/signal) — those stay control-plane-only. `workerHealth` IS on the port: the
- * operator answers it scoped to the requester's own groups, so a tenant's Workers panel works too.
+ * 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.
  *
- * Declared as an **abstract class** rather than an interface so it doubles as its own NestJS DI token
- * (the idiomatic inject-by-type pattern): providers bind `{ provide: RunGateway, useClass/useFactory }`
- * and consumers inject `constructor(private readonly gateway: RunGateway)` with no string/symbol token.
- * `StoreRunGateway`/`ProxyRunGateway` `implements RunGateway`; abstract methods carry no body, so the
- * emitted runtime class is an empty, non-instantiable shell used only as the token.
+ * 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 abstract class RunGateway {
-    /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
-    abstract topology(): DurableTopology;
-    abstract getRunDetail(runId: string): Promise<RunDetail | null>;
-    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
-     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
-     *  plane sent. */
-    abstract listRuns(query: RunQuery): Promise<RunListItem[]>;
-    /**
-     * Counts of the runs matching `query`, grouped by `(status, origin)` — what a console's status and
-     * origin chips display. Separate from {@link listRuns} precisely so the list can be PAGINATED: the
-     * page bounds what is rendered, these counts stay whole-set exact. Zero-count cells are absent.
-     */
-    abstract runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
-    /**
-     * The distinct values of one filter axis over the runs matching `query`, with counts — what fills a
-     * console's tenant/tag/attribute pickers. On the port (not control-plane-only) because the pickers
-     * belong to the same panel as {@link listRuns}: a tenant that can list its runs has to be able to
-     * see what it may filter them by, or its console offers a blank dropdown.
-     *
-     * Returns `[]` when the underlying store does not implement the enumeration — an empty picker with
-     * free-text entry still standing, not an error.
-     */
-    abstract runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
-    /**
-     * Bulk-resolve {@link RunWaiting} for an arbitrary set of run ids — for a consumer with its OWN
-     * filtered/paginated run listing (so it isn't just `listRuns` under another name) that needs to know
-     * which of ITS runs are parked on a breakpoint (or any other event wait) without re-deriving the bulk
-     * waiter scan itself or reaching for raw SQL against `durable_step_checkpoints`. A `Record` (not a
-     * `Map`) because `ProxyRunGateway` serialises the reply over the transport as plain JSON. Entries are
-     * present ONLY for runs currently waiting — an unknown id, a non-suspended id, and a suspended id
-     * parked on something non-event (a bare `ctx.sleep`, an in-flight step) are simply absent, same as a
-     * `listRuns` row with no `waiting`.
-     */
-    abstract waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
-    /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
-     *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
-    abstract workerHealth(): Promise<GroupHealth[]>;
-    abstract cancel(runId: string, opts?: {
-        compensate?: boolean;
-    }): Promise<RunResult | null>;
-    abstract retry(runId: string): Promise<RunResult | null>;
-    abstract continue(runId: string): Promise<RunResult | null>;
-    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
-     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
-     *  plus how many steps were re-dispatched, or null if the run is unknown. */
-    abstract redispatchPending(runId: string): Promise<(RunResult & {
-        redispatched: number;
-    }) | null>;
-    abstract retryWithInput(runId: string, input: unknown): Promise<{
-        runId: string;
-    } | null>;
-    /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
-    abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
-}
+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.
@@ -5573,9 +6016,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;
 
@@ -5622,11 +6066,21 @@ declare class CodecStateStore implements StateStore {
     /** 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>;
@@ -5726,12 +6180,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;
@@ -6081,6 +6540,11 @@ 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;
@@ -6094,6 +6558,7 @@ 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[]>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
@@ -6155,6 +6620,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[]>;
@@ -6200,4 +6670,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, type FanJoin, 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 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, 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, 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, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, listSignalWaitersOfRuns, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, 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, 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 };