@dudousxd/nestjs-durable-core 0.53.0 → 0.54.0

package/dist/index.d.cts

@@ -648,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
@@ -2007,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
@@ -2104,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?;
@@ -2384,23 +2431,29 @@ 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.
+     * 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 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.
+     * 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
@@ -2409,6 +2462,14 @@ declare class WorkflowEngine {
      * 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
@@ -2477,9 +2538,25 @@ 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
@@ -3225,14 +3302,41 @@ declare class CodecStateStore implements StateStore {
     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
@@ -3598,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
@@ -3636,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

@@ -648,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
@@ -2007,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
@@ -2104,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?;
@@ -2384,23 +2431,29 @@ 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.
+     * 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 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.
+     * 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
@@ -2409,6 +2462,14 @@ declare class WorkflowEngine {
      * 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
@@ -2477,9 +2538,25 @@ 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
@@ -3225,14 +3302,41 @@ declare class CodecStateStore implements StateStore {
     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
@@ -3598,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
@@ -3636,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 };