@classytic/arc 2.23.0 → 2.25.0

package/dist/{eventPlugin-A6EbthXR.d.mts → eventPlugin-Bg3cP2_u.d.mts}

@@ -140,12 +140,41 @@ interface RetryOptions {
    */
   transport?: Pick<EventTransport, "deadLetter">;
   /**
-   * Callback when all retries are exhausted. The event is "dead".
-   * Use this to publish to a `$deadLetter` channel, log, alert, etc.
+   * DURABLE dead-letter persistence for exhausted events (custom store,
+   * `$deadLetter` publisher, ...). Treated exactly like
+   * {@link transport}.deadLetter: a failure follows {@link dlqFailureMode}
+   * — rethrow by default, so the transport redelivers instead of
+   * acknowledging an event that is neither processed nor persisted.
    *
-   * Fires in addition to {@link transport} routing if both are set.
+   * This is what `eventPlugin({ deadLetterQueue })` wires. Use
+   * {@link onDead} for metrics/alerts whose failure must NOT affect
+   * acknowledgement.
+   */
+  deadLetter?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  /**
+   * OBSERVABILITY callback when all retries are exhausted (metrics,
+   * alerting, logging). Fires in addition to {@link transport} /
+   * {@link deadLetter} routing. Failures are logged and swallowed — this
+   * callback can never affect whether the event is acknowledged; durable
+   * persistence belongs in {@link deadLetter}.
    */
   onDead?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  /**
+   * What to do when `transport.deadLetter()` ITSELF fails after retries are
+   * exhausted.
+   *
+   *  - `'rethrow'` (default) — the wrapper throws, so the transport treats
+   *    the handler as failed: an at-least-once transport (Redis Streams,
+   *    SQS) keeps the original message pending and redelivers it. The only
+   *    mode that cannot LOSE the event — returning normally would
+   *    acknowledge a message that was neither processed nor persisted.
+   *  - `'log-and-drop'` — log the DLQ failure and return normally,
+   *    acknowledging the message. Only correct when losing the event is
+   *    acceptable (metrics, notifications).
+   *
+   * @default 'rethrow'
+   */
+  dlqFailureMode?: "rethrow" | "log-and-drop";
   /**
    * Optional name for logging + written into `DeadLetteredEvent.handlerName`.
    */
@@ -246,6 +275,12 @@ interface EventPluginOptions {
    * Dead letter queue for events that exhaust all retries.
    * Requires `retry` to be enabled. If `retry` is set but no custom `store`,
    * failed events are published to the `$deadLetter` event type by default.
+   *
+   * The store is DURABLE persistence: if it throws, the wrapped handler
+   * rethrows (per `retry.dlqFailureMode`, default `'rethrow'`) so an
+   * at-least-once transport redelivers instead of acknowledging an event
+   * that was neither processed nor dead-lettered. Metrics/alerting belongs
+   * in `retry.onDead`, whose failures never affect acknowledgement.
    */
   deadLetterQueue?: {
     /** Custom store function. If omitted, publishes to '$deadLetter' event type. */

package/dist/{eventPlugin-DJG2D7sy.mjs → eventPlugin-DrQ_FesK.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { d as createDomainError } from "./errors-DkO8Nk6-.mjs";
-import { n as requestContext } from "./requestContext-BZKOr13H.mjs";
+import { n as requestContext } from "./requestContext-MrlJwECf.mjs";
 import fp from "fastify-plugin";
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 //#region src/events/EventTransport.ts
@@ -118,12 +118,13 @@ var MemoryEventTransport = class {
 * to `unknown` for raw `subscribe(pattern, withRetry(...))` call sites.
 */
 function withRetry(handler, options = {}) {
-	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, transport, onDead, name, logger = console } = options;
+	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, transport, deadLetter, onDead, dlqFailureMode = "rethrow", name, logger = console } = options;
 	const label = name ?? handler.name ?? "anonymous";
 	return async (event) => {
 		const errors = [];
 		let firstFailedAt;
 		let lastFailedAt;
+		let dlqPersistError;
 		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
 			await handler(event);
 			return;
@@ -160,13 +161,21 @@ function withRetry(handler, options = {}) {
 				await transport.deadLetter(dlq);
 			} catch (dlqErr) {
 				logger.error("[Arc Events] transport.deadLetter() failed:", dlqErr);
+				dlqPersistError = dlqErr instanceof Error ? dlqErr : new Error(String(dlqErr));
 			}
 		}
+		if (deadLetter) try {
+			await deadLetter(event, errors);
+		} catch (dlqErr) {
+			logger.error("[Arc Events] deadLetter() persistence failed:", dlqErr);
+			dlqPersistError ??= dlqErr instanceof Error ? dlqErr : new Error(String(dlqErr));
+		}
 		if (onDead) try {
 			await onDead(event, errors);
 		} catch (dlqErr) {
-			logger.error("[Arc Events] Dead letter callback failed:", dlqErr);
+			logger.error("[Arc Events] onDead observability callback failed:", dlqErr);
 		}
+		if (dlqPersistError && dlqFailureMode === "rethrow") throw new Error(`[Arc Events] Handler '${label}' exhausted retries for ${event.type} AND dead-letter persistence failed — rethrowing so the transport redelivers instead of acknowledging a lost event (set dlqFailureMode: 'log-and-drop' to accept loss).`, { cause: dlqPersistError });
 	};
 }
 /**
@@ -279,13 +288,22 @@ const eventPlugin = async (fastify, opts = {}) => {
 			let wrappedHandler = handler;
 			if (retryOpts && pattern !== "$deadLetter") wrappedHandler = withRetry(handler, {
 				...retryOpts,
-				onDead: dlqOpts?.store ?? createDeadLetterPublisher(fastify.events),
+				deadLetter: dlqOpts?.store ?? createDeadLetterPublisher(fastify.events),
 				logger: fastify.log
 			});
 			if (logEvents) fastify.log?.info?.({
 				pattern,
 				retry: !!retryOpts
 			}, "Subscribing to events");
+			if (typeof transport.subscribe !== "function") {
+				const error = /* @__PURE__ */ new Error(`[Arc Events] transport '${transport.name}' is publish-only (no subscribe) — cannot register a handler for '${pattern}'. Use MemoryEventTransport / RedisEventTransport, or a transport that implements subscribe().`);
+				fastify.log?.error?.({
+					transport: transport.name,
+					pattern
+				}, error.message);
+				if (!failOpen) throw error;
+				return () => {};
+			}
 			try {
 				return await transport.subscribe(pattern, wrappedHandler);
 			} catch (error) {

package/dist/events/index.d.mts

@@ -1,7 +1,8 @@
 import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-QmY7A258.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-A6EbthXR.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-Bg3cP2_u.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-iVR2l7aS.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-uIaauNpZ.mjs";
+import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailurePolicy, OutboxStore, OutboxWriteOptions } from "@classytic/primitives/outbox";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/events/eventTypes.d.ts
 /**
@@ -82,279 +83,65 @@ declare class MemoryOutboxStore implements OutboxStore {
   _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
 }
 //#endregion
-//#region src/events/outbox.d.ts
+//#region src/events/outbox/backoff.d.ts
 /**
- * **Terminology (v2.8.1+):**
- *
- * Arc's outbox uses **`delivered`** as the canonical term for "event has been
- * successfully published to the transport and marked by `acknowledge()`".
- *
- * - **`acknowledge()`** is the operation that transitions an event to delivered
- * - **`delivered`** is the resulting state
- * - **`deliveredAt`** is the timestamp column/field in every reference implementation
- *
- * Store authors should use `deliveredAt` for their timestamp field. Older
- * drafts of these docs used `acknowledgedAt` — that is a deprecated alias and
- * should not be used in new code.
- */
-/**
- * Options passed to {@link OutboxStore.save} for richer write semantics.
- * Stores may ignore fields they don't support — contract is best-effort.
- */
-interface OutboxWriteOptions {
-  /**
-   * Host-provided DB session/transaction handle for atomic writes.
-   * Typed as `unknown` so stores can accept any backend (mongoose session,
-   * pg client, Prisma tx, etc.) without Arc taking a peer dep.
-   */
-  readonly session?: unknown;
-  /** Earliest time the event should be visible to relay workers (for delayed publishing) */
-  readonly visibleAt?: Date;
-  /** Idempotency key — stores that support it should dedupe on this */
-  readonly dedupeKey?: string;
-  /** Partition/routing key for sharded transports (Kafka, Redis Streams) */
-  readonly partitionKey?: string;
-  /** Arbitrary headers propagated to the transport layer */
-  readonly headers?: Readonly<Record<string, string>>;
-}
-/**
- * Options for {@link OutboxStore.claimPending} — lease-based work claim.
- * Supports safe multi-worker relay: each worker atomically claims a batch
- * with a lease TTL, preventing duplicate publishes.
- */
-interface OutboxClaimOptions {
-  /** Max events to claim (default: batchSize) */
-  readonly limit?: number;
-  /** Unique identifier for the claiming worker */
-  readonly consumerId?: string;
-  /** Lease duration in ms — claim is released automatically after this */
-  readonly leaseMs?: number;
-  /** Only claim events of these types (optional filter) */
-  readonly types?: readonly string[];
-}
-/** Options for {@link OutboxStore.acknowledge} */
-interface OutboxAcknowledgeOptions {
-  /** Worker identifier — stores may enforce "only owner can ack" */
-  readonly consumerId?: string;
-}
-/** Options for {@link OutboxStore.fail} */
-interface OutboxFailOptions {
-  /** Worker identifier — stores may enforce "only owner can fail" */
-  readonly consumerId?: string;
-  /** Schedule retry for a later time (implements backoff) */
-  readonly retryAt?: Date;
-  /** Move the event to dead-letter state (no further retries) */
-  readonly deadLetter?: boolean;
-}
-/** Normalized error info passed to {@link OutboxStore.fail} */
-interface OutboxErrorInfo {
-  readonly message: string;
-  readonly code?: string;
-}
-/**
- * Context passed to {@link OutboxFailurePolicy}.
+ * Exponential backoff for outbox failure policies — pure date math shared
+ * by `failurePolicy({ attempts })` style handlers.
  */
-interface OutboxFailureContext {
-  /** The event whose delivery just failed */
-  readonly event: DomainEvent;
-  /** The error returned by the transport / handler */
-  readonly error: Error;
-  /**
-   * Attempt count including this failure (1 on the first fail).
-   *
-   * Tracked by {@link EventOutbox} in-process — accurate within a single
-   * relay process, resets on restart. For durable attempt counts, query
-   * your store directly inside the policy.
-   */
-  readonly attempts: number;
-}
 /**
- * Decision returned by {@link OutboxFailurePolicy} — controls how the
- * relay calls `store.fail()` for a failed event.
+ * Options for {@link exponentialBackoff}.
  */
-interface OutboxFailureDecision {
-  /** Schedule retry for this time. Omit for immediate (next-poll) retry. */
-  readonly retryAt?: Date;
+interface ExponentialBackoffOptions {
+  /** Current attempt count (1-indexed — first retry is attempt 1) */
+  readonly attempt: number;
+  /** Base delay in ms (first retry delay). Default: 1000 (1 second) */
+  readonly baseMs?: number;
+  /** Maximum delay in ms — caps exponential growth. Default: 60_000 (1 minute) */
+  readonly maxMs?: number;
   /**
-   * Move the event to dead-letter state (no further retries). When `true`,
-   * {@link RelayResult.deadLettered} is incremented.
+   * Jitter factor [0–1]. The returned delay is multiplied by
+   * `1 + (random * jitter)` to spread retry bursts across workers.
+   * Default: 0.2 (±20%). Set to 0 to disable.
    */
-  readonly deadLetter?: boolean;
+  readonly jitter?: number;
+  /** Reference time (for deterministic tests). Default: `Date.now()` */
+  readonly now?: number;
 }
 /**
- * Centralised retry/DLQ policy evaluated by {@link EventOutbox.relayBatch}
- * on every failure. Returns the options passed to `store.fail()`.
+ * Compute a `retryAt` `Date` using exponential backoff with jitter.
+ *
+ * This is a convenience helper for store authors implementing
+ * {@link OutboxStore.fail}: call it to compute the retry visibility window
+ * based on the event's current attempt count.
  *
- * Typical shape:
+ * Formula: `delay = min(maxMs, baseMs * 2^(attempt - 1)) * (1 + random * jitter)`
+ *
+ * @example Basic usage inside a store's `fail()` method
  * ```typescript
- * failurePolicy: ({ attempts, error }) => {
- *   if (attempts >= 5) return { deadLetter: true };
- *   return { retryAt: exponentialBackoff({ attempt: attempts }) };
+ * async fail(eventId, error, options) {
+ *   const entry = await this.findById(eventId);
+ *   entry.attempts++;
+ *   if (entry.attempts >= MAX_ATTEMPTS) {
+ *     return this.deadLetter(eventId, error);
+ *   }
+ *   const retryAt = exponentialBackoff({ attempt: entry.attempts });
+ *   entry.visibleAt = retryAt;
+ *   await this.update(entry);
  * }
  * ```
  *
- * Without a policy, the relay uses the legacy "immediate re-visibility" fail
- * behaviour (each fail() is equivalent to `{}`).
- */
-type OutboxFailurePolicy = (ctx: OutboxFailureContext) => OutboxFailureDecision | Promise<OutboxFailureDecision>;
-/**
- * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
- * does not own the event's current lease.
- *
- * Stores that enforce lease ownership MUST throw this (not silently return)
- * so {@link EventOutbox} can detect the mismatch and avoid over-counting
- * successful deliveries. {@link EventOutbox.relay} catches it and reports
- * via {@link EventOutboxOptions.onError} instead of counting as relayed.
- */
-declare class OutboxOwnershipError extends Error {
-  readonly eventId: string;
-  readonly attemptedBy: string;
-  readonly currentOwner: string | null;
-  constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
-}
-/** Thrown by {@link EventOutbox.store} when an event is missing `type` or `meta.id`. */
-declare class InvalidOutboxEventError extends Error {
-  constructor(reason: string);
-}
-/**
- * Durable storage contract for the transactional outbox pattern.
- *
- * **Required methods**: `save`, `getPending`, `acknowledge`.
- *
- * **Optional capabilities** — stores opt-in to richer semantics:
- * - `claimPending` — lease-based work claim for multi-worker relay
- * - `fail` — failure tracking with retry scheduling and dead-letter
- * - `purge` — acknowledged event cleanup
- *
- * Arc's {@link EventOutbox} detects capabilities at runtime and degrades
- * gracefully for legacy stores that only implement the required methods.
- *
- * ## Required semantics
- *
- * Implementations MUST honor these contracts — `EventOutbox` depends on them
- * for correctness of at-least-once delivery:
- *
- * 1. **`save` must reject invalid events.** If `event.type` or `event.meta.id`
- *    is missing/empty, throw — do not persist. `EventOutbox.store()` validates
- *    first, but stores should defend against direct-save code paths.
- *
- * 2. **`claimPending` must be atomic.** Two workers calling `claimPending`
- *    concurrently must never receive the same event. Stores backed by SQL/Mongo
- *    should use `SELECT ... FOR UPDATE SKIP LOCKED` or `findOneAndUpdate` with
- *    `{ leaseOwner: null }` as the match condition.
- *
- * 3. **`acknowledge` / `fail` must throw {@link OutboxOwnershipError} on
- *    ownership mismatch.** When `options.consumerId` is provided and does not
- *    match the current lease owner, the method MUST throw — never silently
- *    no-op. `EventOutbox.relay` relies on this signal to avoid counting
- *    hijacked events as successfully relayed.
- *
- * 4. **`acknowledge` on an unknown `eventId` is a no-op.** This keeps relay
- *    idempotent when the store has been purged or the event was manually
- *    removed. Do NOT throw `OutboxOwnershipError` in this case.
- *
- * 5. **`fail` must deterministically update lease/visibility.** On success,
- *    the event MUST become re-claimable (either immediately or at `retryAt`),
- *    or transition to dead-letter state. The lease owner should be cleared.
- *
- * 6. **Malformed events must never be returned by `getPending`/`claimPending`.**
- *    If the store's underlying storage has corrupt rows, the store is
- *    responsible for quarantining them (e.g., direct DB delete, DLQ).
+ * @example Tuning for a faster transport
+ * ```typescript
+ * exponentialBackoff({ attempt: 3, baseMs: 250, maxMs: 10_000, jitter: 0.3 });
+ * // attempt=1 → ~250ms   ±30%
+ * // attempt=2 → ~500ms   ±30%
+ * // attempt=3 → ~1000ms  ±30%
+ * // attempt=10 → capped at 10_000ms
+ * ```
  */
-interface OutboxStore {
-  /**
-   * Save event to outbox (typically called within a business transaction).
-   *
-   * MUST reject events missing `type` or `meta.id` — throw rather than persist.
-   *
-   * @param event - Event to persist
-   * @param options - Optional write metadata (session, visibleAt, dedupeKey, etc.)
-   */
-  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
-  /**
-   * Get pending (unrelayed) events, ordered FIFO.
-   *
-   * This is the legacy/simple pull API. Multi-worker deployments should
-   * prefer {@link OutboxStore.claimPending} to avoid duplicate publishes.
-   *
-   * Events returned by this method MUST be well-formed (valid `type` and
-   * `meta.id`). Corrupt rows must be quarantined by the store, not exposed
-   * to the relay loop.
-   */
-  getPending(limit: number): Promise<DomainEvent[]>;
-  /**
-   * Atomically claim pending events with a lease.
-   *
-   * When implemented, {@link EventOutbox.relay} prefers this over `getPending`
-   * so multi-worker relay is safe: each worker holds an exclusive lease on
-   * its batch, and stale leases are automatically recovered.
-   *
-   * **Atomicity is mandatory**: two concurrent callers must never receive
-   * overlapping events. Use `SELECT ... FOR UPDATE SKIP LOCKED` (SQL) or
-   * a compound condition on `findOneAndUpdate` (Mongo).
-   */
-  claimPending?(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
-  /**
-   * Mark event as successfully relayed.
-   *
-   * **Ownership contract**: If `options.consumerId` is provided and does not
-   * match the current lease owner, this method MUST throw
-   * {@link OutboxOwnershipError}. Unknown `eventId` is a no-op.
-   *
-   * @param eventId - Event ID (from `meta.id`)
-   * @param options - Optional ack metadata (consumerId for lease enforcement)
-   * @throws {@link OutboxOwnershipError} on ownership mismatch
-   */
-  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
-  /**
-   * Record a relay failure. When implemented, {@link EventOutbox.relay} calls
-   * this instead of stopping the batch — enables retry scheduling and DLQ.
-   *
-   * **Ownership contract**: Same as `acknowledge` — MUST throw
-   * {@link OutboxOwnershipError} on mismatch. After a successful call, the
-   * lease owner MUST be cleared and the event MUST be re-claimable (at
-   * `retryAt` if provided) or transitioned to dead-letter.
-   *
-   * @throws {@link OutboxOwnershipError} on ownership mismatch
-   */
-  fail?(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
-  /**
-   * Return events currently in dead-letter state as typed
-   * {@link DeadLetteredEvent} envelopes.
-   *
-   * Closes the loop between {@link OutboxStore.fail} (with `deadLetter: true`)
-   * and {@link import('./EventTransport.js').DeadLetteredEvent} — apps get the
-   * same shape out of the outbox that {@link import('./retry.js').withRetry}
-   * delivers to transports. No hand-building DLQ envelopes.
-   *
-   * Implementations MUST populate `error`, `attempts`, and both
-   * `firstFailedAt` / `lastFailedAt` from whatever they tracked during `fail()`
-   * calls. `handlerName` is optional — stores that don't track it can omit.
-   *
-   * @param limit - Max envelopes to return
-   */
-  getDeadLettered?(limit: number): Promise<DeadLetteredEvent[]>;
-  /**
-   * Purge old **delivered** events (optional, DB-agnostic contract).
-   *
-   * Cleanup is scoped to events in the `delivered` state — events still
-   * pending, failed, or dead-lettered MUST NOT be removed by purge.
-   *
-   * Arc does **not** ship a concrete implementation — your store owns the
-   * cleanup strategy that fits your database:
-   *
-   * - **MongoDB:** TTL index on `deliveredAt` (automatic, zero-code)
-   * - **SQL:** Scheduled `DELETE FROM outbox WHERE status = 'delivered' AND delivered_at < :cutoff`
-   * - **Redis:** Key expiry (`EXPIRE`) on delivered entries
-   *
-   * Called by {@link EventOutbox.purge}. If not implemented, cleanup is
-   * entirely the app's responsibility via native DB tools.
-   *
-   * @param olderThanMs - Remove events delivered more than this many ms ago
-   * @returns Number of purged events
-   */
-  purge?(olderThanMs: number): Promise<number>;
-}
+declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
+//#endregion
+//#region src/events/outbox/relay.d.ts
 /** Reason codes passed to {@link EventOutboxOptions.onError}. */
 type OutboxRelayErrorKind = "publish_failed" | "acknowledge_failed" | "fail_failed" | "ownership_mismatch" | "malformed_event";
 /**
@@ -387,6 +174,14 @@ interface RelayResult {
   readonly deadLettered: number;
   /** Whether `publishMany` was used (true) or per-event `publish` (false) */
   readonly usedPublishMany: boolean;
+  /**
+   * Wall-clock ms spent claiming this batch from the store. With the
+   * portable repository adapter this is ~2 DB round trips; a persistently
+   * high value under low batch sizes points at store latency, not volume.
+   */
+  readonly claimMs?: number;
+  /** Wall-clock ms spent publishing + acknowledging the batch. */
+  readonly publishMs?: number;
 }
 /**
  * Called by {@link EventOutbox.relay} when a non-fatal error occurs during
@@ -598,58 +393,6 @@ declare class EventOutbox {
    */
   purge(olderThanMs?: number): Promise<number>;
 }
-/**
- * Options for {@link exponentialBackoff}.
- */
-interface ExponentialBackoffOptions {
-  /** Current attempt count (1-indexed — first retry is attempt 1) */
-  readonly attempt: number;
-  /** Base delay in ms (first retry delay). Default: 1000 (1 second) */
-  readonly baseMs?: number;
-  /** Maximum delay in ms — caps exponential growth. Default: 60_000 (1 minute) */
-  readonly maxMs?: number;
-  /**
-   * Jitter factor [0–1]. The returned delay is multiplied by
-   * `1 + (random * jitter)` to spread retry bursts across workers.
-   * Default: 0.2 (±20%). Set to 0 to disable.
-   */
-  readonly jitter?: number;
-  /** Reference time (for deterministic tests). Default: `Date.now()` */
-  readonly now?: number;
-}
-/**
- * Compute a `retryAt` `Date` using exponential backoff with jitter.
- *
- * This is a convenience helper for store authors implementing
- * {@link OutboxStore.fail}: call it to compute the retry visibility window
- * based on the event's current attempt count.
- *
- * Formula: `delay = min(maxMs, baseMs * 2^(attempt - 1)) * (1 + random * jitter)`
- *
- * @example Basic usage inside a store's `fail()` method
- * ```typescript
- * async fail(eventId, error, options) {
- *   const entry = await this.findById(eventId);
- *   entry.attempts++;
- *   if (entry.attempts >= MAX_ATTEMPTS) {
- *     return this.deadLetter(eventId, error);
- *   }
- *   const retryAt = exponentialBackoff({ attempt: entry.attempts });
- *   entry.visibleAt = retryAt;
- *   await this.update(entry);
- * }
- * ```
- *
- * @example Tuning for a faster transport
- * ```typescript
- * exponentialBackoff({ attempt: 3, baseMs: 250, maxMs: 10_000, jitter: 0.3 });
- * // attempt=1 → ~250ms   ±30%
- * // attempt=2 → ~500ms   ±30%
- * // attempt=3 → ~1000ms  ±30%
- * // attempt=10 → capped at 10_000ms
- * ```
- */
-declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
 //#endregion
 //#region src/events/repository-outbox-adapter.d.ts
 declare function repositoryAsOutboxStore(repository: RepositoryLike): OutboxStore;
@@ -813,4 +556,4 @@ interface FastifyEventBus {
   };
 }
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type EventDefinitionInput, type EventDefinitionOutput, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };
+export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type EventDefinitionInput, type EventDefinitionOutput, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type ExponentialBackoffOptions, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };