@dudousxd/nestjs-durable-core 0.64.0 → 0.66.0

package/dist/index.d.ts

@@ -168,6 +168,34 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
  * wire contract — the adonis + python SDKs build the byte-identical shape (design §7.8), and the
  * golden fixtures in `<repo>/fixtures/wire/` pin the exact bytes all three SDKs must agree on.
  */
+/**
+ * One workflow a worker ANNOUNCES it can execute — the richer form of a `workflows` name.
+ *
+ * The rule is "announce only what you can run": a process publishes a registration for a workflow
+ * whose body it holds and whose queue it consumes. It never publishes one for a workflow it merely
+ * knows how to *route to* (an engine's `registerRemote`), because that claim says nothing about a
+ * live executor existing — which is precisely the ambiguity an aggregate registry has to remove.
+ *
+ * Every field but `name` is optional because the SDKs hold different amounts of this. A worker that
+ * knows only names (the Python `@worker.workflow("x")` form, or any pre-registrations SDK) publishes
+ * bare `workflows` names instead and is still a first-class announcer — see {@link WorkerDescriptor.registrations}.
+ * A reader must therefore treat an absent field as "not stated", never as a value: the aggregate in
+ * `./announced` never invents a version, a group or an origin that nobody announced.
+ */
+interface WorkflowRegistration {
+    /** Registered workflow name — the `workflow` a {@link WorkflowTask} carries. */
+    name: string;
+    /** Registered version, when the announcer knows one. Absent = unversioned announcement. */
+    version?: string;
+    /** The routing token this workflow's turns are dispatched to (the queue this worker consumes for
+     *  it). Absent = the announcer did not say; a reader must NOT assume the by-convention token. */
+    group?: string;
+    /** Capabilities a worker must advertise to run it (design §7.5), as the announcer declares them. */
+    requires?: string[];
+    /** The package that DECLARED the workflow (see `WorkflowRun.origin`). Absent = unknown; nothing
+     *  ever substitutes a default, because a wrong origin is worse than no origin. */
+    origin?: string;
+}
 /**
  * A worker's (or control-plane's) advertised identity, wire-protocol support, feature capabilities
  * and registered handlers. Published on startup + on change (design §7.2) and consumed by
@@ -200,6 +228,19 @@ interface WorkerDescriptor {
     workflows: string[];
     /** Registered step handler names → routing targets. Order-insensitive (a set). */
     steps: string[];
+    /**
+     * The richer, per-workflow ANNOUNCEMENT of what this instance can execute (name + version + group
+     * + requires + origin). OPTIONAL and purely additive: an SDK that has only names keeps publishing
+     * {@link workflows} and is aggregated all the same, just unversioned. An SDK that publishes this
+     * SHOULD also list the same names in {@link workflows}, so a reader that predates this field still
+     * sees the workflow at all.
+     *
+     * It rides the descriptor rather than a registry of its own so it inherits the whole liveness
+     * story for free: the descriptor key is written with the heartbeat's TTL and refreshed by the same
+     * beat, so an announcement from a worker that has since died EXPIRES instead of offering a choice
+     * that fails at run time.
+     */
+    registrations?: WorkflowRegistration[];
     /** Optional routing partition (queue/group sharding). */
     partition?: string;
     /** Optional tenant namespace this instance serves. */
@@ -252,7 +293,13 @@ declare function isLegacyDescriptor(raw: RawWorkerDescriptor | WorkerDescriptor)
  * - absent `workflows`/`steps` → `[]`, absent `sdk` → an `unknown` marker, absent `startedAt` → `0`.
  *
  * The undefined-vs-`[]` distinction is deliberate: an absent field means "legacy, doesn't advertise
