@classytic/arc 2.31.0 → 2.32.0

package/dist/{defineResource-Bv6EtN1x.mjs → defineResource-XFPPUu2c.mjs}

@@ -1,22 +1,22 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-D3Dv4LAV.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-J99LGTJI.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { r as ForbiddenError } from "./errors-Cj42AntO.mjs";
-import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-Cys0ko9Z.mjs";
-import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-De7GqHck.mjs";
-import { a as buildRouteHooks, c as buildAuthMiddleware, i as selectPluginMw, n as buildRouteConfig, o as resolveRoutePreHandlers, r as resolveRouterPluginMw, s as routeHookOptions, t as buildRateLimitConfig, u as buildArcDecorator } from "./rateLimit-CMPY5Qms.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CB5Cuzk9.mjs";
-import { r as buildCrudPermissionMw, t as tryRegisterRoute } from "./registerRoute-CBN84fc7.mjs";
-import { c as getDefaultCrudSchemas } from "./utils-vL8BrDE2.mjs";
-import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-D--wdJM-.mjs";
-import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-PSZwi8JV.mjs";
-import { t as hasEvents } from "./typeGuards-B0ryPo3I.mjs";
-import { a as createFastifyHandler, i as createCrudHandlers, n as buildPipelineHandler, o as createRequestContext, r as resolvePipelineSteps } from "./pipeline-UPQFatit.mjs";
-import { I as requireAuth } from "./permissions-L--QDAir.mjs";
-import { r as getAvailablePresets, t as applyPresets } from "./presets-C4-g4_4P.mjs";
-import { t as pluralize } from "./pluralize-O0FZgESl.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-BE5NwaQk.mjs";
+import { r as ForbiddenError } from "./errors-Bh1KK5ps.mjs";
+import { n as getUserRoles } from "./userHelpers-BNsOXzOd.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-DXYX7dIR.mjs";
+import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-Dk34dxhI.mjs";
+import { a as buildRouteHooks, c as buildAuthMiddleware, i as selectPluginMw, n as buildRouteConfig, o as resolveRoutePreHandlers, r as resolveRouterPluginMw, s as routeHookOptions, t as buildRateLimitConfig, u as buildArcDecorator } from "./rateLimit-C7mmAGs3.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-DEi65pGj.mjs";
+import { r as buildCrudPermissionMw, t as tryRegisterRoute } from "./registerRoute-B_QrjYZS.mjs";
+import { c as getDefaultCrudSchemas } from "./utils-BtOha_Sp.mjs";
+import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-Crjvczi_.mjs";
+import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-DPZdQmDz.mjs";
+import { t as hasEvents } from "./typeGuards-B_5-hKjJ.mjs";
+import { a as createFastifyHandler, i as createCrudHandlers, n as buildPipelineHandler, o as createRequestContext, r as resolvePipelineSteps } from "./pipeline-CPA-jx0M.mjs";
+import { B as requireAuth } from "./permissions-Dl_m0NCe.mjs";
+import { r as getAvailablePresets, t as applyPresets } from "./presets-Dntd_pUO.mjs";
+import { t as pluralize } from "./pluralize-C2ZkKbsn.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-Dti7ebyv.mjs";
 //#region src/core/middlewares/fieldWrite.ts
 /**
 * Build a preHandler that enforces field-write permissions on the request body.
@@ -42,7 +42,10 @@ function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRIT
 		if (!body || typeof body !== "object" || Array.isArray(body)) return;
 		const scope = request.scope ?? PUBLIC_SCOPE;
 		if (isElevated(scope)) return;
-		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, resolveEffectiveRoles(getUserRoles(request.user), isMember(scope) ? scope.orgRoles : []));
+		const globalRoles = getUserRoles(request.user);
+		const orgRoles = isMember(scope) ? scope.orgRoles : [];
+		const effectiveRoles = resolveEffectiveRoles(globalRoles, orgRoles);
+		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, effectiveRoles);
 		if (deniedFields.length > 0 && policy === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
 		request.body = filtered;
 	};
@@ -114,8 +117,9 @@ function createCustomRoutes(fastify, routes, controller, options) {
 			const fieldWriteMw = buildFieldWritePreHandler(fieldPermissions, onFieldWriteDenied);
 			if (fieldWriteMw) customPreHandlers.push(fieldWriteMw);
 		}
+		const preAuthHandlers = route.preAuth ?? [];
 		const hooks = buildRouteHooks({
-			preAuth: route.preAuth ?? [],
+			preAuth: preAuthHandlers,
 			arcDecorator,
 			authMw: buildAuthMiddleware(fastify, route.permissions),
 			permissionMw: buildCrudPermissionMw(route.permissions, resourceName, opName),
@@ -287,7 +291,8 @@ function buildCrudHandlers(ctrl, pipeline, resourceName) {
 	for (const op of CRUD_OPERATIONS) {
 		const steps = resolvePipelineSteps(pipeline, op);
 		if (steps.length === 0) continue;
-		wrapped[op] = buildPipelineHandler(ctrl[op].bind(ctrl), steps, op, resourceName);
+		const method = ctrl[op].bind(ctrl);
+		wrapped[op] = buildPipelineHandler(method, steps, op, resourceName);
 	}
 	return wrapped;
 }
@@ -1226,11 +1231,13 @@ function buildResourcePlugin(resource) {
 			handler: hook.handler,
 			priority: hook.priority
 		});
-		if (isFirstMount && resource.cache?.invalidateOn) if (fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
-			pattern,
-			tags
-		});
-		else fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`cache.invalidateOn\` but \`queryCachePlugin\` is not registered. Cache-invalidation rules are silently ignored. Either register the plugin (\`await fastify.register(queryCachePlugin, ...)\`) or remove the \`cache.invalidateOn\` config to clean up the resource definition.`);
+		if (isFirstMount && resource.cache?.invalidateOn) {
+			if (fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
+				pattern,
+				tags
+			});
+			else fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`cache.invalidateOn\` but \`queryCachePlugin\` is not registered. Cache-invalidation rules are silently ignored. Either register the plugin (\`await fastify.register(queryCachePlugin, ...)\`) or remove the \`cache.invalidateOn\` config to clean up the resource definition.`);
+		}
 		if (isFirstMount && resource.audit) {
 			if (!(fastify.hasDecorator("audit") && typeof fastify.audit?.create === "function" && fastify.audit?._noop !== true)) fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`audit: ${JSON.stringify(resource.audit)}\` but \`auditPlugin\` is not registered (or is registered with a noop logger). Audit events for this resource will NOT be recorded. Either register \`auditPlugin\` (\`await fastify.register(auditPlugin, { store: ... })\`) or remove the \`audit\` flag from the resource definition.`);
 		}
@@ -1271,7 +1278,7 @@ function buildResourcePlugin(resource) {
 				extensions: resource.extensions
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-CDXEdasl.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-DkJZWo0m.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1286,7 +1293,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-KrQDzx-k.mjs"), import("./validate-_KbifpHF.mjs").then((n) => n.r)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-B1exOVD8.mjs"), import("./validate-PMCPR9El.mjs").then((n) => n.r)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1486,10 +1493,12 @@ var ResourceDefinition = class {
 	_validateControllerMethods() {
 		const errors = [];
 		const enabledCrudRoutes = CRUD_OPERATIONS.filter((route) => !this.disabledRoutes.includes(route));
-		if (!this.disableDefaultRoutes && enabledCrudRoutes.length > 0) if (!this.controller) errors.push("Controller is required when CRUD routes are enabled");
-		else {
-			const ctrl = this.controller;
-			for (const method of enabledCrudRoutes) if (typeof ctrl[method] !== "function") errors.push(`CRUD method '${method}' not found on controller`);
+		if (!this.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
+			if (!this.controller) errors.push("Controller is required when CRUD routes are enabled");
+			else {
+				const ctrl = this.controller;
+				for (const method of enabledCrudRoutes) if (typeof ctrl[method] !== "function") errors.push(`CRUD method '${method}' not found on controller`);
+			}
 		}
 		for (const route of this.routes) {
 			if (typeof route.handler !== "string") continue;

package/dist/discovery/index.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 import { readdir } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/docs/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { n as getUserRoles } from "../userHelpers-ChYJ6CdK.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-B2L4js1v.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "../userHelpers-BNsOXzOd.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-DIRzvxC0.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{elevation-D2l1mh4g.mjs → elevation-DNXXxgjl.mjs}

@@ -1,8 +1,8 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-BhflRrBs.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { n as requireSingleHeaderValue } from "./headers-3zvE0rM3.mjs";
-import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BXjQYbeC.mjs";
+import { n as getUserRoles } from "./userHelpers-BNsOXzOd.mjs";
 import fp from "fastify-plugin";
 //#region src/scope/elevation.ts
 var elevation_exports = /* @__PURE__ */ __exportAll({

package/dist/encryption/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as ArcError } from "../errors-Cj42AntO.mjs";
-import { t as parseJsonBody } from "../jsonBody-BYbLDi5D.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { t as ArcError } from "../errors-Bh1KK5ps.mjs";
+import { t as parseJsonBody } from "../jsonBody-DDSR2HFl.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/encryption/fieldCipher.ts
@@ -71,7 +71,8 @@ function parseFieldEnvelope(token) {
 }
 /** Decrypt a parsed `arc.v1` envelope with the resolved key. Throws on tamper. */
 function decryptField(envelope, key) {
-	const decipher = createDecipheriv("aes-256-gcm", toKeyBuffer(key), envelope.iv);
+	const secret = toKeyBuffer(key);
+	const decipher = createDecipheriv("aes-256-gcm", secret, envelope.iv);
 	decipher.setAuthTag(envelope.tag);
 	return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]).toString("utf8");
 }

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

