@classytic/arc 2.8.0 → 2.8.1

package/dist/{errorHandler-BW08lEiy.mjs → errorHandler-Cw34h_om.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { p as isArcError } from "./errors-Cg58SLNi.mjs";
+import { p as isArcError } from "./errors-BF2bIOIS.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/errorHandler.ts
 var errorHandler_exports = /* @__PURE__ */ __exportAll({ errorHandlerPlugin: () => errorHandlerPlugin });

package/dist/{errorHandler-BeN-ERN7.d.mts → errorHandler-DJ7OAB2V.d.mts}

@@ -1,4 +1,4 @@
-import { t as DomainEvent } from "./EventTransport-n1KBxC_N.mjs";
+import { t as DomainEvent } from "./EventTransport-CLXJUzyT.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/plugins/caching.d.ts

package/dist/{eventPlugin-CAOWMQS8.d.mts → eventPlugin-Cdjwo0Gv.d.mts}

@@ -1,4 +1,4 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-n1KBxC_N.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-CLXJUzyT.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/events/defineEvent.d.ts

package/dist/{eventPlugin-x4jo3sG0.mjs → eventPlugin-XijlQmlL.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { t as requestContext } from "./requestContext-xHIKedG6.mjs";
+import { t as requestContext } from "./requestContext-DYvHl113.mjs";
 import fp from "fastify-plugin";
 //#region src/events/EventTransport.ts
 /**
@@ -33,6 +33,24 @@ var MemoryEventTransport = class {
 			this.logger.error(`[EventTransport] Handler error for ${event.type}:`, err);
 		}
 	}
+	/**
+	* Reference `publishMany` implementation — delegates to `publish()` in order.
+	*
+	* Production transports (Kafka, Redis pipeline, SQS batch) should override
+	* this with a single batched network call. Memory transport has nothing to
+	* batch, so we just loop — the loop still returns a proper result map so
+	* `EventOutbox.relay` can exercise the batched code path in tests.
+	*/
+	async publishMany(events) {
+		const results = /* @__PURE__ */ new Map();
+		for (const event of events) try {
+			await this.publish(event);
+			results.set(event.meta.id, null);
+		} catch (err) {
+			results.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+		}
+		return results;
+	}
 	async subscribe(pattern, handler) {
 		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
 		this.handlers.get(pattern)?.add(handler);

package/dist/events/index.d.mts

@@ -1,7 +1,7 @@
-import { a as MemoryEventTransport, i as EventTransport, n as EventHandler, o as MemoryEventTransportOptions, r as EventLogger, s as createEvent, t as DomainEvent } from "../EventTransport-n1KBxC_N.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-CAOWMQS8.mjs";
+import { a as MemoryEventTransport, c as createEvent, i as EventTransport, n as EventHandler, o as MemoryEventTransportOptions, r as EventLogger, s as PublishManyResult, t as DomainEvent } from "../EventTransport-CLXJUzyT.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-Cdjwo0Gv.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-CF1lrKVk.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-BgrYzpeq.mjs";
 
 //#region src/events/eventTypes.d.ts
 /**
@@ -51,68 +51,439 @@ declare const CACHE_EVENTS: Readonly<{
 type CacheEvent = (typeof CACHE_EVENTS)[keyof typeof CACHE_EVENTS];
 //#endregion
 //#region src/events/outbox.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;
+}
+/**
+ * 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).
+ */
 interface OutboxStore {
-  /** Save event to outbox (called within business transaction) */
-  save(event: DomainEvent): Promise<void>;
-  /** Get pending (unrelayed) events, ordered FIFO */
+  /**
+   * 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[]>;
-  /** Mark event as successfully relayed */
-  acknowledge(eventId: string): Promise<void>;
   /**
-   * Purge old acknowledged events (optional, DB-agnostic contract).
+   * 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>;
+  /**
+   * 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 `acknowledgedAt` (automatic, zero-code)
-   * - **SQL:** Scheduled `DELETE FROM outbox WHERE acknowledged_at < :cutoff`
-   * - **Redis:** Key expiry (`EXPIRE`) on acknowledged entries
+   * - **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 acknowledged more than this many ms ago
+   * @param olderThanMs - Remove events delivered more than this many ms ago
    * @returns Number of purged events
    */
   purge?(olderThanMs: number): Promise<number>;
 }
+/** Reason codes passed to {@link EventOutboxOptions.onError}. */
+type OutboxRelayErrorKind = "publish_failed" | "acknowledge_failed" | "fail_failed" | "ownership_mismatch" | "malformed_event";
+/**
+ * Rich per-batch outcome returned by {@link EventOutbox.relayBatch}.
+ *
+ * Useful for operational dashboards, alerting thresholds, and test assertions.
+ * The simpler {@link EventOutbox.relay} returns just the `relayed` count for
+ * backward compatibility.
+ */
+interface RelayResult {
+  /** Number of events successfully published AND acknowledged */
+  readonly relayed: number;
+  /** Number of events claimed and attempted in this batch */
+  readonly attempted: number;
+  /** Number of publish failures (transport rejected the event) */
+  readonly publishFailed: number;
+  /** Number of acknowledge failures after successful publish (at-least-once replay risk) */
+  readonly ackFailed: number;
+  /** Number of ownership mismatches (our lease expired mid-flight) */
+  readonly ownershipMismatches: number;
+  /** Number of malformed events encountered (aborts the batch) */
+  readonly malformed: number;
+  /** Number of fail() calls that themselves threw (store bugs / contention) */
+  readonly failHookErrors: number;
+  /** Whether `publishMany` was used (true) or per-event `publish` (false) */
+  readonly usedPublishMany: boolean;
+}
+/**
+ * Called by {@link EventOutbox.relay} when a non-fatal error occurs during
+ * a batch. Used for logging and metrics. Must not throw.
+ */
+type OutboxRelayErrorHandler = (info: {
+  readonly kind: OutboxRelayErrorKind;
+  readonly event?: DomainEvent;
+  readonly error: Error;
+}) => void;
 interface EventOutboxOptions {
   /** Outbox store for persistence */
-  store: OutboxStore;
+  readonly store: OutboxStore;
   /** Transport to relay events to (optional — can relay later) */
-  transport?: EventTransport;
+  readonly transport?: EventTransport;
   /** Max events per relay batch (default: 100) */
-  batchSize?: number;
+  readonly batchSize?: number;
+  /**
+   * Unique identifier for this relay worker. Used when the store supports
+   * `claimPending`/`fail` to enforce lease ownership. Defaults to a random ID.
+   */
+  readonly consumerId?: string;
+  /**
+   * Lease duration in ms for claimed events. Only used when the store
+   * supports `claimPending`. Default: 30 seconds.
+   */
+  readonly leaseMs?: number;
+  /**
+   * Callback for non-fatal errors during relay: publish failures,
+   * ownership mismatches, ack/fail errors, malformed events. Use this for
+   * logging and metrics. Must not throw — exceptions are swallowed.
+   */
+  readonly onError?: OutboxRelayErrorHandler;
+  /**
+   * Enable {@link EventTransport.publishMany} when the transport implements it.
+   * Default: `true`. Set to `false` to force per-event `publish()` — useful
+   * for transports where strict event-order observability matters more than
+   * throughput, or to debug batch-specific issues.
+   */
+  readonly usePublishMany?: boolean;
 }
 declare class EventOutbox {
   private readonly _store;
   private readonly _transport?;
   private readonly _batchSize;
+  private readonly _consumerId;
+  private readonly _leaseMs;
+  private readonly _onError?;
+  private readonly _usePublishMany;
   constructor(opts: EventOutboxOptions);
-  /** Store event in outbox (call within your DB transaction) */
-  store(event: DomainEvent): Promise<void>;
+  /** Unique consumer ID used for lease ownership when the store supports claims */
+  get consumerId(): string;
+  /**
+   * Store event in outbox.
+   *
+   * Validates that `event.type` and `event.meta.id` are present — throws
+   * {@link InvalidOutboxEventError} otherwise, so corrupt rows can never
+   * be persisted via this API.
+   *
+   * Pass `options.session` to participate in a host-managed DB transaction
+   * (store must support session-aware writes). Other options (`visibleAt`,
+   * `dedupeKey`, `partitionKey`, `headers`) are forwarded to stores that
+   * implement them and ignored otherwise.
+   */
+  store(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
+  private _reportError;
   /**
-   * Relay pending events to transport.
+   * Relay pending events to transport and return the number of successful
+   * publish+acknowledge pairs.
    *
-   * Processes events in FIFO order up to `batchSize`. Stops on the first
-   * transport failure — remaining events stay pending for the next relay call.
+   * For richer observability (per-kind counts, publishMany detection, etc.)
+   * use {@link relayBatch} which returns a {@link RelayResult}. This method
+   * is the backward-compatible shortcut that returns just the count.
    *
-   * @returns Number of successfully published events in this batch
+   * @returns Number of successfully published AND acknowledged events
    */
   relay(): Promise<number>;
   /**
-   * Purge old acknowledged events from the outbox store.
+   * Relay a batch of pending events to the transport and return a rich
+   * {@link RelayResult} describing the outcome of each event.
+   *
+   * Behavior summary:
+   *
+   * - **Claim path**: uses {@link OutboxStore.claimPending} when the store
+   *   supports it (safe for multi-worker relay) or falls back to
+   *   {@link OutboxStore.getPending} (single-worker only).
+   *
+   * - **Publish path**: if the transport implements
+   *   {@link EventTransport.publishMany} and `usePublishMany` is not disabled,
+   *   the entire batch is sent in one call. Otherwise each event is published
+   *   individually. Either way, per-event outcomes are tracked.
+   *
+   * - **Failure path**: if the store implements `fail`, per-event failures
+   *   are reported via `store.fail(...)` and the batch continues. Without
+   *   `fail`, the batch stops on the first failure (legacy behavior).
+   *
+   * - **Malformed events**: events missing `type` or `meta.id` abort the
+   *   batch — a well-behaved store must never return them (see
+   *   {@link OutboxStore} semantics #6). The error is reported via `onError`.
+   *
+   * - **Ownership mismatches**: if `acknowledge`/`fail` throws
+   *   {@link OutboxOwnershipError} (our lease expired and another worker
+   *   claimed the event), the event is NOT counted as relayed. The other
+   *   worker will re-publish — at-least-once semantics preserved.
+   *
+   * @returns Per-kind outcome counts for the batch
+   */
+  relayBatch(): Promise<RelayResult>;
+  /**
+   * Purge old **delivered** events from the outbox store.
    * Delegates to `store.purge()` if implemented; no-op otherwise.
-   * @param olderThanMs - Remove events acknowledged more than this many ms ago (default: 7 days)
+   * @param olderThanMs - Remove events delivered more than this many ms ago (default: 7 days)
    * @returns Number of purged events, or 0 if store doesn't support purge
    */
   purge(olderThanMs?: number): Promise<number>;
 }
+interface MemoryEntry {
+  event: DomainEvent;
+  status: "pending" | "delivered" | "dead_letter";
+  attempts: number;
+  visibleAt: number;
+  leaseOwner: string | null;
+  leaseExpiresAt: number;
+  deliveredAt: number | null;
+  lastError: OutboxErrorInfo | null;
+  dedupeKey?: string;
+}
+/**
+ * In-memory outbox store — reference implementation supporting the full
+ * capability set (claim/lease, fail/retry, dedupe, visibleAt).
+ *
+ * For dev/testing only. Production deployments should use a durable store
+ * backed by the app's database.
+ */
 declare class MemoryOutboxStore implements OutboxStore {
-  private events;
-  save(event: DomainEvent): Promise<void>;
+  private readonly entries;
+  private readonly seenDedupeKeys;
+  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
   getPending(limit: number): Promise<DomainEvent[]>;
-  acknowledge(eventId: string): Promise<void>;
+  claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
+  purge(olderThanMs: number): Promise<number>;
+  /** Test helper: inspect entry by id */
+  _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
 }
+/**
+ * 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
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxStore, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RetryOptions, type ValidationResult, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, withRetry };
+export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, withRetry };