@adonis-agora/durable 0.10.0 → 0.11.0

package/dist/src/handshake/descriptor.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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 nestjs + python SDKs build the byte-identical shape, design §7.8).
+ */
+/**
+ * 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.
+ */
+export 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).
+ */
+export 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).
+ */
+export 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 that have existed since v1, so a legacy worker
+ * can still be routed work that `requires` them (design §7.5/§7.7).
+ *
+ * This is the canonical aviary v1 execution surface, byte-for-byte identical across the Adonis,
+ * nestjs-durable, and Python SDKs (verified against the aviary codebase). `search-attr-v2` and other
+ * modern features are layered ON TOP and are NOT part of the v1 baseline — a legacy worker guarantees
+ * only the v1 `search-attributes` surface. Keep this list in lockstep with the other two SDKs.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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".
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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'`.
+ */
+export declare function heartbeatStatus(descriptor: RawWorkerDescriptor | WorkerDescriptor, opts?: {
+    ts?: number;
+    status?: WorkerLifecycle;
+}): HeartbeatStatus;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/src/handshake/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../src/handshake/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,8FAA8F;IAC9F,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IACvD;;4EAEwE;IACxE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,sFAAsF;IACtF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,gBAAgB,CAAC,UAAU,CAAiC,CAAC;AAE9F;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAYlD,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,GAAG;IAC5F,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC5B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,OAAO,CAEvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,gBAAgB,CAajG;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,MAAM,CAGzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,mBAAmB,GAAG,gBAAgB,EAClD,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAA;CAAO,GACnD,eAAe,CAMjB"}

package/dist/src/handshake/descriptor.js

@@ -0,0 +1,133 @@
+/**
+ * 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 nestjs + python SDKs build the byte-identical shape, design §7.8).
+ */
+/**
+ * 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).
+ */
+export 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).
+ */
+export const LEGACY_V1_PROTOCOL = { version: 1, range: [1, 1] };
+/**
+ * The feature set a legacy (pre-handshake) worker is assumed to advertise when its `capabilities`
+ * field is ABSENT. These are the durable primitives that have existed since v1, so a legacy worker
+ * can still be routed work that `requires` them (design §7.5/§7.7).
+ *
+ * This is the canonical aviary v1 execution surface, byte-for-byte identical across the Adonis,
+ * nestjs-durable, and Python SDKs (verified against the aviary codebase). `search-attr-v2` and other
+ * modern features are layered ON TOP and are NOT part of the v1 baseline — a legacy worker guarantees
+ * only the v1 `search-attributes` surface. Keep this list in lockstep with the other two SDKs.
+ */
+export const LEGACY_V1_CAPABILITIES = Object.freeze([
+    'saga',
+    'signals',
+    'search-attributes',
+    'priority',
+    'entities',
+    'child-workflows',
+    'singleton',
+    'schedules',
+    'continue-as-new',
+    'queries',
+    'cancellation',
+]);
+/**
+ * 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).
+ */
+export function isLegacyDescriptor(raw) {
+    return raw.protocol === undefined;
+}
+/**
+ * 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".
+ */
+export function normalizeDescriptor(raw) {
+    return {
+        instanceId: raw.instanceId,
+        runtime: raw.runtime,
+        sdk: raw.sdk ?? { name: 'unknown', version: '0' },
+        protocol: raw.protocol ?? { ...LEGACY_V1_PROTOCOL },
+        capabilities: raw.capabilities ?? [...LEGACY_V1_CAPABILITIES],
+        workflows: raw.workflows ?? [],
+        steps: raw.steps ?? [],
+        ...(raw.partition !== undefined ? { partition: raw.partition } : {}),
+        ...(raw.namespace !== undefined ? { namespace: raw.namespace } : {}),
+        startedAt: raw.startedAt ?? 0,
+    };
+}
+/** Canonical, order-insensitive projection of a descriptor used for hashing. The three set-valued
+ *  fields are sorted + de-duplicated so member order can never change the hash; scalar fields are
+ *  taken verbatim; optional fields collapse to `null` so present-with-undefined and absent agree. */
+function canonicalizeForHash(d) {
+    const set = (xs) => [...new Set(xs)].sort();
+    // Keys are emitted in a FIXED order (this literal's order) so the stringify below is stable
+    // regardless of the input object's key insertion order.
+    return {
+        instanceId: d.instanceId,
+        runtime: d.runtime,
+        sdk: { name: d.sdk.name, version: d.sdk.version },
+        protocol: { version: d.protocol.version, range: [d.protocol.range[0], d.protocol.range[1]] },
+        capabilities: set(d.capabilities),
+        workflows: set(d.workflows),
+        steps: set(d.steps),
+        partition: d.partition ?? null,
+        namespace: d.namespace ?? null,
+        startedAt: d.startedAt,
+    };
+}
+/**
+ * Deterministic 64-bit FNV-1a hash of a string → 16-char lowercase hex. Chosen over a crypto digest
+ * because it is trivially reproducible in every SDK (TS/Python/…) with no dependency, keeping the
+ * ETag scheme portable for cross-language conformance (design §7.8).
+ */
+function fnv1a64Hex(input) {
+    const OFFSET = 0xcbf29ce484222325n;
+    const PRIME = 0x100000001b3n;
+    const MASK = 0xffffffffffffffffn;
+    let hash = OFFSET;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= BigInt(input.charCodeAt(i) & 0xff);
+        // charCodeAt can exceed a byte; fold the high byte in too so non-ASCII still contributes.
+        hash ^= BigInt((input.charCodeAt(i) >> 8) & 0xff);
+        hash = (hash * PRIME) & MASK;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/**
+ * 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.
+ */
+export function descriptorHash(descriptor) {
+    const canonical = canonicalizeForHash(normalizeDescriptor(descriptor));
+    return fnv1a64Hex(JSON.stringify(canonical));
+}
+/**
+ * Build the compact two-tier heartbeat for a descriptor, stamping the ETag (design §7.2). `ts`
+ * defaults to now and `status` to `'up'`.
+ */
+export function heartbeatStatus(descriptor, opts = {}) {
+    return {
+        ts: opts.ts ?? Date.now(),
+        status: opts.status ?? 'up',
+        descriptorHash: descriptorHash(descriptor),
+    };
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/src/handshake/descriptor.js.map

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

package/dist/src/handshake/negotiate.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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).
+ */
+import { type RawWorkerDescriptor, type WorkerDescriptor } from './descriptor.js';
+/**
+ * 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.
+ */
+export 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. */
+export 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). */
+export 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;
+}
+export 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.
+ */
+export declare function negotiate(localRaw: RawWorkerDescriptor | WorkerDescriptor, remoteRaw: RawWorkerDescriptor | WorkerDescriptor, opts?: NegotiateOptions): NegotiationResult;
+//# sourceMappingURL=negotiate.d.ts.map

