@dudousxd/nestjs-durable-core 0.52.0 → 0.54.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
@@ -638,6 +648,39 @@ interface StateStore {
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
     } | null>;
+    /**
+     * Buffer a published event that matched NO live waiter, so a LATER `ctx.waitForEvent(name, { match })`
+     * still consumes it instead of it being silently dropped — the events analog of {@link bufferSignal}'s
+     * reliability contract for signals, but MATCH-based rather than token-based: an event's buffer is keyed
+     * by `name` alone (many waiters can share a name with different `match` criteria), so consumption is
+     * list ({@link listBufferedEvents}) + evaluate the WAITER's own match predicate + claim
+     * ({@link removeBufferedEvent}) — never a blind take, because the store has no way to know which
+     * candidate a given waiter wants. `input.id` is minted by the caller (engine.publishEvent) so
+     * {@link removeBufferedEvent} can later target this exact row.
+     */
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    /**
+     * Buffered events for `name`, OLDEST (`publishedAt`) first, capped at `limit`. A waiter scans these,
+     * evaluates its own `eventMatches(payload, match)` locally, and claims the one it wants via
+     * {@link removeBufferedEvent} — the match predicate belongs to the WAITER, never the store.
+     */
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    /**
+     * Atomically delete the buffered event `id`. Returns `true` iff a row was actually deleted, `false`
+     * if it was already gone (claimed by a concurrent waiter, reclaimed by `engine.publishEvent`'s own
+     * late re-check, or pruned as expired) — the arbiter under concurrency: whichever caller's delete
+     * returns `true` is the one that gets to deliver the payload; every other caller backs off.
+     */
+    removeBufferedEvent(id: string): Promise<boolean>;
     /**
      * 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
@@ -1997,6 +2040,19 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * Retention for a BUFFERED event that no `waitForEvent` ever claims (see
+     * {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
+     * copy around for a later matching wait). Default `undefined`: keep it until consumed, same as
+     * {@link StateStore.bufferSignal}'s buffered signals — no silent expiry. Set a duration (ms) to
+     * have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
+     * as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
+     * reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
+     * stale buffered event but zero waiters ever registered against it is not visited by this pass; that
+     * is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
+     * bug to route around here.
+     */
+    eventBufferTtlMs?: number | undefined;
     /**
      * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
      * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
@@ -2094,6 +2150,7 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly eventBufferTtlMs;
     private readonly remoteRedispatchMs;
     private readonly remoteRedispatchMax;
     private readonly webhookUrl?;
@@ -2373,8 +2430,46 @@ 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/event-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a
+     * crash between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+     * `takeBufferedSignal`/`listBufferedEvents`, or the other side's `takeSignalWaiter`/fan-out →
+     * `bufferSignal`/`bufferEvent` → re-check — see `signal`'s interleaving proof, which `publishEvent`
+     * mirrors for events) can leave both rows stranded with nothing left to pair them: the waiter's turn
+     * already suspended, the other side 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 (and, for events, also
+     * where an `eventBufferTtlMs` prune piggy-backs — see {@link reconcileBufferedEvent}). 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 OR event waiter and a matching payload is already buffered, pair and deliver
+     * them directly instead of falling through to a full replay. Child/breakpoint waiter tokens are
+     * never buffered (a child/breakpoint notifies via `signal` only once its counterpart is already
+     * registered) — `takeBufferedSignal` on those is a guaranteed miss, so this only ever does real work
+     * for a plain signal or an event waiter (classified via {@link isEventToken}).
+     *
+     * Also opportunistically prunes expired buffered EVENTS for this waiter's name when
+     * {@link eventBufferTtlMs} is set (see its doc — scoped to names a registered waiter references in
+     * this tick's batch, piggy-backing the SAME scan rather than a separate pass), even on a miss.
+     *
+     * 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;
+    /**
+     * The EVENT half of {@link reconcileSignalWaiter}: scan this waiter's name for a matching buffered
+     * event (same list+evaluate+claim shape as `waitForEvent`'s own consumption — the match predicate
+     * belongs to the waiter, never the store), pruning any expired candidates it encounters along the
+     * way when {@link eventBufferTtlMs} is configured. A pruned-but-non-matching candidate does not stop
+     * the scan; only a MATCHING hit (or exhausting the scan window) does.
+     */
+    private reconcileBufferedEvent;
     /**
      * 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
@@ -2443,10 +2538,57 @@ declare class WorkflowEngine {
      *  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).
+     *
+     * Semantics (deliberate — mirrors `signalWithStart`'s reliability contract, so document it exactly):
+     * a publish that resumes ≥1 live waiter, OR routes into an `eventBatch` accumulator / starts ≥1
+     * subscriber, behaves exactly as above and is NOT buffered — fan-out stays live-only, same as
+     * today. A publish that touches NEITHER — no live waiter matched, no subscriber exists/started —
+     * buffers ONE copy (via {@link StateStore.bufferEvent}) unless `opts.buffer === false`, so it isn't
+     * silently dropped just because nobody happened to be listening yet. That buffered copy is consumed
+     * by the FIRST future `ctx.waitForEvent(name, { match })` whose match accepts its payload —
+     * point-to-point on redelivery, by design (only one waiter ever gets it, even though the LIVE path
+     * above is fan-out) — never by a second, later-registered onEvent subscriber (subscriber starts stay
+     * live-only; `opts.id` dedupe applies to those only, unchanged). Right after buffering, this re-checks
+     * `listSignalWaiters` ONCE — sandwich parity with `signal`'s own take → buffer → re-check — so a
+     * waiter that registers in the sliver between the initial miss and the buffer write is still paired
+     * instead of leaving both rows stranded (see `signal`'s interleaving proof; `waitForEvent`'s own
+     * post-registration buffer scan is the mirror-image half of this same race).
      */
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
+        buffer?: boolean;
     }): 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
@@ -3155,18 +3297,46 @@ 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;
     } | null>;
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    removeBufferedEvent(id: string): Promise<boolean>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
+/**
+ * How many candidates a buffered-event scan considers (`listBufferedEvents(name, limit)`) before
+ * giving up. An event's buffer is keyed by `name` only (see {@link eventMatches}'s match-based
+ * consumption), so a hot name with many distinct payloads sitting unclaimed could in principle
+ * accumulate an unbounded backlog; this caps the per-scan cost regardless. Shared by the workflow-ctx
+ * consumer and the engine's reconcile sweep so both see the same window.
+ */
+declare const EVENT_BUFFER_SCAN_LIMIT = 50;
+/** The literal prefix EVERY event-waiter token starts with, regardless of `name` — `eventPrefix(name)`
+ *  always begins with this; exported so a caller that only needs to CLASSIFY a token (not fan out a
+ *  specific name) doesn't have to re-derive or duplicate the literal (see run-waiting.ts's own copy,
+ *  kept in sync with this one, and engine.ts's reconcile sweep). */
+declare const EVENT_TOKEN_PREFIX = "event:";
 /** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
 declare function eventPrefix(name: string): string;
+/** Whether `token` is an event-waiter token (vs. a plain signal / child / webhook / breakpoint one). */
+declare function isEventToken(token: string): boolean;
 /** 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 event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
@@ -3522,6 +3692,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>;
@@ -3531,6 +3702,21 @@ declare class InMemoryStateStore implements StateStore {
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
     } | null>;
+    /** `id -> row`, so {@link removeBufferedEvent} can delete an exact row regardless of iteration
+     *  order — mirrors the SQL stores' PK-by-id delete. */
+    private readonly bufferedEvents;
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    removeBufferedEvent(id: string): Promise<boolean>;
     /**
      * 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
@@ -3569,4 +3755,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, 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 };
+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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, 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, isEventToken, 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
@@ -638,6 +648,39 @@ interface StateStore {
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
     } | null>;
+    /**
+     * Buffer a published event that matched NO live waiter, so a LATER `ctx.waitForEvent(name, { match })`
+     * still consumes it instead of it being silently dropped — the events analog of {@link bufferSignal}'s
+     * reliability contract for signals, but MATCH-based rather than token-based: an event's buffer is keyed
+     * by `name` alone (many waiters can share a name with different `match` criteria), so consumption is
+     * list ({@link listBufferedEvents}) + evaluate the WAITER's own match predicate + claim
+     * ({@link removeBufferedEvent}) — never a blind take, because the store has no way to know which
+     * candidate a given waiter wants. `input.id` is minted by the caller (engine.publishEvent) so
+     * {@link removeBufferedEvent} can later target this exact row.
+     */
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    /**
+     * Buffered events for `name`, OLDEST (`publishedAt`) first, capped at `limit`. A waiter scans these,
+     * evaluates its own `eventMatches(payload, match)` locally, and claims the one it wants via
+     * {@link removeBufferedEvent} — the match predicate belongs to the WAITER, never the store.
+     */
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    /**
+     * Atomically delete the buffered event `id`. Returns `true` iff a row was actually deleted, `false`
+     * if it was already gone (claimed by a concurrent waiter, reclaimed by `engine.publishEvent`'s own
+     * late re-check, or pruned as expired) — the arbiter under concurrency: whichever caller's delete
+     * returns `true` is the one that gets to deliver the payload; every other caller backs off.
+     */
+    removeBufferedEvent(id: string): Promise<boolean>;
     /**
      * 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
@@ -1997,6 +2040,19 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * Retention for a BUFFERED event that no `waitForEvent` ever claims (see
+     * {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
+     * copy around for a later matching wait). Default `undefined`: keep it until consumed, same as
+     * {@link StateStore.bufferSignal}'s buffered signals — no silent expiry. Set a duration (ms) to
+     * have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
+     * as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
+     * reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
+     * stale buffered event but zero waiters ever registered against it is not visited by this pass; that
+     * is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
+     * bug to route around here.
+     */
+    eventBufferTtlMs?: number | undefined;
     /**
      * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
      * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
@@ -2094,6 +2150,7 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly eventBufferTtlMs;
     private readonly remoteRedispatchMs;
     private readonly remoteRedispatchMax;
     private readonly webhookUrl?;
@@ -2373,8 +2430,46 @@ 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/event-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a
+     * crash between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+     * `takeBufferedSignal`/`listBufferedEvents`, or the other side's `takeSignalWaiter`/fan-out →
+     * `bufferSignal`/`bufferEvent` → re-check — see `signal`'s interleaving proof, which `publishEvent`
+     * mirrors for events) can leave both rows stranded with nothing left to pair them: the waiter's turn
+     * already suspended, the other side 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 (and, for events, also
+     * where an `eventBufferTtlMs` prune piggy-backs — see {@link reconcileBufferedEvent}). 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 OR event waiter and a matching payload is already buffered, pair and deliver
+     * them directly instead of falling through to a full replay. Child/breakpoint waiter tokens are
+     * never buffered (a child/breakpoint notifies via `signal` only once its counterpart is already
+     * registered) — `takeBufferedSignal` on those is a guaranteed miss, so this only ever does real work
+     * for a plain signal or an event waiter (classified via {@link isEventToken}).
+     *
+     * Also opportunistically prunes expired buffered EVENTS for this waiter's name when
+     * {@link eventBufferTtlMs} is set (see its doc — scoped to names a registered waiter references in
+     * this tick's batch, piggy-backing the SAME scan rather than a separate pass), even on a miss.
+     *
+     * 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;
+    /**
+     * The EVENT half of {@link reconcileSignalWaiter}: scan this waiter's name for a matching buffered
+     * event (same list+evaluate+claim shape as `waitForEvent`'s own consumption — the match predicate
+     * belongs to the waiter, never the store), pruning any expired candidates it encounters along the
+     * way when {@link eventBufferTtlMs} is configured. A pruned-but-non-matching candidate does not stop
+     * the scan; only a MATCHING hit (or exhausting the scan window) does.
+     */
+    private reconcileBufferedEvent;
     /**
      * 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
@@ -2443,10 +2538,57 @@ declare class WorkflowEngine {
      *  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).
+     *
+     * Semantics (deliberate — mirrors `signalWithStart`'s reliability contract, so document it exactly):
+     * a publish that resumes ≥1 live waiter, OR routes into an `eventBatch` accumulator / starts ≥1
+     * subscriber, behaves exactly as above and is NOT buffered — fan-out stays live-only, same as
+     * today. A publish that touches NEITHER — no live waiter matched, no subscriber exists/started —
+     * buffers ONE copy (via {@link StateStore.bufferEvent}) unless `opts.buffer === false`, so it isn't
+     * silently dropped just because nobody happened to be listening yet. That buffered copy is consumed
+     * by the FIRST future `ctx.waitForEvent(name, { match })` whose match accepts its payload —
+     * point-to-point on redelivery, by design (only one waiter ever gets it, even though the LIVE path
+     * above is fan-out) — never by a second, later-registered onEvent subscriber (subscriber starts stay
+     * live-only; `opts.id` dedupe applies to those only, unchanged). Right after buffering, this re-checks
+     * `listSignalWaiters` ONCE — sandwich parity with `signal`'s own take → buffer → re-check — so a
+     * waiter that registers in the sliver between the initial miss and the buffer write is still paired
+     * instead of leaving both rows stranded (see `signal`'s interleaving proof; `waitForEvent`'s own
+     * post-registration buffer scan is the mirror-image half of this same race).
      */
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
+        buffer?: boolean;
     }): 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
