@adonis-agora/durable 0.9.1 → 0.11.0

package/dist/src/role_bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role_bindings.js","sourceRoot":"","sources":["../../src/role_bindings.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mCAAmC,CAAC;AACvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,sCAAsC,CAAC;AAC7E,MAAM,CAAC,MAAM,6BAA6B,GAAG,6CAA6C,CAAC;AAC3F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,iCAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkB,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAezE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAkB;IACpD,MAAM,CAAC,GAAG,SAAuD,CAAC;IAClE,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,qBAAqB,KAAK,UAAU;QAAE,OAAO,CAAC,CAAC,qBAAqB,EAAE,CAAC;IACzF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAkB;IACvD,MAAM,CAAC,GAAG,SAA2D,CAAC;IACtE,OAAO,CACL,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,YAAY,KAAK,UAAU;QACpC,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU;QAClC,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU;QACvC,OAAO,CAAC,CAAC,kBAAkB,KAAK,UAAU,CAC3C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAkB;IACnD,MAAM,CAAC,GAAG,SAAuD,CAAC;IAClE,OAAO,CACL,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,gBAAgB,KAAK,UAAU;QACxC,OAAO,CAAC,CAAC,kBAAkB,KAAK,UAAU;QAC1C,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU;QAClC,OAAO,CAAC,CAAC,aAAa,KAAK,UAAU,CACtC,CAAC;AACJ,CAAC"}

package/dist/src/run-gateway/interface.d.ts