package/dist/src/handshake/negotiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/handshake/negotiate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,CAAC;AAE5E;uFACuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,uBAAuB,GAAG,wBAAwB,CAAC;IACzD,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,MAAM,EAAE;QACN,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9B,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,oEAAoE;QACpE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,oEAAoE;QACpE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,gFAAgF;QAChF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH;AAED;4EAC4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,0FAA0F;IAC1F,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE;QAAE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC1E,YAAY,EAAE;QACZ,qFAAqF;QACrF,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,sCAAsC;QACtC,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,sCAAsC;QACtC,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,wEAAwE;IACxE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,mBAAmB,GAAG,gBAAgB,EAChD,SAAS,EAAE,mBAAmB,GAAG,gBAAgB,EACjD,IAAI,GAAE,gBAAqB,GAC1B,iBAAiB,CAgFnB"}

package/dist/src/handshake/negotiate.js

@@ -0,0 +1,108 @@
+/**
+ * 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).
+ */
+import { normalizeDescriptor, } from './descriptor.js';
+const rangesOverlap = (a, b) => Math.max(a[0], b[0]) <= Math.min(a[1], b[1]);
+const difference = (a, b) => {
+    const bset = new Set(b);
+    return [...new Set(a)].filter((x) => !bset.has(x)).sort();
+};
+const intersection = (a, b) => {
+    const bset = new Set(b);
+    return [...new Set(a)].filter((x) => bset.has(x)).sort();
+};
+/**
+ * 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.
+ */
+export function negotiate(localRaw, remoteRaw, opts = {}) {
+    const local = normalizeDescriptor(localRaw);
+    const remote = normalizeDescriptor(remoteRaw);
+    const localRange = local.protocol.range;
+    const remoteRange = remote.protocol.range;
+    const shared = intersection(local.capabilities, remote.capabilities);
+    const missingOnRemote = difference(local.capabilities, remote.capabilities);
+    const missingOnLocal = difference(remote.capabilities, local.capabilities);
+    const capabilities = { shared, missingOnRemote, missingOnLocal };
+    // (1) Protocol range gap → incompatible. This is the ONLY path that blocks dispatch outright.
+    if (!rangesOverlap(localRange, remoteRange)) {
+        return {
+            outcome: 'incompatible',
+            negotiatedProtocol: null,
+            protocol: { localRange, remoteRange },
+            capabilities,
+            reason: {
+                code: 'protocol.incompatible',
+                message: `no common protocol major: local speaks [${localRange[0]}, ${localRange[1]}], ` +
+                    `remote speaks [${remoteRange[0]}, ${remoteRange[1]}]`,
+                detail: { localRange, remoteRange },
+            },
+            local,
+            remote,
+        };
+    }
+    const negotiatedProtocol = Math.min(localRange[1], remoteRange[1]);
+    // (2) A required capability the remote cannot provide → degraded (router parks the specific run).
+    const required = opts.required ?? [];
+    const missingRequired = difference(required, remote.capabilities);
+    if (missingRequired.length > 0) {
+        return {
+            outcome: 'degraded',
+            negotiatedProtocol,
+            protocol: { localRange, remoteRange },
+            capabilities,
+            reason: {
+                code: 'capability.unavailable',
+                message: `remote is missing required capability(ies): ${missingRequired.join(', ')}`,
+                detail: { missingRequired, missingOnRemote, missingOnLocal },
+            },
+            local,
+            remote,
+        };
+    }
+    // (3) Any capability asymmetry → degraded (soft; route capability-requiring work carefully).
+    if (missingOnRemote.length > 0 || missingOnLocal.length > 0) {
+        const parts = [];
+        if (missingOnRemote.length > 0)
+            parts.push(`remote lacks ${missingOnRemote.join(', ')}`);
+        if (missingOnLocal.length > 0)
+            parts.push(`local lacks ${missingOnLocal.join(', ')}`);
+        return {
+            outcome: 'degraded',
+            negotiatedProtocol,
+            protocol: { localRange, remoteRange },
+            capabilities,
+            reason: {
+                code: 'capability.unavailable',
+                message: `capability mismatch: ${parts.join('; ')}`,
+                detail: { missingOnRemote, missingOnLocal },
+            },
+            local,
+            remote,
+        };
+    }
+    // (4) Ranges overlap + full capability parity → compatible.
+    return {
+        outcome: 'compatible',
+        negotiatedProtocol,
+        protocol: { localRange, remoteRange },
+        capabilities,
+        local,
+        remote,
+    };
+}
+//# sourceMappingURL=negotiate.js.map

