@dudousxd/nestjs-durable-core 0.51.0 → 0.53.0

package/dist/index.d.cts

@@ -628,6 +628,16 @@ interface StateStore {
     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[]>;
+    /**
+     * Delete the EXACT waiter row — `token` AND `runId` AND `seq` must all match — no-op if absent.
+     * Unlike {@link takeSignalWaiter}, which deletes ANY row for `token` (fine when the caller just won
+     * the race to consume it), this is for a caller removing its OWN registration after resolving the
+     * wait some other way (a buffered hit, a timeout): blind `takeSignalWaiter(token)` there could steal
+     * a DIFFERENT run's waiter that has since claimed the same token (`token` is the store's primary key,
+     * so a later `putSignalWaiter` for the same token replaces the row). The exact-match variant only
+     * ever removes the row this caller itself put there.
+     */
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     /**
      * 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
@@ -1749,6 +1759,59 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
  */
 declare function currentWorkflowCtx(): WorkflowCtx | undefined;
 
+/**
+ * Cross-package, cross-runtime marker for engine CONTROL-FLOW signals — {@link WorkflowSuspended}
+ * and {@link ContinueAsNew} (this package), plus the thin worker's {@link
+ * import('@dudousxd/durable-worker').Suspend} (`@dudousxd/durable-worker`, the BullMQ
+ * route-by-handler runtime). These are thrown by `WorkflowCtx`/`WorkflowContext` ops to unwind the
+ * current turn — never real failures — so a workflow's `catch` block MUST rethrow them untouched.
+ * Running a failure/cleanup path on a control-flow signal corrupts the run: it emits extra
+ * `recordStep` commands into history that a subsequent replay didn't produce the first time,
+ * surfacing as a `NonDeterminismError`/`NondeterminismError` on resume.
+ *
+ * `Symbol.for` (the GLOBAL registry), NOT a plain `Symbol()` — so a duplicate copy of this module
+ * (pnpm peer-dependency multiplexing, a dual ESM/CJS load, or the SEPARATE `@dudousxd/durable-worker`
+ * package declaring the same `Symbol.for` key locally) still collapses onto the SAME symbol. Same
+ * rationale as `DURABLE_STEP_NAME` in `./step-name-symbol.ts`.
+ *
+ * Deliberately checked as a stamped property, NOT `instanceof` — `instanceof` only recognizes a
+ * signal thrown by the SAME class the checking code imported, which fails across the in-process
+ * engine (`@dudousxd/nestjs-durable-core`'s `WorkflowSuspended`/`ContinueAsNew`) and the thin worker
+ * (`@dudousxd/durable-worker`'s `Suspend`) — two different classes for what is, from a workflow
+ * author's catch block, the same "this isn't a real error, let it through" event.
+ *
+ * NOT designed to survive a serialization boundary (e.g. JSON over the wire) — these signals are
+ * always thrown and caught in-process within a single replay turn, never (de)serialized, so a
+ * stamped-but-not-cloneable property is sufficient.
+ */
+declare const CONTROL_FLOW_SIGNAL: unique symbol;
+/**
+ * True for any engine control-flow signal (currently: {@link WorkflowSuspended}, {@link
+ * ContinueAsNew}, and the thin worker's `Suspend`) — regardless of which runtime or module instance
+ * threw it. Workflow `catch` blocks MUST rethrow these untouched; running a failure/cleanup path on
+ * one corrupts the run's history (extra commands recorded during what replay will later see as a
+ * suspend, not a failure) and the resumed replay dies with a non-determinism error.
+ *
+ * Deliberately NOT control-flow (do not add to this predicate):
+ * - `Cancelled` (worker) / a cancelled run — a TERMINAL outcome the consumer may legitimately want
+ *   to observe and react to (e.g. release a lock), not a mid-turn unwind to rethrow untouched.
+ * - `StepFailed` (worker) / an awaited step rejection reaching the engine — a REAL failure a
+ *   workflow's `catch` is meant to compensate for; misclassifying it as control-flow would swallow
+ *   genuine errors instead of protecting them.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await ctx.step('chargeCard', input);
+ * } catch (error) {
+ *   if (isWorkflowControlFlowSignal(error)) throw error; // suspend/continue-as-new: rethrow as-is
+ *   await ctx.step('refund', input); // a REAL failure — safe to run cleanup here
+ *   throw error;
+ * }
+ * ```
+ */
+declare function isWorkflowControlFlowSignal(error: unknown): boolean;
+
 /**
  * Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
  * used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
@@ -2320,8 +2383,32 @@ declare class WorkflowEngine {
     /**
      * 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.
+     *
+     * Piggy-backs the signal-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a crash
+     * between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+     * `takeBufferedSignal`, or a signaler's `takeSignalWaiter` → `bufferSignal` → re-check — see
+     * `signal`'s interleaving proof) can leave both rows stranded with nothing left to pair them: the
+     * waiter's turn already suspended, the signaler that buffered it already returned. Event-wait
+     * suspends already carry a `reconcileMs` fallback `wakeAt` (see {@link reconcileWakeAt}) precisely so
+     * they show up HERE — that's what makes this due-timer pass the natural place for the sweep. One
+     * bulk waiter scan, filtered to just this tick's batch, keeps it cheap regardless of store size.
      */
     resumeDueTimers(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * The reconcile safety net's per-run check (see {@link resumeDueTimers}): if this suspended run has
+     * a registered signal waiter AND its token already has a buffered payload, pair and deliver them
+     * directly instead of falling through to a full replay. Event/child/breakpoint waiter tokens are
+     * never buffered (`publishEvent` doesn't buffer, and a child/breakpoint notifies via `signal` only
+     * once its counterpart is already registered) — so `takeBufferedSignal` on those is a guaranteed
+     * miss, and this is naturally signal-only without needing to classify the token.
+     *
+     * Returns `undefined` (not settled — `resumeLeased` proceeds with its normal `resume`) when there's
+     * no waiter or no buffered hit. Deliberately never returns `null`: a delivered signal always resumes
+     * via {@link deliverSignal}, and even a `NamespaceMismatch` there is reported as a real (non-nullish)
+     * result — returning `null` would read as "not settled" to `resumeLeased`'s `??` fallback and
+     * trigger a second, redundant `resume` call on the same run.
+     */
+    private reconcileSignalWaiter;
     /**
      * 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
@@ -2394,6 +2481,37 @@ declare class WorkflowEngine {
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
     }): Promise<number>;
+    /**
+     * Deliver a signal to an already-known waiter: write its resolving `signal:<token>` checkpoint and
+     * resume the run. Shared by {@link signal}'s direct hit, its post-buffer re-check reclaim, and the
+     * due-timer reconcile sweep ({@link reconcileSignalWaiter}) — all three resolve a waiter the exact
+     * same way.
+     */
+    private deliverSignal;
+    /**
+     * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
+     * the run result — or null if no run is (or ends up) waiting for it.
+     *
+     * Race with the waiter side (`waitForSignal`'s check → `putSignalWaiter` → re-check, same shape in
+     * the remote `waitSignal` command): a waiter can register in the sliver between this method's
+     * initial `takeSignalWaiter` miss and its `bufferSignal` write, and the naive old flow (buffer and
+     * return) would then leave BOTH a buffered payload and a registered waiter sitting in the store with
+     * nothing left to pair them — a lost wake, forever suspended.
+     *
+     * The interleaving proof: the waiter side does check → put → re-check, this side does take → buffer
+     * → re-check. Whichever side's SECOND look runs last is guaranteed to observe the other side's
+     * write, because it always follows that write in real time:
+     *  - If the waiter's `put` lands before this method's first `take`, the take just finds it directly
+     *    (the pre-existing, non-racy path).
+     *  - If the waiter's `put` lands after this method's `bufferSignal`, our re-check below either sees
+     *    it (if `put` also lands before the re-check) or the waiter's OWN post-put re-check sees our
+     *    buffer (if `put` lands after our re-check but the waiter hasn't re-checked yet either — its
+     *    re-check strictly follows its own put).
+     *  - If the waiter's `put` lands between this method's `take` and its re-`take`, the re-check below
+     *    catches it.
+     * Either way, the destructive `take*` ops (on the waiter row, on the buffer) arbitrate: whichever
+     * side actually removes the row is the one that delivers, so a signal is never delivered twice.
+     */
     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
@@ -2875,6 +2993,8 @@ declare class GatherError extends Error {
 declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
     readonly wakeAt?: number | undefined;
+    /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+    readonly [CONTROL_FLOW_SIGNAL] = true;
     constructor(wakeAt?: number);
 }
 /**
@@ -2884,6 +3004,8 @@ declare class WorkflowSuspended extends Error {
  */
 declare class ContinueAsNew extends Error {
     readonly input: unknown;
+    /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+    readonly [CONTROL_FLOW_SIGNAL] = true;
     constructor(input: unknown);
 }
 
@@ -3098,6 +3220,7 @@ declare class CodecStateStore implements StateStore {
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     bufferSignal(token: string, payload: unknown): Promise<void>;
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
@@ -3465,6 +3588,7 @@ declare class InMemoryStateStore implements StateStore {
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     transaction<T>(work: (tx: {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
@@ -3512,4 +3636,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, CONTROL_FLOW_SIGNAL, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, isWorkflowControlFlowSignal, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.d.ts

@@ -628,6 +628,16 @@ interface StateStore {
     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[]>;
+    /**
+     * Delete the EXACT waiter row — `token` AND `runId` AND `seq` must all match — no-op if absent.
+     * Unlike {@link takeSignalWaiter}, which deletes ANY row for `token` (fine when the caller just won
+     * the race to consume it), this is for a caller removing its OWN registration after resolving the
+     * wait some other way (a buffered hit, a timeout): blind `takeSignalWaiter(token)` there could steal
+     * a DIFFERENT run's waiter that has since claimed the same token (`token` is the store's primary key,
+     * so a later `putSignalWaiter` for the same token replaces the row). The exact-match variant only
+     * ever removes the row this caller itself put there.
+     */
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     /**
      * 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
@@ -1749,6 +1759,59 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
  */
 declare function currentWorkflowCtx(): WorkflowCtx | undefined;
 
+/**
+ * Cross-package, cross-runtime marker for engine CONTROL-FLOW signals — {@link WorkflowSuspended}
+ * and {@link ContinueAsNew} (this package), plus the thin worker's {@link
+ * import('@dudousxd/durable-worker').Suspend} (`@dudousxd/durable-worker`, the BullMQ
+ * route-by-handler runtime). These are thrown by `WorkflowCtx`/`WorkflowContext` ops to unwind the
+ * current turn — never real failures — so a workflow's `catch` block MUST rethrow them untouched.
+ * Running a failure/cleanup path on a control-flow signal corrupts the run: it emits extra
+ * `recordStep` commands into history that a subsequent replay didn't produce the first time,
+ * surfacing as a `NonDeterminismError`/`NondeterminismError` on resume.
+ *
+ * `Symbol.for` (the GLOBAL registry), NOT a plain `Symbol()` — so a duplicate copy of this module
+ * (pnpm peer-dependency multiplexing, a dual ESM/CJS load, or the SEPARATE `@dudousxd/durable-worker`
+ * package declaring the same `Symbol.for` key locally) still collapses onto the SAME symbol. Same
+ * rationale as `DURABLE_STEP_NAME` in `./step-name-symbol.ts`.
+ *
+ * Deliberately checked as a stamped property, NOT `instanceof` — `instanceof` only recognizes a
+ * signal thrown by the SAME class the checking code imported, which fails across the in-process
+ * engine (`@dudousxd/nestjs-durable-core`'s `WorkflowSuspended`/`ContinueAsNew`) and the thin worker
+ * (`@dudousxd/durable-worker`'s `Suspend`) — two different classes for what is, from a workflow
+ * author's catch block, the same "this isn't a real error, let it through" event.
+ *
+ * NOT designed to survive a serialization boundary (e.g. JSON over the wire) — these signals are
+ * always thrown and caught in-process within a single replay turn, never (de)serialized, so a
+ * stamped-but-not-cloneable property is sufficient.
+ */
+declare const CONTROL_FLOW_SIGNAL: unique symbol;
+/**
+ * True for any engine control-flow signal (currently: {@link WorkflowSuspended}, {@link
+ * ContinueAsNew}, and the thin worker's `Suspend`) — regardless of which runtime or module instance
+ * threw it. Workflow `catch` blocks MUST rethrow these untouched; running a failure/cleanup path on
+ * one corrupts the run's history (extra commands recorded during what replay will later see as a
+ * suspend, not a failure) and the resumed replay dies with a non-determinism error.
+ *
+ * Deliberately NOT control-flow (do not add to this predicate):
+ * - `Cancelled` (worker) / a cancelled run — a TERMINAL outcome the consumer may legitimately want
+ *   to observe and react to (e.g. release a lock), not a mid-turn unwind to rethrow untouched.
+ * - `StepFailed` (worker) / an awaited step rejection reaching the engine — a REAL failure a
+ *   workflow's `catch` is meant to compensate for; misclassifying it as control-flow would swallow
+ *   genuine errors instead of protecting them.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await ctx.step('chargeCard', input);
+ * } catch (error) {
+ *   if (isWorkflowControlFlowSignal(error)) throw error; // suspend/continue-as-new: rethrow as-is
+ *   await ctx.step('refund', input); // a REAL failure — safe to run cleanup here
+ *   throw error;
+ * }
+ * ```
+ */
+declare function isWorkflowControlFlowSignal(error: unknown): boolean;
+
 /**
  * Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
  * used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
@@ -2320,8 +2383,32 @@ declare class WorkflowEngine {
     /**
      * 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.
+     *
+     * Piggy-backs the signal-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a crash
+     * between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+     * `takeBufferedSignal`, or a signaler's `takeSignalWaiter` → `bufferSignal` → re-check — see
+     * `signal`'s interleaving proof) can leave both rows stranded with nothing left to pair them: the
+     * waiter's turn already suspended, the signaler that buffered it already returned. Event-wait
+     * suspends already carry a `reconcileMs` fallback `wakeAt` (see {@link reconcileWakeAt}) precisely so
+     * they show up HERE — that's what makes this due-timer pass the natural place for the sweep. One
+     * bulk waiter scan, filtered to just this tick's batch, keeps it cheap regardless of store size.
      */
     resumeDueTimers(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * The reconcile safety net's per-run check (see {@link resumeDueTimers}): if this suspended run has
+     * a registered signal waiter AND its token already has a buffered payload, pair and deliver them
+     * directly instead of falling through to a full replay. Event/child/breakpoint waiter tokens are
+     * never buffered (`publishEvent` doesn't buffer, and a child/breakpoint notifies via `signal` only
+     * once its counterpart is already registered) — so `takeBufferedSignal` on those is a guaranteed
+     * miss, and this is naturally signal-only without needing to classify the token.
+     *
+     * Returns `undefined` (not settled — `resumeLeased` proceeds with its normal `resume`) when there's
+     * no waiter or no buffered hit. Deliberately never returns `null`: a delivered signal always resumes
+     * via {@link deliverSignal}, and even a `NamespaceMismatch` there is reported as a real (non-nullish)
+     * result — returning `null` would read as "not settled" to `resumeLeased`'s `??` fallback and
+     * trigger a second, redundant `resume` call on the same run.
+     */
+    private reconcileSignalWaiter;
     /**
      * 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
@@ -2394,6 +2481,37 @@ declare class WorkflowEngine {
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
     }): Promise<number>;
+    /**
+     * Deliver a signal to an already-known waiter: write its resolving `signal:<token>` checkpoint and
+     * resume the run. Shared by {@link signal}'s direct hit, its post-buffer re-check reclaim, and the
+     * due-timer reconcile sweep ({@link reconcileSignalWaiter}) — all three resolve a waiter the exact
+     * same way.
+     */
+    private deliverSignal;
+    /**
+     * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
+     * the run result — or null if no run is (or ends up) waiting for it.
+     *
+     * Race with the waiter side (`waitForSignal`'s check → `putSignalWaiter` → re-check, same shape in
+     * the remote `waitSignal` command): a waiter can register in the sliver between this method's
+     * initial `takeSignalWaiter` miss and its `bufferSignal` write, and the naive old flow (buffer and
+     * return) would then leave BOTH a buffered payload and a registered waiter sitting in the store with
+     * nothing left to pair them — a lost wake, forever suspended.
+     *
+     * The interleaving proof: the waiter side does check → put → re-check, this side does take → buffer
+     * → re-check. Whichever side's SECOND look runs last is guaranteed to observe the other side's
+     * write, because it always follows that write in real time:
+     *  - If the waiter's `put` lands before this method's first `take`, the take just finds it directly
+     *    (the pre-existing, non-racy path).
+     *  - If the waiter's `put` lands after this method's `bufferSignal`, our re-check below either sees
+     *    it (if `put` also lands before the re-check) or the waiter's OWN post-put re-check sees our
+     *    buffer (if `put` lands after our re-check but the waiter hasn't re-checked yet either — its
+     *    re-check strictly follows its own put).
+     *  - If the waiter's `put` lands between this method's `take` and its re-`take`, the re-check below
+     *    catches it.
+     * Either way, the destructive `take*` ops (on the waiter row, on the buffer) arbitrate: whichever
+     * side actually removes the row is the one that delivers, so a signal is never delivered twice.
+     */
     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
@@ -2875,6 +2993,8 @@ declare class GatherError extends Error {
 declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
     readonly wakeAt?: number | undefined;
+    /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+    readonly [CONTROL_FLOW_SIGNAL] = true;
     constructor(wakeAt?: number);
 }
 /**
@@ -2884,6 +3004,8 @@ declare class WorkflowSuspended extends Error {
  */
 declare class ContinueAsNew extends Error {
     readonly input: unknown;
+    /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+    readonly [CONTROL_FLOW_SIGNAL] = true;
     constructor(input: unknown);
 }
 
@@ -3098,6 +3220,7 @@ declare class CodecStateStore implements StateStore {
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     bufferSignal(token: string, payload: unknown): Promise<void>;
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
@@ -3465,6 +3588,7 @@ declare class InMemoryStateStore implements StateStore {
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;
+    removeSignalWaiter(waiter: SignalWaiter): Promise<void>;
     transaction<T>(work: (tx: {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
@@ -3512,4 +3636,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, CONTROL_FLOW_SIGNAL, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, isWorkflowControlFlowSignal, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };