@dudousxd/nestjs-durable-core 0.0.0-beta-20260701163515

package/dist/index.d.cts

@@ -0,0 +1,2717 @@
+import { z } from 'zod';
+
+/**
+ * Flow control for remote steps. A queue caps how much work `ctx.call(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
+ * the run in memory.
+ *
+ * Accounting is per engine instance (the DBOS `workerConcurrency` tier): correct for the common
+ * single-orchestrator deployment. Global, cross-instance limits would need a durable counter in the
+ * store — a deliberate follow-up, not built here.
+ *
+ * Beyond raw caps, the controller can admit contended slots by PRIORITY and by per-KEY FAIRNESS
+ * (round-robin), so a single noisy key/tenant can't monopolize the concurrency budget. This is the
+ * DISPATCH/admission layer — it never touches workflow replay (engine positional logic). Default
+ * behaviour is unchanged FIFO when neither priority nor fairness is configured/passed.
+ *
+ * Design (vs Temporal/Inngest/DBOS): Temporal task queues are FIFO with separate priority levels;
+ * Inngest concurrency keys + throttle give per-key fairness; DBOS queues are FIFO with a
+ * `workerConcurrency` cap. We fold both knobs into the same in-process admission gate: an optional
+ * per-call `priority` (higher first) and an optional queue-level `fairness: 'key'` (round-robin by
+ * the per-call `key`). Because blocked calls re-suspend durably and retry independently (there is no
+ * resident FIFO list to reorder), the controller remembers the set of WAITERS that asked-and-were-
+ * 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 })`. */
+    name: string;
+    /** Max steps in flight at once for this queue (this instance). Omit for unlimited. */
+    concurrency?: number;
+    /** Fixed-window rate limit: at most `limit` admissions per `periodMs`. Omit for unlimited. */
+    rateLimit?: {
+        limit: number;
+        periodMs: number;
+    };
+    /** Delay (ms) before a concurrency-blocked call re-checks for a free slot. Default 1000. */
+    retryMs?: number;
+    /**
+     * Fairness policy for a contended concurrency slot. `'key'` round-robins across distinct per-call
+     * keys (the least-recently-served key wins the next slot), so one key can't monopolize the budget.
+     * Omit (or `'fifo'`) for plain first-come ordering. Priority always wins over fairness; fairness
+     * only breaks ties within the same priority.
+     */
+    fairness?: 'fifo' | 'key';
+    /**
+     * Arrival-order tiebreak among otherwise-equal waiters (same priority, same fairness rank).
+     * `'fifo'` (default) admits the earliest arrival; `'lifo'` admits the most recent (a stack). Orthogonal
+     * to `priority` and `fairness` — those still win first; this only breaks their ties.
+     */
+    order?: 'fifo' | 'lifo';
+}
+/**
+ * Per-call admission hints. All optional — omitting them keeps the legacy FIFO behaviour.
+ * - `priority`: higher is admitted first (default 0).
+ * - `key`: the fairness bucket (e.g. a tenant id) for `fairness: 'key'`.
+ * - `waiterId`: a stable id for THIS call across its retries (the engine passes the stepId), so the
+ *   controller can track it as one waiter instead of counting each retry as a new contender.
+ */
+interface AdmissionItem {
+    priority?: number | undefined;
+    key?: string | undefined;
+    waiterId?: string | undefined;
+}
+/** Admission decision: either admitted, or blocked until `retryAt` (epoch ms). */
+type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    retryAt: number;
+};
+/** In-process admission controller for one {@link QueueConfig}. */
+declare class QueueController {
+    readonly config: QueueConfig;
+    private readonly clock;
+    private inFlight;
+    private windowStart;
+    private windowCount;
+    /** Registered waiters by id (only used when priority/fairness ordering is in play). */
+    private readonly waiters;
+    /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
+    private waiterSeq;
+    /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
+    private readonly keyServed;
+    private servedTick;
+    constructor(config: QueueConfig, clock: () => number);
+    /** Whether this controller does any priority/fairness ordering (else it's a plain FIFO gate). */
+    private get ordered();
+    /**
+     * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
+     * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
+     *
+     * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
+     * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
+     * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
+     */
+    tryAdmit(item?: AdmissionItem): Admission;
+    /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
+    release(): void;
+    /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
+    private register;
+    /**
+     * Is the calling item the best candidate among all registered waiters? Ordering, best first:
+     *   1. higher `priority`;
+     *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
+     *   3. earliest registration (FIFO) — stable tiebreak.
+     * A bare item (no waiterId) is compared on its hints directly.
+     */
+    private isNext;
+    /** Strict "a should be admitted before b" comparison under the active policy. */
+    private better;
+    /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
+    private servedOf;
+}
+
+/**
+ * Pluggable backend for the remote-step flow-control gate (`ctx.call(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.
+ *
+ * The default {@link InMemoryAdmissionBackend} keeps per-instance counts — correct for a single
+ * orchestrator. Swap in a store/Redis-backed backend to make the caps and ordering GLOBAL across
+ * engine replicas (so `concurrency: 5` means 5 in-flight across the whole fleet, not 5 per pod).
+ *
+ * `tryAdmit`/`release` are async so a global backend can do its atomic round-trip; the in-memory one
+ * resolves synchronously. An UNREGISTERED queue name is treated as ungated (admits immediately) — the
+ * engine only tracks/releases a slot for a registered queue.
+ */
+interface AdmissionBackend {
+    /** Register (or replace) a queue's config. Called from `engine.registerQueue`. */
+    register(config: QueueConfig): void;
+    /** Whether `queue` is registered (gated). The engine only tracks/releases a slot for a gated queue. */
+    handles(queue: string): boolean;
+    /** May a call on `queue` take a slot now? On `ok`, the caller holds a slot until {@link release}. */
+    tryAdmit(queue: string, item: AdmissionItem): Promise<Admission>;
+    /**
+     * Release the slot granted by {@link tryAdmit} for `queue`. `slotId` is the admitted item's
+     * `waiterId` (the engine's stepId), so a lease-based backend can drop the exact slot; an in-process
+     * counter ignores it.
+     */
+    release(queue: string, slotId: string): Promise<void>;
+    /**
+     * Optional: subscribe to "a slot just freed on `queue`" events (e.g. a fleet-wide pub/sub). The
+     * engine uses it to wake its admission-blocked runs early instead of waiting for their retry tick.
+     * A backend without it falls back to retry-tick polling. Fired best-effort across the fleet.
+     */
+    onFreed?(handler: (queue: string) => void): void;
+}
+/**
+ * Default admission backend: one in-process {@link QueueController} per registered queue. Caps and
+ * waiter ordering are per engine instance (see {@link QueueConfig}). Preserves the exact pre-backend
+ * behaviour — the engine used to hold these controllers directly.
+ */
+declare class InMemoryAdmissionBackend implements AdmissionBackend {
+    private readonly clock;
+    private readonly controllers;
+    constructor(clock: () => number);
+    register(config: QueueConfig): void;
+    handles(queue: string): boolean;
+    tryAdmit(queue: string, item: AdmissionItem): Promise<Admission>;
+    release(queue: string, _slotId: string): Promise<void>;
+}
+
+/**
+ * Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
+ * `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
+ */
+declare function parseDuration(duration: string | number): number;
+
+/**
+ * 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
+ * TypeScript workflow, its **class**. The class carries the input/output types through the call, so
+ * `ctx.child(ShippingWorkflow, input)` type-checks the input and returns a typed result — while a
+ * string stays available for the cross-runtime case.
+ */
+/**
+ * The symbol the `@Workflow` decorator stamps a workflow's registered name onto, so a class ref can
+ * be resolved back to its name. A global-registry symbol (`Symbol.for`) so it survives duplicate
+ * copies of this package in a dependency tree.
+ */
+declare const WORKFLOW_NAME_KEY: unique symbol;
+/** Structural shape of a `@Workflow` class — its `run(ctx, input)` carries the input/output types. */
+type WorkflowClass<TInput = unknown, TOutput = unknown> = abstract new (...args: never[]) => {
+    run(ctx: never, input: TInput): Promise<TOutput> | TOutput;
+};
+/** A workflow reference: a registered name (cross-runtime) or a workflow class (typed, same-runtime). */
+type WorkflowRef<TInput = unknown, TOutput = unknown> = string | WorkflowClass<TInput, TOutput>;
+/** The input type a workflow class's `run` accepts. */
+type WorkflowInputOf<C> = C extends abstract new (...args: never[]) => {
+    run(ctx: never, input: infer I): unknown;
+} ? I : unknown;
+/** The output type a workflow class's `run` resolves to (Promise unwrapped). */
+type WorkflowOutputOf<C> = C extends abstract new (...args: never[]) => {
+    run(ctx: never, input: never): infer R;
+} ? Awaited<R> : unknown;
+/**
+ * Resolve a {@link WorkflowRef} to its registered workflow name: a string is returned as-is; a
+ * `@Workflow` class is resolved via the name the decorator stamped on it. Throws if a class was
+ * never decorated (so it carries no registered name).
+ */
+declare function workflowName(ref: WorkflowRef): string;
+
+/**
+ * Core type contracts for nestjs-durable.
+ *
+ * These are intentionally framework-agnostic: `@dudousxd/nestjs-durable-core` knows only
+ * these interfaces, never a concrete transport, store or ORM. Adapters implement them.
+ */
+type RunStatus = 
+/** Created + enqueued by `start`, not yet picked up — a worker will lease and execute it. */
+'pending' | 'running' | 'suspended'
+/**
+ * Compensating cancel in progress: `cancel(runId, { compensate: true })` has been requested and the
+ * saga undo is running in the background. NON-TERMINAL — the run is still in-flight (counted by the
+ * admission gate, re-driven by recovery if the engine crashes mid-compensation), and flips to
+ * `cancelled` once compensation completes. A non-compensating cancel skips this and goes straight to
+ * `cancelled`.
+ */
+ | 'cancelling' | 'completed' | 'failed' | 'cancelled'
+/** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill). Terminal; inspect it. */
+ | 'dead';
+/** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
+interface WorkflowRun {
+    id: string;
+    /** Registered workflow name, e.g. `checkout`. */
+    workflow: string;
+    /** Code version at start; old runs must resume on the version they began on. */
+    workflowVersion: string;
+    status: RunStatus;
+    /** Serialized workflow input (the args the run was started with). */
+    input: unknown;
+    /** Serialized workflow output, once `completed`. */
+    output?: unknown;
+    /** Structured error, once `failed`. */
+    error?: StepError | undefined;
+    /** When `suspended` on a durable sleep: epoch ms at which the run becomes due to resume. */
+    wakeAt?: number | undefined;
+    /** Recovery lease owner (engine instance id) while a run is being resumed. */
+    lockedBy?: string | undefined;
+    /** Recovery lease expiry (epoch ms); another instance may take over once it passes. */
+    lockedUntil?: number | undefined;
+    /** How many times crash-recovery has picked this run up — caps poison pills (see maxRecoveryAttempts). */
+    recoveryAttempts?: number | undefined;
+    /** Searchable labels: the workflow's static `@Workflow({ tags })` merged with the run's start-time tags. */
+    tags?: string[] | undefined;
+    /** Typed, queryable run data (e.g. `{ amount: 200, tier: 'pro' }`) — see {@link RunQuery.attributes}. */
+    searchAttributes?: SearchAttributes | undefined;
+    /**
+     * The worker-pool partition this run belongs to. Stamped at creation from the creating engine's
+     * `namespace` (default `'default'`). A worker only picks up / recovers / resumes-timers-for /
+     * times-out runs in its own namespace. `undefined` on a run created before this field existed; the
+     * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
+     */
+    namespace?: string | undefined;
+    /**
+     * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
+     * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
+     * lower-priority ones at the worker. Higher wins; absent = unprioritised. Best-effort ordering, not
+     * durable state required for correctness — a transport without priority support ignores it.
+     */
+    priority?: number | undefined;
+    /**
+     * REMOTE workflow turn awaiting a decision: the `taskId` of the turn the engine dispatched to a
+     * workflow worker and then SUSPENDED on. Set by the dispatch-and-suspend path; matched by
+     * {@link WorkflowEngine.completeRemoteDecision} so ONLY the decision for the currently-awaited turn
+     * is applied (a stale/duplicate/foreign decision is dropped), then cleared the moment it is applied.
+     * This is what makes a workflow-turn decision multi-instance safe: any engine instance that receives
+     * the decision looks the run up by `decision.runId` and applies it durably, instead of resolving an
+     * in-memory promise that only the dispatching instance held. Absent on non-remote / not-awaiting runs.
+     */
+    awaitingDecisionTaskId?: string | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
+/**
+ * The recorded result of a single step at a deterministic logical position (`seq`).
+ * On replay, a `completed` checkpoint means the step is NOT re-executed — its `output` is
+ * returned. A non-terminal checkpoint (`pending`/`running`) does not short-circuit: the step is
+ * re-awaited (remote) or re-run (local).
+ */
+interface StepCheckpoint {
+    runId: string;
+    /** Deterministic logical position of the step within the run. */
+    seq: number;
+    /** Registered step name (matches the remote handler name for remote steps). */
+    name: string;
+    kind: StepKind;
+    /** Stable id passed to remote workers so they can dedupe a re-delivered task. */
+    stepId: string;
+    /**
+     * `pending` = a remote step dispatched and awaiting its worker result (the run is durably
+     * suspended, not held in memory); it becomes `completed`/`failed` when the result arrives.
+     * `running` = a local step whose body is executing in-process right now (see `trackStepStart`);
+     * it's overwritten by `completed`/`failed` when the body settles, and on a crash mid-body it
+     * 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). */
+    input?: unknown;
+    output?: unknown;
+    error?: StepError | undefined;
+    attempts: number;
+    /** For remote steps: which worker group ran it. */
+    workerGroup?: string | undefined;
+    /** Structured events/logs the step emitted (sub-step outcomes, debug/error lines). */
+    events?: StepEvent[] | undefined;
+    /** For sleep steps: epoch ms the sleep elapses at. */
+    wakeAt?: number | undefined;
+    /**
+     * Set on the running placeholder checkpoints of the children dispatched by one `ctx.all` call —
+     * a shared tag (`all:<firstSeq>`) grouping the N siblings so the dashboard can render them as one
+     * parallel fan-out. Optional and additive: absent on every non-`all` checkpoint. Mirrors the
+     * Python SDK's `parallelGroup`.
+     */
+    parallelGroup?: string | undefined;
+    /**
+     * When the step entered the system: for a remote step, when the engine dispatched it to the
+     * transport; for a local step, when it began. Queue-wait time = `startedAt − enqueuedAt`.
+     */
+    enqueuedAt: Date;
+    /** When processing actually began: worker pickup for a remote step, execution start for a local one. */
+    startedAt: Date;
+    finishedAt: Date;
+}
+/**
+ * A structured event a step (or its worker) emits while running — a log line and/or a sub-step
+ * outcome. The dashboard renders these under the step, so you can see what happened inside a step
+ * that the workflow treats as one unit (e.g. which of N parallel sub-processes ok/failed/skipped).
+ */
+interface StepEvent {
+    /** Epoch ms. */
+    at: number;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    /** Stable run identity for a sub-process. Distinct invocations of the same `name` carry distinct
+     *  ids, so their phases and log trails never collapse into one. Absent on events emitted by the
+     *  legacy `sub()` path, which keys by `name` instead. */
+    subId?: string;
+    /** For a sub-step/sub-process within the step: its name. */
+    name?: string;
+    /** Open, consumer-defined grouping label for a sub-process (e.g. a handler/lane). The dashboard
+     *  groups rows by it. The library never interprets it. */
+    group?: string;
+    /** For a sub-step: its terminal outcome (closed enum — drives colour + aggregation). */
+    status?: 'ok' | 'failed' | 'skipped';
+    /** Open, consumer-defined intermediate phase label for a sub-process transition. Carries no
+     *  terminal `status`; the library timestamps and orders it but never interprets it. */
+    phase?: string;
+    /** For a log line emitted *inside* a sub-process: that owning sub-process's name, so the dashboard
+     *  can group a step's log trail under each sub-process instead of one flat list. Set on logs (no
+     *  `status`); a worker stamps it from the sub-process it's running.
+     *  @deprecated Superseded by `subId` for run-distinct grouping; kept so existing workers/runs render. */
+    process?: string;
+    /** Optional structured payload. `data.durationMs` (number) overrides the derived duration. */
+    data?: unknown;
+}
+/**
+ * Handed to a local step's body (`ctx.step(name, (log) => …)`) so it can record what happened
+ * inside the step — debug/info/warn/error lines and per-sub-process outcomes. The events are
+ * checkpointed with the step and rendered under it in the dashboard. The remote/cross-language
+ * counterpart is the worker attaching the same `StepEvent[]` to its `StepResult` (see the Python
+ * SDK's `StepContext`), so observability is symmetric regardless of where the step ran.
+ */
+interface StepLogger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    /** Record a sub-step / sub-process outcome (e.g. one of N parallel p-processes). */
+    sub(name: string, status: 'ok' | 'failed' | 'skipped', message?: string, data?: unknown): void;
+    /** Record a sub-process event. Typically pass `phase` for an intermediate transition (carrying no
+     *  terminal status), or `status` for the terminal outcome — the type permits either; the engine
+     *  interprets which is set. `id` is the run identity (distinct per invocation); `group` is an
+     *  open grouping label. */
+    subEvent(e: {
+        id: string;
+        name: string;
+        group?: string | undefined;
+        phase?: string | undefined;
+        status?: 'ok' | 'failed' | 'skipped' | undefined;
+        message?: string | undefined;
+        data?: unknown;
+    }): void;
+    /**
+     * Ergonomic sub-process lifecycle: run `body`, timing it, and record a terminal `ok` with the
+     * measured `durationMs` on success — or `failed` (with the error message) if it throws, then
+     * re-throw. `sp.phase(label)` records an intermediate transition; `sp.skip(reason)` a terminal
+     * `skipped`. Logs emitted inside `body` are tagged to this sub-process so the dashboard groups
+     * them under it. Returns whatever `body` returns. The TS twin of the Python SDK's `sub_process`.
+     *
+     * ```ts
+     * const rows = await log.subProcess('fetch-data', async () => readEverything());
+     * await log.subProcess('export-file', () => upload(rows));
+     * ```
+     */
+    subProcess<T>(name: string, body: (sp: SubProcessHandle) => Promise<T> | T, opts?: {
+        group?: string;
+        id?: string;
+    }): Promise<T>;
+}
+/** The handle a {@link StepLogger.subProcess} body receives to mark phases / a non-`ok` outcome. */
+interface SubProcessHandle {
+    /** Record an intermediate phase transition (a consumer-defined label, no terminal status). */
+    phase(phase: string, data?: unknown): SubProcessHandle;
+    /** Record a terminal `skipped` outcome (e.g. nothing to do / validation failed). */
+    skip(reason?: string, data?: unknown): void;
+    /** Record a terminal `failed` outcome explicitly (the wrapper also does this if the body throws). */
+    fail(reason?: string, data?: unknown): void;
+}
+interface StepError {
+    message: string;
+    /** Optional machine-readable code, e.g. `declined`, `timeout`. */
+    code?: string | undefined;
+    /** Whether the engine should treat this as retryable. */
+    retryable?: boolean | undefined;
+    stack?: string | undefined;
+}
+interface StateStore {
+    /**
+     * Provision the tables/collections this store needs, idempotently. Called on boot when the
+     * module's `autoSchema` is on. Optional: stores that need no setup (in-memory) omit it.
+     */
+    ensureSchema?(): Promise<void>;
+    createRun(run: WorkflowRun): Promise<void>;
+    updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * Hard-delete a run and all of its rows — the run plus its checkpoints, signal waiters, and
+     * normalized search-attribute rows. Unlike a cancelled run (which stays as terminal history), a
+     * deleted run is GONE: it no longer appears in {@link getRun} or {@link listRuns}. This removes
+     * exactly the one run — the engine's {@link WorkflowEngine.deleteRun} handles the child cascade.
+     * No-op if the run doesn't exist. (Token-keyed buffered signals are transient and left alone.)
+     */
+    deleteRun(runId: string): Promise<void>;
+    /**
+     * Hard-delete up to `limit` terminal runs that fall OUTSIDE `policy` (oldest / over the count cap
+     * first), cascading to their child rows exactly like {@link deleteRun}. Returns how many runs were
+     * deleted — call again while it returns `limit` to drain a large backlog in bounded batches.
+     *
+     * Optional: only adapters that implement a bulk prune provide it; the retention poller no-ops with a
+     * warning when the configured store omits it. See {@link RetentionPolicy} for the keep/prune rule.
+     */
+    pruneTerminalRuns?(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
+    getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
+    /**
+     * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
+     * being a single transaction; stores without transactions cannot give the strong guarantee.
+     */
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    /**
+     * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
+     * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
+     * acquired — so concurrent engine instances never recover the same run twice.
+     */
+    tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
+    /** Release a run's recovery lease so another instance can pick it up (e.g. once it suspends). */
+    releaseRunLock(runId: string): Promise<void>;
+    /**
+     * Extend a run's lease to `leaseUntilMs`, but ONLY if `owner` still holds it — so a live worker
+     * heartbeating its long run keeps the lease, while a dead worker's lease still expires and gets
+     * reclaimed. Returns false if the lease was lost (taken over or released).
+     */
+    renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
+    /** Record that a run is suspended waiting for an external signal `token`. */
+    putSignalWaiter(waiter: SignalWaiter): Promise<void>;
+    /** Atomically take (and remove) the run waiting on `token`, if any. */
+    takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
+    /** List waiters whose `token` starts with `prefix` — used to fan out an event to its subscribers. */
+    listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    /**
+     * Buffer a signal whose waiter hasn't arrived yet, so the next `waitForSignal(token)` consumes it
+     * instead of it being lost (FIFO per token). Makes signals reliable regardless of timing and
+     * powers `signalWithStart`.
+     */
+    bufferSignal(token: string, payload: unknown): Promise<void>;
+    /** Take the oldest buffered signal for `token` (FIFO), or null if none is buffered. */
+    takeBufferedSignal(token: string): Promise<{
+        payload: unknown;
+    } | null>;
+    /**
+     * Run `work` in a SINGLE store transaction — giving it the store-native transaction handle (`raw`)
+     * for the caller's own DB writes plus a `saveCheckpoint` that commits IN THE SAME transaction, so a
+     * business write and the step's "done" checkpoint are atomic (exactly-once). Optional — only the SQL
+     * adapters implement it; `ctx.transaction` errors on a store without it.
+     */
+    transaction?<T>(work: (tx: StoreTransaction) => Promise<T>): Promise<T>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    /**
+     * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
+     * `undefined` if none. A targeted read that avoids fetching + deserializing every checkpoint just to
+     * keep one match — the store does the filter (`WHERE name = … ORDER BY seq DESC LIMIT 1`). Preserves
+     * the "last in seq order wins" semantics the engine relies on for `getEvent` (a re-published key
+     * overwrites the prior value at a higher seq, so the highest-seq match is the current value).
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS filter that produces the identical result.
+     */
+    getLatestCheckpointByName?(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    /**
+     * All checkpoints for `runId` whose `name` starts with ANY of `prefixes`, ordered by `seq` ascending
+     * (same order as {@link listCheckpoints}). A targeted read that avoids scanning every checkpoint just
+     * to keep the prefix matches — the store does the filter (`WHERE name LIKE 'prefix%' …`). Used by the
+     * run-tree to find a parent's child edges (`signal:child:` / `spawn:` checkpoints) without loading the
+     * whole history. An empty `prefixes` array matches nothing.
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS prefix scan that produces the identical result.
+     */
+    listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+}
+/** The terminal run statuses — a run in one of these is finished and will never change on its own.
+ *  Only these are eligible for retention pruning (a {@link RetentionPolicy} targeting a non-terminal
+ *  status would race the engine and delete live work). */
+declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+/**
+ * One retention rule for hard-pruning terminal run history. Within `statuses` (terminal only), a run
+ * is KEPT only if it satisfies EVERY bound you set, and pruned the moment it violates any:
+ *  - `maxAge` — prune runs whose `updatedAt` (≈ the time they reached terminal) is older than
+ *    `now - maxAge`. A number is milliseconds; a string is an `ms`-style duration parsed by
+ *    {@link parseDuration} (`'7d'`, `'2w'`, `'90m'` — note `'m'` is MINUTES; use `'30d'` for a month).
+ *  - `maxCount` — keep only the `maxCount` most-recent (by `updatedAt`) runs in the status set; prune
+ *    everything past that.
+ *
+ * Set one or both (both = the most-restrictive wins: capped at `maxCount` rows AND nothing older than
+ * `maxAge`). Statuses not named by any policy are never pruned.
+ */
+interface RetentionPolicy {
+    statuses: RunStatus[];
+    maxAge?: number | string;
+    maxCount?: number;
+}
+/** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
+type SearchAttributes = Record<string, string | number | boolean>;
+type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+/** One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all. */
+interface AttributeFilter {
+    key: string;
+    op: AttributeOp;
+    value: string | number | boolean;
+}
+interface RunQuery {
+    workflow?: string | undefined;
+    status?: RunStatus | undefined;
+    /**
+     * Match any of these statuses (a `status IN (...)` filter). ORed together, and ANDed with the other
+     * predicates. Use this instead of issuing one {@link listRuns} call per status — e.g. the singleton
+     * admission gate counts `running` + `suspended` in-flight runs in a single scan. If both `status` and
+     * `statuses` are set, both must hold (the single `status` further narrows the set). Empty array =
+     * matches nothing.
+     */
+    statuses?: RunStatus[] | undefined;
+    /** Only runs carrying this tag (exact match against {@link WorkflowRun.tags}). */
+    tag?: string | undefined;
+    /**
+     * Typed/range predicates over {@link WorkflowRun.searchAttributes}, ANDed together (e.g. `amount`
+     * >= 200 and `tier` = 'pro'). Applied in-process after the coarse filters, so pair with
+     * `workflow`/`status`/`tag` to bound the scan on large stores.
+     */
+    attributes?: AttributeFilter[] | undefined;
+    /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
+    namespace?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}
+/** The transaction handle `StateStore.transaction` hands to its work callback. */
+interface StoreTransaction {
+    /** The store-native transaction handle (TypeORM `EntityManager`, Prisma tx client, MikroORM `EntityManager`,
+     *  Drizzle tx) — do your business DB writes on THIS so they commit atomically with the checkpoint. */
+    readonly raw: unknown;
+    /** Persist the step checkpoint inside this transaction. */
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+}
+/** Binds an external signal `token` to the suspended run/step position waiting for it. */
+interface SignalWaiter {
+    token: string;
+    runId: string;
+    seq: number;
+    /**
+     * The parallel-fan group this waiter belongs to, carried from the awaiting command so the resolving
+     * `signal:<token>` checkpoint (notably `signal:child:<id>` for an awaited child run) can be tagged
+     * with it. A worker's `ctx.gather_children`/`ctx.all` fan-out stamps every `startChild` with the same
+     * group; without threading it through the waiter, the child-await checkpoint comes out untagged and the
+     * dashboard renders the fan as a sequential chain instead of one parallel group. Undefined for an
+     * ordinary (non-fan) signal/child await.
+     */
+    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;
+}
+/** A unit of work dispatched to a remote worker. This is the documented wire payload. */
+interface RemoteTask {
+    runId: string;
+    seq: number;
+    /** Handler name the worker registered, e.g. `payments.charge-card`. */
+    name: string;
+    stepId: string;
+    /** Worker group expected to handle this task. */
+    group: string;
+    input: unknown;
+    /** W3C traceparent so the worker can continue the distributed trace. */
+    traceparent?: string | undefined;
+    /**
+     * Opaque context carrier (tenant / user / correlation ids) the worker re-exposes to the step
+     * handler, for cross-process propagation alongside the {@link traceparent}. The engine treats it
+     * as a pass-through object and never inspects its shape — the producer (e.g. `@dudousxd/nestjs-context`)
+     * owns the keys. Absent when no `context` provider is configured.
+     */
+    context?: Record<string, unknown> | undefined;
+    /**
+     * Id of the transport this task was dispatched on (when the engine runs a pool — see
+     * {@link NamedTransport}). A worker that consumes several transports replies via the matching one,
+     * so failover is symmetric without the worker choosing a transport. Absent for a single transport.
+     */
+    transport?: string | undefined;
+    /**
+     * 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
+     * wins; absent means default/unprioritised. Transports without priority support ignore it.
+     */
+    priority?: number | undefined;
+    attempt: number;
+}
+interface StepResult {
+    runId: string;
+    seq: number;
+    stepId: string;
+    status: 'completed' | 'failed';
+    output?: unknown;
+    error?: StepError | undefined;
+    /** Epoch ms when the worker began processing — lets the engine report queue-wait time. */
+    startedAt?: number | undefined;
+    /** Structured events the worker emitted while running the step (sub-step outcomes, logs). */
+    events?: StepEvent[] | undefined;
+}
+interface Heartbeat {
+    runId: string;
+    seq: number;
+    /**
+     * The in-flight step this beat keeps alive. ABSENT for a RUN-scoped (workflow-turn) heartbeat: a
+     * worker replaying a long workflow turn beats for its `runId` so the engine rearms the run's
+     * `advance` deadline (see `WorkflowEngineDeps.remoteAdvanceSilenceMs`). The engine then keys the
+     * liveness reset by `runId` instead of `stepId`.
+     */
+    stepId?: string | undefined;
+    group: string;
+}
+/** engine → workflow worker: advance this run one turn by replaying the function against `history`. */
+interface WorkflowTask {
+    /** Dedupe id for this turn (a re-delivered task must be idempotent). */
+    taskId: string;
+    runId: string;
+    /** Registered workflow name + the version the run started on — replay must use that version. */
+    workflow: string;
+    workflowVersion: string;
+    input: unknown;
+    /** Completed durable ops so far, ordered by seq — what the worker replays its results from. */
+    history: HistoryEvent[];
+    /** Signals delivered to the run but not yet consumed, so `wait_signal` resolves on replay. */
+    pendingSignals?: Array<{
+        seq: number;
+        signal: string;
+        payload: unknown;
+    }>;
+    group: string;
+    /** Id of the transport this task was dispatched on (pool failover) — see {@link NamedTransport}. */
+    transport?: string;
+    traceparent?: string;
+    /**
+     * Admission priority carried to the broker (BullMQ job `priority`) so an urgent child workflow can
+     * jump ahead of already-enqueued lower-priority ones at the worker. Higher wins; absent means
+     * default/unprioritised. Transports without priority support ignore it.
+     */
+    priority?: number | undefined;
+    attempt: number;
+}
+/** One resolved durable op in a run's history — a superset of a completed {@link StepCheckpoint}. */
+interface HistoryEvent {
+    seq: number;
+    kind: 'step' | 'call' | 'timer' | 'signal' | 'child';
+    name?: string | undefined;
+    /** Resolved value: a step/call output, a child run's output, a signal payload. */
+    output?: unknown;
+    /** Set when the op resolved to a failure (e.g. a failed remote step the workflow may catch). */
+    error?: StepError | undefined;
+}
+/** 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`. */
+{
+    kind: 'call';
+    seq: number;
+    name: string;
+    group: string;
+    input: unknown;
+    parallelGroup?: string;
+}
+/** `ctx.step(name, body)` — a LOCAL step the worker already ran this turn; the engine persists its
+ *  result so replay returns it instead of re-running (durability for side-effectful work).
+ *  `startedAt`/`finishedAt` (epoch ms) carry the step's real wall-clock window so the dashboard
+ *  shows a true duration instead of 0ms, and `events` carry the sub-process/log trail the step
+ *  emitted (so each handler's p-processes show under it). All optional for back-compat. */
+ | {
+    kind: 'recordStep';
+    seq: number;
+    name: string;
+    output?: unknown;
+    error?: StepError;
+    startedAt?: number;
+    finishedAt?: number;
+    events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` tags every step in the parallel fan with the same group, so the
+     *  engine carries it onto the checkpoint and the dashboard renders the fan as one group. */
+    parallelGroup?: string;
+}
+/** `ctx.sleep(ms)` — a durable timer of `ms` duration. The engine computes the absolute deadline
+ *  (now + ms) when it applies the command, so the worker never reads the clock (determinism). */
+ | {
+    kind: 'sleep';
+    seq: number;
+    ms: number;
+}
+/** `ctx.wait_signal(name)` — block until a signal `name` is delivered to the run. */
+ | {
+    kind: 'waitSignal';
+    seq: number;
+    signal: string;
+}
+/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. A worker's
+ *  `ctx.all([...])` fan-out tags every dispatched child with the same `parallelGroup` so the
+ *  dashboard can render the fan as one group (parity with the gathered `recordStep` tag). */
+ | {
+    kind: 'startChild';
+    seq: number;
+    workflow: string;
+    input: unknown;
+    parallelGroup?: string;
+};
+/** workflow worker → engine: the result of replaying one turn of a remote workflow. */
+interface WorkflowDecision {
+    taskId: string;
+    runId: string;
+    /** `continue` = produced `commands` and is blocked on an await; otherwise the run settles.
+     *  `cancelled` = the worker bailed at an op boundary because the run was cancelled mid-turn. */
+    status: 'continue' | 'completed' | 'failed' | 'cancelled';
+    /** New durable ops the replay produced this turn (status === 'continue'), ordered by seq. */
+    commands: WorkflowCommand[];
+    /** Final workflow output (status === 'completed'). */
+    output?: unknown;
+    /** Terminal error (status === 'failed'). */
+    error?: StepError;
+}
+/**
+ * workflow worker → engine: a LOCAL step's lifecycle, streamed AS IT HAPPENS (not batched into the
+ * turn's final {@link WorkflowDecision}). A Python `@workflow` runs its `ctx.step`s inline over one
+ * turn that can last minutes; without this the engine learns of the steps only when the turn ends,
+ * so the dashboard shows nothing mid-run. The worker emits `running` when a step's body starts and
+ * `completed`/`failed` when it settles; the engine checkpoints each immediately, so a step appears
+ * in-flight and then resolves live. The turn's final `recordStep` command re-persists the same
+ * checkpoint idempotently (replay history), so this is purely additive observability.
+ */
+interface WorkflowStepEvent {
+    runId: string;
+    seq: number;
+    name: string;
+    phase: 'running' | 'completed' | 'failed';
+    /** Epoch ms the step body began (all phases) and settled (`completed`/`failed`). */
+    startedAt: number;
+    finishedAt?: number;
+    /** The replayed result / failure for the settled phases. */
+    output?: unknown;
+    error?: StepError;
+    /** Sub-process + log trail the step emitted so far (the handler's p-processes). */
+    events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` fan tags every step's lifecycle with the same group so the
+     *  dashboard renders the live fan-out as one group (parity with the `recordStep` tag). */
+    parallelGroup?: string | undefined;
+}
+/**
+ * Advances a workflow run one turn. The engine has one per workflow: the default {@link InProcess}
+ * one runs a registered TS function with the in-process replay machinery; a remote one dispatches a
+ * {@link WorkflowTask} to a worker (Python) and awaits its {@link WorkflowDecision}. Either way the
+ * engine applies the returned decision — so recovery, timers, singleton and dead-letter stay engine
+ * concerns, identical for in-process and remote workflows.
+ */
+interface WorkflowExecutor {
+    /**
+     * INLINE replay: advance the turn and RETURN its decision (the in-process executor runs the
+     * registered TS function synchronously). The engine awaits this under the run's lease. Provide this
+     * OR {@link dispatch} — exactly one. An executor with only `advance` is single-instance by nature
+     * (the decision is produced in-process, not delivered over a broker).
+     */
+    advance?(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+    /**
+     * DISPATCH-AND-SUSPEND (broker-backed, multi-instance safe): enqueue the turn to a worker under the
+     * ENGINE-SUPPLIED `taskId`, WITHOUT awaiting the decision. The engine generates `taskId`, records it
+     * on the run as the awaited marker, AND releases the run's lease — all BEFORE calling this — so the
+     * worker's {@link WorkflowDecision} (delivered over {@link Transport.onDecision} and applied DURABLY
+     * by {@link WorkflowEngine.completeRemoteDecision}, which looks the run up by `decision.runId`) can
+     * never arrive ahead of its marker or contend with a still-held lease and be dropped. This method
+     * therefore ONLY enqueues — it owns no taskId generation and returns nothing. No in-memory await, so
+     * the decision is never lost to a point-to-point broker handing it to a non-dispatching instance.
+     * Provide this OR {@link advance} — exactly one.
+     */
+    dispatch?(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
+}
+/**
+ * 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 })`.
+ * The chosen `id` is stamped on the {@link RemoteTask} so a worker replies through the matching one.
+ */
+interface NamedTransport {
+    id: string;
+    transport: Transport;
+}
+/**
+ * Decides where a freshly-`start`ed run executes. `start` creates the run as `pending` and hands its
+ * id here instead of running the body inline — so the API/caller never blocks on workflow execution.
+ * The default in-process dispatcher runs it on this instance (a microtask); a broker-backed one
+ * enqueues the id for a worker pool to consume (`engine.runOne(runId)`); a no-op one leaves it
+ * `pending` in the store for a worker's `runPending` poll to pick up (DB-only, caller-doesn't-execute).
+ */
+interface RunDispatcher {
+    dispatch(runId: string): void | Promise<void>;
+}
+interface Transport {
+    /** engine → worker */
+    dispatch(task: RemoteTask): Promise<void>;
+    /** worker → engine: a step finished (ok or error). */
+    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. */
+    close?(): Promise<void>;
+    /** engine → workflow worker: dispatch a {@link WorkflowTask} (the polyglot-workflow path). Optional
+     *  — only transports that carry workflow tasks (BullMQ) implement it; the {@link RemoteWorkflowExecutor}
+     *  uses it + {@link onDecision} to advance a remote workflow over the broker. */
+    dispatchWorkflowTask?(task: WorkflowTask): Promise<void>;
+    /** workflow worker → engine: a replayed turn's {@link WorkflowDecision}. Pair with dispatchWorkflowTask. */
+    onDecision?(handler: (decision: WorkflowDecision) => Promise<void>): void;
+    /** workflow worker → engine: a LOCAL step's {@link WorkflowStepEvent}, streamed mid-turn so the
+     *  engine can checkpoint it live. Point-to-point (a single engine instance consumes each event and
+     *  persists it once — no cross-pod duplicate writes). Optional; only broker transports carry it. */
+    dispatchStepEvent?(event: WorkflowStepEvent): Promise<void>;
+    /** engine ← workflow worker: consume streamed {@link WorkflowStepEvent}s. Pair with dispatchStepEvent. */
+    onStepEvent?(handler: (event: WorkflowStepEvent) => Promise<void>): void;
+    /** Worker-health for a group: queue backlog + live worker heartbeats. Optional — only broker
+     *  transports (BullMQ) that can introspect the task queue and the worker-heartbeat keys implement
+     *  it. The engine aggregates this across its groups in {@link WorkflowEngine.workerHealth}. */
+    groupHealth?(group: string): Promise<GroupHealth>;
+    /** Distinct groups that currently have a live worker heartbeat — discovered from the heartbeat
+     *  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;
+}
+/** 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). */
+interface WorkerConcurrencyStatus {
+    /** `fixed` = the configured `concurrency` number, never moves. `adaptive` = the controller tunes it. */
+    mode: 'fixed' | 'adaptive';
+    /** The concurrency ceiling in effect right now (fixed: the configured value; adaptive: the live limit). */
+    limit: number;
+    /** Adaptive only — the floor the controller won't go below. */
+    min?: number;
+    /** Adaptive only — the ceiling the controller won't exceed. */
+    max?: number;
+}
+/** The adaptive controller's most recent limit change — the "why did it move" a dashboard shows so an
+ *  auto-tuner isn't a black box. Absent until the controller first adjusts (or for a fixed worker). */
+interface WorkerAdjust {
+    /** Epoch ms of the adjustment. */
+    at: number;
+    /** Limit before this change. */
+    from: number;
+    /** Limit after this change. */
+    to: number;
+    /** Why it moved: `ram_ceiling` (hard brake), `backpressure` (errors/stall), `grow` (had headroom),
+     *  `shrink` (latency gradient showed queuing), `cpu_ceiling`. */
+    reason: 'ram_ceiling' | 'cpu_ceiling' | 'backpressure' | 'grow' | 'shrink';
+}
+/** A live snapshot of a worker's execution state, carried in the worker-liveness heartbeat (so it
+ *  rides the existing TTL'd key — no extra round-trip) and surfaced per worker in the dashboard. Every
+ *  field beyond {@link concurrency}/{@link inFlight} is best-effort: a field a runtime can't measure is
+ *  simply omitted. The shape is shared by the TS and Python SDKs so a mixed-language group reports
+ *  uniformly. */
+interface WorkerStatus {
+    /** Which SDK is running this worker — `node` (TS) or `python`. */
+    runtime?: 'node' | 'python';
+    /** The worker's concurrency knob and its live ceiling. */
+    concurrency: WorkerConcurrencyStatus;
+    /** Tasks executing right now (0..limit). With `limit`, this is the saturation a dashboard charts. */
+    inFlight: number;
+    /** Resident set size in bytes, if the runtime can read it. */
+    rssBytes?: number;
+    /** The process memory ceiling in bytes (cgroup `memory.max`, else host total), if known. */
+    rssLimitBytes?: number;
+    /** RSS as a percent of {@link rssLimitBytes} (0..100) — what the adaptive RAM brake watches. */
+    rssPct?: number;
+    /** Process CPU utilisation percent over the last control tick (0..100×cores), if measured. */
+    cpuPct?: number;
+    /** Completed tasks per minute over the recent window — the controller's throughput signal. */
+    throughputPerMin?: number;
+    /** p95 of recent task durations in ms — the latency a dashboard charts against the limit. */
+    p95Ms?: number;
+    /** The adaptive controller's last limit change (absent for a fixed worker or before the first move). */
+    lastAdjust?: WorkerAdjust;
+}
+/** One worker's liveness record — a TTL'd heartbeat a worker refreshes while it's consuming. Its
+ *  ABSENCE (the key expired) is the signal: a worker that died or stalled stops refreshing. */
+interface WorkerHeartbeat {
+    /** The worker group this instance serves (e.g. `pipeline`, `processing-workflows`). */
+    group: string;
+    /** Stable per-process id (host + pid), so N replicas of a group each show as a distinct worker. */
+    instanceId: string;
+    /** Epoch ms of the worker's most recent heartbeat. */
+    lastBeatAt: number;
+    /** The worker's live execution snapshot, when its heartbeat carries one (newer SDKs stamp a JSON
+     *  value; an older SDK's bare-timestamp heartbeat leaves this undefined). */
+    status?: WorkerStatus;
+}
+/** Per-group worker-health snapshot: how much work is queued vs. how many workers are alive to do it.
+ *  The actionable alert state is `depth > 0 && liveWorkers.length === 0` — work piling up with no
+ *  consumer (exactly the failure where a worker is "alive but not consuming"). */
+interface GroupHealth {
+    group: string;
+    /** Outstanding jobs in the group's task queue (waiting + active + delayed + prioritized). */
+    depth: number;
+    /** Workers with a non-expired heartbeat for this group. */
+    liveWorkers: WorkerHeartbeat[];
+}
+/**
+ * The **control plane** — a broadcast pub/sub across ALL engine instances (every pod), separate
+ * from the {@link Transport}'s point-to-point work queues (`dispatch`/`onResult`). It carries what
+ * every instance may need regardless of who runs a given run: lifecycle events (so a dashboard-only
+ * pod can live-tail a run executing on a worker pod) and cancellation (so the pod actually running a
+ * run learns it was cancelled elsewhere). In-process implementations broadcast locally; a
+ * cross-process one (BullMQ) fans out over its broker (Redis pub/sub). Give the engine a
+ * `controlPlane` to enable cross-instance events/cancellation; omit it and the engine is local-only.
+ * A transport that can broadcast may implement this too and be passed as both.
+ */
+interface ControlPlane {
+    publishControl(msg: ControlMessage): Promise<void>;
+    onControl(handler: (msg: ControlMessage) => void): void;
+}
+/** A message on the {@link ControlPlane}. `from` is the originating engine's `instanceId`, so a
+ *  broker that echoes a publish back to its own subscriber (e.g. Redis pub/sub) can be deduped by
+ *  the originator. */
+type ControlMessage = {
+    from?: string;
+} & ({
+    kind: 'event';
+    event: EngineEvent;
+} | {
+    kind: 'cancel';
+    runId: string;
+} | {
+    kind: 'enqueued';
+    runId: string;
+});
+type BackoffStrategy = 'fixed' | 'exp';
+/**
+ * Options for `ctx.child` / `ctx.startChild`. A bare string passed instead is shorthand for
+ * `{ childId }`, so the existing `ctx.child(ref, input, 'my-id')` form keeps working.
+ */
+interface ChildCallOptions {
+    /** Deterministic child run id; defaults to one derived from the parent run id + call position. */
+    childId?: string | undefined;
+    /**
+     * Dispatch priority for a REMOTE child workflow — stamped on the child run and carried onto every
+     * {@link WorkflowTask} dispatched to advance it, so an urgent child can jump ahead of enqueued
+     * lower-priority ones at the worker. Higher wins; absent = unprioritised. Ignored for an in-process
+     * (TS class) child, which runs in the engine and never hits a broker queue.
+     */
+    priority?: number | undefined;
+}
+interface StepOptions {
+    /** Max attempts before the step (and run) fails. */
+    retries?: number;
+    /** How the delay between retries grows: `fixed` (constant) or `exp` (doubles each attempt). */
+    backoff?: BackoffStrategy;
+    /** 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 **remote** step (`ctx.call`): 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.
+     */
+    timeoutMs?: number;
+    /**
+     * Saga compensation: if this step completes but the run later **fails**, the engine runs the
+     * registered `compensate` callbacks in reverse order (undo what was done). Local steps only.
+     * Idempotency note: a step is already deduplicated by its deterministic `stepId` (runId:seq) —
+     * remote workers can use it as the idempotency key, so there's no separate key option.
+     */
+    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.
+ */
+interface RemoteStepDef<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;
+}
+/**
+ * A durable webhook handle minted by {@link WorkflowCtx.webhook}. Hand `url` to a third party,
+ * then `await wait()` — the run suspends with zero compute until the external system POSTs the
+ * callback (delivered as `engine.signal(token, body)`), and resumes with the body.
+ */
+interface DurableWebhook<TPayload = unknown> {
+    /** Deterministic signal token (`wh:<runId>:<seq>`) the callback delivers on — stable across replay. */
+    readonly token: string;
+    /**
+     * Public callback URL for `token`, built by the engine's `webhookUrl` option. Hand this to the
+     * third party. `undefined` when no builder is configured (use {@link DurableWebhook.token} to
+     * build your own).
+     */
+    readonly url?: string | undefined;
+    /** Suspend until the callback arrives, then resume with its payload. */
+    wait(): Promise<TPayload>;
+}
+/**
+ * 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.
+ */
+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.
+     */
+    step<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): 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
+     * never leave the write done-but-not-checkpointed (which a plain `ctx.step` would re-run). `fn`
+     * receives the store-native transaction handle (`tx` — a TypeORM/MikroORM `EntityManager`, a Prisma
+     * tx client, or a Drizzle tx); do your writes on it. Needs a SQL store that supports transactions
+     * (the bundled SQL adapters do); throws otherwise.
+     */
+    transaction<TOutput>(name: string, fn: (tx: unknown) => Promise<TOutput>): Promise<TOutput>;
+    /**
+     * Call a durable **entity** op and await its result — the entity (`engine.registerEntity`) runs the
+     * op serialized per `key` over durable state. e.g. `await ctx.callEntity('cart', userId, 'add', item)`.
+     */
+    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
+     * across restarts.
+     */
+    sleep(duration: string | number): Promise<void>;
+    /**
+     * Durable sleep until an **absolute** time (a `Date` or epoch ms) — like {@link sleep} but for a
+     * fixed deadline (e.g. "resume at midnight"). Resumes automatically once the time passes, across
+     * restarts. The recorded wake time is fixed on the first run, so it's replay-stable.
+     */
+    sleepUntil(when: Date | number): Promise<void>;
+    /**
+     * End this run and **continue as a fresh execution** of the same workflow with `input` and a clean
+     * history — for long-running / looping workflows that would otherwise accumulate unbounded
+     * checkpoints (and slow replays). The next run gets id `<runId>~N`. Terminal: it always throws, so
+     * code after it never runs. Carry forward whatever state the next iteration needs in `input`.
+     */
+    continueAsNew(input?: unknown): Promise<never>;
+    /**
+     * Suspend the run until an external `engine.signal(token, payload)` arrives (e.g. a webhook or
+     * human approval), then resume with the payload. Waits indefinitely by default — no compute
+     * consumed. Pass `{ timeoutMs }` to bound the wait: if the deadline passes first the call throws
+     * a `SignalTimeoutError` (catch it in the workflow to branch).
+     */
+    waitForSignal<TPayload>(token: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<TPayload>;
+    /**
+     * Wait for a named **event** published via `engine.publishEvent(name, payload)`, then resume with
+     * the payload. Unlike a signal (point-to-point by token), events are name-based pub/sub: pass an
+     * optional `match` (a subset of the payload that must deep-equal) so a publish fans out only to the
+     * runs it concerns — e.g. `ctx.waitForEvent('payment.settled', { match: { orderId } })`. `timeoutMs`
+     * bounds the wait (throws `SignalTimeoutError`). No compute consumed while waiting.
+     */
+    waitForEvent<TPayload>(name: string, opts?: {
+        match?: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<TPayload>;
+    /**
+     * An external task with **async completion**: run `dispatch` once (checkpointed — e.g. send to a
+     * queue, kick off a non-durable worker or a foreign service like a Python process), then suspend
+     * with zero compute until `engine.completeTask(runId, name, result)` (or `failTask`) reports back,
+     * and resume with the result. The durable, first-class counterpart of the hand-rolled
+     * "dispatch over SQS → wait for COMPLETE_PHASE → signal" pattern. `name` must be unique per run.
+     */
+    task<TResult>(name: string, dispatch: () => Promise<void>, options?: StepOptions): Promise<TResult>;
+    /**
+     * Run another registered workflow as a **tracked child** and await its result: starts it once and
+     * suspends — zero compute — until the child reaches a terminal state, then resumes with the child's
+     * output (or throws a FatalError if the child failed). `childId` defaults to a deterministic id
+     * derived from this run and the call position, so it's stable across replay.
+     *
+     * Pass the child's **class** (`ctx.child(ShippingWorkflow, input)`) for a typed input + result; pass
+     * a **string** name for a cross-runtime child (e.g. a Python workflow) where there's no class.
+     */
+    child<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, options?: string | ChildCallOptions): Promise<WorkflowOutputOf<C>>;
+    child<TOutput>(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<TOutput>;
+    /**
+     * Start a child workflow **fire-and-forget**: dispatches it once (checkpointed, replay-safe) and
+     * returns its run id immediately — the parent keeps running instead of suspending. Use it to kick
+     * off side work (an audit log, a notification) you don't need to wait on, or to fan out: collect
+     * the ids, then later `await ctx.child(...)` each with the same id to join (the start is idempotent
+     * by id, so the child runs exactly once). Class or string ref, like {@link child}.
+     */
+    startChild<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, options?: string | ChildCallOptions): Promise<string>;
+    startChild(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<string>;
+    /**
+     * Run N children of the SAME workflow **in parallel** and wait for ALL of them: dispatches one
+     * child per entry in `inputs` (concurrently, each with its own durable lifecycle), suspends — zero
+     * compute — until every child reaches a terminal state, then resumes with their outputs in **input
+     * order**. Child ids are group-scoped and stable (`<runId>.all.<firstSeq>.<i>`), and the running
+     * placeholders share a `parallelGroup` tag so the dashboard renders the fan-out as one group.
+     *
+     * `mode` (default `waitAll`): `waitAll` waits for all then throws an aggregate {@link GatherError}
+     * if any failed; `failFast` throws as soon as a failed child is seen (siblings are not cancelled in
+     * v1 — their eventual results are ignored). Empty `inputs` returns `[]` with no side effects. The
+     * wait-all / fan-out counterpart to {@link child}; parity with the Python SDK's `gather_children`.
+     */
+    all<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<WorkflowOutputOf<C>[]>;
+    all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<TOutput[]>;
+    /**
+     * Pause the run at this point until a human resumes it from the dashboard (or
+     * `engine.continue(runId)`). Records a visible `pending` checkpoint so the breakpoint shows up
+     * in the timeline, then suspends with zero compute — the durable equivalent of a debugger
+     * breakpoint. Gate it on your own config to make breakpoints opt-in per run:
+     * `if (cfg.breakAfterExtraction) await ctx.breakpoint('after-extraction')`.
+     */
+    breakpoint(label?: string): Promise<void>;
+    /**
+     * Mint a durable webhook: returns a handle with a deterministic `token` and (if the engine has a
+     * `webhookUrl` builder) a public `url`. Hand the url to a third party — inside a `ctx.step` — then
+     * `await handle.wait()` to suspend with zero compute until they POST the callback (the dashboard
+     * turns that POST into `engine.signal(token, body)`). The first-class, replay-safe version of
+     * "expose a callback URL and wait for it".
+     */
+    webhook<TPayload>(): DurableWebhook<TPayload>;
+    /**
+     * Publish a named, queryable value from inside the run — the latest value for `key` is readable
+     * externally via `engine.getEvent(runId, key)` while the run is still in flight (progress, a
+     * partial result, a status). Checkpointed and replay-safe (overwrites the previous value for the
+     * same key). The read side has no effect on the run — the durable, suspend-model counterpart of a
+     * Temporal query.
+     */
+    setEvent<TValue>(key: string, value: TValue): Promise<void>;
+    /**
+     * Expose a named **update point**: suspend until an external `engine.update(runId, name, arg)`
+     * delivers `arg`, then resume with it. The update is run-scoped (`name` need only be unique within
+     * the run) and gated by any validator registered via `engine.registerUpdateValidator` — a rejected
+     * update never reaches here. Pass `{ timeoutMs }` to bound the wait (throws `SignalTimeoutError`).
+     * The durable counterpart of a Temporal update handler.
+     */
+    onUpdate<TArg>(name: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<TArg>;
+    /**
+     * Guard an in-place workflow change without a new version. Wrap the changed code in
+     * `if (await ctx.patched('my-change')) { …new… } else { …old… }`: a fresh run records a marker and
+     * takes the new branch (`true`); a run already recorded under the old code keeps the old branch
+     * (`false`), because its history has a real step where the marker would sit. The marker is
+     * position-transparent for old runs (it doesn't shift their recorded steps), so guarding code is
+     * replay-safe. Once every old run has drained, remove the guard (keep the new branch).
+     */
+    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.
+     */
+    now(): Promise<number>;
+    /**
+     * Deterministic random in `[0, 1)`: recorded once, then replayed. Use instead of `Math.random()`
+     * (same replay-safety reason as {@link now}).
+     */
+    random(): Promise<number>;
+    /** Deterministic UUID v4: recorded once, then replayed. Use instead of `crypto.randomUUID()`. */
+    uuid(): Promise<string>;
+    /**
+     * 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 +
+     * exactly-once — recorded at this position on the first run and SKIPPED on replay, so it does one
+     * write, not one per turn. Use this instead of injecting the {@link StateStore} to mutate the run
+     * you're executing (`@Inject(state-store)` + `store.updateRun(ctx.runId, …)` becomes
+     * `ctx.upsertSearchAttributes(…)`).
+     */
+    upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
+}
+/** Result of executing or resuming a workflow run. */
+interface RunResult {
+    runId: string;
+    status: RunStatus;
+    output?: unknown;
+    error?: StepError | undefined;
+}
+/**
+ * Validates an incoming `engine.update` before it is delivered to the run. Throw (or return a
+ * non-empty string) to reject — the run is left untouched. Return nothing/void to accept. May be
+ * async (e.g. a business-rule check against a DB).
+ */
+type UpdateValidator<TArg = unknown> = (arg: TArg) => void | string | Promise<void | string>;
+/** Outcome of `engine.update`: rejected by the validator, or accepted and delivered. */
+type UpdateResult = {
+    accepted: false;
+    reason: string;
+} | {
+    accepted: true;
+    run: RunResult | null;
+};
+type EngineEventType = 'run.started' | 'run.completed' | 'run.failed' | 'run.suspended' | 'step.started' | 'step.completed' | 'step.failed' | 'step.progress';
+/**
+ * A lifecycle event emitted by the engine. The observability surfaces (dashboard, OTel, the
+ * Telescope integration) all subscribe to these rather than reaching into the store.
+ */
+interface EngineEvent {
+    type: EngineEventType;
+    runId: string;
+    workflow?: string | undefined;
+    seq?: number | undefined;
+    name?: string | undefined;
+    kind?: StepKind | undefined;
+    output?: unknown;
+    error?: StepError | undefined;
+    /** Wall-clock duration of the unit that just finished (step or run), when known. */
+    durationMs?: number | undefined;
+    /** For a remote step: how long it waited in the queue before a worker picked it up. */
+    queueMs?: number | undefined;
+    /** The live step event carried by a `step.progress` (the single log line / sub-process outcome a
+     *  running step just emitted). Absent on lifecycle events. */
+    event?: StepEvent | undefined;
+    at: Date;
+}
+type EngineListener = (event: EngineEvent) => void;
+/** What a {@link StepInterceptor} is told about the local step it is wrapping. */
+interface StepInvocation {
+    readonly runId: string;
+    readonly workflow: string;
+    /** The step name passed to `ctx.step(name, ...)` (also `'now'`/`'random'`/`'uuid'` internals). */
+    readonly stepName: string;
+    /** The step's logical position within the run. */
+    readonly seq: number;
+    /** 1-based attempt number — increments across `ctx.step` retries. */
+    readonly attempt: number;
+}
+/**
+ * Wraps the **real execution** of a local `ctx.step` (Template/Nest-style onion middleware). Call
+ * `next()` to run the step body (or the next interceptor) and return — or transform — its result;
+ * throw to fail the step. First-registered runs outermost. Interceptors fire only when a step
+ * actually executes, NOT on replay (a replayed step returns its recorded output without running),
+ * so they see true execution timing. Register with `engine.use`.
+ */
+type StepInterceptor = (invocation: StepInvocation, next: () => Promise<unknown>) => Promise<unknown>;
+
+/** 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. */
+interface EntityConfig<S = unknown> {
+    /** Build the initial state for a fresh key. */
+    initialState: () => S;
+    /** Operation handlers, keyed by op name. Each runs serially per key, exactly once. */
+    handlers: Record<string, EntityHandler<S>>;
+}
+/** 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;
+    signalWithStart(workflow: string, input: unknown, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }): Promise<{
+        runId: string;
+    }>;
+    getEvent<T>(runId: string, key: string): Promise<T | undefined>;
+    signal(token: string, payload: unknown): Promise<unknown>;
+}
+/**
+ * Durable keyed **entities** (virtual objects): a keyed actor whose handlers run **serialized per
+ * key** over **durable state**, exactly once. Each key is one long-lived run (`entity:<name>:<key>`)
+ * processing ops in order. Drive it with `signal` (fire) or `ctx.callEntity` (call + await result),
+ * read state with `getState`. Registers its built-in runner on construction.
+ */
+declare class Entities {
+    private readonly host;
+    private readonly configs;
+    constructor(host: EntityHost);
+    register<S>(name: string, config: EntityConfig<S>): void;
+    /** Deliver an op to an entity's runner, starting it on first contact. `reply` (a signal token)
+     *  receives the handler's result, for `ctx.callEntity`. */
+    dispatch(name: string, key: string, op: string, arg: unknown, reply?: string): Promise<{
+        runId: string;
+    }>;
+    signal(name: string, key: string, op: string, arg?: unknown): Promise<void>;
+    getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
+    /** The built-in runner: one long-lived run per key, processing ops serially over state. */
+    private run;
+}
+
+/** How `onEvent` triggers are coalesced into fewer runs (see `@Workflow({ debounce | batch })`). */
+type EventBatchConfig = {
+    mode: 'debounce';
+    windowMs: number;
+} | {
+    mode: 'batch';
+    maxSize: number;
+    windowMs: number;
+};
+/** The slice of the engine the accumulators need (so they stay a standalone module). */
+interface AccumulatorHost {
+    register(name: string, version: string, fn: (ctx: WorkflowCtx, input: unknown) => Promise<unknown>): void;
+    signalWithStart(workflow: string, input: unknown, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }): Promise<{
+        runId: string;
+    }>;
+}
+/**
+ * Built-in workflows that coalesce `onEvent` triggers. Each is a long-lived per-target accumulator
+ * fed by `signalWithStart`: it collects payloads then starts the target once, and `continueAsNew`s to
+ * re-arm for the next burst. Signal buffering keeps the re-arm race-free. Registers its runners on
+ * construction.
+ */
+declare class EventAccumulators {
+    private readonly host;
+    constructor(host: AccumulatorHost);
+    /** Route an `onEvent` payload into its target's debounce/batch accumulator. */
+    route(target: string, config: EventBatchConfig, payload: unknown): Promise<{
+        runId: string;
+    }>;
+    /** Fire the target with the LAST payload once events have been quiet for `windowMs`. */
+    private debounce;
+    /** Fire the target with all payloads (`{ events }`) once `maxSize` or `windowMs` from the first. */
+    private batch;
+}
+
+type WorkflowFn = (ctx: WorkflowCtx, 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. */
+    tags?: string[] | undefined;
+    /** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
+    searchAttributes?: SearchAttributes | undefined;
+    /**
+     * Dispatch priority for a remote run — stamped on the run and carried onto every {@link WorkflowTask}
+     * 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).
+ * Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
+ * admission on a timer until a slot frees. Race-free on a consistent store (admission order is the
+ * same `(createdAt, id)` view for every instance).
+ */
+interface SingletonConfig {
+    /** Derive the serialization key from the workflow input. */
+    key: (input: unknown) => string;
+    /** Max concurrent runs sharing the key. Default 1 (a mutex). */
+    limit?: number;
+    /**
+     * Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
+     * set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
+     * `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
+     * default unbounded queue. Counts `pending`/`running`/`suspended` runs sharing the key.
+     */
+    maxQueueDepth?: number;
+}
+interface WorkflowEngineDeps {
+    store: StateStore;
+    /** A single task transport. Shorthand for a one-entry `transports` pool (id `default`). */
+    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
+     * this instead of `transport` for failover / multi-broker setups.
+     */
+    transports?: NamedTransport[] | undefined;
+    /**
+     * Cross-instance broadcast pub/sub for lifecycle events + cancellation (see {@link ControlPlane}).
+     * Separate from the task `transport`; omit for a single-instance / local-only setup. A transport
+     * that can also broadcast may be passed here as well.
+     */
+    controlPlane?: ControlPlane | undefined;
+    /** 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
+     * {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
+     * concurrency / rate-limit / ordering GLOBAL across engine replicas.
+     */
+    admission?: AdmissionBackend | undefined;
+    /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
+    instanceId?: string | undefined;
+    /**
+     * 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. 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. */
+    leaseMs?: number | undefined;
+    /**
+     * Cap how many times crash-recovery may pick up the same still-`running` run before giving up and
+     * moving it to the `dead` dead-letter state (a poison pill that crashes the process every boot).
+     * Omit for unlimited (the default — recovery always retries).
+     */
+    maxRecoveryAttempts?: number | undefined;
+    /**
+     * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
+     * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
+     * it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
+     * re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
+     * legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
+     * side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
+     * for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
+     * ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
+     * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
+     */
+    remoteAdvanceSilenceMs?: number | undefined;
+    /**
+     * Build the public callback URL for a `ctx.webhook()` token (e.g.
+     * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
+     * {@link DurableWebhook.url}. Omit if you build URLs yourself from the token.
+     */
+    webhookUrl?: ((token: string) => string) | undefined;
+    /**
+     * Provide the current W3C `traceparent` to stamp on each dispatched {@link RemoteTask}, so a
+     * worker (including the Python SDK) continues the distributed trace. Keep core OTel-free: supply
+     * `otelTraceparent` from `@dudousxd/nestjs-durable-otel`, or your own context reader. Omit to send none.
+     */
+    traceparent?: (() => string | undefined) | undefined;
+    /**
+     * Provide an opaque context carrier (tenant / user / correlation ids) to attach to each dispatched
+     * {@link RemoteTask} as its `context`, so a worker (including the Python SDK) re-exposes it to the
+     * step handler — cross-process propagation alongside the {@link traceparent}. Keep core dependency-free:
+     * supply this from `@dudousxd/nestjs-context` or your own request-scoped reader. The engine never
+     * inspects the returned object's shape. Omit to send none.
+     *
+     * Re-evaluated at each (re)dispatch — including a retry or a resume that the engine drives AFTER a
+     * crash/scale-down, which runs OUTSIDE the originating request scope. On such a path this provider
+     * may return empty or stale values (the request-scoped tenant/user is gone). Treat the carrier as
+     * best-effort correlation/propagation metadata only — do NOT treat it as an authorization boundary.
+     */
+    context?: (() => Record<string, unknown> | undefined) | undefined;
+    /**
+     * Re-hydrate the originating context around a LOCAL step body, so a `@DurableStep` reader sees the
+     * tenant / user / correlation ids that were live when the run was started — even on a path the
+     * engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
+     * Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
+     * runs `fn` with that context ambiently established (e.g. inside `@dudousxd/nestjs-context`'s ALS)
+     * and returns its result. Keep core dependency-free: supply this from the nestjs wiring (which owns
+     * nestjs-context) or your own ALS bridge. The handler signature is unchanged — re-hydration is
+     * ambient. Default: passthrough (`(_, fn) => fn()`), so behavior is byte-identical when unset.
+     */
+    rehydrate?: (<T>(carrier: Record<string, unknown> | undefined, fn: () => T) => T) | undefined;
+    /**
+     * Attempts for each saga compensation when the run fails (a transient undo — e.g. a refund API
+     * hiccup — gets another try). Default 1 (no retry). Compensations must be idempotent.
+     */
+    compensationRetries?: number | undefined;
+    /**
+     * Persist a `running` checkpoint when a local step's body begins, so an in-flight step shows up
+     * in the dashboard (and a fresh page load / REST query) the moment it starts — not only once it
+     * completes. The `step.started` lifecycle event is emitted either way (the live SSE view always
+     * sees the start); this flag only controls the extra checkpoint write. Default `true`. Set
+     * `false` on hot paths with many short local steps to halve their checkpoint writes — you keep
+     * the live event but lose reload-survivable in-flight visibility.
+     */
+    trackStepStart?: boolean | undefined;
+    /**
+     * Where a freshly-`start`ed run executes (see {@link RunDispatcher}). Defaults to in-process: the
+     * run executes on this instance asynchronously (a microtask), so `start` returns without blocking.
+     * Pass a no-op dispatcher on a caller that must NOT run workflows (e.g. an API/dashboard pod), and
+     * run `runPending` on a worker pod to pick those up; or a broker-backed one for a worker pool.
+     */
+    runDispatcher?: RunDispatcher | undefined;
+    /**
+     * When `true`, the engine routes an unregistered workflow to the live worker group of the SAME
+     * name: if the transport reports a live heartbeat for group `"processing"` and no local
+     * `register`/`registerRemote` exists for that name, a `start`/`resume` for it is dispatched to
+     * that group over the primary transport — no `engine.remote()` boilerplate needed. Default `false`
+     * (opt-in; existing behavior is unchanged). Requires a transport that implements
+     * `listWorkerGroups` (e.g. BullMQ); when the transport has none, or the group is not live, the
+     * existing "not registered" error is still thrown.
+     */
+    remoteByConvention?: boolean | undefined;
+}
+/**
+ * The orchestrator. Owns workflow state and replays runs deterministically: each step's
+ * result is checkpointed, so on resume a completed step returns its saved output instead of
+ * re-executing. Remote steps are dispatched over the Transport; their results checkpoint the
+ * same way local steps do.
+ */
+declare class WorkflowEngine {
+    private readonly store;
+    /** Ordered transport pool (dispatch + failover). Empty = no remote steps. */
+    private readonly pool;
+    private readonly controlPlane?;
+    private readonly clock;
+    private readonly instanceId;
+    private readonly namespace;
+    private readonly leaseMs;
+    private readonly maxRecoveryAttempts?;
+    private readonly remoteAdvanceSilenceMs?;
+    private readonly webhookUrl?;
+    private readonly traceparent?;
+    private readonly context?;
+    /** Establish the originating context ambiently around a local step body (see {@link WorkflowEngineDeps.rehydrate}). Default passthrough. */
+    private readonly rehydrate;
+    private readonly compensationRetries;
+    /** Persist a `running` checkpoint at the start of a local step body (see {@link WorkflowEngineDeps.trackStepStart}). */
+    private readonly trackStepStart;
+    /** Where a freshly-started run executes — in-process by default (see {@link RunDispatcher}). */
+    private readonly runDispatcher;
+    /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
+    private readonly singletons;
+    /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
+    private readonly workflows;
+    /** The newest registered version per workflow name — used to `start` new runs. */
+    private readonly latest;
+    /** Event name → workflow names started when that event is published (see `onEvent`). */
+    private readonly eventTriggers;
+    /** Durable-entity subsystem (registers the `__entity` runner; see `registerEntity`). */
+    private readonly entities;
+    /** Event debounce/batch accumulators (register the `__evt_*` runners; see `accumulators.route`). */
+    private readonly accumulators;
+    /** In-flight remote steps awaiting a worker result, keyed by stepId. */
+    private readonly pending;
+    /** "Reset the liveness timer" callbacks keyed by the beat's target — a stepId (in-flight remote step)
+     *  or a runId (in-flight remote workflow turn) — invoked when a matching heartbeat arrives. The two id
+     *  shapes don't collide in practice: a stepId is `${runId}:${seq}`, a run key is the bare runId. */
+    private readonly heartbeatResets;
+    private readonly listeners;
+    /** Step interceptors (onion middleware around real local-step execution), first = outermost. */
+    private readonly interceptors;
+    /** Callbacks notified (on any instance) when a run is cancelled — for cooperative cancellation. */
+    private readonly cancelListeners;
+    /** Callbacks notified when a run is enqueued elsewhere — for low-latency cross-pod dispatch. */
+    private readonly enqueuedListeners;
+    /** Notified when a run is dead-lettered (moved to `dead`) — a hook for a DLQ handler. */
+    private readonly deadListeners;
+    /** Validators gating `engine.update`, keyed by `<workflow>:<updateName>`. */
+    private readonly updateValidators;
+    /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
+    private readonly cancelRequested;
+    /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
+    private readonly admission;
+    /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
+    private readonly queueWaiters;
+    /** Which queue a dispatched step took a slot from, by stepId — so the result can release it. */
+    private readonly stepQueue;
+    /** Executions currently in flight, so a graceful shutdown can wait for them to settle. */
+    private readonly inflight;
+    private draining;
+    /** When true, route an unregistered workflow to the live worker group of the same name. */
+    private readonly remoteByConvention;
+    constructor(deps: WorkflowEngineDeps);
+    /**
+     * Register a **durable entity** (a virtual object): a keyed actor whose `handlers` run **serialized
+     * per key** over **durable state**, exactly once. Drive it with `signalEntity` (fire) /
+     * `ctx.callEntity` (call + await result) and read its state with `getEntityState`. See {@link Entities}.
+     */
+    registerEntity<S>(name: string, config: EntityConfig<S>): void;
+    /** Send an operation to an entity (fire-and-forget). Ordered + exactly-once per key. */
+    signalEntity(name: string, key: string, op: string, arg?: unknown): Promise<void>;
+    /** Read an entity's current durable state (published after each op), or undefined if it has none yet. */
+    getEntityState<S = unknown>(name: string, key: string): Promise<S | undefined>;
+    /**
+     * Be notified when a run is enqueued on ANOTHER instance (via the control plane), so a worker can
+     * pick it up at once — e.g. `engine.onEnqueued((runId) => engine.runOne(runId))`. Returns an
+     * unsubscribe function. Only wire this on instances that should execute runs (workers).
+     */
+    onEnqueued(listener: (runId: string) => void): () => void;
+    /** Fire cooperative-cancellation listeners for `runId` (a worker bridge aborts in-flight work). */
+    private notifyCancelled;
+    /**
+     * Register a workflow version. Register multiple versions of the same name to keep in-flight
+     * runs working across a breaking change: old runs resume on the version they started on, new
+     * runs start on the newest registered version.
+     *
+     * GROUP-SERVED (uniform dispatch, opt-in): pass `{ group, executor }` to have the engine DISPATCH
+     * this workflow's turns to a worker `group` (via `executor.advance`) instead of running `fn`
+     * inline — exactly as {@link registerRemote} does for a cross-SDK (e.g. Python) body, EXCEPT the
+     * body is a TS `fn` the engine retains so an IN-APP worker on `group` can fetch it by name
+     * ({@link workflowBody}) and run it. This is "one app, both roles": the same process owns the
+     * engine AND consumes its own group. Recovery, timers, singleton, cancel and dead-lettering stay
+     * engine concerns, identical to a remote run. OMIT `group`/`executor` (the default) to keep the
+     * inline fast path — `fn` runs in-process and the run pays zero dispatch round-trips. The first
+     * step toward routing every run through a group with no local/remote flag (Phase 3).
+     */
+    register(name: string, version: string, fn: WorkflowFn, opts?: {
+        tags?: string[] | undefined;
+        singleton?: SingletonConfig | undefined;
+        executionTimeout?: string | number | undefined;
+        validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+        onEvent?: string[] | undefined;
+        eventBatch?: EventBatchConfig | undefined;
+        /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
+         *  Omit for the default inline fast path. See the method doc. */
+        group?: string | undefined;
+        /** Advances a turn by dispatching a {@link WorkflowTask} to `group`. Requires `group`. For an
+         *  in-app worker, pair a transport-backed {@link RemoteWorkflowExecutor} (group consumed by a
+         *  worker that calls {@link workflowBody}) so the retained `fn` runs through the transport hop. */
+        executor?: WorkflowExecutor | undefined;
+    }): void;
+    /**
+     * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
+     * own group to SERVE a group-served `register(..., { group, executor })` workflow (uniform dispatch):
+     * the worker fetches the body by name when it picks up the dispatched {@link WorkflowTask}, replays
+     * it, and returns the {@link WorkflowDecision}. `undefined` for an unregistered name or a body-less
+     * remote (a `registerRemote` / synthesized child carries only a throwing stub, never handed out).
+     */
+    workflowBody(name: string, version: string): WorkflowFn | undefined;
+    /**
+     * Register a workflow whose body runs in another SDK (e.g. Python). The engine owns the run exactly
+     * as for a TS workflow — it persists checkpoints, recovers, runs timers — but advances it by handing
+     * the run's history to `executor` (which dispatches a {@link WorkflowTask} to the worker) and applying
+     * the {@link WorkflowDecision} the worker's replay returns. The worker never touches the store.
+     */
+    registerRemote(name: string, version: string, opts: {
+        group: string;
+        executor: WorkflowExecutor;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
+    /**
+     * Register a flow-control queue referenced by `ctx.call(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.
+     */
+    registerQueue(config: QueueConfig): void;
+    /** Subscribe to lifecycle events. Returns an unsubscribe function. */
+    subscribe(listener: EngineListener): () => void;
+    /**
+     * Register a {@link StepInterceptor} — onion middleware run around the real execution of every
+     * local `ctx.step` (timing, logging, tracing, error enrichment, context propagation). First
+     * registered is outermost; interceptors fire only when a step executes, never on replay. Returns
+     * an unsubscribe function.
+     */
+    use(interceptor: StepInterceptor): () => void;
+    /**
+     * Fold the registered interceptors around a local step body (identity when there are none), then
+     * run the whole thing inside the re-hydrated originating context. The carrier is read at execution
+     * time from {@link context} — the SAME reader stamped on dispatched remote tasks — so a local step
+     * sees the live tenant / user / trace ids ambiently (via the {@link rehydrate} bridge). Default
+     * `rehydrate` is a passthrough, so this is byte-identical to a bare body call when unwired.
+     */
+    private interceptStep;
+    /**
+     * Be notified when a run is cancelled — on ANY instance, via the transport control plane. A
+     * worker bridge can use this for cooperative cancellation: abort the in-flight work for `runId`
+     * instead of finishing it just to have the result discarded. Returns an unsubscribe function.
+     */
+    onCancel(listener: (runId: string) => void): () => void;
+    /**
+     * Be notified when a run is **dead-lettered** — moved to `dead` after exceeding
+     * `maxRecoveryAttempts`. The listener receives the dead run (status `dead`, with its error), so a
+     * DLQ handler can do something other than just leaving it parked: alert, push to a real queue, or
+     * start a dead-letter workflow (e.g. `engine.onDead((run) => engine.start('pipeline-dlq', run, ...))`).
+     * Returns an unsubscribe function.
+     */
+    onDead(listener: (run: WorkflowRun) => void): () => void;
+    private notifyDead;
+    /** Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the
+     *  control plane so other instances (e.g. a dashboard pod) can live-tail this run. */
+    private emit;
+    /** Deliver an event to local subscribers only (no re-broadcast) — used for both locally-produced
+     *  events and ones received from the control plane, so an event shows up once on every instance. */
+    private deliver;
+    start<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, runId: string, opts?: StartOptions): Promise<RunResult>;
+    start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
+    /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    resume(runId: string): Promise<RunResult>;
+    /**
+     * The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
+     * `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
+     * flat registry FIRST (so an explicit `registerRemote(name, …)` ALWAYS wins, and a registered run
+     * never reaches here); this resolves only the new case: a child spawned by a remote workflow (e.g. a
+     * Python `gather_children` / `start_child` fan-out) of a name the host never `registerRemote`-ed. It
+     * is driven as a remote run on the ancestor's group + the SAME executor instance, so the host needs
+     * no redundant registration per child name.
+     *
+     * RECOMPUTED per resume rather than memoized into `this.workflows`: a synthesized child is not a real
+     * registration and must not leak into `latest`, `knownGroups`, or `sweepTimeouts` (which iterate the
+     * registry); recomputing also stays correct if the ancestor's remote registration is re-pointed at a
+     * new executor across a deploy. Only unregistered runs pay it, so registered workflows pay nothing.
+     */
+    private findInheritedRegistration;
+    /**
+     * A throwaway {@link RegisteredWorkflow} that routes `name@version` as a remote run on the ancestor's
+     * group via the ancestor's SAME executor instance. The executor is group-scoped (it dispatches a
+     * {@link WorkflowTask} carrying `run.workflow`, and the worker picks the body by name), so reusing it
+     * is correct AND required — a second executor on the same group would race the worker for results.
+     * Only `remote` is inherited; the child gets none of the ancestor's singleton/timeout/validator, so
+     * its identity stays its own.
+     */
+    private synthesizeRemoteChild;
+    /**
+     * When `remoteByConvention` is enabled, 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 flag is off or the group is not live.
+     *
+     * 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
+     * live `child:<childId>` signal waiter — present for as long as the parent is suspended awaiting the
+     * child, i.e. throughout the child's executable lifetime (start, every resume, crash recovery, cancel
+     * cascade), which is exactly when we resolve. A registered-but-LOCAL parent stops the walk (an
+     * unregistered child of a TS workflow is a genuine misconfiguration → skew error); only an
+     * unregistered parent keeps walking, so a child of an inherited child still reaches the remote root.
+     * `visited` guards against a pathological cyclic id graph.
+     */
+    private findRemoteAncestor;
+    /**
+     * The run that spawned `childRunId`, via its live `child:<childRunId>` signal waiter — every awaited
+     * child (`ctx.child`, `ctx.all`, a remote `start_child`) suspends its parent on exactly this waiter,
+     * and the waiter is written BEFORE the child is started. Only reached for an UNREGISTERED child, so
+     * registered runs never pay the scan; returns `undefined` once the parent has settled the child (the
+     * waiter is consumed), but by then the child is terminal and no longer resolved.
+     */
+    private findParentRunId;
+    /** Track an in-flight execution so {@link drain} can wait for it. */
+    private track;
+    /**
+     * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
+     * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
+     * deploy hands off cleanly instead of leaving runs to the lease timeout.
+     */
+    drain(timeoutMs?: number): Promise<void>;
+    /**
+     * Cancel in-flight runs that have outlived their workflow's `executionTimeout`. Call it from the
+     * timer poller alongside {@link resumeDueTimers}. A timed-out run is moved to `cancelled` with an
+     * `execution_timeout` error (terminal, so a late step result can't resurrect it).
+     */
+    sweepTimeouts(now?: number): Promise<void>;
+    /**
+     * Resume every run left incomplete by a crash or deploy. Called on boot. Completed steps
+     * replay from their checkpoints, so only the work that had not finished runs again.
+     */
+    recoverIncomplete(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Per-recovery bookkeeping (called once the lease is held): count the attempt, or — past
+     * `maxRecoveryAttempts` — move a poison pill to the `dead` dead-letter state. Returns a terminal
+     * result to skip the resume, or `undefined` to proceed.
+     */
+    private countRecovery;
+    /**
+     * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
+     * boot. A run still not due re-suspends cheaply without running new work.
+     */
+    resumeDueTimers(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Lease and execute one run by id — the worker side of dispatch. Acquires the recovery lease (so
+     * exactly one instance runs it), then resumes the body. Returns the result, or null if another
+     * instance holds the lease or the engine is draining. The default in-process dispatcher calls this;
+     * a broker-backed worker calls it per consumed run id.
+     */
+    runOne(runId: string): Promise<RunResult | null>;
+    /**
+     * Re-enqueue a run for a worker to (re-)execute — the dispatch-model **retry**. Sets it back to
+     * `pending`, clears any stale lease, and dispatches; a worker resumes it (replaying its checkpoints,
+     * re-attempting the failed step). Returns the enqueued state immediately — never runs the body
+     * inline — or null if the run is unknown. The dashboard "retry" goes through here so it can't block
+     * the HTTP request on workflow execution.
+     */
+    requeue(runId: string): Promise<RunResult | null>;
+    /**
+     * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
+     * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
+     * the original stays inspectable. Returns the new run's id, or null if `runId` is unknown.
+     */
+    retryWithInput(runId: string, input: unknown, newRunId?: string): Promise<{
+        runId: string;
+    } | null>;
+    /**
+     * Pick up and execute every `pending` run — the poll-based side of dispatch for a worker pod with
+     * no broker. Runs enqueued by other pods (or by a caller using a no-op dispatcher) sit `pending`
+     * in the store until polled; leasing ensures exactly one pod runs each. Call periodically alongside
+     * {@link resumeDueTimers}.
+     */
+    runPending(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Resolve once `runId` reaches a settled state — terminal (completed/failed/cancelled/dead) or
+     * suspended (handed off to a timer/signal/event). The async counterpart to dispatch: pair it with
+     * `start` when a call site needs the outcome — `await start(...); const r = await waitForRun(id)`.
+     */
+    waitForRun(runId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Resume each run only if this instance can acquire its recovery lease — so when several
+     * replicas recover or poll at once, each run is picked up by exactly one of them.
+     */
+    private resumeLeased;
+    /**
+     * Deliver an external signal to the run waiting on `token` and resume it with `payload`.
+     * Returns the run result, or null if no run is waiting for that token.
+     */
+    /**
+     * Publish a named event. It does two things, and returns how many runs it touched (the sum):
+     *  1. **Resumes** every in-flight run waiting on it via `ctx.waitForEvent(name, { match })` whose
+     *     match the payload satisfies (fan-out, vs `signal`'s point-to-point token).
+     *  2. **Starts** a fresh run of every workflow registered with `onEvent: [name]`, passing the
+     *     payload as input. Idempotent by `evt:<id>:<workflow>` — pass `opts.id` to dedupe redeliveries
+     *     of the same logical event (default: a fresh uuid, so each publish triggers once).
+     */
+    publishEvent(name: string, payload: unknown, opts?: {
+        id?: string;
+    }): Promise<number>;
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
+    /**
+     * Ensure a run exists for `runId`, then deliver a signal to it — atomically race-free thanks to
+     * signal buffering: if the run is new (or busy / not yet waiting), the signal is buffered and
+     * consumed when it reaches `waitForSignal(token)`. The canonical **durable-entity / accumulator**
+     * pattern: one long-lived run per key (the `runId`) that loops on `waitForSignal`, fed events by
+     * many `signalWithStart` calls. `start` is idempotent by `runId`, so concurrent callers converge on
+     * one run. (Use a per-run `token`, e.g. derived from `runId`, so the signal targets this entity.)
+     */
+    signalWithStart(workflow: WorkflowRef, input: unknown, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }, opts?: StartOptions): Promise<{
+        runId: string;
+    }>;
+    /**
+     * Report the result of a `ctx.task(name, …)` back to its run (async completion). The external
+     * worker that the task dispatched to calls this when done; the run resumes with `result`. Returns
+     * null if no run is waiting on the task (e.g. a duplicate/late delivery) — a safe no-op.
+     */
+    completeTask(runId: string, name: string, result: unknown): Promise<RunResult | null>;
+    /** Report that a `ctx.task` failed — the run resumes and throws a FatalError at the task. */
+    failTask(runId: string, name: string, error: string): Promise<RunResult | null>;
+    /**
+     * Notify a parent that's waiting on `runId` as a child of its terminal outcome (the `ctx.child`
+     * rendezvous). A no-op when no parent is waiting, so `execute()` can call it on every run without
+     * knowing about the child feature.
+     */
+    private notifyParent;
+    /**
+     * Cancel a run (e.g. from the dashboard). Returns null if the run does not exist. Pass
+     * `{ compensate: true }` to undo the saga first: the suspended run is resumed so its completed
+     * steps' compensations run in reverse (visible as `compensate:<step>` events), then it's marked
+     * cancelled. Without it, cancellation is immediate (no undo).
+     */
+    cancel(runId: string, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult | null>;
+    /**
+     * Bulk-cancel every run matching a filter — e.g. cancel all `order` runs tagged `vip`, or every run
+     * whose `tier` search attribute is `free`. The filter is a {@link RunQuery} (workflow / status / tag
+     * / search-attribute predicates), so it reuses the same matching the dashboard list uses. Each match
+     * is run through {@link cancel}, so the same plumbing applies per run: child cascade, the optional
+     * saga `compensate`, local cancel listeners, and the control-plane broadcast that tells the owning
+     * worker to abort. Returns one {@link RunResult} per matched run (already-finished matches report
+     * their terminal status — `cancel` is a no-op on them, never clobbering a completed/dead run).
+     */
+    cancelWhere(filter: Omit<RunQuery, 'limit' | 'offset'>, opts?: {
+        compensate?: boolean;
+    }): Promise<RunResult[]>;
+    /**
+     * Hard-delete a run and its entire subtree. Unlike {@link cancel} (which marks a run `cancelled`
+     * but keeps it as history), delete REMOVES the run and all its rows (checkpoints, signal waiters,
+     * search-attribute rows) — it vanishes from {@link getRun} and {@link listRuns}. Use it to purge a
+     * finished run whose data is being deleted (e.g. a pipeline run whose result rows are cleared).
+     *
+     * Cascades depth-first via {@link getRunChildren} so children are gone before the parent (no
+     * orphaned child runs). Prefer {@link cancel} first for a live run — deleting one mid-flight orphans
+     * its worker (its next checkpoint write fails). Returns the number of runs deleted (0 if absent).
+     */
+    deleteRun(runId: string): Promise<number>;
+    /**
+     * Cascade cancellation to a run's children — both awaited (`ctx.child`, found via its live
+     * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
+     * checkpoint). Recursive, so a whole subtree is cancelled; the terminal guard in `cancel` stops it
+     * at finished / already-cancelled runs (no loops, no re-cancel).
+     */
+    private cancelChildren;
+    /**
+     * The ids of the runs a run spawned — both awaited (`ctx.child`) and fire-and-forget
+     * (`ctx.startChild`, found via its `spawn:<id>` checkpoint). The canonical parent→children edge,
+     * used for both cancellation cascades and the dashboard run-tree.
+     *
+     * An awaited child is discovered two ways, because the live `child:<id>` waiter only exists WHILE
+     * the parent is suspended on it: the waiter resolves and is consumed the moment the child settles,
+     * so a completed parent (or a completed awaited child) would otherwise drop out of the tree. The
+     * `signal:child:<id>` checkpoint (the placeholder written when the parent first awaits the child,
+     * overwritten as completed/failed when it settles) persists across completion, so we read both and
+     * dedupe — the edge stays stable for a finished run, not just a live one.
+     */
+    getRunChildren(parentRunId: string): Promise<string[]>;
+    /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
+     *  `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
+     *  workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
+     *  with backlog and ZERO workers is still reported (the alert case has no heartbeat to discover). */
+    knownGroups(extra?: string[]): string[];
+    /** Per-group worker health (queue backlog + live worker heartbeats). Covers {@link knownGroups}
+     *  (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
+     *  groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
+     *  from registrations, shows once its workers beat). Empty when no transport can introspect health
+     *  (only the BullMQ transport implements `groupHealth`). */
+    workerHealth(extra?: string[]): Promise<GroupHealth[]>;
+    /**
+     * Persist a streamed local-step lifecycle event from a remote workflow worker (see
+     * {@link WorkflowStepEvent}). A Python `@workflow` runs its `ctx.step`s inline over one turn that
+     * can last minutes; the worker streams each step's start/finish so the engine checkpoints it LIVE —
+     * a step shows `running` the moment its body begins, then resolves to `completed`/`failed` with its
+     * real wall-clock window and sub-process events — instead of every step appearing at once when the
+     * turn ends. The turn's final `recordStep` command re-persists the same (runId, seq) checkpoint
+     * idempotently, so this is purely additive observability and never changes the run's outcome.
+     */
+    private persistStepEvent;
+    /**
+     * Announce a local step's body has begun and (when `trackStepStart`) checkpoint it as `running`,
+     * so it's visible in flight rather than appearing only on completion. The checkpoint is a
+     * placeholder overwritten by {@link completeStep}/{@link failStep}; it never short-circuits replay
+     * (only `completed` does), so a crash mid-body just re-runs the step. The `step.started` event
+     * fires regardless — the live SSE view sees the start even with persistence off.
+     */
+    private startStep;
+    /** Checkpoint a finished step and announce it — the two things that must always happen together. */
+    private completeStep;
+    /** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
+    private failStep;
+    private execute;
+    /**
+     * Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
+     * a workflow task to the worker and awaits its replay) and apply the decision. Mirrors
+     * {@link runExecution}'s settle/suspend; the lease is held by {@link execute}. The result that lands
+     * us back here (a remote step finished, a timer fired) goes through `resume` like any TS workflow.
+     */
+    /**
+     * Apply a terminal/suspended transition once: persist the new run status, emit the matching
+     * lifecycle event, and (on completion/failure) wake a waiting parent. Both the TS and remote
+     * executors funnel their completed/failed/suspended outcomes through here so a status update can
+     * never drift from its event or `notifyParent` call. Does NOT touch the run lock — each executor
+     * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
+     */
+    private settleRun;
+    private runRemoteExecution;
+    /**
+     * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
+     * settle (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by
+     * the INLINE-advance path ({@link runRemoteExecution}, under the held lease) and the durable
+     * DISPATCH path ({@link completeRemoteDecision}, which holds the lease itself). Idempotent transitions
+     * — the caller has already ensured this is the decision for the currently-awaited turn.
+     */
+    private applyDecision;
+    /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
+    private remoteHistory;
+    /** Apply a turn's commands: persist recorded local steps, dispatch remote calls, schedule timers.
+     *  Returns the earliest timer deadline to suspend on (or undefined — suspended on a result). */
+    private applyCommands;
+    /**
+     * Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
+     * exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
+     * suspended, hit continue-as-new, or threw — so a cancel is never lost just because the body didn't
+     * stop at a suspension point. Clears the in-memory cancel flag.
+     */
+    private compensateAndCancel;
+    /** The run body, lease held + renewed by {@link execute}. */
+    private runExecution;
+    /**
+     * Run one saga compensation, retried up to `compensationRetries`, emitting a `compensate:<step>`
+     * step event for its outcome so a stranded undo is visible. Never throws — a permanently-failing
+     * compensation is skipped so it can't mask the original failure.
+     */
+    private runCompensation;
+    /** The seam handed to {@link createWorkflowCtx}: the authoring API reaches durability + lifecycle
+     *  (checkpointing, dispatch, child start) through this, so the ctx primitives live in their own
+     *  module and the engine stays the orchestrator. */
+    private ctxHostFor;
+    /**
+     * Resume a run paused at a {@link WorkflowCtx.breakpoint} (e.g. the dashboard "continue" button).
+     * Finds the run's pending breakpoint checkpoint and signals it. Returns null if the run isn't
+     * paused at a breakpoint.
+     */
+    continue(runId: string): Promise<RunResult | null>;
+    /**
+     * Read the latest value a run published for `key` via {@link WorkflowCtx.setEvent} — a
+     * side-effect-free query of a live (or finished) run's state. Returns `undefined` if the run
+     * never published that key. The suspend-model counterpart of a Temporal query.
+     */
+    getEvent<TValue = unknown>(runId: string, key: string): Promise<TValue | undefined>;
+    /**
+     * Register a validator gating `engine.update(runId, name, …)` for runs of `workflow`. The
+     * validator runs BEFORE the update is delivered, so a rejection leaves the run untouched. One
+     * validator per (workflow, update name); registering again replaces it.
+     */
+    registerUpdateValidator<TArg>(workflow: string, name: string, validate: UpdateValidator<TArg>): void;
+    /**
+     * Deliver a validated update to the run waiting at `ctx.onUpdate(name)`. Runs the registered
+     * validator (if any) first: on rejection returns `{ accepted: false, reason }` without disturbing
+     * the run; otherwise delivers `arg` and resumes, returning `{ accepted: true, run }` (`run` is null
+     * if nothing was waiting — a too-early or duplicate update).
+     */
+    update(runId: string, name: string, arg: unknown): Promise<UpdateResult>;
+    private callRemote;
+    /**
+     * Complete a durable remote step from its worker result and resume the run — runs on whichever
+     * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
+     * A no-op if the checkpoint isn't `pending` (a duplicate or late delivery).
+     */
+    private completeRemoteResult;
+    /**
+     * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
+     * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
+     * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
+     * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
+     * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
+     * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
+     */
+    private completeRemoteDecision;
+    /**
+     * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
+     * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
+     * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
+     */
+    private rearmDecisionDeadline;
+    /**
+     * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
+     * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
+     * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
+     */
+    private wakeQueueWaiters;
+    /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
+    private releaseQueueSlot;
+    /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
+    private callRemoteInMemory;
+    /**
+     * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
+     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
+     * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
+     * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
+     * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
+     */
+    private awaitWithLivenessDeadline;
+    /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
+     *  `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
+    private awaitWithHeartbeat;
+}
+/** Raised inside the workflow when a remote worker reports a step failure. */
+declare class RemoteStepError extends Error {
+    readonly stepError?: StepError | undefined;
+    constructor(stepError?: StepError);
+}
+
+/**
+ * Thrown inside a step to signal an unrecoverable failure: the engine will NOT retry it,
+ * regardless of the step's `retries` setting, and fails the run immediately. Use it for
+ * business errors that retrying cannot fix (e.g. a declined card, invalid input).
+ */
+declare class FatalError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown by `start` when a singleton workflow's wait queue is full: the count of in-flight + gated
+ * runs sharing the key already equals `limit + maxQueueDepth`, so admitting another would let the
+ * same-key backlog grow unbounded. Back-pressure — the caller should retry later or shed load. Only
+ * raised when {@link SingletonConfig.maxQueueDepth} is set (omit it for the old unbounded behavior).
+ */
+declare class SingletonQueueFullError extends Error {
+    readonly workflow: string;
+    readonly key: string;
+    readonly maxQueueDepth: number;
+    constructor(workflow: string, key: string, maxQueueDepth: number);
+}
+/**
+ * Internal control signal thrown to suspend a run (e.g. on a durable sleep). Not an error the
+ * user should throw or catch; the engine uses it to stop execution and persist `wakeAt`.
+ */
+declare class SignalTimeoutError extends Error {
+    readonly token: string;
+    readonly timeoutMs: number;
+    constructor(token: string, timeoutMs: number);
+}
+/**
+ * Thrown when a remote step produces no result and no heartbeat within its `timeoutMs` window —
+ * i.e. the worker is presumed dead. Subject to the step's `retries` (it's retryable), so the engine
+ * re-dispatches before giving up.
+ */
+declare class RemoteStepTimeout extends Error {
+    readonly stepId: string;
+    readonly timeoutMs: number;
+    constructor(stepId: string, timeoutMs: number);
+}
+/**
+ * Thrown by a remote {@link WorkflowExecutor} (e.g. {@link RemoteWorkflowExecutor}) when an `advance`
+ * does not produce its decision within the configured `timeoutMs` — i.e. the worker is presumed gone
+ * (the decision was dropped by a stall/redelivery or an instance restart spanning the in-memory waiter
+ * map). Crucially this is NOT a run failure: the work may have actually completed and only the decision
+ * was lost. The engine treats it as RECOVERABLE — it releases the run lease and leaves the run
+ * `running` so `recoverIncomplete` re-drives it deterministically (replaying completed steps from
+ * history). Distinct from a real executor error, which still fails the run.
+ *
+ * OPT-IN: only thrown when the executor was constructed with a `timeoutMs`. Absent a timeout, the
+ * engine awaits the decision with its prior (unbounded) behavior — so existing users see no change.
+ *
+ * Known hazard: a timeout that fires while a worker is LEGITIMATELY still executing a not-yet-
+ * checkpointed step will re-drive and re-run that in-flight step → DUPLICATE side effects. Therefore
+ * the timeout is only safe when set GENEROUSLY (longer than the longest legitimate single turn). The
+ * robust fix — a liveness/heartbeat-rearmed deadline so only a genuinely-dead worker re-drives — is the
+ * documented follow-up (see the Track A diagnosis doc, "Part B").
+ */
+declare class RemoteWorkflowTimeout extends Error {
+    readonly taskId: string;
+    readonly timeoutMs: number;
+    constructor(taskId: string, timeoutMs: number);
+}
+/**
+ * Thrown on resume when the workflow code no longer matches the recorded history: the step at a
+ * logical position has a different name/kind than the checkpoint saved there. This means the
+ * workflow definition changed (a step was added/removed/reordered) under an in-flight run without a
+ * new `@Workflow` version — continuing would replay the wrong checkpoint into the wrong step and
+ * silently corrupt the run, so the engine fails loudly instead. Register a new workflow version for
+ * breaking changes (old runs finish on the version they started on).
+ */
+declare class NonDeterminismError extends Error {
+    readonly runId: string;
+    readonly seq: number;
+    constructor(runId: string, seq: number, expected: string, recorded: string);
+}
+/**
+ * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
+ * (input index, child run id, error message) and presents an aggregate message summarizing the count
+ * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
+ * the Python SDK's `GatherFailed`.
+ */
+declare class GatherError extends Error {
+    readonly failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[];
+    constructor(failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[], total?: number);
+}
+declare class WorkflowSuspended extends Error {
+    /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
+    readonly wakeAt?: number | undefined;
+    constructor(wakeAt?: number);
+}
+/**
+ * Thrown by `ctx.continueAsNew(input)` to end the current run and hand off to a fresh execution of
+ * the same workflow with a clean history — for long-running / looping workflows that would otherwise
+ * accumulate unbounded checkpoints. The engine completes this run and starts the next one.
+ */
+declare class ContinueAsNew extends Error {
+    readonly input: unknown;
+    constructor(input: unknown);
+}
+
+/** Canonical step id — the stable identity of a step within a run, used for dedupe and
+ *  correlation. The format is part of the cross-language wire contract (Python builds the same). */
+declare function stepId(runId: string, seq: number): string;
+/** Deterministic signal token a breakpoint suspends on — derived from its logical position. Shared
+ *  so `ctx.breakpoint` (which records it) and `engine.continue` (which signals it) agree. */
+declare const breakpointToken: (runId: string, seq: number) => string;
+/** A remote-worker step body. The optional `log` records sub-process outcomes and debug/error
+ *  lines that ride back on the result — the TypeScript twin of the Python SDK's `StepContext`. */
+type StepHandler = (input: unknown, log: StepLogger) => Promise<unknown> | unknown;
+/**
+ * Run `handler` for `task` and produce the wire-format {@link StepResult}. Pure (no transport,
+ * no I/O beyond the handler), so every transport — and any language port — can share the exact
+ * same completed / failed / no-handler contract instead of re-deriving it.
+ */
+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.
+ *
+ * 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},
+ * delivered over the transport's `onDecision` and applied DURABLY (by run id) on whatever engine
+ * instance consumes it — even one that did not dispatch the turn — can never arrive ahead of its marker
+ * or contend with a still-held lease and be dropped. A point-to-point broker can therefore hand the
+ * decision to any instance without it being dropped (the bug this design fixes).
+ *
+ * Recovery-safe: if the engine crashes (or a decision is genuinely lost because the worker died), the
+ * suspended turn's heartbeat-rearmed window (`remoteAdvanceSilenceMs`) lapses and the timer poller
+ * re-dispatches a fresh task with the same history — the worker's replay is deterministic, so it
+ * returns the same decision; a late decision for the old `taskId` no longer matches the run's
+ * currently-awaited turn and is dropped.
+ */
+declare class RemoteWorkflowExecutor implements WorkflowExecutor {
+    private readonly transport;
+    private readonly group;
+    constructor(transport: Transport, group: string, _opts?: {
+        timeoutMs?: number;
+    });
+    /**
+     * Enqueue one workflow turn under the engine-supplied `taskId`. Does NOT await the decision — the
+     * engine has already suspended the run on `taskId` and applies the decision durably via `onDecision`.
+     */
+    dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<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
+ * cipher / codec); wrap an async KMS yourself if you need one.
+ */
+interface PayloadCodec {
+    encode(value: unknown): unknown;
+    decode(value: unknown): unknown;
+}
+/**
+ * A `StateStore` decorator that runs run/step **payloads** (input + output) through a
+ * {@link PayloadCodec} — encoded on write, decoded on read — so they're never stored in the clear.
+ * Adapter-agnostic: wrap any store. Searchable metadata (id, status, workflow, tags, timestamps) and
+ * the structured `error` are left untouched so the dashboard, queries, and recovery still work.
+ *
+ * ```ts
+ * const store = new CodecStateStore(new TypeOrmStateStore(ds), aesCodec);
+ * ```
+ */
+declare class CodecStateStore implements StateStore {
+    private readonly inner;
+    private readonly codec;
+    constructor(inner: StateStore, codec: PayloadCodec);
+    private enc;
+    private dec;
+    private encRun;
+    private decRun;
+    private encCp;
+    private decCp;
+    ensureSchema(): Promise<void>;
+    createRun(run: WorkflowRun): Promise<void>;
+    updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
+    getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    transaction<T>(work: (tx: {
+        raw: unknown;
+        saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
+    }) => Promise<T>): Promise<T>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
+    releaseRunLock(runId: string): Promise<void>;
+    renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
+    putSignalWaiter(waiter: SignalWaiter): Promise<void>;
+    takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
+    listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    bufferSignal(token: string, payload: unknown): Promise<void>;
+    takeBufferedSignal(token: string): Promise<{
+        payload: unknown;
+    } | null>;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+}
+
+/** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
+declare function eventPrefix(name: string): string;
+/** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
+declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
+/** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
+declare function eventMatchOf(token: string): Record<string, unknown>;
+/** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
+declare function eventMatches(payload: unknown, match: Record<string, unknown>): boolean;
+
+interface MetricsSnapshot {
+    runs: {
+        started: number;
+        completed: number;
+        failed: number;
+        suspended: number;
+    };
+    steps: {
+        started: number;
+        completed: number;
+        failed: number;
+    };
+    /** Per-workflow run counters, keyed by workflow name. */
+    byWorkflow: Record<string, {
+        started: number;
+        completed: number;
+        failed: number;
+    }>;
+    /** Sum + count of recorded step durations (ms), for an average. */
+    stepDuration: {
+        sumMs: number;
+        count: number;
+    };
+}
+interface MetricsCollector {
+    snapshot(): MetricsSnapshot;
+    /** Prometheus text exposition of the counters — serve this from a `/metrics` endpoint. */
+    prometheus(): string;
+    /** Unsubscribe from the engine. */
+    stop(): void;
+}
+type Subscribable = {
+    subscribe(listener: (event: EngineEvent) => void): () => void;
+};
+/**
+ * Subscribe to an engine's lifecycle events and accumulate Prometheus-style counters (runs + steps by
+ * outcome, per-workflow run counts, step-duration sum/count). Dependency-free — call `.prometheus()`
+ * from your metrics endpoint, or `.snapshot()` for the raw numbers. Counters are per process; scrape
+ * each instance.
+ */
+declare function collectMetrics(engine: Subscribable): MetricsCollector;
+
+interface ScheduledWorkflow {
+    /** Stable key identifying this schedule — part of the deterministic run id. */
+    key: string;
+    workflow: string;
+    input?: unknown;
+    /** Start one run every `everyMs`. Mutually exclusive with `cron`. */
+    everyMs?: number;
+    /**
+     * A cron expression (5 fields `m h dom mon dow`, or 6 with leading seconds) evaluated in
+     * {@link ScheduledWorkflow.timezone}. Mutually exclusive with `everyMs`. Needs the optional peer
+     * dependency `cron-parser`.
+     */
+    cron?: string;
+    /** IANA timezone the `cron` fires in (e.g. `America/Sao_Paulo`). Defaults to UTC. */
+    timezone?: string;
+    /** Temporarily stop firing this schedule (kept registered). Defaults to false. */
+    paused?: boolean;
+    /**
+     * What to do when the previous window's run hasn't finished yet (fixed-interval schedules only):
+     * `'allow'` (default) starts the new window anyway; `'skip'` skips it while the prior run is still
+     * `running`/`suspended`, so a slow run can't pile up overlapping executions.
+     */
+    overlap?: 'allow' | 'skip';
+    /**
+     * Randomly delay the dispatch by up to this many ms BEFORE firing, to spread load when many
+     * instances tick on the same boundary (avoids a thundering herd). Opt-in; absent = fire immediately.
+     *
+     * This is dispatch-path jitter only — it does NOT affect the run id (still the time bucket), so
+     * idempotency is unchanged: two instances jittering the same window still start it exactly once.
+     * (The engine forbids `Math.random` inside workflow code; the scheduler dispatch path is not
+     * workflow code, so jitter here is fine.)
+     */
+    jitter?: number;
+    /**
+     * Enqueue windows that were missed while the scheduler was down, instead of silently skipping
+     * them. Opt-in; absent = only the current window fires. `maxCatchup` bounds how many PRIOR windows
+     * are backfilled (a long outage can't flood the system). Backfilled runs use each missed window's
+     * deterministic bucket run id, so `engine.start` idempotency skips any that already ran.
+     */
+    backfill?: {
+        maxCatchup: number;
+    };
+}
+/** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
+ *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
+interface RunSchedulesOptions {
+    random?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Deterministic run id for a fixed-interval schedule's current time window. */
+declare function scheduledRunId(key: string, everyMs: number, nowMs: number): string;
+/**
+ * Epoch ms of the most recent cron fire at or before `nowMs`, evaluated in `timezone` (default UTC).
+ * This is the deterministic "bucket" a cron run is keyed on, so polling repeatedly within an
+ * interval resolves to the same fire time — and thus the same idempotent run id.
+ */
+declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string): number;
+/**
+ * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
+ * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
+ * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
+ * current windows.
+ */
+declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
+
+/**
+ * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
+ * local-step path (`ctx.step`) and the remote-worker path (`runStepHandler`) so a step records
+ * the same {@link StepEvent} shape wherever it runs — the TypeScript twin of the Python SDK's
+ * `StepContext`.
+ */
+declare function createStepLogger(events: StepEvent[], now: () => number): StepLogger;
+
+/**
+ * Does a run's search attributes satisfy EVERY filter (AND)? A missing key never matches (so `ne`
+ * on an absent key is false too — the attribute simply isn't there to compare). Empty/undefined
+ * filters match everything. Shared by every store so typed/range queries behave identically across
+ * adapters (applied in-process after the coarse workflow/status/tag filters).
+ */
+declare function matchesAttributes(attributes: SearchAttributes | undefined, filters: AttributeFilter[] | undefined): boolean;
+/**
+ * Apply a query's attribute predicates then its `offset`/`limit`, in-process — for store adapters
+ * that can't express typed/range predicates in SQL. Pass rows already coarse-filtered (workflow /
+ * status / tag) and sorted newest-first; this filters by `attributes` and paginates. Only call it
+ * when `query.attributes` is set (otherwise let the DB do `LIMIT`/`OFFSET`).
+ */
+declare function applyAttributeQuery(rows: WorkflowRun[], query: RunQuery): WorkflowRun[];
+/**
+ * One normalized row of the `durable_run_attributes` side-table: a single (key → value) pair of a
+ * run's search attributes, split into typed columns so SQL can index/range-scan it. Exactly one of
+ * `strValue`/`numValue` is set per row (booleans normalize to a string `"true"`/`"false"` so `eq`/`ne`
+ * still match). NULL for the column that doesn't apply, which keeps `(key, numValue)` /
+ * `(key, strValue)` indexes selective.
+ */
+interface RunAttributeRow {
+    runId: string;
+    key: string;
+    strValue: string | null;
+    numValue: number | null;
+}
+/**
+ * Explode a run's search attributes into normalized side-table rows (one per key). Used by SQL stores
+ * to maintain `durable_run_attributes` on every create/update and by the in-memory store's index, so
+ * attribute predicates can be pushed DOWN into a join/EXISTS instead of scanned in-process. Numbers go
+ * to `numValue`; strings to `strValue`; booleans to `strValue` as `"true"`/`"false"` (matching how the
+ * in-process `compare` treats `eq`/`ne` on booleans). Returns `[]` for a run with no attributes.
+ */
+declare function normalizeAttributeRows(runId: string, attributes: SearchAttributes | undefined): RunAttributeRow[];
+/** SQL comparison operator for an {@link AttributeOp} (used to build pushdown predicates). */
+declare function sqlComparator(op: AttributeOp): string;
+/**
+ * Which side-table column an attribute filter compares against: numeric operands (and range ops on
+ * numbers) hit `numValue`; everything else hits `strValue` (booleans are stored as `"true"`/`"false"`).
+ * Keeping this in core means every SQL adapter pushes predicates down identically.
+ */
+declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strValue';
+/** 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;
+
+/**
+ * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
+ * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
+ *
+ * These use `Symbol.for(key)` (the global symbol registry), NOT `Symbol(key)`, so the token is the
+ * SAME instance no matter how many times `core` is evaluated in a process. A consumer can hold more
+ * than one physical copy of `core` at runtime — pnpm peer-dependency multiplexing installs a
+ * separate virtual copy per distinct peer set, and the dual ESM/CJS build can be loaded once as
+ * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
+ * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
+ * (injector) could resolve different symbols → Nest can't satisfy the dependency
+ * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
+ * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
+ */
+/**
+ * @deprecated Use {@link STATE_STORE_CANONICAL} (`@dudousxd/nestjs-durable:state-store`). The legacy
+ * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
+ */
+declare const STATE_STORE: unique symbol;
+/**
+ * @deprecated Use {@link TRANSPORT_CANONICAL} (`@dudousxd/nestjs-durable:transport`). The legacy
+ * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
+ */
+declare const TRANSPORT: unique symbol;
+/**
+ * @deprecated Use {@link DURABLE_OPTIONS_CANONICAL} (`@dudousxd/nestjs-durable:options`). The legacy
+ * token stays bound as a back-compat alias and still resolves; it will be removed in a future major.
+ */
+declare const DURABLE_OPTIONS: unique symbol;
+/**
+ * Canonical, cross-lib-discoverable aliases of the durable DI tokens, following the ecosystem
+ * capability naming `@dudousxd/nestjs-durable:<name>` (identical to `capability('durable', <name>)`).
+ * `DurableModule` binds these alongside the legacy tokens (dual-bind), so an external library can
+ * resolve durable's store/transport/options by the canonical name without importing durable
+ * internals. Bare `Symbol.for` (same cross-copy-stability rationale as the legacy tokens above)
+ * keeps `core` free of any `@dudousxd/nestjs-diagnostics` runtime dependency.
+ */
+declare const STATE_STORE_CANONICAL: unique symbol;
+declare const TRANSPORT_CANONICAL: unique symbol;
+declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
+
+/**
+ * A non-durable, in-process `StateStore` for tests and local development.
+ * The shipped `@dudousxd/nestjs-durable-store` package re-exports an equivalent.
+ */
+declare class InMemoryStateStore implements StateStore {
+    private readonly runs;
+    private readonly checkpoints;
+    private readonly signalWaiters;
+    /**
+     * Normalized search-attribute side-table, the in-memory analog of the SQL stores'
+     * `durable_run_attributes`: `key -> (runId -> row)`. Maintained on every create/update so an
+     * attribute query can be pushed DOWN to a key-indexed candidate set instead of scanning every run
+     * and comparing in-process. Mirrors {@link normalizeAttributeRows} so behavior matches the SQL path.
+     */
+    private readonly attributeIndex;
+    /** Test/observability hook: how many candidate runs the last attribute query's index produced. */
+    lastAttributeCandidates: number;
+    /**
+     * Test/observability hook: how many checkpoint rows the LAST checkpoint read materialized (the rows
+     * actually returned to the caller). `listCheckpoints` returns all rows for the run; the targeted
+     * {@link getLatestCheckpointByName} / {@link listCheckpointsByNamePrefix} return only the matches —
+     * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
+     */
+    lastCheckpointRowsRead: number;
+    private key;
+    /** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
+    private reindexAttributes;
+    createRun(run: WorkflowRun): Promise<void>;
+    updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
+    getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
+    tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
+    releaseRunLock(runId: string): Promise<void>;
+    renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
+    putSignalWaiter(waiter: SignalWaiter): Promise<void>;
+    takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
+    listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    transaction<T>(work: (tx: {
+        raw: unknown;
+        saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
+    }) => Promise<T>): Promise<T>;
+    private readonly bufferedSignals;
+    bufferSignal(token: string, payload: unknown): Promise<void>;
+    takeBufferedSignal(token: string): Promise<{
+        payload: unknown;
+    } | null>;
+    /**
+     * Candidate run ids satisfying ONE attribute predicate, served from {@link attributeIndex} — the
+     * pushdown step. Numeric predicates scan only `numValue` rows under the key; string/boolean ones
+     * scan `strValue` rows. This is the in-memory analog of the SQL EXISTS on `durable_run_attributes`.
+     */
+    private candidatesForFilter;
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+}
+
+/**
+ * An in-process `Transport` (and `ControlPlane`) for tests and local development: registered
+ * handlers stand in for remote workers, so a whole cross-app workflow runs in a single process,
+ * and control messages broadcast locally. Pass the same instance as both `transport` and
+ * `controlPlane`.
+ */
+declare class InMemoryTransport implements Transport, ControlPlane {
+    private readonly handlers;
+    private resultHandler?;
+    private heartbeatHandler?;
+    private stepEventHandler?;
+    private readonly controlHandlers;
+    /** Register a fake worker handler for a step name. */
+    handle(name: string, fn: StepHandler): void;
+    dispatch(task: RemoteTask): Promise<void>;
+    onResult(handler: (result: StepResult) => Promise<void>): void;
+    onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /** Test hook: deliver a liveness heartbeat to the engine, as a real broker would on its channel. */
+    emitHeartbeat(beat: Heartbeat): Promise<void>;
+    /** Workflow step lifecycle: deliver to the engine's handler (async, mirroring a real broker). */
+    dispatchStepEvent(event: WorkflowStepEvent): Promise<void>;
+    onStepEvent(handler: (event: WorkflowStepEvent) => Promise<void>): void;
+    publishControl(msg: ControlMessage): Promise<void>;
+    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 StartRunMessage, 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, tenantGroup, workflowName };