@classytic/arc 2.31.0 → 2.33.0

package/dist/outbox-module-CXB79bvt.mjs

@@ -0,0 +1,839 @@
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { i as resolveEventTransport } from "./EventTransport-tq4CEB-q.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "./store-helpers-B88p99Z2.mjs";
+import { and, anyOf, eq, lte, ne, or } from "@classytic/repo-core/filter";
+import { randomBytes } from "node:crypto";
+import { InvalidOutboxEventError, OutboxOwnershipError } from "@classytic/primitives/outbox";
+import { update } from "@classytic/repo-core/update";
+import { hostname } from "node:os";
+//#region src/events/outbox/backoff.ts
+/**
+* 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
+* ```
+*/
+function exponentialBackoff(options) {
+	const attempt = Math.max(1, Math.floor(options.attempt));
+	const baseMs = options.baseMs ?? 1e3;
+	const maxMs = options.maxMs ?? 6e4;
+	const jitter = Math.max(0, Math.min(1, options.jitter ?? .2));
+	const now = options.now ?? Date.now();
+	const exp = baseMs * 2 ** (attempt - 1);
+	const capped = Math.min(maxMs, exp);
+	const jittered = jitter > 0 ? capped * (1 + Math.random() * jitter) : capped;
+	return new Date(now + jittered);
+}
+//#endregion
+//#region src/events/repository-outbox-adapter.ts
+const DEFAULT_LEASE_MS$1 = 3e4;
+const DEFAULT_CLAIM_LIMIT = 100;
+const DEFAULT_PURGE_BATCH = 500;
+/** Column this adapter reads/writes for the visibility timestamp. */
+const DEFAULT_VISIBLE_AT_FIELD = "visibleAt";
+function repositoryAsOutboxStore(repository, options) {
+	const visibleAtField = options?.visibleAtField ?? DEFAULT_VISIBLE_AT_FIELD;
+	const missing = [];
+	if (typeof repository.create !== "function") missing.push("create");
+	if (typeof repository.getOne !== "function") missing.push("getOne");
+	if (typeof repository.getAll !== "function") missing.push("getAll");
+	if (typeof repository.deleteMany !== "function") missing.push("deleteMany");
+	if (typeof repository.findOneAndUpdate !== "function") missing.push("findOneAndUpdate");
+	if (missing.length > 0) throw new Error(`EventOutbox: repository is missing required methods: ${missing.join(", ")}. mongokit ≥3.10.2 satisfies all five; other kits must implement them to back the outbox.`);
+	const r = repository;
+	const idField = repository.idField ?? "_id";
+	/**
+	* Unwrap mongokit's pagination envelope ({ data, total, ... }) — some
+	* kits may return a bare array when pagination is disabled. Handle both.
+	*/
+	const unwrapDocs = (result) => {
+		if (Array.isArray(result)) return result;
+		return result?.data ?? [];
+	};
+	const isDuplicateKeyError = createIsDuplicateKeyError(repository);
+	const safeGetOne = createSafeGetOne(repository);
+	const isWellFormed = (event) => !!event && typeof event.type === "string" && !!event.meta?.id;
+	/**
+	* Filter matching every row that's eligible to be claimed by a relayer:
+	* status=pending, visible now, and either unleased or under an expired
+	* lease. Used by `getPending` and `claimPending` — defined once so the
+	* two code paths stay in lockstep.
+	*/
+	const claimableFilter = (now) => and(eq("status", "pending"), lte(visibleAtField, now), or(eq("leaseOwner", null), lte("leaseExpiresAt", now)));
+	/**
+	* FENCED claim — the ONE claim implementation (`claimPending` delegates).
+	* The token rides the SAME CAS that claims the row: `inc: { fenceToken: 1 }`
+	* next to the attempts bump, so a takeover after lease expiry mints a
+	* strictly greater token in the very statement that takes ownership —
+	* no second round trip, no window. Minted by the store; a process cannot
+	* fence itself.
+	*/
+	const claimPendingFenced = async (options) => {
+		const limit = options?.limit ?? DEFAULT_CLAIM_LIMIT;
+		const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS$1;
+		const consumerId = options?.consumerId ?? "anonymous";
+		const typeFilter = options?.types?.length ? anyOf("type", options.types) : null;
+		const now = /* @__PURE__ */ new Date();
+		const candidateFilter = typeFilter ? and(claimableFilter(now), typeFilter) : claimableFilter(now);
+		const candidates = unwrapDocs(await r.getAll({
+			filters: candidateFilter,
+			sort: { createdAt: 1 },
+			page: 1,
+			limit
+		}));
+		if (candidates.length === 0) return [];
+		return (await Promise.all(candidates.map((candidate) => {
+			const claimNow = /* @__PURE__ */ new Date();
+			const leaseExpiresAt = new Date(claimNow.getTime() + leaseMs);
+			return r.findOneAndUpdate(and(eq(idField, candidate.event.meta.id), claimableFilter(claimNow)), update({
+				set: {
+					leaseOwner: consumerId,
+					leaseExpiresAt
+				},
+				inc: {
+					attempts: 1,
+					fenceToken: 1
+				}
+			}), { returnDocument: "after" });
+		}))).filter((doc) => doc !== null).filter((doc) => isWellFormed(doc.event)).map((doc) => ({
+			event: doc.event,
+			fencingToken: doc.fenceToken ?? 0
+		}));
+	};
+	return {
+		/**
+		* Transactional: `save` forwards `options.session` to the backing
+		* repository's `create`, so the event row joins the caller's transaction on
+		* the SAME connection and commits or rolls back with the domain write.
+		*
+		* Declared explicitly because `OutboxWriteOptions.session` is best-effort by
+		* contract — a caller cannot infer atomicity from the presence of an outbox,
+		* only from this flag. See `OutboxStore.transactionalSave` in
+		* `@classytic/primitives/outbox`.
+		*/
+		transactionalSave: true,
+		async save(event, options) {
+			if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
+			if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
+			const now = /* @__PURE__ */ new Date();
+			const doc = {
+				[idField]: event.meta.id,
+				event,
+				type: event.type,
+				status: "pending",
+				attempts: 0,
+				[visibleAtField]: options?.visibleAt ?? now,
+				leaseOwner: null,
+				leaseExpiresAt: null,
+				deliveredAt: null,
+				firstFailedAt: null,
+				lastFailedAt: null,
+				lastError: null,
+				dedupeKey: options?.dedupeKey ?? null,
+				partitionKey: options?.partitionKey ?? null,
+				headers: options?.headers ? { ...options.headers } : null,
+				createdAt: now
+			};
+			try {
+				await r.create(doc, options?.session ? { session: options.session } : void 0);
+			} catch (err) {
+				if (isDuplicateKeyError(err)) return;
+				throw err;
+			}
+		},
+		async getPending(limit) {
+			const now = /* @__PURE__ */ new Date();
+			const result = await r.getAll({
+				filters: claimableFilter(now),
+				sort: { createdAt: 1 },
+				page: 1,
+				limit
+			});
+			return unwrapDocs(result).map((d) => d.event).filter(isWellFormed);
+		},
+		async claimPending(options) {
+			return (await claimPendingFenced(options)).map((c) => c.event);
+		},
+		claimPendingFenced,
+		async acknowledge(eventId, options) {
+			const now = /* @__PURE__ */ new Date();
+			const baseFilter = and(eq(idField, eventId), ne("status", "delivered"));
+			let filter = options?.consumerId ? and(baseFilter, eq("leaseOwner", options.consumerId)) : baseFilter;
+			if (options?.fencingToken !== void 0) filter = and(filter, eq("fenceToken", options.fencingToken));
+			if (await r.findOneAndUpdate(filter, update({ set: {
+				status: "delivered",
+				deliveredAt: now,
+				leaseOwner: null,
+				leaseExpiresAt: null
+			} }), { returnDocument: "after" })) return;
+			const current = await safeGetOne(eq(idField, eventId));
+			if (!current) return;
+			if (current.status === "delivered") return;
+			if (options?.consumerId && current.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, current.leaseOwner);
+			if (options?.fencingToken !== void 0 && current.fenceToken !== options.fencingToken) throw new OutboxOwnershipError(eventId, `token ${options.fencingToken}`, `token ${current.fenceToken}`);
+		},
+		async fail(eventId, error, options) {
+			const now = /* @__PURE__ */ new Date();
+			const targetStatus = options?.deadLetter ? "dead_letter" : "pending";
+			const visibleAt = options?.retryAt ?? now;
+			const baseFilter = eq(idField, eventId);
+			let filter = options?.consumerId ? and(baseFilter, eq("leaseOwner", options.consumerId)) : baseFilter;
+			if (options?.fencingToken !== void 0) filter = and(filter, eq("fenceToken", options.fencingToken));
+			const current = await safeGetOne(baseFilter);
+			if (!current) return;
+			if (options?.consumerId && current.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, current.leaseOwner);
+			const errorInfo = error.code ? {
+				message: error.message,
+				code: error.code
+			} : { message: error.message };
+			const firstFailedAt = current.firstFailedAt ?? now;
+			if (await r.findOneAndUpdate(filter, update({ set: {
+				status: targetStatus,
+				[visibleAtField]: visibleAt,
+				leaseOwner: null,
+				leaseExpiresAt: null,
+				lastFailedAt: now,
+				lastError: errorInfo,
+				firstFailedAt
+			} }), { returnDocument: "after" })) return;
+			if (options?.consumerId) {
+				const after = await safeGetOne(baseFilter);
+				if (after && after.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, after.leaseOwner);
+			}
+		},
+		async getDeadLettered(limit) {
+			const result = await r.getAll({
+				filters: eq("status", "dead_letter"),
+				sort: { [idField]: 1 },
+				page: 1,
+				limit
+			});
+			return unwrapDocs(result).filter((d) => isWellFormed(d.event)).map((d) => ({
+				event: d.event,
+				error: {
+					message: d.lastError?.message ?? "unknown",
+					...d.lastError?.code !== void 0 ? { code: d.lastError.code } : {}
+				},
+				attempts: d.attempts,
+				firstFailedAt: d.firstFailedAt ?? d.lastFailedAt ?? d.createdAt,
+				lastFailedAt: d.lastFailedAt ?? d.firstFailedAt ?? d.createdAt
+			}));
+		},
+		async purge(olderThanMs) {
+			const cutoff = new Date(Date.now() - olderThanMs);
+			let totalDeleted = 0;
+			for (;;) {
+				const result = await r.getAll({
+					filters: and(eq("status", "delivered"), lte("deliveredAt", cutoff)),
+					sort: { deliveredAt: 1 },
+					page: 1,
+					limit: DEFAULT_PURGE_BATCH,
+					select: idField
+				});
+				const batch = unwrapDocs(result);
+				if (batch.length === 0) break;
+				const ids = batch.map((d) => d[idField]);
+				const res = await r.deleteMany(anyOf(idField, ids));
+				totalDeleted += res.deletedCount ?? 0;
+				if (batch.length < DEFAULT_PURGE_BATCH) break;
+			}
+			return totalDeleted;
+		},
+		/**
+		* Re-drive one dead-lettered event — the other half of `fail({ deadLetter: true })`.
+		*
+		* Filtered on `status: 'dead_letter'` as well as the id, so this is a no-op on a row
+		* that is merely retrying. Requeuing a backing-off row would zero its attempt count
+		* and defeat the failure policy, and the id alone cannot distinguish the two.
+		*
+		* `attempts` resets because the operator's whole claim is that the CAUSE is fixed:
+		* carrying the old count forward would dead-letter the retry again after one more
+		* blip, which reads as "the fix did not work".
+		*/
+		async requeue(eventId) {
+			return await r.findOneAndUpdate(and(eq(idField, eventId), eq("status", "dead_letter")), update({ set: {
+				status: "pending",
+				attempts: 0,
+				leaseOwner: null,
+				leaseExpiresAt: null,
+				[visibleAtField]: /* @__PURE__ */ new Date(),
+				lastError: null
+			} }), { returnDocument: "after" }) != null;
+		},
+		/** Rows in `status` — the count behind an operator dashboard or a dead-letter alert. */
+		async countByStatus(status) {
+			const filters = eq("status", status);
+			const counter = repository.count;
+			if (typeof counter === "function") return counter.call(repository, filters);
+			/**
+			* Fallback for a kit without `count`. Two shapes, and the difference decides the
+			* query — getting it wrong here produces a number that LIES, which is worse than
+			* no number at all: the operator reads a healthy dashboard and stops looking.
+			*
+			* A paginated kit reports the match count in its envelope, so one row is enough
+			* to read it — deliberately not a hydrate-and-length, since a `delivered` count
+			* would drag the whole retention window into memory for one integer.
+			*
+			* A kit that returns a BARE ARRAY has no envelope to read, so the rows ARE the
+			* count and every match has to come back. `unwrapDocs` documents that shape as
+			* real, so it is not hypothetical. `select: idField` keeps it to one column.
+			*/
+			const probe = await r.getAll({
+				filters,
+				page: 1,
+				limit: 1,
+				select: idField
+			});
+			if (Array.isArray(probe)) {
+				const all = await r.getAll({
+					filters,
+					select: idField
+				});
+				return unwrapDocs(all).length;
+			}
+			const total = probe?.total ?? probe?.meta?.total;
+			if (typeof total === "number") return total;
+			/**
+			* An envelope in a shape neither branch recognises. Throwing beats returning 0:
+			* a zero is indistinguishable from a healthy queue, so it would silence exactly
+			* the alert this method exists to raise.
+			*/
+			throw new Error("repositoryAsOutboxStore.countByStatus: the repository's `getAll` returned an envelope with no `total` (and is not a bare array), so the count cannot be read. Implement `count(filter)` on the repository — every kit that has it answers this in one query.");
+		},
+		/**
+		* Age of the oldest PENDING row, or `null` when the queue is empty.
+		*
+		* The signal a pending count cannot give: a count of 40 looks the same whether the
+		* relay is draining briskly or has been wedged for an hour behind one poison row.
+		*
+		* Measured from `createdAt`, not the last attempt — the question is how long the
+		* event has gone undelivered, and restarting the clock on every retry would make a
+		* permanently-failing row look permanently fresh, which is the exact row an alert
+		* exists to surface.
+		*/
+		async oldestPendingAgeMs() {
+			const result = await r.getAll({
+				filters: eq("status", "pending"),
+				sort: { createdAt: 1 },
+				page: 1,
+				limit: 1
+			});
+			const [oldest] = unwrapDocs(result);
+			if (oldest?.createdAt == null) return null;
+			return Date.now() - new Date(oldest.createdAt).getTime();
+		}
+	};
+}
+//#endregion
+//#region src/events/outbox/relay.ts
+/** Default outbox retention — delivered events older than this are eligible for purge */
+const DEFAULT_OUTBOX_RETENTION_MS = 6048e5;
+const DEFAULT_LEASE_MS = 3e4;
+/**
+* Hard cap on the in-process attempt-counter map. Entries are cleared on
+* local ack and on dead-letter, but an event that fails HERE and is later
+* acked by a DIFFERENT relay worker (lease expiry → reclaim) never drains
+* locally — without a cap the map grows for the life of the process in
+* multi-worker deployments. Eviction is oldest-write-first; evicting an
+* entry only resets its non-authoritative in-process count (the documented
+* contract already says counts reset on restart — durable counts live in
+* the store).
+*/
+const MAX_TRACKED_ATTEMPTS = 1e4;
+var EventOutbox = class {
+	_store;
+	_transport;
+	_batchSize;
+	_consumerId;
+	_leaseMs;
+	_onError;
+	_usePublishMany;
+	_sessionProvider;
+	_traceContextProvider;
+	_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}.
+	*/
+	_attempts = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		if (opts.repository) this._store = repositoryAsOutboxStore(opts.repository);
+		else if (opts.store) this._store = opts.store;
+		else throw new Error("EventOutbox: either `repository` or `store` must be provided. Pass a RepositoryLike (mongokit / prismakit) for the common case, or a concrete OutboxStore (memory / custom) for non-repository backends.");
+		this._transport = opts.transport;
+		this._batchSize = opts.batchSize ?? 100;
+		this._consumerId = opts.consumerId ?? `relay-${Math.random().toString(36).slice(2, 10)}`;
+		this._leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS;
+		this._onError = opts.onError;
+		this._usePublishMany = opts.usePublishMany ?? true;
+		this._failurePolicy = opts.failurePolicy;
+		this._sessionProvider = opts.sessionProvider;
+		this._traceContextProvider = opts.traceContextProvider;
+	}
+	/** Unique consumer ID used for lease ownership when the store supports claims */
+	get consumerId() {
+		return this._consumerId;
+	}
+	/**
+	* 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.
+	*/
+	async store(event, options) {
+		if (!event || typeof event !== "object") throw new InvalidOutboxEventError("event is not an object");
+		if (!event.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
+		if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
+		let effective = options;
+		if (effective?.session === void 0 && this._sessionProvider) {
+			const autoSession = this._sessionProvider();
+			if (autoSession !== void 0) effective = {
+				...effective ?? {},
+				session: autoSession
+			};
+		}
+		if (!effective?.headers?.traceparent && this._traceContextProvider) {
+			const traceHeaders = this._traceContextProvider();
+			if (traceHeaders && Object.keys(traceHeaders).length > 0) effective = {
+				...effective ?? {},
+				headers: {
+					...traceHeaders,
+					...effective?.headers ?? {}
+				}
+			};
+		}
+		if (effective?.dedupeKey === void 0 && event.meta.idempotencyKey) effective = {
+			...effective ?? {},
+			dedupeKey: event.meta.idempotencyKey
+		};
+		await this._store.save(event, effective);
+	}
+	_reportError(kind, error, event) {
+		if (!this._onError) return;
+		const err = error instanceof Error ? error : new Error(String(error));
+		try {
+			this._onError({
+				kind,
+				event,
+				error: err
+			});
+		} catch {}
+	}
+	/**
+	* 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
+	*/
+	async relay() {
+		return (await this.relayBatch()).relayed;
+	}
+	/**
+	* 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
+	*/
+	async relayBatch() {
+		const empty = {
+			relayed: 0,
+			attempted: 0,
+			publishFailed: 0,
+			ackFailed: 0,
+			ownershipMismatches: 0,
+			malformed: 0,
+			failHookErrors: 0,
+			deadLettered: 0,
+			usedPublishMany: false
+		};
+		if (!this._transport) return empty;
+		const claimStartedAt = Date.now();
+		const fenceTokens = /* @__PURE__ */ new Map();
+		let pending;
+		if (typeof this._store.claimPendingFenced === "function") pending = (await this._store.claimPendingFenced({
+			limit: this._batchSize,
+			consumerId: this._consumerId,
+			leaseMs: this._leaseMs
+		})).map((c) => {
+			if (c.event?.meta?.id) fenceTokens.set(c.event.meta.id, c.fencingToken);
+			return c.event;
+		});
+		else if (this._store.claimPending) pending = await this._store.claimPending({
+			limit: this._batchSize,
+			consumerId: this._consumerId,
+			leaseMs: this._leaseMs
+		});
+		else pending = await this._store.getPending(this._batchSize);
+		const claimMs = Date.now() - claimStartedAt;
+		const publishStartedAt = Date.now();
+		const valid = [];
+		let malformed = 0;
+		for (const event of pending) {
+			if (!event?.type || !event.meta?.id) {
+				this._reportError("malformed_event", new InvalidOutboxEventError("store returned event missing type or meta.id — batch aborted"), event);
+				malformed++;
+				break;
+			}
+			valid.push(event);
+		}
+		const counts = {
+			relayed: 0,
+			publishFailed: 0,
+			ackFailed: 0,
+			ownershipMismatches: 0,
+			failHookErrors: 0,
+			deadLettered: 0
+		};
+		const canPublishMany = this._usePublishMany && typeof this._transport.publishMany === "function";
+		const canFail = typeof this._store.fail === "function";
+		let publishOutcomes;
+		if (canPublishMany && valid.length > 0) try {
+			const result = await this._transport.publishMany?.(valid);
+			publishOutcomes = new Map(result);
+		} catch (batchErr) {
+			publishOutcomes = /* @__PURE__ */ new Map();
+			const err = batchErr instanceof Error ? batchErr : new Error(String(batchErr));
+			for (const ev of valid) publishOutcomes.set(ev.meta.id, err);
+		}
+		else {
+			publishOutcomes = /* @__PURE__ */ new Map();
+			for (const event of valid) try {
+				await this._transport.publish(event);
+				publishOutcomes.set(event.meta.id, null);
+			} catch (err) {
+				publishOutcomes.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+				if (!canFail) break;
+			}
+		}
+		let stopBatch = false;
+		for (const event of valid) {
+			if (stopBatch) break;
+			const publishErr = publishOutcomes.get(event.meta.id);
+			if (publishErr instanceof Error) {
+				counts.publishFailed++;
+				this._reportError("publish_failed", publishErr, event);
+				if (!canFail) {
+					stopBatch = true;
+					continue;
+				}
+				const attempts = (this._attempts.get(event.meta.id) ?? 0) + 1;
+				this._attempts.delete(event.meta.id);
+				this._attempts.set(event.meta.id, attempts);
+				if (this._attempts.size > MAX_TRACKED_ATTEMPTS) {
+					const oldest = this._attempts.keys().next().value;
+					if (oldest !== void 0) this._attempts.delete(oldest);
+				}
+				const fenceToken = fenceTokens.get(event.meta.id);
+				let failOpts = {
+					consumerId: this._consumerId,
+					...fenceToken !== void 0 ? { fencingToken: fenceToken } : {}
+				};
+				if (this._failurePolicy) try {
+					const decision = await this._failurePolicy({
+						event,
+						error: publishErr,
+						attempts
+					});
+					failOpts = {
+						...failOpts,
+						...decision
+					};
+				} catch (policyErr) {
+					this._reportError("fail_failed", policyErr, event);
+				}
+				try {
+					await this._store.fail?.(event.meta.id, normalizeError(publishErr), failOpts);
+					if (failOpts.deadLetter) {
+						counts.deadLettered++;
+						this._attempts.delete(event.meta.id);
+					}
+				} catch (failErr) {
+					if (failErr instanceof OutboxOwnershipError) {
+						counts.ownershipMismatches++;
+						this._reportError("ownership_mismatch", failErr, event);
+					} else {
+						counts.failHookErrors++;
+						this._reportError("fail_failed", failErr, event);
+					}
+				}
+				continue;
+			}
+			try {
+				const ackFenceToken = fenceTokens.get(event.meta.id);
+				await this._store.acknowledge(event.meta.id, {
+					consumerId: this._consumerId,
+					...ackFenceToken !== void 0 ? { fencingToken: ackFenceToken } : {}
+				});
+				counts.relayed++;
+				this._attempts.delete(event.meta.id);
+			} catch (ackErr) {
+				counts.ackFailed++;
+				if (ackErr instanceof OutboxOwnershipError) {
+					counts.ownershipMismatches++;
+					this._reportError("ownership_mismatch", ackErr, event);
+				} else this._reportError("acknowledge_failed", ackErr, event);
+			}
+		}
+		return {
+			relayed: counts.relayed,
+			attempted: valid.length,
+			publishFailed: counts.publishFailed,
+			ackFailed: counts.ackFailed,
+			ownershipMismatches: counts.ownershipMismatches,
+			malformed,
+			failHookErrors: counts.failHookErrors,
+			deadLettered: counts.deadLettered,
+			usedPublishMany: canPublishMany && valid.length > 0,
+			claimMs,
+			publishMs: Date.now() - publishStartedAt
+		};
+	}
+	/**
+	* 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.
+	*/
+	async getDeadLettered(limit = 100) {
+		if (!this._store.getDeadLettered) return [];
+		return this._store.getDeadLettered(limit);
+	}
+	/**
+	* 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
+	*/
+	async purge(olderThanMs = DEFAULT_OUTBOX_RETENTION_MS) {
+		if (!this._store.purge) return 0;
+		return this._store.purge(olderThanMs);
+	}
+};
+function normalizeError(err) {
+	if (err instanceof Error) return {
+		message: err.message,
+		code: err.code
+	};
+	return { message: String(err) };
+}
+//#endregion
+//#region src/events/outbox-module.ts
+/**
+* The OUTBOX as a module — so the store is a SLOT other modules depend on, not a value the host
+* threads by hand.
+*
+* ## The failure this exists to make impossible
+*
+* A durable store passed as a constructor argument to N consumers will eventually miss one, and
+* the miss is silent. Observed in two independent ERP hosts on the same fleet:
+*
+*   - one passed an outbox to its revenue-attach seam and **not** to `createOrder`, so
+*     `order:created` published fire-and-forget — a failed publish discarded the revenue trigger
+*     entirely: no attach, no dead-letter, no log. Cash collected, nothing recorded.
+*   - the other had the identical gap, written independently.
+*
+* Six consumers had to be wired by hand in each host (order kernel, revenue kernel, access
+* kernel, revenue-attach durability, line-activation dead letters, promo-commit dead letters).
+* That is not a discipline problem; it is a design problem.
+*
+* As a module the store is registered ONCE and read from the registry. A consumer declares
+* `dependsOn: ['outbox']` and arc refuses to boot without it — the omission becomes a startup
+* failure instead of a quiet data-loss window.
+*
+* ## What this module does NOT do
+*
+* It does not build a store. Store construction is store-specific (a mongo model, a SQL table),
+* and arc is deliberately storage-agnostic — `repositoryAsOutboxStore` already adapts any
+* repository, and kits own their own schema (e.g. `@classytic/mongokit/outbox`). This module owns
+* the three things that are genuinely arc's: the module SLOT, the relay SCHEDULE, and shutdown.
+*/
+/**
+* The store contract is `@classytic/primitives/outbox`'s, not arc's — arc adapts to it rather
+* than owning it, which is why a kit (mongokit) can supply a store with no arc dependency.
+*/
+/** Default relay cadence. Frequent enough that a retry is not a user-visible delay. */
+const DEFAULT_RELAY_EVERY_MS = 5e3;
+/**
+* One relay identity per RELAY INSTANCE — `<name>:<hostname>:<pid>:<random>`.
+*
+* A lease identifies an independently executing CLAIMANT, not a crash domain.
+* Arc lets two outbox modules coexist (`name` is the `dependsOn` key), each
+* with its own schedule arm, and nothing stops two of them pointing at the
+* same store: they tick independently, so they are two claimants and must be
+* two identities. Scoping this per-process instead would have made the module
+* WEAKER than the primitive it wraps — `EventOutbox`'s own fallback is already
+* per-instance — and would leave the store unable to tell the two apart after
+* a lease expiry, which is exactly the stale-owner hole this replaced.
+*
+* Every component earns its place: `name` distinguishes co-resident modules,
+* `hostname:pid` makes a lease row legible in ops tooling, and the random
+* suffix breaks the tie a container restart creates — same hostname, often the
+* same pid, and the restarted process must not inherit a predecessor's
+* identity while that predecessor's lease is still live.
+*
+* Called once per `bootstrap()`, so the id is stable across every tick of the
+* relay it belongs to — which the lease depends on.
+*/
+function mintConsumerId(name) {
+	return `${name}:${hostname()}:${process.pid}:${randomBytes(4).toString("hex")}`;
+}
+/**
+* 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.
+*/
+function createOutboxModule(options) {
+	const name = options.name ?? "outbox";
+	const relayEveryMs = options.relayEveryMs ?? DEFAULT_RELAY_EVERY_MS;
+	/**
+	* Built at bootstrap and reused by the schedule.
+	*
+	* Not rebuilt per tick: `EventOutbox` carries the consumer id the lease is keyed on, and a fresh
+	* instance per tick would be a fresh claimant every few seconds — which defeats the lease it
+	* depends on for exactly-once publishing.
+	*/
+	let exports;
+	return {
+		name,
+		bootstrap: (fastify) => {
+			const store = typeof options.store === "function" ? options.store(fastify) : options.store;
+			/**
+			* The RAW transport, never `fastify.events`.
+			*
+			* This read used to be `(fastify as { events?: EventTransport }).events` — a cast across
+			* two INCOMPATIBLE shapes. The facade's `publish(type, payload, meta?)` took the relayed
+			* `DomainEvent` as its `type` argument and failed the non-empty-string guard, so the
+			* documented default path published NOTHING: subscribers saw nothing and every tick
+			* reported `publishFailed: 1` until the row dead-lettered. The cast is what let two
+			* mismatched signatures typecheck.
+			*/
+			const transport = options.transport === void 0 ? resolveEventTransport(fastify) : typeof options.transport === "function" ? options.transport(fastify) : options.transport;
+			/**
+			* No transport is BOOT-FATAL, because the alternative is invisible:
+			* `EventOutbox.relayBatch()` returns an empty result when it has none, so the
+			* module's schedule would tick forever, publish nothing, and let the store grow —
+			* a durable backlog nobody is draining, reported as healthy. The failure this
+			* module exists to prevent, arrived at from the other side.
+			*/
+			if (transport === void 0) throw new Error(`Outbox module "${name}" could not resolve an event transport, so its relay would tick forever without publishing while the store grows. Register arc's events plugin (it is on by default — check \`arcPlugins.events !== false\`), or pass an explicit \`transport\` to \`createOutboxModule\`. Note the outbox needs the RAW EventTransport, not the \`fastify.events\` facade: the facade takes \`(type, payload, meta?)\` and fails open, which would acknowledge rows whose publish actually failed.`);
+			exports = {
+				store,
+				relay: new EventOutbox({
+					store,
+					transport,
+					...options.batchSize !== void 0 ? { batchSize: options.batchSize } : {},
+					...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
+					consumerId: options.consumerId ?? mintConsumerId(name),
+					...options.onError !== void 0 ? { onError: options.onError } : {},
+					...options.failurePolicy !== void 0 ? { failurePolicy: options.failurePolicy } : {}
+				})
+			};
+			return exports;
+		},
+		/**
+		* The relay runs on the module's OWN schedule arm, so the host stops owning the tick — and
+		* a host that forgets to start one cannot exist.
+		*/
+		scheduledJobs: () => [{
+			name: `${name}.relay`,
+			kind: "relay",
+			every: relayEveryMs,
+			runOnStart: options.runOnStart ?? true,
+			handler: async () => {
+				await exports?.relay.relay();
+			}
+		}]
+	};
+}
+//#endregion
+export { exponentialBackoff as i, EventOutbox as n, repositoryAsOutboxStore as r, createOutboxModule as t };