@@ -1,6 +1,6 @@
-/*! @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.32.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-BhflRrBs.mjs";
+import { m as statusToArcCode, p as isArcError } from "./errors-Bh1KK5ps.mjs";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
 //#region src/plugins/errorHandler.ts

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

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

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

@@ -1,9 +1,9 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-BhflRrBs.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-Bh1KK5ps.mjs";
+import { n as requestContext } from "./requestContext-B6vQF-sy.mjs";
+import { n as createEvent, t as MemoryEventTransport } from "./EventTransport-BV10D0oG.mjs";
 import fp from "fastify-plugin";
 //#region src/events/retry.ts
 /**
@@ -139,10 +139,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);

package/dist/events/index.d.mts

@@ -1,9 +1,12 @@
 
 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 { t as ArcModule } from "../types-CT5vu6M0.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 { 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 { FastifyInstance } from "fastify";
+import { MemoryOutboxStore } from "@classytic/primitives/memory-outbox";
+import { OutboxFailurePolicy, OutboxStore, OutboxWriteOptions } from "@classytic/primitives/outbox";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/events/eventTypes.d.ts
 /**
@@ -56,44 +59,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
@@ -405,6 +370,97 @@ declare class EventOutbox {
   purge(olderThanMs?: number): Promise<number>;
 }
 //#endregion
+//#region src/events/outbox-module.d.ts
+interface OutboxModuleOptions {
+  /**
+   * The durable store. Supply it directly, or as a factory when it needs the booted app
+   * (a mongoose connection decorated by an earlier plugin, for instance).
+   */
+  store: OutboxStore | ((fastify: FastifyInstance) => OutboxStore);
+  /**
+   * Where relayed events are published. Omit to use `fastify.events` — the ordinary case; pass
+   * one only when the outbox must publish somewhere other than the app's own transport.
+   */
+  transport?: EventTransport | ((fastify: FastifyInstance) => EventTransport);
+  /** Module name, and therefore the `dependsOn` key. Default `'outbox'`. */
+  name?: string;
+  /** Relay interval in ms. Default 5000. */
+  relayEveryMs?: number;
+  /**
+   * Rows per relay tick. Left to the store's own default when omitted — a batch size is a
+   * throughput tuning decision, not something this module should invent.
+   */
+  batchSize?: number;
+  /** Lease duration for a claimed batch, in ms. */
+  leaseMs?: number;
+  /**
+   * Consumer id recorded on the lease. Default `'arc-outbox-relay'`.
+   *
+   * Give each relaying process a DISTINCT id when several run: the lease is what stops two
+   * relays publishing the same event, and it can only do that if they are distinguishable.
+   */
+  consumerId?: string;
+  /**
+   * Called for every non-fatal relay problem — publish failures, ownership mismatches,
+   * acknowledge failures.
+   *
+   * **Wire this.** Silence here is the failure mode that matters: the relay keeps ticking, rows
+   * keep failing, and the only symptom is revenue that never posted.
+   */
+  onError?: OutboxRelayErrorHandler;
+  /**
+   * Retry / dead-letter policy for a failed publish — `({ attempts }) => { retryAt } |
+   * { deadLetter: true }`.
+   *
+   * Omitting it takes `EventOutbox`'s default. Exposed because a real host had one and losing it
+   * on adoption would be a silent downgrade: without a policy a permanently-failing row either
+   * retries forever or dead-letters on the first blip, and both are wrong for money. A typical
+   * shape is exponential backoff up to N attempts, then dead-letter.
+   */
+  failurePolicy?: OutboxFailurePolicy;
+  /**
+   * Run one relay pass at boot. Default `true` — a process that restarts with a backlog should
+   * drain it immediately rather than waiting a full interval, because that backlog is precisely
+   * the events the previous process failed to publish.
+   */
+  runOnStart?: boolean;
+}
+/** What the module exports at `fastify.arc.modules.<name>`. */
+interface OutboxModuleExports {
+  /** The store, for consumers that write events transactionally. */
+  store: OutboxStore;
+  /** The relay, for a host that wants to drain on demand (tests, admin actions). */
+  relay: EventOutbox;
+}
+/**
+ * Compose the outbox as a module.
+ *
+ * ```ts
+ * // host
+ * const model = createOutboxModel(connection, { visibleAtField: 'nextVisibleAt' });
+ * createApp({ modules: [
+ *   createOutboxModule({
+ *     store: repositoryAsOutboxStore(new Repository(model), { visibleAtField: 'nextVisibleAt' }),
+ *     onError: (err, ctx) => app.log.error({ err, ...ctx }, 'outbox relay'),
+ *   }),
+ *   …
+ * ]});
+ *
+ * // consumer module
+ * defineModule({
+ *   name: 'order',
+ *   dependsOn: ['outbox'],
+ *   bootstrap: (f) => createOrder({
+ *     outbox: getModuleExports<OutboxModuleExports>(f, 'outbox').store,
+ *   }),
+ * });
+ * ```
+ *
+ * `dependsOn` is doing real work there: it both orders the bootstraps and makes a missing outbox a
+ * boot error naming the module that needed it.
+ */
+declare function createOutboxModule(options: OutboxModuleOptions): ArcModule<OutboxModuleExports>;
+//#endregion
 //#region src/events/repository-outbox-adapter.d.ts
 interface RepositoryOutboxStoreOptions {
   /**
@@ -422,7 +478,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 +650,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 };