@dudousxd/nestjs-durable-core 0.58.0 → 0.59.0

package/dist/index.d.cts

@@ -161,6 +161,243 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
     release(queue: string, _slotId: string): Promise<void>;
 }
 
+/**
+ * Worker/control-plane handshake descriptor — the single source of truth for routing, compatibility
+ * and observability across a store-less durable cluster (design §7.1). Pure data + a deterministic,
+ * order-insensitive content hash; NO transport, NO I/O. Every field is part of the cross-language
+ * 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.
+ */
+/**
+ * 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
+ * {@link negotiate} (compat) and the capability-aware router (design §7.5). Exactly the §7.1 shape.
+ */
+interface WorkerDescriptor {
+    /** Stable id for this process in the fleet (mirrors aviary's per-instance heartbeat key). */
+    instanceId: string;
+    /** Execution runtime — a `python` worker and a `node` control-plane interoperate over the wire. */
+    runtime: 'node' | 'python';
+    /** Which SDK + version produced this descriptor. Observability only; never gates dispatch. */
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Wire-protocol majors this side speaks. `version` is its preferred/current major; `range` is the
+     * inclusive `[min, max]` band it can negotiate down/up to. Overlap of two ranges is what makes two
+     * sides compatible (design §7.4); `version` is informational.
+     */
+    protocol: {
+        version: number;
+        range: [number, number];
+    };
+    /** Named features advertised: `'saga'`, `'signals'`, `'search-attr-v2'`, `'priority'`, … A modern
+     *  worker MAY advertise `[]` (no named features); an ABSENT field means "legacy v1" — see
+     *  {@link normalizeDescriptor}. Order-insensitive: treated as a set. */
+    capabilities: string[];
+    /** Registered workflow handler names → routing targets. Order-insensitive (a set). */
+    workflows: string[];
+    /** Registered step handler names → routing targets. Order-insensitive (a set). */
+    steps: string[];
+    /** Optional routing partition (queue/group sharding). */
+    partition?: string;
+    /** Optional tenant namespace this instance serves. */
+    namespace?: string;
+    /** Process start time (epoch ms) — a restart changes it, so it participates in the content hash. */
+    startedAt: number;
+}
+/**
+ * The current wire-protocol major. The whole protocol as it exists today is defined as **v1**; the
+ * handshake exists so a future **v2 breaking change** is detectable rather than silently corrupting
+ * (design §7.7).
+ */
+declare const CURRENT_PROTOCOL_VERSION = 1;
+/**
+ * The protocol band assumed for a descriptor that omits `protocol` entirely — an existing aviary
+ * worker that predates the handshake. Absence = **legacy v1 baseline, assume compatible** (§7.7).
+ */
+declare const LEGACY_V1_PROTOCOL: WorkerDescriptor['protocol'];
+/**
+ * The feature set a legacy (pre-handshake) worker is assumed to advertise when its `capabilities`
+ * field is ABSENT. These are the durable primitives aviary has shipped since v1, so a legacy worker
+ * can still be routed work that `requires` them (design §7.5/§7.7).
+ *
+ * CROSS-SDK CONTRACT — this list is the canonical "what a v1 worker can do" baseline and MUST stay
+ * byte-identical across the adonis + nestjs + python SDKs. It is the ACTUAL aviary durable v1
+ * execution surface (each name maps to a shipped primitive: saga/compensation, signals,
+ * search-attributes, priority/fairness, entities, child-workflows, singleton gating, cron schedules,
+ * continue-as-new, queries, cooperative cancellation). `search-attr-v2` is a MODERN capability layered
+ * on top and is deliberately NOT in the v1 baseline — a v1 worker only guarantees the v1
+ * `search-attributes` surface.
+ */
+declare const LEGACY_V1_CAPABILITIES: readonly string[];
+/**
+ * A raw, possibly-partial descriptor as it may arrive off the wire from an older SDK: `protocol`
+ * and/or `capabilities` may be missing. {@link normalizeDescriptor} fills the legacy-v1 defaults.
+ */
+type RawWorkerDescriptor = Omit<Partial<WorkerDescriptor>, 'instanceId' | 'runtime'> & {
+    instanceId: string;
+    runtime: 'node' | 'python';
+};
+/**
+ * True when a descriptor predates the handshake — it carries no `protocol` field. Such a descriptor
+ * is treated as legacy v1 and assumed compatible (design §7.7).
+ */
+declare function isLegacyDescriptor(raw: RawWorkerDescriptor | WorkerDescriptor): boolean;
+/**
+ * Fill legacy-v1 defaults so downstream logic always sees a complete {@link WorkerDescriptor}:
+ * - absent `protocol` → {@link LEGACY_V1_PROTOCOL} (assume-compatible v1 baseline),
+ * - absent `capabilities` → {@link LEGACY_V1_CAPABILITIES} (a modern `[]` is preserved as-is),
+ * - 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".
+ */
+declare function normalizeDescriptor(raw: RawWorkerDescriptor | WorkerDescriptor): WorkerDescriptor;
+/**
+ * Compact, liveness lifecycle status carried on the cheap steady-state heartbeat (design §7.2).
+ * Distinct from aviary's rich `WorkerStatus` object (owned by the transport layer): this is the
+ * lightweight two-tier advertisement, whose job is to carry the {@link descriptorHash} ETag.
+ */
+type WorkerLifecycle = 'up' | 'draining' | 'quiescing' | 'stopped';
+/**
+ * The two-tier heartbeat payload (design §7.2): a cheap `{ ts, status, descriptorHash }` beaten every
+ * ~10s. The `descriptorHash` is an **ETag** — the control-plane re-reads the full (expensive)
+ * descriptor only when this hash changes, keeping steady-state chatter tiny.
+ */
+interface HeartbeatStatus {
+    /** Beat time, epoch ms. */
+    ts: number;
+    /** Compact lifecycle status. */
+    status: WorkerLifecycle;
+    /** ETag over the full descriptor — see {@link descriptorHash}. */
+    descriptorHash: string;
+}
+/**
+ * Stable ETag over a descriptor's content (design §7.2). **Order-insensitive** over the set-valued
+ * fields (`capabilities`/`workflows`/`steps`) — the same members in any order yield the same hash —
+ * and stable across the object's key insertion order. Any change to a routing/compat-relevant field
+ * (including `startedAt` on restart) changes the hash, which is what triggers a full re-read.
+ *
+ * Accepts a raw/partial descriptor too: it is normalized first, so a legacy descriptor hashes as its
+ * v1 baseline.
+ */
+declare function descriptorHash(descriptor: RawWorkerDescriptor | WorkerDescriptor): string;
+/**
+ * Build the compact two-tier heartbeat for a descriptor, stamping the ETag (design §7.2). `ts`
+ * defaults to now and `status` to `'up'`.
+ */
+declare function heartbeatStatus(descriptor: RawWorkerDescriptor | WorkerDescriptor, opts?: {
+    ts?: number;
+    status?: WorkerLifecycle;
+}): HeartbeatStatus;
+
+/**
+ * Capability- & protocol-aware dispatch planning (design §7.5/§7.6). Sits BETWEEN the pure handshake
+ * (`resolveRouting`/`negotiate`, `./{routing,negotiate}`) and the engine's dispatch path: given a
+ * step's/workflow's required capabilities and the LIVE worker descriptors for its routing token,
+ * decide whether a live worker can actually run it — and if not, produce the LOUD, structured reason
+ * the engine parks the run `blocked` with (never a silent hang into a queue nobody consumes).
+ *
+ * Pure logic + a small control-plane descriptor factory: no transport, no store, no I/O. The engine
+ * feeds in descriptors it read off the broker and acts on the returned plan.
+ */
+
+/**
+ * Build the control-plane's OWN handshake descriptor — the side the engine negotiates AGAINST each
+ * worker (design §7.3). The CP advertises the protocol band it speaks so a worker stuck on an
+ * incompatible major is detected instead of dispatched into (design §7.4). Capabilities default to
+ * empty (the CP demands nothing of itself); `partition`/`namespace` scope it to a pool when set.
+ *
+ * The CP is not a worker, so `workflows`/`steps` are empty and `runtime` is `node`. `startedAt`
+ * participates only in the descriptor hash (irrelevant for negotiation), so it defaults to `0` unless
+ * a caller wants a stable identity.
+ */
+declare function controlPlaneDescriptor(opts: {
+    instanceId: string;
+    /** SDK identity for observability (never gates dispatch). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    /** Protocol majors the CP can negotiate. Defaults to the current single-major band `[v, v]`. */
+    protocol?: {
+        version: number;
+        range: [number, number];
+    };
+    /** Capabilities the CP itself advertises (rarely needed; the CP is a router, not an executor). */
+    capabilities?: string[];
+    partition?: string | undefined;
+    namespace?: string | undefined;
+    startedAt?: number;
+}): WorkerDescriptor;
+/** The structured delta a blocked-dispatch diagnostics event carries (design §7.6) — enough for the
+ *  telescope timeline + dashboard health panel to render exactly WHY nobody could run the work, never
+ *  a bare boolean. Serializable (plain data), so it rides an `EngineEvent`/control-plane message. */
+interface DispatchDiagnostics {
+    /** Which machine code fired — a missing capability vs. an unbridgeable protocol gap. */
+    code: 'capability.unavailable' | 'protocol.incompatible';
+    /** The routing token the work would have been dispatched to. */
+    token: string;
+    /** The capabilities the handler required (de-duplicated). */
+    requires: string[];
+    /** How many live workers were advertising on this token at decision time. */
+    liveWorkers: number;
+    /** Required capabilities NOT advertised by ANY live worker (the `capability.unavailable` delta). */
+    missingCapabilities?: string[];
+    /** The protocol band the control-plane speaks (the `protocol.incompatible` delta). */
+    controlPlaneRange?: [number, number];
+    /** Protocol bands of the capable-but-incompatible workers (the `protocol.incompatible` delta). */
+    workerRanges?: [number, number][];
+    /** The control-plane descriptor negotiated against (attached wholesale for observability). */
+    controlPlane: WorkerDescriptor;
+    /** The live worker descriptors considered (attached wholesale — the full picture on the timeline). */
+    workers: WorkerDescriptor[];
+}
+/** At least one live worker can run the handler — dispatch proceeds as today. */
+interface RoutableDispatch {
+    status: 'routable';
+    /** The normalized subset that is BOTH capable and protocol-compatible. */
+    workers: WorkerDescriptor[];
+}
+/** No live worker can run the handler — the engine parks the run `blocked` with this reason/delta. */
+interface BlockedDispatch {
+    status: 'blocked';
+    code: 'capability.unavailable' | 'protocol.incompatible';
+    /** Dashboard/telescope copy, e.g. `blocked: no compatible worker (requires saga)`. */
+    reason: string;
+    requires: string[];
+    diagnostics: DispatchDiagnostics;
+}
+type DispatchPlan = RoutableDispatch | BlockedDispatch;
+/**
+ * Thrown from deep in a `ctx.step` dispatch when {@link planDispatch} returns `blocked`, so the
+ * engine's run-execution catch can park the run `blocked` (with the carried plan) instead of writing
+ * a `pending` checkpoint + dispatching into a queue no live worker consumes. Distinct from
+ * `WorkflowSuspended` — a blocked run is re-driven by the blocked-recovery poll, not a durable timer.
+ */
+declare class WorkflowBlocked extends Error {
+    readonly plan: BlockedDispatch;
+    constructor(plan: BlockedDispatch);
+}
+/**
+ * Decide whether a handler requiring `requires` can be dispatched to a token whose LIVE fleet is
+ * `liveDescriptors`, negotiating each candidate against the control-plane descriptor `cp`
+ * (design §7.4/§7.5).
+ *
+ * A worker is dispatchable iff it is BOTH capability-capable ({@link canRoute}) AND
+ * protocol-compatible ({@link negotiate} outcome ≠ `incompatible`). If ≥1 such worker exists →
+ * `routable`. Otherwise `blocked`, with the reason discriminated:
+ * - some workers had the capability but ALL are protocol-incompatible → `protocol.incompatible`;
+ * - otherwise (no live worker advertises every required capability) → `capability.unavailable`.
+ *
+ * Precondition (enforced by the caller): `liveDescriptors` is NON-EMPTY. An empty fleet means "no
+ * descriptors published" — the legacy/pre-handshake path — where the guard is intentionally skipped so
+ * existing workers keep flowing (design §7.7); the engine never calls this with an empty fleet.
+ */
+declare function planDispatch(requires: string[], liveDescriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[], cp: WorkerDescriptor, token: string): DispatchPlan;
+
 /**
  * Vendored subset of the Standard Schema spec (https://standardschema.dev) — the `~standard`
  * property protocol implemented by zod 3.24+, valibot, arktype, and others. Vendored (rather than
@@ -271,6 +508,10 @@ interface StepConfig {
      *  worker dead and fails the dispatch with a `RemoteStepTimeout` (retryable — re-dispatches per
      *  `retries`). Omit to wait indefinitely. */
     timeoutMs?: number | undefined;
