@dudousxd/nestjs-durable-core 0.44.1 → 0.46.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * Flow control for remote steps. A queue caps how much work `ctx.call(step, input, { queue })`
+ * Flow control for dispatched steps. A queue caps how much work `ctx.step(step, input, { queue })`
  * admits at once — a concurrency limit and/or a fixed-window rate limit. When a call can't be
  * admitted it doesn't dispatch: the run re-suspends with a near-future wake time, and the timer
  * poller re-tries admission later — so flow control is durable (survives crashes) without holding
@@ -25,7 +25,7 @@ import { z } from 'zod';
  * blocked, and on a later retry only admits the one that is rightful-next under the policy.
  */
 interface QueueConfig {
-    /** Queue name, referenced by `ctx.call(step, input, { queue: name })`. */
+    /** Queue name, referenced by `ctx.step(step, input, { queue: name })`. */
     name: string;
     /** Max steps in flight at once for this queue (this instance). Omit for unlimited. */
     concurrency?: number;
@@ -114,7 +114,7 @@ declare class QueueController {
 }
 
 /**
- * Pluggable backend for the remote-step flow-control gate (`ctx.call(step, input, { queue })`). The
+ * Pluggable backend for the step flow-control gate (`ctx.step(step, input, { queue })`). The
  * engine asks it whether a queued call may be admitted now (concurrency / rate / ordering) and tells
  * it when an admitted slot is released.
  *
@@ -167,6 +167,69 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
  */
 declare function parseDuration(duration: string | number): number;
 
+/**
+ * Cross-package step-name stamp. The `@Step` decorator (`@dudousxd/nestjs-durable`) writes a
+ * method's derived routing name under this key; core's `ctx.step` reads it (via {@link stepNameOf})
+ * to route a method-reference call to the same handler a worker registers by name.
+ *
+ * `Symbol.for` (the GLOBAL registry), NOT a plain `Symbol()` — so a duplicate copy of this module
+ * (pnpm peer-dependency multiplexing, or a dual ESM/CJS load) still reads the SAME key. A plain
+ * `Symbol()` would mint a distinct token per copy, so a decorator running against one core instance
+ * could stamp a name core's `ctx.step` (a different instance) can never read back. Mirrors the
+ * `STATE_STORE` token fix in `./tokens.ts`.
+ */
+declare const DURABLE_STEP_NAME: unique symbol;
+/**
+ * Cross-package step-DISPATCH-POLICY stamp. `@Step({ retries, backoff, backoffMs, backoffMaxMs,
+ * jitter, timeoutMs })` (`@dudousxd/nestjs-durable`) writes the def-level durable-retry/liveness
+ * policy under this key; core's `ctx.step` reads it (via {@link stepConfigOf}) and merges it with any
+ * per-call {@link StepDispatchOpts} override to build the dispatched {@link StepDef}. Same
+ * `Symbol.for` rationale as {@link DURABLE_STEP_NAME} — a duplicate copy of this module (pnpm
+ * peer-dependency multiplexing, dual ESM/CJS) must still read back the SAME key.
+ */
+declare const DURABLE_STEP_CONFIG: unique symbol;
+/**
+ * The def-level durable-dispatch policy a `@Step(...)` can stamp on a method: retry/backoff and the
+ * remote-liveness `timeoutMs` — the dispatch-relevant subset of the engine's `StepOptions`. Read off
+ * a handler reference via {@link stepConfigOf}; a per-call {@link StepDispatchOpts} passed to
+ * `ctx.step(ref, input, opts)` overrides these field-by-field.
+ */
+interface StepConfig {
+    /** Max attempts before the step (and run) fails. */
+    retries?: number | undefined;
+    /** How the delay between retries grows: `fixed` (constant) or `exp` (doubles each attempt). */
+    backoff?: 'fixed' | 'exp' | undefined;
+    /** Base delay in ms between retries. Omit (or 0) to retry with no delay. */
+    backoffMs?: number | undefined;
+    /** Upper bound on the (exponential) backoff delay. */
+    backoffMaxMs?: number | undefined;
+    /** Add random jitter (50–100% of the computed delay) to avoid thundering-herd retries. */
+    jitter?: boolean | undefined;
+    /** Liveness window for the 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 | undefined;
+}
+/**
+ * A method carrying its `@Step`-stamped routing name (and, optionally, its dispatch policy).
+ * `ctx.step(ref, input)` reads the name via {@link stepNameOf} — the reference itself is never
+ * invoked directly by the caller's process (the worker serving that name re-resolves the real
+ * handler from DI), so an unbound `this` on `ref` is irrelevant; `ref` is purely a typed,
+ * refactor-safe handle onto the stamped name (and policy).
+ */
+type StepRef<TInput = unknown, TOutput = unknown> = ((input: TInput) => Promise<TOutput> | TOutput) & {
+    [DURABLE_STEP_NAME]?: string | undefined;
+    [DURABLE_STEP_CONFIG]?: StepConfig | undefined;
+};
+/** Read the `@Step`-stamped routing name off a function ref. `undefined` for anything unstamped
+ *  (including a plain string — {@link stepNameOf} only reads function refs; a caller passing a
+ *  string already has the routing name and dispatches it directly). */
+declare function stepNameOf(ref: unknown): string | undefined;
+/** Read the `@Step`-stamped dispatch policy off a function ref. `undefined` for anything unstamped
+ *  (including a plain string — a cross-runtime string-name call has no def-level policy to read; pass
+ *  it via {@link StepDispatchOpts} instead). */
+declare function stepConfigOf(ref: unknown): StepConfig | undefined;
+
 /**
  * A **workflow reference** is how one workflow names another to call it: either a registered workflow
  * **name** (a string — the only option across runtimes, e.g. a Python workflow) or, for a same-runtime
@@ -297,7 +360,7 @@ interface StepCheckpoint {
      * simply re-runs on replay (only `completed` short-circuits).
      */
     status: 'pending' | 'running' | 'completed' | 'failed';
-    /** What the step was called with — the `ctx.call` args for a remote step (a local step has none). */
+    /** What the step was called with — the `ctx.step` (dispatched) args for a remote step (a local step has none). */
     input?: unknown;
     output?: unknown;
     error?: StepError | undefined;
@@ -594,6 +657,85 @@ interface SignalWaiter {
      */
     parallelGroup?: string | undefined;
 }
+/**
+ * A DB-less tenant worker → control plane request to start a run. Published by a worker that has
+ * no direct DB access (the hosted-control-plane tenant model) onto the
+ * `<effectivePrefix>-start-run` queue; the control plane consumes it and turns it into a durable
+ * run (P4 of the tenants plan).
+ *
+ * The `tenant` identifies the namespace that owns the run (maps to the engine's `namespace`); it
+ * is separate from the wire-level key prefix so a single transport can serve multiple tenants.
+ */
+interface StartRunMessage {
+    tenant: string;
+    /** Registered workflow name. */
+    workflow: string;
+    input: unknown;
+    /** Optional caller-supplied run id (idempotency key). The engine generates one if absent. */
+    runId?: string | undefined;
+    /** Tags to stamp on the run (merged with the workflow's static @Workflow tags). */
+    tags?: string[] | undefined;
+    /** Typed, queryable run data to stamp on the run (same as {@link StartOptions.searchAttributes}). */
+    searchAttributes?: SearchAttributes | undefined;
+}
+/**
+ * A tenant worker → control plane read/control request over the shared transport. Enqueued on
+ * `<effectivePrefix>-run-request`; the control plane's `onRunRequest` consumer answers it, scoped to
+ * `tenant`, and publishes a {@link RunReply} on `<effectivePrefix>-run-reply` correlated by `requestId`.
+ */
+interface RunRequest {
+    /** Correlation id minted by the tenant; the matching {@link RunReply} carries it back. */
+    requestId: string;
+    /** The requesting tenant — the operator scopes the run's namespace to this. */
+    tenant: string;
+    body: RunRequestKind;
+}
+/** The discriminated verb + args of a {@link RunRequest}. Mirrors the tenant-facing `RunGateway`. */
+type RunRequestKind = {
+    kind: 'getRunDetail';
+    runId: string;
+} | {
+    kind: 'listRuns';
+    query: RunQuery;
+} | {
+    kind: 'cancel';
+    runId: string;
+    opts?: {
+        compensate?: boolean;
+    };
+} | {
+    kind: 'retry';
+    runId: string;
+} | {
+    kind: 'continue';
+    runId: string;
+} | {
+    kind: 'retryWithInput';
+    runId: string;
+    input: unknown;
+};
+/** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
+interface RunReply {
+    requestId: string;
+    result: RunReplyResult;
+}
+/** Success carries the verb's payload (JSON-serialised); failure carries a re-throwable error. */
+type RunReplyResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+/** A lifecycle event re-published to a single tenant's channel (`<effectivePrefix>-tenant-events-<tenant>`)
+ *  so a store-less tenant can live-tail ITS OWN runs. Scoped by the run's namespace at publish time. */
+interface TenantEvent {
+    tenant: string;
+    event: EngineEvent;
+}
 /** A unit of work dispatched to a remote worker. This is the documented wire payload. */
 interface RemoteTask {
     runId: string;
@@ -622,7 +764,7 @@ interface RemoteTask {
     /**
      * Admission priority carried through to the broker (BullMQ job `priority`) so a transport that
      * supports priority ordering lets an urgent task jump ahead of already-enqueued lower-priority
-     * ones at the worker. Mirrors the per-call `priority` from `ctx.call(..., { priority })`. Higher
+     * ones at the worker. Mirrors the per-call `priority` from `ctx.step(..., { priority })`. Higher
      * wins; absent means default/unprioritised. Transports without priority support ignore it.
      */
     priority?: number | undefined;
@@ -693,10 +835,10 @@ interface HistoryEvent {
 }
 /** A decision the workflow function produced at a `seq` that was not yet in history. */
 type WorkflowCommand = 
-/** `ctx.call(remoteStep, input)` — dispatch a remote step and await it. A worker's
- *  `ctx.gather_calls([...])` fan-out tags every dispatched call with the same `parallelGroup` so the
- *  dashboard renders the remote steps as one parallel fan (parity with the gathered `recordStep` /
- *  `startChild` tags). Undefined for a lone sequential `ctx.call`. */
+/** `ctx.step(handlerOrName, input)` — dispatch a step (by typed handler reference or by name) and
+ *  await it. A worker's `ctx.gather_calls([...])` fan-out tags every dispatched call with the same
+ *  `parallelGroup` so the dashboard renders the dispatched steps as one parallel fan (parity with
+ *  the gathered `recordStep` / `startChild` tags). Undefined for a lone sequential `ctx.step`. */
 {
     kind: 'call';
     seq: number;
@@ -816,7 +958,7 @@ interface WorkflowExecutor {
 }
 /**
  * A transport in an ordered pool, identified by `id`. The engine dispatches on the first by default
- * and fails over to the next on a dispatch error; a step can pin one via `ctx.call(…, { transport })`.
+ * and fails over to the next on a dispatch error; a step can pin one via `ctx.step(…, { transport })`.
  * The chosen `id` is stamped on the {@link RemoteTask} so a worker replies through the matching one.
  */
 interface NamedTransport {
@@ -840,6 +982,13 @@ interface Transport {
     onResult(handler: (result: StepResult) => Promise<void>): void;
     /** worker → engine: liveness signal for an in-flight long step. */
     onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /**
+     * Partition this transport's queues/keys by `namespace` (matching the engine's store namespace), so
+     * multiple logical deployments can share one broker. Idempotent. An explicit namespace passed to the
+     * transport's constructor TAKES PRECEDENCE over this. No-op when `namespace === "default"`. Optional —
+     * transports that don't partition simply omit it.
+     */
+    useNamespace?(namespace: string): void;
     /** Release the transport's resources (broker workers, queues, connections) for a clean shutdown.
      *  Optional — an in-process transport has nothing to close. Called on `onApplicationShutdown`
      *  after the engine drains, so a deploy hands off instead of leaving the broker to time out. */
@@ -864,6 +1013,35 @@ interface Transport {
      *  keyspace, so a group with workers but no engine-side registration (e.g. a local-step group)
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
+    /**
+     * DB-less tenant worker → control plane: publish a {@link StartRunMessage} requesting a new run.
+     * Optional — only transports that carry the hosted-control-plane protocol (P4) implement this.
+     * The message is enqueued on `<effectivePrefix>-start-run`; the control plane's
+     * `onStartRun` consumer turns it into a durable run.
+     */
+    dispatchStartRun?(msg: StartRunMessage): Promise<void>;
+    /**
+     * control plane ← tenant worker: consume {@link StartRunMessage}s and start runs. Pair with
+     * {@link dispatchStartRun}. Optional — only control-plane-side transports implement this.
+     */
+    onStartRun?(handler: (msg: StartRunMessage) => Promise<void>): void;
+    /**
+     * Tenant worker → control plane: publish a {@link RunRequest} (read/control) on
+     * `<effectivePrefix>-run-request`. Optional — only broker transports carry it.
+     */
+    dispatchRunRequest?(msg: RunRequest): Promise<void>;
+    /** control plane ← tenant worker: consume {@link RunRequest}s. Pair with {@link dispatchRunRequest}. */
+    onRunRequest?(handler: (msg: RunRequest) => Promise<void>): void;
+    /** control plane → tenant worker: publish a correlated {@link RunReply} on `<effectivePrefix>-run-reply`
+     *  (pub/sub; every tenant subscribes and filters by `requestId`). */
+    publishRunReply?(reply: RunReply): Promise<void>;
+    /** tenant worker ← control plane: consume {@link RunReply}s (filter by `requestId` client-side). */
+    onRunReply?(handler: (reply: RunReply) => void): void;
+    /** control plane → tenant worker: re-publish a lifecycle {@link TenantEvent} on the run's per-tenant
+     *  channel `<effectivePrefix>-tenant-events-<tenant>`. */
+    publishTenantEvent?(evt: TenantEvent): Promise<void>;
+    /** tenant worker ← control plane: subscribe to THIS tenant's event channel. Returns an unsubscribe fn. */
+    onTenantEvent?(tenant: string, handler: (evt: TenantEvent) => void): () => void;
 }
 /** How a worker decides its concurrency, carried in {@link WorkerStatus} so a dashboard can tell a
  *  fixed knob from a self-regulating one (and, for the latter, where the controller currently sits). */
@@ -997,10 +1175,10 @@ interface StepOptions {
     /** Add random jitter (50–100% of the computed delay) to avoid thundering-herd retries. */
     jitter?: boolean;
     /**
-     * Liveness window for a **remote** step (`ctx.call`): if the worker produces no result and no
+     * Liveness window for a dispatched step (`ctx.step`): if the worker produces no result and no
      * heartbeat within this many ms, the engine presumes it dead and fails the dispatch with a
      * `RemoteStepTimeout` (retryable — it re-dispatches per `retries`). Each heartbeat resets the
-     * window. Ignored for local steps. Omit to wait indefinitely.
+     * window. Omit to wait indefinitely.
      */
     timeoutMs?: number;
     /**
@@ -1012,17 +1190,22 @@ interface StepOptions {
     compensate?: () => Promise<void>;
 }
 /**
- * A typed handle to a step that runs on a remote worker. The `name` string is the contract:
- * the worker registers a handler under the same name. `input`/`output` validate at the boundary.
+ * The structural carrier a dispatched `ctx.step` call resolves to and hands the engine: `name` is
+ * the routing contract (the worker registers a handler under the same name, and routing is BY that
+ * name — a worker subscribes per registered handler name, not a hand-declared group). There is no
+ * public factory for this anymore — a `ctx.step(ref, input)` call builds one internally from the
+ * `@Step`-stamped name (see {@link StepRef}/`stepNameOf`); a `ctx.step(name, input)` call builds one
+ * from the literal string. `input`/`output` are optional runtime zod schemas an authoring layer MAY
+ * attach (e.g. `@Step({ input, output })`) for validation at the dispatch boundary — a bare `@Step()`
+ * carries neither, and the engine skips validation when they're absent.
  */
-interface RemoteStepDef<TInput = unknown, TOutput = unknown> extends StepOptions {
+interface StepDef<TInput = unknown, TOutput = unknown> extends StepOptions {
     name: string;
-    /** Worker group expected to handle this step. */
-    group: string;
-    input: z.ZodType<TInput>;
-    output: z.ZodType<TOutput>;
-    /** Branding so `ctx.call` can infer types. */
-    readonly __remote: true;
+    /** Optional isolation partition; routing is by `name`. Suffixes the routing token as
+     *  `<name>@<partition>` (via {@link tenantGroup}) — omit to route by the bare (sanitized) `name`. */
+    partition?: string | undefined;
+    input?: z.ZodType<TInput> | undefined;
+    output?: z.ZodType<TOutput> | undefined;
 }
 /**
  * A durable webhook handle minted by {@link WorkflowCtx.webhook}. Hand `url` to a third party,
@@ -1041,6 +1224,45 @@ interface DurableWebhook<TPayload = unknown> {
     /** Suspend until the callback arrives, then resume with its payload. */
     wait(): Promise<TPayload>;
 }
+/**
+ * Options for a dispatched {@link WorkflowCtx.step} call. `retries`/`backoff`/`backoffMs`/
+ * `backoffMaxMs`/`jitter`/`timeoutMs` are a PER-CALL override of the `@Step`-declared
+ * {@link StepConfig} (see `stepConfigOf`) — the effective policy `ctx.step` builds into the dispatched
+ * {@link StepDef} is `{ ...stepConfigOf(ref), ...opts }`, so a call-site value wins field-by-field. The
+ * string (cross-runtime) form of `ctx.step` has no stamped `@Step` to read, so it uses these fields
+ * as-is.
+ */
+interface StepDispatchOpts {
+    /** Subject the dispatch to a registered flow-control queue (concurrency / rate limit). */
+    queue?: string;
+    /** Admission priority within `queue`; higher is admitted first when a slot is contended
+     *  (default 0). No effect without a `queue`. */
+    priority?: number;
+    /** The fairness bucket for a queue with `fairness: 'key'` (e.g. a tenant id) — the queue
+     *  round-robins across distinct keys so one key can't monopolize the budget. Defaults to the run
+     *  id when omitted. No effect without a `queue`. */
+    fairnessKey?: string;
+    /** Pin the dispatch to a named transport in the pool (else the pool's first, with failover to the
+     *  rest). See `engine.registerQueue` / the engine's `transports` option. */
+    transport?: string;
+    /** Max attempts before the step (and run) fails. Overrides the `@Step`-declared value. */
+    retries?: number;
+    /** How the delay between retries grows: `fixed` (constant) or `exp` (doubles each attempt).
+     *  Overrides the `@Step`-declared value. */
+    backoff?: BackoffStrategy;
+    /** Base delay in ms between retries. Omit (or 0) to retry with no delay. Overrides the
+     *  `@Step`-declared value. */
+    backoffMs?: number;
+    /** Upper bound on the (exponential) backoff delay. Overrides the `@Step`-declared value. */
+    backoffMaxMs?: number;
+    /** Add random jitter (50–100% of the computed delay) to avoid thundering-herd retries. Overrides
+     *  the `@Step`-declared value. */
+    jitter?: boolean;
+    /** Liveness window for this 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. Overrides the `@Step`-declared value. */
+    timeoutMs?: number;
+}
 /**
  * The context handed to a workflow function. Every interaction with the outside world goes
  * through it so the engine can checkpoint — the workflow body itself stays deterministic.
@@ -1048,11 +1270,25 @@ interface DurableWebhook<TPayload = unknown> {
 interface WorkflowCtx {
     readonly runId: string;
     /**
-     * Run a local durable step: executed once, then its result is checkpointed and replayed. The
-     * body receives a {@link StepLogger} to record debug/error lines and sub-process outcomes — these
-     * are checkpointed with the step and shown under it in the dashboard.
+     * Run a durable step — always dispatched, always engine-scheduled: the ONE step primitive (no
+     * local/remote placement choice). Pass the step's method **reference** (a `@Step`-decorated
+     * method, typed by its own signature — refactor-safe, autocompleted):
+     *
+     * ```ts
+     * const r = await ctx.step(this.extraction.runExtractionPage, { page, key });
+     * ```
+     *
+     * or its **name** for a cross-runtime handler (no JS reference to import, e.g. a Python `@step`):
+     *
+     * ```ts
+     * const out = await ctx.step<ProcResult>('processing:proc', input);
+     * ```
+     *
+     * Both forms dispatch identically — a step runs on whatever worker serves that name and the run
+     * suspends (zero compute) until the result lands, then resumes with it (durable, replay-safe).
      */
-    step<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): Promise<TOutput>;
+    step<TInput, TOutput>(handler: StepRef<TInput, TOutput>, input: TInput, opts?: StepDispatchOpts): Promise<TOutput>;
+    step<TOutput = unknown>(name: string, input: unknown, opts?: StepDispatchOpts): Promise<TOutput>;
     /**
      * **Exactly-once** durable step for DB work: runs `fn` and writes the step's checkpoint in ONE
      * store transaction, so the business write and the "done" marker commit atomically — a crash can
@@ -1069,23 +1305,6 @@ interface WorkflowCtx {
     callEntity<TResult = unknown>(name: string, key: string, op: string, arg?: unknown): Promise<TResult>;
     /** Send a durable entity op without awaiting a result (fire-and-forget, dispatched once). */
     signalEntity(name: string, key: string, op: string, arg?: unknown): Promise<void>;
-    /**
-     * Dispatch a typed remote step and await its checkpointed result. Options:
-     * - `queue` — subject the dispatch to a registered flow-control queue (concurrency / rate limit).
-     * - `priority` — admission priority within that queue; higher is admitted first when a slot is
-     *   contended (default 0). No effect without a `queue`.
-     * - `fairnessKey` — the fairness bucket for a queue with `fairness: 'key'` (e.g. a tenant id);
-     *   the queue round-robins across distinct keys so one key can't monopolize the budget. Defaults
-     *   to the run id when omitted. No effect without a `queue`.
-     * - `transport` — pin the dispatch to a named transport in the pool (else the pool's first, with
-     *   failover to the rest). See `engine.registerQueue` / the engine's `transports` option.
-     */
-    call<TInput, TOutput>(step: RemoteStepDef<TInput, TOutput>, input: TInput, opts?: {
-        queue?: string;
-        priority?: number;
-        fairnessKey?: string;
-        transport?: string;
-    }): Promise<TOutput>;
     /**
      * Durable sleep: suspends the run for `duration` (e.g. `'30s'`, `'2h'`, `'7 days'`, or ms as a
      * number) without consuming resources, resuming automatically once the timer is due — even
@@ -1215,18 +1434,25 @@ interface WorkflowCtx {
      */
     patched(id: string): Promise<boolean>;
     /**
-     * Deterministic wall-clock (epoch ms): records the time on the first run and replays the SAME
-     * value afterwards. Use this instead of `Date.now()` inside a workflow — a raw `Date.now()` returns
-     * a different value on every replay, which silently corrupts a durable run.
+     * Deterministic wall-clock, epoch **milliseconds** (like `Date.now()`): records the time on the
+     * first run and replays the SAME value afterwards. Use this instead of `Date.now()`/`new Date()`
+     * inside a workflow — a raw clock read returns a different value on every replay, which silently
+     * corrupts a durable run. Returns a number so it composes in arithmetic (deadlines, elapsed);
+     * for an ISO string do `new Date(await ctx.now()).toISOString()`. Every step is dispatched now
+     * (see {@link step}), so a trivial timestamp capture gets this lightweight deterministic helper
+     * instead of a full `@Step` + worker round-trip.
      */
     now(): Promise<number>;
     /**
-     * Deterministic random in `[0, 1)`: recorded once, then replayed. Use instead of `Math.random()`
-     * (same replay-safety reason as {@link now}).
+     * **Deterministic capture.** Run `fn` once, checkpoint its result, and on replay return the SAME
+     * value WITHOUT re-running `fn` — the durable way to bring a non-deterministic value into a workflow
+     * where you control the generator: `ctx.sideEffect(() => uuidv7())`, `() => ulid()`,
+     * `() => Math.random()`, a config/env read. Prefer a {@link step} for real work with side effects
+     * (a DB write, an API call): `fn` here runs only once and MUST be effectively pure (it produces a
+     * value; it is not re-executed on replay), like Temporal's `sideEffect`. For a plain timestamp use
+     * {@link now}.
      */
-    random(): Promise<number>;
-    /** Deterministic UUID v4: recorded once, then replayed. Use instead of `crypto.randomUUID()`. */
-    uuid(): Promise<string>;
+    sideEffect<TValue>(fn: () => TValue | Promise<TValue>): Promise<TValue>;
     /**
      * Merge `attrs` into THIS run's {@link WorkflowRun.searchAttributes} — the indexed metadata the
      * dashboard and {@link RunQuery} filter on. Shallow merge: keys you don't pass are kept. Durable +
@@ -1267,6 +1493,10 @@ interface EngineEvent {
     type: EngineEventType;
     runId: string;
     workflow?: string | undefined;
+    /** The run's worker-pool partition (see {@link WorkflowRun.namespace}), stamped on the `run.*`
+     *  lifecycle events (where the emitting call site already has the run in hand) so a tenant-event
+     *  re-publisher can scope without a per-event store read. Absent on `step.*` events. */
+    namespace?: string | undefined;
     seq?: number | undefined;
     name?: string | undefined;
     kind?: StepKind | undefined;
@@ -1302,6 +1532,17 @@ interface StepInvocation {
  */
 type StepInterceptor = (invocation: StepInvocation, next: () => Promise<unknown>) => Promise<unknown>;
 
+/**
+ * {@link WorkflowCtx} plus the internal in-process local-step primitive — used ONLY by the library's
+ * own built-in workflows (the durable-entity runner) that need a checkpointed, in-process step the
+ * public `ctx.step` (always-dispatched, no in-process placement) no longer provides. Every
+ * `createWorkflowCtx` result actually carries `localStep` at runtime; this type just names the wider
+ * shape for the internal consumers that need it, without widening the public {@link WorkflowCtx}.
+ */
+interface InternalWorkflowCtx extends WorkflowCtx {
+    localStep<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): Promise<TOutput>;
+}
+
 /** One operation on a durable entity: mutate `state` in place and/or return a result. */
 type EntityHandler<S = unknown> = (state: S, arg: unknown) => unknown | Promise<unknown>;
 /** A durable keyed entity (a virtual object): per-key serialized handlers over durable state. */
@@ -1313,7 +1554,7 @@ interface EntityConfig<S = unknown> {
 }
 /** The slice of the engine the entity subsystem needs (so it stays a standalone module). */
 interface EntityHost {
-    register(name: string, version: string, fn: (ctx: WorkflowCtx, input: unknown) => Promise<unknown>): void;
+    register(name: string, version: string, fn: (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>): void;
     signalWithStart(workflow: string, input: unknown, runId: string, signal: {
         token: string;
         payload?: unknown;
@@ -1383,7 +1624,7 @@ declare class EventAccumulators {
     private batch;
 }
 
-type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
+type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
 /** Options for {@link WorkflowEngine.start}. */
 interface StartOptions {
     /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
@@ -1395,6 +1636,12 @@ interface StartOptions {
      * the engine dispatches to advance it. Higher wins; absent = unprioritised. See {@link WorkflowRun.priority}.
      */
     priority?: number | undefined;
+    /**
+     * Override the namespace stamped on the run. Defaults to the engine's own `namespace`. Set by the
+     * control plane when it starts a run on behalf of a tenant (a {@link StartRunMessage}'s `tenant`
+     * maps here), so one DB-less-tenant-facing engine can create runs across many namespaces.
+     */
+    namespace?: string | undefined;
 }
 /**
  * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
@@ -1421,7 +1668,7 @@ interface WorkflowEngineDeps {
     transport?: Transport | undefined;
     /**
      * An ordered pool of named transports. The engine dispatches on the first and fails over to the
-     * next on a dispatch error; a step pins one via `ctx.call(step, input, { transport: id })`. Use
+     * next on a dispatch error; a step pins one via `ctx.step(step, input, { transport: id })`. Use
      * this instead of `transport` for failover / multi-broker setups.
      */
     transports?: NamedTransport[] | undefined;
@@ -1434,7 +1681,7 @@ interface WorkflowEngineDeps {
     /** Epoch-ms clock; injectable for tests. Defaults to `Date.now`. */
     clock?: (() => number) | undefined;
     /**
-     * Flow-control admission backend for `ctx.call(step, input, { queue })`. Defaults to an in-process
+     * Flow-control admission backend for `ctx.step(step, input, { queue })`. Defaults to an in-process
      * {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
      * concurrency / rate-limit / ordering GLOBAL across engine replicas.
      */
@@ -1444,8 +1691,11 @@ interface WorkflowEngineDeps {
     /**
      * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
      * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
-     * namespace. Default `'default'` — byte-identical to a single-pool deployment. Set distinct values
-     * to safely share ONE state store across non-interchangeable pools (e.g. local dev vs a cluster).
+     * namespace. Set distinct values to safely share ONE state store across non-interchangeable pools
+     * (e.g. local dev vs a cluster). **Omit it to make this engine an OPERATOR** — an unset namespace
+     * drives/recovers/resumes runs of EVERY namespace (the poll filters no-op, the resume/decision
+     * guards fall through) and leaves the transport on its bare prefix. This is the hosted control
+     * plane: "ver tudo = ausência de namespace".
      */
     namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
@@ -1688,7 +1938,7 @@ declare class WorkflowEngine {
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
     /**
-     * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
+     * Register a flow-control queue referenced by `ctx.step(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
      * durable. Per engine instance (see {@link QueueConfig}). Registering the same name replaces it.
      */
@@ -1760,6 +2010,17 @@ declare class WorkflowEngine {
      * its identity stays its own.
      */
     private synthesizeRemoteChild;
+    /**
+     * Attempt to route an unregistered workflow to the live worker group of the same name: if the
+     * transport reports a live heartbeat for group `run.workflow`, synthesize a throwaway
+     * {@link RegisteredWorkflow} that dispatches to that group over the primary transport. Returns
+     * `undefined` when the group is not live. Always attempted — there is no opt-in flag; an explicit
+     * `register`/`registerRemote` still takes precedence (this only runs when nothing is registered).
+     *
+     * Recomputed per call (never memoized into `this.workflows`) so it stays correct if group
+     * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
+     */
+    private resolveRemoteByConvention;
     /**
      * Walk the parent chain of `childRunId` to the nearest ancestor registered as REMOTE, returning its
      * registration (or `undefined` if there is none). The parent of an awaited child is found via its
@@ -2229,25 +2490,17 @@ type StepHandler = (input: unknown, log: StepLogger) => Promise<unknown> | unkno
  */
 declare function runStepHandler(task: RemoteTask, handler: StepHandler | undefined): Promise<StepResult>;
 
-interface RemoteStepConfig<TInput, TOutput> extends StepOptions {
-    name: string;
-    /** Worker group expected to handle this step. Defaults to the `name` prefix before the first dot. */
-    group?: string;
-    input: z.ZodType<TInput>;
-    output: z.ZodType<TOutput>;
-}
-/**
- * Defines a typed handle to a step that runs on a remote worker. Call it from a workflow with
- * `ctx.call(step, input)`; a worker registers a handler under the same `name`.
- */
-declare function remoteStep<TInput, TOutput>(config: RemoteStepConfig<TInput, TOutput>): RemoteStepDef<TInput, TOutput>;
-
 /**
  * A {@link WorkflowExecutor} backed by a {@link Transport}: it advances a remote workflow by
  * DISPATCHING a {@link WorkflowTask} over the broker under the ENGINE-SUPPLIED `taskId`, WITHOUT
  * awaiting the decision. Pass one to `engine.registerRemote(name, version, { group, executor })` so a
  * workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
  *
+ * Routes by NAME, not a hand-declared group: the dispatched task's routing token is
+ * `tenantGroup(sanitizeQueueToken(name), partition)` — the same formula a {@link import('./interfaces').StepDef}
+ * uses — so `partition` is an optional isolation suffix, not a separate identity. Omit it to route by
+ * the bare (sanitized) `name`.
+ *
  * Multi-instance safe by construction: the executor holds NO in-memory state correlating a dispatched
  * turn to its decision. The engine records the `taskId` on the run as the awaited marker AND releases
  * the run's lease BEFORE calling `dispatch`, so the worker's {@link import('./interfaces').WorkflowDecision},
@@ -2264,8 +2517,9 @@ declare function remoteStep<TInput, TOutput>(config: RemoteStepConfig<TInput, TO
  */
 declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     private readonly transport;
-    private readonly group;
-    constructor(transport: Transport, group: string, _opts?: {
+    private readonly name;
+    private readonly partition?;
+    constructor(transport: Transport, name: string, partition?: string | undefined, _opts?: {
         timeoutMs?: number;
     });
     /**
@@ -2275,6 +2529,35 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/** A run + its timeline + child ids — the detail view. Mirrors the dashboard's `RunDetail`. */
+interface RunDetail {
+    run: WorkflowRun;
+    /** Steps in execution order (local + remote). */
+    timeline: StepCheckpoint[];
+    /** Ids of runs this run spawned (parent→children tree). */
+    children: string[];
+}
+/**
+ * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
+ * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
+ * a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
+ * (no metrics/bulk/workerHealth/update/signal) — those stay control-plane-only.
+ */
+interface RunGateway {
+    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>;
+    /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
+    subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
+}
+
 /**
  * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
  * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
@@ -2505,6 +2788,23 @@ declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strV
 /** The literal a side-table predicate compares against (booleans → `"true"`/`"false"` strings). */
 declare function attributeOperand(filter: AttributeFilter): string | number;
 
+/**
+ * Compute the worker group a tenant's run dispatches to. Mirrors the transport's
+ * default-is-bare rule (see {@link TransportPool.useNamespace}'s `'default'` no-op): a
+ * `tenant` of `undefined`, `''`, or `'default'` is the bare `baseGroup`, so a single-tenant
+ * deployment (or the `'default'` tenant of a multi-tenant one) stays byte-identical to today.
+ * Any other tenant suffixes the group as `<baseGroup>@<tenant>`, so an operator control plane
+ * (namespace: undefined) can route each tenant's run to its own worker pool.
+ */
+declare function tenantGroup(baseGroup: string, tenant: string | undefined): string;
+/**
+ * Sanitize a handler/workflow name for use as a BullMQ queue token: BullMQ forbids `:` in queue
+ * names (it uses the colon internally as a key separator), so every `:` is replaced with `-`. `.`
+ * is legal in a BullMQ queue name and is left as-is — step/workflow names commonly use it as a
+ * namespacing separator (e.g. `payments.charge-card`).
+ */
+declare function sanitizeQueueToken(name: string): string;
+
 /**
  * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
  * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
@@ -2635,4 +2935,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };