@dudousxd/nestjs-durable 0.0.0-beta-20260701163515

package/dist/index.d.ts

@@ -0,0 +1,718 @@
+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 { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+
+/**
+ * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
+ * (`packages/core/src/accessor.ts`).
+ *
+ * We deliberately do NOT import nestjs-context (it is an OPTIONAL peer). Instead
+ * we declare the same shape here and inject it via the shared
+ * {@link CONTEXT_ACCESSOR} token with `@Optional()`. Any object that structurally
+ * satisfies this interface — including nestjs-context's real accessor — works.
+ *
+ * Kept byte-aligned with nestjs-context's `ContextAccessor` (and the identical
+ * mirror in `@dudousxd/nestjs-authz`): `traceId()` / `tenantId()` are REQUIRED
+ * (the real accessor always provides them) and `get()` is included, so the
+ * structural match stays exact when DurableModule auto-feeds the carrier.
+ */
+interface UserRef {
+    type: string;
+    id: string | number;
+}
+/** Opaque shape of the context store. durable never reads it; mirrors the upstream surface. */
+type ContextStore = Record<string, unknown>;
+interface ContextAccessor {
+    /** Trace id for the current request, or `undefined` when unavailable. */
+    traceId(): string | undefined;
+    /** Current tenant id, or `undefined` when no multi-tenant context is populated. */
+    tenantId(): string | undefined;
+    /** Reference to the current user, or `undefined` when unauthenticated. */
+    userRef(): UserRef | undefined;
+    /** The raw context store for the current request, or `undefined`. */
+    get(): ContextStore | undefined;
+}
+
+declare const WORKFLOW_METADATA: unique symbol;
+interface WorkflowMeta {
+    name: string;
+    version: string;
+    /** The workflow this workflow's dead runs route to (a name or a class). See `WorkflowOptions`. */
+    deadLetterWorkflow?: WorkflowRef | undefined;
+    /** Static searchable labels stamped on every run of this workflow. See `WorkflowOptions`. */
+    tags?: string[] | undefined;
+    /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
+    singleton?: SingletonConfig | undefined;
+    /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
+    executionTimeout?: string | number | undefined;
+    /** class-validator DTO validated at start. See `WorkflowOptions`. */
+    inputSchema?: (new (...args: any[]) => object) | undefined;
+    /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
+    validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+    /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
+    onEvent?: string[] | undefined;
+    /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
+    debounce?: string | number | undefined;
+    /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
+    batch?: {
+        maxSize: number;
+        within: string | number;
+    } | undefined;
+}
+interface WorkflowOptions {
+    name: string;
+    version?: string;
+    /**
+     * Route this workflow's dead-lettered runs to another **registered** workflow — by class
+     * (`deadLetterWorkflow: CheckoutDlqWorkflow`, refactor-safe) or by name for a cross-runtime
+     * handler. For a handler co-located on the same class, prefer an inline `@DeadLetter()` method
+     * instead — it takes precedence, and declaring both is a boot-time error. The handler receives a
+     * {@link DeadLetter} payload, idempotent by a `dlq:<runId>` id.
+     */
+    deadLetterWorkflow?: WorkflowRef;
+    /**
+     * Static labels stamped on **every run** of this workflow (e.g. `tags: ['etl', 'critical']`) and
+     * merged with any per-run tags passed to `start`. Searchable/filterable in the dashboard.
+     */
+    tags?: string[];
+    /**
+     * Serialize runs of this workflow that share a key — a durable FIFO mutex. e.g.
+     * `singleton: { key: (input) => `base:${input.baseId}` }` runs at most one pipeline per base at a
+     * time; same-key runs queue (suspended) and admit in creation order as slots free. `limit` (default
+     * 1) raises the concurrency.
+     */
+    singleton?: SingletonConfig;
+    /**
+     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
+     * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
+     * runs that get stuck or loop forever. Omit for no limit.
+     */
+    executionTimeout?: string | number;
+    /**
+     * Validate the workflow input at `start` against a **class-validator DTO** (the same
+     * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
+     * run is created. Needs the optional peers `class-validator` + `class-transformer`.
+     * `@Workflow({ inputSchema: CheckoutInput })`.
+     */
+    inputSchema?: new (...args: any[]) => object;
+    /**
+     * Custom input validator (throws on invalid) — an escape hatch for zod/yup/etc. instead of
+     * `inputSchema`. Takes precedence over `inputSchema` if both are set.
+     */
+    validateInput?: (input: unknown) => void | Promise<void>;
+    /**
+     * 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.
+     */
+    onEvent?: string[];
+    /**
+     * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
+     * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
+     */
+    debounce?: string | number;
+    /**
+     * Coalesce `onEvent` triggers by **batching** — start one run with all payloads (`{ events: [...] }`)
+     * once `maxSize` is reached or `within` elapses from the first event. e.g.
+     * `batch: { maxSize: 100, within: '10s' }`.
+     */
+    batch?: {
+        maxSize: number;
+        within: string | number;
+    };
+}
+/**
+ * Marks a provider class as a durable workflow. Its `run(ctx, input)` method becomes the
+ * workflow function the engine executes and replays.
+ */
+declare function Workflow(options: WorkflowOptions): ClassDecorator;
+declare function getWorkflowMeta(target: Function): WorkflowMeta | undefined;
+declare const DURABLE_STEP_METADATA: unique symbol;
+interface DurableStepMeta {
+    name: string;
+}
+/**
+ * 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.
+ */
+declare function Step(name: string): 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.
+ */
+declare const DurableStep: typeof Step;
+declare function getDurableStepMeta(method: Function): DurableStepMeta | undefined;
+declare const DEAD_LETTER_METADATA: unique symbol;
+/**
+ * The payload a dead-letter handler receives: the dead run's id, its workflow, the input it was
+ * started with (typed via `TInput`), and the failure that killed it.
+ */
+interface DeadLetter<TInput = unknown> {
+    /** Id of the run that was dead-lettered (inspectable + retriable in the dashboard). */
+    deadRunId: string;
+    /** Name of the workflow whose run died. */
+    workflow: string;
+    /** The original input the dead run was started with. */
+    input: TInput;
+    /** The structured error that moved the run to `dead`, when known. */
+    error?: StepError;
+}
+/**
+ * Marks a method on a `@Workflow` class as that workflow's **inline dead-letter handler**. When a
+ * run of the workflow is moved to `dead` (exceeded `maxRecoveryAttempts`), this method runs — as a
+ * durable workflow itself, auto-registered as `<workflow>.dlq` with a `dlq:<runId>` id — receiving a
+ * {@link DeadLetter} payload. It shares the class's injected dependencies, so the handler lives in
+ * the same file as the workflow it protects.
+ *
+ * Takes precedence over `@Workflow({ deadLetterWorkflow })` and the module-level `deadLetterWorkflow`
+ * default. The method signature is `(ctx, dead)` — the same `ctx` a workflow `run` gets.
+ */
+declare function DeadLetter(): MethodDecorator;
+declare function isDeadLetterHandler(method: Function): boolean;
+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[];
+    /**
+     * The tenant this worker process serves. Each of {@link groups} is suffixed via
+     * `tenantGroup(group, tenant)` (`@dudousxd/nestjs-durable-core`) before the consumer starts, so
+     * `undefined`, `''`, or `'default'` stays byte-identical to the bare group (production
+     * unchanged), and any other tenant serves `<group>@<tenant>` — matching the group name an
+     * OPERATOR control plane's `remoteByConvention` routes that tenant's runs to
+     * (`tenantGroup(run.workflow, run.namespace)` on the engine side).
+     */
+    tenant?: 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.
+ *
+ * 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).
+ */
+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[];
+
+/**
+ * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
+ * (status sets must be disjoint — validated at boot), swept together on a shared interval.
+ *
+ * ```ts
+ * retention: {
+ *   sweepInterval: '1m',
+ *   batchSize: 1_000,
+ *   policies: [
+ *     { statuses: ['completed', 'cancelled'], maxAge: '14d', maxCount: 200 },
+ *     { statuses: ['failed'], maxAge: '90d' }, // keep failures longer for debugging
+ *   ],
+ * }
+ * ```
+ */
+interface DurableRetentionOptions {
+    /** The retention rules, one per (disjoint) status group. */
+    policies: RetentionPolicy[];
+    /**
+     * How often to run the prune sweep. A number is milliseconds; a string is an `ms`-style duration
+     * (`'1m'`, `'5m'` — `'m'` is minutes). `0` runs it once on boot only. Defaults to 60000 (1 minute).
+     */
+    sweepInterval?: number | string;
+    /** Max runs hard-deleted per batch (per policy, looped until drained). Defaults to 1000. */
+    batchSize?: number;
+}
+interface DurableModuleOptions {
+    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 })`.
+     * Use instead of `transport`.
+     */
+    transports?: NamedTransport[];
+    /**
+     * Cross-instance broadcast pub/sub (lifecycle events + cancellation). Defaults to the (first)
+     * 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. */
+    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.
+     */
+    autoSchema?: boolean;
+    /**
+     * Worker-pool partition 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`.
+     */
+    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.
+     */
+    leaseMs?: number;
+    /** Unique id for this instance (for leases). Defaults to a random id. */
+    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.
+     */
+    maxRecoveryAttempts?: number;
+    /**
+     * Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
+     * returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
+     * 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.
+     */
+    remoteAdvanceSilenceMs?: number;
+    /**
+     * The **default** workflow to route dead-lettered runs to, for workflows that don't declare their
+     * own. When a run is moved to `dead` (exceeded `maxRecoveryAttempts`), the started handler gets a
+     * `DeadLetter` payload `{ deadRunId, workflow, input, error }` (idempotent by a `dlq:<runId>` id) —
+     * 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).
+     */
+    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.
+     */
+    worker?: boolean;
+    /**
+     * Internal axis, orthogonal to {@link worker}: whether this instance DRIVES runs — polls
+     * pending, recovers crashed (`recoverIncomplete`), resumes due timers, sweeps timeouts — even
+     * when it does not itself execute `@Workflow`/`@Step` bodies. Defaults to `worker !== false`
+     * (back-compat: `worker:true` drives, and a plain `worker:false` API/dashboard pod does not).
+     * `DurableControlPlaneModule` sets this `true` alongside `worker:false`: an OPERATOR control
+     * plane that drives every run but dispatches each one to a remote tenant worker group (see
+     * {@link remoteByConvention}) instead of running it in-process. Most apps never set this
+     * directly — use `DurableModule` (a worker) or `DurableControlPlaneModule` (a driving,
+     * non-executing control plane) instead.
+     */
+    drive?: boolean;
+    /** Max ms to wait for in-flight runs on shutdown before exiting. Defaults to 10000. */
+    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
+     * time-bucket run id, so racing instances start each window exactly once. Cron schedules need the
+     * optional `cron-parser` peer dependency.
+     */
+    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
+     * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (the
+     * MikroORM adapter does); other adapters no-op with a warning. See {@link DurableRetentionOptions}.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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`.
+     */
+    traceparent?: () => string | undefined;
+    /**
+     * Provide an opaque context carrier (tenant / user / correlation ids) to stamp on dispatched remote
+     * tasks, so workers re-expose it to the step handler alongside the `traceparent`. The engine never
+     * inspects its shape.
+     *
+     * **Auto-feed**: if you omit this AND `@dudousxd/nestjs-context` is installed (its accessor is bound
+     * to the shared `CONTEXT_ACCESSOR` token), DurableModule defaults this to a reader that builds
+     * `{ traceId, tenantId, userRef }` from the accessor — so a workflow dispatched within a request
+     * automatically carries the originating context across process boundaries. Pass your own reader to
+     * override the auto-feed; with neither, the carrier is omitted (unchanged behavior).
+     *
+     * 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.
+     */
+    context?: () => Record<string, unknown> | undefined;
+    /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos. */
+    compensationRetries?: number;
+    /**
+     * Route an **unregistered** workflow whose name matches a live worker group to that group over the
+     * primary transport — no per-workflow `engine.remote()` registration needed. Default `false`. Set
+     * `true` on a control plane that dispatches to convention-named polyglot workers (see
+     * `WorkflowEngineDeps.remoteByConvention`).
+     */
+    remoteByConvention?: boolean;
+    /**
+     * 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). See
+     * {@link DurableModuleOptions.store}.
+     */
+    scopeReads?: boolean;
+    /**
+     * 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}.
+     */
+    inAppWorker?: DurableInAppWorkerOptions;
+}
+interface DurableModuleAsyncOptions {
+    useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
+    inject?: InjectionToken[];
+}
+declare class DurableModule {
+    static forRoot(options: DurableModuleOptions): DynamicModule;
+    static forRootAsync(options: DurableModuleAsyncOptions): DynamicModule;
+    private static build;
+}
+/**
+ * The **control-plane** packaging of {@link DurableModule}: an intention-revealing alias that always
+ * forces `worker: false, drive: true`. A control-plane instance mounts the engine, the dashboard, and
+ * the store, and DRIVES every run — polls pending, recovers crashed, resumes due timers, sweeps
+ * timeouts — but never itself executes a `@Workflow`/`@Step` body: pair it with
+ * `remoteByConvention: true` (or per-workflow `engine.remote()`) so each driven run dispatches to a
+ * remote tenant worker group instead of running in-process. A started run no longer sits orphaned
+ * `pending` forever waiting for a worker's own poll — this instance drives it itself.
+ *
+ * Pair it with tenant workers packaged via `DurableWorkerModule` (which run `@Step`/`@Workflow`
+ * handlers over the transport, hold no engine/store, and can `startRun` back over the protocol). Use
+ * `DurableModule` directly when one instance should be BOTH dispatcher and worker.
+ *
+ * Any `worker`/`drive` passed in options is ignored — this factory hard-sets `worker: false, drive: true`.
+ */
+declare class DurableControlPlaneModule {
+    static forRoot(options: DurableModuleOptions): DynamicModule;
+    static forRootAsync(options: DurableModuleAsyncOptions): DynamicModule;
+}
+
+declare const ENTITY_METADATA: unique symbol;
+declare const ENTITY_ON_METADATA: unique symbol;
+/**
+ * Marks an `@Injectable()` class as a **durable entity** (a virtual object): its `@On(op)` methods run
+ * serialized per key over the instance's fields as durable state. e.g.
+ *
+ * ```ts
+ * @Entity({ name: 'cart' }) @Injectable()
+ * class Cart { items: Item[] = []; @On('add') add(i: Item) { this.items.push(i); } @On('list') list() { return this.items; } }
+ * ```
+ *
+ * The class must be **constructible with no arguments** (a fresh instance is the initial state per key)
+ * — keep entities pure state, no DI. Drive them with `EntityService` or `ctx.signalEntity`/`callEntity`.
+ */
+declare function Entity(options: {
+    name: string;
+}): ClassDecorator;
+/** Marks an entity method as the handler for operation `op`. */
+declare function On(op: string): MethodDecorator;
+declare function getEntityMeta(target: Function): {
+    name: string;
+} | undefined;
+/**
+ * Build the engine `EntityConfig` for a discovered `@Entity` class: a fresh instance per key, and
+ * handlers that rehydrate the class prototype onto the (serialized) state before dispatching the op,
+ * so methods work after replay.
+ */
+declare function entityConfigFor(ctor: Function): {
+    initialState: () => object;
+    handlers: Record<string, EntityHandler>;
+};
+/** Inject this to drive durable entities from outside a workflow. */
+declare class EntityService {
+    private readonly engine;
+    constructor(engine: WorkflowEngine);
+    /** Send an operation to an entity (fire-and-forget; ordered + exactly-once per key). */
+    signal(name: string, key: string, op: string, arg?: unknown): Promise<void>;
+    /** Read an entity's current durable state (or undefined if it has none yet). */
+    getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
+}
+
+declare const STEP_INTERCEPTOR_METADATA: unique symbol;
+/**
+ * The shape a `@StepInterceptor()` provider must implement: `intercept(invocation, next)` wraps the
+ * real execution of every local `ctx.step` (call `next()` to run the step body / next interceptor,
+ * and return — or transform — its result). The engine-level {@link StepInterceptor} primitive, with
+ * NestJS dependency injection.
+ */
+interface DurableStepInterceptor {
+    intercept(invocation: StepInvocation, next: () => Promise<unknown>): Promise<unknown>;
+}
+/**
+ * Marks an `@Injectable()` class as a durable step interceptor. The module discovers it on boot and
+ * registers its `intercept` method with the engine (so it can inject loggers/tracers/etc.). First
+ * declared is outermost. Interceptors fire only when a step actually executes, never on replay.
+ */
+declare function StepInterceptor(): ClassDecorator;
+declare function isStepInterceptor(target: Function): boolean;
+
+/**
+ * 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
+ * peer dependency) — instead we share its well-known token by value so DI
+ * resolves the same provider when nestjs-context is installed and present.
+ *
+ * `Symbol.for(key)` uses the global symbol registry, so this resolves to the
+ * SAME symbol instance as nestjs-context's `tokens.ts` (and the identical token
+ * declared by `@dudousxd/nestjs-authz`) without any import. The key MUST stay
+ * byte-identical with nestjs-context's export.
+ */
+declare const CONTEXT_ACCESSOR: unique symbol;
+
+/** Public entry point for starting and resuming workflow runs. */
+declare class WorkflowService {
+    private readonly engine;
+    constructor(engine: WorkflowEngine);
+    /**
+     * Enqueue a workflow run — it creates the run (`pending`) and returns `{ runId, status: 'pending' }`
+     * immediately; a worker executes the body (so the caller never blocks on workflow logic). Use
+     * {@link waitForRun} when you need the outcome. Pass the workflow's **class**
+     * (`start(CheckoutWorkflow, input)`) for a typed input + refactor-safety, or a **name** string for a
+     * cross-runtime workflow. `runId` defaults to a random id; pass your own to make the start idempotent
+     * (a redelivery returns the existing run). `opts.tags` are merged with the workflow's static
+     * `@Workflow({ tags })`; `opts.searchAttributes` stamp typed, queryable run data.
+     */
+    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>;
+    resume(runId: string): Promise<RunResult>;
+    /**
+     * Resolve once a run settles — terminal (completed/failed/cancelled/dead) or suspended. `start`
+     * only enqueues (a worker runs the body), so pair them when a request needs the outcome:
+     * `const { runId } = await svc.start(...); const result = await svc.waitForRun(runId)`.
+     */
+    waitForRun(runId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+    /** Deliver an external signal (e.g. from a webhook) to the run waiting on `token`. */
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
+    /**
+     * Ensure a run exists for `runId`, then deliver a signal to it — race-free (the signal is buffered
+     * until the run reaches its `waitForSignal`). The durable-entity / accumulator pattern: one
+     * long-lived run per key fed events by many calls. See {@link WorkflowEngine.signalWithStart}.
+     */
+    signalWithStart<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }, opts?: StartOptions): Promise<{
+        runId: string;
+    }>;
+    signalWithStart(workflow: string, input: unknown, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }, opts?: StartOptions): Promise<{
+        runId: string;
+    }>;
+    /**
+     * 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
+     * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
+     * touched (resumed + started).
+     */
+    publishEvent(name: string, payload: unknown, opts?: {
+        id?: string;
+    }): Promise<number>;
+}
+
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, DurableControlPlaneModule, 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 };