+    /** Capabilities a live worker must advertise to run this step (handshake design §7.5). The
+     *  control-plane routes the step only to capable+compatible workers; if descriptors are published
+     *  on its group but none qualifies, the run parks `blocked`. Absent/empty = "runs anywhere". */
+    requires?: string[] | undefined;
 }
 /**
  * A method carrying its `@Step`-stamped routing name (and, optionally, its dispatch policy).
@@ -342,7 +583,15 @@ type RunStatus =
  * `cancelled` once compensation completes. A non-compensating cancel skips this and goes straight to
  * `cancelled`.
  */
- | 'cancelling' | 'completed' | 'failed' | 'cancelled'
+ | 'cancelling'
+/**
+ * No live worker on the run's next-dispatch group is BOTH capability-capable and protocol-compatible
+ * (handshake design §7.5). NON-TERMINAL — the run wrote no `pending` checkpoint and dispatched
+ * nothing; it carries a `wakeAt` so the blocked-recovery poll re-drives it to re-check the live
+ * fleet, and proceeds the moment a capable+compatible worker appears. Only engaged when descriptors
+ * are actually published (a legacy/pre-handshake fleet skips the guard, design §7.7).
+ */
+ | 'blocked' | 'completed' | 'failed' | 'cancelled'
 /** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill). Terminal; inspect it. */
  | 'dead';
 /** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
@@ -1179,6 +1428,14 @@ interface Transport {
      *  keyspace, so a group with workers but no engine-side registration (e.g. a local-step group)
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
+    /**
+     * The live handshake {@link WorkerDescriptor}s advertised for `group` (design §7.2). Optional — only
+     * broker transports that carry the two-tier descriptor advertisement (BullMQ) implement it; a pure
+     * in-process transport returns nothing, so the engine's routing guard stays disengaged (legacy
+     * assume-compatible, design §7.7). The engine feeds these into {@link planDispatch} to decide whether
+     * a run can dispatch to `group` or must park `blocked`.
+     */
+    readWorkerDescriptors?(group: string): Promise<WorkerDescriptor[]>;
     /**
      * 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.
@@ -1357,6 +1614,15 @@ interface StepOptions {
      * window. Omit to wait indefinitely.
      */
     timeoutMs?: number;
+    /**
+     * Capabilities a live worker MUST advertise to run this dispatched step (handshake design §7.5).
+     * The control-plane routes the step only to workers whose descriptor advertises every name here;
+     * if descriptors are published on the step's group but NONE is capability-capable + protocol-
+     * compatible, the run parks `blocked` (never a silent hang) and the blocked-recovery poll re-drives
+     * it when a capable worker appears. Absent/empty = "runs anywhere" (the default; backward-compatible
+     * — a legacy fleet publishing no descriptors skips the guard entirely, design §7.7).
+     */
+    requires?: string[];
     /**
      * Saga compensation: if this step completes but the run later **fails**, the engine runs the
      * registered `compensate` callbacks in reverse order (undo what was done). Local steps only.
@@ -1446,6 +1712,9 @@ interface StepDispatchOpts {
      *  worker dead and fails the dispatch with a `RemoteStepTimeout` (retryable — re-dispatches per
      *  `retries`). Omit to wait indefinitely. Overrides the `@Step`-declared value. */
     timeoutMs?: number;
+    /** Capabilities a live worker must advertise to run this dispatch (handshake design §7.5). Overrides
+     *  the `@Step`-declared `requires`. Absent = inherit the def-level value (or "runs anywhere"). */
+    requires?: string[];
 }
 /** What a saga undo handler receives: the compensated step's original input and its result — the
  *  ONE argument a compensation `@Step` is called with, so it's self-describing on the wire (a
@@ -1724,7 +1993,7 @@ type UpdateResult = {
     accepted: true;
     run: RunResult | null;
 };
-type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress';
+type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress' | 'run.blocked';
 /**
  * A lifecycle event emitted by the engine. The observability surfaces (dashboard, OTel, the
  * Telescope integration) all subscribe to these rather than reaching into the store.
@@ -1749,6 +2018,12 @@ interface EngineEvent {
     /** The live step event carried by a `step.progress` (the single log line / sub-process outcome a
      *  running step just emitted). Absent on lifecycle events. */
     event?: StepEvent | undefined;
+    /** Capabilities the blocked dispatch required (on a `run.blocked` event). */
+    requires?: string[] | undefined;
+    /** The structured routing delta on a `run.blocked` event (design §7.6): which capability/protocol
+     *  gap fired, how many live workers were considered, and both descriptors — enough for the health
+     *  panel/telescope to render the reason. Absent on all other event types. */
+    diagnostics?: DispatchDiagnostics | undefined;
     at: Date;
 }
 type EngineListener = (event: EngineEvent) => void;
@@ -2067,6 +2342,14 @@ interface WorkflowEngineDeps {
      * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
      */
     remoteRedispatchMax?: number | undefined;
+    /**
+     * How long (ms) a run parked `blocked` (no capability-capable + protocol-compatible live worker,
+     * handshake design §7.5) waits before the blocked-recovery poll re-drives it to re-check the live
+     * fleet. Default 5000. The run proceeds the moment a capable+compatible worker appears; until then it
+     * re-parks with a fresh `wakeAt` each poll. Only relevant once a step/workflow declares `requires`
+     * AND descriptors are published (a legacy fleet never parks blocked).
+     */
+    blockedPollMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -2146,6 +2429,10 @@ declare class WorkflowEngine {
     private readonly eventBufferTtlMs;
     private readonly remoteRedispatchMs;
     private readonly remoteRedispatchMax;
+    /** How long a `blocked` run waits before the recovery poll re-checks the live fleet (design §7.5). */
+    private readonly blockedPollMs;
+    /** This engine's control-plane handshake descriptor — negotiated against each worker (design §7.3). */
+    private readonly cpDescriptor;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2246,6 +2533,9 @@ declare class WorkflowEngine {
          *  in-app worker, pair a transport-backed {@link RemoteWorkflowExecutor} (group consumed by a
          *  worker that calls {@link workflowBody}) so the retained `fn` runs through the transport hop. */
         executor?: WorkflowExecutor | undefined;
+        /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5).
+         *  Only meaningful with `group`/`executor` (a remote/group-served workflow). Absent = runs anywhere. */
+        requires?: string[] | undefined;
     }): void;
     /**
      * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
@@ -2268,6 +2558,8 @@ declare class WorkflowEngine {
         singleton?: SingletonConfig;
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
+        /** Capabilities a live worker must advertise to run this remote workflow's turns (handshake §7.5). */
+        requires?: string[];
     }): void;
     /**
      * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
@@ -2291,6 +2583,8 @@ declare class WorkflowEngine {
         singleton?: SingletonConfig;
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
+        /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5). */
+        requires?: string[];
     }): void;
     /**
      * Register a flow-control queue referenced by `ctx.step(step, input, { queue })`. Caps concurrent
@@ -2852,6 +3146,34 @@ declare class WorkflowEngine {
      * if nothing was waiting — a too-early or duplicate update).
      */
     update(runId: string, name: string, arg: unknown): Promise<UpdateResult>;