- * this axis"; an explicit empty array means "modern SDK that genuinely advertises nothing".
+ * this axis"; an explicit empty array means "modern SDK that genuinely advertises nothing". The same
+ * reasoning keeps `registrations` ABSENT when it was absent (rather than defaulting to `[]`): "this
+ * SDK does not announce registrations" and "this SDK announces none" are different facts, and only
+ * the second one licenses a reader to conclude the worker serves nothing. (No SDK publishes `[]`
+ * today — {@link describeWorker} and the Python builder both OMIT the field when there is nothing to
+ * announce, so a worker with no workflows keeps its pre-announcement bytes and ETag — but a reader
+ * must not collapse the two cases on that basis.)
  */
 declare function normalizeDescriptor(raw: RawWorkerDescriptor | WorkerDescriptor): WorkerDescriptor;
 /**
@@ -292,6 +339,35 @@ declare function heartbeatStatus(descriptor: RawWorkerDescriptor | WorkerDescrip
     ts?: number;
     status?: WorkerLifecycle;
 }): HeartbeatStatus;
+/**
+ * Build a worker's own {@link WorkerDescriptor} in the exact §7.1 shape every SDK publishes — the
+ * single builder both TS advertisers use (the BullMQ transport's in-app worker and the standalone
+ * `runRedisWorker`), so two processes in the same fleet cannot drift into two dialects of the same
+ * wire.
+ *
+ * Set-valued fields are sorted here (not just in the hash projection) so the published BYTES are
+ * stable across registration order too — a re-registration in a different order must not look like a
+ * change to a reader diffing the raw value. `partition` and `namespace` are omitted when empty, and
+ * `namespace` additionally when it is `default`, keeping a single-tenant deployment byte-identical
+ * to the un-namespaced scheme. `capabilities` is the canonical v1 baseline this protocol guarantees.
+ */
+declare function describeWorker(opts: {
+    instanceId: string;
+    runtime: 'node' | 'python';
+    sdk: {
+        name: string;
+        version: string;
+    };
+    steps: string[];
+    workflows?: string[] | undefined;
+    /** What this instance announces it can EXECUTE — see {@link WorkflowRegistration}. Omitted from
+     *  the descriptor entirely when absent or empty, so a worker with nothing to announce keeps the
+     *  pre-registrations bytes (and therefore the pre-registrations hash). */
+    registrations?: readonly WorkflowRegistration[] | undefined;
+    startedAt: number;
+    partition?: string | undefined;
+    namespace?: string | undefined;
+}): WorkerDescriptor;
 
 /**
  * Capability- & protocol-aware dispatch planning (design §7.5/§7.6). Sits BETWEEN the pure handshake
@@ -1463,6 +1539,34 @@ interface Transport {
      * a run can dispatch to `group` or must park `blocked`.
      */
     readWorkerDescriptors?(group: string): Promise<WorkerDescriptor[]>;
+    /**
+     * Every live {@link WorkerDescriptor} in the deployment, across all groups — the read behind
+     * {@link WorkflowEngine.announcedWorkflows}. Optional, same as {@link readWorkerDescriptors}: a
+     * transport that cannot introspect the advertisement keyspace returns nothing and the registry is
+     * simply empty.
+     *
+     * Deliberately NOT `listWorkerGroups()` + a read per group: a worker publishes the SAME descriptor
+     * under every token it consumes, so per-group reads cost one round trip per group to re-fetch bytes
+     * the caller already has. One pass over the advertisement keyspace, de-duplicated by `instanceId`,
+     * answers with one scan and no per-group fan-out — and it also sees an instance whose groups the
+     * 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.
@@ -1615,6 +1719,19 @@ type BackoffStrategy = 'fixed' | 'exp';
 interface ChildCallOptions {
     /** Deterministic child run id; defaults to one derived from the parent run id + call position. */
     childId?: string | undefined;
+    /**
+     * Pin the child to this EXACT registered version instead of the newest one — the same contract as
+     * `StartOptions.version`, reached from inside a workflow body: an unregistered version fails the
+     * child's start rather than quietly running a different body, and a version can only be pinned on a
+     * workflow that is really registered (not on the synthesized remote/convention routes). A `ctx.child`
+     * whose pinned start fails surfaces it as a failed child on the parent's waiter; a fire-and-forget
+     * `ctx.startChild` buffers it until the parent joins the id.
+     *
+     * Replay-safe as long as you pass a CONSTANT (`{ version: '2' }`), which is the point — it names the
+     * body you meant. Computing it from a live registry read at call time would make the body
+     * non-deterministic, exactly like reading the clock.
+     */
+    version?: string | undefined;
     /**
      * Dispatch priority for a REMOTE child workflow — stamped on the child run and carried onto every
      * {@link WorkflowTask} dispatched to advance it, so an urgent child can jump ahead of enqueued
@@ -2288,6 +2405,438 @@ declare class EventAccumulators {
     private batch;
 }
 
+/**
+ * The announced workflow registry (design §7.9) — the aggregate answer to "what workflows exist in
+ * this deployment?", built ONLY from what live workers say about themselves.
+ *
+ * ## Why this is announced, not inferred
+ *
+ * `WorkflowEngine.workflowBody(name, version)` answers for the process that asks, and a missing body
+ * is ambiguous by design: it means "not registered here", but equally "registered via
+ * `registerRemote` against another SDK" or "a group this pod resolves by convention against a live
+ * worker". A picker built on that inference would offer different options depending on which replica
+ * served the request. So the registry is not derived from any engine's registry: a worker publishes
+ * what it can execute ({@link WorkerDescriptor.registrations}, or bare `workflows` names), and this
+ * module folds those statements together. Every entry is therefore a fact somebody asserted, and the
+ * aggregate is the same on every pod because every pod reads the same published statements.
+ *
+ * The announcer is always the process that CONSUMES the queue, never the engine that dispatches to
+ * it — including when the two share a process (the co-located in-app worker announces; the engine
+ * beside it does not). One consequence is worth stating plainly rather than leaving to be
+ * rediscovered: a pure operator (`store` with no `connection`) runs its bodies inline, consumes no
+ * queue, and therefore announces NOTHING. Its workflows are real and startable through its own
+ * `start()`, but they are not in this registry, because nothing about them is externally addressable
+ * for a picker to point at.
+ *
+ * ## Liveness
+ *
+ * There is no expiry logic here because there is no state here. An announcement lives on the
+ * descriptor key, which is written with the worker-heartbeat TTL and refreshed by the same beat; a
+ * worker that dies stops refreshing and its key expires, taking its announcements with it. The
+ * resolution of that liveness is therefore the TTL (35s against a 10s beat), so an entry can name a
+ * worker that died within the last beat window — the same staleness the capability router already
+ * accepts when it reads descriptors to decide whether to dispatch. A caller that needs a stronger
+ * guarantee should not seek it here: dispatch to a dead worker parks the run `blocked`/`pending` on
+ * its queue and the existing worker-health surface reports it. What this design DOES rule out is the
+ * unbounded failure — an announcement that outlives its worker forever.
+ *
+ * ## Disagreement
+ *
+ * Two live workers can announce the same `name@version` with different groups, origins or capability
+ * demands. The aggregate keeps EVERY distinct claim and reports the axes they differ on
+ * ({@link AnnouncedWorkflow.disagreements}); it never merges them into one value and never picks a
+ * winner, because either choice would make a caller act on a claim nobody made. Silence is not a
+ * claim: a worker that announced no origin does not disagree with one that did.
+ *
+ * ## Steps are deliberately out of scope
+ *
+ * There is no equivalent registry for steps, and this is not an omission to be fixed later. A step is
+ * not addressable from outside a run: it is identified by its `(runId, seq)` position in one
+ * workflow's history, `ctx.step` is only callable from inside a replaying body, and no engine entry
+ * point starts a step on its own. "Call this step" is therefore not something the engine can do, so a
+ * 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. */
+interface WorkflowAnnouncement extends WorkflowRegistration {
+    /** The announcing worker's instance id. */
+    instanceId: string;
+    /** The announcing worker's runtime — how a Python-served workflow is told from a Node-served one. */
+    runtime: 'node' | 'python';
+}
+/** An axis on which the live announcers of one workflow do not agree. `values` holds every distinct
+ *  DECLARED value (sorted); an announcer that stated nothing on the axis contributes nothing. */
+interface Disagreement {
+    axis: 'group' | 'origin' | 'requires';
+    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. 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). 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, 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. */
+    disagreements: Disagreement[];
+}
+/**
+ * What one descriptor announces. `registrations` is authoritative when present; any `workflows` name
+ * it does not cover is still announced as a bare, unversioned claim, so a worker that describes some
+ * of its workflows richly and others by name alone is reported in full rather than in part.
+ *
+ * A descriptor with neither field announces nothing — including the control plane's own descriptor,
+ * which is a router, not an executor.
+ */
+declare function announcementsOf(raw: RawWorkerDescriptor | WorkerDescriptor): WorkflowAnnouncement[];
+/**
+ * Fold every live descriptor's announcements into one entry per `name@version`, sorted by key.
+ *
+ * Pure: it holds nothing and caches nothing, so no pod ever carries a growing table of the fleet's
+ * registrations — the caller reads the live descriptors it already knows how to read, folds them
+ * here, and drops the result. The work is O(descriptors × announcements) per call, on demand.
+ *
+ * The same instance announcing the same workflow twice (a worker publishes its descriptor under
+ * every routing token it consumes, so the same bytes arrive several times) folds to ONE announcer:
+ * `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
+ * logic: given a local and a remote {@link WorkerDescriptor}, compute the negotiated session (highest
+ * common protocol major + capability intersection) and classify it into one of three outcomes with a
+ * precise, structured reason — never a bare boolean (design §7.6).
+ */
+
+/**
+ * The three compatibility outcomes (design §7.4):
+ * - `compatible`   — protocol ranges intersect + full capability parity → dispatch freely.
+ * - `degraded`     — ranges intersect but a capability is missing on one side → dispatch, but route
+ *                    capability-requiring work only to capable workers (soft warning).
+ * - `incompatible` — no protocol-range overlap → do NOT dispatch; red flag with the exact reason.
+ */
+type NegotiationOutcome = 'compatible' | 'degraded' | 'incompatible';
+/** Structured failure/warning payload — carries the precise delta so a diagnostics event can render
+ *  it on the timeline + dashboard health panel (design §7.6). Never a bare boolean. */
+interface NegotiationReason {
+    /** Stable machine code for alerting/telescope. */
+    code: 'protocol.incompatible' | 'capability.unavailable';
+    /** Human-readable one-liner (dashboard/telescope copy). */
+    message: string;
+    /** The exact delta: which protocol ranges failed to overlap, or which capabilities are missing. */
+    detail: {
+        localRange?: [number, number];
+        remoteRange?: [number, number];
+        /** Capabilities the local side advertises that the remote lacks. */
+        missingOnRemote?: string[];
+        /** Capabilities the remote side advertises that the local lacks. */
+        missingOnLocal?: string[];
+        /** Explicitly-required capabilities not satisfied by the negotiated session. */
+        missingRequired?: string[];
+    };
+}
+/** The negotiated session + full delta between two sides. Carries both normalized descriptors so a
+ *  downstream diagnostics event can attach them wholesale (design §7.6). */
+interface NegotiationResult {
+    outcome: NegotiationOutcome;
+    /** Highest common protocol major, or `null` when ranges do not overlap (incompatible). */
+    negotiatedProtocol: number | null;
+    protocol: {
+        localRange: [number, number];
+        remoteRange: [number, number];
+    };
+    capabilities: {
+        /** Intersection — the capabilities the negotiated session can rely on everywhere. */
+        shared: string[];
+        /** Local advertises, remote lacks. */
+        missingOnRemote: string[];
+        /** Remote advertises, local lacks. */
+        missingOnLocal: string[];
+    };
+    /** Present for `degraded` + `incompatible`; absent for `compatible`. */
+    reason?: NegotiationReason;
+    local: WorkerDescriptor;
+    remote: WorkerDescriptor;
+}
+interface NegotiateOptions {
+    /**
+     * Capabilities the local side needs the negotiated session to provide. A required capability the
+     * remote lacks degrades the session (dispatch generally, but capability-requiring runs park via
+     * the router, design §7.5) — it never, on its own, makes the pair *incompatible*: only a protocol
+     * range gap does that (design §7.4).
+     */
+    required?: string[];
+}
+/**
+ * Negotiate compatibility between `local` and `remote` (design §7.3/§7.4). Accepts raw/partial
+ * descriptors (a missing `protocol`/`capabilities` is normalized to the legacy-v1 baseline, so a
+ * legacy peer negotiates as **assume-compatible**, design §7.7).
+ *
+ * Outcome logic:
+ * 1. no protocol-range overlap → `incompatible` (`protocol.incompatible`);
+ * 2. else if a `required` capability is missing on the remote → `degraded` (`capability.unavailable`);
+ * 3. else if the capability sets differ at all (either direction) → `degraded`;
+ * 4. else full parity → `compatible`.
+ *
+ * **Bilateral-symmetric** on outcome for the parity path: `negotiate(a, b).outcome ===
+ * negotiate(b, a).outcome` (the `missingOnLocal`/`missingOnRemote` delta swaps). `required` is the
+ * caller's own need and intentionally asymmetric.
+ */
+declare function negotiate(localRaw: RawWorkerDescriptor | WorkerDescriptor, remoteRaw: RawWorkerDescriptor | WorkerDescriptor, opts?: NegotiateOptions): NegotiationResult;
+
+/**
+ * Capability-aware routing (design §7.5). A workflow/step handler may declare
+ * `requires: ['saga', 'search-attr-v2']`; the control-plane dispatches only to workers whose
+ * descriptor advertises every required capability. If no live capable worker exists the run must
+ * **park as `blocked`** with a precise reason (visible in the dashboard) — never a silent hang.
+ *
+ * Pure logic: no transport, no store. Consumers (the dispatcher/provider) feed live descriptors in.
+ */
+
+/** A handler's capability demand — either a bare list, or anything carrying a `requires` array
+ *  (a workflow/step ref). An absent/empty list means "runs anywhere" (design §7.5). */
+type CapabilityRequirement = string[] | {
+    requires?: string[];
+};
+/** Normalize the two accepted shapes to a de-duplicated list of required capability names. */
+declare function requiredCapabilities(handler: CapabilityRequirement): string[];
+/**
+ * Can `worker` run a handler with these requirements? True iff the worker's (normalized) descriptor
+ * advertises **every** required capability. A legacy worker (no `capabilities` field) is normalized
+ * to the v1 baseline first (design §7.7), so it can still run baseline-only work.
+ */
+declare function canRoute(handler: CapabilityRequirement, worker: RawWorkerDescriptor | WorkerDescriptor): boolean;
+/**
+ * The capabilities a handler requires that `worker` does NOT advertise — the precise routing delta.
+ * Empty iff {@link canRoute} is true.
+ */
+declare function missingCapabilities(handler: CapabilityRequirement, worker: RawWorkerDescriptor | WorkerDescriptor): string[];
+/** Filter a fleet down to the workers that can run a handler (design §7.5). */
+declare function capableWorkers<T extends RawWorkerDescriptor | WorkerDescriptor>(handler: CapabilityRequirement, workers: readonly T[]): T[];
+/** A run is dispatchable — at least one live worker can execute the handler. */
+interface RoutableResolution {
+    status: 'routable';
+    /** The normalized subset of the fleet that can run it. */
+    workers: WorkerDescriptor[];
+    requires: string[];
+}
+/** No live capable worker — the run parks as `blocked` with a human reason (design §7.5). */
+interface BlockedResolution {
+    status: 'blocked';
+    /** Exactly the dashboard copy: `blocked: no compatible worker (requires <caps>)`. */
+    reason: string;
+    requires: string[];
+}
+type RoutingResolution = RoutableResolution | BlockedResolution;
+/**
+ * Decide whether a handler can be dispatched to the given live fleet (design §7.5). Returns
+ * `routable` with the capable subset, or `blocked` with a precise reason when nobody can run it —
+ * so the run parks visibly instead of hanging silently. An empty fleet always blocks.
+ */
+declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
+
 type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
 /**
  * Options for {@link WorkflowEngine.start}.
@@ -2298,6 +2847,26 @@ type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>
  * another lib's, and an origin filter would quietly lie.
  */
 interface StartOptions {
+    /**
+     * Start THIS registered version instead of the newest one. Omit (the default) and the run starts on
+     * the newest registered version, exactly as it always has — this option only ever narrows.
+     *
+     * Resolved against the by-name@version registry, so it pins anything explicitly registered:
+     * {@link WorkflowEngine.register}, {@link WorkflowEngine.registerRemote}, {@link WorkflowEngine.remote}.
+     * A version that is NOT registered throws before a run row is created and NEVER falls back to
+     * `latest` — a silent fallback is the exact failure this option exists to prevent (a caller that
+     * asked for `name@3` and got `name@4` has no way to tell, and its run is already going).
+     *
+     * NOT available on the two SYNTHESIZED registration paths, which exist precisely because nothing is
+     * registered: a child inheriting its remote ancestor's routing (see `findInheritedRegistration`),
+     * and convention routing to a live worker group of the same name (`resolveRemoteByConvention`).
+     * Both INVENT the version they stamp — the ancestor's, and the `'1'` convention default — as a
+     * routing placeholder; neither is evidence that the worker has a body at the version you asked for.
+     * A pinned start that reaches them therefore throws rather than pretending to have honoured the pin.
+     * To pin a cross-SDK workflow, register it for real — `engine.remote('name', { version: '2', group })`
+     * — which puts `name@2` in the registry and pins like any other registration.
+     */
+    version?: string | undefined;
     /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
     tags?: string[] | undefined;
     /** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
@@ -2333,6 +2902,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`). */
@@ -2645,6 +3238,10 @@ declare class WorkflowEngine {
      * remote (a `registerRemote` / synthesized child carries only a throwing stub, never handed out).
      */
     workflowBody(name: string, version: string): WorkflowFn | undefined;
+    /** The registered versions of `name`, for the pinned-start error — "2 is not registered" is a
+     *  guess-the-typo error without them, and the answer (which versions this deploy actually carries)
+     *  is right here. `none` when the name is unknown entirely. */
+    private registeredVersions;
     /**
      * Register a workflow whose body runs in another SDK (e.g. Python). The engine owns the run exactly
      * as for a TS workflow — it persists checkpoints, recovers, runs timers — but advances it by handing
@@ -2770,6 +3367,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
@@ -2800,7 +3412,32 @@ declare class WorkflowEngine {
     /**
      * Cancel in-flight runs that have outlived their workflow's `executionTimeout`. Call it from the
      * timer poller alongside {@link resumeDueTimers}. A timed-out run is moved to `cancelled` with an
-     * `execution_timeout` error (terminal, so a late step result can't resurrect it).
+     * `execution_timeout` error (terminal, so a late step result can't resurrect it), AND its children
+     * are cascaded exactly as an explicit {@link cancel} cascades them.
+     *
+     * WHY THE TERMINAL WRITE IS DIRECT, not a call to {@link cancel}. Two reasons, both still standing:
+     * the run must land with the `execution_timeout` error `cancel` knows nothing about (`cancel` writes
+     * a plain `cancelled`, and the code is what a dashboard/alert distinguishes a timeout by), and this
+     * is a SCAN — it walks every in-flight run of every timed workflow on every poller tick, so it must
+     * not pay `cancel`'s per-run re-read and singleton/control-plane work on runs it isn't cancelling.
+     * The cascade below is charged only to the runs that ACTUALLY timed out, which are rare by
+     * construction; the scan itself is unchanged.
+     *
+     * The subtree, though, has no reason to differ, and before this it did: a timed-out parent's
+     * children kept running with the parent gone and nothing pointing at them — a silent orphan you
+     * could only find by reading the runs table by hand. {@link cancelChildren} is the SAME recursive
+     * walk `cancel` uses, so children of children go too, and it inherits that path's two guards:
+     * `cancel` returns early on a run that is already `completed`/`cancelled`/`dead` (a child that beat
+     * the sweep to the finish is never clobbered, and a re-cancel is a no-op), and it writes the
+     * parent's terminal status BEFORE recursing, so a cyclic parent→child graph terminates on the
+     * second visit instead of looping. Two pollers sweeping the same run concurrently therefore write
+     * the same terminal state twice and cascade into already-cancelled children — idempotent, not
+     * corrupting. The one window it does NOT close is the pre-existing check-then-write race an
+     * explicit `cancel` has always had (a child that completes between `cancel`'s read and its write);
+     * closing that needs a compare-and-set in the store contract, not a change here.
+     *
+     * Cascade failures are swallowed per subtree for the same reason `cancelChildren` swallows them per
+     * child: one unreachable child must not abort the sweep and leave every LATER timed-out run alive.
      */
     sweepTimeouts(now?: number): Promise<void>;
     /**
@@ -3064,6 +3701,10 @@ declare class WorkflowEngine {
      * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
      * checkpoint). Recursive, so a whole subtree is cancelled; the terminal guard in `cancel` stops it
      * at finished / already-cancelled runs (no loops, no re-cancel).
+     *
+     * Two callers, deliberately the same walk: an explicit {@link cancel}, and {@link sweepTimeouts}
+     * when a parent hits its `executionTimeout` — a timed-out parent's subtree dies the same way an
+     * explicitly cancelled one's does, or the children are orphans nobody is holding a reference to.
      */
     private cancelChildren;
     /**
@@ -3090,6 +3731,40 @@ declare class WorkflowEngine {
      *  from registrations, shows once its workers beat). Empty when no transport can introspect health
      *  (only the BullMQ transport implements `groupHealth`). */
     workerHealth(extra?: string[]): Promise<GroupHealth[]>;
+    /**
+     * What workflows the LIVE fleet announces it can execute — the deployment-wide registry a picker
+     * ("call this existing workflow") needs, and the one question this engine's own registry cannot
+     * answer. {@link workflowBody} answers only for this process, and a missing body is ambiguous: it
+     * means "not registered here", but equally "registered via {@link registerRemote} against another
+     * SDK" or "a group resolved by convention against a worker". An inferred answer would therefore
+     * differ per replica. This one does not: every pod folds the same published announcements.
+     *
+     * Scoped like every other poll surface — an engine WITH a `namespace` sees only workers in it, and
+     * an operator (namespace unset) sees the whole deployment ("ver tudo = ausência de namespace"). A
+     * descriptor that states no namespace is `default`, matching how a single-tenant fleet publishes.
+     *
+     * Cost: one advertisement scan per CALL, on demand. Nothing is added to the poll loop and nothing
+     * is retained — no pod holds a table of the fleet's registrations. Empty when no transport can
+     * introspect the advertisement keyspace (a pure in-process transport advertises nothing).
+     *
+     * 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
@@ -3550,140 +4225,6 @@ declare class ContinueAsNew extends Error {
     constructor(input: unknown);
 }
 
-/**
- * Bilateral compatibility negotiation between two handshake descriptors (design §7.3/§7.4). Pure
- * logic: given a local and a remote {@link WorkerDescriptor}, compute the negotiated session (highest
- * common protocol major + capability intersection) and classify it into one of three outcomes with a
- * precise, structured reason — never a bare boolean (design §7.6).
- */
-
-/**
- * The three compatibility outcomes (design §7.4):
- * - `compatible`   — protocol ranges intersect + full capability parity → dispatch freely.
- * - `degraded`     — ranges intersect but a capability is missing on one side → dispatch, but route
- *                    capability-requiring work only to capable workers (soft warning).
- * - `incompatible` — no protocol-range overlap → do NOT dispatch; red flag with the exact reason.
- */
-type NegotiationOutcome = 'compatible' | 'degraded' | 'incompatible';
-/** Structured failure/warning payload — carries the precise delta so a diagnostics event can render
- *  it on the timeline + dashboard health panel (design §7.6). Never a bare boolean. */
-interface NegotiationReason {
-    /** Stable machine code for alerting/telescope. */
-    code: 'protocol.incompatible' | 'capability.unavailable';
-    /** Human-readable one-liner (dashboard/telescope copy). */
-    message: string;
-    /** The exact delta: which protocol ranges failed to overlap, or which capabilities are missing. */
-    detail: {
-        localRange?: [number, number];
-        remoteRange?: [number, number];
-        /** Capabilities the local side advertises that the remote lacks. */
-        missingOnRemote?: string[];
-        /** Capabilities the remote side advertises that the local lacks. */
-        missingOnLocal?: string[];
-        /** Explicitly-required capabilities not satisfied by the negotiated session. */
-        missingRequired?: string[];
-    };
-}
-/** The negotiated session + full delta between two sides. Carries both normalized descriptors so a
- *  downstream diagnostics event can attach them wholesale (design §7.6). */
-interface NegotiationResult {
-    outcome: NegotiationOutcome;
-    /** Highest common protocol major, or `null` when ranges do not overlap (incompatible). */
-    negotiatedProtocol: number | null;
-    protocol: {
-        localRange: [number, number];
-        remoteRange: [number, number];
-    };
-    capabilities: {
-        /** Intersection — the capabilities the negotiated session can rely on everywhere. */
-        shared: string[];
-        /** Local advertises, remote lacks. */
-        missingOnRemote: string[];
-        /** Remote advertises, local lacks. */
-        missingOnLocal: string[];
-    };
-    /** Present for `degraded` + `incompatible`; absent for `compatible`. */
-    reason?: NegotiationReason;
-    local: WorkerDescriptor;
-    remote: WorkerDescriptor;
-}
-interface NegotiateOptions {
-    /**
-     * Capabilities the local side needs the negotiated session to provide. A required capability the
-     * remote lacks degrades the session (dispatch generally, but capability-requiring runs park via
-     * the router, design §7.5) — it never, on its own, makes the pair *incompatible*: only a protocol
-     * range gap does that (design §7.4).
-     */
-    required?: string[];
-}
-/**
- * Negotiate compatibility between `local` and `remote` (design §7.3/§7.4). Accepts raw/partial
- * descriptors (a missing `protocol`/`capabilities` is normalized to the legacy-v1 baseline, so a
- * legacy peer negotiates as **assume-compatible**, design §7.7).
- *
- * Outcome logic:
- * 1. no protocol-range overlap → `incompatible` (`protocol.incompatible`);
- * 2. else if a `required` capability is missing on the remote → `degraded` (`capability.unavailable`);
- * 3. else if the capability sets differ at all (either direction) → `degraded`;
- * 4. else full parity → `compatible`.
- *
- * **Bilateral-symmetric** on outcome for the parity path: `negotiate(a, b).outcome ===
- * negotiate(b, a).outcome` (the `missingOnLocal`/`missingOnRemote` delta swaps). `required` is the
- * caller's own need and intentionally asymmetric.
- */
-declare function negotiate(localRaw: RawWorkerDescriptor | WorkerDescriptor, remoteRaw: RawWorkerDescriptor | WorkerDescriptor, opts?: NegotiateOptions): NegotiationResult;
-
-/**
- * Capability-aware routing (design §7.5). A workflow/step handler may declare
- * `requires: ['saga', 'search-attr-v2']`; the control-plane dispatches only to workers whose
- * descriptor advertises every required capability. If no live capable worker exists the run must
- * **park as `blocked`** with a precise reason (visible in the dashboard) — never a silent hang.
- *
- * Pure logic: no transport, no store. Consumers (the dispatcher/provider) feed live descriptors in.
- */
-
-/** A handler's capability demand — either a bare list, or anything carrying a `requires` array
- *  (a workflow/step ref). An absent/empty list means "runs anywhere" (design §7.5). */
-type CapabilityRequirement = string[] | {
-    requires?: string[];
-};
-/** Normalize the two accepted shapes to a de-duplicated list of required capability names. */
-declare function requiredCapabilities(handler: CapabilityRequirement): string[];
-/**
- * Can `worker` run a handler with these requirements? True iff the worker's (normalized) descriptor
- * advertises **every** required capability. A legacy worker (no `capabilities` field) is normalized
- * to the v1 baseline first (design §7.7), so it can still run baseline-only work.
- */
-declare function canRoute(handler: CapabilityRequirement, worker: RawWorkerDescriptor | WorkerDescriptor): boolean;
-/**
- * The capabilities a handler requires that `worker` does NOT advertise — the precise routing delta.
- * Empty iff {@link canRoute} is true.
- */
-declare function missingCapabilities(handler: CapabilityRequirement, worker: RawWorkerDescriptor | WorkerDescriptor): string[];
-/** Filter a fleet down to the workers that can run a handler (design §7.5). */
-declare function capableWorkers<T extends RawWorkerDescriptor | WorkerDescriptor>(handler: CapabilityRequirement, workers: readonly T[]): T[];
-/** A run is dispatchable — at least one live worker can execute the handler. */
-interface RoutableResolution {
-    status: 'routable';
-    /** The normalized subset of the fleet that can run it. */
-    workers: WorkerDescriptor[];
-    requires: string[];
-}
-/** No live capable worker — the run parks as `blocked` with a human reason (design §7.5). */
-interface BlockedResolution {
-    status: 'blocked';
-    /** Exactly the dashboard copy: `blocked: no compatible worker (requires <caps>)`. */
-    reason: string;
-    requires: string[];
-}
-type RoutingResolution = RoutableResolution | BlockedResolution;
-/**
- * Decide whether a handler can be dispatched to the given live fleet (design §7.5). Returns
- * `routable` with the capable subset, or `blocked` with a precise reason when nobody can run it —
- * so the run parks visibly instead of hanging silently. An empty fleet always blocks.
- */
-declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
-
 /**
  * Wrappers around the **real execution** of a unit of durable work — a workflow turn, or a step
  * handler body. Distinct from {@link StepInterceptor} (`engine.use`), which only sees the in-process
@@ -4423,4 +4964,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, 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 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, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, 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, 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, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, 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 };