@classytic/arc 2.31.0 → 2.33.0

package/dist/{errorHandler-C5NeD6bT.mjs → errorHandler-C7xBqHsI.mjs}

@@ -1,9 +1,35 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
-import { m as statusToArcCode, p as isArcError } from "./errors-Cj42AntO.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
+import { m as statusToArcCode, p as isArcError } from "./errors-Cd_yy7aW.mjs";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+import { isProductionEnv } from "@classytic/primitives/environment";
 import fp from "fastify-plugin";
 //#region src/plugins/errorHandler.ts
+/**
+* Global error handler — converts every thrown error into the canonical
+* `ErrorContract` wire shape from `@classytic/repo-core/errors`.
+*
+* Wire shape (no envelope; HTTP status discriminates success vs error):
+* ```
+* { code, message, status, details?, meta?, correlationId? }
+* ```
+*
+* Throw anywhere — controller, hook, middleware — and the response is
+* automatically converted. `ArcError` instances and any `HttpError`-shaped
+* throw (mongokit, sqlitekit, streamline, prismakit) flow through the
+* canonical converter unchanged.
+*
+* Custom domain error classes register via `errorMappers` (instanceof) or
+* `errorMap` (by name). Driver-specific duplicate-key violations
+* (Mongo 11000, Prisma P2002, Postgres 23505, MySQL 1062, SQLite
+* UNIQUE) collapse to a 409 with `code: 'arc.conflict'`.
+*
+* @example
+* await fastify.register(errorHandlerPlugin, {
+*   includeStack: process.env.NODE_ENV !== 'production',
+*   onError: (err) => Sentry.captureException(err),
+* });
+*/
 var errorHandler_exports = /* @__PURE__ */ __exportAll({
 	defaultIsDuplicateKeyError: () => defaultIsDuplicateKeyError,
 	errorHandlerPlugin: () => errorHandlerPlugin
@@ -94,8 +120,19 @@ function mongooseValidationDetails(errors) {
 	}));
 }
 async function errorHandlerPluginFn(fastify, options = {}) {
-	const isProduction = process.env.NODE_ENV === "production";
-	const { includeStack = !isProduction, exposeInternalMessages = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
+	/**
+	* The FALLBACK for a plugin registered directly (`fastify.register(errorHandlerPlugin)`), which
+	* has no access to `createApp`'s resolved `preset`. Composed through `createApp`, both switches
+	* arrive already derived from the preset and this default never applies — see
+	* `factory/registerAuth.ts#registerErrorHandler`.
+	*
+	* Via the shared classifier, NOT `process.env.NODE_ENV === "production"`. That comparison
+	* recognises only the long spelling, so a deployment using `NODE_ENV=prod` got BOTH switches
+	* true: stack traces AND the raw thrown message of a 500 returned to clients, in production,
+	* with nothing to indicate it.
+	*/
+	const productionEnv = isProductionEnv(process.env.NODE_ENV);
+	const { includeStack = !productionEnv, exposeInternalMessages = !productionEnv, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
 	fastify.setErrorHandler(async (error, request, reply) => {
 		if (onError) try {
 			await onError(error, request);

package/dist/{errorHandler-CpYUJmPA.d.mts → errorHandler-DI5AN2b5.d.mts}

@@ -17,11 +17,22 @@ interface ErrorMapper<T extends Error = Error> {
   };
 }
 interface ErrorHandlerOptions {
-  /** Include `meta.stack` on the wire (defaults to `NODE_ENV !== 'production'`). */
+  /**
+   * Include `meta.stack` on the wire.
+   *
+   * Under `createApp`, defaults from the resolved `preset` (falling back to the
+   * environment via `isProductionEnv`, which knows both `production` and `prod`).
+   * Registering this plugin DIRECTLY skips that, and the default is the
+   * environment alone.
+   */
   includeStack?: boolean;
   /**
-   * Ship the raw `error.message` of UNCLASSIFIED 500s on the wire
-   * (defaults to `NODE_ENV !== 'production'`).
+   * Ship the raw `error.message` of UNCLASSIFIED 500s on the wire.
+   *
+   * Same derivation as {@link includeStack}: the `preset` under `createApp`,
+   * otherwise the environment. Both are host keys, so stating one no longer
+   * silently resets the other — `registerErrorHandler` MERGES them over the
+   * derived pair instead of replacing it.
    *
    * Only the `arc.internal_error` fallback is affected — an unclassified
    * throw carries whatever some driver/library put in the message (connection

package/dist/{errors-Cj42AntO.mjs → errors-Cd_yy7aW.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/utils/errors.ts
 /**
 * Base Arc Error. Implements the canonical `HttpError` contract — `status`

package/dist/{eventPlugin-GF5nnBIq.d.mts → eventPlugin-DSNEZWfV.d.mts}

@@ -1,5 +1,5 @@
 
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-2uVV34WU.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-BEVP50ka.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/events/defineEvent.d.ts
 interface EventSchema {
@@ -227,6 +227,34 @@ declare function createDeadLetterPublisher(events: {
 interface EventPluginOptions {
   /** Event transport (default: MemoryEventTransport) */
   transport?: EventTransport;
+  /**
+   * Declare that this deployment is ONE process on purpose — the in-memory
+   * transport is its intended configuration, not a forgotten default.
+   *
+   * A single-node host (a small SaaS on one VPS, an on-prem install, a
+   * personal deployment that cannot justify Redis) is a legitimate production
+   * topology: with one process there are no other instances to broadcast to,
+   * so the memory transport is not a compromise — it is exactly sufficient.
+   * Without this flag arc cannot tell that apart from the accidental default
+   * (a multi-replica deployment that forgot to configure Redis), so it warns
+   * on every boot. Setting `singleProcess: true` states the topology and
+   * downgrades the warn to a factual info line.
+   *
+   * What it does NOT change: in-process delivery semantics. Events still
+   * vanish with the process — subscribers that were offline missed them. For
+   * durable at-least-once delivery on a single node, pair this with the
+   * repository-backed outbox (`createOutboxModule` + `repositoryAsOutboxStore`):
+   * events are committed to YOUR database and relayed to the in-process
+   * subscribers, so a crash between write and delivery replays on restart —
+   * no Redis anywhere in that path.
+   *
+   * Scale-out later by swapping the transport (Redis Streams etc.) and
+   * removing this flag; handler code is transport-independent and unchanged.
+   *
+   * Ignored (with a warn) when a non-memory transport is configured — the
+   * declaration would be describing a topology the transport contradicts.
+   */
+  singleProcess?: boolean;
   /** Enable event logging (default: false) */
   logEvents?: boolean;
   /**

package/dist/{eventPlugin-CkffEihm.mjs → eventPlugin-Dar8qRaj.mjs}

@@ -1,9 +1,10 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { d as createDomainError } from "./errors-Cj42AntO.mjs";
-import { n as requestContext } from "./requestContext-2TxXOJ7T.mjs";
-import { n as createEvent, t as MemoryEventTransport } from "./EventTransport-9mlTgqzE.mjs";
+import { d as createDomainError } from "./errors-Cd_yy7aW.mjs";
+import { n as requestContext } from "./requestContext-uYE35JxI.mjs";
+import { n as MemoryEventTransport, r as createEvent, t as ARC_EVENT_TRANSPORT } from "./EventTransport-tq4CEB-q.mjs";
+import { isProductionEnv } from "@classytic/primitives/environment";
 import fp from "fastify-plugin";
 //#region src/events/retry.ts
 /**
@@ -116,14 +117,39 @@ function sleep(ms) {
 }
 //#endregion
 //#region src/events/eventPlugin.ts
+/**
+* Event Plugin
+*
+* Integrates event transport with Fastify.
+* Defaults to in-memory transport; configure durable transport for production.
+*
+* @example
+* // Development (in-memory)
+* await fastify.register(eventPlugin);
+*
+* // Production (Redis)
+* await fastify.register(eventPlugin, {
+*   transport: new RedisEventTransport({ url: process.env.REDIS_URL }),
+* });
+*/
 var eventPlugin_exports = /* @__PURE__ */ __exportAll({
 	default: () => eventPlugin_default,
 	eventPlugin: () => eventPlugin
 });
 const eventPlugin = async (fastify, opts = {}) => {
-	const { transport = new MemoryEventTransport(), logEvents = false, failOpen = true, retry: retryOpts, deadLetterQueue: dlqOpts, wal, onPublish, onPublishError, registry, validateMode: rawValidateMode, warnOnDuplicate: rawWarnOnDuplicate } = opts;
+	/**
+	* Lifecycle ownership: arc closes ONLY the transport it built.
+	*
+	* A host-supplied transport (a Redis client wrapper, typically) may be
+	* shared with other apps in the process or outlive this one — closing it
+	* on this app's shutdown severs a connection arc does not own. Read
+	* BEFORE the destructure, because the default below is indistinguishable
+	* from a host value afterwards.
+	*/
+	const ownsTransport = opts.transport === void 0;
+	const { transport = new MemoryEventTransport(), singleProcess = false, logEvents = false, failOpen = true, retry: retryOpts, deadLetterQueue: dlqOpts, wal, onPublish, onPublishError, registry, validateMode: rawValidateMode, warnOnDuplicate: rawWarnOnDuplicate } = opts;
 	const validateMode = rawValidateMode ?? (registry ? "warn" : "off");
-	const warnOnDuplicate = rawWarnOnDuplicate ?? process.env.NODE_ENV !== "production";
+	const warnOnDuplicate = rawWarnOnDuplicate ?? !isProductionEnv(process.env.NODE_ENV);
 	const DUP_WINDOW_MS = 5e3;
 	const recentPublishes = /* @__PURE__ */ new Map();
 	const evictExpiredPublishes = (now) => {
@@ -139,10 +165,11 @@ const eventPlugin = async (fastify, opts = {}) => {
 			if (type.startsWith("$") && type !== "$deadLetter") throw new Error(`[Arc Events] Event type '${type}' uses reserved '$' prefix`);
 			if (type.length > 256) throw new Error("[Arc Events] Event type exceeds 256 characters");
 			const store = requestContext.get();
-			const event = createEvent(type, payload, {
+			const enrichedMeta = {
 				...store?.requestId && !meta?.correlationId ? { correlationId: store.requestId } : {},
 				...meta
-			});
+			};
+			const event = createEvent(type, payload, enrichedMeta);
 			if (warnOnDuplicate && event.meta.correlationId) {
 				const now = Date.now();
 				evictExpiredPublishes(now);
@@ -219,7 +246,32 @@ const eventPlugin = async (fastify, opts = {}) => {
 		transportName: transport.name,
 		registry
 	});
+	/**
+	* The RAW transport, for machinery that must observe publish failure.
+	*
+	* `fastify.events` is a REQUEST-FACING FACADE, and two of its properties make
+	* it wrong for a relay to publish through:
+	*
+	*   1. Different signature — `publish(type, payload, meta?)` vs the
+	*      transport's `publish(event)`. Handing it a `DomainEvent` makes the
+	*      envelope the `type` argument, which fails the non-empty-string guard.
+	*      Measured on the default `createOutboxModule()` path: subscribers saw
+	*      NOTHING and every relay tick reported `publishFailed: 1`, so events
+	*      retried to dead-letter and never arrived.
+	*   2. Fail-open — the facade catches publish errors and only rethrows when
+	*      `failOpen: false`. That is correct for HTTP (a transport outage must
+	*      not fail a user's request) and fatal for an outbox: a swallowed error
+	*      reads as success, the row is acknowledged, and the durability the
+	*      outbox exists to provide is gone.
+	*
+	* So the boundary is explicit: **the facade may fail open; the relay must
+	* see the truth.** Decorated under a `Symbol.for` key — not part of the
+	* public `EventsDecorator` surface, and registry-keyed so it still resolves
+	* if a host's graph ends up with two arc copies.
+	*/
+	fastify.decorate(ARC_EVENT_TRANSPORT, transport);
 	fastify.addHook("onClose", async () => {
+		if (!ownsTransport) return;
 		try {
 			await transport.close?.();
 		} catch (error) {
@@ -230,8 +282,13 @@ const eventPlugin = async (fastify, opts = {}) => {
 			if (!failOpen) throw error;
 		}
 	});
-	if (transport.name === "memory") fastify.log?.warn?.("[Arc Events] Using in-memory transport. Events will not persist or scale across instances. For production, configure a durable transport (Redis, RabbitMQ, etc.)");
-	else fastify.log?.debug?.(`[Arc Events] Using ${transport.name} transport`);
+	if (transport.name === "memory") {
+		if (singleProcess) fastify.log?.info?.("[Arc Events] In-memory transport, declared single-process. Events are delivered in-process only and do not survive a crash or restart; subscribers in other processes (if any ever exist) will not receive them. For durability on this single node, pair with the repository-backed outbox (createOutboxModule + repositoryAsOutboxStore) — no Redis required. That covers a crash BEFORE publish; to also retry a THROWING handler, construct the transport with `onHandlerError: 'throw'` (by default a handler error is logged and the outbox row is still acknowledged).");
+		else fastify.log?.warn?.("[Arc Events] Using in-memory transport. Events will not persist or scale across instances. If this deployment is intentionally a single process, declare it — `eventPlugin, { singleProcess: true }` — and this becomes a supported configuration instead of a warning. Otherwise configure a durable transport (Redis Streams, RabbitMQ, etc.)");
+	} else {
+		if (singleProcess) fastify.log?.warn?.(`[Arc Events] \`singleProcess: true\` is declared but the '${transport.name}' transport is configured — a cross-instance transport contradicts a single-process declaration. The flag is ignored; remove it or switch back to the memory transport.`);
+		fastify.log?.debug?.(`[Arc Events] Using ${transport.name} transport`);
+	}
 };
 var eventPlugin_default = fp(eventPlugin, {
 	name: "arc-events",

package/dist/events/index.d.mts

@@ -1,9 +1,10 @@
 
-import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-2uVV34WU.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-GF5nnBIq.mjs";
+import { i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions } from "../EventTransport-BEVP50ka.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-DSNEZWfV.mjs";
+import { a as EventOutbox, c as OutboxRelayErrorKind, i as MemoryOutboxStore, l as RelayResult, n as OutboxModuleOptions, o as EventOutboxOptions, r as createOutboxModule, s as OutboxRelayErrorHandler, t as OutboxModuleExports } from "../outbox-module-D-VFq37T.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-qN6A-RFv.mjs";
-import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailurePolicy, OutboxStore, OutboxWriteOptions } from "@classytic/primitives/outbox";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-mwLWlfHG.mjs";
+import { OutboxStore } from "@classytic/primitives/outbox";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/events/eventTypes.d.ts
 /**
@@ -56,44 +57,6 @@ declare const CACHE_EVENTS: Readonly<{
 /** Type for cache event names */
 type CacheEvent = (typeof CACHE_EVENTS)[keyof typeof CACHE_EVENTS];
 //#endregion
-//#region src/events/memory-outbox.d.ts
-interface MemoryEntry {
-  event: DomainEvent;
-  status: "pending" | "delivered" | "dead_letter";
-  attempts: number;
-  visibleAt: number;
-  leaseOwner: string | null;
-  leaseExpiresAt: number;
-  deliveredAt: number | null;
-  firstFailedAt: number | null;
-  lastFailedAt: number | null;
-  lastError: OutboxErrorInfo | null;
-  dedupeKey?: string;
-}
-declare class MemoryOutboxStore implements OutboxStore {
-  private readonly entries;
-  private readonly seenDedupeKeys;
-  /**
-   * Drop every entry (including delivered / failed / dead-lettered rows) and
-   * the dedupe-key memory.
-   *
-   * For tests only — it is the in-memory analogue of truncating the table, and
-   * exists so a suite can isolate cases against ONE store instance (the
-   * `reset` hook of `runOutboxStoreContract`). Not part of `OutboxStore`; a
-   * production store must never expose this.
-   */
-  clear(): void;
-  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
-  getPending(limit: number): Promise<DomainEvent[]>;
-  claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
-  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
-  fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
-  getDeadLettered(limit: number): Promise<DeadLetteredEvent[]>;
-  purge(olderThanMs: number): Promise<number>;
-  /** Test helper: inspect entry by id */
-  _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
-}
-//#endregion
 //#region src/events/outbox/backoff.d.ts
 /**
  * Exponential backoff for outbox failure policies — pure date math shared
@@ -152,259 +115,6 @@ interface ExponentialBackoffOptions {
  */
 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";
-/**
- * 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;
-  /**
-   * Number of events moved to dead-letter state this batch via the configured
-   * {@link OutboxFailurePolicy}. Zero when no policy is set or no failure
-   * tripped the `deadLetter` branch.
-   */
-  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
- * 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 {
-  /**
-   * Repository managing the outbox collection. Arc consumes it directly —
-   * no wrapper classes. Requires `create`, `getOne`, `findAll`,
-   * `deleteMany`, and `findOneAndUpdate` from `RepositoryLike` (mongokit
-   * ≥3.8 satisfies all of these). Takes precedence over `store` when both
-   * are passed.
-   *
-   * Use this for the common path where the outbox lives in your primary
-   * database. Use `store` for non-repository backends (memory / custom).
-   */
-  readonly repository?: RepositoryLike;
-  /**
-   * Non-repository outbox store. Use when your backend isn't a repository
-   * (memory for tests, Kafka, DynamoDB, custom). Ignored if `repository`
-   * is also passed.
-   */
-  readonly store?: OutboxStore;
-  /** Transport to relay events to (optional — can relay later) */
-  readonly transport?: EventTransport;
-  /** Max events per relay batch (default: 100) */
-  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;
-  /**
-   * Retry/DLQ decision policy. When set, {@link EventOutbox.relayBatch}
-   * invokes this on every failure and uses the returned options for
-   * `store.fail()`. Centralises the "after N fails, dead-letter" rule so
-   * apps don't recompute `exponentialBackoff` + escalation thresholds on
-   * every failure site.
-   *
-   * Without a policy, `fail()` is called with `{}` (immediate re-visibility
-   * on next poll) — legacy behaviour, unchanged.
-   */
-  readonly failurePolicy?: OutboxFailurePolicy;
-  /**
-   * Unit-of-Work session provider (AsyncLocalStorage integration).
-   *
-   * When set, `store()` calls this to get the active DB session and uses
-   * it as `OutboxWriteOptions.session` — **only when the caller has not
-   * already passed an explicit `options.session`**. This eliminates the
-   * boilerplate of threading the transaction handle from the controller
-   * through every service layer down to the outbox call site.
-   *
-   * Wire up with arc's `transactionContext`:
-   * ```typescript
-   * import { transactionContext } from '@classytic/arc/context';
-   *
-   * const outbox = new EventOutbox({
-   *   store: myOutboxStore,
-   *   sessionProvider: () => transactionContext.get(),
-   * });
-   *
-   * // In your service layer — session is auto-picked up:
-   * await transactionContext.run(mongooseSession, async () => {
-   *   await orders.insertOne(order, { session: mongooseSession });
-   *   await outbox.store(orderCreatedEvent); // no session arg needed
-   * });
-   * ```
-   */
-  readonly sessionProvider?: () => unknown;
-  /**
-   * W3C Trace Context provider.
-   *
-   * When set, `store()` calls this and merges the returned headers into
-   * `OutboxWriteOptions.headers` — only when `traceparent` is not already
-   * present in the caller-supplied headers. Downstream relay workers can
-   * then forward the headers to the transport, preserving the distributed
-   * trace tree across service boundaries.
-   *
-   * Wire up with arc's `getTraceHeaders`:
-   * ```typescript
-   * import { getTraceHeaders } from '@classytic/arc/context';
-   *
-   * const outbox = new EventOutbox({
-   *   store: myOutboxStore,
-   *   traceContextProvider: getTraceHeaders,
-   * });
-   * ```
-   */
-  readonly traceContextProvider?: () => Record<string, string> | undefined;
-}
-declare class EventOutbox {
-  private readonly _store;
-  private readonly _transport?;
-  private readonly _batchSize;
-  private readonly _consumerId;
-  private readonly _leaseMs;
-  private readonly _onError?;
-  private readonly _usePublishMany;
-  private readonly _sessionProvider?;
-  private readonly _traceContextProvider?;
-  private readonly _failurePolicy?;
-  /**
-   * In-process attempt counter per event id. Accurate within this relay
-   * process; resets on restart. Populated as failures occur and cleared on
-   * successful ack or dead-letter transition; additionally hard-capped at
-   * {@link MAX_TRACKED_ATTEMPTS} (oldest-write evicted first) so events
-   * resolved by another relay worker can't accumulate forever. For durable
-   * authoritative counts, apps can query the store directly inside
-   * {@link OutboxFailurePolicy}.
-   */
-  private readonly _attempts;
-  constructor(opts: EventOutboxOptions);
-  /** 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 and return the number of successful
-   * publish+acknowledge pairs.
-   *
-   * 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 AND acknowledged events
-   */
-  relay(): Promise<number>;
-  /**
-   * 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>;
-  /**
-   * Fetch current dead-lettered events as typed {@link DeadLetteredEvent}
-   * envelopes. Delegates to {@link OutboxStore.getDeadLettered} — returns
-   * `[]` when the store doesn't implement it.
-   *
-   * Pairs with {@link OutboxFailurePolicy}: apps set a policy that routes to
-   * `deadLetter: true` after N attempts, then read back with this to alert,
-   * replay, or archive.
-   */
-  getDeadLettered(limit?: number): Promise<DeadLetteredEvent[]>;
-  /**
-   * Purge old **delivered** events from the outbox store.
-   * Delegates to `store.purge()` if implemented; no-op otherwise.
-   * @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>;
-}
-//#endregion
 //#region src/events/repository-outbox-adapter.d.ts
 interface RepositoryOutboxStoreOptions {
   /**
@@ -422,7 +132,18 @@ interface RepositoryOutboxStoreOptions {
    */
   readonly visibleAtField?: string;
 }
-declare function repositoryAsOutboxStore(repository: RepositoryLike, options?: RepositoryOutboxStoreOptions): OutboxStore;
+/**
+ * What this adapter GUARANTEES, as opposed to what `OutboxStore` permits.
+ *
+ * Most of the contract is optional so a minimal or non-relational store can implement
+ * the floor and no more. This adapter implements all of it, and saying so in the type
+ * is not cosmetic: with a plain `OutboxStore` return every caller of `getDeadLettered`,
+ * `requeue` or `countByStatus` has to write `store.requeue?.(id)`, and the `?.` silently
+ * evaluates to `undefined` if the method ever disappears — an operator's replay that
+ * quietly does nothing and reports success.
+ */
+type RepositoryOutboxStore = OutboxStore & Required<Pick<OutboxStore, "fail" | "getDeadLettered" | "purge" | "requeue" | "countByStatus" | "oldestPendingAgeMs">>;
+declare function repositoryAsOutboxStore(repository: RepositoryLike, options?: RepositoryOutboxStoreOptions): RepositoryOutboxStore;
 //#endregion
 //#region src/events/subscribe-helpers.d.ts
 /**
@@ -583,4 +304,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, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RepositoryOutboxStoreOptions, 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 OutboxModuleExports, type OutboxModuleOptions, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RepositoryOutboxStore, type RepositoryOutboxStoreOptions, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, createOutboxModule, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };