@dudousxd/nestjs-durable 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { StepError, WorkflowRef, SingletonConfig, WorkflowExecutor, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
-import { ConcurrencyOption, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
+import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunDetail, RunQuery, WorkflowRun, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { z } from 'zod';
+import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -105,7 +106,7 @@ interface WorkflowOptions {
      * Start a fresh run of this workflow whenever any of these events is published via
      * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
      * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
-     * the `@OnEvent(...)` class decorator; the two are merged.
+     * the `@OnDurableEvent(...)` class decorator; the two are merged.
      */
     onEvent?: string[];
     /**
@@ -131,14 +132,71 @@ declare function Workflow(options: WorkflowOptions): ClassDecorator;
 declare function getWorkflowMeta(target: Function): WorkflowMeta | undefined;
 declare const DURABLE_STEP_METADATA: unique symbol;
 interface DurableStepMeta {
+    /** The resolved routing name — derived (`Class.method`) or explicit, always present. */
     name: string;
+    /** Opt-in runtime input schema, validated when the handler is served (see `scanSteps`). Absent on
+     *  a bare `@Step()` — compile-time types from the method signature only, no runtime check. */
+    input?: z.ZodType | undefined;
+    /** Opt-in runtime output schema, validated before the handler's result is handed back. */
+    output?: z.ZodType | undefined;
 }
 /**
- * Marks a provider method as the handler for a remote step `name`. An in-process transport
- * (e.g. the event-emitter transport) routes dispatched tasks to it. The method's single
- * argument is the step input; its return value is the step output.
+ * `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
+ * timeoutMs? })` — the object call form. See {@link Step}.
  */
-declare function Step(name: string): MethodDecorator;
+interface StepOptions {
+    /** Explicit routing name, overriding the derived `Class.method`. */
+    name?: string;
+    /** Runtime input schema, validated at the serve boundary (opt-in — a bare `@Step()` skips it). */
+    input?: z.ZodType;
+    /** Runtime output schema, validated before the result is returned (opt-in). */
+    output?: z.ZodType;
+    /**
+     * Def-level durable-dispatch policy stamped under `DURABLE_STEP_CONFIG` and read by `ctx.step` at
+     * the dispatch boundary (see `stepConfigOf`) — a per-call `ctx.step(ref, input, opts)` overrides
+     * these field-by-field. Max attempts before the step (and run) fails.
+     */
+    retries?: number;
+    /** How the delay between retries grows: `fixed` (constant) or `exp` (doubles each attempt). */
+    backoff?: 'fixed' | 'exp';
+    /** Base delay in ms between retries. Omit (or 0) to retry with no delay. */
+    backoffMs?: number;
+    /** Upper bound on the (exponential) backoff delay. */
+    backoffMaxMs?: number;
+    /** Add random jitter (50–100% of the computed delay) to avoid thundering-herd retries. */
+    jitter?: boolean;
+    /**
+     * Liveness window for a dispatched step: no result/heartbeat within this many ms presumes the
+     * worker dead and fails the dispatch with a `RemoteStepTimeout` (retryable — re-dispatches per
+     * `retries`). Omit to wait indefinitely.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Marks a provider method as a durable step handler. An in-process transport (e.g. the
+ * event-emitter transport) or a co-located/thin worker runtime routes a dispatched task to it BY
+ * NAME — `ctx.step(this.svc.method, input)` reads that same name off the method reference (stamped
+ * via the shared, cross-package `DURABLE_STEP_NAME` symbol from `@dudousxd/nestjs-durable-core`), so
+ * there's no separately-declared def linking a call site to this handler. The method's single
+ * argument is the step input (plus an optional `StepLogger` second arg); its return value is the
+ * step output.
+ *
+ * Three call forms:
+ * - `@Step()` — bare: the routing name is DERIVED from the method as `` `${ClassName}.${method}` ``
+ *   (e.g. `ExtractionService.runExtractionPage`) — refactor-safe, no magic string.
+ * - `@Step('custom:name')` — explicit name override (stable across refactors, or a cross-runtime
+ *   contract with a non-JS worker that has no `@Step` of its own).
+ * - `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
+ *   timeoutMs? })` — optional name override, opt-in RUNTIME zod schemas, and a def-level
+ *   durable-retry/liveness-timeout policy. `input` validates before the method runs; `output`
+ *   validates its return value before it's handed back (see `scanSteps`). `retries`/`backoff`/
+ *   `backoffMs`/`backoffMaxMs`/`jitter`/`timeoutMs` are the policy `ctx.step` reads off this method
+ *   reference (via `stepConfigOf`) to build the dispatched `StepDef`'s durable retry/backoff and
+ *   remote-liveness timeout — a per-call `ctx.step(ref, input, opts)` overrides them field-by-field.
+ *   A bare `@Step()` carries none of this and skips validation/retry/timeout — compile-time types
+ *   from the method signature are the only check, and the step dispatches with no retry/timeout.
+ */
+declare function Step(nameOrOptions?: string | StepOptions): MethodDecorator;
 /**
  * @deprecated Use `@Step` instead. `@DurableStep` is a back-compat alias of {@link Step} and
  * writes the same `DURABLE_STEP_METADATA`, so discovery/registrars treat them identically.
@@ -176,190 +234,17 @@ declare const ON_EVENT_METADATA: unique symbol;
 /**
  * Subscribe a `@Workflow` class to one or more events: when any of them is published via
  * `publishEvent(name, payload)`, a fresh run of the workflow starts with the payload as input.
- * Equivalent to `@Workflow({ onEvent })` — use whichever reads better; multiple `@OnEvent(...)`
- * decorators and the option are all merged.
- */
-declare function OnEvent(...events: string[]): ClassDecorator;
-/** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnEvent`. */
-declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
-
-/**
- * Options for a **store-less thin worker** process: where to consume (`connection`/`prefix`) and
- * which worker `groups` this process serves. There is deliberately NO `store`, `transport`, engine,
- * dashboard, recovery, or timer config — a thin worker only registers `@Workflow`/`@Step`
- * handlers and runs the BullMQ consumer (see {@link DurableWorkerModule}).
- */
-interface DurableWorkerModuleOptions {
-    /** ioredis connection (string or options), as `runRedisWorker` / `BullMQTransport` accept. */
-    connection: string | Record<string, unknown>;
-    /** The worker groups this process serves — one BullMQ consumer is started per group. */
-    groups: string[];
-    /** Key prefix namespacing the durable queues. Defaults to `durable` (matches the transport). */
-    prefix?: string;
-    /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
-    instanceId?: string;
-    /**
-     * How many tasks each group's consumer runs concurrently (BullMQ Worker concurrency). Defaults to 1.
-     * Applies to every group unless overridden per-group by {@link concurrencyByGroup}. Raise it so a
-     * fanned-out batch (e.g. the N remote steps of a `gather`) runs in parallel instead of serially.
-     *
-     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let each consumer self-tune its concurrency
-     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
-     */
-    concurrency?: ConcurrencyOption;
-    /** Per-group concurrency override, keyed by group name. Falls back to {@link concurrency} (then 1).
-     *  Each value may itself be `'adaptive'` / `{ mode:'adaptive', ... }`. */
-    concurrencyByGroup?: Record<string, ConcurrencyOption>;
-}
-interface DurableWorkerModuleAsyncOptions {
-    useFactory: (...args: never[]) => DurableWorkerModuleOptions | Promise<DurableWorkerModuleOptions>;
-    inject?: InjectionToken[];
-}
-/** The resolved {@link DurableWorkerModuleOptions} (canonical token). */
-declare const DURABLE_WORKER_OPTIONS: unique symbol;
-/**
- * The `runRedisWorker` function the module uses to start each group's BullMQ consumer. Defaults to
- * the real one from `@dudousxd/durable-worker`; tests `overrideProvider` it with a fake so no real
- * Redis is needed.
- */
-declare const RUN_REDIS_WORKER: unique symbol;
-/** The list of started {@link RunningWorker} handles (one per group), closed on shutdown. */
-declare const DURABLE_WORKER_RUNNERS: unique symbol;
-/** The signature of `runRedisWorker` — injected behind {@link RUN_REDIS_WORKER}. */
-type RunRedisWorkerFn = (opts: RunRedisWorkerOptions) => Promise<RunningWorker>;
-/**
- * Discovers every provider carrying `@Workflow` metadata and registers its `run(ctx, input)` on the
- * thin {@link DurableWorkerRuntime}. Mirrors the engine-side `WorkflowRegistrar`, but registers on
- * the runner-core runtime instead of a `WorkflowEngine` — the runtime drives `run` with the thin
- * `WorkflowContext` (which `implements WorkflowCtx`), so the body runs unchanged. NO store/engine.
- */
-declare class ThinWorkflowRegistrar implements OnModuleInit {
-    private readonly discovery;
-    private readonly runtime;
-    constructor(discovery: DiscoveryService, runtime: DurableWorkerRuntime);
-    onModuleInit(): void;
-}
-/**
- * Discovers every `@Step` method and registers it as a step handler on the thin
- * {@link DurableWorkerRuntime}. Mirrors the engine-side `DurableStepRegistrar`, but always registers
- * on the runtime (a thin worker IS the consumer — there is no in-process-vs-queue branch).
- */
-declare class ThinStepRegistrar implements OnModuleInit {
-    private readonly discovery;
-    private readonly metadataScanner;
-    private readonly runtime;
-    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, runtime: DurableWorkerRuntime);
-    onModuleInit(): void;
-}
-/**
- * Starts one BullMQ consumer per configured group on bootstrap (after both registrars have run, so
- * every handler is registered before any task is consumed) and closes them on shutdown. The only
- * runtime side effect of a thin worker: register handlers, run the consumer. No engine, no store,
- * no recovery, no timers, no dispatch.
- *
- * For the shutdown close to fire, enable Nest's shutdown hooks: `app.enableShutdownHooks()`.
- */
-declare class ThinWorkerBootstrap implements OnApplicationBootstrap, OnApplicationShutdown {
-    private readonly runtime;
-    private readonly options;
-    private readonly runRedisWorker;
-    private readonly runnersSink;
-    private readonly runners;
-    constructor(runtime: DurableWorkerRuntime, options: DurableWorkerModuleOptions, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
-    onApplicationBootstrap(): Promise<void>;
-    onApplicationShutdown(): Promise<void>;
-}
-/**
- * A NestJS dynamic module that turns an app into a **PURE durable worker**: it discovers
- * `@Workflow`/`@Step` providers, registers them on the thin {@link DurableWorkerRuntime}, and
- * runs one BullMQ consumer per group via `runRedisWorker`. It is **control-plane-less** — it binds
- * NO `WorkflowEngine`, NO store/ORM, NO dashboard, NO timer poller, NO recovery, and NO run dispatch.
- * Use it for a worker pod that only executes work an engine elsewhere coordinates.
+ * Equivalent to `@Workflow({ onEvent })` — use whichever reads better; multiple
+ * `@OnDurableEvent(...)` decorators and the option are all merged.
  *
- * Contrast with `DurableModule` (`worker: true`), which is a full control plane WITH a store: this
- * module is the store-less half. A workflow body runs identically on either (conformance-tested).
+ * Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
+ * app using both libs an auto-import picking the wrong one fails silently in either direction.
  */
-declare class DurableWorkerModule {
-    static forRoot(options: DurableWorkerModuleOptions): DynamicModule;
-    static forRootAsync(options: DurableWorkerModuleAsyncOptions): DynamicModule;
-    private static build;
-}
-
-/**
- * Opt-in config for an **in-app worker**: the same NestJS process runs the engine AND serves its own
- * discovered `@Workflow`/`@Step` on one default `group`. The engine registers each `@Workflow`
- * GROUP-SERVED (its turns are dispatched to `group` over the transport via a {@link RemoteWorkflowExecutor}
- * instead of run inline), and a co-located {@link DurableWorkerRuntime} consumes `group` and replays the
- * very same TS bodies. This is the uniform-dispatch "one app, both roles" shape — every turn pays a
- * transport round-trip even though the worker is the same process. Requires a transport that carries
- * workflow tasks (BullMQ); an in-process-only transport cannot dispatch a {@link WorkflowExecutor}.
- */
-interface DurableInAppWorkerOptions {
-    /** The default group this app dispatches its `@Workflow` turns to AND consumes as a worker. */
-    group: string;
-    /** ioredis connection (string or options) for the co-located worker consumer (`runRedisWorker`). */
-    connection: string | Record<string, unknown>;
-    /** Key prefix namespacing the durable queues. Defaults to `durable` (matches the transport). */
-    prefix?: string;
-    /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
-    instanceId?: string;
-    /**
-     * How many tasks the co-located worker runs concurrently from its group's queue (BullMQ Worker
-     * concurrency). Defaults to 1. Raise it so a fanned-out batch (e.g. the N remote steps of a
-     * `gather`) runs in parallel. Per process; total parallelism is `concurrency × replicas`.
-     *
-     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let the worker self-tune its concurrency
-     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
-     */
-    concurrency?: ConcurrencyOption;
-}
-/** The resolved {@link DurableInAppWorkerOptions} or `null` when the app didn't opt in. */
-declare const IN_APP_WORKER_OPTIONS: unique symbol;
-/**
- * The group-served binding the {@link import('./workflow.registrar').WorkflowRegistrar} applies to every
- * discovered `@Workflow`: `{ group, executor }` when the app opted into an in-app worker, else `null`
- * (workflows register inline — the unchanged default). The executor is a {@link RemoteWorkflowExecutor}
- * over the engine's own transport, so a group-served turn is dispatched to `group` and the co-located
- * worker (below) advances it.
- */
-declare const IN_APP_WORKER_BINDING: unique symbol;
-/** The co-located worker's {@link DurableWorkerRuntime} (the consumer half). */
-declare const IN_APP_WORKER_RUNTIME: unique symbol;
-/** `runRedisWorker`, injected so tests can substitute a fake (no real Redis). Defaults to the real one. */
-declare const IN_APP_RUN_REDIS_WORKER: unique symbol;
-/** Started {@link RunningWorker} handles for the in-app group(s), closed on shutdown. */
-declare const IN_APP_WORKER_RUNNERS: unique symbol;
-/** The group-served binding shape resolved behind {@link IN_APP_WORKER_BINDING}. */
-interface InAppWorkerBinding {
-    group: string;
-    executor: WorkflowExecutor;
-}
-/**
- * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@Step`
- * on a {@link DurableWorkerRuntime} (the SAME bodies the engine registered group-served), and on bootstrap
- * it starts one `runRedisWorker` consumer on the configured group, closing it on shutdown. A no-op when
- * the app didn't opt in. Mirrors the thin {@link import('./durable-worker.module').DurableWorkerModule},
- * but co-located with a full engine.
- */
-declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown {
-    private readonly discovery;
-    private readonly metadataScanner;
-    private readonly options;
-    private readonly runtime;
-    private readonly runRedisWorker;
-    private readonly runnersSink;
-    private readonly runners;
-    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, options: DurableInAppWorkerOptions | null, runtime: DurableWorkerRuntime, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
-    onModuleInit(): void;
-    onApplicationBootstrap(): Promise<void>;
-    onApplicationShutdown(): Promise<void>;
-}
-/**
- * The providers that stand up an in-app worker, added to {@link import('./durable.module').DurableModule}.
- * All are inert when `inAppWorker` is unset (the binding resolves to `null`, the bootstrap no-ops), so a
- * plain `DurableModule` is byte-for-byte unchanged.
- */
-declare function inAppWorkerProviders(): Provider[];
+declare function OnDurableEvent(...events: string[]): ClassDecorator;
+/** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
+declare const OnEvent: typeof OnDurableEvent;
+/** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnDurableEvent`. */
+declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
 
 /**
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
@@ -387,12 +272,32 @@ interface DurableRetentionOptions {
     /** Max runs hard-deleted per batch (per policy, looped until drained). Defaults to 1000. */
     batchSize?: number;
 }
+/**
+ * Options for `DurableModule.forRoot`/`forRootAsync`. The **role is inferred** from which of `store`/
+ * `connection` are set:
+ *
+ * - `{ store, transport }` — **operator**: a real `WorkflowEngine` + `StoreRunGateway` + drivers/
+ *   timer/retention/registrars, executing registered bodies INLINE. Driven by {@link drive} (default
+ *   `true`).
+ * - `{ connection }` (no `store`) — **thin worker**: `WorkflowEngine` resolves to a store-less
+ *   `DurableStartClient`; `RUN_GATEWAY` is a `ProxyRunGateway` when `transport` is also given, else
+ *   every method rejects with a clear error. No store/timer/retention/entity — just discovered
+ *   `@Workflow`/`@Step` handlers served over ONE `runRedisWorker` consumer.
+ * - `{ store, transport, connection }` — an **operator that also runs a co-located worker**: every
+ *   `@Workflow` is registered GROUP-SERVED (dispatched over the transport, PER WORKFLOW NAME, instead
+ *   of inline) and a co-located consumer (one `runRedisWorker` call) replays the same bodies.
+ *
+ * `forRoot` throws when neither `store` nor `connection` is set, and when `store` is set without a
+ * `transport`.
+ */
 interface DurableModuleOptions {
-    store: StateStore;
+    /** State store — set this to play the **operator** role (see the interface doc for the full role
+     *  matrix). Omit for a store-less **thin worker** (`connection` only). */
+    store?: StateStore;
     transport?: Transport;
     /**
      * An ordered pool of named transports for failover / multi-broker setups. The engine dispatches on
-     * the first and fails over to the next; a step pins one via `ctx.call(step, input, { transport })`.
+     * the first and fails over to the next; a step pins one via `ctx.step(handler, input, { transport })`.
      * Use instead of `transport`.
      */
     transports?: NamedTransport[];
@@ -401,29 +306,34 @@ interface DurableModuleOptions {
      * transport when it can broadcast (event-emitter, BullMQ); set explicitly to use a dedicated one.
      */
     controlPlane?: ControlPlane;
-    /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. */
+    /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. Operator only. */
     timerPollMs?: number;
     /**
      * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
      * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
+     * Operator only.
      */
     autoSchema?: boolean;
     /**
-     * Worker-pool partition for this instance (forwarded to the engine). Default `'default'`. Set a
-     * distinct value to share ONE state store across non-interchangeable pools — e.g. a developer's
-     * local instance vs the deployed cluster. See `WorkflowEngineDeps.namespace`.
+     * Worker-pool namespace for this instance (forwarded to the engine). The poll paths
+     * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
+     * namespace. Set distinct values to safely share ONE state store across non-interchangeable
+     * pools — e.g. a developer's local instance vs the deployed cluster. **Omit it to make this
+     * instance an OPERATOR** — an unset namespace drives/recovers/resumes runs of EVERY namespace and
+     * leaves the transport on its bare prefix. See `WorkflowEngineDeps.namespace`. Not to be confused
+     * with {@link partition} (the co-located/thin-worker QUEUE routing suffix).
      */
     namespace?: string;
     /**
      * Multi-instance recovery lease, in ms — how long an instance owns a run it picked up before
-     * another may take over. Defaults to 30000. Set above your longest synchronous run.
+     * another may take over. Defaults to 30000. Set above your longest synchronous run. Operator only.
      */
     leaseMs?: number;
-    /** Unique id for this instance (for leases). Defaults to a random id. */
+    /** Unique id for this instance (for leases, and the co-located/thin-worker consumer's heartbeats). */
     instanceId?: string;
     /**
      * Cap recovery attempts before a still-`running` run is moved to the `dead` dead-letter state
-     * (a poison pill that crashes the process every boot). Omit for unlimited.
+     * (a poison pill that crashes the process every boot). Omit for unlimited. Operator only.
      */
     maxRecoveryAttempts?: number;
     /**
@@ -432,6 +342,7 @@ interface DurableModuleOptions {
      * and lets recovery re-drive; each heartbeat rearms the window so a slow-but-alive worker is never
      * re-driven. Pair with a worker SDK that emits run-scoped heartbeats (`@dudousxd/durable-worker` ≥ the
      * release that ships them, and the Python `durable-worker`). Omit for the prior unbounded await.
+     * Operator only.
      */
     remoteAdvanceSilenceMs?: number;
     /**
@@ -441,54 +352,59 @@ interface DurableModuleOptions {
      * it can alert, compensate, or queue for review. Resolution per dead run: the workflow's inline
      * `@DeadLetter()` method → its `@Workflow({ deadLetterWorkflow })` reference → this default. Omit
      * everything to just leave dead runs parked (inspectable + retriable from the dashboard). Accepts a
-     * workflow class (refactor-safe) or a name (cross-runtime).
+     * workflow class (refactor-safe) or a name (cross-runtime). Operator only.
      */
     deadLetterWorkflow?: WorkflowRef;
     /**
-     * Whether this instance plays the **worker** role: register `@Step` handlers (consume the
-     * transport), recover incomplete runs on boot, and poll due timers. Defaults to `true`. Set
-     * `false` for a **dashboard/dispatch-only** instance (e.g. an API pod) that mounts the control
-     * plane and reads the store but must not process or recover workflows — leave that to the workers.
+     * Whether an **operator** instance actively DRIVES runs — polls pending, recovers crashed
+     * (`recoverIncomplete`), resumes due timers, sweeps timeouts, prunes retention, and consumes local
+     * steps — as opposed to a read-only/dashboard replica. Defaults to `true`. Set `false` for a
+     * **dashboard/dispatch-only** instance (e.g. an API pod) that mounts the store/dashboard but must
+     * not process or recover workflows — leave that to another driving instance. `drive: false` also
+     * installs the engine's no-op run dispatcher, so a freshly `start()`ed run stays enqueue-only until
+     * a driving instance's poll picks it up. Ignored (irrelevant) for a thin worker (no `store`).
      */
-    worker?: boolean;
-    /** Max ms to wait for in-flight runs on shutdown before exiting. Defaults to 10000. */
+    drive?: boolean;
+    /** Max ms to wait for in-flight runs on shutdown before exiting. Defaults to 10000. Operator only. */
     shutdownTimeoutMs?: number;
     /**
      * Recurring workflows to start on a schedule (fixed interval or cron). The timer poller fires
-     * them each tick on **worker** instances only; `engine.start` is idempotent by the schedule's
+     * them each tick on **driving** instances only; `engine.start` is idempotent by the schedule's
      * time-bucket run id, so racing instances start each window exactly once. Cron schedules need the
-     * optional `cron-parser` peer dependency.
+     * optional `cron-parser` peer dependency. Operator only.
      */
     schedules?: ScheduledWorkflow[];
     /**
      * Hard-prune terminal run history on an interval so `durable_workflow_runs` (and its child tables)
      * stays bounded — without it, completed/failed/cancelled runs accumulate forever and the timer
-     * poller's per-tick status scans get linearly slower. Worker instances only. Omit to keep all
+     * poller's per-tick status scans get linearly slower. Driving instances only. Omit to keep all
      * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (the
      * MikroORM adapter does); other adapters no-op with a warning. See {@link DurableRetentionOptions}.
+     * Operator only.
      */
     retention?: DurableRetentionOptions;
     /**
      * Build the public callback URL for a `ctx.webhook()` token, e.g.
      * ``(t) => `https://api.example.com/durable/api/webhooks/${t}` ``. Populates `DurableWebhook.url`
      * so a step can hand the URL to a third party. The dashboard's `POST webhooks/:token` receives the
-     * callback. Omit to build URLs yourself from the token.
+     * callback. Omit to build URLs yourself from the token. Operator only.
      */
     webhookUrl?: (token: string) => string;
     /**
      * Flow-control queues for remote steps, registered on the engine at startup. Reference one from a
-     * workflow with `ctx.call(step, input, { queue: name })` to cap its concurrency / admission rate.
+     * workflow with `ctx.step(handler, input, { queue: name })` to cap its concurrency / admission rate.
+     * Operator only.
      */
     queues?: QueueConfig[];
     /**
      * Admission backend for the flow-control `queues`. Defaults to in-process (per-instance) caps. Pass
      * a `RedisAdmissionBackend` (from `@dudousxd/nestjs-durable-admission-redis`) to make concurrency /
-     * rate-limit / priority ordering GLOBAL across every engine replica.
+     * rate-limit / priority ordering GLOBAL across every engine replica. Operator only.
      */
     admission?: AdmissionBackend;
     /**
      * Provide the current W3C `traceparent` to stamp on dispatched remote tasks, so workers continue
-     * the distributed trace. Pass `otelTraceparent` from `@dudousxd/nestjs-durable-otel`.
+     * the distributed trace. Pass `otelTraceparent` from `@dudousxd/nestjs-durable-otel`. Operator only.
      */
     traceparent?: () => string | undefined;
     /**
@@ -505,20 +421,63 @@ interface DurableModuleOptions {
      * Re-evaluated at each (re)dispatch — including a retry or a crash/scale-down resume that the engine
      * drives OUTSIDE the originating request scope, where this reader may return empty or stale values.
      * Treat the carrier as best-effort correlation/propagation metadata only — do NOT treat it as an
-     * authorization boundary.
+     * authorization boundary. Operator only.
      */
     context?: () => Record<string, unknown> | undefined;
-    /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos. */
+    /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos.
+     *  Operator only. */
     compensationRetries?: number;
     /**
-     * Opt into an **in-app worker** (uniform dispatch): the same process runs the engine AND serves its
-     * own discovered `@Workflow`/`@Step` on one default `group`. Each `@Workflow` is registered
-     * GROUP-SERVED — its turns are dispatched to `group` over the transport and replayed by a co-located
-     * worker consumer — instead of run inline. Requires a workflow-task transport (BullMQ). Omit (the
-     * default) to keep every `@Workflow` on the inline fast path with zero dispatch round-trips. See
-     * {@link DurableInAppWorkerOptions}.
+     * Opt into tenant read scoping: when `true` AND {@link namespace} is set, the module confines the
+     * store's reads to that namespace (a tenant-boundary view) instead of the operator view that sees
+     * all namespaces. Default `false` — the control plane (e.g. flip's `/ctrl` operator screens) stays
+     * unscoped. Requires a store that exposes the `withScope` capability (the MikroORM adapter does);
+     * a pre-built store without it is used as-is (construct it already-scoped instead). Operator only.
+     */
+    scopeReads?: boolean;
+    /**
+     * ioredis connection (string or options) for a **thin worker** (`connection` only) or the
+     * **co-located worker** consumer (`store` + `connection`). Set this to play a worker role (see the
+     * interface doc for the full role matrix). Omit to keep every `@Workflow` on the operator's inline
+     * fast path with zero dispatch round-trips.
+     */
+    connection?: string | Record<string, unknown>;
+    /**
+     * The isolation partition a worker role serves — a thin worker's or co-located worker's queue
+     * subscription, AND (for a co-located worker) the suffix each `@Workflow`'s dispatch token carries.
+     * Each handler's queue token is `tenantGroup(sanitizeQueueToken(name), partition)`
+     * (`@dudousxd/nestjs-durable-core`), so `undefined`, `''`, or `'default'` stays byte-identical to
+     * the bare (sanitized) name (single-tenant deployment unchanged), and any other partition serves
+     * `<name>@<partition>` — matching the queue name an operator's convention dispatch routes that
+     * tenant's runs to (`tenantGroup(run.workflow, run.namespace)` on the engine side). Not to be
+     * confused with {@link namespace} (the operator's own poll-scoping axis). Ignored for a plain
+     * operator (no `connection`).
+     */
+    partition?: string;
+    /** Key prefix namespacing the durable queues for a worker role's consumer. Defaults to `durable`
+     *  (matches the transport). Ignored for a plain operator (no `connection`). */
+    prefix?: string;
+    /**
+     * How many tasks a worker role's co-located/thin consumer runs concurrently PER SUBSCRIBED QUEUE
+     * (BullMQ Worker concurrency — the same limit is applied to every per-name queue the single
+     * `runRedisWorker` call starts). Defaults to 1. Raise it so a fanned-out batch (e.g. the N remote
+     * steps of a `gather`) runs in parallel instead of serially.
+     *
+     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let the consumer self-tune its concurrency
+     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat. Ignored
+     * for a plain operator (no `connection`).
+     */
+    concurrency?: ConcurrencyOption;
+    /**
+     * Per-handler concurrency override, keyed by workflow/step NAME. Falls back to {@link concurrency}
+     * (then 1). NOT YET WIRED THROUGH: `runRedisWorker` (`@dudousxd/durable-worker`) currently applies
+     * one {@link concurrency} limit uniformly across every per-name queue it subscribes to from a
+     * single call — reserved here for when per-name concurrency lands there.
      */
-    inAppWorker?: DurableInAppWorkerOptions;
+    concurrencyByHandler?: Record<string, ConcurrencyOption>;
+    /** Timeout for a thin worker's `RunGateway` round-trip over `transport` before it rejects. Defaults
+     *  to 10_000ms inside `ProxyRunGateway`. Ignored for an operator (bound to `StoreRunGateway`). */
+    runGatewayTimeoutMs?: number;
 }
 interface DurableModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
@@ -530,6 +489,118 @@ declare class DurableModule {
     private static build;
 }
 
+/**
+ * The **store-less `engine.start` facade** for a tenant worker. Provided under the `WorkflowEngine`
+ * DI token by {@link import('./durable.module').DurableModule} (`forRoot({ connection })`, no
+ * `store`), so tenant code calls `engine.start(...)` UNCHANGED — it has no idea it is a tenant.
+ * Instead of touching a DB, `start` publishes a `StartRunMessage` on the SHARED `durable-start-run`
+ * queue (Option B: tenant rides as message DATA, never as wire segmentation). The operator (control
+ * plane, `namespace: undefined`) consumes it, stamps the run's namespace from `tenant`, and routes
+ * the run's task to `<workflow>@<tenant>` — the partition THIS tenant's worker serves.
+ *
+ * `cancel`/`deleteRun` need the store/driver a tenant does not have; they throw. No wire message
+ * exists for them (the operator owns cancellation/retention).
+ */
+declare class DurableStartClient {
+    private readonly options;
+    private readonly deps?;
+    private readonly tenant;
+    constructor(options: DurableModuleOptions, deps?: StartRunDeps | undefined);
+    start<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, runId?: string, opts?: StartOptions): Promise<RunResult>;
+    start(workflow: string, input: unknown, runId?: string, opts?: StartOptions): Promise<RunResult>;
+    cancel(_runId: string): Promise<void>;
+    deleteRun(_runId: string): Promise<void>;
+    resume(_runId: string): Promise<void>;
+    waitForRun(_runId: string, _opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    signal(_token: string, _payload: unknown): Promise<void>;
+    signalWithStart(_workflow: string, _input: unknown, _runId: string, _signal: {
+        token: string;
+        payload?: unknown;
+    }, _opts?: StartOptions): Promise<void>;
+    publishEvent(_name: string, _payload: unknown, _opts?: {
+        id?: string;
+    }): Promise<void>;
+}
+
+/**
+ * The `runRedisWorker` function the module uses to start each partition's BullMQ consumer.
+ * Defaults to the real one from `@dudousxd/durable-worker`; tests `overrideProvider` it with a
+ * fake so no real Redis is needed.
+ */
+declare const RUN_REDIS_WORKER: unique symbol;
+/** The list of started {@link RunningWorker} handles (the single handle {@link ThinWorkerBootstrap}
+ *  starts), closed on shutdown. */
+declare const DURABLE_WORKER_RUNNERS: unique symbol;
+/** The signature of `runRedisWorker` — injected behind {@link RUN_REDIS_WORKER}. */
+type RunRedisWorkerFn = (opts: RunRedisWorkerOptions) => Promise<RunningWorker>;
+/**
+ * Discovers every provider carrying `@Workflow` metadata and registers its `run(ctx, input)` on the
+ * thin {@link DurableWorkerRuntime}. Mirrors the engine-side `WorkflowRegistrar`, but registers on
+ * the runner-core runtime instead of a `WorkflowEngine` — the runtime drives `run` with the thin
+ * `WorkflowContext` (which `implements WorkflowCtx`), so the body runs unchanged. NO store/engine.
+ * Inert (skips registration) outside the pure thin-worker role — see {@link isPureThinWorker}.
+ */
+declare class ThinWorkflowRegistrar implements OnModuleInit {
+    private readonly discovery;
+    private readonly runtime;
+    private readonly options;
+    constructor(discovery: DiscoveryService, runtime: DurableWorkerRuntime, options: DurableModuleOptions);
+    onModuleInit(): void;
+}
+/**
+ * Discovers every `@Step` method and registers it as a step handler on the thin
+ * {@link DurableWorkerRuntime}. Mirrors the engine-side `DurableStepRegistrar`, but always registers
+ * on the runtime (a thin worker IS the consumer — there is no in-process-vs-queue branch). Inert
+ * outside the pure thin-worker role — see {@link isPureThinWorker}.
+ */
+declare class ThinStepRegistrar implements OnModuleInit {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly runtime;
+    private readonly options;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, runtime: DurableWorkerRuntime, options: DurableModuleOptions);
+    onModuleInit(): void;
+}
+/**
+ * Starts ONE `runRedisWorker` call on bootstrap — after both registrars have run, so every handler
+ * is registered before any task is consumed — and closes it on shutdown. The runner (`@dudousxd/
+ * durable-worker`) derives its subscription from `runtime.registeredNames()` (one queue per
+ * registered `@Workflow`/`@Step` name), not a hand-declared group list. Inert outside the pure
+ * thin-worker role — see {@link isPureThinWorker}: an operator (`store` set) never starts this
+ * consumer, and `store + connection` starts its OWN co-located consumer instead (`in-app-worker.ts`).
+ *
+ * For the shutdown close to fire, enable Nest's shutdown hooks: `app.enableShutdownHooks()`.
+ */
+declare class ThinWorkerBootstrap implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly runtime;
+    private readonly options;
+    private readonly runRedisWorker;
+    private readonly runnersSink;
+    private readonly runners;
+    constructor(runtime: DurableWorkerRuntime, options: DurableModuleOptions, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+/**
+ * The thin-worker slice of {@link import('./durable.module').DurableModule}'s unified provider set —
+ * active for the pure thin-worker role (`connection` set, `store` unset): registers discovered
+ * `@Workflow`/`@Step` on a store-less {@link DurableWorkerRuntime} and starts ONE `runRedisWorker`
+ * consumer, one queue PER REGISTERED NAME. Always present in the provider list (so a single
+ * `DurableModule.forRootAsync` can serve any role once its options resolve); every class/factory here
+ * is inert (see {@link isPureThinWorker}) outside that role.
+ */
+declare function thinWorkerProviders(): Provider[];
+/**
+ * The no-transport fallback bound to `RUN_GATEWAY` for a thin worker (`connection` set, `store`
+ * unset) that didn't also pass a `transport` — mirrors `DurableStartClient`'s tenant-error idiom
+ * (`tenantUnsupported`): every method rejects with a clear, named error instead of a cryptic
+ * `this.gateway.X is not a function`. `subscribe` is synchronous on the `RunGateway` port, so it
+ * throws synchronously (same message) rather than returning a rejected promise.
+ */
+declare function unavailableRunGateway(): RunGateway;
+
 declare const ENTITY_METADATA: unique symbol;
 declare const ENTITY_ON_METADATA: unique symbol;
 /**
@@ -571,6 +642,135 @@ declare class EntityService {
     getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
 }
 
+/**
+ * The **co-located in-app worker** (uniform dispatch): active whenever an app supplies BOTH `store`
+ * AND `connection` (`DurableModule.forRoot({ store, transport, connection, partition? })`) — the same
+ * process runs the engine AND serves its own discovered `@Workflow`/`@Step`. The engine registers each
+ * `@Workflow` GROUP-SERVED — its turns are dispatched, PER WORKFLOW NAME, to
+ * `tenantGroup(sanitizeQueueToken(name), partition)` over the transport via a per-workflow
+ * `RemoteWorkflowExecutor` instead of run inline — and a co-located {@link DurableWorkerRuntime}
+ * subscribes one queue per discovered name (via `runRedisWorker`) and replays the very same TS bodies.
+ * This is the uniform-dispatch "one app, both roles" shape — every turn pays a transport round-trip
+ * even though the worker is the same process. Requires a transport that carries workflow tasks
+ * (BullMQ); an in-process-only transport cannot dispatch a `WorkflowExecutor`.
+ *
+ * Distinct from the PURE thin-worker role (`connection` set, `store` unset — see
+ * `durable-worker.module.ts`'s `ThinWorkflowRegistrar`/`ThinStepRegistrar`/`ThinWorkerBootstrap`),
+ * which has no engine/store of its own at all.
+ */
+declare const IN_APP_WORKER_BINDING: unique symbol;
+/** The co-located worker's {@link DurableWorkerRuntime} (the consumer half). */
+declare const IN_APP_WORKER_RUNTIME: unique symbol;
+/** `runRedisWorker`, injected so tests can substitute a fake (no real Redis). Defaults to the real one. */
+declare const IN_APP_RUN_REDIS_WORKER: unique symbol;
+/** Started {@link RunningWorker} handles for the in-app worker, closed on shutdown. */
+declare const IN_APP_WORKER_RUNNERS: unique symbol;
+/** The group-served binding shape resolved behind {@link IN_APP_WORKER_BINDING}. */
+interface InAppWorkerBinding {
+    transport: Transport;
+    partition?: string;
+}
+/**
+ * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@Step`
+ * on a {@link DurableWorkerRuntime} (the SAME bodies the engine registered group-served), and on
+ * bootstrap it starts one `runRedisWorker` call that subscribes one queue per discovered name,
+ * suffixed by the configured partition, closing it on shutdown. A no-op outside the co-located role
+ * (see {@link isCoLocatedWorker}). Mirrors the thin {@link
+ * import('./durable-worker.module').ThinWorkerBootstrap}, but co-located with a full engine.
+ */
+declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly options;
+    private readonly runtime;
+    private readonly runRedisWorker;
+    private readonly runnersSink;
+    private readonly runners;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, options: DurableModuleOptions, runtime: DurableWorkerRuntime, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
+    onModuleInit(): void;
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+/**
+ * The providers that stand up the co-located in-app worker, added to {@link
+ * import('./durable.module').DurableModule}'s unified provider set. All are inert outside the
+ * co-located role (`store` + `connection` both set — see {@link isCoLocatedWorker}), so a plain
+ * operator (`store` only) or pure thin worker (`connection` only) is unaffected.
+ */
+declare function inAppWorkerProviders(): Provider[];
+
+/**
+ * Tenant-side `RunGateway` — round-trips every verb as a `RunRequest`/`RunReply` pair over the
+ * transport, correlated by a minted `requestId`, and bridges `subscribe` onto the transport's
+ * per-tenant event stream. Bound under `RUN_GATEWAY` by `DurableModule`'s thin-worker role
+ * (`connection` set, no `store`) when the app supplies a `transport` (see `unavailableRunGateway`
+ * for the no-transport fallback). The counterpart to the operator-side `StoreRunGateway`: a tenant
+ * worker never touches a store/driver directly, only this proxy.
+ */
+declare class ProxyRunGateway implements RunGateway {
+    private readonly transport;
+    private readonly tenant;
+    private readonly timeoutMs;
+    private readonly pending;
+    constructor(transport: Transport, tenant: string, timeoutMs?: number);
+    private handleReply;
+    private request;
+    getRunDetail(runId: string): Promise<RunDetail | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    retry(runId: string): Promise<RunResult | null>;
+    continue(runId: string): Promise<RunResult | null>;
+    retryWithInput(runId: string, input: unknown): Promise<{
+        runId: string;
+    } | null>;
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+
+/**
+ * True for the **operator** role — `store` is set (with or without a co-located `connection`). See
+ * {@link DurableModuleOptions} for the full role matrix. Kept in its own module (rather than
+ * `durable.module.ts`) so the poller/registrar classes can import it as a plain VALUE without a
+ * circular value dependency on the module that also imports them as providers.
+ */
+declare function isOperatorRole(options: DurableModuleOptions): boolean;
+/**
+ * True when an operator instance actively DRIVES runs — polls pending, recovers crashed, resumes due
+ * timers, sweeps timeouts, prunes retention, consumes local steps — as opposed to a read-only/
+ * dashboard replica (`drive: false`) that mounts the store/dashboard but leaves driving to another
+ * instance. Meaningless (`false`) outside the operator role. Defaults to `true` for an operator.
+ */
+declare function isDrivingOperator(options: DurableModuleOptions): boolean;
+
+/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
+ *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
+ *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
+ *  this up (see `durable.module.ts`). */
+interface RunRequestTransport {
+    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
+    publishRunReply(reply: RunReply): Promise<void>;
+}
+/**
+ * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
+ * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
+ * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
+ * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
+ * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
+ * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
+ * sent. This is the security boundary of the tenant run gateway — do not weaken it.
+ */
+declare class RunRequestResponder {
+    private readonly transport;
+    private readonly gateway;
+    constructor(transport: RunRequestTransport, gateway: RunGateway);
+    /** Register the consumer on the transport. Each request is answered independently; a handler
+     *  failure never throws back into the transport (errors are captured into an error reply). */
+    start(): void;
+    private handle;
+    private callVerb;
+}
+
 declare const STEP_INTERCEPTOR_METADATA: unique symbol;
 /**
  * The shape a `@StepInterceptor()` provider must implement: `intercept(invocation, next)` wraps the
@@ -589,6 +789,57 @@ interface DurableStepInterceptor {
 declare function StepInterceptor(): ClassDecorator;
 declare function isStepInterceptor(target: Function): boolean;
 
+/**
+ * Store-backed `RunGateway` — the operator-side implementation, bound to {@link RUN_GATEWAY} on
+ * worker/drive instances. Reuses `DashboardService`'s six read/control method bodies verbatim
+ * (`dashboard.service.ts:76-172`), so a consumer that only needs the bounded `RunGateway` surface
+ * (the `RunRequestResponder`, a thin controller) doesn't have to depend on the dashboard package.
+ */
+declare class StoreRunGateway implements RunGateway {
+    private readonly store;
+    private readonly engine;
+    constructor(store: StateStore, engine: WorkflowEngine);
+    getRunDetail(runId: string): Promise<RunDetail | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    /** Re-enqueue (dispatch model) instead of resuming inline — a worker picks the run up and replays it. */
+    retry(runId: string): Promise<RunResult | null>;
+    continue(runId: string): Promise<RunResult | null>;
+    retryWithInput(runId: string, input: unknown): Promise<{
+        runId: string;
+    } | null>;
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+
+/** The narrow slice of `StateStore` the republisher needs — the `step.*`-event namespace fallback
+ *  (see {@link TenantEventRepublisher.namespaceFor}). Mirrors the `RunRequestTransport` narrowing
+ *  convention (`run-request-responder.ts`): depend on the smallest surface, not the whole store. */
+type RunLookupStore = Pick<StateStore, 'getRun'>;
+/**
+ * Re-publishes engine lifecycle events onto a run's per-tenant channel via `publish` (bound from
+ * `Transport.publishTenantEvent`), so a store-less tenant worker can live-tail its OWN runs.
+ *
+ * The run's namespace is read straight off `event.namespace` (stamped by `engine.ts`'s `emit()` on
+ * every `run.*` lifecycle event, where the run is already in hand); a `step.*` event doesn't carry
+ * it, so those fall back to `store.getRun`. EVERY run's resolved namespace is memoized in
+ * `runNamespaces` — including a bare/`default` run — so the store is read at most ONCE per run id
+ * regardless of how many `step.*` events that run emits; a `null` cache entry means "resolved, not
+ * a tenant" (distinct from "not yet resolved", i.e. absent from the map). A run's entry is deleted
+ * the moment its terminal event is handled, so the cache stays bounded to in-flight runs (tenant and
+ * default alike) — the same order of magnitude it was already paying for tenant runs alone, in
+ * exchange for turning a per-event store read into a per-run one.
+ */
+declare class TenantEventRepublisher {
+    private readonly store;
+    private readonly publish;
+    private readonly runNamespaces;
+    constructor(store: RunLookupStore, publish: (event: TenantEvent) => Promise<void>);
+    handle(event: EngineEvent): Promise<void>;
+    private namespaceFor;
+}
+
 /**
  * Cross-lib injection token for the current-request context accessor, owned by
  * `@dudousxd/nestjs-context`. We do NOT import nestjs-context (it is an OPTIONAL
@@ -601,6 +852,14 @@ declare function isStepInterceptor(target: Function): boolean;
  * byte-identical with nestjs-context's export.
  */
 declare const CONTEXT_ACCESSOR: unique symbol;
+/**
+ * Injection token for the bound `RunGateway` — the read/control surface a consumer (a controller,
+ * or the `RunRequestResponder`) uses instead of reaching for `WorkflowEngine`/`StateStore`
+ * directly. `DurableModule` binds it to `StoreRunGateway` on worker/drive (operator) instances.
+ * `Symbol.for` so re-resolving this module (e.g. across a dynamic-module boundary) still hits the
+ * same registration.
+ */
+declare const RUN_GATEWAY: unique symbol;
 
 /** Public entry point for starting and resuming workflow runs. */
 declare class WorkflowService {
@@ -647,7 +906,7 @@ declare class WorkflowService {
     }>;
     /**
      * Publish a named event. Resumes runs waiting on it via `ctx.waitForEvent(name, { match })` and
-     * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnEvent` (the
+     * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnDurableEvent` (the
      * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
      * touched (resumed + started).
      */
@@ -656,4 +915,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, type DurableInAppWorkerOptions, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_OPTIONS, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnEvent, RUN_REDIS_WORKER, type RunRedisWorkerFn, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isStepInterceptor };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };