@dudousxd/nestjs-durable-core 0.76.1 → 0.78.0

package/dist/index.d.ts

@@ -474,6 +474,198 @@ 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;
+}
+interface FanPageQuery {
+    offset?: number | undefined;
+    limit?: number | undefined;
+    /** Only failed members (a failed step, or a child that failed). */
+    failedOnly?: boolean | 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;
+/** 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 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;
+}
+/** 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;
+}
+/**
+ * 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
@@ -983,8 +1175,12 @@ interface StateStore {
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
-    /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
-    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    /**
+     * Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume — the most
+     * overdue first, at most `limit` of them when it is given. Every driving instance polls this each
+     * tick, so a recovery wave of thousands of due runs must come back in batches, not all at once.
+     */
+    listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
     /**
      * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
      * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
@@ -1175,6 +1371,15 @@ interface StateStore {
      * plus an in-JS prefix scan that produces the identical result.
      */
     listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+    /**
+     * How many of the run's checkpoints with `fromSeq <= seq <= toSeq` have one of `statuses`. The join
+     * barrier of a step fan (`ctx.all` over a `@Step`) asks this on every result — "is any step of the
+     * fan still `pending`?" — so it must be a count, not a load of the fan.
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * 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>;
 }
 /**
  * A persisted schedule as the STORE sees it: a handful of queryable columns plus two JSON documents
@@ -1485,6 +1690,21 @@ interface AllOptions {
      */
     concurrency?: number;
 }
+/**
+ * Options for `ctx.all` over a `@Step` — one durable step per input instead of one child workflow
+ * per input. The per-call step policy (`retries`, `backoff`, …) applies to every step of the fan.
+ * Flow-control `queue`s and a liveness `timeoutMs` are not supported on a fan.
+ */
+interface AllStepsOptions extends Omit<StepDispatchOpts, 'queue' | 'timeoutMs'> {
+    /** `waitAll` (default) or `failFast` — see {@link WorkflowCtx.all}. */
+    mode?: 'waitAll' | 'failFast';
+    /**
+     * The most steps in flight at once. Unset sends the whole fan immediately. When set, steps go out
+     * in waves of `concurrency`, the next once the previous has settled; each wave costs the parent one
+     * turn. Part of the fan's identity, like `inputs`.
+     */
+    concurrency?: number;
+}
 /** One child of a fan as {@link StateStore.registerChildWaits} writes it. */
 interface ChildWait {
     waiter: SignalWaiter;
@@ -1541,6 +1761,12 @@ interface RunRequest {
 type RunRequestKind = {
     kind: 'getRunDetail';
     runId: string;
+    options?: RunDetailOptions | undefined;
+} | {
+    kind: 'getFanMembers';
+    runId: string;
+    group: string;
+    query: FanPageQuery;
 } | {
     kind: 'listRuns';
     query: RunQuery;
@@ -2360,6 +2586,14 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      * `concurrency` caps how many children run at once (see {@link AllOptions.concurrency}).
      */
     all<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: AllOptions): Promise<WorkflowOutputOf<C>[]>;
+    /**
+     * Run one durable **step** per entry in `inputs` in parallel and wait for all of them — the same
+     * fan as above with a `@Step` instead of a child workflow, so each item costs a step instead of a
+     * whole run. The steps share a `parallelGroup` (the dashboard renders them as one fan), the parent
+     * replays once per settled wave rather than once per result, and outputs come back in input order;
+     * failures surface as a {@link GatherError}, like the child fan.
+     */
+    all<TInput, TOutput>(step: StepRef<TInput, TOutput>, inputs: TInput[], opts?: AllStepsOptions): Promise<TOutput[]>;
     all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: AllOptions): Promise<TOutput[]>;
     /**
      * Pause the run at this point until a human resumes it from the dashboard (or
@@ -3628,6 +3862,13 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * The most due timers one {@link WorkflowEngine.resumeDueTimers} pass loads and drives, most
+     * overdue first. Every driving instance runs that pass each tick, so a wave of thousands of due
+     * runs (a recovery after an outage, a fan's children waking together) is worked through in
+     * batches instead of every instance loading and walking all of it. Default 500.
+     */
+    timerBatchSize?: number | undefined;
     /**
      * Retention for a BUFFERED event that no `waitForEvent` ever claims (see
      * {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
@@ -3746,6 +3987,7 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly timerBatchSize;
     private readonly eventBufferTtlMs;
     private readonly remoteRedispatchMs;
     private readonly remoteRedispatchMax;
@@ -3812,6 +4054,15 @@ declare class WorkflowEngine {
      * dropped one {@link redriveSettledSteps} recovers. Pruned by age (see {@link noteSettledHere}).
      */
     private readonly settledHere;
+    /**
+     * The step fans (`ctx.all` over a `@Step`) a turn suspended on, by run, while that turn executes on
+     * THIS instance — re-checked once its lease is released (see {@link redriveSettledStepFans}).
+     */
+    private readonly awaitedStepFans;
+    /** Step fans whose join barrier this instance opened, by `runId:firstSeq` — see {@link settledHere}. */
+    private readonly stepFansFiredHere;
+    /** The tail of each run's queue of results being handled on this instance — see {@link serializedPerRun}. */
+    private readonly resultChains;
     /** 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. */
@@ -4332,6 +4583,13 @@ declare class WorkflowEngine {
      * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
      */
     private redriveSettledSteps;
+    /**
+     * {@link redriveSettledSteps} for a step fan: once the turn that suspended on it released its lease,
+     * re-drive the run if no step of the fan is still `pending` — the last result landed on another
+     * instance while this one held the lease, and its wake was dropped there. A fan whose barrier this
+     * instance opened is skipped, for the reason {@link settledHere} gives.
+     */
+    private redriveSettledStepFans;
     private redriveSettledChildren;
     /**
      * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
@@ -4849,8 +5107,24 @@ declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /**
+     * `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
+     * reserves the whole position block up front, so replay re-derives the same seqs.
+     *
+     * Each turn reads the fan's checkpoints fresh, hands every step that already has one to
+     * {@link callRemote} (which owns the completed / pending-lease / failed-retry rules), and sends
+     * the steps nobody has sent yet: all of them, or with `concurrency`, the next wave once the last
+     * one has drained. New steps are written `pending` BEFORE any is dispatched, so a turn that runs
+     * concurrently with this one finds them already sent instead of sending them again. The join
+     * barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
+     */
+    private callRemoteAll;
+    /** Write the `pending` checkpoints of a step fan's new steps, then dispatch them. */
+    private sendStepFan;
     /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
     private noteSettledHere;
+    /** Record `key` in a "happened here recently" map, pruning entries older than a lease. */
+    private noteRecent;
     /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
     private savePendingCheckpoint;
     /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
@@ -4858,11 +5132,26 @@ declare class WorkflowEngine {
      *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
     private dispatchRemoteTask;
     /**
-     * Complete a durable remote step from its worker result and resume the run — runs on whichever
-     * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
-     * A no-op if the checkpoint isn't `pending` (a duplicate or late delivery).
+     * Run `work` after every earlier `work` for the same run on this instance has settled. A result
+     * resumes its run inline, and `execute` lets this instance into a lease it already holds — so two
+     * results of one run handled at once here would run two turns of it concurrently. Results of
+     * different runs still go in parallel, which is what a results consumer with concurrency > 1 is for.
+     */
+    private serializedPerRun;
+    /**
+     * Complete a durable remote step from its worker result — runs on whichever instance receives the
+     * 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.
      */
     private completeRemoteResult;
+    /**
+     * 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.
+     */
+    private stepFanStillRunning;
     /**
      * 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
@@ -4916,6 +5205,8 @@ declare class RemoteStepError extends Error {
     readonly stepError?: StepError | undefined;
     constructor(stepError?: StepError);
 }
+/** 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
@@ -5346,111 +5637,6 @@ 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[];
-}
-/**
- * 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): 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;
-}
-
 /**
  * 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
@@ -5531,6 +5717,8 @@ 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>;
+    /** 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>;
@@ -5575,7 +5763,7 @@ declare class CodecStateStore implements StateStore {
     }) => Promise<T>): Promise<T>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -6003,7 +6191,7 @@ declare class InMemoryStateStore implements StateStore {
     saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string, limit?: number): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -6063,6 +6251,7 @@ declare class InMemoryStateStore implements StateStore {
     listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): 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[]>;
 }
 
@@ -6106,4 +6295,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
     updatedAt: Date;
 } | undefined;
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, 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 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 };