+    /**
+     * Plan a dispatch to `token` for a handler requiring `requires` (handshake design §7.5). Returns:
+     * - `undefined` — NO live descriptors published on this token: the guard does not engage, so a
+     *   pre-handshake fleet (or an in-process transport that advertises none) keeps flowing exactly as
+     *   before (design §7.7);
+     * - a `routable` plan — ≥1 live worker is capability-capable AND protocol-compatible (dispatch);
+     * - a `blocked` plan — descriptors exist but none can run it (park the run, never dispatch into it).
+     */
+    private planRoute;
+    /** Throw {@link WorkflowBlocked} when no live worker can run a dispatch to `token` — so the caller's
+     *  run-execution catch parks the run `blocked` (with the plan) instead of persisting a `pending`
+     *  checkpoint + dispatching into a queue nobody consumes (design §7.5). A no-op when the guard does
+     *  not engage (no descriptors) or a capable+compatible worker exists. */
+    private ensureRoutable;
+    /**
+     * Park a run `blocked` (handshake design §7.5/§7.6): no live worker on its next-dispatch group is
+     * capability-capable + protocol-compatible. Persists the `blocked` status with a human reason + the
+     * machine `code` + a `wakeAt` so the blocked-recovery poll re-drives it, emits the LOUD structured
+     * `capability.unavailable`/`protocol.incompatible` diagnostics (both descriptors + the precise delta),
+     * and releases the run lease so any instance can re-drive it. Re-checks the persisted status first so
+     * a concurrent cancel/complete is never clobbered. `releaseRunLock` is idempotent, so a caller whose
+     * own `finally` also releases (the run-execution path) is safe.
+     */
+    private parkBlocked;
+    /** Runs parked `blocked` whose recovery poll is due (`wakeAt <= nowMs`), namespace-scoped like
+     *  {@link resumeDueTimers}. Re-driving one re-checks the live fleet: it dispatches if a
+     *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
+    private dueBlockedRuns;
     private callRemote;
     /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
      *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
@@ -3092,6 +3414,140 @@ 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;
+
 /** Canonical step id — the stable identity of a step within a run, used for dedupe and
  *  correlation. The format is part of the cross-language wire contract (Python builds the same). */
 declare function stepId(runId: string, seq: number): string;
@@ -3761,4 +4217,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, CONTROL_FLOW_SIGNAL, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, 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 HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type 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 WorkerHeartbeat, type WorkerStatus, 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, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, isEventToken, isWorkflowControlFlowSignal, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+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 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, type 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, collectMetrics, controlPlaneDescriptor, createStepLogger, currentWorkflowCtx, descriptorHash, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, heartbeatStatus, indexWaitersByRun, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };