@adonis-agora/durable 0.9.1 → 0.11.0

package/dist/src/run-gateway/run-request-responder.js

@@ -0,0 +1,228 @@
+/** `EngineEvent` types that END a run's lifecycle — no further event for that `runId` follows, so it is
+ *  the safe point to drop the run from the namespace cache. Cancellation + dead-lettering are both
+ *  emitted as `run.failed`; `run.suspended` is NOT terminal (a suspended run resumes). */
+function isTerminalRunEvent(event) {
+    return event.type === 'run.completed' || event.type === 'run.failed';
+}
+/**
+ * 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 class RunRequestResponder {
+    #transport;
+    #gateway;
+    #verifyTenant;
+    #subscribeEngineEvents;
+    // Per-run namespace memo for tenant-events republishing: read the store at most once per run id (a
+    // `step.*` event carries no namespace), dropped on the run's terminal event so it stays bounded to
+    // in-flight runs. `null` = "resolved, not a tenant" (distinct from absent = "not yet resolved").
+    #runNamespaces = new Map();
+    #unsubscribeEvents;
+    constructor(transport, gateway, options = {}) {
+        this.#transport = transport;
+        this.#gateway = gateway;
+        this.#verifyTenant = options.verifyTenant;
+        this.#subscribeEngineEvents = options.subscribeEngineEvents;
+    }
+    /**
+     * 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() {
+        this.#transport.onRunRequest(async (msg) => {
+            const reply = await this.#handleRequest(msg);
+            await this.#transport.publishRunReply(reply);
+        });
+        this.#transport.onStartRun(async (msg) => {
+            const reply = await this.#handleStart(msg);
+            if (reply)
+                await this.#transport.publishRunReply(reply);
+        });
+        if (this.#subscribeEngineEvents) {
+            this.#unsubscribeEvents = this.#subscribeEngineEvents((event) => {
+                void this.#republish(event);
+            });
+        }
+    }
+    /** Stop re-publishing tenant events (the transport consumers are torn down with the transport). */
+    stop() {
+        this.#unsubscribeEvents?.();
+        this.#unsubscribeEvents = undefined;
+        this.#runNamespaces.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // read / control
+    // ---------------------------------------------------------------------------
+    async #handleRequest(msg) {
+        const tenant = await this.#resolveTenant(msg.tenant);
+        if (tenant === null) {
+            return reply(msg.requestId, {
+                ok: false,
+                error: { message: 'invalid or unauthorized tenant token', code: 'unauthorized' },
+            });
+        }
+        const { body } = msg;
+        if (body.kind === 'listRuns') {
+            // Force the namespace to the verified tenant — the client value is DISCARDED, never validated, so
+            // a tenant can't widen its own query into another's namespace.
+            const data = await this.#gateway.listRuns({ ...body.query, namespace: tenant });
+            return reply(msg.requestId, { ok: true, data });
+        }
+        if (body.kind === 'workerHealth') {
+            // Not runId-bearing. Scope by the group-name convention instead: a tenant's queues are suffixed
+            // `<name>@<tenant>`, so keep only groups ending in `@<tenant>` — the operator's own bare groups
+            // and every other tenant's are dropped.
+            const all = await this.#gateway.workerHealth();
+            const data = all.filter((h) => h.group.endsWith(`@${tenant}`));
+            return reply(msg.requestId, { ok: true, data });
+        }
+        // Every remaining verb is runId-bearing. Load the run FIRST — before calling the verb — so a
+        // cross-tenant request never reaches the gateway's mutating methods (signal/cancel/redispatch) or
+        // leaks another tenant's run via a read (getRun/getCheckpoints/getSearchAttributes).
+        const run = await this.#gateway.getRun(body.runId);
+        if (run && run.namespace !== tenant) {
+            return reply(msg.requestId, {
+                ok: false,
+                error: { message: 'run belongs to another tenant', code: 'cross-tenant' },
+            });
+        }
+        try {
+            const data = await this.#callVerb(body, run);
+            return reply(msg.requestId, { ok: true, data });
+        }
+        catch (err) {
+            return reply(msg.requestId, {
+                ok: false,
+                error: { message: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+    /** Dispatch a runId-bearing verb. `run` is the already-loaded run (ownership-checked by the caller) —
+     *  reused for `getRun` so it isn't fetched twice. An unknown verb is rejected, never silently dropped. */
+    #callVerb(body, run) {
+        switch (body.kind) {
+            case 'getRun':
+                return Promise.resolve(run);
+            case 'getCheckpoints':
+                return this.#gateway.getCheckpoints(body.runId);
+            case 'getRunChildren':
+                return this.#gateway.getRunChildren(body.runId);
+            case 'getSearchAttributes':
+                return this.#gateway.getSearchAttributes(body.runId);
+            case 'signal':
+                return this.#gateway.signal(body.runId, body.signal, body.payload);
+            case 'cancel':
+                return this.#gateway.cancel(body.runId, body.opts);
+            case 'redispatch':
+                return this.#gateway.redispatchPending(body.runId);
+            default:
+                // Exhaustiveness guard: an unrecognised verb (a newer/incompatible client) is rejected loudly.
+                return Promise.reject(new Error(`unknown run-request verb: ${body.kind}`));
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // start-run
+    // ---------------------------------------------------------------------------
+    /**
+     * Answer a start-run. The reply is correlated by the message's `runId` (the proxy mints/forwards one
+     * so the fire-and-forget aviary `StartRunMessage` can carry a correlated answer). The run's namespace
+     * is FORCED to the verified tenant, so the started run is owned by that tenant and later reachable
+     * only by it. Returns `undefined` (no reply) only when there is no id to correlate on.
+     */
+    async #handleStart(msg) {
+        const correlationId = msg.runId;
+        const tenant = await this.#resolveTenant(msg.tenant);
+        if (tenant === null) {
+            return correlationId === undefined
+                ? undefined
+                : reply(correlationId, {
+                    ok: false,
+                    error: { message: 'invalid or unauthorized tenant token', code: 'unauthorized' },
+                });
+        }
+        try {
+            const result = await this.#gateway.start(msg.workflow, msg.input, {
+                ...(msg.runId !== undefined ? { runId: msg.runId } : {}),
+                ...(msg.tags !== undefined ? { tags: msg.tags } : {}),
+                ...(msg.searchAttributes !== undefined ? { searchAttributes: msg.searchAttributes } : {}),
+                // Force the run's namespace to the verified tenant — never a body claim (anti-IDOR at the root).
+                namespace: tenant,
+            });
+            return reply(correlationId ?? result.runId, { ok: true, data: result });
+        }
+        catch (err) {
+            return correlationId === undefined
+                ? undefined
+                : reply(correlationId, {
+                    ok: false,
+                    error: { message: err instanceof Error ? err.message : String(err) },
+                });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // tenant-events republishing
+    // ---------------------------------------------------------------------------
+    async #republish(event) {
+        const namespace = await this.#namespaceFor(event);
+        // A terminal run emits no further events — drop its cache entry now regardless of whether this event
+        // was itself re-published, so the slot is reclaimed even for a bare/default run.
+        if (isTerminalRunEvent(event))
+            this.#runNamespaces.delete(event.runId);
+        // Skip bare/default runs — no real tenant to re-publish to.
+        if (!namespace || namespace === 'default')
+            return;
+        await this.#transport.publishTenantEvent({ tenant: namespace, event }).catch(() => undefined);
+    }
+    async #namespaceFor(event) {
+        if (this.#runNamespaces.has(event.runId)) {
+            const cached = this.#runNamespaces.get(event.runId);
+            return cached === null ? undefined : cached;
+        }
+        if (event.namespace !== undefined) {
+            this.#runNamespaces.set(event.runId, event.namespace === 'default' ? null : event.namespace);
+            return event.namespace === 'default' ? undefined : event.namespace;
+        }
+        const run = await this.#gateway.getRun(event.runId);
+        const ns = run?.namespace !== undefined && run.namespace !== 'default' ? run.namespace : null;
+        this.#runNamespaces.set(event.runId, ns);
+        return ns === null ? undefined : ns;
+    }
+    // ---------------------------------------------------------------------------
+    // trust boundary
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve the tenant a request is ALLOWED to act as. With a verifier, the wire `tenant` is treated as
+     * the signed token: it is verified and the real tenant DERIVED from it (`null` on reject). Without a
+     * verifier, the wire value is trusted verbatim (prefix/network isolation only, aviary-compatible).
+     */
+    async #resolveTenant(wireTenant) {
+        if (!this.#verifyTenant)
+            return wireTenant;
+        const verified = await this.#verifyTenant({ token: wireTenant, tenant: wireTenant });
+        return verified ? verified.tenant : null;
+    }
+}
+/** Build a correlated {@link RunReply}. */
+function reply(requestId, result) {
+    return { requestId, result };
+}
+//# sourceMappingURL=run-request-responder.js.map

package/dist/src/run-gateway/run-request-responder.js.map

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

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

@@ -0,0 +1,90 @@
+import type { EngineEvent, GroupHealth, RunQuery, RunResult, SearchAttributes, StepCheckpoint, WorkflowRun } from '../interfaces.js';
+import type { WorkflowRef } from '../workflow-ref.js';
+import type { DurableTopology, RunGateway, StartRunOptions } from './interface.js';
+/**
+ * The slice of {@link WorkflowEngine} the {@link StoreRunGateway} delegates to. Declared structurally
+ * (not by importing the concrete class) so the gateway depends only on the verbs it forwards, and so
+ * `redispatchPending` — which the AdonisJS engine does NOT yet implement (the lost-remote-step
+ * re-dispatch machinery from aviary's core engine isn't ported) — can be declared OPTIONAL: the
+ * gateway calls it when present and degrades to `null` when absent. The real `WorkflowEngine` is
+ * structurally assignable to this.
+ *
+ * TODO(integrator): once the engine grows a `redispatchPending(runId)` method (port of aviary
+ * `WorkflowEngine.redispatchPending`), this optional member becomes a hard delegation. Consider
+ * exporting a shared engine-facing port type from the package so this local structural mirror can be
+ * dropped.
+ */
+export interface RunGatewayEngine {
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getRunChildren(parentRunId: string): Promise<string[]>;
+    workerHealth(extra?: string[]): Promise<GroupHealth[]>;
+    start(workflow: string, input: unknown, runId: string, opts?: StartRunOptions): Promise<RunResult>;
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    subscribe(listener: (event: EngineEvent) => void): () => void;
+    /** Optional — absent on the current AdonisJS engine; see {@link RunGatewayEngine} note. */
+    redispatchPending?(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
+}
+/** Options for {@link StoreRunGateway}. */
+export interface StoreRunGatewayOptions {
+    /**
+     * The role reported by {@link StoreRunGateway.topology}. `standalone` for a single-process
+     * deployment (the default — this package's first target); `control-plane` when this engine is the
+     * store-owning operator that tenant proxies round-trip to. A store-backed gateway is never a
+     * `tenant` (that's the proxy's role), so only these two are accepted.
+     */
+    role?: 'standalone' | 'control-plane' | undefined;
+}
+/**
+ * Store-backed {@link RunGateway} — the operator-side implementation. Wraps the local
+ * {@link WorkflowEngine} and forwards each read/control/stream verb to the engine's existing method,
+ * exactly the surface a `standalone` or `control-plane` deployment exposes. It holds NO state of its
+ * own beyond the injected engine and its declared role; all durability lives in the engine/store.
+ *
+ * Idiomatic AdonisJS: a plain class constructed with its dependency, wired by the package's provider /
+ * `defineConfig` (no framework DI decorators). A later `ProxyRunGateway` (Wave 2) will implement the
+ * SAME {@link RunGateway} interface over the transport for `tenant` deployments — nothing here needs
+ * to change for that.
+ */
+export declare class StoreRunGateway implements RunGateway {
+    #private;
+    constructor(engine: RunGatewayEngine, options?: StoreRunGatewayOptions);
+    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>;
+    workerHealth(): Promise<GroupHealth[]>;
+    start(workflow: WorkflowRef, input: unknown, opts?: StartRunOptions): Promise<RunResult>;
+    /**
+     * Deliver `signal` (by name) with `payload` to the addressed run. Confirmed against the engine's
+     * waiter convention (design §8): `engine.signal` is GENUINELY GLOBAL-BY-NAME — `ctx.waitForSignal(name)`
+     * registers a waiter under the caller-chosen `name` VERBATIM, and `engine.signal(name, payload)` matches
+     * by that exact string. There is NO `signal:<runId>:<name>` waiter convention: the run-scoped families
+     * (`task:<runId>:<name>`, `update:<runId>:<name>`, `wh:<runId>:<seq>`, `child:<id>`) are the FRAMEWORK
+     * composing the token before it hands it to `waitForSignal` — an external, user-named signal never is.
+     * Deriving a run-scoped token here would therefore reach NO waiter (a run parked on `waitForSignal('go')`
+     * would never see `signal('go')`), so the name is forwarded unchanged.
+     *
+     * `runId` is NOT dropped from the port on purpose: the `RunRequestResponder` uses it for the tenant
+     * ownership check (loads the run, rejects cross-tenant) BEFORE this delegates, and a `ProxyRunGateway`
+     * uses it to route to the run's owning control plane. So the signal stays name-addressed while the run
+     * boundary is still enforced one layer up.
+     */
+    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>;
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+//# sourceMappingURL=store-run-gateway.d.ts.map

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

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

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

@@ -0,0 +1,80 @@
+/**
+ * Store-backed {@link RunGateway} — the operator-side implementation. Wraps the local
+ * {@link WorkflowEngine} and forwards each read/control/stream verb to the engine's existing method,
+ * exactly the surface a `standalone` or `control-plane` deployment exposes. It holds NO state of its
+ * own beyond the injected engine and its declared role; all durability lives in the engine/store.
+ *
+ * Idiomatic AdonisJS: a plain class constructed with its dependency, wired by the package's provider /
+ * `defineConfig` (no framework DI decorators). A later `ProxyRunGateway` (Wave 2) will implement the
+ * SAME {@link RunGateway} interface over the transport for `tenant` deployments — nothing here needs
+ * to change for that.
+ */
+export class StoreRunGateway {
+    #engine;
+    #role;
+    constructor(engine, options = {}) {
+        this.#engine = engine;
+        this.#role = options.role ?? 'standalone';
+    }
+    topology() {
+        return { role: this.#role };
+    }
+    getRun(runId) {
+        return this.#engine.getRun(runId);
+    }
+    listRuns(query) {
+        return this.#engine.listRuns(query);
+    }
+    getCheckpoints(runId) {
+        return this.#engine.listCheckpoints(runId);
+    }
+    getRunChildren(runId) {
+        return this.#engine.getRunChildren(runId);
+    }
+    async getSearchAttributes(runId) {
+        const run = await this.#engine.getRun(runId);
+        return run?.searchAttributes;
+    }
+    workerHealth() {
+        return this.#engine.workerHealth();
+    }
+    async start(workflow, input, opts) {
+        const runId = opts?.runId ?? globalThis.crypto.randomUUID();
+        // `start` is overloaded per ref kind (class | string) on the engine; a `WorkflowRef` union fits
+        // neither overload, so resolve to the string overload (the engine handles both at runtime).
+        return this.#engine.start(workflow, input, runId, opts);
+    }
+    /**
+     * Deliver `signal` (by name) with `payload` to the addressed run. Confirmed against the engine's
+     * waiter convention (design §8): `engine.signal` is GENUINELY GLOBAL-BY-NAME — `ctx.waitForSignal(name)`
+     * registers a waiter under the caller-chosen `name` VERBATIM, and `engine.signal(name, payload)` matches
+     * by that exact string. There is NO `signal:<runId>:<name>` waiter convention: the run-scoped families
+     * (`task:<runId>:<name>`, `update:<runId>:<name>`, `wh:<runId>:<seq>`, `child:<id>`) are the FRAMEWORK
+     * composing the token before it hands it to `waitForSignal` — an external, user-named signal never is.
+     * Deriving a run-scoped token here would therefore reach NO waiter (a run parked on `waitForSignal('go')`
+     * would never see `signal('go')`), so the name is forwarded unchanged.
+     *
+     * `runId` is NOT dropped from the port on purpose: the `RunRequestResponder` uses it for the tenant
+     * ownership check (loads the run, rejects cross-tenant) BEFORE this delegates, and a `ProxyRunGateway`
+     * uses it to route to the run's owning control plane. So the signal stays name-addressed while the run
+     * boundary is still enforced one layer up.
+     */
+    signal(_runId, signal, payload) {
+        return this.#engine.signal(signal, payload);
+    }
+    cancel(runId, opts) {
+        return this.#engine.cancel(runId, opts);
+    }
+    redispatchPending(runId) {
+        // The AdonisJS engine doesn't yet expose per-step re-dispatch; degrade to null when absent so the
+        // verb stays byte-compatible for a proxy without inventing engine behaviour. See RunGatewayEngine.
+        return this.#engine.redispatchPending?.(runId) ?? Promise.resolve(null);
+    }
+    subscribe(runId, onEvent) {
+        return this.#engine.subscribe((event) => {
+            if (event.runId === runId)
+                onEvent(event);
+        });
+    }
+}
+//# sourceMappingURL=store-run-gateway.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-run-gateway.js","sourceRoot":"","sources":["../../../src/run-gateway/store-run-gateway.ts"],"names":[],"mappings":"AAuDA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IACjB,OAAO,CAAmB;IAC1B,KAAK,CAAiC;IAE/C,YAAY,MAAwB,EAAE,UAAkC,EAAE;QACxE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC;IAC5C,CAAC;IAED,QAAQ;QACN,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,cAAc,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,cAAc,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,KAAa;QACrC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO,GAAG,EAAE,gBAAgB,CAAC;IAC/B,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAAqB,EAAE,KAAc,EAAE,IAAsB;QACvE,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAC5D,gGAAgG;QAChG,4FAA4F;QAC5F,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,OAAiB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,IAA+B;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,iBAAiB,CAAC,KAAa;QAC7B,kGAAkG;QAClG,mGAAmG;QACnG,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,SAAS,CAAC,KAAa,EAAE,OAAqC;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/run-gateway/tenant-auth.d.ts

@@ -0,0 +1,19 @@
+import type { TenantVerifier } from '../config_types.js';
+/**
+ * Mint the signed token a tenant pod presents: `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``.
+ * Put it on the pod's `config/durable.ts` as `tenant.token`; the pod carries only the token (never the
+ * secret), and the control plane verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
+ */
+export declare function signTenantToken(tenant: string, secret: string): string;
+/**
+ * Build the control-plane-side {@link TenantVerifier} for {@link signTenantToken}-minted tokens under
+ * `secret`. It parses the token, recomputes the HMAC over the embedded tenant, and compares it in
+ * CONSTANT TIME (`timingSafeEqual`) — so a tampered tenant, a forged/absent signature, or a token
+ * signed with a different secret all return `null` (rejected). The verified tenant is DERIVED from the
+ * token's own claim, and the advisory `tenant` on the request body is ignored (spec §9).
+ *
+ * `capabilities`, if given, is a static grant stamped onto every {@link VerifiedTenant} this verifier
+ * authenticates (the HMAC token carries no scoped claims of its own); omit for none.
+ */
+export declare function hmacTenantVerifier(secret: string, capabilities?: string[]): TenantVerifier;
+//# sourceMappingURL=tenant-auth.d.ts.map

package/dist/src/run-gateway/tenant-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-auth.d.ts","sourceRoot":"","sources":["../../../src/run-gateway/tenant-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,oBAAoB,CAAC;AA8BzE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAY1F"}

package/dist/src/run-gateway/tenant-auth.js

@@ -0,0 +1,71 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Layered tenant auth (spec §9). On a store-less pod the `tenant` on a `RunRequest`/`StartRunMessage`
+ * is only a CLAIM; without a signed proof the isolation boundary is meaningless. This module provides
+ * the default defense-in-depth on top of prefix/network isolation: a symmetric HMAC token a tenant pod
+ * carries and presents in the `tenant` wire field, which the control-plane {@link TenantVerifier}
+ * checks and DERIVES the real tenant from — never trusting the body.
+ *
+ * The token is deliberately tiny and self-describing (`<tenant>.<base64url-hmac>`), so it fits the
+ * existing byte-compatible `tenant: string` wire field with NO envelope change: an aviary/Python
+ * control plane that doesn't verify simply treats the whole string as the tenant name (and finds no
+ * runs — a safe failure), while an Adonis control plane configured with {@link hmacTenantVerifier}
+ * verifies the signature and scopes to the embedded tenant.
+ *
+ * HMAC (shared secret) is the zero-infra default; a deployment that prefers asymmetric / issued tokens
+ * supplies its own {@link TenantVerifier} in `config/durable.ts` instead. Prefix/network segmentation
+ * is a deployment concern (Redis ACLs, per-tenant prefixes) and lives outside this code.
+ */
+/** Separator between the tenant claim and its signature in a token. `.` is URL/JSON-safe and never
+ *  appears in the base64url signature, so the LAST `.` unambiguously splits the two halves — a tenant
+ *  name may itself contain dots. */
+const TOKEN_SEP = '.';
+/** The HMAC digest, byte-for-byte, that authenticates `tenant` under `secret`. */
+function sign(tenant, secret) {
+    return createHmac('sha256', secret).update(tenant).digest('base64url');
+}
+/**
+ * Mint the signed token a tenant pod presents: `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``.
+ * Put it on the pod's `config/durable.ts` as `tenant.token`; the pod carries only the token (never the
+ * secret), and the control plane verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
+ */
+export function signTenantToken(tenant, secret) {
+    return `${tenant}${TOKEN_SEP}${sign(tenant, secret)}`;
+}
+/**
+ * Build the control-plane-side {@link TenantVerifier} for {@link signTenantToken}-minted tokens under
+ * `secret`. It parses the token, recomputes the HMAC over the embedded tenant, and compares it in
+ * CONSTANT TIME (`timingSafeEqual`) — so a tampered tenant, a forged/absent signature, or a token
+ * signed with a different secret all return `null` (rejected). The verified tenant is DERIVED from the
+ * token's own claim, and the advisory `tenant` on the request body is ignored (spec §9).
+ *
+ * `capabilities`, if given, is a static grant stamped onto every {@link VerifiedTenant} this verifier
+ * authenticates (the HMAC token carries no scoped claims of its own); omit for none.
+ */
+export function hmacTenantVerifier(secret, capabilities) {
+    return ({ token }) => {
+        // The signed token travels in the request's `tenant` field, so the responder passes it as `token`.
+        if (typeof token !== 'string' || token.length === 0)
+            return null;
+        const sep = token.lastIndexOf(TOKEN_SEP);
+        if (sep <= 0 || sep === token.length - 1)
+            return null; // no claim or no signature half
+        const tenant = token.slice(0, sep);
+        const presented = token.slice(sep + 1);
+        const expected = sign(tenant, secret);
+        if (!constantTimeEquals(presented, expected))
+            return null;
+        return capabilities !== undefined ? { tenant, capabilities } : { tenant };
+    };
+}
+/** Constant-time string compare that never throws on a length mismatch (`timingSafeEqual` requires
+ *  equal-length buffers) and never short-circuits on the first differing byte — so a rejected token
+ *  leaks nothing about how much of the signature matched. */
+function constantTimeEquals(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+//# sourceMappingURL=tenant-auth.js.map

package/dist/src/run-gateway/tenant-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-auth.js","sourceRoot":"","sources":["../../../src/run-gateway/tenant-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;;;;;;;;;GAgBG;AAEH;;oCAEoC;AACpC,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB,kFAAkF;AAClF,SAAS,IAAI,CAAC,MAAc,EAAE,MAAc;IAC1C,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAc;IAC5D,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,YAAuB;IACxE,OAAO,CAAC,EAAE,KAAK,EAAE,EAAyB,EAAE;QAC1C,mGAAmG;QACnG,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjE,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,gCAAgC;QACvF,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,OAAO,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5E,CAAC,CAAC;AACJ,CAAC;AAED;;6DAE6D;AAC7D,SAAS,kBAAkB,CAAC,CAAS,EAAE,CAAS;IAC9C,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/src/services/main.d.ts

@@ -1,13 +1,26 @@
 import { WorkflowEngine } from '../engine.js';
+import type { RunGateway } from '../run-gateway/interface.js';
 /**
- * Returns the singleton {@link WorkflowEngine} resolved from the container.
+ * The ACTIVE role's {@link RunGateway} — the store-less-cluster read/control/start surface (design §8).
+ * On `standalone`/`control-plane` it is the store-backed `StoreRunGateway`; on `tenant` it is the
+ * `ProxyRunGateway` that round-trips over the wire. App/dashboard/CLI code reads the SAME object either
+ * way, so store presence is invisible above this line:
  *
- * Import it directly instead of resolving the engine yourself:
+ * ```ts
+ * import { runGateway } from '@adonis-agora/durable/services/main'
+ * const run = await runGateway.getRun(runId)
+ * ```
+ */
+declare let runGateway: RunGateway;
+/**
+ * The singleton {@link WorkflowEngine} — bound ONLY on the store roles (`standalone`/`control-plane`).
+ * A `tenant` pod owns no engine (structural isolation), so this stays `undefined` there; use
+ * {@link runGateway} for role-agnostic access.
  *
  * ```ts
  * import engine from '@adonis-agora/durable/services/main'
  * ```
  */
 declare let engine: WorkflowEngine;
-export { engine as default };
+export { engine as default, runGateway };
 //# sourceMappingURL=main.d.ts.map

package/dist/src/services/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;GAQG;AACH,QAAA,IAAI,MAAM,EAAE,cAAc,CAAC;AAM3B,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,QAAA,IAAI,UAAU,EAAE,UAAU,CAAC;AAE3B;;;;;;;;GAQG;AACH,QAAA,IAAI,MAAM,EAAE,cAAc,CAAC;AAY3B,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/src/services/main.js

@@ -1,9 +1,22 @@
 import app from '@adonisjs/core/services/app';
 import { WorkflowEngine } from '../engine.js';
+import { DURABLE_RUN_GATEWAY } from '../role_bindings.js';
 /**
- * Returns the singleton {@link WorkflowEngine} resolved from the container.
+ * The ACTIVE role's {@link RunGateway} — the store-less-cluster read/control/start surface (design §8).
+ * On `standalone`/`control-plane` it is the store-backed `StoreRunGateway`; on `tenant` it is the
+ * `ProxyRunGateway` that round-trips over the wire. App/dashboard/CLI code reads the SAME object either
+ * way, so store presence is invisible above this line:
  *
- * Import it directly instead of resolving the engine yourself:
+ * ```ts
+ * import { runGateway } from '@adonis-agora/durable/services/main'
+ * const run = await runGateway.getRun(runId)
+ * ```
+ */
+let runGateway;
+/**
+ * The singleton {@link WorkflowEngine} — bound ONLY on the store roles (`standalone`/`control-plane`).
+ * A `tenant` pod owns no engine (structural isolation), so this stays `undefined` there; use
+ * {@link runGateway} for role-agnostic access.
  *
  * ```ts
  * import engine from '@adonis-agora/durable/services/main'
@@ -11,7 +24,13 @@ import { WorkflowEngine } from '../engine.js';
  */
 let engine;
 await app.booted(async () => {
-    engine = await app.container.make(WorkflowEngine);
+    const config = app.config.get('durable', {});
+    const role = config.role ?? 'standalone';
+    runGateway = await app.container.make(DURABLE_RUN_GATEWAY);
+    // Expose the engine only for store roles — a tenant pod has no engine binding to resolve.
+    if (role !== 'tenant') {
+        engine = await app.container.make(WorkflowEngine);
+    }
 });
-export { engine as default };
+export { engine as default, runGateway };
 //# sourceMappingURL=main.js.map

package/dist/src/services/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,6BAA6B,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;GAQG;AACH,IAAI,MAAsB,CAAC;AAE3B,MAAM,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC1B,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AACpD,CAAC,CAAC,CAAC;AAEH,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,6BAA6B,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;;;;;GAUG;AACH,IAAI,UAAsB,CAAC;AAE3B;;;;;;;;GAQG;AACH,IAAI,MAAsB,CAAC;AAE3B,MAAM,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAgB,SAAS,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,YAAY,CAAC;IACzC,UAAU,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC3D,0FAA0F;IAC1F,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/src/step-name-symbol.d.ts

@@ -40,6 +40,9 @@ export 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 (design §7.5). Dispatch parks the run
+     *  `blocked` when no live capable+protocol-compatible worker exists. Absent/empty = runs anywhere. */
+    requires?: string[] | undefined;
 }
 /**
  * A method carrying its `@Step`-stamped routing name (and, optionally, its dispatch policy).

package/dist/src/step-name-symbol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-name-symbol.d.ts","sourceRoot":"","sources":["../../src/step-name-symbol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAiD,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+FAA+F;IAC/F,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B;;iDAE6C;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAAC,CAC1D,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG;IACjC,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,CAAC,mBAAmB,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF;;uEAEuE;AACvE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI3D;AAED;;0EAE0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAIjE"}
+{"version":3,"file":"step-name-symbol.d.ts","sourceRoot":"","sources":["../../src/step-name-symbol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAiD,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+FAA+F;IAC/F,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B;;iDAE6C;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;0GACsG;IACtG,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACjC;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAAC,CAC1D,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG;IACjC,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,CAAC,mBAAmB,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF;;uEAEuE;AACvE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI3D;AAED;;0EAE0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAIjE"}