@adonis-agora/durable 0.49.0 → 0.50.0

package/dist/src/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.49.0';
+export const VERSION = '0.50.0';
 // Re-export the configure hook from the package root so `node ace configure` finds it.
 // AdonisJS imports the package MAIN and reads `configure` off the module namespace —
 // the `./configure` subpath alone is never consulted.
@@ -8,6 +8,7 @@ export { configure } from '../configure.js';
 export * from './admission.js';
 // --- config-driven admission drivers ----------------------------------------
 export { admissions } from './admissions/factory.js';
+export { currentStep } from './ambient-step.js';
 export { BaseWorkflow, setWorkflowEngineResolver, } from './base-workflow.js';
 export * from './codec-state-store.js';
 // --- ace command building blocks --------------------------------------------
@@ -22,6 +23,7 @@ export { controlPlanes } from './control-planes/factory.js';
 // --- AdonisJS integration ---------------------------------------------------
 export { defineConfig } from './define_config.js';
 export * from './diagnostics-bridge.js';
+export { DuplicateDiscoveryError, } from './discovery-roots.js';
 export * from './dispatch-routing.js';
 export * from './duration.js';
 export * from './engine.js';
@@ -34,6 +36,7 @@ export { childIdsOf, parentRunIdOf } from './fan-join.js';
 // --- store-less cluster: handshake & capability negotiation -----------------
 export * from './handshake/announced.js';
 export * from './handshake/descriptor.js';
+export * from './handshake/directory.js';
 export * from './handshake/negotiate.js';
 export * from './handshake/routing.js';
 export * from './interfaces.js';
@@ -43,10 +46,12 @@ export * from './on-error.js';
 export * from './pollers.js';
 export * from './protocol.js';
 export * from './queue.js';
+export { isRemoteEvent } from './remote-event.js';
 export * from './remote-workflow-executor.js';
 export * from './run-detail-summary.js';
+export * from './run-facets.js';
 export { ProxyRunGateway, } from './run-gateway/proxy-run-gateway.js';
-export { RunRequestResponder, } from './run-gateway/run-request-responder.js';
+export { RunRequestResponder, UNSUPPORTED_RUN_REQUEST, } from './run-gateway/run-request-responder.js';
 export { StoreRunGateway, } from './run-gateway/store-run-gateway.js';
 export { hmacTenantVerifier, signTenantToken } from './run-gateway/tenant-auth.js';
 export * from './run-pagination.js';
@@ -55,13 +60,17 @@ export * from './run-waiting.js';
 export * from './scheduler.js';
 export * from './schedules.js';
 export * from './search-attributes.js';
+export * from './search-attributes-schema.js';
+export * from './singleton-admission.js';
+export * from './standard-schema.js';
 export * from './step-discovery.js';
 export { DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, stepConfigOf, stepNameOf, } from './step-name-symbol.js';
 export * from './step-ref.js';
 // --- config-driven state-store drivers --------------------------------------
 export { stores } from './stores/factory.js';
 export { LucidStateStore } from './stores/lucid.js';
-export { createDurableTables, DURABLE_TABLES, dropDurableTables, } from './stores/lucid-schema.js';
+export { onCorruptJsonColumn, } from './stores/lucid-mappers.js';
+export { createDurableTables, DURABLE_JSON_COLUMNS, DURABLE_SCHEMA_META_TABLE, DURABLE_SCHEMA_REVISION, DURABLE_TABLES, dropDurableTables, } from './stores/lucid-schema.js';
 export * from './tenant-group.js';
 export { InMemoryStateStore } from './testing/in-memory-state-store.js';
 export { InMemoryTransport } from './testing/in-memory-transport.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/interfaces.d.ts

@@ -1,7 +1,7 @@
-import type { z } from 'zod';
 import type { DispatchDiagnostics } from './dispatch-routing.js';
 import type { WorkerDescriptor } from './handshake/descriptor.js';
 import type { FanPageQuery, RunDetailOptions } from './run-detail-summary.js';
+import type { StandardSchemaV1 } from './standard-schema.js';
 import type { StepRef } from './step-name-symbol.js';
 import type { WorkflowClass, WorkflowInputOf, WorkflowOutputOf } from './workflow-ref.js';
 /**
@@ -73,6 +73,17 @@ export interface WorkflowRun {
      * durable state required for correctness — a transport without priority support ignores it.
      */
     priority?: number | undefined;
+    /**
+     * REMOTE workflow turn awaiting a decision: the globally unique `taskId` of the turn the engine
+     * dispatched to a workflow worker and then SUSPENDED on. Written BEFORE the turn is enqueued (and the
+     * run lease released), matched by the engine's decision handler so ONLY the decision for the
+     * currently-awaited turn is applied (a stale / duplicate / foreign decision is dropped), and cleared
+     * the moment that decision is applied. This is what makes a workflow-turn decision multi-instance
+     * safe: whichever engine replica consumes the decision looks the run up by `decision.runId` and
+     * applies it durably, instead of resolving an in-memory promise only the dispatching replica held.
+     * Absent on non-remote runs and on runs not currently awaiting a turn.
+     */
+    awaitingDecisionTaskId?: string | undefined;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -298,6 +309,26 @@ export interface StateStore {
      * outcome was still being computed from a now-stale run snapshot.
      */
     updateRunIf(runId: string, expectedStatuses: RunStatus[], patch: Partial<WorkflowRun>): Promise<boolean>;
+    /**
+     * Atomically claim a singleton slot for `runId` — the store half of the `singleton` gate. Required
+     * for ATOMIC singleton admission; without it the engine falls back to a non-atomic scan and warns once.
+     *
+     * Inside ONE critical section that serializes competing claims BEFORE it reads (a transaction with
+     * `SELECT … FOR UPDATE`, or a write lock taken first; a plain list-then-update is unsafe across
+     * engine instances): read the active (`pending`/`running`/`suspended`/`blocked`) runs of `workflow`
+     * carrying `tag`, then decide with {@link singletonAdmissionTags} — runs already carrying the
+     * reserved `durable:singleton:admitted` tag keep their slots, and the free ones go to the oldest
+     * unadmitted waiters by `(createdAt, id)`. On admission persist the returned tags and return `true`
+     * (also `true`, without a write, when the run already holds a slot).
+     *
+     * On denial, when `retryWakeAt` is given, park the candidate `suspended` with that `wakeAt` under the
+     * same locks ({@link singletonAdmissionDenialPatch}), and never write a run that is no longer active
+     * (a concurrent cancel must not be resurrected). Return `false` for a missing or inactive run.
+     *
+     * The slot is released by the terminal settle: `updateRun`/`updateRunIf` writing a terminal status
+     * must drop the reserved tag. An expired execution lease never releases it.
+     */
+    tryAdmitSingleton?(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
     getRun(runId: string): Promise<WorkflowRun | null>;
     /**
      * Hard-delete a run and everything tied to it (its checkpoints, signal waiters, and search-attribute
@@ -305,6 +336,15 @@ export interface StateStore {
      * engine's {@link WorkflowEngine.deleteRun} handles the child-subtree cascade.
      */
     deleteRun(runId: string): Promise<void>;
+    /**
+     * {@link deleteRun} for a batch of runs: every id's checkpoints, signal waiters, attribute rows and
+     * run row, as a few `IN (...)` statements in one transaction instead of four statements per run.
+     * Unknown ids are ignored. Like {@link deleteRun} it removes exactly the listed runs; the engine's
+     * `purgeRuns` and retention sweep walk the child edges first.
+     *
+     * Optional: a store that omits it gets one {@link deleteRun} per id.
+     */
+    deleteRuns?(runIds: string[]): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -321,6 +361,16 @@ export interface StateStore {
      * Optional: a store that omits it falls back to {@link saveCheckpoint}, which keeps that race.
      */
     saveCheckpointIfPending?(checkpoint: StepCheckpoint): Promise<boolean>;
+    /**
+     * {@link saveCheckpointIfPending} for many checkpoints in one call: resolves, per entry and in
+     * input order, whether it wrote. Same result as calling it on each entry in turn (a later entry for
+     * the same `(runId, seq)` is compared against the earlier one's write), with each row's
+     * compare-and-set still atomic. The call as a whole is atomic too: if it rejects, nothing was
+     * written. The engine settles a batch of one run's step results through it, one call per batch.
+     *
+     * Optional: a store that omits it gets one {@link saveCheckpointIfPending} per entry.
+     */
+    saveCheckpointsIfPending?(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
     /**
      * Used by recovery on boot to find runs to resume (crashed, left `running`). When `namespace` is
      * given, restrict to runs in that worker-pool partition (ANDed); omit it to return all (back-compat).
@@ -332,8 +382,15 @@ export interface StateStore {
      * without it the engine falls back to {@link listIncompleteRuns} and filters in process, which on
      * a busy fleet fetches (and lock-probes) every healthy running run once per tick per worker. When
      * `namespace` is given, restrict to that worker-pool partition (ANDed).
+     *
+     * When `owner` is given, ALSO return `running` runs whose lease is still live but held by `owner`
+     * (`locked_by = owner`, ORed with the free/expired predicate). The engine passes its own
+     * `instanceId` for one lease window after boot, so an instance that restarts under a stable id
+     * (a pod name) after a crash reclaims the leases its previous incarnation left behind at once,
+     * instead of waiting up to `leaseMs` for them to expire; the engine itself filters out the runs
+     * the live process is executing. A store that ignores `owner` keeps the expiry-only behaviour.
      */
-    listOrphanedRuns?(nowMs: number, limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listOrphanedRuns?(nowMs: number, limit: number, namespace?: string, owner?: string): Promise<WorkflowRun[]>;
     /**
      * The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. When
      * `namespace` is given, restrict to runs in that worker-pool partition (ANDed); omit it for all.
@@ -435,6 +492,13 @@ export interface StateStore {
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
     } | null>;
+    /**
+     * Up to `limit` distinct tokens starting with `prefix` that have at least one buffered signal.
+     * Reads no payload and consumes nothing. Optional: the entity lost-wake reconcile
+     * (`engine.reconcileEntityWakes`) uses it to find entity ops buffered while no wake reached their
+     * entity; without it that reconcile is a no-op.
+     */
+    listBufferedSignalTokens?(prefix: string, limit: number): Promise<string[]>;
     /**
      * Buffer a published event that matched NO live waiter, so a LATER `ctx.waitForEvent(name, { match })`
      * still consumes it instead of it being silently dropped — the events analog of {@link bufferSignal}'s
@@ -468,6 +532,15 @@ export interface StateStore {
      * returns `true` is the one that gets to deliver the payload; every other caller backs off.
      */
     removeBufferedEvent(id: string): Promise<boolean>;
+    /**
+     * Delete up to `limit` buffered events published before `publishedBefore` (epoch ms), oldest
+     * first, across every name; resolves how many it deleted. What the engine's `eventBufferTtlMs`
+     * prune calls, so an event nobody ever waits for does not stay in the table forever.
+     *
+     * Optional: without it the prune has no way to enumerate names, and expired events are only skipped
+     * (and removed) when a `waitForEvent` for their name scans them.
+     */
+    pruneBufferedEvents?(publishedBefore: number, limit: number): Promise<number>;
     /**
      * Run `work` in a SINGLE store transaction — giving it the store-native transaction handle (`raw`)
      * for the caller's own DB writes plus a `saveCheckpoint` that commits IN THE SAME transaction, so a
@@ -483,6 +556,15 @@ export interface StateStore {
      * Optional: without it the engine counts a {@link listRuns} result.
      */
     countRuns?(query: Omit<RunQuery, 'page' | 'size'>): Promise<number>;
+    /**
+     * 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 listing counted in memory. Cells with a
+     * zero count are absent; a run with no (or a blank) origin counts under `origin: null`.
+     *
+     * Optional: without it `runFacetsOf` counts a {@link listRuns} result, which is correct but
+     * unbounded.
+     */
+    runFacets?(query: RunFacetQuery): Promise<RunFacetRow[]>;
     /** Insert or fully replace the schedule `record.id`. */
     saveSchedule?(record: ScheduleRecord): Promise<void>;
     /** The schedule `id`, or null. */
@@ -554,9 +636,115 @@ export interface StateStore {
      * and counts in JS, which loads the whole run on every result of a fan.
      */
     countCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
+    /**
+     * The run's checkpoints aggregated into {@link CheckpointStat} buckets — one per
+     * `(parallelGroup, status, nameKind)` present — with `opts.group` narrowing it to one group. A
+     * `GROUP BY`, not a load: it is what lets a run detail draw a 40,000-member fan from a few rows.
+     * Ungrouped checkpoints come back under `group: null`. Bucket order is unspecified.
+     *
+     * Optional: a store that omits it still works — the run detail then loads every checkpoint and
+     * summarizes it in JS (`summarizeTimeline`), which is the same answer read the expensive way. A
+     * store that implements it must implement {@link queryCheckpoints} too.
+     */
+    checkpointStats?(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /**
+     * The run's checkpoints that match `query`, in `seq` order (the order of {@link listCheckpoints}),
+     * paged by `offset`/`limit`. Every filter is optional; an absent one does not narrow. An EMPTY
+     * `statuses` or `namePrefixes` matches nothing; an empty `excludeGroups` excludes nothing.
+     *
+     * Optional, paired with {@link checkpointStats}: the run detail reads a fan's failures, its folded
+     * checkpoints and one page of its members through it, instead of the run's whole history.
+     */
+    queryCheckpoints?(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
+}
+/**
+ * How a checkpoint's name classifies it, for {@link CheckpointStat}: an awaited child's
+ * `signal:child:` checkpoint, a folded `fan:` checkpoint standing for many children, a `spawn:`
+ * edge to a fire-and-forget child, or any other step.
+ */
+export type CheckpointNameKind = 'child' | 'folded' | 'spawn' | 'step';
+/** The {@link CheckpointNameKind} of a checkpoint name — what a store's SQL `CASE` must agree with. */
+export declare function checkpointNameKind(name: string): CheckpointNameKind;
+/**
+ * One bucket of {@link StateStore.checkpointStats}: the checkpoints of one run sharing a
+ * `parallelGroup`, a `status` and a {@link CheckpointNameKind}, reduced to aggregates.
+ */
+export interface CheckpointStat {
+    /** The bucket's `parallelGroup`, or `null` for ungrouped checkpoints. */
+    group: string | null;
+    status: StepCheckpoint['status'];
+    nameKind: CheckpointNameKind;
+    /** Rows in the bucket (at least 1). */
+    count: number;
+    minSeq: number;
+    maxSeq: number;
+    /** Smallest and largest `name`, by the database's string order. Equal when every row shares one. */
+    minName: string;
+    maxName: string;
+    /** Earliest `enqueuedAt`, read as {@link StateStore.listCheckpoints} reads it (falling back to `startedAt`). */
+    minEnqueuedAt: Date;
+    minStartedAt: Date;
+    maxStartedAt: Date;
+    maxFinishedAt: Date;
+    /** Sum of `attempts` — moves when a step is retried in place, so a change marker sees it. */
+    sumAttempts: number;
+}
+/** What {@link StateStore.queryCheckpoints} selects. */
+export interface CheckpointQuery {
+    /** Only this `parallelGroup`'s checkpoints. */
+    group?: string | undefined;
+    /** Leave out these groups' checkpoints (ungrouped checkpoints are kept). */
+    excludeGroups?: string[] | undefined;
+    statuses?: StepCheckpoint['status'][] | undefined;
+    /** Only names starting with one of these. */
+    namePrefixes?: string[] | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}
+/**
+ * One `(status, origin)` cell of {@link StateStore.runFacets} — a `GROUP BY` row, not a page of runs.
+ * `origin` is `null` for runs carrying none (absent or blank).
+ */
+export interface RunFacetRow {
+    status: RunStatus;
+    origin: string | null;
+    count: number;
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 export type SearchAttributes = Record<string, string | number | boolean>;
+/**
+ * A Standard Schema (https://standardschema.dev — zod, valibot, arktype, …) whose validated OUTPUT is
+ * search-attribute-shaped: flat `string`/`number`/`boolean` values only. Declared via
+ * `static workflow = { searchAttributes }` (or `register(..., { searchAttributesSchema })`), it makes
+ * `ctx.upsertSearchAttributes` validate the MERGED attributes and reject a non-conforming write with a
+ * `SchemaValidationError`. The `Output extends SearchAttributes` bound is enforced at the declaration
+ * site — a schema whose output has a nested object/array value is a compile-time error. Its
+ * `validate` must be synchronous (an async refinement could make replay nondeterministic).
+ *
+ * @example
+ * ```ts
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() })
+ *
+ * export default class CheckoutWorkflow extends BaseWorkflow {
+ *   static workflow = { name: 'checkout', searchAttributes: orderAttrs }
+ *   async run(ctx: WorkflowCtx<InferSearchAttributes<typeof orderAttrs>>, input: Order) {
+ *     await ctx.upsertSearchAttributes({ tier: input.tier, amount: input.total })
+ *   }
+ * }
+ * ```
+ */
+export type SearchAttributesSchema<A extends SearchAttributesShape = SearchAttributesShape> = StandardSchemaV1<unknown, A>;
+/**
+ * The bound a TYPED search-attributes shape must satisfy: {@link SearchAttributes} whose values may
+ * also be `undefined` — so an optional key (`v.optional(v.number())`, `z.number().optional()`), which
+ * infers as `key?: number | undefined`, still type-checks under `exactOptionalPropertyTypes`.
+ */
+export type SearchAttributesShape = Record<string, string | number | boolean | undefined>;
+/** Infer the validated OUTPUT shape of a {@link SearchAttributesSchema} — feed it to
+ *  `WorkflowCtx<A>`: `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`. */
+export type InferSearchAttributes<S extends StandardSchemaV1<unknown, SearchAttributesShape>> = StandardSchemaV1.InferOutput<S>;
 export type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
 /** One value a search attribute can hold, and so one operand a predicate compares against. */
 export type AttributeValue = string | number | boolean;
@@ -684,17 +872,36 @@ export type RunFacetQuery = Omit<RunQuery, 'status' | 'statuses' | 'page' | 'siz
 export type RunScope = Pick<RunQuery, 'workflow' | 'workflows' | 'tag' | 'tags' | 'namespace' | 'namespaces' | 'attributes'>;
 /** True when `scope` sets at least one predicate — a bulk delete refuses an empty (match-all) scope. */
 export declare function isNonEmptyRunScope(scope: RunScope | undefined): boolean;
+/**
+ * The input a dead-letter workflow is started with when a run goes `dead` (see the engine's
+ * `deadLetterWorkflow` and a workflow's own `deadLetterWorkflow` / `deadLetter()` method): which run
+ * died, of which workflow, with what input, and why (`max_recovery_attempts`). The handler run's id is
+ * `dlq:<deadRunId>`.
+ */
+export interface DeadLetter<TInput = unknown> {
+    deadRunId: string;
+    workflow: string;
+    input: TInput;
+    error?: StepError | undefined;
+}
 /** The terminal run statuses — the only ones retention may delete. */
 export type TerminalRunStatus = 'completed' | 'failed' | 'cancelled' | 'dead';
 export declare const TERMINAL_RUN_STATUSES: readonly TerminalRunStatus[];
 /**
  * A retention rule confined to a {@link RunScope}: terminal runs in `statuses` matching `scope` are
- * hard-deleted once their last activity is older than `maxAgeMs`. Sits next to the per-status
- * `retention` ages, so e.g. chat turns can age out after a day while everything else keeps 30.
+ * hard-deleted once their last activity is older than `maxAgeMs`, and/or once more than `maxCount`
+ * newer ones exist. Sits next to the per-status `retention` ages, so e.g. chat turns can age out
+ * after a day while everything else keeps 30.
+ *
+ * `maxCount` keeps the `maxCount` newest runs (by start time, `createdAt`) of the whole status set
+ * WITHIN the scope — "keep acme's newest 100" counts acme's runs only — and deletes the older ones.
+ * With both bounds the most restrictive wins: a run goes once it is past either. At least one of the
+ * two must be set.
  */
 export interface ScopedRetentionPolicy {
     statuses: TerminalRunStatus[];
-    maxAgeMs: number;
+    maxAgeMs?: number | undefined;
+    maxCount?: number | undefined;
     scope: RunScope;
 }
 /**
@@ -875,7 +1082,13 @@ export interface StepResult {
 export interface Heartbeat {
     runId: string;
     seq: number;
-    stepId: string;
+    /**
+     * The in-flight step this beat keeps alive. ABSENT (or `''`) for a RUN-scoped (workflow-turn)
+     * heartbeat: a worker replaying a long workflow turn beats for its `runId` so the engine pushes the
+     * awaited turn's re-drive deadline forward (see `WorkflowEngineDeps.remoteAdvanceSilenceMs`). The
+     * Python `durable-worker` sends `{ runId, seq: 0, group }` with no `stepId` for exactly this.
+     */
+    stepId?: string | undefined;
     group: string;
     /** Worker-side emission time (epoch ms). Optional on the wire for back-compat with 0.17-era workers. */
     at?: number | undefined;
@@ -1023,7 +1236,34 @@ export interface WorkflowStepEvent {
  * concerns, identical for in-process and remote workflows.
  */
 export interface WorkflowExecutor {
-    advance(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * INLINE replay: advance the turn and RETURN its decision (e.g. `LocalWorkflowTurnExecutor`
+     * runs the turn body in-process). The engine awaits this under the run's lease, so it is
+     * single-instance by nature. Provide this OR {@link dispatch}; when both exist the engine uses
+     * `dispatch`.
+     */
+    advance?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): enqueue the turn to a worker under the
+     * ENGINE-SUPPLIED, globally unique `taskId`, WITHOUT awaiting the decision. Before calling this the
+     * engine has already recorded `taskId` on the run ({@link WorkflowRun.awaitingDecisionTaskId}),
+     * suspended it and released its lease, so the worker's {@link WorkflowDecision} — delivered over
+     * {@link Transport.onDecision} to WHICHEVER engine replica consumes it — always finds its marker and
+     * a free lease. This method only enqueues; a throw fails the run.
+     */
+    dispatch?(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
+    /**
+     * Subscribe the engine's decision handler to the transport this executor dispatches over. Called
+     * once per registration with the SAME handler function, so a transport that keeps a handler set
+     * (bullmq, queue, db) dedupes it across executors. Required for {@link dispatch} to make progress.
+     */
+    subscribeDecisions?(handler: (decision: WorkflowDecision) => Promise<void>): void;
+    /**
+     * Optional per-workflow liveness window (ms) for a dispatched turn: with no decision and no
+     * run-scoped heartbeat for this long, the turn is re-driven (re-dispatched under a fresh `taskId`).
+     * Combined with the engine's `remoteAdvanceSilenceMs` (the shorter wins). Heartbeats rearm it.
+     */
+    readonly decisionTimeoutMs?: number | undefined;
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
@@ -1080,10 +1320,11 @@ export interface RunRequest {
 }
 /**
  * The discriminated verb + args of a {@link RunRequest}. Mirrors THIS package's tenant-facing
- * {@link RunGateway} — so it diverges from aviary's verb set (aviary has `getRunDetail`/`retry`/
- * `continue`/`retryWithInput`/`waitingFor`; this package has `getRun`/`getCheckpoints`/
- * `getSearchAttributes`/`signal`) while the shared verbs (`listRuns`/`cancel`/`redispatch`/
- * `workerHealth`) keep aviary's EXACT shape, and the request/reply ENVELOPE stays byte-compatible.
+ * {@link RunGateway}: aviary's whole verb set in aviary's EXACT shapes (`getRunDetail`,
+ * `getFanMembers`, `listRuns`, `runFacets`, `runValueFacets`, `workerHealth`, `cancel`, `retry`,
+ * `continue`, `retryWithInput`, `redispatch`, `waitingFor`), plus this package's own
+ * `getRun`/`getCheckpoints`/`getRunChildren`/`getSearchAttributes`/`signal`. The request/reply
+ * ENVELOPE stays byte-compatible.
  * `start` and `subscribe` are NOT here — they ride `${P}-start-run` and `${P}-tenant-events-<tenant>`
  * respectively.
  */
@@ -1127,6 +1368,27 @@ export type RunRequestKind = {
 } | {
     kind: 'redispatch';
     runId: string;
+} | {
+    kind: 'runFacets';
+    query: RunFacetQuery;
+} | {
+    kind: 'runValueFacets';
+    axis: RunValueAxis;
+    query: RunFacetQuery;
+    opts?: RunValueFacetOptions | undefined;
+} | {
+    kind: 'retry';
+    runId: string;
+} | {
+    kind: 'continue';
+    runId: string;
+} | {
+    kind: 'retryWithInput';
+    runId: string;
+    input: unknown;
+} | {
+    kind: 'waitingFor';
+    runIds: string[];
 };
 /** The control plane's answer to a {@link RunRequest} (or to a start-run, correlated by the minted
  *  runId), keyed by `requestId`. Byte-compatible with aviary's `RunReply`. */
@@ -1183,12 +1445,17 @@ export interface Transport {
     /** Start every consumer subscription parked by {@link Transport.deferConsumers} — the explicit
      *  "this process IS a worker" declaration. Idempotent; a no-op when nothing was deferred. */
     startConsumers?(): void;
+    /** Called by the provider when this transport backs a store-less `tenant` pod, before anything is
+     *  registered on it. Optional — a transport whose behaviour does not depend on the role omits it (the
+     *  queue transport uses it to forward worker advertisement to the control plane when it has no key
+     *  store of its own). */
+    useTenantRole?(): void;
     /** Release the transport's resources (broker workers, queues, connections) for a clean shutdown.
      *  Optional — an in-process transport has nothing to close. Called on `onApplicationShutdown`
      *  after the engine drains, so a deploy hands off instead of leaving the broker to time out. */
     close?(): Promise<void>;
     /** engine → workflow worker: dispatch a {@link WorkflowTask} (the polyglot-workflow path). Optional
-     *  — only transports that carry workflow tasks (BullMQ) implement it; the {@link RemoteWorkflowExecutor}
+     *  — only transports that carry workflow tasks (BullMQ, queue, db) implement it; the {@link RemoteWorkflowExecutor}
      *  uses it + {@link onDecision} to advance a remote workflow over the broker. */
     dispatchWorkflowTask?(task: WorkflowTask): Promise<void>;
     /** workflow worker → engine: a replayed turn's {@link WorkflowDecision}. Pair with dispatchWorkflowTask. */
@@ -1200,8 +1467,8 @@ export interface Transport {
     /** engine ← workflow worker: consume streamed {@link WorkflowStepEvent}s. Pair with dispatchStepEvent. */
     onStepEvent?(handler: (event: WorkflowStepEvent) => Promise<void>): void;
     /** Worker-health for a group: queue backlog + live worker heartbeats. Optional — only broker
-     *  transports (BullMQ) that can introspect the task queue and the worker-heartbeat keys implement
-     *  it. The engine aggregates this across its groups in {@link WorkflowEngine.workerHealth}. */
+     *  transports (BullMQ, queue, db) that can introspect the task queue and the worker-heartbeat keys
+     *  implement it. The engine aggregates this across its groups in {@link WorkflowEngine.workerHealth}. */
     groupHealth?(group: string): Promise<GroupHealth>;
     /** Distinct groups that currently have a live worker heartbeat — discovered from the heartbeat
      *  keyspace, so a group with workers but no engine-side registration (e.g. a local-step group)
@@ -1218,6 +1485,17 @@ export interface Transport {
      * `[]` (never throw) when the keyspace is empty or unreadable. Pairs with {@link listWorkerGroups}.
      */
     listWorkerDescriptors?(token: string): Promise<WorkerDescriptor[]>;
+    /**
+     * EVERY live worker descriptor, across all routing tokens — the fleet-wide read behind
+     * {@link WorkflowEngine.workflowDirectory}. Optional, and MUST degrade to `[]` when unreadable.
+     */
+    readAllWorkerDescriptors?(): Promise<WorkerDescriptor[]>;
+    /**
+     * EVERY live worker heartbeat, across all routing tokens — the liveness floor of
+     * {@link WorkflowEngine.workflowDirectory}, which is how a worker too old to publish a descriptor
+     * still shows up. Optional, same as {@link readAllWorkerDescriptors}.
+     */
+    readAllWorkerHeartbeats?(): Promise<WorkerHeartbeat[]>;
     /** tenant → control plane: publish a {@link StartRunMessage} on `${P}-start-run` (queue, job
      *  `startRun`) requesting a new run. Pair with {@link onStartRun}. */
     dispatchStartRun?(msg: StartRunMessage): Promise<void>;
@@ -1291,7 +1569,9 @@ export interface WorkerHeartbeat {
  *  consumer (exactly the failure where a worker is "alive but not consuming"). */
 export interface GroupHealth {
     group: string;
-    /** Outstanding jobs in the group's task queue (waiting + active + delayed + prioritized). */
+    /** Outstanding jobs in the group's task queue (waiting + active + delayed + prioritized on BullMQ;
+     *  pending only on the queue transport, whose adapter contract counts nothing else; pending +
+     *  claimed task rows on the db transport). */
     depth: number;
     /** Workers with a non-expired heartbeat for this group. */
     liveWorkers: WorkerHeartbeat[];
@@ -1396,7 +1676,8 @@ export interface StepOptions {
  * name (a worker subscribes per registered handler name, not a hand-declared group). There is no
  * public factory for this anymore — `ctx.step(ref, input)` builds one internally from the
  * `@Step`-stamped name (see {@link StepRef}/`stepNameOf`) and a `ctx.step(name, input)` from the
- * literal string. `input`/`output` are OPTIONAL runtime zod schemas an authoring layer MAY attach
+ * literal string. `input`/`output` are OPTIONAL runtime Standard Schemas (zod, valibot, arktype, …)
+ * an authoring layer MAY attach
  * (e.g. `@Step({ input, output })`) for validation at the dispatch boundary — a bare `@Step()`
  * carries neither, and the engine skips validation when they're absent. The `StepOptions` fields
  * (retries/backoff/timeoutMs …) carry the merged per-call/def dispatch policy.
@@ -1406,8 +1687,8 @@ export interface StepDef<TInput = unknown, TOutput = unknown> extends StepOption
     /** Optional isolation partition; routing is by `name`. Suffixes the routing token as
      *  `<name>@<partition>` (via `tenantGroup`) — omit to route by the bare (sanitized) `name`. */
     partition?: string | undefined;
-    input?: z.ZodType<TInput> | undefined;
-    output?: z.ZodType<TOutput> | undefined;
+    input?: StandardSchemaV1<unknown, TInput> | undefined;
+    output?: StandardSchemaV1<unknown, TOutput> | undefined;
 }
 /**
  * Options for a dispatched {@link WorkflowCtx.step} call. `retries`/`backoff`/`backoffMs`/
@@ -1494,8 +1775,13 @@ export interface DurableWebhook<TPayload = unknown> {
 /**
  * The context handed to a workflow function. Every interaction with the outside world goes
  * through it so the engine can checkpoint — the workflow body itself stays deterministic.
+ *
+ * Generic over `A`, the run's {@link SearchAttributes} shape — narrows {@link upsertSearchAttributes}
+ * to a `Partial<A>` (pair it with a {@link SearchAttributesSchema}: annotate `run`'s ctx as
+ * `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`). Defaults to the untyped bag, so a bare
+ * `WorkflowCtx` behaves exactly as before.
  */
-export interface WorkflowCtx {
+export interface WorkflowCtx<A extends SearchAttributesShape = SearchAttributes> {
     readonly runId: string;
     /**
      * Run a durable step — always dispatched, always engine-scheduled: the ONE step primitive (no
@@ -1718,8 +2004,10 @@ export interface WorkflowCtx {
      * exactly-once — recorded at this position on the first run and SKIPPED on replay, so it does one
      * write, not one per turn. Use this instead of injecting the {@link StateStore} to mutate the run
      * you're executing (`store.updateRun(ctx.runId, …)` becomes `ctx.upsertSearchAttributes(…)`).
+     * With a declared {@link SearchAttributesSchema}, the merged result is validated first and a
+     * non-conforming write throws a `SchemaValidationError` (nothing is written or recorded).
      */
-    upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
+    upsertSearchAttributes(attrs: Partial<A>): Promise<void>;
 }
 /**
  * {@link WorkflowCtx} with ONE signature per method: the string-addressed forms of the five overloaded
@@ -1737,7 +2025,7 @@ export interface WorkflowCtx {
  *
  * Every `WorkflowCtx` is assignable to it (guarded by `test/types/dynamic-workflow-ctx.ts`).
  */
-export interface DynamicWorkflowCtx extends Omit<WorkflowCtx, 'step' | 'child' | 'startChild' | 'all' | 'allSettled'> {
+export interface DynamicWorkflowCtx<A extends SearchAttributesShape = SearchAttributes> extends Omit<WorkflowCtx<A>, 'step' | 'child' | 'startChild' | 'all' | 'allSettled'> {
     /** {@link WorkflowCtx.step} by step name. */
     step<TOutput = unknown>(name: string, input: unknown, opts?: StepDispatchOpts & {
         compensate?: string;