@adonis-agora/durable 0.49.1 → 0.51.0

package/dist/src/transports/queue-remote.js

@@ -0,0 +1,398 @@
+import { cachedLiveKeys, NO_WORKER_KEYS } from './worker-keys.js';
+/**
+ * Naming and bookkeeping for the parts of the store-less (P4) protocol that BullMQ carries on Redis
+ * PUB/SUB and that a point-to-point `@adonisjs/queue` adapter cannot broadcast: run replies and tenant
+ * events. {@link import('./queue.js').QueueTransport} delivers both through per-instance INBOX queues:
+ *
+ * - **Run replies** — every requesting instance consumes its own `${P}:run-replies:<instance>`. The
+ *   requester stamps its instance id (`replyTo`) on the run-request / start-run job it pushes; the
+ *   control-plane instance that pops the job remembers `correlationId → replyTo` while the handler runs,
+ *   so the responder's `publishRunReply` lands on exactly the requester's inbox. Nothing is broadcast.
+ * - **Tenant events** — every instance subscribed to a tenant sends an {@link InboxRegistration} onto
+ *   `${P}:inbox-registrations` when it subscribes and every third of the TTL after that. Whichever
+ *   control-plane instance pops it records a TTL'd `${P}-tenant-subscriber:<tenant>:<instance>` key in
+ *   the CONTROL PLANE's {@link WorkerKeyStore} (the one its worker descriptors live in, shared by its
+ *   replicas). A publisher reads the live subscribers of the event's tenant from that store and pushes
+ *   one copy onto each one's `${P}:tenant-events:<instance>` inbox. The subscriber itself needs no store,
+ *   which is what lets a store-less tenant pod live-tail.
+ *
+ * The same registration keeps a TTL'd `${P}-inbox:<instance>` liveness key for every instance that
+ * consumes an inbox, which the publisher-side janitor uses to drain the inbox of an instance that died
+ * (see {@link InboxRegistry}).
+ *
+ * A worker with no key store of its own (a store-less tenant pod) advertises its descriptor and
+ * heartbeat keys the same way: as {@link KeyAdvertisement}s the control plane records — restricted to
+ * the `-worker-descriptor:` / `-worker-heartbeat:` keyspace — so the control plane still sees it.
+ *
+ * Segments taken from the wire or from user config (tenant, instance id) are URI-encoded inside KEYS, so
+ * neither can contain the `:` separator and one tenant's key prefix can never match another's.
+ */
+/** Default TTL (ms) of the subscriber and inbox liveness keys; re-announced every third of it. */
+export const DEFAULT_INBOX_TTL_MS = 30_000;
+/** Default reuse window (ms) of the publisher's read of the live tenant subscribers. Short on purpose:
+ *  a subscriber that just registered misses the events published inside this window. */
+export const DEFAULT_TENANT_SUBSCRIBERS_CACHE_MS = 1_000;
+/** Default cadence (ms) of the janitor that drains the inboxes of dead instances. */
+export const DEFAULT_INBOX_SWEEP_INTERVAL_MS = 30_000;
+/** How many jobs one janitor round pops from one dead inbox (the next round continues). */
+const DRAIN_PER_SWEEP = 1_000;
+/** Bounds on what a registration read off the wire may ask for. */
+const MAX_REGISTRATION_TTL_MS = 10 * 60_000;
+const MAX_REGISTRATION_TENANTS = 1_000;
+const enc = (segment) => encodeURIComponent(segment);
+/** `${P}:run-replies:<instance>` — the inbox a requesting instance consumes its {@link RunReply}s from. */
+export function runRepliesQueue(prefix, instanceId) {
+    return `${prefix}:run-replies:${instanceId}`;
+}
+/** `${P}:tenant-events:<instance>` — the inbox a subscribing instance consumes its tenant events from. */
+export function tenantEventsQueue(prefix, instanceId) {
+    return `${prefix}:tenant-events:${instanceId}`;
+}
+/** `${P}:inbox-registrations` — where instances announce their inboxes and subscriptions. */
+export function inboxRegistrationsQueue(prefix) {
+    return `${prefix}:inbox-registrations`;
+}
+/** The key prefix of every live subscriber of `tenant`. */
+export function tenantSubscriberKeyPrefix(prefix, tenant) {
+    return `${prefix}-tenant-subscriber:${enc(tenant)}:`;
+}
+/** `${P}-tenant-subscriber:<tenant>:<instance>` — "this instance wants `tenant`'s events". */
+export function tenantSubscriberKey(prefix, tenant, instanceId) {
+    return `${tenantSubscriberKeyPrefix(prefix, tenant)}${enc(instanceId)}`;
+}
+/** `${P}-inbox:<instance>` — "this instance is alive and consuming its inboxes". */
+export function inboxKey(prefix, instanceId) {
+    return `${prefix}-inbox:${enc(instanceId)}`;
+}
+function ownerOf(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed.instanceId === 'string' ? parsed.instanceId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const isStringArray = (v) => Array.isArray(v) && v.length <= MAX_REGISTRATION_TENANTS && v.every((t) => typeof t === 'string');
+/** Narrow a key advertisement read off the wire; anything malformed is `undefined` (ignored). */
+export function parseAdvertisement(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const r = raw;
+    if (r.kind !== 'advertise' || !Array.isArray(r.put) || !isStringArray(r.remove))
+        return undefined;
+    if (r.put.length > MAX_REGISTRATION_TENANTS)
+        return undefined;
+    const put = [];
+    for (const entry of r.put) {
+        const e = entry;
+        if (!e ||
+            typeof e.key !== 'string' ||
+            typeof e.value !== 'string' ||
+            typeof e.ttlMs !== 'number' ||
+            !Number.isFinite(e.ttlMs) ||
+            e.ttlMs <= 0) {
+            return undefined;
+        }
+        put.push({ key: e.key, value: e.value, ttlMs: Math.min(e.ttlMs, MAX_REGISTRATION_TTL_MS) });
+    }
+    return { kind: 'advertise', put, remove: r.remove };
+}
+/** Narrow a registration read off the wire; anything malformed is `undefined` (ignored). */
+export function parseRegistration(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const r = raw;
+    if (typeof r.instanceId !== 'string' || r.instanceId === '')
+        return undefined;
+    if (typeof r.ttlMs !== 'number' || !Number.isFinite(r.ttlMs) || r.ttlMs <= 0)
+        return undefined;
+    if (typeof r.inbox !== 'boolean' || !isStringArray(r.tenants))
+        return undefined;
+    if (r.withdraw !== undefined && !isStringArray(r.withdraw))
+        return undefined;
+    return {
+        instanceId: r.instanceId,
+        ttlMs: Math.min(r.ttlMs, MAX_REGISTRATION_TTL_MS),
+        inbox: r.inbox,
+        tenants: r.tenants,
+        withdraw: r.withdraw,
+    };
+}
+/**
+ * The registry side of the inbox design, in three parts:
+ *
+ * - **subscriber** — what this instance announces (its subscriptions and its inbox liveness), re-sent
+ *   every third of the TTL while it lasts;
+ * - **recorder** (control plane) — turns announcements into TTL'd keys in its worker-key store;
+ * - **publisher** (control plane) — reads a tenant's live subscribers, and runs the janitor that drains
+ *   inboxes it pushed to whose owner stopped announcing itself.
+ *
+ * Dead instances: a subscriber that dies stops announcing, so within the TTL its keys expire and
+ * publishers stop pushing to it — its inbox stops growing. What was pushed meanwhile is drained by the
+ * janitor of each publisher that pushed it (tracked in memory): once the owner's `-inbox:` key is gone
+ * and the last push is older than the TTL, the publisher pops and completes what is left. A publisher
+ * that restarts forgets what it tracked, so a crash of BOTH sides can leave at most a TTL's worth of
+ * jobs behind.
+ *
+ * Without a real key store on the control plane ({@link NO_WORKER_KEYS}) nothing can be recorded or
+ * read: tenant events reach no one, and the janitor stays off (it could not tell a live inbox from a
+ * dead one).
+ */
+export class InboxRegistry {
+    #options;
+    #now;
+    #enabled;
+    #subscribers;
+    /** Tenants this instance currently subscribes to. */
+    #tenants = new Set();
+    /** Whether this instance consumes an inbox (so it keeps announcing its liveness). */
+    #inboxActive = false;
+    #refreshTimer;
+    /** Inboxes this instance pushed to: queue → its owner and the time of the last push. */
+    #pushed = new Map();
+    #sweepTimer;
+    #sweeping;
+    #warned = false;
+    #warnedAdvertisement = false;
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? Date.now;
+        this.#enabled = options.store !== NO_WORKER_KEYS;
+        this.#subscribers = cachedLiveKeys(options.store, options.subscribersCacheMs, this.#now);
+    }
+    // ---------------------------------------------------------------------------
+    // subscriber
+    // ---------------------------------------------------------------------------
+    #announce(withdraw) {
+        void this.#options
+            .announce({
+            instanceId: this.#options.instanceId,
+            ttlMs: this.#options.ttlMs,
+            inbox: this.#inboxActive,
+            tenants: [...this.#tenants],
+            ...(withdraw ? { withdraw } : {}),
+        })
+            .catch((err) => this.#options.onError(err));
+    }
+    /** Mark this instance as an inbox consumer (announced now and on every refresh). */
+    activateInbox() {
+        if (this.#inboxActive)
+            return;
+        this.#inboxActive = true;
+        this.#announce();
+        this.#ensureRefresh();
+    }
+    /** Subscribe to `tenant`'s events (idempotent). */
+    subscribe(tenant) {
+        if (this.#tenants.has(tenant))
+            return;
+        this.#tenants.add(tenant);
+        this.#inboxActive = true;
+        this.#announce();
+        this.#ensureRefresh();
+    }
+    /** End the subscription to `tenant` (its last handler went away). */
+    unsubscribe(tenant) {
+        if (!this.#tenants.delete(tenant))
+            return;
+        this.#announce([tenant]);
+    }
+    #ensureRefresh() {
+        if (this.#refreshTimer)
+            return;
+        this.#refreshTimer = setInterval(() => this.#announce(), Math.max(Math.floor(this.#options.ttlMs / 3), 1));
+        this.#refreshTimer.unref?.();
+    }
+    /**
+     * A {@link DescriptorRedis} that forwards a worker's descriptor / heartbeat writes to the control
+     * plane instead of a local store. Writes made in the same tick go out as ONE message (a worker beats
+     * every token at once). A failed send is reported, never thrown into the worker's heartbeat.
+     */
+    remoteKeyWriter() {
+        let batch;
+        const enqueue = (mutate) => {
+            if (!batch) {
+                const pending = { kind: 'advertise', put: [], remove: [] };
+                batch = pending;
+                mutate(pending);
+                return Promise.resolve().then(() => {
+                    batch = undefined;
+                    return this.#options.announce(pending).catch((err) => this.#options.onError(err));
+                });
+            }
+            mutate(batch);
+            return Promise.resolve();
+        };
+        return {
+            set: (key, value, _mode, ttlSeconds) => enqueue((b) => b.put.push({ key, value, ttlMs: ttlSeconds * 1000 })),
+            del: (...keys) => enqueue((b) => b.remove.push(...keys)),
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // recorder (control plane)
+    // ---------------------------------------------------------------------------
+    /** Record a message read off `${P}:inbox-registrations` as TTL'd keys in the store. */
+    async record(raw) {
+        const advertisement = parseAdvertisement(raw);
+        if (advertisement)
+            return this.#recordAdvertisement(advertisement);
+        const registration = parseRegistration(raw);
+        if (!registration)
+            return; // malformed: nothing safe to record
+        if (!this.#enabled) {
+            if (!this.#warned) {
+                this.#warned = true;
+                this.#options.onError(new Error('[QueueTransport] received a tenant-event subscription but has no worker-key store to ' +
+                    'record it in (transports.queue() defaults to the app database); tenant events cannot ' +
+                    'reach any subscriber.'));
+            }
+            return;
+        }
+        const prefix = this.#options.prefix();
+        const { instanceId, ttlMs } = registration;
+        const value = JSON.stringify({ instanceId });
+        const expiresAt = this.#now() + ttlMs;
+        const removed = (registration.withdraw ?? []).map((t) => tenantSubscriberKey(prefix, t, instanceId));
+        if (!registration.inbox)
+            removed.push(inboxKey(prefix, instanceId));
+        if (removed.length > 0)
+            await this.#options.store.remove(removed);
+        if (registration.inbox)
+            await this.#options.store.put(inboxKey(prefix, instanceId), value, expiresAt);
+        for (const tenant of registration.tenants) {
+            await this.#options.store.put(tenantSubscriberKey(prefix, tenant, instanceId), value, expiresAt);
+        }
+    }
+    /** Record a forwarded worker advertisement — only keys of the worker advertisement keyspace. */
+    async #recordAdvertisement(ad) {
+        if (!this.#enabled) {
+            if (!this.#warnedAdvertisement) {
+                this.#warnedAdvertisement = true;
+                this.#options.onError(new Error('[QueueTransport] received a forwarded worker advertisement but has no worker-key store ' +
+                    'to record it in (transports.queue() defaults to the app database); the store-less ' +
+                    "pod's workers will not appear in groupHealth, the dashboard or handshake negotiation."));
+            }
+            return;
+        }
+        const prefix = this.#options.prefix();
+        const allowed = (key) => key.startsWith(`${prefix}-worker-descriptor:`) ||
+            key.startsWith(`${prefix}-worker-heartbeat:`);
+        const removed = ad.remove.filter(allowed);
+        if (removed.length > 0)
+            await this.#options.store.remove(removed);
+        const now = this.#now();
+        for (const { key, value, ttlMs } of ad.put) {
+            if (allowed(key))
+                await this.#options.store.put(key, value, now + ttlMs);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // publisher (control plane)
+    // ---------------------------------------------------------------------------
+    /** The instance ids with a live subscription to `tenant` (deduplicated; malformed values skipped). */
+    async subscribersOf(tenant) {
+        if (!this.#enabled)
+            return [];
+        const marker = tenantSubscriberKeyPrefix(this.#options.prefix(), tenant);
+        const owners = new Set();
+        for (const { key, value } of await this.#subscribers()) {
+            if (!key.startsWith(marker))
+                continue;
+            const owner = ownerOf(value);
+            if (owner !== undefined)
+                owners.add(owner);
+        }
+        return [...owners];
+    }
+    /** Record a push onto `owner`'s inbox `queue`, so the janitor can drain it if `owner` dies. */
+    notePush(queue, owner) {
+        if (!this.#enabled || this.#options.sweepIntervalMs <= 0)
+            return;
+        this.#pushed.set(queue, { owner, lastPushAt: this.#now() });
+        if (this.#sweepTimer)
+            return;
+        this.#sweepTimer = setInterval(() => {
+            if (this.#sweeping)
+                return;
+            const round = this.sweep().finally(() => {
+                if (this.#sweeping === round)
+                    this.#sweeping = undefined;
+            });
+            this.#sweeping = round;
+        }, this.#options.sweepIntervalMs);
+        this.#sweepTimer.unref?.();
+    }
+    /**
+     * One janitor round: for every inbox pushed to more than a TTL ago, drain it when its owner no longer
+     * has a live `-inbox:` key, or stop tracking it when the owner is alive (it consumed it). Reads the
+     * store fresh — never the publisher cache — so a decision to drain is never stale.
+     */
+    async sweep() {
+        if (this.#pushed.size === 0)
+            return;
+        const now = this.#now();
+        let live;
+        try {
+            live = await this.#options.store.live(now);
+        }
+        catch (err) {
+            this.#options.onError(err);
+            return;
+        }
+        const inboxPrefix = inboxKey(this.#options.prefix(), '');
+        const alive = new Set();
+        for (const { key, value } of live) {
+            if (!key.startsWith(inboxPrefix))
+                continue;
+            const owner = ownerOf(value);
+            if (owner !== undefined)
+                alive.add(owner);
+        }
+        for (const [queue, { owner, lastPushAt }] of [...this.#pushed]) {
+            if (now - lastPushAt < this.#options.ttlMs)
+                continue;
+            if (alive.has(owner)) {
+                this.#pushed.delete(queue);
+                continue;
+            }
+            try {
+                const emptied = await this.#options.drain(queue, DRAIN_PER_SWEEP);
+                // A push that raced the drain re-armed the entry with a newer time: keep tracking it then.
+                if (emptied && this.#pushed.get(queue)?.lastPushAt === lastPushAt)
+                    this.#pushed.delete(queue);
+            }
+            catch (err) {
+                this.#options.onError(err);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // shutdown
+    // ---------------------------------------------------------------------------
+    /** Stop the timers and withdraw what this instance announced (best-effort, one last announcement). */
+    async close() {
+        if (this.#refreshTimer)
+            clearInterval(this.#refreshTimer);
+        this.#refreshTimer = undefined;
+        if (this.#sweepTimer)
+            clearInterval(this.#sweepTimer);
+        this.#sweepTimer = undefined;
+        await this.#sweeping;
+        if (!this.#inboxActive && this.#tenants.size === 0)
+            return;
+        const withdraw = [...this.#tenants];
+        this.#tenants.clear();
+        this.#inboxActive = false;
+        await this.#options
+            .announce({
+            instanceId: this.#options.instanceId,
+            ttlMs: this.#options.ttlMs,
+            inbox: false,
+            tenants: [],
+            withdraw,
+        })
+            .catch((err) => this.#options.onError(err));
+    }
+}
+//# sourceMappingURL=queue-remote.js.map

package/dist/src/transports/queue-remote.js.map

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

package/dist/src/transports/queue.d.ts

@@ -1,8 +1,10 @@
 import type { AcquiredJob, AdapterFactory } from '@adonisjs/queue/types';
 import type { WorkerDescriptor } from '../handshake/descriptor.js';
-import { type ControlMessage, type ControlPlane, type Heartbeat, type RemoteTask, type StepResult, type Transport } from '../interfaces.js';
+import { type ControlMessage, type ControlPlane, type GroupHealth, type Heartbeat, type RemoteTask, type RunReply, type RunRequest, type StartRunMessage, type StepResult, type TenantEvent, type Transport, type WorkflowDecision, type WorkflowStepEvent, type WorkflowTask } from '../interfaces.js';
 import { type StepHandler } from '../protocol.js';
 import type { DescriptorRedis } from '../worker-runtime/registry.js';
+import { type WorkflowTurnHandler } from '../workflow-turn.js';
+import { type ConcurrencyOption } from './adaptive-concurrency.js';
 import { type WorkerKeyStore } from './worker-keys.js';
 /**
  * The wire payloads carried as a queue job's `payload`. Everything that crosses the queue is plain
@@ -19,6 +21,15 @@ export type TaskPayload = RemoteTask;
 export type ResultPayload = StepResult;
 export type HeartbeatPayload = Heartbeat;
 export type ControlPayload = ControlMessage;
+/** A run-request / start-run as it crosses the queue: the DTO plus the requester's instance id, so the
+ *  control plane can route the reply to that requester's inbox (see `queue-remote.ts`). Private to this
+ *  transport's wire — the shared {@link RunRequest} / {@link StartRunMessage} DTOs are unchanged. */
+export type RunRequestPayload = RunRequest & {
+    replyTo?: string;
+};
+export type StartRunPayload = StartRunMessage & {
+    replyTo?: string;
+};
 /**
  * The lease a `@boringnode/queue` >= 0.8 adapter (`@adonisjs/queue` 0.7) hands out with every claim:
  * `completeJob` / `retryJob` / `failJob` take `{ id, leaseToken }` instead of a bare job id, so only the
@@ -77,6 +88,30 @@ export interface QueueTransportOptions {
     namespace?: string;
     /** Poll interval (ms) for the result/task/heartbeat/control loops. Default 200ms. */
     pollIntervalMs?: number;
+    /**
+     * How many jobs of ONE step name this worker runs at once. Default 1 (one at a time, the historical
+     * behavior). Each handler name's task loop keeps up to this many jobs in flight from a single poll
+     * loop — more slots do not add polling — and every in-flight claim is renewed and drained on
+     * `close()` like a single one.
+     *
+     * `'adaptive'`, or `{ mode: 'adaptive', min, max, start, tickMs, ramCeilingPct, cpuCeilingPct }`,
+     * lets the same {@link AdaptiveController} the BullMQ transport uses move the limit at runtime (from
+     * step latency, errors/stalls, RSS and optionally CPU); every task loop reads the live limit on each
+     * tick. Either way the limit, in-flight count, RSS, CPU, throughput and p95 ride this worker's
+     * liveness heartbeat (see {@link QueueTransport.groupHealth}).
+     */
+    concurrency?: ConcurrencyOption;
+    /** How many step results the engine side settles at once. Default 1. */
+    resultConcurrency?: number;
+    /**
+     * Idle backoff for the task, heartbeat and control loops, as a multiple of {@link pollIntervalMs}:
+     * after consecutive empty polls the sleep doubles up to `idleBackoffMax × pollIntervalMs`, and any
+     * poll that finds a job resets it. Default 4 (an idle loop polls every 800ms instead of 200ms),
+     * which bounds the backend load of an idle worker serving many step names at the cost of up to that
+     * much pickup latency for the first job after a quiet spell. `1` disables it. The results loop never
+     * backs off: a result is on the critical path of every step.
+     */
+    idleBackoffMax?: number;
     /**
      * How often (ms) the stalled-job reclaim sweep runs. Reclaim is ON by default (default 30s); set to
      * `0` to disable it entirely. This is a coarse background check, NOT run on every poll tick — see
@@ -85,10 +120,16 @@ export interface QueueTransportOptions {
     stalledCheckIntervalMs?: number;
     /**
      * How old (ms) a claim must be before the reclaim sweep presumes its worker dead and re-delivers the
-     * job. Default 30min — intentionally generous, because the claim's `acquiredAt` is never renewed
-     * while the worker processes: a legitimately long step holds one claim for its entire duration, and
-     * re-delivery double-runs a step whose worker is merely slow. Raise it above your longest step. Only used when the adapter implements
-     * `recoverStalledJobs` and the sweep is enabled.
+     * job. Only used when the adapter implements `recoverStalledJobs` and the sweep is enabled.
+     *
+     * - On an adapter that renews claims (`adapter.renewJobs` — every `@adonisjs/queue` 0.6/0.7 driver):
+     *   default 2min. This transport renews every in-flight claim each half threshold, so the threshold
+     *   bounds how long a worker may go SILENT (crashed, or its event loop blocked), not how long a step
+     *   may run.
+     * - On an adapter that cannot (a custom one without `renewJobs`): default 30min — intentionally
+     *   generous, because the claim is never renewed and a legitimately long step holds it for its entire
+     *   duration; re-delivery double-runs a step whose worker is merely slow. Raise it above your longest
+     *   step.
      */
     stalledThresholdMs?: number;
     /**
@@ -112,8 +153,36 @@ export interface QueueTransportOptions {
      * advertised, and the engine routes without descriptors.
      */
     workerKeys?: WorkerKeyStore;
+    /**
+     * How long `close()` waits (ms) for jobs already in a handler before handing the rest back to the
+     * broker. Default 5000 — the same option, and default, as the `bullmq` and `db` transports.
+     */
+    closeTimeoutMs?: number;
     /** How long a read of {@link workerKeys} is reused (ms). Default 5000; `0` reads every time. */
     workerKeysCacheMs?: number;
+    /**
+     * How often (ms) a worker refreshes the liveness key of each step name it serves. Default 10000;
+     * each key lives at least 35s (three intervals when longer), so a worker that dies drops out of
+     * {@link QueueTransport.groupHealth} within that.
+     */
+    workerHeartbeatIntervalMs?: number;
+    /**
+     * TTL (ms) of what an instance announces to the control plane for the store-less protocol: each
+     * tenant it subscribes to (`onTenantEvent`) and that its inboxes are being consumed. The control plane
+     * records both as keys in its {@link workerKeys} store; the instance re-announces every third of the
+     * TTL. A subscriber that dies stops receiving pushes within about this long. Default 30000.
+     */
+    inboxTtlMs?: number;
+    /**
+     * How long a publisher reuses its read of a tenant's live subscribers (ms). A subscription made
+     * within this window of an event may miss it. Default 1000; `0` reads the store on every event.
+     */
+    tenantSubscribersCacheMs?: number;
+    /**
+     * How often (ms) a publisher drains the inboxes it pushed run replies / tenant events to whose owner
+     * no longer advertises itself (a dead tenant pod). Default 30000; `0` disables the janitor.
+     */
+    inboxSweepIntervalMs?: number;
 }
 /**
  * A `@adonisjs/queue`-backed {@link Transport}. Remote steps are dispatched to a per-group task
@@ -127,6 +196,12 @@ export interface QueueTransportOptions {
  * is single-consumer (point-to-point), so it is correct for a single engine instance but does NOT
  * fan out to every pod the way a real pub/sub does.
  *
+ * It also carries remote workflow turns (`dispatchWorkflowTask` / `handleWorkflow` / `onDecision`,
+ * streamed step events) and the store-less tenant-pod protocol (start-run, run-request, run replies,
+ * tenant events), so a `tenant` pod can reach a `control-plane` over `@adonisjs/queue` alone. Run
+ * replies and tenant events, which BullMQ broadcasts on Redis PUB/SUB, ride per-instance inbox queues
+ * here — see `queue-remote.ts`.
+ *
  * Run one instance engine-side (`onResult` + `dispatch`) and one per worker process (`handle()`).
  * The wire payloads are the documented `RemoteTask`/`StepResult` JSON, so non-Node workers on the
  * same queues interoperate.
@@ -136,9 +211,30 @@ export interface QueueTransportOptions {
  */
 export declare class QueueTransport implements Transport, ControlPlane {
     #private;
+    /**
+     * Per-group worker health, for `engine.workerHealth()` and the dashboard/Telescope worker panels.
+     * Present only when a {@link QueueTransportOptions.workerKeys} store is configured (the
+     * `transports.queue()` default) — without one no worker can advertise liveness, and reporting
+     * "backlog, zero workers" for every group would be a false alarm.
+     *
+     * - `depth` is the task queue's PENDING count (`adapter.sizeOf`), the jobs waiting for a worker.
+     *   Unlike BullMQ's waiting+active+delayed+prioritized it leaves out jobs in flight and delayed
+     *   retries: the `@adonisjs/queue` adapter contract has no count for those. Priorities are included
+     *   (they are pending jobs). An adapter without `sizeOf` reports `0`.
+     * - `liveWorkers` are the unexpired `${P}-worker-heartbeat:<group>:<instance>` keys, each with the
+     *   worker's {@link WorkerStatus} when it carries one (this transport's own beats do).
+     */
+    readonly groupHealth?: (group: string) => Promise<GroupHealth>;
     constructor(options: QueueTransportOptions);
-    /** The writer a worker runtime's registry advertises its descriptor and heartbeat through. */
+    /** The writer a worker runtime's registry advertises its descriptor and heartbeat through: the key
+     *  store when this instance has one. A store-less tenant pod (see {@link useTenantRole}) with no key
+     *  store forwards it to the control plane instead, which records it in its own — so the control plane
+     *  still sees the pod's workers. Otherwise, with no store, nothing is advertised. */
     createDescriptorRedis(): DescriptorRedis;
+    /** Declare that this transport backs a store-less `tenant` pod (the provider calls it): worker
+     *  advertisement is then forwarded to the control plane when this instance has no key store. Only a
+     *  tenant pod is guaranteed a control plane that records the forwarded keys. */
+    useTenantRole(): void;
     /** The live worker descriptors advertised on `token`. */
     listWorkerDescriptors(token: string): Promise<WorkerDescriptor[]>;
     /** The routing tokens a live worker beats on. */
@@ -181,12 +277,69 @@ export declare class QueueTransport implements Transport, ControlPlane {
      * dispatches by (see `engine.callRemote`). Re-registering a name just swaps the handler fn.
      */
     handle(name: string, fn: StepHandler): void;
+    /**
+     * Register a WORKFLOW turn consumer (worker side). Shares the step task loop of the workflow name's
+     * routing token — the same queue {@link dispatchWorkflowTask} targets — and tells the two job kinds
+     * apart BY SHAPE: a `workflow`-shaped job runs `turn(task)` and its {@link WorkflowDecision} is pushed
+     * onto `${P}:decisions`. Re-registering swaps the turn fn.
+     */
+    handleWorkflow(name: string, turn: WorkflowTurnHandler): void;
     /** Worker side: publish a liveness heartbeat for an in-flight long step. */
     heartbeat(beat: Heartbeat): Promise<void>;
     onResult(handler: (result: StepResult) => Promise<void>): void;
     onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
     publishControl(msg: ControlMessage): Promise<void>;
     onControl(handler: (msg: ControlMessage) => void): void;
+    /** engine → workflow worker: a {@link WorkflowTask} on the workflow's routing-token task queue (job
+     *  `workflow`), the queue a {@link handleWorkflow} consumer polls. */
+    dispatchWorkflowTask(task: WorkflowTask): Promise<void>;
+    /**
+     * engine ← workflow worker: consume {@link WorkflowDecision}s from `${P}:decisions`. ONE loop per
+     * transport; every registered handler sees every decision (the engine applies one by run id and drops
+     * any its run no longer awaits), so several remote workflows can share the transport.
+     */
+    onDecision(handler: (decision: WorkflowDecision) => Promise<void>): void;
+    /** workflow worker → engine: a local step's lifecycle on `${P}:step-events` (job `stepEvent`),
+     *  point-to-point so ONE engine instance checkpoints each event once. */
+    dispatchStepEvent(event: WorkflowStepEvent): Promise<void>;
+    /** engine ← workflow worker: consume streamed step events. Idempotent — a second call is a no-op. */
+    onStepEvent(handler: (event: WorkflowStepEvent) => Promise<void>): void;
+    /** tenant → control plane: enqueue a {@link StartRunMessage} on `${P}:start-run` (job `startRun`),
+     *  stamped with this instance as the reply target. */
+    dispatchStartRun(msg: StartRunMessage): Promise<void>;
+    /** control plane ← tenant: consume {@link StartRunMessage}s. Idempotent — a second call is a no-op. */
+    onStartRun(handler: (msg: StartRunMessage) => Promise<void>): void;
+    /** tenant → control plane: enqueue a {@link RunRequest} on `${P}:run-request` (job `runRequest`),
+     *  stamped with this instance as the reply target. */
+    dispatchRunRequest(msg: RunRequest): Promise<void>;
+    /** control plane ← tenant: consume {@link RunRequest}s. Idempotent — a second call is a no-op. */
+    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
+    /**
+     * control plane → tenant: push a correlated {@link RunReply} onto the inbox of the instance that sent
+     * the request (`${P}:run-replies:<instance>`). Only the instance that consumed the request knows the
+     * requester, so this must run while that request is being handled — which is what the responder does.
+     * A reply with no known requester (a request that carried no `replyTo`) is dropped and reported.
+     */
+    publishRunReply(reply: RunReply): Promise<void>;
+    /**
+     * tenant ← control plane: consume this instance's reply inbox. Idempotent — a second call is a no-op
+     * (one gateway per transport matches every reply by id). The inbox is private to this instance, so it
+     * is consumed even when consumers are deferred: no other process could take its jobs.
+     */
+    onRunReply(handler: (reply: RunReply) => void): void;
+    /**
+     * control plane → tenant: push a {@link TenantEvent} onto the inbox of every instance with a live
+     * subscription to `evt.tenant` (none: nothing is pushed). Publishes are serialized, so each
+     * subscriber receives one publisher's events in publish order.
+     */
+    publishTenantEvent(evt: TenantEvent): Promise<void>;
+    /**
+     * tenant ← control plane: subscribe to `tenant`'s events. Announces the subscription to the control
+     * plane (re-announced every third of {@link QueueTransportOptions.inboxTtlMs} while it lasts) and
+     * consumes this instance's event inbox. Needs no store on this side. Returns an unsubscribe fn that
+     * detaches only this handler; the last one withdraws the subscription.
+     */
+    onTenantEvent(tenant: string, handler: (evt: TenantEvent) => void): () => void;
     /**
      * Stop every poll loop, WAIT (bounded) for the job already in a handler's hands, and hand any
      * still-unfinished job back to the broker before destroying the adapter. Without the wait, a