@dudousxd/nestjs-durable-core 0.27.1 → 0.28.0

package/dist/index.d.ts

@@ -1,20 +1,2044 @@
-export * from './duration';
-export * from './engine';
-export * from './entities';
-export * from './errors';
-export * from './event-accumulators';
-export * from './interfaces';
-export * from './protocol';
-export * from './queue';
-export * from './remote-step-factory';
-export * from './remote-workflow-executor';
-export * from './codec-state-store';
-export * from './events';
-export * from './metrics';
-export * from './scheduler';
-export * from './search-attributes';
-export * from './tokens';
-export * from './workflow-ref';
-export { InMemoryStateStore } from './testing/in-memory-state-store';
-export { InMemoryTransport } from './testing/in-memory-transport';
-//# sourceMappingURL=index.d.ts.map
+import { z } from 'zod';
+
+/**
+ * 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' | '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;
+    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;
+    /**
+     * 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>;
+    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(): Promise<WorkflowRun[]>;
+    /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
+    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
+    listDueTimers(nowMs: number): 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[]>;
+}
+/** 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;
+    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;
+}
+/** 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;
+    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;
+    stepId: string;
+    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;
+    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. */
+{
+    kind: 'call';
+    seq: number;
+    name: string;
+    group: string;
+    input: unknown;
+}
+/** `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[];
+}
+/** `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. */
+ | {
+    kind: 'startChild';
+    seq: number;
+    workflow: string;
+    input: unknown;
+};
+/** 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. */
+    status: 'continue' | 'completed' | 'failed';
+    /** 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[];
+}
+/**
+ * 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 {
+    advance(run: WorkflowRun, history: HistoryEvent[], pendingSignals?: WorkflowTask['pendingSignals']): Promise<WorkflowDecision>;
+}
+/**
+ * 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;
+    /** 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[]>;
+}
+/** 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;
+}
+/** 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';
+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>, childId?: string): Promise<WorkflowOutputOf<C>>;
+    child<TOutput>(workflow: string, input: unknown, childId?: string): 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>, childId?: string): Promise<string>;
+    startChild(workflow: string, input: unknown, childId?: string): Promise<string>;
+    /**
+     * 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>;
+}
+/** 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;
+}
+
+/**
+ * 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';
+}
+/**
+ * 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;
+}
+
+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;
+}
+/**
+ * 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;
+    /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
+    instanceId?: 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;
+    /**
+     * 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;
+}
+/**
+ * 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 leaseMs;
+    private readonly maxRecoveryAttempts?;
+    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;
+    /** 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;
+    /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+    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 queues for remote steps, keyed by name (see {@link registerQueue}). */
+    private readonly queues;
+    /** 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;
+    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.
+     */
+    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;
+    }): void;
+    /**
+     * 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;
+    /**
+     * 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>;
+    /** 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[]>;
+    /**
+     * 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;
+    /**
+     * Whether `run` may run now under its singleton key: it's among the `limit` oldest in-flight runs
+     * (running or suspended) sharing the key, by `(createdAt, id)` order. A consistent store gives every
+     * instance the same ordering, so admission is race-free + FIFO.
+     */
+    private admitSingleton;
+    /**
+     * Notify-on-release: a singleton run just settled (freeing a slot), so wake the gated waiters that
+     * can now be admitted — immediately, instead of letting them sleep until their ~1s retry timer.
+     * Dispatches up to `limit` of the oldest gated (`suspended` + same singleton tag) waiters by
+     * `(createdAt, id)`; each re-checks admission in `runExecution` and runs only if it actually wins a
+     * slot, so this never breaks the FIFO + race-free guarantees (the durable timer remains the
+     * cross-instance / crash fallback — this just removes the poll latency on the happy path).
+     */
+    private wakeNextSingletons;
+    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.
+     */
+    private runRemoteExecution;
+    /** 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;
+    /** 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;
+    /** 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 a remote result, but reject with `RemoteStepTimeout` if neither the result nor a heartbeat
+     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`) rearms the
+     * window, so a worker that keeps beating stays alive past `timeoutMs`.
+     */
+    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 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);
+}
+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 and awaiting the matching {@link WorkflowDecision}
+ * (correlated by `taskId`). 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.
+ *
+ * Recovery-safe: if the engine crashes awaiting a decision, the re-drive 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` simply finds no waiter and is dropped.
+ */
+declare class RemoteWorkflowExecutor implements WorkflowExecutor {
+    private readonly transport;
+    private readonly group;
+    private readonly opts;
+    private readonly pending;
+    private subscribed;
+    constructor(transport: Transport, group: string, opts?: {
+        timeoutMs?: number;
+    });
+    private ensureSubscribed;
+    advance(run: WorkflowRun, history: HistoryEvent[]): Promise<WorkflowDecision>;
+}
+
+/**
+ * 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>;
+    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(): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number): 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[]>;
+}
+
+/** 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[]>;
+
+/**
+ * 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;
+
+/**
+ * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
+ * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
+ */
+declare const STATE_STORE: unique symbol;
+declare const TRANSPORT: unique symbol;
+declare const DURABLE_OPTIONS: 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;
+    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>;
+    getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
+    saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
+    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number): 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[]>;
+}
+
+/**
+ * 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 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;
+    /** 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 AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, 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, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };