@classytic/arc 2.41.1 → 2.44.0

package/dist/{openapi-CmFf3yq_.mjs → openapi-CMegfsm8.mjs}

@@ -1,9 +1,9 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as getUserRoles } from "./userHelpers-ChRvkuSZ.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-BVA7cFRG.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-BoPGQ5-4.mjs";
-import { t as pluralize } from "./pluralize-CXWZIzTv.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-DNqoaK81.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "./userHelpers-C76zD5pa.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-BVjkQ5DD.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-5N04zBL4.mjs";
+import { t as pluralize } from "./pluralize-COUNYo3d.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-zG13rpPJ.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**
@@ -133,7 +133,17 @@ function buildPaginatedListSchema(itemRef) {
 					total: { type: "integer" },
 					pages: { type: "integer" },
 					hasNext: { type: "boolean" },
-					hasPrev: { type: "boolean" }
+					hasPrev: { type: "boolean" },
+					totalIsEstimate: {
+						type: "boolean",
+						description: "true when `total` is an estimate or a cap (render as e.g. '10,000+')."
+					},
+					countedAt: {
+						type: "string",
+						format: "date-time",
+						nullable: true,
+						description: "When `total` was counted; null when no count was taken."
+					}
 				}
 			},
 			{
@@ -161,6 +171,17 @@ function buildPaginatedListSchema(itemRef) {
 						type: "string",
 						nullable: true,
 						description: "Opaque cursor for the next page, or null when `hasMore` is false. Round-trip verbatim as the `after` query param."
+					},
+					prev: {
+						type: "string",
+						nullable: true,
+						description: "Opaque cursor for the previous page, or null on the first page. Round-trip verbatim as the `before` query param."
+					},
+					hasPrev: { type: "boolean" },
+					end: {
+						type: "string",
+						nullable: true,
+						description: "Cursor at this page's last row — resume a feed with `after` from here."
 					}
 				}
 			},
@@ -379,7 +400,7 @@ function createOperation(resource, operation, summary, extras, requiresAuthOverr
 	const requiresAuth = requiresAuthOverride !== void 0 ? requiresAuthOverride : typeof operationPermission === "function" && !isPublic;
 	const permAnnotation = describePermissionForOpenApi(operationPermission);
 	const descParts = [];
-	if (permAnnotation) descParts.push(`**Permission**: ${permAnnotation.type === "public" ? "Public" : permAnnotation.type === "requireRoles" ? `Requires roles: ${(permAnnotation.roles ?? []).join(", ")}` : "Requires authentication"}`);
+	if (permAnnotation) descParts.push(`**Permission**: ${permAnnotation.type === "public" ? permAnnotation.rowFiltered ? "Public (row-filtered: a policy narrows which records anyone can see)" : "Public" : permAnnotation.type === "requireRoles" ? `Requires roles: ${(permAnnotation.roles ?? []).join(", ")}` : "Requires authentication"}`);
 	if (resource.presets && resource.presets.length > 0) descParts.push(`**Presets**: ${resource.presets.join(", ")}`);
 	const applicableSteps = (resource.pipelineSteps ?? []).filter((s) => {
 		if (!s.operations) return true;
@@ -398,6 +419,7 @@ function createOperation(resource, operation, summary, extras, requiresAuthOverr
 			type: s.type,
 			name: s.name
 		})) },