@@ -3155,18 +3297,46 @@ 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;
     } | null>;
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    removeBufferedEvent(id: string): Promise<boolean>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
+/**
+ * How many candidates a buffered-event scan considers (`listBufferedEvents(name, limit)`) before
+ * giving up. An event's buffer is keyed by `name` only (see {@link eventMatches}'s match-based
+ * consumption), so a hot name with many distinct payloads sitting unclaimed could in principle
+ * accumulate an unbounded backlog; this caps the per-scan cost regardless. Shared by the workflow-ctx
+ * consumer and the engine's reconcile sweep so both see the same window.
+ */
+declare const EVENT_BUFFER_SCAN_LIMIT = 50;
+/** The literal prefix EVERY event-waiter token starts with, regardless of `name` — `eventPrefix(name)`
+ *  always begins with this; exported so a caller that only needs to CLASSIFY a token (not fan out a
+ *  specific name) doesn't have to re-derive or duplicate the literal (see run-waiting.ts's own copy,
+ *  kept in sync with this one, and engine.ts's reconcile sweep). */
+declare const EVENT_TOKEN_PREFIX = "event:";
 /** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
 declare function eventPrefix(name: string): string;
+/** Whether `token` is an event-waiter token (vs. a plain signal / child / webhook / breakpoint one). */
+declare function isEventToken(token: string): boolean;
 /** 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 event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
@@ -3522,6 +3692,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>;
@@ -3531,6 +3702,21 @@ declare class InMemoryStateStore implements StateStore {
     takeBufferedSignal(token: string): Promise<{
         payload: unknown;
     } | null>;
+    /** `id -> row`, so {@link removeBufferedEvent} can delete an exact row regardless of iteration
+     *  order — mirrors the SQL stores' PK-by-id delete. */
+    private readonly bufferedEvents;
+    bufferEvent(input: {
+        name: string;
+        payload: unknown;
+        id: string;
+        publishedAt: number;
+    }): Promise<void>;
+    listBufferedEvents(name: string, limit: number): Promise<Array<{
+        id: string;
+        payload: unknown;
+        publishedAt: number;
+    }>>;
+    removeBufferedEvent(id: string): Promise<boolean>;
     /**
      * 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
@@ -3569,4 +3755,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, 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 };
+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, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, 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, isEventToken, isWorkflowControlFlowSignal, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };