@classytic/arc 2.32.0 → 2.33.0

package/dist/events/index.mjs

@@ -1,12 +1,9 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { t as MemoryEventTransport } from "../EventTransport-BV10D0oG.mjs";
-import { a as createEventRegistry, i as wrapWithSchema, n as subscribeWithSchema, o as defineEvent, r as wrapWithBoundary, t as subscribeWithBoundary } from "../subscribe-helpers-sp5xTDVA.mjs";
-import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-Dk_TyXeE.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DmEMHlPQ.mjs";
-import { and, anyOf, eq, lte, ne, or } from "@classytic/repo-core/filter";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { n as MemoryEventTransport } from "../EventTransport-tq4CEB-q.mjs";
+import { a as createEventRegistry, i as wrapWithSchema, n as subscribeWithSchema, o as defineEvent, r as wrapWithBoundary, t as subscribeWithBoundary } from "../subscribe-helpers-CLIOHsOK.mjs";
+import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-Dar8qRaj.mjs";
+import { i as exponentialBackoff, n as EventOutbox, r as repositoryAsOutboxStore, t as createOutboxModule } from "../outbox-module-CXB79bvt.mjs";
 import { MemoryOutboxStore } from "@classytic/primitives/memory-outbox";
-import { InvalidOutboxEventError, OutboxOwnershipError } from "@classytic/primitives/outbox";
-import { update } from "@classytic/repo-core/update";
 //#region src/events/eventTypes.ts
 /**
 * Event Type Constants and Helpers
@@ -58,776 +55,4 @@ const CACHE_EVENTS = Object.freeze({
 	TAG_VERSION_BUMPED: "arc.cache.tag.bumped"
 });
 //#endregion
-//#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
-/**
-* RepositoryLike → OutboxStore adapter.
-*
-* Maps the `OutboxStore` vocabulary (save / claimPending / acknowledge /
-* fail / getDeadLettered / purge) onto arc's own `RepositoryLike` primitives
-* (create / getOne / findAll / deleteMany / findOneAndUpdate). `EventOutbox`
-* wraps a passed repository with this helper when you use the
-* `{ repository }` option; the function is also re-exported from
-* `@classytic/arc/events` so consumers can build and decorate the store
-* manually (metrics, tracing, multi-transport fan-out).
-*
-* Portability: filters compose via `@classytic/repo-core/filter` and
-* updates via `@classytic/repo-core/update`. The primary-key column name
-* is read from `repository.idField` — mongokit defaults to `_id`,
-* sqlitekit / pgkit / prismakit to the schema's declared PK. The adapter
-* therefore runs on any kit that implements `StandardRepo.findOneAndUpdate`
-* + `getOne` + `getAll` + `deleteMany` + `create`.
-*
-* `fail()` uses a lease-gated read-then-write pair to preserve
-* `firstFailedAt` across retries without relying on Mongo's aggregation-
-* pipeline `$ifNull`. Leases guarantee single-writer during the failure
-* window (`claimPending` filters out non-owned rows), so the two calls are
-* safe under concurrent relayers.
-*
-* Why we DON'T use `StandardRepo.claim()` (repo-core 0.4+) anywhere in this
-* adapter — design note for the next reader who wants to "modernize" us:
-*
-*   • `claimPending` (FIFO claim-next loop): `claim(id, ...)` requires the
-*     candidate id upfront, but the relayer doesn't have it — that's the
-*     whole point of `findOneAndUpdate({ filter, sort: { createdAt: 1 } })`,
-*     which finds + claims in a SINGLE round-trip per claimed event.
-*     Replacing with `getOne(filter, sort) → claim(id, ...)` doubles the
-*     round-trips, opens a TOCTOU window where the candidate state can
-*     change between read and CAS (we'd need a retry loop on null-on-race),
-*     and gains nothing — the existing call is already atomic and
-*     race-free. Throughput regression with no upside; do not adopt.
-*
-*   • `acknowledge` (pending → delivered): id is in scope, but the current
-*     filter uses `ne('status', 'delivered')` to allow ack from any
-*     non-delivered state (defensive; lease invariant means it's pending
-*     in practice). `claim` requires an exact `from` value, so adopting
-*     would tighten the source-state predicate from "not delivered" to
-*     "exactly pending". That's a behavior change — even if the new
-*     behavior is arguably tighter/safer, the constraint here is "no
-*     semantic regression". Keep `findOneAndUpdate`.
-*
-*   • `fail` (any → pending|dead_letter): the current `baseFilter` is
-*     id-only (with optional `leaseOwner` guard) — there's NO source-state
-*     predicate at all. Adopting `claim` would ADD `from: 'pending'`,
-*     blocking `fail()` calls against rows in any other state. Same "no
-*     semantic regression" concern; keep `findOneAndUpdate`. The
-*     read-then-write pair also exists here to preserve `firstFailedAt`
-*     portably (see paragraph above) — `claim` doesn't simplify that.
-*
-* No kit currently ships a filter-based `claimNext`/`claimPending` (Path C
-* in the v2.11.x evaluation) — checked mongokit 3.13.0 + sqlitekit 0.3.0.
-* If/when one appears, the FIFO loop becomes a 1-call adoption candidate.
-*/
-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)));
-	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) {
-			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 }
-				}), { returnDocument: "after" });
-			}))).filter((doc) => doc !== null).map((doc) => doc.event).filter(isWellFormed);
-		},
-		async acknowledge(eventId, options) {
-			const now = /* @__PURE__ */ new Date();
-			const baseFilter = and(eq(idField, eventId), ne("status", "delivered"));
-			const filter = options?.consumerId ? and(baseFilter, eq("leaseOwner", options.consumerId)) : baseFilter;
-			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);
-		},
-		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);
-			const filter = options?.consumerId ? and(baseFilter, eq("leaseOwner", options.consumerId)) : baseFilter;
-			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 pending = this._store.claimPending ? await this._store.claimPending({
-			limit: this._batchSize,
-			consumerId: this._consumerId,
-			leaseMs: this._leaseMs
-		}) : 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);
-				}
-				let failOpts = { consumerId: this._consumerId };
-				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 {
-				await this._store.acknowledge(event.meta.id, { consumerId: this._consumerId });
-				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
-/** Default relay cadence. Frequent enough that a retry is not a user-visible delay. */
-const DEFAULT_RELAY_EVERY_MS = 5e3;
-/**
-* 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;
-			const transport = options.transport === void 0 ? fastify.events : typeof options.transport === "function" ? options.transport(fastify) : options.transport;
-			exports = {
-				store,
-				relay: new EventOutbox({
-					store,
-					...transport !== void 0 ? { transport } : {},
-					...options.batchSize !== void 0 ? { batchSize: options.batchSize } : {},
-					...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
-					consumerId: options.consumerId ?? "arc-outbox-relay",
-					...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`,
-			every: relayEveryMs,
-			runOnStart: options.runOnStart ?? true,
-			handler: async () => {
-				await exports?.relay.relay();
-			}
-		}]
-	};
-}
-//#endregion
 export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEventRegistry, createOutboxModule, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };