@btravstack/outbox 0.0.0-stage → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @btravstack/outbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> The transactional outbox relay for [`@btravstack/core`](../core): a poll loop
+> that publishes committed facts in outbox order, a per-tenant
+> claim so replicas take turns rather than race for the same rows, and a Prisma
+> 8 store.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/reference/outbox)** ·
+[API Reference](https://btravstack.github.io/btravstack/api/outbox/)
+
+```sh
+pnpm add @btravstack/outbox @btravstack/core @btravstack/config @btravstack/di unthrown
+```
+
+Four peer dependencies, plus `@prisma/orm-postgres` — optional, and needed only
+if you compose the Prisma store from `@btravstack/outbox/prisma`. Node `>=22`.
+
+## A worked example
+
+<!-- doctest: group=order-amqp-worker -->
+<!-- doctest: prelude
+import { Module, Port, Provider } from "@btravstack/di";
+import type { OutboxDatabase } from "@btravstack/outbox/prisma";
+import { TaggedError, type AsyncResult } from "unthrown";
+
+// The application's own halves, declared here so this sample stands on the
+// published packages alone: its database port, from `prismaDatabase`, and a
+// transport client of its own contract.
+class OrderDatabase extends Port("ReadmeOrderDatabase")<OutboxDatabase<unknown>> {}
+class Refused extends TaggedError("Refused") {}
+class Broker extends Port("ReadmeBroker")<{
+  readonly send: (topic: string, body: unknown) => AsyncResult<void, Refused>;
+}> {}
+declare const BrokerModule: Module<Broker, never, never>;
+declare const OrderPersistenceModule: Module<OrderDatabase, never, never>;
+-->
+
+The application writes its outbox row in the same transaction as the row it
+describes — that stays its own. What it provides the relay is where the table
+is, and what publishing a row means:
+
+```ts
+import { OutboxPublisher, OutboxStore, outbox } from "@btravstack/outbox";
+import { prismaOutboxStore } from "@btravstack/outbox/prisma";
+
+const store = Provider(OutboxStore)({
+  inject: { db: OrderDatabase },
+  sync: ({ db }) => prismaOutboxStore(db, { schema: "orders" }),
+});
+
+const publisher = Provider(OutboxPublisher)({
+  inject: { broker: Broker },
+  sync: ({ broker }) => ({
+    publish: (message) =>
+      broker.send(`${message.kind}.changed`, {
+        eventId: message.id,
+        tenantId: message.tenantId,
+        id: message.subjectId,
+        payload: message.payload === null ? null : JSON.parse(message.payload),
+      }),
+  }),
+});
+
+export const Relay = Module("Relay")({
+  imports: [OrderPersistenceModule, BrokerModule, outbox()],
+  provides: [store, publisher],
+  exports: [],
+});
+```
+
+## Options
+
+| Option              | Where                        | What it is                                                                       |
+| ------------------- | ---------------------------- | -------------------------------------------------------------------------------- |
+| `OUTBOX_TENANTS`    | environment, or `tenants`    | the tenants this relay serves, comma-separated — required                        |
+| `OUTBOX_POLL_MS`    | environment, or `pollMs`     | the idle sleep between sweeps (default `200`)                                    |
+| `OUTBOX_MAX_LAG_MS` | environment, or `maxLagMs`   | the oldest pending age the `outbox` health check tolerates (default 60 s)        |
+| `clock`             | `outbox({ clock })`          | what the poll sleeps on and the lag is measured against (default: `systemClock`) |
+| `schema`, `table`   | `prismaOutboxStore(db, {…})` | where the model lives (default `public`, `outboxMessage`)                        |
+
+The full table — defaults, semantics, the table's PSL and the reasoning — lives
+on [the reference page](https://btravstack.github.io/btravstack/reference/outbox),
+which is this list's one detailed home.
+
+## What it decides, and what it does not
+
+**It decides** that delivery is at-least-once, that one relay publishes a
+tenant at a time while its claiming session lives — so replicas take turns
+rather than race for a tenant's rows, and a tenant's committed facts go out in
+outbox order (which is not commit order: the reference page says what that
+means for a subject); a session lost mid-batch, like a crash between a publish
+and its mark, re-publishes — that a refused
+publish stops its tenant's batch and backs that tenant off, and that a tenant
+falling behind is unhealthy on `/healthz`. A subscriber deduplicates on the
+outbox id, which the publisher puts on the wire.
+
+**It does not decide** what a publish is, which transport it rides or how the
+payload is encoded — that is your `OutboxPublisher` — nor the transaction that
+writes the row, which is your adapter's. There is no exactly-once, no
+retention and no second store; the reasons are in [`AGENTS.md`](./AGENTS.md).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,213 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_di = require("@btravstack/di");
+let _btravstack_core = require("@btravstack/core");
+let unthrown = require("unthrown");
+let _btravstack_config = require("@btravstack/config");
+//#region src/outbox.ts
+/**
+* Where the relay reads from. An application provides it — from
+* `@btravstack/outbox/prisma`'s `prismaOutboxStore`, `memoryOutboxStore`, or
+* an adapter of its own — beside the transaction that writes the rows, which
+* stays the application's.
+*/
+var OutboxStore = class extends (0, _btravstack_di.Port)("OutboxStore") {};
+var OutboxPublisher = class extends (0, _btravstack_di.Port)("OutboxPublisher") {};
+//#endregion
+//#region src/memory.ts
+/**
+* An outbox held in the process: for tests, and for an application whose
+* in-memory repositories need somewhere to record their facts. Its claim is a
+* per-tenant flag, so two relays over ONE instance behave as two replicas over
+* one table do — which is the only sharing an in-process store can have.
+*/
+const memoryOutboxStore = (clock = _btravstack_core.systemClock) => {
+	const messages = [];
+	const published = /* @__PURE__ */ new Set();
+	const claimed = /* @__PURE__ */ new Set();
+	const pendingOf = (tenantId, limit) => messages.filter((message) => message.tenantId === tenantId && !published.has(message.id)).slice(0, limit);
+	return {
+		append: (message) => {
+			messages.push({
+				...message,
+				id: messages.length + 1,
+				occurredAt: new Date(clock.now())
+			});
+		},
+		pending: (tenantId, limit) => (0, unthrown.OkAsync)(pendingOf(tenantId, limit)),
+		oldestPending: (tenantIds) => (0, unthrown.OkAsync)(tenantIds.flatMap((tenantId) => pendingOf(tenantId, 1).map(({ occurredAt }) => ({
+			tenantId,
+			occurredAt
+		})))),
+		claim: (tenantId, limit, relay) => {
+			if (claimed.has(tenantId)) return (0, unthrown.OkAsync)();
+			claimed.add(tenantId);
+			return (0, unthrown.OkAsync)().flatMap(() => relay(pendingOf(tenantId, limit))).map((ids) => {
+				for (const id of ids) published.add(id);
+			}).tapFailure(() => claimed.delete(tenantId)).tap(() => claimed.delete(tenantId));
+		}
+	};
+};
+//#endregion
+//#region src/relay.ts
+/** How many messages one claim hands the publisher. */
+const BATCH = 32;
+/** The ceiling the back-off doubles towards, unless the poll interval is already longer. */
+const MAX_BACKOFF_MS = 3e4;
+var OutboxConfig = class extends (0, _btravstack_di.Port)("OutboxConfig") {};
+/** The running relay. Nothing resolves it; it exists to be started and stopped. */
+var OutboxRelay = class extends (0, _btravstack_di.Port)("OutboxRelay") {};
+/** A tenant is bounded — the relay is told its tenants — so it rides the instruments; the subject does not. */
+const publishing = (message) => ({
+	component: "outbox",
+	name: "publish",
+	attributes: {
+		operation: "publish",
+		kind: message.kind,
+		"btravstack.tenant_id": message.tenantId
+	},
+	details: {
+		"btravstack.outbox.id": message.id,
+		"btravstack.outbox.subject": message.subjectId
+	}
+});
+/** Not traced: one span per tenant per poll would bury the publishes it contains. */
+const claiming = (tenantId) => ({
+	component: "outbox",
+	name: "claim",
+	attributes: {
+		operation: "claim",
+		"btravstack.tenant_id": tenantId
+	},
+	traced: false
+});
+const startRelay = (store, publisher, observers, clock, { tenants, pollMs }) => {
+	const stopping = new AbortController();
+	const { signal } = stopping;
+	const publishInOrder = async (batch) => {
+		const published = [];
+		for (const message of batch) {
+			if (!(await (0, _btravstack_core.observed)(observers, publishing(message), () => publisher.publish(message))).isOk()) break;
+			published.push(message.id);
+		}
+		return published;
+	};
+	const sweep = async (tenantId) => {
+		let swept = "idle";
+		return (await (0, _btravstack_core.observed)(observers, claiming(tenantId), () => store.claim(tenantId, BATCH, (batch) => (0, unthrown.fromSafePromise)(publishInOrder(batch).then((published) => {
+			swept = published.length < batch.length ? "failed" : batch.length === BATCH ? "full" : "idle";
+			return published;
+		}))))).isOk() ? swept : "failed";
+	};
+	const backoff = (failures) => Math.min(pollMs * 2 ** failures, Math.max(pollMs, MAX_BACKOFF_MS));
+	const running = (async () => {
+		const schedule = tenants.map((tenantId) => ({
+			tenantId,
+			due: clock.now(),
+			failures: 0
+		}));
+		while (!signal.aborted) {
+			for (const tenant of schedule) {
+				if (signal.aborted) break;
+				if (tenant.due > clock.now()) continue;
+				const swept = await sweep(tenant.tenantId);
+				tenant.failures = swept === "failed" ? tenant.failures + 1 : 0;
+				tenant.due = clock.now() + (swept === "full" ? 0 : backoff(tenant.failures));
+			}
+			const wait = Math.min(...schedule.map(({ due }) => due)) - clock.now();
+			if (wait > 0) await clock.sleep(wait, signal);
+		}
+	})();
+	return { stop: () => (0, unthrown.fromSafePromise)((async () => {
+		stopping.abort();
+		await running;
+	})()) };
+};
+/**
+* The outbox relay: the other half of a write that recorded its fact in the
+* same transaction as the row it describes. It claims each tenant's oldest
+* pending messages, hands them to the application's {@link OutboxPublisher}
+* in outbox order, marks published what was published, and sleeps.
+*
+* ```ts
+* outbox({ tenants: ["acme"] });
+* ```
+*
+* **At-least-once, with replicas taking turns.** A crash between a publish and
+* its mark re-publishes on the next claim, and so does a claiming session the
+* database ends mid-batch, so a subscriber must tolerate a repeat, keyed by the
+* outbox id. What the claim rules out is replicas racing: a tenant is held by
+* one relay while its claiming session lives and skipped by the rest, so its
+* committed facts go out in outbox order — which is not commit order: an id
+* still in an open transaction surfaces after a higher one that committed.
+*
+* **A refused publish stops the tenant's batch** and backs that tenant off,
+* doubling from the poll interval to 30 seconds, so a later fact never
+* overtakes an earlier one and no other tenant waits. A message the publisher refuses forever therefore holds its tenant's
+* outbox — which is what the health check is for: it reports a tenant whose
+* oldest pending message is older than `maxLagMs`.
+*
+* Started as the graph builds, before the runtime accepts anything, and
+* stopped when the application scope closes, after the runtime has drained.
+* Every claim and publish is reported to `Observers`; the module holds no
+* logger of its own.
+*/
+const outbox = (options = {}) => {
+	const clock = options.clock ?? _btravstack_core.systemClock;
+	const config = _btravstack_config.Config.provider(OutboxConfig)(_btravstack_config.Config.object({
+		tenants: _btravstack_config.Config.pinned(options.tenants, _btravstack_config.Config.list("OUTBOX_TENANTS")),
+		pollMs: _btravstack_config.Config.pinned(options.pollMs, _btravstack_config.Config.integer("OUTBOX_POLL_MS", {
+			min: 1,
+			max: 6e4,
+			default: 200
+		})),
+		maxLagMs: _btravstack_config.Config.pinned(options.maxLagMs, _btravstack_config.Config.integer("OUTBOX_MAX_LAG_MS", {
+			min: 1,
+			default: 6e4
+		}))
+	}));
+	const relay = (0, _btravstack_di.Provider)(OutboxRelay)({
+		inject: {
+			store: OutboxStore,
+			publisher: OutboxPublisher,
+			observers: _btravstack_core.Observers,
+			config: OutboxConfig
+		},
+		acquire: ({ store, publisher, observers, config: bound }) => (0, unthrown.OkAsync)(startRelay(store, publisher, observers, clock, bound)),
+		release: (running) => running.stop().get()
+	});
+	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
+		inject: {
+			store: OutboxStore,
+			config: OutboxConfig
+		},
+		sync: ({ store, config: { tenants, maxLagMs } }) => ({
+			name: "outbox",
+			check: () => store.oldestPending(tenants).flatMap((oldest) => {
+				const behind = oldest.map(({ tenantId, occurredAt }) => ({
+					tenantId,
+					lagMs: clock.now() - occurredAt.getTime()
+				})).filter(({ lagMs }) => lagMs > maxLagMs);
+				return behind.length === 0 ? (0, unthrown.OkAsync)() : (0, unthrown.ErrAsync)(new _btravstack_core.HealthCheckFailed({ reason: behind.map(({ tenantId, lagMs }) => `${tenantId} is ${String(lagMs)} ms behind`).join(", ") }));
+			})
+		})
+	});
+	return (0, _btravstack_di.Module)("Outbox")({
+		needs: [
+			_btravstack_config.Env,
+			OutboxStore,
+			OutboxPublisher
+		],
+		provides: [
+			config,
+			_btravstack_core.noObserverMember,
+			relay,
+			healthCheck
+		],
+		exports: [_btravstack_core.HealthChecks]
+	});
+};
+//#endregion
+exports.OutboxPublisher = OutboxPublisher;
+exports.OutboxStore = OutboxStore;
+exports.memoryOutboxStore = memoryOutboxStore;
+exports.outbox = outbox;

package/dist/index.d.cts

@@ -0,0 +1,63 @@
+import { a as OutboxStoreService, i as OutboxStore, n as OutboxPublisher, o as PublishRefused, r as OutboxPublisherService, t as OutboxMessage } from "./outbox-Bn2wYUh6.cjs";
+import { Clock, HealthChecks } from "@btravstack/core";
+import { ConfigInvalid, Env } from "@btravstack/config";
+import { Module, Scope } from "@btravstack/di";
+//#region src/memory.d.ts
+/** What an in-memory write appends: the envelope, without the two fields the store assigns. */
+type OutboxAppend = Omit<OutboxMessage, "id" | "occurredAt">;
+/** The in-process store, plus the write half an application's in-memory adapter calls. */
+type MemoryOutboxStore = OutboxStoreService & {
+  readonly append: (message: OutboxAppend) => void;
+};
+/**
+ * An outbox held in the process: for tests, and for an application whose
+ * in-memory repositories need somewhere to record their facts. Its claim is a
+ * per-tenant flag, so two relays over ONE instance behave as two replicas over
+ * one table do — which is the only sharing an in-process store can have.
+ */
+export declare const memoryOutboxStore: (clock?: Clock) => MemoryOutboxStore;
+//#endregion
+//#region src/relay.d.ts
+/** What {@link outbox} is handed. Each field pins the variable named beside it. */
+type OutboxOptions = {
+  /** The tenants this relay serves — `OUTBOX_TENANTS`, comma-separated, required. */
+  readonly tenants?: readonly string[];
+  /** The idle sleep between sweeps — `OUTBOX_POLL_MS` (default `200`). */
+  readonly pollMs?: number;
+  /** The oldest pending age `/healthz` tolerates — `OUTBOX_MAX_LAG_MS` (default `60_000`). */
+  readonly maxLagMs?: number;
+  /** What the poll sleeps on and the lag is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock;
+};
+/**
+ * The outbox relay: the other half of a write that recorded its fact in the
+ * same transaction as the row it describes. It claims each tenant's oldest
+ * pending messages, hands them to the application's {@link OutboxPublisher}
+ * in outbox order, marks published what was published, and sleeps.
+ *
+ * ```ts
+ * outbox({ tenants: ["acme"] });
+ * ```
+ *
+ * **At-least-once, with replicas taking turns.** A crash between a publish and
+ * its mark re-publishes on the next claim, and so does a claiming session the
+ * database ends mid-batch, so a subscriber must tolerate a repeat, keyed by the
+ * outbox id. What the claim rules out is replicas racing: a tenant is held by
+ * one relay while its claiming session lives and skipped by the rest, so its
+ * committed facts go out in outbox order — which is not commit order: an id
+ * still in an open transaction surfaces after a higher one that committed.
+ *
+ * **A refused publish stops the tenant's batch** and backs that tenant off,
+ * doubling from the poll interval to 30 seconds, so a later fact never
+ * overtakes an earlier one and no other tenant waits. A message the publisher refuses forever therefore holds its tenant's
+ * outbox — which is what the health check is for: it reports a tenant whose
+ * oldest pending message is older than `maxLagMs`.
+ *
+ * Started as the graph builds, before the runtime accepts anything, and
+ * stopped when the application scope closes, after the runtime has drained.
+ * Every claim and publish is reported to `Observers`; the module holds no
+ * logger of its own.
+ */
+export declare const outbox: (options?: OutboxOptions) => Module<HealthChecks, ConfigInvalid, Env | OutboxStore | OutboxPublisher | Scope>;
+//#endregion
+export { type MemoryOutboxStore, type OutboxAppend, type OutboxMessage, type OutboxOptions, OutboxPublisher, type OutboxPublisherService, OutboxStore, type OutboxStoreService, type PublishRefused };

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+import { a as OutboxStoreService, i as OutboxStore, n as OutboxPublisher, o as PublishRefused, r as OutboxPublisherService, t as OutboxMessage } from "./outbox-Bn2wYUh6.mjs";
+import { Module, Scope } from "@btravstack/di";
+import { Clock, HealthChecks } from "@btravstack/core";
+import { ConfigInvalid, Env } from "@btravstack/config";
+//#region src/memory.d.ts
+/** What an in-memory write appends: the envelope, without the two fields the store assigns. */
+type OutboxAppend = Omit<OutboxMessage, "id" | "occurredAt">;
+/** The in-process store, plus the write half an application's in-memory adapter calls. */
+type MemoryOutboxStore = OutboxStoreService & {
+  readonly append: (message: OutboxAppend) => void;
+};
+/**
+ * An outbox held in the process: for tests, and for an application whose
+ * in-memory repositories need somewhere to record their facts. Its claim is a
+ * per-tenant flag, so two relays over ONE instance behave as two replicas over
+ * one table do — which is the only sharing an in-process store can have.
+ */
+export declare const memoryOutboxStore: (clock?: Clock) => MemoryOutboxStore;
+//#endregion
+//#region src/relay.d.ts
+/** What {@link outbox} is handed. Each field pins the variable named beside it. */
+type OutboxOptions = {
+  /** The tenants this relay serves — `OUTBOX_TENANTS`, comma-separated, required. */
+  readonly tenants?: readonly string[];
+  /** The idle sleep between sweeps — `OUTBOX_POLL_MS` (default `200`). */
+  readonly pollMs?: number;
+  /** The oldest pending age `/healthz` tolerates — `OUTBOX_MAX_LAG_MS` (default `60_000`). */
+  readonly maxLagMs?: number;
+  /** What the poll sleeps on and the lag is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock;
+};
+/**
+ * The outbox relay: the other half of a write that recorded its fact in the
+ * same transaction as the row it describes. It claims each tenant's oldest
+ * pending messages, hands them to the application's {@link OutboxPublisher}
+ * in outbox order, marks published what was published, and sleeps.
+ *
+ * ```ts
+ * outbox({ tenants: ["acme"] });
+ * ```
+ *
+ * **At-least-once, with replicas taking turns.** A crash between a publish and
+ * its mark re-publishes on the next claim, and so does a claiming session the
+ * database ends mid-batch, so a subscriber must tolerate a repeat, keyed by the
+ * outbox id. What the claim rules out is replicas racing: a tenant is held by
+ * one relay while its claiming session lives and skipped by the rest, so its
+ * committed facts go out in outbox order — which is not commit order: an id
+ * still in an open transaction surfaces after a higher one that committed.
+ *
+ * **A refused publish stops the tenant's batch** and backs that tenant off,
+ * doubling from the poll interval to 30 seconds, so a later fact never
+ * overtakes an earlier one and no other tenant waits. A message the publisher refuses forever therefore holds its tenant's
+ * outbox — which is what the health check is for: it reports a tenant whose
+ * oldest pending message is older than `maxLagMs`.
+ *
+ * Started as the graph builds, before the runtime accepts anything, and
+ * stopped when the application scope closes, after the runtime has drained.
+ * Every claim and publish is reported to `Observers`; the module holds no
+ * logger of its own.
+ */
+export declare const outbox: (options?: OutboxOptions) => Module<HealthChecks, ConfigInvalid, Env | OutboxStore | OutboxPublisher | Scope>;
+//#endregion
+export { type MemoryOutboxStore, type OutboxAppend, type OutboxMessage, type OutboxOptions, OutboxPublisher, type OutboxPublisherService, OutboxStore, type OutboxStoreService, type PublishRefused };

package/dist/index.mjs

@@ -0,0 +1,209 @@
+import { Module, Port, Provider } from "@btravstack/di";
+import { HealthCheckFailed, HealthChecks, Observers, noObserverMember, observed, systemClock } from "@btravstack/core";
+import { ErrAsync, OkAsync, fromSafePromise } from "unthrown";
+import { Config, Env } from "@btravstack/config";
+//#region src/outbox.ts
+/**
+* Where the relay reads from. An application provides it — from
+* `@btravstack/outbox/prisma`'s `prismaOutboxStore`, `memoryOutboxStore`, or
+* an adapter of its own — beside the transaction that writes the rows, which
+* stays the application's.
+*/
+var OutboxStore = class extends Port("OutboxStore") {};
+var OutboxPublisher = class extends Port("OutboxPublisher") {};
+//#endregion
+//#region src/memory.ts
+/**
+* An outbox held in the process: for tests, and for an application whose
+* in-memory repositories need somewhere to record their facts. Its claim is a
+* per-tenant flag, so two relays over ONE instance behave as two replicas over
+* one table do — which is the only sharing an in-process store can have.
+*/
+const memoryOutboxStore = (clock = systemClock) => {
+	const messages = [];
+	const published = /* @__PURE__ */ new Set();
+	const claimed = /* @__PURE__ */ new Set();
+	const pendingOf = (tenantId, limit) => messages.filter((message) => message.tenantId === tenantId && !published.has(message.id)).slice(0, limit);
+	return {
+		append: (message) => {
+			messages.push({
+				...message,
+				id: messages.length + 1,
+				occurredAt: new Date(clock.now())
+			});
+		},
+		pending: (tenantId, limit) => OkAsync(pendingOf(tenantId, limit)),
+		oldestPending: (tenantIds) => OkAsync(tenantIds.flatMap((tenantId) => pendingOf(tenantId, 1).map(({ occurredAt }) => ({
+			tenantId,
+			occurredAt
+		})))),
+		claim: (tenantId, limit, relay) => {
+			if (claimed.has(tenantId)) return OkAsync();
+			claimed.add(tenantId);
+			return OkAsync().flatMap(() => relay(pendingOf(tenantId, limit))).map((ids) => {
+				for (const id of ids) published.add(id);
+			}).tapFailure(() => claimed.delete(tenantId)).tap(() => claimed.delete(tenantId));
+		}
+	};
+};
+//#endregion
+//#region src/relay.ts
+/** How many messages one claim hands the publisher. */
+const BATCH = 32;
+/** The ceiling the back-off doubles towards, unless the poll interval is already longer. */
+const MAX_BACKOFF_MS = 3e4;
+var OutboxConfig = class extends Port("OutboxConfig") {};
+/** The running relay. Nothing resolves it; it exists to be started and stopped. */
+var OutboxRelay = class extends Port("OutboxRelay") {};
+/** A tenant is bounded — the relay is told its tenants — so it rides the instruments; the subject does not. */
+const publishing = (message) => ({
+	component: "outbox",
+	name: "publish",
+	attributes: {
+		operation: "publish",
+		kind: message.kind,
+		"btravstack.tenant_id": message.tenantId
+	},
+	details: {
+		"btravstack.outbox.id": message.id,
+		"btravstack.outbox.subject": message.subjectId
+	}
+});
+/** Not traced: one span per tenant per poll would bury the publishes it contains. */
+const claiming = (tenantId) => ({
+	component: "outbox",
+	name: "claim",
+	attributes: {
+		operation: "claim",
+		"btravstack.tenant_id": tenantId
+	},
+	traced: false
+});
+const startRelay = (store, publisher, observers, clock, { tenants, pollMs }) => {
+	const stopping = new AbortController();
+	const { signal } = stopping;
+	const publishInOrder = async (batch) => {
+		const published = [];
+		for (const message of batch) {
+			if (!(await observed(observers, publishing(message), () => publisher.publish(message))).isOk()) break;
+			published.push(message.id);
+		}
+		return published;
+	};
+	const sweep = async (tenantId) => {
+		let swept = "idle";
+		return (await observed(observers, claiming(tenantId), () => store.claim(tenantId, BATCH, (batch) => fromSafePromise(publishInOrder(batch).then((published) => {
+			swept = published.length < batch.length ? "failed" : batch.length === BATCH ? "full" : "idle";
+			return published;
+		}))))).isOk() ? swept : "failed";
+	};
+	const backoff = (failures) => Math.min(pollMs * 2 ** failures, Math.max(pollMs, MAX_BACKOFF_MS));
+	const running = (async () => {
+		const schedule = tenants.map((tenantId) => ({
+			tenantId,
+			due: clock.now(),
+			failures: 0
+		}));
+		while (!signal.aborted) {
+			for (const tenant of schedule) {
+				if (signal.aborted) break;
+				if (tenant.due > clock.now()) continue;
+				const swept = await sweep(tenant.tenantId);
+				tenant.failures = swept === "failed" ? tenant.failures + 1 : 0;
+				tenant.due = clock.now() + (swept === "full" ? 0 : backoff(tenant.failures));
+			}
+			const wait = Math.min(...schedule.map(({ due }) => due)) - clock.now();
+			if (wait > 0) await clock.sleep(wait, signal);
+		}
+	})();
+	return { stop: () => fromSafePromise((async () => {
+		stopping.abort();
+		await running;
+	})()) };
+};
+/**
+* The outbox relay: the other half of a write that recorded its fact in the
+* same transaction as the row it describes. It claims each tenant's oldest
+* pending messages, hands them to the application's {@link OutboxPublisher}
+* in outbox order, marks published what was published, and sleeps.
+*
+* ```ts
+* outbox({ tenants: ["acme"] });
+* ```
+*
+* **At-least-once, with replicas taking turns.** A crash between a publish and
+* its mark re-publishes on the next claim, and so does a claiming session the
+* database ends mid-batch, so a subscriber must tolerate a repeat, keyed by the
+* outbox id. What the claim rules out is replicas racing: a tenant is held by
+* one relay while its claiming session lives and skipped by the rest, so its
+* committed facts go out in outbox order — which is not commit order: an id
+* still in an open transaction surfaces after a higher one that committed.
+*
+* **A refused publish stops the tenant's batch** and backs that tenant off,
+* doubling from the poll interval to 30 seconds, so a later fact never
+* overtakes an earlier one and no other tenant waits. A message the publisher refuses forever therefore holds its tenant's
+* outbox — which is what the health check is for: it reports a tenant whose
+* oldest pending message is older than `maxLagMs`.
+*
+* Started as the graph builds, before the runtime accepts anything, and
+* stopped when the application scope closes, after the runtime has drained.
+* Every claim and publish is reported to `Observers`; the module holds no
+* logger of its own.
+*/
+const outbox = (options = {}) => {
+	const clock = options.clock ?? systemClock;
+	const config = Config.provider(OutboxConfig)(Config.object({
+		tenants: Config.pinned(options.tenants, Config.list("OUTBOX_TENANTS")),
+		pollMs: Config.pinned(options.pollMs, Config.integer("OUTBOX_POLL_MS", {
+			min: 1,
+			max: 6e4,
+			default: 200
+		})),
+		maxLagMs: Config.pinned(options.maxLagMs, Config.integer("OUTBOX_MAX_LAG_MS", {
+			min: 1,
+			default: 6e4
+		}))
+	}));
+	const relay = Provider(OutboxRelay)({
+		inject: {
+			store: OutboxStore,
+			publisher: OutboxPublisher,
+			observers: Observers,
+			config: OutboxConfig
+		},
+		acquire: ({ store, publisher, observers, config: bound }) => OkAsync(startRelay(store, publisher, observers, clock, bound)),
+		release: (running) => running.stop().get()
+	});
+	const healthCheck = Provider.member(HealthChecks)({
+		inject: {
+			store: OutboxStore,
+			config: OutboxConfig
+		},
+		sync: ({ store, config: { tenants, maxLagMs } }) => ({
+			name: "outbox",
+			check: () => store.oldestPending(tenants).flatMap((oldest) => {
+				const behind = oldest.map(({ tenantId, occurredAt }) => ({
+					tenantId,
+					lagMs: clock.now() - occurredAt.getTime()
+				})).filter(({ lagMs }) => lagMs > maxLagMs);
+				return behind.length === 0 ? OkAsync() : ErrAsync(new HealthCheckFailed({ reason: behind.map(({ tenantId, lagMs }) => `${tenantId} is ${String(lagMs)} ms behind`).join(", ") }));
+			})
+		})
+	});
+	return Module("Outbox")({
+		needs: [
+			Env,
+			OutboxStore,
+			OutboxPublisher
+		],
+		provides: [
+			config,
+			noObserverMember,
+			relay,
+			healthCheck
+		],
+		exports: [HealthChecks]
+	});
+};
+//#endregion
+export { OutboxPublisher, OutboxStore, memoryOutboxStore, outbox };

package/dist/outbox-Bn2wYUh6.d.cts

@@ -0,0 +1,86 @@
+import { AsyncResult } from "unthrown";
+//#region src/outbox.d.ts
+/**
+ * One committed fact awaiting broadcast: a row of the outbox table, as the
+ * relay reads it.
+ *
+ * The row IS the envelope. `tenantId` is whose fact it is, and the unit the
+ * relay claims by; `kind` is which sort of thing changed; `subjectId` is which
+ * one, and the key a reader compacts on; `payload` is the application's own
+ * encoding, handed to the publisher untouched — a `null` payload is the
+ * **tombstone**, the last word about a subject. `id` is the outbox sequence,
+ * and the order the relay publishes a tenant's facts in.
+ */
+type OutboxMessage = {
+  readonly id: number;
+  readonly tenantId: string;
+  readonly kind: string;
+  readonly subjectId: string;
+  readonly payload: string | null;
+  readonly occurredAt: Date;
+};
+/**
+ * What a store answers for the relay. Both operations promise `never`: a
+ * database that will not answer is a defect the relay observes and retries,
+ * not a domain outcome.
+ */
+type OutboxStoreService = {
+  /**
+   * A tenant's oldest unpublished messages, in outbox order, at most `limit`.
+   * A read and nothing more — it claims nothing, which is what lets the health
+   * check and a spec look without racing the relay.
+   */
+  readonly pending: (tenantId: string, limit: number) => AsyncResult<readonly OutboxMessage[], never>;
+  /**
+   * When each of `tenantIds`' oldest unpublished message was written, for the
+   * tenants that have one — in ONE round trip however many tenants are asked
+   * about, because the health check asks on every `/healthz`, and a query per
+   * tenant would queue the pool behind the probe meant to report it.
+   */
+  readonly oldestPending: (tenantIds: readonly string[]) => AsyncResult<readonly {
+    readonly tenantId: string;
+    readonly occurredAt: Date;
+  }[], never>;
+  /**
+   * Claims a tenant's oldest unpublished messages, hands them to `relay`, and
+   * marks published exactly the ids `relay` answers — all under one claim, so
+   * no other caller holding the same store is handed the same tenant until it
+   * is released.
+   *
+   * A tenant another caller has claimed is **skipped, not waited for**: the
+   * call answers `Ok` without running `relay`. A defect from `relay` releases
+   * the claim and marks nothing.
+   */
+  readonly claim: (tenantId: string, limit: number, relay: (batch: readonly OutboxMessage[]) => AsyncResult<readonly number[], never>) => AsyncResult<void, never>;
+};
+declare const OutboxStore_base: import("@btravstack/di").PortClass<"OutboxStore">;
+/**
+ * Where the relay reads from. An application provides it — from
+ * `@btravstack/outbox/prisma`'s `prismaOutboxStore`, `memoryOutboxStore`, or
+ * an adapter of its own — beside the transaction that writes the rows, which
+ * stays the application's.
+ */
+declare class OutboxStore extends OutboxStore_base<OutboxStoreService> {}
+/**
+ * Whatever tagged error the publisher models — a broker that refused, a
+ * message the contract rejects. The relay reports it and acts on none of it,
+ * so the type asks for a tag and nothing else.
+ */
+type PublishRefused = {
+  readonly _tag: string;
+};
+/**
+ * What "publish" means, which only the application knows: the transport, the
+ * contract and the decoding of `payload`.
+ *
+ * Any `Err` is a message left pending: the relay stops the tenant's batch
+ * there, so a later fact never overtakes it, and tries again after its
+ * back-off.
+ */
+type OutboxPublisherService = {
+  readonly publish: (message: OutboxMessage) => AsyncResult<void, PublishRefused>;
+};
+declare const OutboxPublisher_base: import("@btravstack/di").PortClass<"OutboxPublisher">;
+declare class OutboxPublisher extends OutboxPublisher_base<OutboxPublisherService> {}
+//#endregion
+export { OutboxStoreService as a, OutboxStore as i, OutboxPublisher as n, PublishRefused as o, OutboxPublisherService as r, OutboxMessage as t };

package/dist/outbox-Bn2wYUh6.d.mts

@@ -0,0 +1,86 @@
+import { AsyncResult } from "unthrown";
+//#region src/outbox.d.ts
+/**
+ * One committed fact awaiting broadcast: a row of the outbox table, as the
+ * relay reads it.
+ *
+ * The row IS the envelope. `tenantId` is whose fact it is, and the unit the
+ * relay claims by; `kind` is which sort of thing changed; `subjectId` is which
+ * one, and the key a reader compacts on; `payload` is the application's own
+ * encoding, handed to the publisher untouched — a `null` payload is the
+ * **tombstone**, the last word about a subject. `id` is the outbox sequence,
+ * and the order the relay publishes a tenant's facts in.
+ */
+type OutboxMessage = {
+  readonly id: number;
+  readonly tenantId: string;
+  readonly kind: string;
+  readonly subjectId: string;
+  readonly payload: string | null;
+  readonly occurredAt: Date;
+};
+/**
+ * What a store answers for the relay. Both operations promise `never`: a
+ * database that will not answer is a defect the relay observes and retries,
+ * not a domain outcome.
+ */
+type OutboxStoreService = {
+  /**
+   * A tenant's oldest unpublished messages, in outbox order, at most `limit`.
+   * A read and nothing more — it claims nothing, which is what lets the health
+   * check and a spec look without racing the relay.
+   */
+  readonly pending: (tenantId: string, limit: number) => AsyncResult<readonly OutboxMessage[], never>;
+  /**
+   * When each of `tenantIds`' oldest unpublished message was written, for the
+   * tenants that have one — in ONE round trip however many tenants are asked
+   * about, because the health check asks on every `/healthz`, and a query per
+   * tenant would queue the pool behind the probe meant to report it.
+   */
+  readonly oldestPending: (tenantIds: readonly string[]) => AsyncResult<readonly {
+    readonly tenantId: string;
+    readonly occurredAt: Date;
+  }[], never>;
+  /**
+   * Claims a tenant's oldest unpublished messages, hands them to `relay`, and
+   * marks published exactly the ids `relay` answers — all under one claim, so
+   * no other caller holding the same store is handed the same tenant until it
+   * is released.
+   *
+   * A tenant another caller has claimed is **skipped, not waited for**: the
+   * call answers `Ok` without running `relay`. A defect from `relay` releases
+   * the claim and marks nothing.
+   */
+  readonly claim: (tenantId: string, limit: number, relay: (batch: readonly OutboxMessage[]) => AsyncResult<readonly number[], never>) => AsyncResult<void, never>;
+};
+declare const OutboxStore_base: import("@btravstack/di").PortClass<"OutboxStore">;
+/**
+ * Where the relay reads from. An application provides it — from
+ * `@btravstack/outbox/prisma`'s `prismaOutboxStore`, `memoryOutboxStore`, or
+ * an adapter of its own — beside the transaction that writes the rows, which
+ * stays the application's.
+ */
+declare class OutboxStore extends OutboxStore_base<OutboxStoreService> {}
+/**
+ * Whatever tagged error the publisher models — a broker that refused, a
+ * message the contract rejects. The relay reports it and acts on none of it,
+ * so the type asks for a tag and nothing else.
+ */
+type PublishRefused = {
+  readonly _tag: string;
+};
+/**
+ * What "publish" means, which only the application knows: the transport, the
+ * contract and the decoding of `payload`.
+ *
+ * Any `Err` is a message left pending: the relay stops the tenant's batch
+ * there, so a later fact never overtakes it, and tries again after its
+ * back-off.
+ */
+type OutboxPublisherService = {
+  readonly publish: (message: OutboxMessage) => AsyncResult<void, PublishRefused>;
+};
+declare const OutboxPublisher_base: import("@btravstack/di").PortClass<"OutboxPublisher">;
+declare class OutboxPublisher extends OutboxPublisher_base<OutboxPublisherService> {}
+//#endregion
+export { OutboxStoreService as a, OutboxStore as i, OutboxPublisher as n, PublishRefused as o, OutboxPublisherService as r, OutboxMessage as t };

package/dist/prisma.cjs

@@ -0,0 +1,85 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let unthrown = require("unthrown");
+//#region src/prisma.ts
+/**
+* An `int8` id as the number the port speaks, refused rather than rounded past
+* 2^53 — a row whose id cannot be named exactly would be marked, and
+* deduplicated on, as some other row.
+*/
+const safe = (id) => {
+	const value = Number(id);
+	if (!Number.isSafeInteger(value)) throw new RangeError(`outbox id ${String(id)} exceeds 2^53`);
+	return value;
+};
+const identifier = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+/** A template whose text carries the table's identifier — the one part a parameter cannot be. */
+const statement = (...parts) => Object.assign([...parts], { raw: [...parts] });
+/**
+* The outbox store over a Prisma 8 client, in raw SQL against the documented
+* table — the model is the application's, declared in its own contract.
+*
+* **The claim is a transaction-scoped advisory lock per tenant**, taken with
+* `pg_try_advisory_xact_lock` before the batch is read: a relay that does not
+* get it skips the tenant, and the lock dies with the transaction, so a relay
+* that crashes mid-batch releases it with its connection. The batch is read,
+* published and marked inside that one transaction, so a mark that never
+* commits leaves its rows pending rather than lost. The cost is a pooled
+* connection held for the length of one batch's publishes.
+*
+* **One relay per tenant holds while its claiming session lives.** The claim
+* lifts `idle_in_transaction_session_timeout` for its own transaction, so a
+* configured timeout cannot end it mid-batch; a session the server ends any
+* other way (a terminated backend, a failover) frees the lock while the relay
+* is still publishing, and another relay may publish the same rows — which is
+* at-least-once delivery, deduplicated on the id.
+*
+* The table's `id` is a `BigInt` — an `Int` runs out at 2^31 — read through
+* `pg/int8@1` and refused, as a defect, past 2^53 rather than rounded.
+* `occurredAt` is read through `to_json`, which answers ISO 8601 whatever the
+* column's codec or the server's `DateStyle`, so the store needs no codec
+* beyond `pg/text@1` and `pg/int8@1` — both of which the table itself uses.
+*/
+const prismaOutboxStore = (db, options = {}) => {
+	const schema = options.schema ?? "public";
+	const table = options.table ?? "outboxMessage";
+	const qualified = `${identifier(schema)}.${identifier(table)}`;
+	const { sql } = db.raw;
+	const lock = (tenantId) => sql`SELECT set_config('idle_in_transaction_session_timeout', '0', true) AS lifted, pg_try_advisory_xact_lock(hashtext(${`${schema}.${table}`}), hashtext(${tenantId}))::text AS locked`.returnsRow({
+		lifted: "pg/text@1",
+		locked: "pg/text@1"
+	}).build();
+	const select = (tenantId, limit) => sql(statement(`SELECT "id", "tenantId", "kind", "subjectId", "payload", to_json("occurredAt") #>> '{}' AS "occurredAt" FROM ${qualified} WHERE "tenantId" = `, ` AND "publishedAt" IS NULL ORDER BY "id" LIMIT `, "::int"), tenantId, String(limit)).returnsRow({
+		id: "pg/int8@1",
+		tenantId: "pg/text@1",
+		kind: "pg/text@1",
+		subjectId: "pg/text@1",
+		payload: "pg/text@1",
+		occurredAt: "pg/text@1"
+	}).build();
+	const oldest = (tenantIds) => sql(statement(`SELECT "tenantId", to_json(min("occurredAt")) #>> '{}' AS "occurredAt" FROM ${qualified} WHERE "publishedAt" IS NULL AND "tenantId" IN (SELECT json_array_elements_text(`, `::json)) GROUP BY "tenantId"`), JSON.stringify(tenantIds)).returnsRow({
+		tenantId: "pg/text@1",
+		occurredAt: "pg/text@1"
+	}).build();
+	const mark = (ids) => sql(statement(`UPDATE ${qualified} SET "publishedAt" = now() WHERE "id" = ANY(string_to_array(`, ", ',')::bigint[])"), ids.join(",")).affectedCount().build();
+	const read = async (tx, tenantId, limit) => (await tx.query(select(tenantId, limit))).map((row) => ({
+		...row,
+		id: safe(row.id),
+		occurredAt: new Date(row.occurredAt)
+	}));
+	const transaction = (work) => (0, unthrown.fromSafePromise)(Promise.resolve().then(() => db.transaction((tx) => work(tx))));
+	return {
+		pending: (tenantId, limit) => transaction((tx) => read(tx, tenantId, limit)),
+		oldestPending: (tenantIds) => transaction(async (tx) => (await tx.query(oldest(tenantIds))).map(({ tenantId, occurredAt }) => ({
+			tenantId,
+			occurredAt: new Date(occurredAt)
+		}))),
+		claim: (tenantId, limit, relay) => transaction(async (tx) => {
+			const [held] = await tx.query(lock(tenantId));
+			if (held?.locked !== "true") return;
+			const published = await relay(await read(tx, tenantId, limit)).get();
+			if (published.length > 0) await tx.query(mark(published));
+		})
+	};
+};
+//#endregion
+exports.prismaOutboxStore = prismaOutboxStore;

package/dist/prisma.d.cts

@@ -0,0 +1,52 @@
+import { a as OutboxStoreService } from "./outbox-Bn2wYUh6.cjs";
+//#region src/prisma.d.ts
+/**
+ * The little of a Prisma 8 client this store needs: the raw lane to build its
+ * statements with, and `transaction` to run them in.
+ */
+export type OutboxDatabase<Tx> = {
+  /**
+   * Required to EXIST and not described further, for `@btravstack/prisma`'s
+   * reason: the real tag takes the contract's own interpolation and row-spec
+   * types, narrower than anything a package that cannot see a contract could
+   * name, and a parameter is contravariant.
+   */
+  readonly raw: {
+    readonly sql: unknown;
+  };
+  readonly transaction: <R>(fn: (tx: Tx) => PromiseLike<R>) => Promise<R>;
+};
+/** Where the table lives. */
+export type PrismaOutboxStoreOptions = {
+  /** The namespace the model is declared in (default `public`). */
+  readonly schema?: string;
+  /** The table Prisma maps the model to (default `outboxMessage`, the table of a model named `OutboxMessage`). */
+  readonly table?: string;
+};
+/**
+ * The outbox store over a Prisma 8 client, in raw SQL against the documented
+ * table — the model is the application's, declared in its own contract.
+ *
+ * **The claim is a transaction-scoped advisory lock per tenant**, taken with
+ * `pg_try_advisory_xact_lock` before the batch is read: a relay that does not
+ * get it skips the tenant, and the lock dies with the transaction, so a relay
+ * that crashes mid-batch releases it with its connection. The batch is read,
+ * published and marked inside that one transaction, so a mark that never
+ * commits leaves its rows pending rather than lost. The cost is a pooled
+ * connection held for the length of one batch's publishes.
+ *
+ * **One relay per tenant holds while its claiming session lives.** The claim
+ * lifts `idle_in_transaction_session_timeout` for its own transaction, so a
+ * configured timeout cannot end it mid-batch; a session the server ends any
+ * other way (a terminated backend, a failover) frees the lock while the relay
+ * is still publishing, and another relay may publish the same rows — which is
+ * at-least-once delivery, deduplicated on the id.
+ *
+ * The table's `id` is a `BigInt` — an `Int` runs out at 2^31 — read through
+ * `pg/int8@1` and refused, as a defect, past 2^53 rather than rounded.
+ * `occurredAt` is read through `to_json`, which answers ISO 8601 whatever the
+ * column's codec or the server's `DateStyle`, so the store needs no codec
+ * beyond `pg/text@1` and `pg/int8@1` — both of which the table itself uses.
+ */
+export declare const prismaOutboxStore: <Tx>(db: OutboxDatabase<Tx>, options?: PrismaOutboxStoreOptions) => OutboxStoreService;
+//#endregion

package/dist/prisma.d.mts

@@ -0,0 +1,52 @@
+import { a as OutboxStoreService } from "./outbox-Bn2wYUh6.mjs";
+//#region src/prisma.d.ts
+/**
+ * The little of a Prisma 8 client this store needs: the raw lane to build its
+ * statements with, and `transaction` to run them in.
+ */
+export type OutboxDatabase<Tx> = {
+  /**
+   * Required to EXIST and not described further, for `@btravstack/prisma`'s
+   * reason: the real tag takes the contract's own interpolation and row-spec
+   * types, narrower than anything a package that cannot see a contract could
+   * name, and a parameter is contravariant.
+   */
+  readonly raw: {
+    readonly sql: unknown;
+  };
+  readonly transaction: <R>(fn: (tx: Tx) => PromiseLike<R>) => Promise<R>;
+};
+/** Where the table lives. */
+export type PrismaOutboxStoreOptions = {
+  /** The namespace the model is declared in (default `public`). */
+  readonly schema?: string;
+  /** The table Prisma maps the model to (default `outboxMessage`, the table of a model named `OutboxMessage`). */
+  readonly table?: string;
+};
+/**
+ * The outbox store over a Prisma 8 client, in raw SQL against the documented
+ * table — the model is the application's, declared in its own contract.
+ *
+ * **The claim is a transaction-scoped advisory lock per tenant**, taken with
+ * `pg_try_advisory_xact_lock` before the batch is read: a relay that does not
+ * get it skips the tenant, and the lock dies with the transaction, so a relay
+ * that crashes mid-batch releases it with its connection. The batch is read,
+ * published and marked inside that one transaction, so a mark that never
+ * commits leaves its rows pending rather than lost. The cost is a pooled
+ * connection held for the length of one batch's publishes.
+ *
+ * **One relay per tenant holds while its claiming session lives.** The claim
+ * lifts `idle_in_transaction_session_timeout` for its own transaction, so a
+ * configured timeout cannot end it mid-batch; a session the server ends any
+ * other way (a terminated backend, a failover) frees the lock while the relay
+ * is still publishing, and another relay may publish the same rows — which is
+ * at-least-once delivery, deduplicated on the id.
+ *
+ * The table's `id` is a `BigInt` — an `Int` runs out at 2^31 — read through
+ * `pg/int8@1` and refused, as a defect, past 2^53 rather than rounded.
+ * `occurredAt` is read through `to_json`, which answers ISO 8601 whatever the
+ * column's codec or the server's `DateStyle`, so the store needs no codec
+ * beyond `pg/text@1` and `pg/int8@1` — both of which the table itself uses.
+ */
+export declare const prismaOutboxStore: <Tx>(db: OutboxDatabase<Tx>, options?: PrismaOutboxStoreOptions) => OutboxStoreService;
+//#endregion

package/dist/prisma.mjs

@@ -0,0 +1,84 @@
+import { fromSafePromise } from "unthrown";
+//#region src/prisma.ts
+/**
+* An `int8` id as the number the port speaks, refused rather than rounded past
+* 2^53 — a row whose id cannot be named exactly would be marked, and
+* deduplicated on, as some other row.
+*/
+const safe = (id) => {
+	const value = Number(id);
+	if (!Number.isSafeInteger(value)) throw new RangeError(`outbox id ${String(id)} exceeds 2^53`);
+	return value;
+};
+const identifier = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+/** A template whose text carries the table's identifier — the one part a parameter cannot be. */
+const statement = (...parts) => Object.assign([...parts], { raw: [...parts] });
+/**
+* The outbox store over a Prisma 8 client, in raw SQL against the documented
+* table — the model is the application's, declared in its own contract.
+*
+* **The claim is a transaction-scoped advisory lock per tenant**, taken with
+* `pg_try_advisory_xact_lock` before the batch is read: a relay that does not
+* get it skips the tenant, and the lock dies with the transaction, so a relay
+* that crashes mid-batch releases it with its connection. The batch is read,
+* published and marked inside that one transaction, so a mark that never
+* commits leaves its rows pending rather than lost. The cost is a pooled
+* connection held for the length of one batch's publishes.
+*
+* **One relay per tenant holds while its claiming session lives.** The claim
+* lifts `idle_in_transaction_session_timeout` for its own transaction, so a
+* configured timeout cannot end it mid-batch; a session the server ends any
+* other way (a terminated backend, a failover) frees the lock while the relay
+* is still publishing, and another relay may publish the same rows — which is
+* at-least-once delivery, deduplicated on the id.
+*
+* The table's `id` is a `BigInt` — an `Int` runs out at 2^31 — read through
+* `pg/int8@1` and refused, as a defect, past 2^53 rather than rounded.
+* `occurredAt` is read through `to_json`, which answers ISO 8601 whatever the
+* column's codec or the server's `DateStyle`, so the store needs no codec
+* beyond `pg/text@1` and `pg/int8@1` — both of which the table itself uses.
+*/
+const prismaOutboxStore = (db, options = {}) => {
+	const schema = options.schema ?? "public";
+	const table = options.table ?? "outboxMessage";
+	const qualified = `${identifier(schema)}.${identifier(table)}`;
+	const { sql } = db.raw;
+	const lock = (tenantId) => sql`SELECT set_config('idle_in_transaction_session_timeout', '0', true) AS lifted, pg_try_advisory_xact_lock(hashtext(${`${schema}.${table}`}), hashtext(${tenantId}))::text AS locked`.returnsRow({
+		lifted: "pg/text@1",
+		locked: "pg/text@1"
+	}).build();
+	const select = (tenantId, limit) => sql(statement(`SELECT "id", "tenantId", "kind", "subjectId", "payload", to_json("occurredAt") #>> '{}' AS "occurredAt" FROM ${qualified} WHERE "tenantId" = `, ` AND "publishedAt" IS NULL ORDER BY "id" LIMIT `, "::int"), tenantId, String(limit)).returnsRow({
+		id: "pg/int8@1",
+		tenantId: "pg/text@1",
+		kind: "pg/text@1",
+		subjectId: "pg/text@1",
+		payload: "pg/text@1",
+		occurredAt: "pg/text@1"
+	}).build();
+	const oldest = (tenantIds) => sql(statement(`SELECT "tenantId", to_json(min("occurredAt")) #>> '{}' AS "occurredAt" FROM ${qualified} WHERE "publishedAt" IS NULL AND "tenantId" IN (SELECT json_array_elements_text(`, `::json)) GROUP BY "tenantId"`), JSON.stringify(tenantIds)).returnsRow({
+		tenantId: "pg/text@1",
+		occurredAt: "pg/text@1"
+	}).build();
+	const mark = (ids) => sql(statement(`UPDATE ${qualified} SET "publishedAt" = now() WHERE "id" = ANY(string_to_array(`, ", ',')::bigint[])"), ids.join(",")).affectedCount().build();
+	const read = async (tx, tenantId, limit) => (await tx.query(select(tenantId, limit))).map((row) => ({
+		...row,
+		id: safe(row.id),
+		occurredAt: new Date(row.occurredAt)
+	}));
+	const transaction = (work) => fromSafePromise(Promise.resolve().then(() => db.transaction((tx) => work(tx))));
+	return {
+		pending: (tenantId, limit) => transaction((tx) => read(tx, tenantId, limit)),
+		oldestPending: (tenantIds) => transaction(async (tx) => (await tx.query(oldest(tenantIds))).map(({ tenantId, occurredAt }) => ({
+			tenantId,
+			occurredAt: new Date(occurredAt)
+		}))),
+		claim: (tenantId, limit, relay) => transaction(async (tx) => {
+			const [held] = await tx.query(lock(tenantId));
+			if (held?.locked !== "true") return;
+			const published = await relay(await read(tx, tenantId, limit)).get();
+			if (published.length > 0) await tx.query(mark(published));
+		})
+	};
+};
+//#endregion
+export { prismaOutboxStore };

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@btravstack/outbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.19.0",
+  "description": "The transactional outbox relay for @btravstack/core: a poll loop that publishes committed facts in outbox order, a per-tenant claim so replicas take turns rather than race for the same rows, and a Prisma 8 store",
+  "keywords": [
+    "dependency-injection",
+    "outbox",
+    "postgres",
+    "prisma",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/outbox"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./prisma": {
+      "import": {
+        "types": "./dist/prisma.d.mts",
+        "default": "./dist/prisma.mjs"
+      },
+      "require": {
+        "types": "./dist/prisma.d.cts",
+        "default": "./dist/prisma.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/config": "0.19.0",
+    "@btravstack/core": "0.19.0",
+    "@btravstack/di": "0.19.0",
+    "@btravstack/testing": "0.19.0",
+    "@btravstack/tsconfig": "0.4.0",
+    "@types/node": "26.6.4",
+    "@unthrown/vitest": "5.12.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "unthrown": "5.12.0",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@btravstack/config": "^0.19.0",
+    "@btravstack/core": "^0.19.0",
+    "@btravstack/di": "^0.19.0",
+    "@prisma/orm-postgres": "^8.0.0-rc.11",
+    "unthrown": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@prisma/orm-postgres": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/prisma.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/prisma.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+  }
 }