+		...resource.idempotency?.required.some((o) => o === operation) && { "x-arc-idempotency": { required: true } },
 		responses: buildErrorResponses({
 			requiresAuth,
 			permRoles: permAnnotation?.roles
@@ -421,7 +443,10 @@ function createOperation(resource, operation, summary, extras, requiresAuthOverr
 function describePermissionForOpenApi(check) {
 	if (!check || typeof check !== "function") return void 0;
 	const fn = check;
-	if (fn._isPublic === true) return { type: "public" };
+	if (fn._isPublic === true) return fn._rowPolicy ? {
+		type: "public",
+		rowFiltered: true
+	} : { type: "public" };
 	const result = { type: "requireAuth" };
 	if (Array.isArray(fn._roles) && fn._roles.length > 0) {
 		result.type = "requireRoles";
@@ -573,6 +598,8 @@ function emitMount(paths, resource, basePath, additionalSecurity, subsetActions,
 		});
 		return typeof effective === "function" && !effective._isPublic;
 	});
+	const requiredActions = subsetActions.filter((a) => a.idempotency?.required === true).map((a) => a.name);
+	const handlerDedup = Object.fromEntries(subsetActions.flatMap((a) => a.idempotency?.required === true && a.idempotency.dedup === "handler" ? [[a.name, String(a.idempotency.owner)]] : []));
 	if (!paths[actionPath]) paths[actionPath] = {};
 	paths[actionPath].post = createOperation(resource, "action", `Perform action (${actionEnum.join(" / ")})`, {
 		...hasId ? { parameters: [{
@@ -583,6 +610,10 @@ function emitMount(paths, resource, basePath, additionalSecurity, subsetActions,
 			description: "Resource ID"
 		}] } : {},
 		description: descLines.join("\n"),
+		...requiredActions.length > 0 && { "x-arc-idempotency": {
+			requiredActions,
+			...Object.keys(handlerDedup).length > 0 ? { handlerDedup } : {}
+		} },
 		requestBody: {
 			required: true,
 			content: { "application/json": { schema: bodySchema } }
@@ -883,6 +914,13 @@ function appendCustomRoutePaths(paths, resource, basePath, additionalSecurity) {
 				content: { "application/json": { schema } }
 			};
 		}
+		if (route.idempotency?.required === true) extras["x-arc-idempotency"] = {
+			required: true,
+			...route.idempotency.dedup === "handler" ? {
+				dedup: "handler",
+				owner: route.idempotency.owner
+			} : {}
+		};
 		paths[fullPath][method] = createOperation(resource, handlerName, route.summary ?? handlerName, extras, requiresAuthForRoute, additionalSecurity);
 	}
 }
@@ -1004,4 +1042,4 @@ var openapi_default = fp(openApiPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { openApiPlugin as n, openapi_default as r, buildOpenApiSpec as t };
+export { openapi_default as n, buildOpenApiSpec as t };

package/dist/outbox-admin/index.d.mts

@@ -1,6 +1,6 @@
 
-import { l as PermissionCheck } from "../base-CxrV1LmG.mjs";
-import { t as ArcModule } from "../types-DfVDvkdP.mjs";
+import { l as PermissionCheck } from "../base-CZyixEQR.mjs";
+import { n as ArcModule, u as ModuleName } from "../types-BJ-2XqVF.mjs";
 import { OutboxStore } from "@classytic/primitives/outbox";
 //#region src/outbox-admin/module.d.ts
 /**
@@ -36,7 +36,7 @@ interface OutboxAdminModuleDeps {
    * Name the outbox module was composed under, used to resolve the relay and
    * declared as a `dependsOn` edge. Default `outbox`.
    */
-  outboxModuleName?: string;
+  outboxModuleName?: ModuleName;
   /** Resource names this module supersedes. */
   owns?: readonly string[];
   /** Cap on `?limit`. Default 500 — a dead-letter list is for triage, not export. */
@@ -80,6 +80,6 @@ interface OutboxAdminModuleDeps {
    */
   relayLagUnhealthyMs?: number;
 }
-declare function createOutboxAdminModule(deps: OutboxAdminModuleDeps): ArcModule<void>;
+export declare function createOutboxAdminModule(deps: OutboxAdminModuleDeps): ArcModule<void>;
 //#endregion
-export { type OutboxAdminModuleDeps, type OutboxAdminPermissions, type OutboxAdminStore, createOutboxAdminModule };
+export type { OutboxAdminModuleDeps, OutboxAdminPermissions, OutboxAdminStore };

package/dist/outbox-admin/index.mjs

@@ -1,7 +1,8 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { i as NotFoundError, u as ValidationError } from "../errors-BH7YU_9O.mjs";
-import { t as defineResource } from "../defineResource-DxkMTjRn.mjs";
-import { n as getModuleExports, t as defineModule } from "../module-DpLJG2_N.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { i as NotFoundError, u as ValidationError } from "../errors-CW4anJBy.mjs";
+import { t as defineResource } from "../defineResource-gUp9ug66.mjs";
+import { n as getModuleExports, t as defineModule } from "../module--L0iBIZz.mjs";
+import { r as readOutboxHealth } from "../health-BYAwA6YS.mjs";
 //#region src/outbox-admin/module.ts
 /**
 * Strip the domain payload and the stack unless explicitly opted in.
@@ -51,20 +52,7 @@ function createOutboxAdminModule(deps) {
 				path: "/health",
 				summary: "Outbox health — pending, dead-letter and relay lag",
 				permissions: view,
-				rawHandler: async (_req, reply) => {
-					const [pending, deadLetter, relayLagMs] = await Promise.all([
-						deps.store.countByStatus("pending"),
-						deps.store.countByStatus("dead_letter"),
-						deps.store.oldestPendingAgeMs()
-					]);
-					const healthy = deadLetter === 0 && (relayLagMs === null || relayLagMs < lagUnhealthyMs);
-					return reply.send({
-						pending,
-						deadLetter,
-						relayLagMs,
-						healthy
-					});
-				}
+				rawHandler: async (_req, reply) => reply.send(await readOutboxHealth(deps.store, lagUnhealthyMs))
 			},
 			{
 				method: "GET",

package/dist/{outbox-module-D2z5WkDY.mjs → outbox-module-Ryk270jd.mjs}

@@ -1,11 +1,15 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as transactionContext } from "./transactionContext-CPbdlnVw.mjs";
-import { n as requestContext } from "./requestContext-cDkAUr-P.mjs";
-import { i as resolveEventTransport } from "./EventTransport-DSqD_Xsg.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "./store-helpers-dW71XVWL.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as transactionContext } from "./transactionContext-orvnGu4F.mjs";
+import { n as requestContext } from "./requestContext-C10UeFe5.mjs";
+import { n as evictToSize, r as touch } from "./boundedMap-DWiKW7lP.mjs";
+import { i as resolveEventTransport } from "./EventTransport-DZWDsaPa.mjs";
+import { t as emitObserved } from "./eventPlugin-BweHAVws.mjs";
+import { n as canReportHealth, r as readOutboxHealth } from "./health-BYAwA6YS.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "./store-helpers-Coj9RhOZ.mjs";
+import { t as claimedAttempts } from "./claimed-DYvQoZLv.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 { InvalidOutboxEventError, OutboxConflictError, OutboxOwnershipError, outboxPayloadFingerprint } from "@classytic/primitives/outbox";
 import { update } from "@classytic/repo-core/update";
 import { hostname } from "node:os";
 //#region src/events/outbox/backoff.ts
@@ -35,9 +39,9 @@ import { hostname } from "node:os";
 * @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=1 → 250–325ms   (+0–30%: jitter only ever DELAYS, never schedules early)
+* // attempt=2 → 500–650ms
+* // attempt=3 → 1000–1300ms
 * // attempt=10 → capped at 10_000ms
 * ```
 */
@@ -54,6 +58,12 @@ function exponentialBackoff(options) {
 }
 //#endregion
 //#region src/events/repository-outbox-adapter.ts
+/** A row read back from the repository that carries its event. */
+function isStoredRow(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const row = value;
+	return typeof row.type === "string" && typeof row.event === "object" && row.event !== null;
+}
 const DEFAULT_LEASE_MS$1 = 3e4;
 const DEFAULT_CLAIM_LIMIT = 100;
 const DEFAULT_PURGE_BATCH = 500;
@@ -110,10 +120,10 @@ function repositoryAsOutboxStore(repository, options) {
 			limit
 		}));
 		if (candidates.length === 0) return [];
-		return (await Promise.all(candidates.map((candidate) => {
+		const claimed = (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({
+			return r.findOneAndUpdate(and(eq(idField, candidate[idField]), claimableFilter(claimNow)), update({
 				set: {
 					leaseOwner: consumerId,
 					leaseExpiresAt
@@ -123,9 +133,22 @@ function repositoryAsOutboxStore(repository, options) {
 					fenceToken: 1
 				}
 			}), { returnDocument: "after" });
-		}))).filter((doc) => doc !== null).filter((doc) => isWellFormed(doc.event)).map((doc) => ({
+		}))).filter((doc) => doc !== null);
+		await Promise.all(claimed.filter((doc) => !isWellFormed(doc.event)).map((doc) => r.findOneAndUpdate(and(eq(idField, doc[idField]), eq("leaseOwner", consumerId), eq("fenceToken", doc.fenceToken ?? 0)), update({ set: {
+			status: "dead_letter",
+			leaseOwner: null,
+			leaseExpiresAt: null,
+			lastFailedAt: /* @__PURE__ */ new Date(),
+			firstFailedAt: doc.firstFailedAt ?? /* @__PURE__ */ new Date(),
+			lastError: {
+				message: "outbox row holds no event with a type and meta.id",
+				code: "MALFORMED_EVENT"
+			}
+		} }), { returnDocument: "after" })));
+		return claimed.filter((doc) => isWellFormed(doc.event)).map((doc) => ({
 			event: doc.event,
-			fencingToken: doc.fenceToken ?? 0
+			fencingToken: doc.fenceToken ?? 0,
+			...typeof doc.attempts === "number" ? { attempts: doc.attempts } : {}
 		}));
 	};
 	return {
@@ -157,7 +180,7 @@ function repositoryAsOutboxStore(repository, options) {
 				firstFailedAt: null,
 				lastFailedAt: null,
 				lastError: null,
-				dedupeKey: options?.dedupeKey ?? null,
+				dedupeKey: options?.dedupeKey ? `${event.type}:${options.dedupeKey}` : null,
 				partitionKey: options?.partitionKey ?? null,
 				headers: options?.headers ? { ...options.headers } : null,
 				createdAt: now
@@ -165,8 +188,11 @@ function repositoryAsOutboxStore(repository, options) {
 			try {
 				await r.create(doc, options?.session ? { session: options.session } : void 0);
 			} catch (err) {
-				if (isDuplicateKeyError(err)) return;
-				throw err;
+				if (!isDuplicateKeyError(err)) throw err;
+				const existing = await safeGetOne(doc.dedupeKey === null ? eq(idField, event.meta.id) : or(eq(idField, event.meta.id), eq("dedupeKey", doc.dedupeKey)));
+				if (!isStoredRow(existing)) throw err;
+				if (existing.type === event.type && outboxPayloadFingerprint(existing.event) === outboxPayloadFingerprint(event)) return;
+				throw new OutboxConflictError(event.meta.id, event.type);
 			}
 		},
 		async getPending(limit) {
@@ -183,6 +209,15 @@ function repositoryAsOutboxStore(repository, options) {
 			return (await claimPendingFenced(options)).map((c) => c.event);
 		},
 		claimPendingFenced,
+		...typeof repository.updateMany === "function" ? { async acknowledgeMany(eventIds) {
+			if (eventIds.length === 0) return;
+			await repository.updateMany?.(and(anyOf(idField, [...eventIds]), ne("status", "delivered")), update({ set: {
+				status: "delivered",
+				deliveredAt: /* @__PURE__ */ new Date(),
+				leaseOwner: null,
+				leaseExpiresAt: null
+			} }));
+		} } : {},
 		async acknowledge(eventId, options) {
 			const now = /* @__PURE__ */ new Date();
 			const baseFilter = and(eq(idField, eventId), ne("status", "delivered"));
@@ -375,6 +410,7 @@ var EventOutbox = class {
 	_consumerId;
 	_leaseMs;
 	_onError;
+	_onPublished;
 	_usePublishMany;
 	_sessionProvider;
 	_traceContextProvider;
@@ -384,9 +420,11 @@ var EventOutbox = class {
 	* 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}.
+	* resolved by another relay worker can't accumulate forever.
+	*
+	* A FALLBACK only: when the store reports `attempts` on the fenced claim
+	* (`repositoryAsOutboxStore` and primitives' `MemoryOutboxStore` do), the
+	* durable count wins — see the failure path in `relayBatch`.
 	*/
 	_attempts = /* @__PURE__ */ new Map();
 	constructor(opts) {
@@ -398,6 +436,7 @@ var EventOutbox = class {
 		this._consumerId = opts.consumerId ?? `relay-${Math.random().toString(36).slice(2, 10)}`;
 		this._leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS;
 		this._onError = opts.onError;
+		this._onPublished = opts.onPublished;
 		this._usePublishMany = opts.usePublishMany ?? true;
 		this._failurePolicy = opts.failurePolicy;
 		this._sessionProvider = opts.sessionProvider;
@@ -516,13 +555,18 @@ var EventOutbox = class {
 		if (!this._transport) return empty;
 		const claimStartedAt = Date.now();
 		const fenceTokens = /* @__PURE__ */ new Map();
+		const durableAttempts = /* @__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);
+			if (c.event?.meta?.id) {
+				fenceTokens.set(c.event.meta.id, c.fencingToken);
+				const attempts = claimedAttempts(c);
+				if (attempts !== void 0) durableAttempts.set(c.event.meta.id, attempts);
+			}
 			return c.event;
 		});
 		else if (this._store.claimPending) pending = await this._store.claimPending({
@@ -555,8 +599,7 @@ var EventOutbox = class {
 		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);
+			publishOutcomes = batchOutcomes(valid, await this._transport.publishMany?.(valid));
 		} catch (batchErr) {
 			publishOutcomes = /* @__PURE__ */ new Map();
 			const err = batchErr instanceof Error ? batchErr : new Error(String(batchErr));
@@ -572,6 +615,12 @@ var EventOutbox = class {
 				if (!canFail) break;
 			}
 		}
+		if (this._onPublished) for (const event of valid) {
+			if (publishOutcomes.get(event.meta.id) !== null) continue;
+			try {
+				this._onPublished(event);
+			} catch {}
+		}
 		let stopBatch = false;
 		for (const event of valid) {
 			if (stopBatch) break;
@@ -583,13 +632,10 @@ var EventOutbox = class {
 					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 localAttempts = (this._attempts.get(event.meta.id) ?? 0) + 1;
+				const attempts = Math.max(localAttempts, durableAttempts.get(event.meta.id) ?? 0);
+				touch(this._attempts, event.meta.id, attempts);
+				evictToSize(this._attempts, MAX_TRACKED_ATTEMPTS);
 				const fenceToken = fenceTokens.get(event.meta.id);
 				let failOpts = {
 					consumerId: this._consumerId,
@@ -679,6 +725,22 @@ var EventOutbox = class {
 		return this._store.purge(olderThanMs);
 	}
 };
+/**
+* A `publishMany` result must name exactly the events it was given. A missing outcome would read as
+* success and be ACKNOWLEDGED unpublished, so any mismatch fails the whole batch — nothing is acked.
+*/
+function batchOutcomes(events, result) {
+	const problem = batchContractProblem(events, result);
+	if (!problem) return new Map(result);
+	const err = /* @__PURE__ */ new Error(`[arc outbox] transport publishMany ${problem} — the whole batch is failed, none acknowledged`);
+	return new Map(events.map((e) => [e.meta.id, err]));
+}
+function batchContractProblem(events, result) {
+	if (!(result instanceof Map)) return "returned no outcome map";
+	const ids = new Set(events.map((e) => e.meta.id));
+	for (const id of ids) if (!result.has(id)) return `returned no outcome for event '${id}'`;
+	for (const id of result.keys()) if (!ids.has(id)) return `returned an outcome for unknown event '${id}'`;
+}
 function normalizeError(err) {
 	if (err instanceof Error) return {
 		message: err.message,
@@ -723,6 +785,10 @@ function normalizeError(err) {
 */
 /** Default relay cadence. Frequent enough that a retry is not a user-visible delay. */
 const DEFAULT_RELAY_EVERY_MS = 5e3;
+/** How long the readiness check reuses a relay-health reading. See `health.probeCacheMs`. */
+const DEFAULT_PROBE_CACHE_MS = 5e3;
+/** How often an unhealthy outbox is logged. See `health.alertEveryMs`. */
+const DEFAULT_HEALTH_ALERT_EVERY_MS = 3e5;
 /**
 * One relay identity per RELAY INSTANCE — `<name>:<hostname>:<pid>:<random>`.
 *
@@ -777,6 +843,35 @@ function mintConsumerId(name) {
 function createOutboxModule(options) {
 	const name = options.name ?? "outbox";
 	const relayEveryMs = options.relayEveryMs ?? DEFAULT_RELAY_EVERY_MS;
+	const lagUnhealthyMs = (options.health === false ? void 0 : options.health?.relayLagUnhealthyMs) ?? 3e5;
+	const probeCacheMs = (options.health === false ? void 0 : options.health?.probeCacheMs) ?? DEFAULT_PROBE_CACHE_MS;
+	if (!Number.isFinite(probeCacheMs) || probeCacheMs < 0) throw new Error(`Outbox module "${name}": health.probeCacheMs must be a non-negative number, got ${String(probeCacheMs)}.`);
+	const alertEveryMs = options.health === false ? 0 : options.health?.alertEveryMs ?? DEFAULT_HEALTH_ALERT_EVERY_MS;
+	if (!Number.isFinite(alertEveryMs) || alertEveryMs < 0) throw new Error(`Outbox module "${name}": health.alertEveryMs must be a non-negative number, got ${String(alertEveryMs)}.`);
+	let log;
+	/** The unmeasurable-store warning is said once, not every alert tick. */
+	let warnedUnmeasurable = false;
+	/**
+	* The readiness probe's reading, reused for `probeCacheMs` and shared by
+	* concurrent probes (single-flight). A failed or unmeasurable reading is
+	* cached as unhealthy for the same window — retrying a failing store on
+	* every probe is load on the thing that is already failing.
+	*/
+	let probeReading;
+	let probeInFlight;
+	const probeHealthy = (read) => {
+		if (probeReading && Date.now() - probeReading.at < probeCacheMs) return Promise.resolve(probeReading.healthy);
+		probeInFlight ??= read().then((h) => h.healthy, () => false).then((healthy) => {
+			probeReading = {
+				at: Date.now(),
+				healthy
+			};
+			return healthy;
+		}).finally(() => {
+			probeInFlight = void 0;
+		});
+		return probeInFlight;
+	};
 	/**
 	* Built at bootstrap and reused by the schedule.
 	*
@@ -785,9 +880,20 @@ function createOutboxModule(options) {
 	* depends on for exactly-once publishing.
 	*/
 	let exports;
+	/** Passes THIS module started (nudge, schedule) that have not settled — `drain()` waits on them. */
+	const inFlightPasses = /* @__PURE__ */ new Set();
+	const trackPass = (pass) => {
+		inFlightPasses.add(pass);
+		const untrack = () => {
+			inFlightPasses.delete(pass);
+		};
+		pass.then(untrack, untrack);
+		return pass;
+	};
 	return {
 		name,
 		bootstrap: (fastify) => {
+			log = fastify.log;
 			const store = typeof options.store === "function" ? options.store(fastify) : options.store;
 			/**
 			* The RAW transport, never `fastify.events`.
@@ -811,6 +917,7 @@ function createOutboxModule(options) {
 			const relay = new EventOutbox({
 				store,
 				transport,
+				onPublished: (event) => emitObserved(fastify.events, event),
 				...options.batchSize !== void 0 ? { batchSize: options.batchSize } : {},
 				...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
 				consumerId: options.consumerId ?? mintConsumerId(name),
@@ -835,22 +942,57 @@ function createOutboxModule(options) {
 			const requestDrain = () => {
 				if (drainQueued) return;
 				drainQueued = true;
+				let passDone = () => {};
+				trackPass(new Promise((resolve) => passDone = resolve));
 				setImmediate(() => {
 					drainQueued = false;
 					requestContext.storage.exit(() => {
 						relay.relayBatch().catch((err) => {
 							fastify.log.error({ err }, `outbox relay "${name}" requested drain failed`);
-						});
+						}).finally(passDone);
 					});
 				});
 			};
+			const drain = ({ maxPasses = 100 } = {}) => requestContext.storage.exit(async () => {
+				const total = {
+					passes: 0,
+					relayed: 0,
+					publishFailed: 0,
+					deadLettered: 0,
+					drained: false
+				};
+				while (total.passes < maxPasses) {
+					if (inFlightPasses.size > 0) await Promise.allSettled([...inFlightPasses]);
+					const r = await relay.relayBatch();
+					total.passes++;
+					total.relayed += r.relayed;
+					total.publishFailed += r.publishFailed;
+					total.deadLettered += r.deadLettered;
+					if (r.attempted === 0 && inFlightPasses.size === 0) {
+						total.drained = true;
+						break;
+					}
+				}
+				return total;
+			});
+			const health = async () => {
+				if (!canReportHealth(store)) throw new Error(`Outbox module "${name}": relay health needs BOTH countByStatus and oldestPendingAgeMs on the store, and it is missing at least one.`);
+				return readOutboxHealth(store, lagUnhealthyMs);
+			};
 			exports = {
 				store,
 				relay,
-				requestDrain
+				requestDrain,
+				drain,
+				health
 			};
 			return exports;
 		},
+		...options.health === false ? {} : { healthChecks: [{
+			name: `${name}.relay`,
+			critical: false,
+			check: () => exports ? probeHealthy(exports.health) : Promise.resolve(false)
+		}] },
 		/**
 		* 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.
@@ -861,9 +1003,37 @@ function createOutboxModule(options) {
 			every: relayEveryMs,
 			runOnStart: options.runOnStart ?? true,
 			handler: async () => {
-				await exports?.relay.relay();
+				if (exports) await trackPass(exports.relay.relay());
+			}
+		}, ...alertEveryMs > 0 ? [{
+			name: `${name}.health`,
+			kind: "relay",
+			every: alertEveryMs,
+			handler: async () => {
+				if (!exports || !log) return;
+				if (!canReportHealth(exports.store)) {
+					if (!warnedUnmeasurable) {
+						warnedUnmeasurable = true;
+						log.warn({
+							marker: "OUTBOX_HEALTH_UNMEASURABLE",
+							outbox: name
+						}, `outbox "${name}" store lacks countByStatus or oldestPendingAgeMs — relay stalls cannot be alerted on`);
+					}
+					return;
+				}
+				const h = await exports.health();
+				if (h.deadLetter > 0) log.warn({
+					marker: "OUTBOX_DEAD_LETTER",
+					outbox: name,
+					...h
+				}, `outbox "${name}" has dead-lettered events — inspect and replay them`);
+				if (h.relayLagMs !== null && h.relayLagMs >= lagUnhealthyMs) log.error({
+					marker: "OUTBOX_RELAY_LAG",
+					outbox: name,
+					...h
+				}, `outbox "${name}" relay is behind — events are committed but not delivered`);
 			}
-		}]
+		}] : []]
 	};
 }
 //#endregion