@dudousxd/nestjs-durable-core 0.65.0 → 0.67.0

package/dist/index.d.ts

@@ -1032,6 +1032,16 @@ interface StateStore {
      */
     transaction?<T>(work: (tx: StoreTransaction) => Promise<T>): Promise<T>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /**
+     * Count the runs matching `query`, grouped by `(status, origin)` — the totals behind a console's
+     * status and origin chips, in ONE aggregate instead of a full listing the caller counts in memory.
+     * This is what lets a run list be paginated at all: `listRuns` can return 100 rows while the chips
+     * still say how many of the 9,000 are failed.
+     *
+     * Cells with a zero count are simply absent. Optional: a store that omits it still works — callers
+     * fall back to counting a {@link listRuns} result, which is correct but unbounded.
+     */
+    runFacets?(query: RunFacetQuery): Promise<RunFacetRow[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     /**
      * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
@@ -1143,14 +1153,34 @@ interface RunQuery {
      * Restrict to runs whose workflow was declared by this package (exact match against
      * {@link WorkflowRun.origin}), ANDed with the other predicates.
      *
-     * A run with NO origin (unknown — see the field) matches no `origin` value at all, so a UI facet
+     * A run with NO origin (unknown — see the field) matches no `origin` VALUE at all, so a UI facet
      * built on this must keep an "all origins" option: filtering by any single package silently hides
-     * every unattributed run, which reads to an operator as "those runs do not exist".
+     * every unattributed run, which reads to an operator as "those runs do not exist". `null` selects
+     * exactly that absent bucket (`origin IS NULL`), so a paginated console can offer an "unknown"
+     * facet without having to hold every run in the browser to find them.
      */
-    origin?: string | undefined;
+    origin?: string | null | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
+/**
+ * The predicates a {@link RunFacetRow} count is taken over — a {@link RunQuery} minus the axes the
+ * facets THEMSELVES report (`status`/`origin`) and minus paging. Keeping them out of the type is
+ * what makes the counts answerable in one query: a console narrows by tag/tenant/attribute, and the
+ * one call back tells it how the matching runs split across every status and every origin at once.
+ */
+type RunFacetQuery = Omit<RunQuery, 'status' | 'statuses' | 'origin' | 'limit' | 'offset'>;
+/**
+ * One `(status, origin)` cell of {@link StateStore.runFacets} — a `GROUP BY` row, not a page of runs.
+ * A console pivots these into its status chips and its origin chips, so both stay exact while the
+ * list itself is paginated. `origin` is `null` for runs carrying none (see {@link WorkflowRun.origin});
+ * that bucket is a real, countable answer here rather than the absence a value-match cannot express.
+ */
+interface RunFacetRow {
+    status: RunStatus;
+    origin: string | null;
+    count: number;
+}
 /** The transaction handle `StateStore.transaction` hands to its work callback. */
 interface StoreTransaction {
     /** The store-native transaction handle (TypeORM `EntityManager`, Prisma tx client, MikroORM `EntityManager`,
@@ -1214,6 +1244,9 @@ type RunRequestKind = {
 } | {
     kind: 'listRuns';
     query: RunQuery;
+} | {
+    kind: 'runFacets';
+    query: RunFacetQuery;
 } | {
     kind: 'workerHealth';
 } | {
@@ -1552,6 +1585,21 @@ interface Transport {
      * caller could not have enumerated.
      */
     readAllWorkerDescriptors?(): Promise<WorkerDescriptor[]>;
+    /**
+     * Every live worker heartbeat in the deployment, across all groups — the LIVENESS floor under
+     * {@link WorkflowEngine.workflowDirectory}. Optional, same as {@link readAllWorkerDescriptors}.
+     *
+     * It exists because a descriptor is the richer advertisement but not the universal one: an SDK
+     * that predates the handshake beats a liveness key and publishes no descriptor at all, and reading
+     * only descriptors reports such a fleet as EMPTY while it is serving work. Convention routing
+     * already resolves those workers off exactly these keys, so a directory built without them
+     * contradicts the dispatcher standing next to it.
+     *
+     * Distinct from {@link listWorkerGroups}, which answers with tokens alone: this carries the
+     * instance behind each one, so the directory can say how many workers back a name and a partition
+     * sighting can name who is beating there.
+     */
+    readAllWorkerHeartbeats?(): Promise<WorkerHeartbeat[]>;
     /**
      * DB-less tenant worker → control plane: publish a {@link StartRunMessage} requesting a new run.
      * Optional — only transports that carry the hosted-control-plane protocol (P4) implement this.
@@ -2442,6 +2490,25 @@ declare class EventAccumulators {
  * picker offering steps would be offering an operation that does not exist. Step HANDLER names are
  * still advertised (`WorkerDescriptor.steps`) — that is a routing/capability fact used to decide
  * whether a dispatched step can be run, not an invocable catalog.
+ *
+ * ## The floor: a live worker that announces nothing
+ *
+ * An SDK old enough to predate the descriptor advertisement publishes only its TTL'd liveness
+ * heartbeat — one key per routing token it consumes. Read strictly, such a fleet announces nothing
+ * and this registry would be empty while work is being served. That answer is not merely unhelpful,
+ * it CONTRADICTS the engine beside it: `resolveRemoteByConvention` routes a call to `X` the moment a
+ * token named `X` heartbeats, so the deployment already treats liveness as sufficient to CALL a
+ * workflow while claiming to know nothing when asked to LIST one. Both answers come out of the same
+ * Redis.
+ *
+ * So the heartbeat is folded in as a second, weaker tier of evidence ({@link AnnouncedWorkflow.evidence}
+ * `'observed'`): the entry exists because a live token of that name exists, which is exactly — no more
+ * and no less — the condition under which convention routing would resolve it. Listing it therefore
+ * cannot introduce a failure the dispatcher did not already have. What it CANNOT do is state a
+ * version, an origin, a runtime, or even that the token serves a workflow rather than a step handler
+ * of the same name: none of that is in a heartbeat, and every one of those stays un-stated rather than
+ * being guessed. A descriptor always wins — a token an announcement already covers is never re-added
+ * as an observation.
  */
 
 /** One live worker's claim about one workflow: the registration plus who announced it. */
@@ -2457,25 +2524,46 @@ interface Disagreement {
     axis: 'group' | 'origin' | 'requires';
     values: string[];
 }
+/**
+ * How strong the fleet's claim about a workflow is. The two tiers are NOT interchangeable and a
+ * caller must not read them as the same fact:
+ *
+ * - `'declared'` — at least one live worker published a descriptor naming this workflow. Everything
+ *   populated on the entry was STATED by that worker; everything absent it declined to state.
+ * - `'observed'` — nobody described it. What exists is a live routing token of this name, which is
+ *   precisely the condition `resolveRemoteByConvention` uses to route a call, so the name IS
+ *   reachable. Nothing else is known: no version, no origin, no runtime, and no assurance that the
+ *   worker consuming that token serves a WORKFLOW there rather than a step handler of the same name.
+ *   An entry like this is a live queue, not a promise.
+ */
+type AnnouncementEvidence = 'declared' | 'observed';
 /** One workflow the live fleet announces, folded across every worker that announced it. */
 interface AnnouncedWorkflow {
+    /** What kind of claim this entry rests on — see {@link AnnouncementEvidence}. A caller that shows
+     *  a version, an origin or a runtime must check this first: an `'observed'` entry has none of
+     *  them, and the emptiness is a fact about the fleet, not a rendering gap. */
+    evidence: AnnouncementEvidence;
     /** `name@version`, or the bare `name` when no announcer stated a version. Stable sort key. */
     key: string;
     name: string;
     /** Absent when no announcer stated one — never inferred from another announcer's version. */
     version?: string;
-    /** Every distinct routing group announced (sorted). Empty = nobody stated one. */
+    /** Every distinct routing group announced (sorted). Empty = nobody stated one. On an `'observed'`
+     *  entry this is the token the heartbeat was published UNDER — not a claim by anybody, but the
+     *  queue a call would actually land on, which is the one thing an observation does establish. */
     groups: string[];
     /** Every distinct declaring package announced (sorted). Empty = nobody stated one. */
     origins: string[];
     /** 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[][];
-    /** Runtimes of the live announcers (sorted, de-duplicated). */
+    /** 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. */
     runtimes: ('node' | 'python')[];
     /** Instance ids of the live workers announcing it (sorted, de-duplicated). Its length is how many
      *  workers can currently run this workflow — `1` is a single point of failure, and it is never 0
-     *  (an entry exists only because somebody announced it). */
+     *  (an entry exists only because somebody announced it, or because somebody is beating on it). */
     instances: string[];
     /** The axes the announcers differ on, empty when they speak with one voice. A caller that must
      *  pick a single target has to resolve these itself — the registry refuses to guess. */
@@ -2502,6 +2590,151 @@ declare function announcementsOf(raw: RawWorkerDescriptor | WorkerDescriptor): W
  * `instances` is a set, so it counts workers, not keys.
  */
 declare function aggregateAnnouncements(descriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): AnnouncedWorkflow[];
+/**
+ * The part of one live worker heartbeat this registry can read: the routing token the beat was
+ * published under, and which process published it. That is genuinely all a heartbeat holds — it is
+ * the cheap tier of the two-tier advertisement, and its job is liveness, not description.
+ *
+ * Structurally satisfied by `WorkerHeartbeat` (the transport-facing shape, which also carries a beat
+ * time and an execution snapshot). Declared here rather than imported so this module keeps its "pure
+ * data, no transport" footing and `interfaces.ts` can keep importing FROM it.
+ */
+interface HeartbeatSighting {
+    /** The routing token the beat was published under (already partition-suffixed when partitioned). */
+    group: string;
+    /** The beating process's instance id. */
+    instanceId: string;
+}
+/**
+ * The weaker tier: one entry per live routing token that NO descriptor accounts for.
+ *
+ * `covered` holds every token the declared announcements already explain — both the sanitized form of
+ * each announced NAME and every group any announcer stated. A token in that set is dropped, so a
+ * fleet that describes itself properly gets exactly the same registry it got before this tier
+ * existed, and a worker is never counted twice under two kinds of evidence.
+ *
+ * Everything an observation cannot know stays empty rather than being filled with a plausible guess:
+ * no version (so nothing can be pinned against it), no origin, no requires, no runtime. The `name` is
+ * the token itself, which equals the workflow's name for every name a queue token can round-trip —
+ * `sanitizeQueueToken` rewrites `:` to `-` and that rewrite is not invertible, so a workflow named
+ * `orders:fulfill` is observed as `orders-fulfill`. Stated here because a picker showing that string
+ * should show what the queue is really called, not a reconstruction that might be wrong.
+ */
+declare function observedAnnouncements(heartbeats: readonly HeartbeatSighting[], covered: ReadonlySet<string>): AnnouncedWorkflow[];
+/**
+ * Every routing token a live descriptor already ACCOUNTS FOR, and which therefore needs no
+ * observation — for either of the two opposite reasons.
+ *
+ * - A token some worker announced as a WORKFLOW: already in the registry, richer than an
+ *   observation could ever be, and re-adding it would count one worker twice.
+ * - A token some worker declared as a STEP HANDLER (`WorkerDescriptor.steps`): it must be left OUT,
+ *   because a step is not addressable from outside a run and offering one as callable would be
+ *   offering an operation the engine does not have. Route-by-handler gives every step its own queue,
+ *   so without this the liveness floor turns a fleet's entire step surface into fake workflows.
+ *
+ * That second exclusion is a DECLARED negative — the worker said "this name is a step" — which is
+ * exactly the sort of fact an observation cannot supply for itself, and the clearest illustration of
+ * what the two tiers are each worth. A worker on an SDK too old to describe itself declares neither
+ * its workflows nor its steps, so every one of its tokens stays observed and indistinguishable: its
+ * step queues are listed alongside its workflow queues because nothing published says which is
+ * which. That is a fair report of the fleet, not a defect in the read.
+ *
+ * `sanitize` is injected so this module keeps no dependency on the queue layer; a declared name is
+ * covered in its bare token form and, for a partitioned worker, in the suffixed form its queues
+ * actually carry.
+ */
+declare function coveredTokens(announced: readonly AnnouncedWorkflow[], descriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[], sanitize: (name: string) => string): Set<string>;
+
+/**
+ * The workflow directory — {@link ./announced}'s registry plus the thing an empty registry could
+ * never say: WHY it is empty.
+ *
+ * ## The three states an empty list used to collapse
+ *
+ * "What workflows can I call?" has three honest answers, and returning `[]` for all of them is the
+ * bug this module exists to fix. They are not shades of the same answer; they call for three
+ * different actions from whoever asked.
+ *
+ * 1. **This process cannot ask.** No transport here can introspect the advertisement or liveness
+ *    keyspace — a pure in-process pool advertises nothing and scans nothing. Workers may well be
+ *    running; nobody looked. ({@link WorkflowDirectory.supported} is `false`.) The action is to
+ *    configure a transport, or to stop treating this pod's answer as the deployment's answer.
+ * 2. **Nothing is live.** The fleet WAS asked and the fleet is empty. ({@link WorkflowDirectory.supported}
+ *    is `true`, `workflows` is `[]`.) The action is to start a worker.
+ * 3. **Here it is.** ({@link WorkflowDirectory.supported} is `true`, `workflows` is populated.)
+ *
+ * There is a fourth that hides inside the second and is the most expensive to debug, because it
+ * looks exactly like "nobody is running" from the caller's side: **a worker is live on a partition
+ * this engine does not serve.** A worker started with a partition consumes `<token>@<partition>`,
+ * convention resolution computes the token for THIS engine's namespace, misses, and reports absence.
+ * The heartbeat keyspace is shared, so the evidence is right there — and
+ * {@link WorkflowDirectory.otherPartitions} reports it instead of letting the caller conclude that
+ * nothing exists.
+ *
+ * ## Why a sentence rides along
+ *
+ * Every field here is structured and a caller can branch on all of it. {@link WorkflowDirectory.detail}
+ * exists anyway because the three states are only useful if the human reading the picker learns which
+ * one they are in, and a UI that has to re-derive that prose from booleans will re-derive it
+ * differently in each place it is shown. The sentence is written once, next to the logic that decides
+ * which state it is.
+ */
+
+/** The namespace a descriptor or a bare routing token belongs to when it states none. Mirrors
+ *  `tenantGroup`'s default-is-bare rule, so a single-tenant deployment reads as `'default'`
+ *  everywhere rather than as a special case. */
+declare const DEFAULT_PARTITION = "default";
+/** Live workers seen on a partition the asking engine does not serve — the case that otherwise reads
+ *  identically to "nothing is running". */
+interface PartitionSighting {
+    /** The partition suffix carried by the tokens (never this engine's own). */
+    partition: string;
+    /** The routing tokens live on it, as published (sorted). */
+    groups: string[];
+    /** The instance ids beating there (sorted). */
+    instances: string[];
+}
+/** What the live fleet can be asked, and what it answered. See the module docblock for the states. */
+interface WorkflowDirectory {
+    /**
+     * Could this process ask the fleet at all?
+     *
+     * `false` means no transport here can read the advertisement or liveness keyspace, so `workflows`
+     * is empty because nothing was asked — NOT because nothing is running. `true` means the read
+     * happened and `workflows` is the answer, including when it is empty.
+     */
+    supported: boolean;
+    /** Everything callable in this engine's partition, declared and observed alike. */
+    workflows: AnnouncedWorkflow[];
+    /** Live workers on OTHER partitions (empty for an operator engine, which serves them all). */
+    otherPartitions: PartitionSighting[];
+    /** One sentence saying which state this is and what it implies. Written for a human. */
+    detail: string;
+}
+/** The partition a routing token belongs to: the suffix after the LAST `@`, or {@link DEFAULT_PARTITION}
+ *  for a bare token. Matches how `tenantGroup` builds the token and how `workerHealth` takes it apart. */
+declare function partitionOfToken(token: string): string;
+/**
+ * Fold live descriptors and live heartbeats into the directory for one engine.
+ *
+ * `namespace` is the asking engine's, and `undefined` means an operator that serves every partition
+ * ("ver tudo = ausência de namespace"): it filters nothing and reports no foreign partitions, because
+ * none of them are foreign to it. A namespaced engine sees only its own partition's workers, and
+ * everything else it can see is reported as a sighting rather than silently dropped — dropping is
+ * what made a misconfigured partition indistinguishable from an empty fleet.
+ *
+ * Pure and holds nothing: the caller does the two live reads it already knows how to do, folds them
+ * here, and drops the result.
+ */
+declare function buildWorkflowDirectory(input: {
+    descriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[];
+    heartbeats: readonly HeartbeatSighting[];
+    namespace: string | undefined;
+    /** Whether ANY transport in the pool could perform the reads above. */
+    supported: boolean;
+    /** The queue-token form of a workflow name — injected so this module needs no queue dependency. */
+    sanitize: (name: string) => string;
+}): WorkflowDirectory;
 
 /**
  * Bilateral compatibility negotiation between two handshake descriptors (design §7.3/§7.4). Pure
@@ -2702,6 +2935,30 @@ interface SingletonConfig {
      */
     maxQueueDepth?: number;
 }
+/**
+ * Stamped on a run whose workflow version NOBODY declared: a remote resolved by convention, served
+ * by a worker that announces no version for it (an SDK too old to publish a descriptor, or a body
+ * whose author simply never stated one).
+ *
+ * ## Why a run has to carry this
+ *
+ * Such a run's `workflowVersion` is `'1'`, the engine's convention default. That value is a routing
+ * placeholder, not an observation — and read back later it is indistinguishable from a worker that
+ * genuinely declared version `'1'`. Any check comparing an authored pin against it therefore passes
+ * whenever the pin is `'1'` and fails whenever it is not, regardless of what the callee actually is.
+ * A check that cannot fail is worse than no check, because it reads as a guarantee.
+ *
+ * The tag is the difference, carried ON the run so a retrospective check needs no second read: a
+ * caller that pinned a version can see that the version it is comparing against was never stated,
+ * and say so, instead of reporting a match it did not really make. It is deliberately a tag rather
+ * than a new column — every store already persists and queries tags, so this needs no migration and
+ * shows up in run listings and dashboards for free. Follows the `singleton:<key>` precedent for an
+ * engine-stamped reserved tag.
+ *
+ * A run whose callee DOES declare a version never carries it; that run's version is the declared one
+ * and a pin against it is genuinely checked.
+ */
+declare const VERSION_UNDECLARED_TAG = "version:undeclared";
 interface WorkflowEngineDeps {
     store: StateStore;
     /** A single task transport. Shorthand for a one-entry `transports` pool (id `default`). */
@@ -3143,6 +3400,21 @@ declare class WorkflowEngine {
      * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
      */
     private resolveRemoteByConvention;
+    /**
+     * The version the LIVE fleet declares for `workflow` on `group`, or `undefined` when it declares
+     * none — which is a fact about the fleet, not a failure to read it.
+     *
+     * The read is the descriptor advertisement, scoped to the one group being resolved: the workers on
+     * that queue, their `registrations`, the entry whose `name` matches. That is where a version can
+     * come from at all — a heartbeat has no room for one, so a worker on an SDK too old to publish a
+     * descriptor declares nothing and the caller is told so rather than handed a default.
+     *
+     * `undefined` when the announcers DISAGREE, and deliberately: two live workers claiming different
+     * versions of one name is a deployment in the middle of something, and picking either would stamp
+     * a run with a version half the fleet does not serve. Undeclared is the honest reading of a
+     * contradiction, and it is the reading that refuses to let a pin pass on a coin flip.
+     */
+    private declaredVersion;
     /**
      * Walk the parent chain of `childRunId` to the nearest ancestor registered as REMOTE, returning its
      * registration (or `undefined` if there is none). The parent of an awaited child is found via its
@@ -3511,6 +3783,21 @@ declare class WorkflowEngine {
      * Workflows only, and deliberately: see the "steps are out of scope" note in `handshake/announced`.
      */
     announcedWorkflows(): Promise<AnnouncedWorkflow[]>;
+    /**
+     * {@link announcedWorkflows}, plus the thing a list of workflows can never say: why it is the
+     * length it is. See {@link WorkflowDirectory} for the three states an empty array used to collapse
+     * into one — "nobody asked", "nothing is live", and the partition mismatch that reads exactly like
+     * the second from the caller's side.
+     *
+     * Two live reads, both on demand and neither retained: the descriptor advertisement (what workers
+     * SAY they serve) and the heartbeat keyspace (what is demonstrably consuming a queue right now).
+     * The second is why a worker on an SDK too old to publish a descriptor appears here at all — it
+     * beats and never describes itself, and reading only descriptors reported such a fleet as empty
+     * while `resolveRemoteByConvention`, a few lines away in this same class, was routing calls to it
+     * off those very keys. Two answers out of one Redis, disagreeing. Now they agree, and the entry
+     * says which of the two kinds of evidence it rests on rather than flattening them together.
+     */
+    workflowDirectory(): Promise<WorkflowDirectory>;
     /**
      * The routing groups of every in-flight run's still-`pending` remote step — the queues where work is
      * dispatched and awaiting a worker. Folded into {@link workerHealth} so a step waiting on a group
@@ -4090,6 +4377,25 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/**
+ * The origin a facet cell is filed under. An origin that is absent, null, or blank is all the same
+ * thing to an operator — a run no package claims — so they collapse to `null` here. Without this the
+ * "unknown" chip would count only one of those spellings while `origin IS NULL` paging returned
+ * another, and the chip's number would not match the page it opens.
+ */
+declare function facetOrigin(origin: string | null | undefined): string | null;
+/**
+ * Fold `(status, origin)` counts into one cell per pair, normalising origins via {@link facetOrigin}.
+ * Store adapters group in SQL and pipe their rows through this, so every adapter — and the in-memory
+ * store the tests run against — agrees on what lands in the unattributed bucket instead of each
+ * collapsing blanks its own way.
+ */
+declare function mergeRunFacetRows(rows: readonly {
+    status: RunStatus;
+    origin: string | null | undefined;
+    count: number;
+}[]): RunFacetRow[];
+
 /** 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
@@ -4147,6 +4453,12 @@ declare abstract class RunGateway {
      *  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[]>;
     /**
      * 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
@@ -4225,6 +4537,13 @@ interface PayloadCodec {
 declare class CodecStateStore implements StateStore {
     private readonly inner;
     private readonly codec;
+    /**
+     * Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
+     * (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
+     * actually aggregates, so `store.runFacets?.()` still reports absence through the wrapper instead
+     * of resolving to a silently wrong empty result.
+     */
+    readonly runFacets?: (query: RunFacetQuery) => Promise<RunFacetRow[]>;
     constructor(inner: StateStore, codec: PayloadCodec);
     private enc;
     private dec;
@@ -4678,7 +4997,11 @@ declare class InMemoryStateStore implements StateStore {
      * scan `strValue` rows. This is the in-memory analog of the SQL EXISTS on `durable_run_attributes`.
      */
     private candidatesForFilter;
+    /** Every run satisfying `query`'s predicates, unsorted and unpaged — the shared body of
+     *  {@link listRuns} (which then sorts + pages it) and {@link runFacets} (which groups it). */
+    private matching;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -4710,4 +5033,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AttributeFilter, type AttributeOp, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, 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, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, 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 StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, 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, 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, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, 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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, 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, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, 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 RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, 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 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, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, coveredTokens, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };