@dudousxd/nestjs-durable-core 0.67.1 → 0.69.0

package/dist/index.d.ts

@@ -1042,6 +1042,20 @@ interface StateStore {
      * fall back to counting a {@link listRuns} result, which is correct but unbounded.
      */
     runFacets?(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * The distinct values of ONE filter axis over the runs matching `query`, with counts — what a
+     * console's tenant/tag/attribute pickers list instead of asking an operator to type a value blind.
+     *
+     * Scoped by the SAME predicates the list is under (`query`), so the options narrow as the operator
+     * narrows: picking a tenant leaves the tag picker offering only tags that tenant's runs actually
+     * carry, and a picker never offers a value that would return an empty list.
+     *
+     * Bounded by {@link RunValueFacetOptions} — read its `scan` note before trusting a `tag` count.
+     *
+     * Optional: a store that omits it still works — the console falls back to free-text entry for these
+     * filters, which is what it had before pickers existed.
+     */
+    runValueFacets?(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     /**
      * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
@@ -1121,15 +1135,40 @@ type SearchAttributesSchema<A extends SearchAttributes = SearchAttributes> = Sta
  *  workflow declares via `@Workflow({ searchAttributes })`. Feed it straight into `WorkflowCtx<A>`:
  *  `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`. */
 type InferSearchAttributes<S extends StandardSchemaV1<unknown, SearchAttributes>> = StandardSchemaV1.InferOutput<S>;
-type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
-/** One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all. */
-interface AttributeFilter {
+type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+/** One value a search attribute can hold, and so one operand a predicate compares against. */
+type AttributeValue = string | number | boolean;
+/**
+ * One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all.
+ *
+ * The scalar ops carry a single `value`. `in` carries a SET of values matched as OR, and it needs to
+ * exist as its own op because ORing inside ONE predicate is the only way to express "tier is pro or
+ * enterprise": two `eq` predicates on the same key are ANDed like every other pair, which no run can
+ * satisfy. An empty `values` matches nothing, mirroring {@link RunQuery.statuses}.
+ */
+type AttributeFilter = {
     key: string;
-    op: AttributeOp;
-    value: string | number | boolean;
-}
+    op: Exclude<AttributeOp, 'in'>;
+    value: AttributeValue;
+    values?: never;
+} | {
+    key: string;
+    op: 'in';
+    values: AttributeValue[];
+    value?: never;
+};
+/** The single-operand members of {@link AttributeFilter} — every op except the `in` set. */
+type ScalarAttributeFilter = Exclude<AttributeFilter, {
+    op: 'in';
+}>;
 interface RunQuery {
     workflow?: string | undefined;
+    /**
+     * Match any of these workflows (`workflow IN (...)`). Same shape as {@link statuses}: ORed with
+     * each other, ANDed with everything else, and further narrowed by a concurrent single `workflow`.
+     * Empty array = matches nothing.
+     */
+    workflows?: string[] | undefined;
     status?: RunStatus | undefined;
     /**
      * Match any of these statuses (a `status IN (...)` filter). ORed together, and ANDed with the other
@@ -1141,6 +1180,13 @@ interface RunQuery {
     statuses?: RunStatus[] | undefined;
     /** Only runs carrying this tag (exact match against {@link WorkflowRun.tags}). */
     tag?: string | undefined;
+    /**
+     * Only runs carrying ANY of these tags. A run's tags are already a set, so the useful multi-value
+     * question is "in this set", not "has all of them" — an operator picking `etl` and `nightly` from a
+     * facet list means the union, and asking for their intersection through this field would return
+     * nothing for tags that never co-occur. ANDed with a concurrent single `tag`; empty = matches nothing.
+     */
+    tags?: string[] | undefined;
     /**
      * Typed/range predicates over {@link WorkflowRun.searchAttributes}, ANDed together (e.g. `amount`
      * >= 200 and `tier` = 'pro'). Applied in-process after the coarse filters, so pair with
@@ -1149,6 +1195,9 @@ interface RunQuery {
     attributes?: AttributeFilter[] | undefined;
     /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
     namespace?: string | undefined;
+    /** Restrict to runs in ANY of these namespaces (`namespace IN (...)`), so a console can compare a
+     *  few tenants side by side. ANDed with a concurrent single `namespace`; empty = matches nothing. */
+    namespaces?: string[] | undefined;
     /**
      * Restrict to runs whose workflow was declared by this package (exact match against
      * {@link WorkflowRun.origin}), ANDed with the other predicates.
@@ -1160,6 +1209,13 @@ interface RunQuery {
      * facet without having to hold every run in the browser to find them.
      */
     origin?: string | null | undefined;
+    /**
+     * Restrict to runs from ANY of these origins. `null` is a member like any other — it selects the
+     * unattributed bucket — so `['@acme/billing', null]` is "this package's runs plus the ones nothing
+     * could attribute", which the single {@link origin} cannot express at all. ANDed with a concurrent
+     * single `origin`; empty = matches nothing.
+     */
+    origins?: Array<string | null> | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -1181,6 +1237,46 @@ interface RunFacetRow {
     origin: string | null;
     count: number;
 }
+/**
+ * Which axis {@link StateStore.runValueFacets} enumerates the distinct VALUES of. Every member is an
+ * axis {@link RunQuery} can then filter by, which is the point: the answer to "what can I pick here"
+ * has to be spendable as a predicate, or a console is offering choices that return nothing.
+ *
+ * `attributeKey` lists the search-attribute keys in use (the left-hand side of a predicate);
+ * `attributeValue` lists the values recorded under ONE key (its right-hand side).
+ */
+type RunValueAxis = {
+    field: 'workflow' | 'status' | 'origin' | 'namespace' | 'tag' | 'attributeKey';
+} | {
+    field: 'attributeValue';
+    key: string;
+};
+/**
+ * One distinct value of a {@link RunValueAxis} and how many of the matching runs carry it — the rows
+ * behind a console's value picker. `value` is `null` only where the axis itself has an absent bucket
+ * (a run with no `origin`); a count is never zero, since a value with no runs produces no row.
+ */
+interface RunValueFacetRow {
+    value: string | null;
+    count: number;
+}
+/**
+ * How much of the store {@link StateStore.runValueFacets} may read to answer.
+ *
+ * `limit` bounds the ROWS RETURNED (highest count first): tag and attribute-value cardinality is
+ * unbounded in principle — a run tagged `singleton:<key>` mints a new tag per key — so a picker asks
+ * for the top slice rather than the whole domain, and keeps free text for everything else.
+ *
+ * `scan` bounds the RUNS READ, and applies to the axes whose values are not a column of the run row
+ * being counted — `tag` (inside a JSON array column) and the two attribute axes (a side table). Those
+ * report counts over the newest `scan` matching runs rather than over all of them: a bounded,
+ * deliberately approximate answer, where the alternative is a full scan on every keystroke. The
+ * column axes (`workflow`, `status`, `origin`, `namespace`) are exact and ignore `scan`.
+ */
+interface RunValueFacetOptions {
+    limit?: number | undefined;
+    scan?: number | undefined;
+}
 /** The transaction handle `StateStore.transaction` hands to its work callback. */
 interface StoreTransaction {
     /** The store-native transaction handle (TypeORM `EntityManager`, Prisma tx client, MikroORM `EntityManager`,
@@ -1247,6 +1343,11 @@ type RunRequestKind = {
 } | {
     kind: 'runFacets';
     query: RunFacetQuery;
+} | {
+    kind: 'runValueFacets';
+    axis: RunValueAxis;
+    query: RunFacetQuery;
+    opts?: RunValueFacetOptions | undefined;
 } | {
     kind: 'workerHealth';
 } | {
@@ -4396,6 +4497,62 @@ declare function mergeRunFacetRows(rows: readonly {
     count: number;
 }[]): RunFacetRow[];
 
+/** Rows a value picker gets when the caller names no bound — enough to fill a dropdown several times
+ *  over, small enough that an axis with unbounded cardinality (tags) can't return a listing. */
+declare const RUN_VALUE_FACET_LIMIT = 100;
+/** Runs read when an axis has to be counted in-process (see {@link RunValueFacetOptions.scan}). */
+declare const RUN_VALUE_FACET_SCAN = 5000;
+/**
+ * Tag prefixes the ENGINE mints one of PER KEY — `singleton:<key>` is stamped on every run of a
+ * singleton workflow so the admission gate can find its siblings.
+ *
+ * A picker ranks these last. They are machine bookkeeping with cardinality that grows with the data,
+ * and on a real deployment they crowd out everything an operator would actually choose: measured on
+ * a 12k-run control plane, 82 of the top 100 tags were `singleton:*`, pushing genuine tags like
+ * `type:mvr` to the edge of the list and past it.
+ *
+ * Ranked, not REMOVED: a singleton tag is still a legitimate thing to filter by (a run row's tag chip
+ * sets exactly that), so it stays offered — just after the tags a human wrote. `version:undeclared`
+ * is engine-minted too but is a single fixed value, so it competes fairly and is not listed here.
+ */
+declare const ENGINE_MINTED_TAG_PREFIXES: readonly ["singleton:"];
+/** Is this a tag the engine mints one of per key? See {@link ENGINE_MINTED_TAG_PREFIXES}. */
+declare function isEngineMintedTag(value: string | null): boolean;
+/**
+ * Is this axis a plain column on the runs table, and so countable with a `GROUP BY` over the whole
+ * matching set?
+ *
+ * The other three are not, in the same way for the same reason — the value isn't in a column of the
+ * row being counted. A run's tags live inside ONE json array column that no `GROUP BY` portable
+ * across sqlite/MySQL/Postgres reaches into, and its search attributes live in a side table whose
+ * join back to the filtered run set differs per adapter. Those axes are counted in-process over a
+ * bounded scan instead ({@link runValueFacetsFromRuns}), so their counts describe that window rather
+ * than the whole store — which is why {@link RunValueFacetOptions.scan} exists.
+ */
+declare function axisIsRunColumn(axis: RunValueAxis): axis is {
+    field: 'workflow' | 'status' | 'origin' | 'namespace';
+};
+/**
+ * Fold, order and bound raw `(value, count)` rows into the answer callers see: highest count first,
+ * ties broken alphabetically so a picker's order is stable between polls, the unattributed bucket
+ * (`null`) last, and no more than `limit` rows.
+ *
+ * Every store pipes its `GROUP BY` through this — the same role {@link mergeRunFacetRows} plays for
+ * status/origin counts — so a picker lists the same values in the same order whichever adapter is
+ * underneath, rather than each SQL dialect's default ordering leaking into the UI.
+ */
+declare function mergeRunValueFacetRows(rows: readonly {
+    value: string | null | undefined;
+    count: number;
+}[], opts?: RunValueFacetOptions): RunValueFacetRow[];
+/**
+ * Count an axis's distinct values across runs already narrowed by the caller's predicates — the
+ * in-process path, used by the in-memory store for every axis and by the SQL stores for `tag` (see
+ * {@link axisIsGroupable}). `runs` must be ordered newest-first and already bounded to
+ * {@link RunValueFacetOptions.scan}, since that window is what the counts then describe.
+ */
+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
@@ -4459,6 +4616,16 @@ declare abstract class RunGateway {
      * 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
@@ -4544,6 +4711,12 @@ declare class CodecStateStore implements StateStore {
      * of resolving to a silently wrong empty result.
      */
     readonly runFacets?: (query: RunFacetQuery) => Promise<RunFacetRow[]>;
+    /**
+     * Forwarded verbatim, and safe to: the axes a value facet enumerates are searchable metadata
+     * (workflow, status, origin, namespace, tags, search attributes), none of which the codec encodes.
+     * Bound the same conditional way as {@link runFacets} so absence is reported, not faked.
+     */
+    readonly runValueFacets?: (axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions) => Promise<RunValueFacetRow[]>;
     constructor(inner: StateStore, codec: PayloadCodec);
     private enc;
     private dec;
@@ -4772,16 +4945,39 @@ interface RunAttributeRow {
  * in-process `compare` treats `eq`/`ne` on booleans). Returns `[]` for a run with no attributes.
  */
 declare function normalizeAttributeRows(runId: string, attributes: SearchAttributes | undefined): RunAttributeRow[];
-/** SQL comparison operator for an {@link AttributeOp} (used to build pushdown predicates). */
-declare function sqlComparator(op: AttributeOp): string;
+/**
+ * SQL comparison operator for a single-operand {@link AttributeOp} (used to build pushdown
+ * predicates). `in` is absent by construction: it compares against a SET, which a store emits as an
+ * OR of equalities over {@link attributePredicateOperands} rather than as one comparator.
+ */
+declare function sqlComparator(op: Exclude<AttributeOp, 'in'>): string;
 /**
  * Which side-table column an attribute filter compares against: numeric operands (and range ops on
  * numbers) hit `numValue`; everything else hits `strValue` (booleans are stored as `"true"`/`"false"`).
  * Keeping this in core means every SQL adapter pushes predicates down identically.
  */
-declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strValue';
+declare function attributeColumnFor(filter: ScalarAttributeFilter): 'numValue' | 'strValue';
 /** The literal a side-table predicate compares against (booleans → `"true"`/`"false"` strings). */
-declare function attributeOperand(filter: AttributeFilter): string | number;
+declare function attributeOperand(filter: ScalarAttributeFilter): string | number;
+/** One comparison a side-table predicate makes: which typed column, with which operator, against
+ *  which literal. */
+interface AttributePredicateOperand {
+    column: 'numValue' | 'strValue';
+    comparator: string;
+    operand: string | number;
+}
+/**
+ * The comparisons one {@link AttributeFilter} makes, for a store to OR together inside its
+ * `EXISTS`/join on the normalized attribute side-table. A scalar op yields exactly ONE comparison
+ * (the same column/operator/literal {@link attributeColumnFor} and {@link attributeOperand} give);
+ * `in` yields one per member, each an equality, since its operands may be of mixed types and so land
+ * in different typed columns.
+ *
+ * An EMPTY list is a real answer, not a missing one: `in` over no values can match no run. A caller
+ * that ORs an empty list must emit a false predicate rather than dropping the filter, or the query
+ * silently widens to every run.
+ */
+declare function attributePredicateOperands(filter: AttributeFilter): AttributePredicateOperand[];
 
 /**
  * Read a run's `searchAttributes` through a {@link SearchAttributesSchema}, typed to the schema's
@@ -5002,6 +5198,10 @@ declare class InMemoryStateStore implements StateStore {
     private matching;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /** Counted over the newest `scan` matching runs for EVERY axis, not just `tag`: this store holds
+     *  its runs in a Map with no index to group by, so the bound that the SQL stores need only for tags
+     *  is the honest one to apply here throughout. */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -5033,4 +5233,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 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 };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, 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, 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, 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, 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, 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 RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, 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, attributePredicateOperands, axisIsRunColumn, 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, isEngineMintedTag, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.js

@@ -6000,6 +6000,86 @@ function mergeRunFacetRows(rows) {
 }
 __name(mergeRunFacetRows, "mergeRunFacetRows");
 
+// src/run-value-facets.ts
+var RUN_VALUE_FACET_LIMIT = 100;
+var RUN_VALUE_FACET_SCAN = 5e3;
+var ENGINE_MINTED_TAG_PREFIXES = [
+  "singleton:"
+];
+function isEngineMintedTag(value) {
+  return value !== null && ENGINE_MINTED_TAG_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+__name(isEngineMintedTag, "isEngineMintedTag");
+function axisIsRunColumn(axis) {
+  return axis.field === "workflow" || axis.field === "status" || axis.field === "origin" || axis.field === "namespace";
+}
+__name(axisIsRunColumn, "axisIsRunColumn");
+function valuesOf(run, axis) {
+  switch (axis.field) {
+    case "workflow":
+      return [
+        run.workflow
+      ];
+    case "status":
+      return [
+        run.status
+      ];
+    case "origin":
+      return [
+        facetOrigin(run.origin)
+      ];
+    case "namespace":
+      return run.namespace === void 0 ? [] : [
+        run.namespace
+      ];
+    case "tag":
+      return run.tags ?? [];
+    case "attributeKey":
+      return Object.keys(run.searchAttributes ?? {});
+    case "attributeValue": {
+      const value = run.searchAttributes?.[axis.key];
+      return value === void 0 ? [] : [
+        String(value)
+      ];
+    }
+  }
+}
+__name(valuesOf, "valuesOf");
+function mergeRunValueFacetRows(rows, opts) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const value = row.value ?? null;
+    counts.set(value, (counts.get(value) ?? 0) + Number(row.count));
+  }
+  const merged = [
+    ...counts
+  ].map(([value, count]) => ({
+    value,
+    count
+  })).filter((row) => row.count > 0).sort((a, b) => {
+    const engineA = isEngineMintedTag(a.value);
+    const engineB = isEngineMintedTag(b.value);
+    if (engineA !== engineB) return engineA ? 1 : -1;
+    if (b.count !== a.count) return b.count - a.count;
+    if (a.value === null) return 1;
+    if (b.value === null) return -1;
+    return a.value.localeCompare(b.value);
+  });
+  return merged.slice(0, opts?.limit ?? RUN_VALUE_FACET_LIMIT);
+}
+__name(mergeRunValueFacetRows, "mergeRunValueFacetRows");
+function runValueFacetsFromRuns(runs, axis, opts) {
+  const rows = [];
+  for (const run of runs) {
+    for (const value of valuesOf(run, axis)) rows.push({
+      value,
+      count: 1
+    });
+  }
+  return mergeRunValueFacetRows(rows, opts);
+}
+__name(runValueFacetsFromRuns, "runValueFacetsFromRuns");
+
 // src/run-gateway.ts
 var RunGateway = class {
   static {
@@ -6021,11 +6101,21 @@ var CodecStateStore = class {
   * of resolving to a silently wrong empty result.
   */
   runFacets;
+  /**
+  * Forwarded verbatim, and safe to: the axes a value facet enumerates are searchable metadata
+  * (workflow, status, origin, namespace, tags, search attributes), none of which the codec encodes.
+  * Bound the same conditional way as {@link runFacets} so absence is reported, not faked.
+  */
+  runValueFacets;
   constructor(inner, codec) {
     this.inner = inner;
     this.codec = codec;
     const facets = inner.runFacets;
     if (facets) this.runFacets = (query) => facets.call(inner, query);
+    const valueFacets = inner.runValueFacets;
+    if (valueFacets) {
+      this.runValueFacets = (axis, query, opts) => valueFacets.call(inner, axis, query, opts);
+    }
   }
   enc(v) {
     return v === void 0 ? void 0 : this.codec.encode(v);
@@ -6380,8 +6470,10 @@ async function runSchedules(engine, schedules, nowMs, opts) {
 __name(runSchedules, "runSchedules");
 
 // src/search-attributes.ts
-function compare(actual, op, expected) {
-  switch (op) {
+function compare(actual, filter) {
+  if (filter.op === "in") return filter.values.some((v) => actual === v);
+  const expected = filter.value;
+  switch (filter.op) {
     case "eq":
       return actual === expected;
     case "ne":
@@ -6400,7 +6492,7 @@ __name(compare, "compare");
 function matchesAttributes(attributes, filters) {
   if (!filters?.length) return true;
   if (!attributes) return false;
-  return filters.every((f) => f.key in attributes && compare(attributes[f.key], f.op, f.value));
+  return filters.every((f) => f.key in attributes && compare(attributes[f.key], f));
 }
 __name(matchesAttributes, "matchesAttributes");
 function applyAttributeQuery(rows, query) {
@@ -6466,6 +6558,30 @@ function attributeOperand(filter) {
   return filter.value;
 }
 __name(attributeOperand, "attributeOperand");
+function attributePredicateOperands(filter) {
+  if (filter.op === "in") {
+    return filter.values.map((value) => {
+      const scalar = {
+        key: filter.key,
+        op: "eq",
+        value
+      };
+      return {
+        column: attributeColumnFor(scalar),
+        comparator: "=",
+        operand: attributeOperand(scalar)
+      };
+    });
+  }
+  return [
+    {
+      column: attributeColumnFor(filter),
+      comparator: sqlComparator(filter.op),
+      operand: attributeOperand(filter)
+    }
+  ];
+}
+__name(attributePredicateOperands, "attributePredicateOperands");
 
 // src/search-attributes-schema.ts
 function readSearchAttributes(schema, run) {
@@ -6693,33 +6809,27 @@ var InMemoryStateStore = class {
     const byRun = this.attributeIndex.get(f.key);
     const out = /* @__PURE__ */ new Set();
     if (!byRun) return out;
-    const numeric = typeof f.value === "number";
-    const operand = typeof f.value === "boolean" ? f.value ? "true" : "false" : f.value;
+    const comparisons = attributePredicateOperands(f);
     for (const row of byRun.values()) {
-      const actual = numeric ? row.numValue : row.strValue;
-      if (actual == null) continue;
-      let ok = false;
-      switch (f.op) {
-        case "eq":
-          ok = actual === operand;
-          break;
-        case "ne":
-          ok = actual !== operand;
-          break;
-        case "gt":
-          ok = actual > operand;
-          break;
-        case "gte":
-          ok = actual >= operand;
-          break;
-        case "lt":
-          ok = actual < operand;
-          break;
-        case "lte":
-          ok = actual <= operand;
-          break;
-      }
-      if (ok) out.add(row.runId);
+      const matched = comparisons.some(({ column, comparator, operand }) => {
+        const actual = column === "numValue" ? row.numValue : row.strValue;
+        if (actual == null) return false;
+        switch (comparator) {
+          case "=":
+            return actual === operand;
+          case "<>":
+            return actual !== operand;
+          case ">":
+            return actual > operand;
+          case ">=":
+            return actual >= operand;
+          case "<":
+            return actual < operand;
+          default:
+            return actual <= operand;
+        }
+      });
+      if (matched) out.add(row.runId);
     }
     return out;
   }
@@ -6730,12 +6840,20 @@ var InMemoryStateStore = class {
       ...this.runs.values()
     ];
     if (query.workflow) runs = runs.filter((r) => r.workflow === query.workflow);
+    if (query.workflows) runs = runs.filter((r) => query.workflows?.includes(r.workflow));
     if (query.status) runs = runs.filter((r) => r.status === query.status);
     if (query.statuses) runs = runs.filter((r) => query.statuses?.includes(r.status));
     if (query.tag) runs = runs.filter((r) => r.tags?.includes(query.tag));
+    if (query.tags) runs = runs.filter((r) => r.tags?.some((t) => query.tags?.includes(t)));
     if (query.namespace !== void 0) runs = runs.filter((r) => r.namespace === query.namespace);
+    if (query.namespaces) {
+      runs = runs.filter((r) => r.namespace !== void 0 && query.namespaces?.includes(r.namespace));
+    }
     if (query.origin === null) runs = runs.filter((r) => r.origin == null);
     else if (query.origin !== void 0) runs = runs.filter((r) => r.origin === query.origin);
+    if (query.origins) {
+      runs = runs.filter((r) => query.origins?.includes(r.origin ?? null));
+    }
     if (query.attributes?.length) {
       let candidates = null;
       for (const f of query.attributes) {
@@ -6772,6 +6890,16 @@ var InMemoryStateStore = class {
       count: 1
     })));
   }
+  /** Counted over the newest `scan` matching runs for EVERY axis, not just `tag`: this store holds
+  *  its runs in a Map with no index to group by, so the bound that the SQL stores need only for tags
+  *  is the honest one to apply here throughout. */
+  async runValueFacets(axis, query, opts) {
+    const runs = await this.listRuns({
+      ...query,
+      limit: opts?.scan ?? RUN_VALUE_FACET_SCAN
+    });
+    return runValueFacetsFromRuns(runs, axis, opts);
+  }
   async listCheckpoints(runId) {
     const rows = [
       ...this.checkpoints.values()
@@ -6859,6 +6987,7 @@ export {
   DURABLE_STEP_CONFIG,
   DURABLE_STEP_NAME,
   DurableWorkflow,
+  ENGINE_MINTED_TAG_PREFIXES,
   EVENT_BUFFER_SCAN_LIMIT,
   EVENT_TOKEN_PREFIX,
   Entities,
@@ -6872,6 +7001,8 @@ export {
   LEGACY_V1_PROTOCOL,
   NonDeterminismError,
   QueueController,
+  RUN_VALUE_FACET_LIMIT,
+  RUN_VALUE_FACET_SCAN,
   RemoteStepError,
   RemoteStepTimeout,
   RemoteWorkflowExecutor,
@@ -6894,6 +7025,8 @@ export {
   applyAttributeQuery,
   attributeColumnFor,
   attributeOperand,
+  attributePredicateOperands,
+  axisIsRunColumn,
   bindWorkflowClass,
   breakpointToken,
   buildWorkflowDirectory,
@@ -6921,12 +7054,14 @@ export {
   heartbeatStatus,
   indexWaitersByRun,
   info,
+  isEngineMintedTag,
   isEventToken,
   isLegacyDescriptor,
   isWorkflowControlFlowSignal,
   log,
   matchesAttributes,
   mergeRunFacetRows,
+  mergeRunValueFacetRows,
   missingCapabilities,
   negotiate,
   normalizeAttributeRows,
@@ -6945,6 +7080,7 @@ export {
   runInWorkflowCtx,
   runSchedules,
   runStepHandler,
+  runValueFacetsFromRuns,
   sanitizeQueueToken,
   scheduledRunId,
   sqlComparator,