@@ -0,0 +1,89 @@
+import type { StartOptions } from '../engine.js';
+import type { EngineEvent, GroupHealth, RunQuery, RunResult, SearchAttributes, StepCheckpoint, WorkflowRun } from '../interfaces.js';
+import type { WorkflowRef } from '../workflow-ref.js';
+/**
+ * Which durable topology a gateway speaks for — surfaced so an operator/consumer can tell a control
+ * plane from a tenant (or a single-process standalone) at a glance. Cheap, synchronous, LOCAL
+ * knowledge: no round-trip. Byte-compatible with aviary's `DurableTopology`, plus a `standalone` role
+ * for the single-process deployment this package targets first (aviary is cluster-only, so it never
+ * needed one). The store-backed gateway ({@link RunGateway} via `StoreRunGateway`) is the operator; a
+ * later `ProxyRunGateway` is the `tenant`.
+ */
+export interface DurableTopology {
+    role: 'control-plane' | 'standalone' | 'tenant';
+    /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
+    tenant?: string | undefined;
+}
+/**
+ * Options for {@link RunGateway.start}. Extends the engine's {@link StartOptions} with an OPTIONAL
+ * `runId`: the gateway mints one (idempotency key) when the caller doesn't supply it, so a gateway
+ * `start` reads `start(workflow, input, opts?)` — one fewer positional than the engine's
+ * `start(workflow, input, runId, opts?)` — matching §8's verb shape while staying idempotent-by-id.
+ */
+export interface StartRunOptions extends StartOptions {
+    /** Explicit run id (idempotency key). Omit to have the gateway mint a fresh one. */
+    runId?: string | undefined;
+}
+/**
+ * The bounded read / control / stream surface a consumer (a controller, the dashboard, a CLI) needs,
+ * intended to be satisfied by BOTH durable topologies: a `standalone` / `control-plane` deployment
+ * binds the store-backed `StoreRunGateway` (delegates to the local {@link WorkflowEngine}); a `tenant`
+ * deployment will later bind a `ProxyRunGateway` that round-trips these same verbs over the transport
+ * to the control plane (Wave 2 — NOT built here). The interface is deliberately transport-agnostic —
+ * every verb is `Promise`-returning (or a synchronous unsubscribe for `subscribe`) so a proxy can
+ * implement it without changing a single signature.
+ *
+ * Verb set follows the store-less cluster design §8. Names/shapes are kept byte-compatible with
+ * aviary's `RunGateway` where the same verb exists there (`topology`, `listRuns`, `cancel`,
+ * `redispatchPending`, `subscribe`); the §8-only verbs (`getRun`, `getCheckpoints`, `signal`,
+ * `start`, `getSearchAttributes`) take engine-faithful shapes.
+ */
+export interface RunGateway {
+    /** This deployment's durable role — synchronous, local metadata (no store/transport hit). */
+    topology(): DurableTopology;
+    /** Read a run's current persisted state, or null if unknown. */
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    /** List runs matching `query` (paged via `limit`/`offset`, filtered by workflow/status/tag/search
+     *  attributes), newest activity first per the store's ordering. */
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /** A run's step checkpoints in execution order — its timeline / history (the detail-view body). */
+    getCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    /** The ids of the runs this run spawned (parent→child tree) — the detail view's children list. Empty
+     *  for a leaf run (or an unknown one). A `ProxyRunGateway` round-trips this over the P4 wire. */
+    getRunChildren(runId: string): Promise<string[]>;
+    /** Typed, queryable run data (`searchAttributes`) stamped on the run, or undefined if it has none. */
+    getSearchAttributes(runId: string): Promise<SearchAttributes | undefined>;
+    /** Per-group worker health (queue backlog + live worker heartbeats). On a control plane this is
+     *  every group; a tenant proxy scopes it to the tenant's own groups. */
+    workerHealth(): Promise<GroupHealth[]>;
+    /**
+     * Start a new run and return its result (carrying the `runId` — minted when `opts.runId` is
+     * omitted). Idempotent by run id: a redelivered start for the same id returns the existing run's
+     * state instead of creating a duplicate.
+     */
+    start(workflow: WorkflowRef, input: unknown, opts?: StartRunOptions): Promise<RunResult>;
+    /**
+     * Deliver an external `signal` (by name/token) with `payload` to the run addressed by `runId`,
+     * resuming a run parked on it. Returns the run result, or null if nothing was waiting (the payload
+     * is buffered for the next waiter — reliable signals). `runId` addresses the target run for a proxy
+     * to route to its owning control plane.
+     */
+    signal(runId: string, signal: string, payload?: unknown): Promise<RunResult | null>;
+    /** Cancel a run. Pass `{ compensate: true }` to run the saga undo first. Returns the run result, or
+     *  null if the run is unknown. */
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    /**
+     * Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     * dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     * plus how many steps were re-dispatched, or null if the run is unknown / the deployment can't
+     * re-dispatch. Byte-compatible with aviary's `redispatchPending`.
+     */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
+    /** Live lifecycle events for ONE run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/src/run-gateway/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/run-gateway/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,eAAe,GAAG,YAAY,GAAG,QAAQ,CAAC;IAChD,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,QAAQ,IAAI,eAAe,CAAC;IAE5B,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;uEACmE;IACnE,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAElD,mGAAmG;IACnG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEzD;qGACiG;IACjG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD,sGAAsG;IACtG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IAE1E;4EACwE;IACxE,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEvC;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEzF;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEpF;sCACkC;IAClC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAElF;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,SAAS,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzF,kGAAkG;IAClG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7E"}

package/dist/src/run-gateway/interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/src/run-gateway/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../../src/run-gateway/interface.ts"],"names":[],"mappings":""}

package/dist/src/run-gateway/proxy-run-gateway.d.ts

@@ -0,0 +1,84 @@
+import type { EngineEvent, GroupHealth, RunQuery, RunReply, RunRequest, RunResult, SearchAttributes, StartRunMessage, StepCheckpoint, TenantEvent, WorkflowRun } from '../interfaces.js';
+import type { WorkflowRef } from '../workflow-ref.js';
+import type { DurableTopology, RunGateway, StartRunOptions } from './interface.js';
+/**
+ * The narrow slice of {@link import('../interfaces.js').Transport} the {@link ProxyRunGateway} needs —
+ * the P4 store-less protocol methods, here declared NON-optional. They are all optional on the full
+ * `Transport` (only broker transports carry P4), so the wiring code capability-checks
+ * (`transport.dispatchRunRequest ? … : …`) before handing the transport in — the same pattern the
+ * operator-side responder uses. Mirrors aviary's `ProxyRunGateway` transport dependency.
+ */
+export interface ProxyTransport {
+    dispatchStartRun(msg: StartRunMessage): Promise<void>;
+    dispatchRunRequest(msg: RunRequest): Promise<void>;
+    onRunReply(handler: (reply: RunReply) => void): void;
+    onTenantEvent(tenant: string, handler: (evt: TenantEvent) => void): () => void;
+}
+/** Options for {@link ProxyRunGateway}. */
+export interface ProxyRunGatewayOptions {
+    /**
+     * Which tenant/partition this pod is — the human namespace name (NOT the signed token). Stamped on
+     * {@link DurableTopology.tenant}, and it is the channel the proxy live-tails
+     * (`${P}-tenant-events-<partition>`), because the control plane re-publishes a run's events keyed by
+     * its resolved NAMESPACE (which equals this partition), never by the token.
+     */
+    partition: string;
+    /**
+     * The pod's signed claim, presented verbatim in the `tenant` field of every {@link RunRequest} /
+     * {@link StartRunMessage}. The responder verifies it and DERIVES the real tenant from it, ignoring
+     * the body (spec §9). Omit to run token-less on prefix/network isolation alone (aviary-compatible) —
+     * then the raw `partition` travels in the `tenant` field and the responder trusts it directly.
+     */
+    token?: string | undefined;
+    /** Round-trip timeout (ms) for a proxied read/control/start. Default 10_000. Spec §8: on timeout the
+     *  proxy fails fast with a clear error rather than hanging a request forever. */
+    requestTimeoutMs?: number | undefined;
+}
+/**
+ * Tenant-side {@link RunGateway} — a store-less pod's read/control/start surface, implemented ENTIRELY
+ * over the wire. It owns NO store (structural isolation, spec §5): every verb round-trips to the
+ * control plane's `RunRequestResponder` and back.
+ *
+ * - read/control (`getRun`/`listRuns`/`getCheckpoints`/`getSearchAttributes`/`workerHealth`/`signal`/
+ *   `cancel`/`redispatchPending`) → publish a {@link RunRequest} correlated by a minted `requestId`,
+ *   await the {@link RunReply} within `requestTimeoutMs`;
+ * - `start` → publish a {@link StartRunMessage} (its own channel, byte-compatible with aviary), then
+ *   await the reply the responder correlates by the minted `runId`;
+ * - `subscribe` → bridge onto the transport's per-tenant event stream (`${P}-tenant-events-<partition>`);
+ * - `topology` → `{ role: 'tenant', tenant: partition }` — synchronous local metadata, no round-trip.
+ *
+ * Fail-fast: a request whose reply never arrives within the timeout (a down/unreachable control plane,
+ * a dropped reply) rejects with a clear, verb-named error instead of hanging forever.
+ *
+ * Idiomatic AdonisJS: a plain class constructed with its transport dependency, wired by the package's
+ * provider for the `tenant` role. The counterpart to the operator-side `StoreRunGateway`.
+ */
+export declare class ProxyRunGateway implements RunGateway {
+    #private;
+    constructor(transport: ProxyTransport, options: ProxyRunGatewayOptions);
+    topology(): DurableTopology;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    getCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getRunChildren(runId: string): Promise<string[]>;
+    getSearchAttributes(runId: string): Promise<SearchAttributes | undefined>;
+    /** Round-trips to the operator, which scopes the result to this tenant's own `@<partition>` groups. */
+    workerHealth(): Promise<GroupHealth[]>;
+    /**
+     * Publish a {@link StartRunMessage} (its own `${P}-start-run` channel) and await the reply the
+     * responder correlates by the minted `runId`. The proxy ALWAYS mints/forwards a `runId` (idempotency
+     * key) so the fire-and-forget aviary `StartRunMessage` can carry a correlated answer back without
+     * changing its bytes.
+     */
+    start(workflow: WorkflowRef, input: unknown, opts?: StartRunOptions): Promise<RunResult>;
+    signal(runId: string, signal: string, payload?: unknown): Promise<RunResult | null>;
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
+    /** Live-tail ONE run by bridging onto this tenant's event channel and filtering by `runId`. */
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+//# sourceMappingURL=proxy-run-gateway.d.ts.map

package/dist/src/run-gateway/proxy-run-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-run-gateway.d.ts","sourceRoot":"","sources":["../../../src/run-gateway/proxy-run-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EAEV,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,WAAW,EACX,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;IACrD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAChF;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;qFACiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAeD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,YAAW,UAAU;;gBAOpC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,sBAAsB;IA0DtE,QAAQ,IAAI,eAAe;IAI3B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAIlD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIjD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAIxD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIhD,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAIzE,uGAAuG;IACvG,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAItC;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAexF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAQnF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAMjF,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,SAAS,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAOxF,+FAA+F;IAC/F,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;CAK5E"}

package/dist/src/run-gateway/proxy-run-gateway.js

@@ -0,0 +1,142 @@
+/**
+ * Tenant-side {@link RunGateway} — a store-less pod's read/control/start surface, implemented ENTIRELY
+ * over the wire. It owns NO store (structural isolation, spec §5): every verb round-trips to the
+ * control plane's `RunRequestResponder` and back.
+ *
+ * - read/control (`getRun`/`listRuns`/`getCheckpoints`/`getSearchAttributes`/`workerHealth`/`signal`/
+ *   `cancel`/`redispatchPending`) → publish a {@link RunRequest} correlated by a minted `requestId`,
+ *   await the {@link RunReply} within `requestTimeoutMs`;
+ * - `start` → publish a {@link StartRunMessage} (its own channel, byte-compatible with aviary), then
+ *   await the reply the responder correlates by the minted `runId`;
+ * - `subscribe` → bridge onto the transport's per-tenant event stream (`${P}-tenant-events-<partition>`);
+ * - `topology` → `{ role: 'tenant', tenant: partition }` — synchronous local metadata, no round-trip.
+ *
+ * Fail-fast: a request whose reply never arrives within the timeout (a down/unreachable control plane,
+ * a dropped reply) rejects with a clear, verb-named error instead of hanging forever.
+ *
+ * Idiomatic AdonisJS: a plain class constructed with its transport dependency, wired by the package's
+ * provider for the `tenant` role. The counterpart to the operator-side `StoreRunGateway`.
+ */
+export class ProxyRunGateway {
+    #transport;
+    #partition;
+    #wireTenant;
+    #timeoutMs;
+    #pending = new Map();
+    constructor(transport, options) {
+        this.#transport = transport;
+        this.#partition = options.partition;
+        // The signed token (verified + tenant-derived by the responder) travels in the `tenant` field; with
+        // no token, the raw partition does (prefix-isolation-only, aviary-compatible).
+        this.#wireTenant = options.token ?? options.partition;
+        this.#timeoutMs = options.requestTimeoutMs ?? 10_000;
+        // One reply subscription for the whole gateway; every RunReply is matched to its pending call by id.
+        this.#transport.onRunReply((reply) => this.#handleReply(reply));
+    }
+    #handleReply(reply) {
+        const pending = this.#pending.get(reply.requestId);
+        if (!pending)
+            return; // an unknown/expired id (or another pod's reply on the shared channel) — ignore
+        clearTimeout(pending.timer);
+        this.#pending.delete(reply.requestId);
+        if (reply.result.ok) {
+            pending.resolve(reply.result.data);
+        }
+        else {
+            const err = new Error(reply.result.error.message);
+            if (reply.result.error.code !== undefined)
+                err.code = reply.result.error.code;
+            pending.reject(err);
+        }
+    }
+    /** Register a pending reply keyed by `correlationId`, arm the fail-fast timeout, and run `send` (the
+     *  publish). A publish rejection settles the pending call immediately; a missing reply trips the timer. */
+    #awaitReply(correlationId, verbLabel, send) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(correlationId);
+                reject(new Error(`durable control plane did not answer ${verbLabel} within ${this.#timeoutMs}ms`));
+            }, this.#timeoutMs);
+            // Don't keep the event loop alive just waiting on a reply.
+            timer.unref?.();
+            this.#pending.set(correlationId, { resolve: resolve, reject, timer });
+            send().catch((error) => {
+                const stillPending = this.#pending.get(correlationId);
+                if (!stillPending)
+                    return; // already settled (timed out / replied) — don't double-reject
+                clearTimeout(stillPending.timer);
+                this.#pending.delete(correlationId);
+                stillPending.reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+    /** Publish a read/control {@link RunRequest} with a freshly minted `requestId` and await its reply. */
+    #request(body) {
+        const requestId = globalThis.crypto.randomUUID();
+        return this.#awaitReply(requestId, body.kind, () => this.#transport.dispatchRunRequest({ requestId, tenant: this.#wireTenant, body }));
+    }
+    topology() {
+        return { role: 'tenant', tenant: this.#partition };
+    }
+    getRun(runId) {
+        return this.#request({ kind: 'getRun', runId });
+    }
+    listRuns(query) {
+        return this.#request({ kind: 'listRuns', query });
+    }
+    getCheckpoints(runId) {
+        return this.#request({ kind: 'getCheckpoints', runId });
+    }
+    getRunChildren(runId) {
+        return this.#request({ kind: 'getRunChildren', runId });
+    }
+    getSearchAttributes(runId) {
+        return this.#request({ kind: 'getSearchAttributes', runId });
+    }
+    /** Round-trips to the operator, which scopes the result to this tenant's own `@<partition>` groups. */
+    workerHealth() {
+        return this.#request({ kind: 'workerHealth' });
+    }
+    /**
+     * Publish a {@link StartRunMessage} (its own `${P}-start-run` channel) and await the reply the
+     * responder correlates by the minted `runId`. The proxy ALWAYS mints/forwards a `runId` (idempotency
+     * key) so the fire-and-forget aviary `StartRunMessage` can carry a correlated answer back without
+     * changing its bytes.
+     */
+    start(workflow, input, opts) {
+        const runId = opts?.runId ?? globalThis.crypto.randomUUID();
+        const msg = {
+            tenant: this.#wireTenant,
+            // A `WorkflowRef` is a class or a string; the wire carries the registered NAME. The engine's
+            // string overload accepts both at runtime, so resolve to the string form on the wire.
+            workflow: workflow,
+            input,
+            runId,
+            ...(opts?.tags !== undefined ? { tags: opts.tags } : {}),
+            ...(opts?.searchAttributes !== undefined ? { searchAttributes: opts.searchAttributes } : {}),
+        };
+        return this.#awaitReply(runId, 'start', () => this.#transport.dispatchStartRun(msg));
+    }
+    signal(runId, signal, payload) {
+        return this.#request(payload === undefined
+            ? { kind: 'signal', runId, signal }
+            : { kind: 'signal', runId, signal, payload });
+    }
+    cancel(runId, opts) {
+        return this.#request(opts === undefined ? { kind: 'cancel', runId } : { kind: 'cancel', runId, opts });
+    }
+    redispatchPending(runId) {
+        return this.#request({
+            kind: 'redispatch',
+            runId,
+        });
+    }
+    /** Live-tail ONE run by bridging onto this tenant's event channel and filtering by `runId`. */
+    subscribe(runId, onEvent) {
+        return this.#transport.onTenantEvent(this.#partition, (evt) => {
+            if (evt.event.runId === runId)
+                onEvent(evt.event);
+        });
+    }
+}
+//# sourceMappingURL=proxy-run-gateway.js.map