package/dist/src/handshake/negotiate.js.map

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

package/dist/src/handshake/routing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import { type RawWorkerDescriptor, type WorkerDescriptor } from './descriptor.js';
+/** 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). */
+export type CapabilityRequirement = string[] | {
+    requires?: string[];
+};
+/** Normalize the two accepted shapes to a de-duplicated list of required capability names. */
+export 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.
+ */
+export 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.
+ */
+export declare function missingCapabilities(handler: CapabilityRequirement, worker: RawWorkerDescriptor | WorkerDescriptor): string[];
+/** Filter a fleet down to the workers that can run a handler (design §7.5). */
+export 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. */
+export 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). */
+export interface BlockedResolution {
+    status: 'blocked';
+    /** Exactly the dashboard copy: `blocked: no compatible worker (requires <caps>)`. */
+    reason: string;
+    requires: string[];
+}
+export 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.
+ */
+export declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
+//# sourceMappingURL=routing.d.ts.map

package/dist/src/handshake/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../src/handshake/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAEzB;uFACuF;AACvF,MAAM,MAAM,qBAAqB,GAAG,MAAM,EAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEvE,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAC7C,OAAO,CAKT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAC7C,MAAM,EAAE,CAGV;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,CAAC,SAAS,mBAAmB,GAAG,gBAAgB,EAC7E,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,EAAE,CAEL;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,SAAS,CAAC,mBAAmB,GAAG,gBAAgB,CAAC,EAAE,GAC3D,iBAAiB,CAcnB"}

package/dist/src/handshake/routing.js

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+import { normalizeDescriptor, } from './descriptor.js';
+/** Normalize the two accepted shapes to a de-duplicated list of required capability names. */
+export function requiredCapabilities(handler) {
+    const list = Array.isArray(handler) ? handler : (handler.requires ?? []);
+    return [...new Set(list)];
+}
+/**
+ * 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.
+ */
+export function canRoute(handler, worker) {
+    const required = requiredCapabilities(handler);
+    if (required.length === 0)
+        return true;
+    const advertised = new Set(normalizeDescriptor(worker).capabilities);
+    return required.every((cap) => advertised.has(cap));
+}
+/**
+ * The capabilities a handler requires that `worker` does NOT advertise — the precise routing delta.
+ * Empty iff {@link canRoute} is true.
+ */
+export function missingCapabilities(handler, worker) {
+    const advertised = new Set(normalizeDescriptor(worker).capabilities);
+    return requiredCapabilities(handler).filter((cap) => !advertised.has(cap));
+}
+/** Filter a fleet down to the workers that can run a handler (design §7.5). */
+export function capableWorkers(handler, workers) {
+    return workers.filter((w) => canRoute(handler, w));
+}
+/**
+ * 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.
+ */
+export function resolveRouting(handler, workers) {
+    const requires = requiredCapabilities(handler);
+    const capable = capableWorkers(handler, workers).map(normalizeDescriptor);
+    if (capable.length > 0) {
+        return { status: 'routable', workers: capable, requires };
+    }
+    const suffix = requires.length > 0 ? ` (requires ${requires.join(', ')})` : '';
+    return {
+        status: 'blocked',
+        reason: `blocked: no compatible worker${suffix}`,
+        requires,
+    };
+}
+//# sourceMappingURL=routing.js.map

package/dist/src/handshake/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../../src/handshake/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAMzB,8FAA8F;AAC9F,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,OAA8B,EAC9B,MAA8C;IAE9C,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACrE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA8B,EAC9B,MAA8C;IAE9C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACrE,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAC5B,OAA8B,EAC9B,OAAqB;IAErB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAoBD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA8B,EAC9B,OAA4D;IAE5D,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAE1E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,gCAAgC,MAAM,EAAE;QAChD,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.0";
 export * from './admission.js';
 export * from './control-flow-signal.js';
 export * from './duration.js';
@@ -11,6 +11,7 @@ export * from './interfaces.js';
 export * from './protocol.js';
 export * from './queue.js';
 export * from './remote-workflow-executor.js';
+export * from './workflow-turn.js';
 export * from './tenant-group.js';
 export { DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type StepConfig, type StepRef, stepConfigOf, stepNameOf, } from './step-name-symbol.js';
 export * from './step-ref.js';
@@ -30,10 +31,11 @@ export { getCurrentWorkflowCtx, workflowAls } from './workflow-als.js';
 export { InMemoryStateStore } from './testing/in-memory-state-store.js';
 export { InMemoryTransport } from './testing/in-memory-transport.js';
 export { transports } from './transports/factory.js';
-export type { TransportContext, TransportFactory, MemoryTransportConfig, EventEmitterTransportConfig, QueueTransportConfig, DbTransportConfig, } from './transports/factory.js';
+export type { TransportContext, TransportFactory, MemoryTransportConfig, EventEmitterTransportConfig, QueueTransportConfig, BullMQTransportConfig, DbTransportConfig, } from './transports/factory.js';
 export { EventEmitterTransport, type EventEmitterTransportOptions, } from './transports/event-emitter.js';
 export { QueueTransport, type QueueTransportOptions } from './transports/queue.js';
 export { DbTransport, type DbTransportOptions } from './transports/db.js';
+export { BullMQTransport, type BullMQTransportOptions, type BullMQDeps, createBullMQDeps, } from './transports/bullmq/index.js';
 export { TRANSPORT_TABLES, createDurableTransportTables, dropDurableTransportTables, } from './transports/db-schema.js';
 export { stores } from './stores/factory.js';
 export type { StoreContext, StoreFactory, LucidStoreConfig } from './stores/factory.js';
@@ -44,4 +46,14 @@ export type { ControlPlaneContext, ControlPlaneFactory, RedisControlPlaneConfig,
 export { RedisControlPlane, type RedisControlPlaneOptions, type RedisPubSub, } from './control-plane-redis/redis-control-plane.js';
 export { defineConfig } from './define_config.js';
 export type { DurableConfig } from './define_config.js';
+export type { StandaloneConfig, ControlPlaneConfig, TenantConfig, TenantVerifier, VerifiedTenant, } from './config_types.js';
+export type { RunGateway, DurableTopology, StartRunOptions } from './run-gateway/interface.js';
+export { StoreRunGateway, type RunGatewayEngine, type StoreRunGatewayOptions, } from './run-gateway/store-run-gateway.js';
+export { ProxyRunGateway, type ProxyTransport, type ProxyRunGatewayOptions, } from './run-gateway/proxy-run-gateway.js';
+export { RunRequestResponder, type ResponderTransport, type RunRequestResponderOptions, } from './run-gateway/run-request-responder.js';
+export { signTenantToken, hmacTenantVerifier } from './run-gateway/tenant-auth.js';
+export * from './handshake/descriptor.js';
+export * from './handshake/negotiate.js';
+export * from './handshake/routing.js';
+export * from './dispatch-routing.js';
 //# sourceMappingURL=index.d.ts.map