package/dist/src/run-gateway/proxy-run-gateway.js.map

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

package/dist/src/run-gateway/run-request-responder.d.ts

@@ -0,0 +1,67 @@
+import type { TenantVerifier } from '../config_types.js';
+import type { EngineEvent, RunReply, RunRequest, StartRunMessage, TenantEvent } from '../interfaces.js';
+import type { RunGateway } from './interface.js';
+/**
+ * The narrow slice of {@link import('../interfaces.js').Transport} the {@link RunRequestResponder}
+ * consumes — the control-plane side of the P4 protocol, declared NON-optional. All four are optional
+ * on the full `Transport` (only broker transports carry P4), so the wiring code capability-checks
+ * before constructing the responder. Mirrors aviary's `RunRequestTransport` narrowing convention.
+ */
+export interface ResponderTransport {
+    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
+    onStartRun(handler: (msg: StartRunMessage) => Promise<void>): void;
+    publishRunReply(reply: RunReply): Promise<void>;
+    publishTenantEvent(evt: TenantEvent): Promise<void>;
+}
+/** Options for {@link RunRequestResponder}. */
+export interface RunRequestResponderOptions {
+    /**
+     * Verifies a tenant's signed claim and DERIVES the real tenant from it (spec §9). Absent → the pod
+     * runs on prefix/network isolation alone and the wire `tenant` is trusted verbatim (aviary-compatible);
+     * present → an invalid/tampered/absent token is REJECTED with an `unauthorized` error reply, and the
+     * body's tenant claim is discarded in favour of the verified one.
+     */
+    verifyTenant?: TenantVerifier | undefined;
+    /**
+     * The engine's GLOBAL lifecycle-event source (typically `engine.subscribe`). The responder
+     * re-publishes each event, scoped by the run's namespace, as a {@link TenantEvent} so a store-less
+     * tenant can live-tail its OWN runs. Omit to disable tenant-events republishing (e.g. a control plane
+     * that only answers read/control, with live-tail served elsewhere).
+     */
+    subscribeEngineEvents?: ((listener: (event: EngineEvent) => void) => () => void) | undefined;
+}
+/**
+ * Operator-side consumer of a store-less tenant's P4 traffic — the TRUST BOUNDARY of the tenant run
+ * gateway (spec §8/§9). It answers each {@link RunRequest}/{@link StartRunMessage} against a
+ * store-backed {@link RunGateway} (typically `StoreRunGateway`), and re-publishes the engine's
+ * lifecycle events to each tenant's channel.
+ *
+ * Enforcement, per request, BEFORE any run is touched:
+ * 1. **Authenticate + derive tenant.** With a {@link RunRequestResponderOptions.verifyTenant}, the
+ *    signed token (carried in the wire `tenant` field) is verified and the real tenant is DERIVED from
+ *    it; the body's claim is ignored. An invalid token short-circuits to an `unauthorized` reply.
+ * 2. **`listRuns` is namespace-forced** to the derived tenant — the client's `namespace` is discarded,
+ *    never merely validated, so a tenant cannot enumerate another's runs.
+ * 3. **`workerHealth` is group-scoped** to the tenant's own `@<tenant>` queues.
+ * 4. **Every runId-bearing verb** (`getRun`/`getCheckpoints`/`getSearchAttributes`/`signal`/`cancel`/
+ *    `redispatch`) loads the run FIRST and rejects with `cross-tenant` when `run.namespace` isn't the
+ *    derived tenant — anti-IDOR, so a tenant can never read OR act on another tenant's run.
+ * 5. **`start` forces the run's namespace** to the derived tenant, so a started run is owned by, and
+ *    later only reachable by, that tenant.
+ * 6. **Unknown verbs are rejected** rather than silently ignored.
+ *
+ * Do not weaken any of these — they are the isolation guarantee of the store-less cluster.
+ */
+export declare class RunRequestResponder {
+    #private;
+    constructor(transport: ResponderTransport, gateway: RunGateway, options?: RunRequestResponderOptions);
+    /**
+     * Register the consumers on the transport (idempotent per transport). Each request is answered
+     * independently; a handler failure never throws back into the transport — every error is captured
+     * into an error reply. If an engine-event source was given, starts re-publishing tenant events.
+     */
+    start(): void;
+    /** Stop re-publishing tenant events (the transport consumers are torn down with the transport). */
+    stop(): void;
+}
+//# sourceMappingURL=run-request-responder.d.ts.map

package/dist/src/run-gateway/run-request-responder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-request-responder.d.ts","sourceRoot":"","sources":["../../../src/run-gateway/run-request-responder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EAER,UAAU,EAEV,eAAe,EACf,WAAW,EAEZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChE,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnE,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC1C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CAC9F;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAmB;;gBAe5B,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,UAAU,EACnB,OAAO,GAAE,0BAA+B;IAQ1C;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAgBb,mGAAmG;IACnG,IAAI,IAAI,IAAI;CA4Kb"}