@rebasepro/server-postgres 0.10.1-canary.a54c057 → 0.10.1-canary.b1e3dbf

package/dist/index.es.js

@@ -5,7 +5,7 @@ import { Client, Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { ApiError, createEmailService, extractUserFromToken, loadCollectionsFromDirectory, logger, safeCompare } from "@rebasepro/server";
 import { and, asc, count, desc, eq, getTableColumns, getTableName, gt, ilike, inArray, isTable, lt, or, relations, sql } from "drizzle-orm";
-import { PgArray, PgChar, PgTable, PgText, PgVarchar, bigint, boolean, char, cidr, customType, date, doublePrecision, geometry, getTableConfig, inet, integer, interval, json, jsonb, line, macaddr, macaddr8, numeric, pgSchema, pgTable, point, primaryKey, real, smallint, text, time, timestamp, unique, uuid, varchar, vector } from "drizzle-orm/pg-core";
+import { PgArray, PgChar, PgTable, PgText, PgVarchar, bigint, boolean, char, cidr, customType, date, doublePrecision, geometry, getTableConfig, index, inet, integer, interval, json, jsonb, line, macaddr, macaddr8, numeric, pgSchema, pgTable, point, primaryKey, real, smallint, text, time, timestamp, unique, uuid, varchar, vector } from "drizzle-orm/pg-core";
 import fs, { promises } from "fs";
 import path from "path";
 import chokidar from "chokidar";
@@ -439,6 +439,19 @@ function isSQLAdmin(admin) {
 function isSchemaAdmin(admin) {
 	return !!admin && (typeof admin.fetchUnmappedTables === "function" || typeof admin.fetchTableMetadata === "function");
 }
+//#endregion
+//#region ../types/src/types/channel_bus.ts
+/**
+* Whether `setting` is an already-constructed transport rather than a request
+* for a built-in one.
+*
+* Structural rather than nominal so that an instance from a *different copy* of
+* `@rebasepro/types` — an entirely normal outcome of a separately versioned
+* transport package — is still recognised.
+*/
+function isChannelBusInstance(setting) {
+	return typeof setting?.publish === "function";
+}
 /** @group Models */
 var POSTGRES_CAPABILITIES = {
 	key: "postgres",
@@ -518,6 +531,25 @@ function getDataSourceCapabilities(engine) {
 	if (!engine) return POSTGRES_CAPABILITIES;
 	return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;
 }
+/**
+* Resolve a client-supplied list `limit` into a safe, always-defined value.
+*
+* - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
+*   so `0`, negatives, and absurd values can never bypass the cap.
+* - An absent / blank / non-numeric limit falls back to the mode default:
+*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+*
+* The return is never `undefined` — no ingress that routes its client limit
+* through this can produce an unbounded read.
+*/
+function resolveClientListLimit(rawLimit, opts = {}) {
+	const maxLimit = opts.maxLimit ?? 1e3;
+	if (rawLimit != null && String(rawLimit).trim() !== "") {
+		const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
+		if (Number.isFinite(parsed)) return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+	}
+	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
+}
 var snakeCaseRegex = /[A-Z]{2,}(?=[A-Z][a-z]|\b)|[A-Z]?[a-z]+|[0-9]+(?:[a-z](?![a-z]))?|[A-Z]/g;
 var toSnakeCase = (str) => {
 	if (!str || typeof str !== "string") return "";
@@ -9349,21 +9381,59 @@ function createAuthSchema(usersSchemaName = "rebase") {
 		isAnonymous: boolean("is_anonymous").default(false).notNull(),
 		roles: text("roles").array().default([]).notNull(),
 		metadata: jsonb("metadata").$type().default({}).notNull(),
+		/**
+		* Sessions that began before this instant are dead, whatever tokens
+		* they still hold. Password resets and admin revocations stamp it.
+		*
+		* Deleting the user's refresh-token rows (which we also do) is not
+		* sufficient on its own: a request already in flight can insert a
+		* freshly rotated row microseconds after the delete and survive it.
+		* This timestamp cannot be outrun that way — it is checked against
+		* `refresh_tokens.session_started_at`, which rotation carries forward.
+		*/
+		tokensValidAfter: timestamp("tokens_valid_after"),
 		createdAt: timestamp("created_at").defaultNow().notNull(),
 		updatedAt: timestamp("updated_at").defaultNow().notNull()
 	});
 	/**
-	* Refresh tokens for long-lived sessions
+	* Refresh tokens for long-lived sessions.
+	*
+	* A row is one token, not one device. Every token minted from the same
+	* sign-in shares a `sessionId`, and rotation ADDS a row rather than
+	* replacing one: the superseded token stays on file, flagged `revoked`
+	* with a `rotatedAt` stamp. That record is what lets the refresh endpoint
+	* tell a client replaying a token it never got an answer for (a response
+	* lost to a redeploy, a second tab racing on boot) apart from a stranger
+	* presenting a token that was never issued. Deleting the old row on sight
+	* — the previous behaviour — made those two cases indistinguishable, and
+	* the legitimate one is overwhelmingly the common one.
+	*
+	* There is deliberately NO unique constraint on (uid, user_agent,
+	* ip_address). Keying a session on the IP meant one row per "device",
+	* so a second browser profile behind the same NAT silently evicted the
+	* first, and a phone changing networks orphaned a row on every hop.
+	* User agent and IP are descriptive metadata for the sessions list;
+	* `sessionId` is the identity.
 	*/
 	const refreshTokens = tableCreator("refresh_tokens", {
 		id: uuid("id").defaultRandom().primaryKey(),
 		uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
+		sessionId: uuid("session_id").defaultRandom().notNull(),
 		tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
 		expiresAt: timestamp("expires_at").notNull(),
+		revoked: boolean("revoked").default(false).notNull(),
+		rotatedAt: timestamp("rotated_at"),
+		/**
+		* When the sign-in this token descends from happened — carried across
+		* every rotation, unlike `createdAt`. `users.tokensValidAfter` is
+		* compared against this, so a revocation cannot be outrun by a token
+		* that rotates immediately after it.
+		*/
+		sessionStartedAt: timestamp("session_started_at").defaultNow().notNull(),
 		userAgent: varchar("user_agent", { length: 500 }),
 		ipAddress: varchar("ip_address", { length: 45 }),
 		createdAt: timestamp("created_at").defaultNow().notNull()
-	}, (table) => ({ uniqueDeviceSession: unique("unique_device_session").on(table.uid, table.userAgent, table.ipAddress) }));
+	}, (table) => ({ sessionIdx: index("idx_refresh_tokens_session").on(table.sessionId) }));
 	/**
 	* Password reset tokens for forgot password flow
 	*/
@@ -10190,67 +10260,46 @@ async function provisionTriggerCdc(run, tables) {
 	};
 }
 //#endregion
-//#region src/services/cdc/CdcListener.ts
-/**
-* Parse a `rebase_cdc` NOTIFY payload. Returns `null` for anything malformed so
-* a single bad message can never crash the listener.
-*/
-function parseCdcPayload(payload) {
-	let parsed;
-	try {
-		parsed = JSON.parse(payload);
-	} catch {
-		return null;
-	}
-	if (!parsed || typeof parsed !== "object") return null;
-	const obj = parsed;
-	const schema = typeof obj.schema === "string" ? obj.schema : void 0;
-	const table = typeof obj.table === "string" ? obj.table : void 0;
-	const op = obj.op;
-	if (!schema || !table) return null;
-	if (op !== "INSERT" && op !== "UPDATE" && op !== "DELETE") return null;
-	return {
-		schema,
-		table,
-		op,
-		row: obj.row && typeof obj.row === "object" ? obj.row : {},
-		truncated: obj.truncated === true
-	};
-}
+//#region src/services/pg-notify-listener.ts
 /**
-* Dedicated Postgres LISTEN client for database-level CDC.
+* A dedicated, self-healing Postgres `LISTEN` connection.
+*
+* Every cross-instance feature in the backend needs the same thing: one
+* connection *outside* the Drizzle pool that stays open, holds a `LISTEN`, and
+* comes back on its own after the database or the network drops it. CDC needed
+* it first; the channel bus needs it too. This is that connection, with the one
+* behaviour that matters to callers preserved: the **first** connect is
+* validated and rethrown, so a caller can fall back to a different strategy,
+* while every later drop is repaired quietly in the background.
 *
-* Mirrors the resilience of the RealtimeService cross-instance LISTEN client: a
-* standalone `pg.Client` (outside the Drizzle pool) that stays connected, and
-* transparently reconnects on error/disconnect. Each backend instance runs one,
-* so every instance observes every committed change regardless of which
-* instance (or external process) made the write.
+* `LISTEN` is session state, so this connection must not go through a
+* transaction-mode pooler (PgBouncer): give it the direct database URL.
 */
-var CdcListener = class CdcListener {
-	connectionString;
-	onEvent;
+var DEFAULT_RECONNECT_DELAY_MS = 3e3;
+/** Guards the identifier interpolated into `LISTEN`. */
+var SAFE_CHANNEL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PgNotifyListener = class {
+	options;
 	client;
 	running = false;
 	reconnectTimer;
-	static RECONNECT_DELAY_MS = 3e3;
-	constructor(connectionString, onEvent) {
-		this.connectionString = connectionString;
-		this.onEvent = onEvent;
+	constructor(options) {
+		this.options = options;
+		if (!SAFE_CHANNEL.test(options.channel)) throw new Error(`Unsafe NOTIFY channel name "${options.channel}" — expected a plain SQL identifier.`);
+	}
+	/** Whether the listener is meant to be connected right now. */
+	get active() {
+		return this.running;
 	}
 	/**
 	* Connect and begin listening. Idempotent.
 	*
-	* The **initial** connection is validated synchronously: if it cannot be
-	* established (or `LISTEN` is refused), this rejects so callers — notably
-	* `REALTIME_CDC=auto` — can detect an unusable connection and fall back to
-	* app-level realtime. Once the initial connection succeeds, later drops
-	* self-heal via {@link scheduleReconnect}.
+	* Rejects if the *initial* connection or `LISTEN` fails, leaving the
+	* listener stopped — callers use that to degrade deliberately instead of
+	* running blind against a channel nothing is delivering.
 	*/
 	async start() {
-		if (this.running) {
-			logger.warn("⚠️ [CDC] CdcListener.start() called but already running. Ignoring.");
-			return;
-		}
+		if (this.running) return;
 		this.running = true;
 		try {
 			await this.connect({ initial: true });
@@ -10259,7 +10308,7 @@ var CdcListener = class CdcListener {
 			throw err;
 		}
 	}
-	/** Stop listening and release the connection. */
+	/** Stop listening and release the connection. Idempotent. */
 	async stop() {
 		this.running = false;
 		if (this.reconnectTimer) {
@@ -10274,34 +10323,30 @@ var CdcListener = class CdcListener {
 		}
 	}
 	async connect({ initial = false } = {}) {
+		const { connectionString, channel, onPayload, logLabel } = this.options;
 		try {
-			const client = new Client({ connectionString: this.connectionString });
+			const client = new Client({ connectionString });
 			client.on("error", (err) => {
-				logger.error("❌ [CDC] LISTEN client error", { detail: err.message });
+				logger.error(`❌ ${logLabel} LISTEN client error`, { detail: err.message });
 				this.scheduleReconnect();
 			});
 			client.on("end", () => {
 				if (this.running) {
-					logger.warn("⚠️ [CDC] LISTEN client disconnected unexpectedly.");
+					logger.warn(`⚠️ ${logLabel} LISTEN client disconnected unexpectedly.`);
 					this.scheduleReconnect();
 				}
 			});
 			client.on("notification", (msg) => {
 				if (!msg.payload) return;
-				const event = parseCdcPayload(msg.payload);
-				if (!event) {
-					logger.warn("⚠️ [CDC] Dropping unparseable change notification.");
-					return;
-				}
-				Promise.resolve(this.onEvent(event)).catch((err) => logger.error("❌ [CDC] Error handling change event", { error: err }));
+				Promise.resolve(onPayload(msg.payload)).catch((err) => logger.error(`❌ ${logLabel} Error handling notification`, { error: err }));
 			});
 			await client.connect();
-			await client.query(`LISTEN ${CDC_CHANNEL}`);
+			await client.query(`LISTEN ${channel}`);
 			this.client = client;
-			logger.info(`📡 [CDC] Listening for database changes on channel "${CDC_CHANNEL}".`);
+			logger.info(`📡 ${logLabel} Listening on channel "${channel}".`);
 		} catch (err) {
 			if (initial) throw err;
-			logger.error("❌ [CDC] Failed to connect LISTEN client", { error: err });
+			logger.error(`❌ ${logLabel} Failed to connect LISTEN client`, { error: err });
 			this.scheduleReconnect();
 		}
 	}
@@ -10317,7 +10362,82 @@ var CdcListener = class CdcListener {
 				this.client = void 0;
 			}
 			await this.connect();
-		}, CdcListener.RECONNECT_DELAY_MS);
+		}, this.options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS);
+	}
+};
+//#endregion
+//#region src/services/cdc/CdcListener.ts
+/**
+* Parse a `rebase_cdc` NOTIFY payload. Returns `null` for anything malformed so
+* a single bad message can never crash the listener.
+*/
+function parseCdcPayload(payload) {
+	let parsed;
+	try {
+		parsed = JSON.parse(payload);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object") return null;
+	const obj = parsed;
+	const schema = typeof obj.schema === "string" ? obj.schema : void 0;
+	const table = typeof obj.table === "string" ? obj.table : void 0;
+	const op = obj.op;
+	if (!schema || !table) return null;
+	if (op !== "INSERT" && op !== "UPDATE" && op !== "DELETE") return null;
+	return {
+		schema,
+		table,
+		op,
+		row: obj.row && typeof obj.row === "object" ? obj.row : {},
+		truncated: obj.truncated === true
+	};
+}
+/**
+* Dedicated Postgres LISTEN client for database-level CDC.
+*
+* A {@link PgNotifyListener} — a connection outside the Drizzle pool that stays
+* open and repairs itself — plus the parsing that turns a `rebase_cdc` payload
+* into a change event. Each backend instance runs one, so every instance
+* observes every committed change regardless of which instance (or external
+* process) made the write.
+*/
+var CdcListener = class {
+	listener;
+	constructor(connectionString, onEvent) {
+		this.listener = new PgNotifyListener({
+			connectionString,
+			channel: CDC_CHANNEL,
+			logLabel: "[CDC]",
+			onPayload: (payload) => {
+				const event = parseCdcPayload(payload);
+				if (!event) {
+					logger.warn("⚠️ [CDC] Dropping unparseable change notification.");
+					return;
+				}
+				return onEvent(event);
+			}
+		});
+	}
+	/**
+	* Connect and begin listening. Idempotent.
+	*
+	* The **initial** connection is validated synchronously: if it cannot be
+	* established (or `LISTEN` is refused), this rejects so callers — notably
+	* `REALTIME_CDC=auto` — can detect an unusable connection and fall back to
+	* app-level realtime. Once the initial connection succeeds, later drops
+	* self-heal in the background.
+	*/
+	async start() {
+		if (this.listener.active) {
+			logger.warn("⚠️ [CDC] CdcListener.start() called but already running. Ignoring.");
+			return;
+		}
+		await this.listener.start();
+	}
+	/** Stop listening and release the connection. */
+	async stop() {
+		await this.listener.stop();
 	}
 };
 //#endregion
@@ -10541,6 +10661,31 @@ var ChannelHistoryStore = class {
 		};
 	}
 	/**
+	* One retained message by its address.
+	*
+	* This is what makes the cross-instance pointer path work: a broadcast too
+	* large to travel inside a `pg_notify` payload is already stored here, so
+	* the notification carries `(channel, seq)` and each receiving instance
+	* reads the body back. Returns null when the message has since been pruned
+	* — a receiver that is that far behind has nothing useful to deliver, and
+	* the client's own `channel_history` replay is the repair path.
+	*/
+	async getBySeq(channel, seq) {
+		const row = (await this.db.execute(sql`
+            SELECT seq, event, payload, sender_id, created_at
+            FROM rebase.channel_messages
+            WHERE channel = ${channel} AND seq = ${seq}
+        `)).rows[0];
+		if (!row) return null;
+		return {
+			seq: Number(row.seq),
+			event: row.event,
+			payload: row.payload,
+			senderId: row.sender_id ?? void 0,
+			at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+		};
+	}
+	/**
 	* Enforce a channel's retention bounds.
 	*
 	* Throttled per channel, so a burst of operations prunes once rather than
@@ -10582,6 +10727,447 @@ var ChannelHistoryStore = class {
 	}
 };
 //#endregion
+//#region src/services/channel-presence.ts
+/**
+* The shared presence roster.
+*
+* Broadcast only ever needed *fan-out* to work across instances — a frame goes
+* out, whoever is connected receives it. Presence needs more than that, because
+* `presence_state` is a question ("who is in this document?") and a per-process
+* `Map` can only answer for the clients that happen to share a replica with the
+* asker. Two people editing the same scene through different pods would each
+* see an empty room while broadcasting cursors at each other perfectly.
+*
+* So presence gets one row per tracked client, in Postgres, readable by every
+* instance. Three consequences worth stating:
+*
+*  - **The table is the roster; the in-process map is a cache of our own
+*    clients.** Reads answer from the table when this store is active, so the
+*    answer is the same whichever instance is asked.
+*
+*  - **`last_seen` is the liveness signal, and it is already there.** The client
+*    heartbeats presence every ~20 s against a 30 s window; the sweep that has
+*    always reaped local stale entries now also reaps rows belonging to
+*    instances that stopped writing — which is exactly what a crashed pod looks
+*    like. Crash recovery is a property of the TTL, not a separate mechanism.
+*
+*  - **The sweep deletes with `RETURNING`.** Whichever instance wins the delete
+*    is the one that announces the departures, so a stale client produces one
+*    `presence_diff` for the cluster rather than one per replica.
+*/
+var ChannelPresenceStore = class {
+	db;
+	instanceId;
+	tablesReady = false;
+	constructor(db, instanceId) {
+		this.db = db;
+		this.instanceId = instanceId;
+	}
+	/** Create the roster table. Idempotent. */
+	async ensureTables() {
+		if (this.tablesReady) return;
+		await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+		await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_presence (
+                channel TEXT NOT NULL,
+                client_id TEXT NOT NULL,
+                instance_id TEXT NOT NULL,
+                state JSONB NOT NULL DEFAULT '{}'::jsonb,
+                last_seen TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                PRIMARY KEY (channel, client_id)
+            )
+        `);
+		await this.db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_channel_presence_last_seen
+            ON rebase.channel_presence (last_seen)
+        `);
+		this.tablesReady = true;
+	}
+	/** Record (or refresh) a client's presence. */
+	async track(channel, clientId, state) {
+		await this.db.execute(sql`
+            INSERT INTO rebase.channel_presence (channel, client_id, instance_id, state, last_seen)
+            VALUES (${channel}, ${clientId}, ${this.instanceId}, ${JSON.stringify(state ?? {})}::jsonb, NOW())
+            ON CONFLICT (channel, client_id) DO UPDATE
+            SET state = EXCLUDED.state,
+                instance_id = EXCLUDED.instance_id,
+                last_seen = NOW()
+        `);
+	}
+	/** Drop one client's presence in one channel. */
+	async remove(channel, clientId) {
+		await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence
+            WHERE channel = ${channel} AND client_id = ${clientId}
+        `);
+	}
+	/** Drop a client from every channel — used when its socket closes. */
+	async removeClient(clientId) {
+		await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence WHERE client_id = ${clientId}
+        `);
+	}
+	/** The global roster for a channel. */
+	async roster(channel) {
+		const result = await this.db.execute(sql`
+            SELECT client_id, state FROM rebase.channel_presence WHERE channel = ${channel}
+        `);
+		const presences = {};
+		for (const row of result.rows) presences[row.client_id] = row.state ?? {};
+		return presences;
+	}
+	/**
+	* Reap rows this instance is not responsible for and that have gone quiet.
+	*
+	* Own rows are excluded because the in-process sweep already handles them —
+	* and handles them better, since it can tell "the socket is gone" from "the
+	* heartbeat is late". What is left is precisely the interesting case: rows
+	* written by an instance that is no longer writing.
+	*
+	* Returns what was removed, so the caller can announce it.
+	*/
+	async sweepStale(ttlMs) {
+		return (await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence
+            WHERE instance_id <> ${this.instanceId}
+              AND last_seen < NOW() - MAKE_INTERVAL(secs => ${ttlMs / 1e3})
+            RETURNING channel, client_id, state
+        `)).rows.map((row) => ({
+			channel: row.channel,
+			clientId: row.client_id,
+			state: row.state ?? {}
+		}));
+	}
+	/**
+	* Remove every row this instance owns. Called on graceful shutdown so a
+	* rolling deploy does not leave a TTL window of ghosts in every roster.
+	*/
+	async removeInstance() {
+		await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence WHERE instance_id = ${this.instanceId}
+        `);
+	}
+};
+//#endregion
+//#region src/services/channel-bus/ChannelBus.ts
+/**
+* The default: no cross-instance delivery at all.
+*
+* This is what every deployment ran before the bus existed, and what a
+* single-instance deployment should keep running — `publish` resolves without
+* touching the network, so the broadcast path is the same handful of `ws.send`
+* calls it always was.
+*/
+var MemoryChannelBus = class {
+	kind = "memory";
+	maxFrameBytes = Infinity;
+	async start() {}
+	async publish() {}
+	async stop() {}
+};
+/** Encoded size of a frame, for a transport's size check. */
+function frameByteLength(frame) {
+	return Buffer.byteLength(JSON.stringify(frame), "utf8");
+}
+//#endregion
+//#region src/services/channel-bus/PostgresChannelBus.ts
+/**
+* Channel bus over Postgres LISTEN/NOTIFY.
+*
+* Chosen because it needs nothing that a Rebase deployment does not already
+* have — the same database, the same direct URL the CDC listener uses. Three
+* properties of `NOTIFY` shape everything below:
+*
+*  - **8000 bytes per payload.** Presence and cursors fit with room to spare; a
+*    scene snapshot does not. Rather than truncate or drop, an oversized frame
+*    on a *retained* channel is published as a pointer — the body is already in
+*    `rebase.channel_messages` with a sequence number, so the receiver reads it
+*    back. That is the same trick the entity path uses (notify an address,
+*    refetch the row), applied to a different table. On an ephemeral channel
+*    there is nothing to point at, so the publish is refused loudly instead of
+*    reaching some instances and not others.
+*
+*  - **A notify is a query on the primary database.** Not a slow one, but it
+*    competes with the application's real queries, and that — not throughput —
+*    is what actually limits this transport. Measured, it carried ~10k
+*    cross-instance messages/second and stayed flat out to eight instances; what
+*    it should not do is spend 10k queries/second of the database's budget on
+*    cursor movement. Hence the batching below.
+*
+*  - **Delivery is best-effort.** Retained channels repair themselves through
+*    the client's history replay, so a lost frame costs a live update rather
+*    than correctness. That is what makes coalescing safe.
+*/
+/** NOTIFY channel carrying channel-bus frames. */
+var CHANNEL_BUS_NOTIFY_CHANNEL = "rebase_channel_bus";
+/**
+* Postgres refuses a NOTIFY payload of 8000 bytes or more. The margin below it
+* is for nothing in particular — it is there so that a payload which passes this
+* check cannot fail at the server for being a few bytes over.
+*/
+var PG_NOTIFY_MAX_PAYLOAD_BYTES = 7500;
+/**
+* How long a batching window stays open.
+*
+* Ten milliseconds is below the threshold where a human notices a cursor lag,
+* and it is the difference between one query per message and one query per
+* window under load. Set to 0 to disable coalescing entirely.
+*/
+var DEFAULT_BATCH_WINDOW_MS = 10;
+/** JSON overhead per frame inside a batch: the wrapping array's comma. */
+var BATCH_SEPARATOR_BYTES = 1;
+/** JSON overhead of the batch envelope itself: `{"batch":[]}`. */
+var BATCH_ENVELOPE_BYTES = 12;
+var PostgresChannelBus = class {
+	db;
+	connectionString;
+	kind = "postgres";
+	maxFrameBytes = PG_NOTIFY_MAX_PAYLOAD_BYTES;
+	listener;
+	batchWindowMs;
+	/**
+	* Frames waiting for the current window to close.
+	*
+	* The window is opened by a publish that found none open, and that publish
+	* is sent *immediately* rather than joining a batch — see {@link publish}.
+	*/
+	pending = [];
+	pendingBytes = BATCH_ENVELOPE_BYTES;
+	windowTimer;
+	stopped = false;
+	constructor(db, connectionString, options = {}) {
+		this.db = db;
+		this.connectionString = connectionString;
+		const configured = options.batchWindowMs;
+		this.batchWindowMs = typeof configured === "number" && configured >= 0 ? configured : 10;
+	}
+	async start(handler) {
+		this.stopped = false;
+		this.listener = new PgNotifyListener({
+			connectionString: this.connectionString,
+			channel: CHANNEL_BUS_NOTIFY_CHANNEL,
+			logLabel: "[ChannelBus]",
+			onPayload: async (payload) => {
+				const frames = parseChannelBusPayload(payload);
+				if (!frames.length) {
+					logger.warn("⚠️ [ChannelBus] Dropping unparseable payload.");
+					return;
+				}
+				for (const frame of frames) await handler(frame);
+			}
+		});
+		await this.listener.start();
+	}
+	/**
+	* Publish, coalescing under load.
+	*
+	* The window is *leading edge*: a publish arriving when no window is open is
+	* sent straight away and opens one, so an idle channel pays no added latency
+	* at all. Frames arriving while it is open are collected and leave together
+	* when it closes. The effect is that cost tracks elapsed time rather than
+	* message count — one query per window instead of one per message — which is
+	* the same shape as the retention pruning throttle, for the same reason.
+	*
+	* The returned promise settles when the frame has actually left, not when it
+	* was queued, so the contract ("reaches the other instances, or rejects")
+	* still holds.
+	*/
+	async publish(frame) {
+		if (this.batchWindowMs === 0 || this.stopped) {
+			await this.send([frame]);
+			return;
+		}
+		if (!this.windowTimer) {
+			this.openWindow();
+			await this.send([frame]);
+			return;
+		}
+		const bytes = frameByteLength(frame) + BATCH_SEPARATOR_BYTES;
+		if (this.pending.length && this.pendingBytes + bytes > this.maxFrameBytes) this.flush();
+		return new Promise((resolve, reject) => {
+			this.pending.push({
+				frame,
+				bytes,
+				resolve,
+				reject
+			});
+			this.pendingBytes += bytes;
+		});
+	}
+	async stop() {
+		this.stopped = true;
+		if (this.windowTimer) {
+			clearTimeout(this.windowTimer);
+			this.windowTimer = void 0;
+		}
+		this.flush();
+		await this.listener?.stop();
+		this.listener = void 0;
+	}
+	openWindow() {
+		this.windowTimer = setTimeout(() => {
+			this.windowTimer = void 0;
+			if (this.pending.length) {
+				this.flush();
+				this.openWindow();
+			}
+		}, this.batchWindowMs);
+		this.windowTimer.unref?.();
+	}
+	/** Send everything queued and settle the promises waiting on it. */
+	flush() {
+		if (!this.pending.length) return;
+		const batch = this.pending;
+		this.pending = [];
+		this.pendingBytes = BATCH_ENVELOPE_BYTES;
+		this.send(batch.map((p) => p.frame)).then(() => {
+			for (const p of batch) p.resolve();
+		}).catch((error) => {
+			for (const p of batch) p.reject(error);
+		});
+	}
+	/**
+	* One NOTIFY.
+	*
+	* A single frame goes out in the plain, unwrapped shape. That is not just
+	* economy: during a rolling deploy an instance running the previous build
+	* understands only that shape, and low-rate traffic — presence, the tail of
+	* a session — is exactly what is flowing while pods restart. Batching only
+	* appears under load, which shrinks the mixed-version window to almost
+	* nothing.
+	*/
+	async send(frames) {
+		if (!frames.length) return;
+		const payload = frames.length === 1 ? JSON.stringify(frames[0]) : JSON.stringify({ batch: frames });
+		await this.db.execute(sql`SELECT pg_notify(${CHANNEL_BUS_NOTIFY_CHANNEL}, ${payload})`);
+	}
+};
+/**
+* Parse a bus payload into the frames it carries.
+*
+* Accepts both wire shapes — a bare frame and a `{ batch: [...] }` envelope —
+* so an instance on the new build understands one on the old. Returns an empty
+* array for anything unrecognisable: a malformed or future-versioned message
+* must never take the listener down.
+*/
+function parseChannelBusPayload(payload) {
+	let parsed;
+	try {
+		parsed = JSON.parse(payload);
+	} catch {
+		return [];
+	}
+	if (!parsed || typeof parsed !== "object") return [];
+	const batch = parsed.batch;
+	if (Array.isArray(batch)) return batch.map((entry) => coerceFrame(entry)).filter((frame) => frame !== null);
+	const single = coerceFrame(parsed);
+	return single ? [single] : [];
+}
+/**
+* Parse a single bus frame, returning null for anything that is not a frame we
+* understand.
+*/
+function parseChannelBusFrame(payload) {
+	try {
+		return coerceFrame(JSON.parse(payload));
+	} catch {
+		return null;
+	}
+}
+function coerceFrame(value) {
+	if (!value || typeof value !== "object") return null;
+	const obj = value;
+	const sid = typeof obj.sid === "string" ? obj.sid : void 0;
+	const channel = typeof obj.channel === "string" ? obj.channel : void 0;
+	if (!sid || !channel) return null;
+	switch (obj.kind) {
+		case "broadcast":
+			if (typeof obj.event !== "string") return null;
+			return {
+				kind: "broadcast",
+				sid,
+				channel,
+				event: obj.event,
+				from: typeof obj.from === "string" ? obj.from : void 0,
+				seq: typeof obj.seq === "number" ? obj.seq : void 0,
+				payload: obj.payload
+			};
+		case "broadcast_ref":
+			if (typeof obj.seq !== "number") return null;
+			return {
+				kind: "broadcast_ref",
+				sid,
+				channel,
+				from: typeof obj.from === "string" ? obj.from : void 0,
+				seq: obj.seq
+			};
+		case "presence_diff": return {
+			kind: "presence_diff",
+			sid,
+			channel,
+			joins: obj.joins ?? {},
+			leaves: obj.leaves ?? {}
+		};
+		default: return null;
+	}
+}
+//#endregion
+//#region src/services/channel-bus/index.ts
+/**
+* Merge `REALTIME_CHANNEL_BUS` into the configured bus.
+*
+* The environment wins over a *named* built-in, so the transport can be changed
+* per deployment without a rebuild — the same reason `REALTIME_CDC` is an env
+* var. It does **not** win over a supplied instance: the env var can only name
+* transports this package knows how to construct, so honouring it there would
+* mean silently discarding the object the application handed us.
+*/
+function resolveChannelBusSetting(configured) {
+	const raw = (process.env.REALTIME_CHANNEL_BUS || "").trim().toLowerCase();
+	if (isChannelBusInstance(configured)) {
+		if (raw && raw !== configured.kind) logger.warn(`⚠️ [ChannelBus] REALTIME_CHANNEL_BUS="${raw}" is ignored because realtime.bus was given a "${configured.kind}" transport instance directly. Remove one of the two to make the intent clear.`);
+		return configured;
+	}
+	if (!raw) return configured ?? { type: "memory" };
+	if (raw !== "memory" && raw !== "postgres") {
+		logger.warn(`⚠️ [ChannelBus] Unknown REALTIME_CHANNEL_BUS value "${raw}" — expected memory|postgres, or pass a ChannelBus instance as realtime.bus for a transport that ships separately. Falling back to the configured bus.`);
+		return configured ?? { type: "memory" };
+	}
+	if (configured?.type === raw) return configured;
+	return raw === "memory" ? { type: "memory" } : { type: "postgres" };
+}
+/**
+* @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
+* supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
+* config-only callers keep their exact types.
+*/
+function resolveChannelBusConfig(configured) {
+	return resolveChannelBusSetting(configured);
+}
+/**
+* Produce the bus a setting asks for.
+*
+* An instance is handed straight back — constructing it was the application's
+* job, and this function has nothing to add. A named built-in that turns out to
+* be unusable degrades to the memory bus, with the reason logged, rather than
+* throwing: a misconfigured bus should cost a deployment its cross-instance
+* fan-out, not its ability to boot.
+*/
+function createChannelBus(setting, deps) {
+	if (isChannelBusInstance(setting)) return setting;
+	switch (setting.type) {
+		case "postgres": {
+			const connectionString = setting.connectionString || deps.directUrl;
+			if (!connectionString) {
+				logger.warn("⚠️ [ChannelBus] realtime.bus is \"postgres\" but no direct database URL is available (set DATABASE_DIRECT_URL or realtime.bus.connectionString) — channel broadcast and presence stay per-instance.");
+				return new MemoryChannelBus();
+			}
+			return new PostgresChannelBus(deps.db, connectionString, { batchWindowMs: setting.batchWindowMs });
+		}
+		default: return new MemoryChannelBus();
+	}
+}
+//#endregion
 //#region src/services/realtimeService.ts
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 var PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -10617,8 +11203,33 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 	* wait on each other.
 	*/
 	channelSendQueues = /* @__PURE__ */ new Map();
+	/**
+	* Cross-instance transport for channel frames and presence.
+	*
+	* Defaults to the memory bus, which publishes nowhere — so a single-instance
+	* deployment runs the same fan-out it always did, with one resolved promise
+	* per broadcast for company. See `channel-bus/ChannelBus.ts`.
+	*/
+	bus = new MemoryChannelBus();
+	/**
+	* The shared presence roster, present only when a real bus is active.
+	*
+	* Fan-out alone is not enough for presence: `presence_state` has to answer
+	* with everyone in the channel, and per-process maps can only answer for
+	* this replica's clients. See `channel-presence.ts`.
+	*/
+	presenceStore;
+	/** Sweeps roster rows left behind by instances that stopped heartbeating. */
+	presenceSweepInterval;
+	/**
+	* Channels whose oversized ephemeral broadcasts have already been reported,
+	* so a hot channel logs the problem once rather than once per message.
+	*/
+	oversizedBroadcastWarned = /* @__PURE__ */ new Set();
 	presenceInterval;
 	static PRESENCE_TIMEOUT_MS = 3e4;
+	/** How often stale roster rows from other instances are reaped. */
+	static PRESENCE_SWEEP_INTERVAL_MS = 1e4;
 	dataService;
 	_subscriptions = /* @__PURE__ */ new Map();
 	subscriptionCallbacks = /* @__PURE__ */ new Map();
@@ -10767,10 +11378,11 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		}
 		for (const [channel, members] of this.channels.entries()) if (members.has(clientId)) {
 			members.delete(clientId);
-			this.removePresence(clientId, channel);
+			this.removePresence(clientId, channel, { skipStore: true });
 			if (members.size === 0) this.channels.delete(channel);
 		}
-		for (const [channel] of this.presence) this.removePresence(clientId, channel);
+		for (const [channel] of this.presence) this.removePresence(clientId, channel, { skipStore: true });
+		this.presenceStoreOp(() => this.presenceStore.removeClient(clientId), "client removal");
 	}
 	async handleMessage(clientId, message, authContext) {
 		const payload = message.payload;
@@ -10819,6 +11431,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 				this.sendError(clientId, msg, subscriptionId);
 				return;
 			}
+			const boundedLimit = resolveClientListLimit(request.limit, { vectorSearch: !!request.vectorSearch });
 			this._subscriptions.set(subscriptionId, {
 				clientId,
 				type: "collection",
@@ -10827,7 +11440,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 					filter: request.filter,
 					orderBy: request.orderBy,
 					order: request.order,
-					limit: request.limit,
+					limit: boundedLimit,
 					startAfter: request.startAfter,
 					databaseId: request.collection?.databaseId,
 					searchString: request.searchString
@@ -10838,7 +11451,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 				filter: request.filter,
 				orderBy: request.orderBy,
 				order: request.order,
-				limit: request.limit,
+				limit: boundedLimit,
 				startAfter: request.startAfter,
 				searchString: request.searchString
 			}, authContext);
@@ -11299,6 +11912,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		const retention = this.channelHistory?.retentionFor(channel);
 		if (!retention) {
 			this.fanOutBroadcast(clientId, channel, event, payload);
+			this.publishBroadcast(clientId, channel, event, payload);
 			return;
 		}
 		const next = (this.channelSendQueues.get(channel) ?? Promise.resolve()).catch(() => {}).then(() => this.persistAndFanOut(clientId, channel, event, payload, retention));
@@ -11327,6 +11941,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			return;
 		}
 		this.fanOutBroadcast(clientId, channel, event, payload, seq);
+		this.publishBroadcast(clientId, channel, event, payload, seq);
 		try {
 			await this.channelHistory.prune(channel, retention);
 		} catch (error) {
@@ -11351,6 +11966,132 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		}
 	}
 	/**
+	* Install the transport that carries channel frames between instances.
+	*
+	* Called once at boot. A bus that cannot start is reported and replaced with
+	* the memory bus: losing cross-instance fan-out degrades collaboration to
+	* what it was before this existed, whereas refusing to boot takes the whole
+	* backend down for it.
+	*/
+	async configureChannelBus(bus) {
+		if (bus.kind === "memory") {
+			this.bus = bus;
+			return;
+		}
+		try {
+			await bus.start((frame) => this.handleBusFrame(frame));
+		} catch (error) {
+			logger.warn(`⚠️ [ChannelBus] Could not start the "${bus.kind}" channel bus — channel broadcast and presence stay per-instance. Clients served by different replicas will not see each other.`, { error });
+			await bus.stop().catch(() => {});
+			this.bus = new MemoryChannelBus();
+			return;
+		}
+		this.bus = bus;
+		try {
+			const store = new ChannelPresenceStore(this.db, this.instanceId);
+			await store.ensureTables();
+			this.presenceStore = store;
+			this.ensurePresenceSweep();
+		} catch (error) {
+			logger.warn("⚠️ [ChannelBus] Could not create the shared presence table — presence rosters will only list clients connected to this instance (broadcast is unaffected).", { error });
+			this.presenceStore = void 0;
+		}
+		logger.info(`📡 [ChannelBus] Cross-instance channels active via ${bus.kind} (instanceId: ${this.instanceId}).`);
+	}
+	/** Which transport is in use — `"memory"` means per-instance only. */
+	getChannelBusKind() {
+		return this.bus.kind;
+	}
+	/**
+	* Send a broadcast to the other instances.
+	*
+	* Fire-and-forget by design: the clients on this instance have already been
+	* served, and a bus that is briefly unreachable must not turn a broadcast
+	* into an error for the sender.
+	*/
+	publishBroadcast(clientId, channel, event, payload, seq) {
+		if (this.bus.kind === "memory") return;
+		const frame = {
+			kind: "broadcast",
+			sid: this.instanceId,
+			channel,
+			event,
+			from: clientId,
+			...seq !== void 0 ? { seq } : {},
+			payload
+		};
+		if (frameByteLength(frame) > this.bus.maxFrameBytes) {
+			if (seq === void 0) {
+				this.reportOversizedBroadcast(clientId, channel);
+				return;
+			}
+			this.publishFrame({
+				kind: "broadcast_ref",
+				sid: this.instanceId,
+				channel,
+				from: clientId,
+				seq
+			});
+			return;
+		}
+		this.publishFrame(frame);
+	}
+	async publishFrame(frame) {
+		try {
+			await this.bus.publish(frame);
+		} catch (error) {
+			logger.error("❌ [ChannelBus] Failed to publish frame — other instances did not receive it", {
+				detail: `${frame.kind} on "${frame.channel}"`,
+				error
+			});
+		}
+	}
+	/**
+	* Tell the sender that a message was delivered locally but nowhere else.
+	*
+	* Staying quiet here would be the worst option available: on one instance
+	* the app works, on two it works for half the users, and nothing in the
+	* logs connects the two. The fix is a one-liner in config — give the
+	* channel a retention rule and the message travels as a pointer instead —
+	* so the message says exactly that.
+	*/
+	reportOversizedBroadcast(clientId, channel) {
+		const remedy = `Add a retention rule for "${channel}" (realtime.channels) — retained messages travel by reference and have no size limit.`;
+		if (!this.oversizedBroadcastWarned.has(channel)) {
+			this.oversizedBroadcastWarned.add(channel);
+			logger.warn(`⚠️ [ChannelBus] A broadcast on ephemeral channel "${channel}" exceeds the ${this.bus.maxFrameBytes}-byte limit of the ${this.bus.kind} bus and reached only this instance. ` + remedy);
+		}
+		this.sendError(clientId, `Broadcast on "${channel}" was too large to reach other instances. ${remedy}`, void 0, "CHANNEL_BUS_PAYLOAD_TOO_LARGE");
+	}
+	/**
+	* Deliver a frame published by another instance to this one's clients.
+	*
+	* Frames we published ourselves are dropped on arrival — the local fan-out
+	* happened before the publish — exactly as the entity-change handler skips
+	* its own `sid`.
+	*/
+	async handleBusFrame(frame) {
+		if (frame.sid === this.instanceId) return;
+		switch (frame.kind) {
+			case "broadcast":
+				this.fanOutBroadcast(frame.from ?? "", frame.channel, frame.event, frame.payload, frame.seq);
+				return;
+			case "broadcast_ref": {
+				if (!this.channels.get(frame.channel)?.size) return;
+				const entry = await this.channelHistory?.getBySeq(frame.channel, frame.seq);
+				if (!entry) {
+					logger.warn(`⚠️ [ChannelBus] Message ${frame.seq} on "${frame.channel}" is no longer retained — clients on this instance will need to replay (channel_history) to catch up.`);
+					return;
+				}
+				this.fanOutBroadcast(frame.from ?? "", frame.channel, entry.event, entry.payload, entry.seq);
+				return;
+			}
+			case "presence_diff":
+				this.deliverPresenceDiff(frame.channel, frame.joins, frame.leaves);
+				return;
+		}
+	}
+	/**
 	* Install retention rules and create the tables they need.
 	*
 	* Safe to call with no rules (and safe not to call at all): the store stays
@@ -11399,32 +12140,77 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			...latestSeq !== void 0 ? { latestSeq } : {}
 		}));
 	}
-	/** Track presence in a channel */
+	/**
+	* Track presence in a channel.
+	*
+	* The client re-sends this every ~20s as a heartbeat against the 30s
+	* timeout, so most calls carry the state that is already recorded. Those
+	* refresh `last_seen` and stop there: re-announcing an unchanged state to
+	* every instance would put a bus message per client per heartbeat on the
+	* wire to tell everyone nothing happened.
+	*/
 	trackPresence(clientId, channel, state) {
 		if (!this.presence.has(channel)) this.presence.set(channel, /* @__PURE__ */ new Map());
-		this.presence.get(channel).set(clientId, {
+		const channelPresence = this.presence.get(channel);
+		const previous = channelPresence.get(clientId);
+		const changed = !previous || JSON.stringify(previous.state) !== JSON.stringify(state);
+		channelPresence.set(clientId, {
 			state,
 			lastSeen: Date.now()
 		});
-		this.broadcastPresenceDiff(channel, { [clientId]: state }, {});
+		this.presenceStoreOp(() => this.presenceStore.track(channel, clientId, state), "track");
+		this.deliverPresenceDiff(channel, { [clientId]: state }, {});
+		if (changed) this.publishPresenceDiff(channel, { [clientId]: state }, {});
 		this.ensurePresenceCleanup();
 	}
-	/** Remove presence from a channel */
-	removePresence(clientId, channel) {
+	/**
+	* Remove presence from a channel.
+	*
+	* `skipStore` is for the socket-close path, which clears every channel at
+	* once and then deletes the client's rows in a single statement instead of
+	* one per channel.
+	*/
+	removePresence(clientId, channel, options) {
 		const channelPresence = this.presence.get(channel);
 		if (!channelPresence) return;
 		const entry = channelPresence.get(clientId);
 		if (entry) {
 			channelPresence.delete(clientId);
-			this.broadcastPresenceDiff(channel, {}, { [clientId]: entry.state });
+			this.deliverPresenceDiff(channel, {}, { [clientId]: entry.state });
+			this.publishPresenceDiff(channel, {}, { [clientId]: entry.state });
+			if (!options?.skipStore) this.presenceStoreOp(() => this.presenceStore.remove(channel, clientId), "remove");
 		}
 		if (channelPresence.size === 0) this.presence.delete(channel);
 	}
-	/** Send full presence state to a specific client */
+	/**
+	* Send the full roster for a channel to one client.
+	*
+	* Answered from the shared table when there is one, because "who is in this
+	* document?" has a single answer that must not depend on which replica the
+	* asker happens to be connected to. Without a bus there is nothing to share
+	* and the local map *is* the roster — that path stays synchronous, which is
+	* what it always was.
+	*/
 	sendPresenceState(clientId, channel) {
+		if (!this.presenceStore) {
+			this.sendPresenceStateMessage(clientId, channel, this.localPresences(channel));
+			return;
+		}
+		this.presenceStore.roster(channel).then((presences) => {
+			this.sendPresenceStateMessage(clientId, channel, presences);
+		}).catch((error) => {
+			logger.warn(`⚠️ [Presence] Could not read the shared roster for "${channel}" — answering with this instance's clients only.`, { error });
+			this.sendPresenceStateMessage(clientId, channel, this.localPresences(channel));
+		});
+	}
+	/** Presence of the clients connected to this instance. */
+	localPresences(channel) {
 		const channelPresence = this.presence.get(channel);
 		const presences = {};
 		if (channelPresence) for (const [id, { state }] of channelPresence) presences[id] = state;
+		return presences;
+	}
+	sendPresenceStateMessage(clientId, channel, presences) {
 		const ws = this.clients.get(clientId);
 		if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({
 			type: "presence_state",
@@ -11432,8 +12218,8 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			presences
 		}));
 	}
-	/** Broadcast presence diff (joins/leaves) to channel */
-	broadcastPresenceDiff(channel, joins, leaves) {
+	/** Deliver a presence diff to this instance's members of the channel. */
+	deliverPresenceDiff(channel, joins, leaves) {
 		const members = this.channels.get(channel);
 		if (!members) return;
 		const message = JSON.stringify({
@@ -11447,6 +12233,26 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			if (ws && ws.readyState === WebSocket.OPEN) ws.send(message);
 		}
 	}
+	/** Tell the other instances about a presence change. */
+	publishPresenceDiff(channel, joins, leaves) {
+		if (this.bus.kind === "memory") return;
+		this.publishFrame({
+			kind: "presence_diff",
+			sid: this.instanceId,
+			channel,
+			joins,
+			leaves
+		});
+	}
+	/** Run a roster write when there is a roster, and never let it throw. */
+	async presenceStoreOp(op, label) {
+		if (!this.presenceStore) return;
+		try {
+			await op();
+		} catch (error) {
+			logger.warn(`⚠️ [Presence] Shared roster ${label} failed`, { error });
+		}
+	}
 	/** Periodic cleanup for stale presences */
 	ensurePresenceCleanup() {
 		if (this.presenceInterval) return;
@@ -11460,6 +12266,35 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		}, 1e4);
 	}
 	/**
+	* Reap roster rows whose owning instance stopped heartbeating.
+	*
+	* This is the cross-instance half of the sweep above, and it doubles as
+	* crash recovery: a pod that dies takes its clients with it but leaves
+	* their rows behind, and after one TTL window they look exactly like any
+	* other client that went quiet. The delete returns what it removed, so
+	* whichever instance wins the race is the one that announces the
+	* departures — once for the cluster, not once per replica.
+	*/
+	ensurePresenceSweep() {
+		if (this.presenceSweepInterval || !this.presenceStore) return;
+		this.presenceSweepInterval = setInterval(() => void this.sweepStalePresence(), RealtimeService.PRESENCE_SWEEP_INTERVAL_MS);
+		this.presenceSweepInterval.unref?.();
+	}
+	/** One pass of the stale-roster sweep. See {@link ensurePresenceSweep}. */
+	async sweepStalePresence() {
+		if (!this.presenceStore) return;
+		try {
+			const removed = await this.presenceStore.sweepStale(RealtimeService.PRESENCE_TIMEOUT_MS);
+			for (const row of removed) {
+				this.debugLog(`👻 [Presence] Reaped stale presence ${row.clientId} on "${row.channel}"`);
+				this.deliverPresenceDiff(row.channel, {}, { [row.clientId]: row.state });
+				this.publishPresenceDiff(row.channel, {}, { [row.clientId]: row.state });
+			}
+		} catch (error) {
+			logger.warn("⚠️ [Presence] Stale-roster sweep failed", { error });
+		}
+	}
+	/**
 	* Gracefully tear down all realtime resources.
 	*
 	* This MUST be called during process shutdown, **before** `pool.end()`.
@@ -11486,8 +12321,23 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			clearInterval(this.presenceInterval);
 			this.presenceInterval = void 0;
 		}
+		if (this.presenceSweepInterval) {
+			clearInterval(this.presenceSweepInterval);
+			this.presenceSweepInterval = void 0;
+		}
+		this.oversizedBroadcastWarned.clear();
+		if (this.presenceStore) {
+			try {
+				await this.presenceStore.removeInstance();
+			} catch (error) {
+				logger.warn("⚠️ [Presence] Could not clear this instance's roster rows on shutdown", { error });
+			}
+			this.presenceStore = void 0;
+		}
 		await this.stopListening();
 		await this.stopCdc();
+		await this.bus.stop().catch((error) => logger.warn("⚠️ [ChannelBus] Error while stopping the channel bus", { error }));
+		this.bus = new MemoryChannelBus();
 		this.clients.clear();
 		this.debugLog("🧹 [RealtimeService] destroy() complete — all resources released.");
 	}
@@ -12463,11 +13313,57 @@ function buildPgRestoreArgs(opts) {
 	];
 	if (opts.clean) args.push("--clean", "--if-exists");
 	if (opts.noOwner) args.push("--no-owner");
-	if (opts.exitOnError) args.push("--exit-on-error");
+	if (opts.exitOnError !== false) args.push("--exit-on-error");
 	args.push(opts.inputFile);
 	return args;
 }
 /**
+* Assemble the `pg_restore --list` argument vector. Reading a dump's table
+* of contents parses the whole archive without touching a database, so it is
+* a cheap integrity check that the file isn't truncated or corrupt.
+*/
+function buildPgRestoreListArgs(inputFile) {
+	return ["--list", inputFile];
+}
+/**
+* Assemble the `pg_dumpall --globals-only` argument vector. Roles (and other
+* cluster-wide objects) live outside any single database, so a per-database
+* `pg_dump` omits them. Without the `rebase_user` role the RLS GRANT
+* statements in the main dump fail on restore and RLS is silently lost — so
+* every backup captures the globals into a sidecar `.globals.sql`.
+*
+* `--no-role-passwords` keeps role secrets out of the artifact (backups may
+* be shipped off-box); roles are recreated password-less and re-secured by
+* the operator.
+*/
+function buildPgDumpallGlobalsArgs(opts) {
+	return [
+		"--globals-only",
+		"--no-role-passwords",
+		"--no-password",
+		`--file=${opts.outFile}`,
+		`--dbname=${opts.connectionString}`
+	];
+}
+/**
+* Derive the globals sidecar path/key for a given `.dump` file. Keeps the
+* two artifacts adjacent so listing, uploading and pruning can find one from
+* the other. A name that doesn't end in `.dump` is returned unchanged with a
+* `.globals.sql` suffix appended.
+*/
+function globalsFileForDump(dumpPath) {
+	return dumpPath.endsWith(".dump") ? dumpPath.slice(0, -5) + ".globals.sql" : dumpPath + ".globals.sql";
+}
+/**
+* Split a `pg_dumpall --globals-only` script into individual statements.
+* Used when replaying globals on restore so each `CREATE ROLE` / `GRANT`
+* can run independently and a benign "role already exists" on one doesn't
+* abort the rest. Drops `--` comment lines and blank statements.
+*/
+function splitGlobalsStatements(sql) {
+	return sql.split("\n").filter((line) => !line.trim().startsWith("--")).join("\n").split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/**
 * Resolve the Postgres connection string the backup commands should use,
 * mirroring the precedence the branch command already relies on.
 */
@@ -20756,6 +21652,58 @@ function resolveLocalBin(binName) {
 	return null;
 }
 //#endregion
+//#region src/backup/backup-logic.ts
+/**
+* Pure-ish orchestration for the backup/restore paths, kept free of `execa`
+* and `pg` value imports so it can be unit-tested under jest (the impure
+* edges — spawning processes, opening connections — live in
+* `backup-service.ts`, which is vitest/runtime only).
+*
+* The functions here take their side-effecting dependency as an argument
+* (a statement runner, an object deleter) so tests can inject fakes.
+*/
+/**
+* Replay a `pg_dumpall --globals-only` script one statement at a time,
+* tolerating per-statement failures. On a same-cluster restore the roles
+* usually already exist (`CREATE ROLE` → "already exists") and on a managed
+* provider an `ALTER ROLE <superuser>` may be refused; neither should abort
+* recreation of the roles that *are* missing. Returns how many statements
+* applied vs were skipped.
+*
+* `runStatement` executes one SQL statement and rejects on error.
+*/
+async function applyGlobalsWith(runStatement, globalsSql, log = () => {}) {
+	let applied = 0;
+	let skipped = 0;
+	for (const statement of splitGlobalsStatements(globalsSql)) try {
+		await runStatement(statement);
+		applied++;
+	} catch (err) {
+		skipped++;
+		log(`  • Skipped global: ${statement.split("\n")[0].slice(0, 80)} (${err instanceof Error ? err.message : String(err)})`);
+	}
+	return {
+		applied,
+		skipped
+	};
+}
+/**
+* Delete each pruned dump together with its `.globals.sql` roles sidecar, so
+* pruning never orphans the roles file. The sidecar is best-effort — older
+* backups predate it, so a missing-sidecar failure is swallowed while a
+* failure deleting the dump itself propagates.
+*
+* `deleteObject` removes one key and rejects if it cannot (e.g. not found).
+*/
+async function pruneWith(keys, deleteObject) {
+	for (const key of keys) {
+		await deleteObject(key);
+		try {
+			await deleteObject(globalsFileForDump(key));
+		} catch {}
+	}
+}
+//#endregion
 //#region src/backup/backup-service.ts
 /**
 * Backup / restore orchestration: thin, well-typed wrappers around
@@ -20768,6 +21716,7 @@ function resolveLocalBin(binName) {
 */
 var backup_service_exports = /* @__PURE__ */ __exportAll({
 	BackupToolError: () => BackupToolError,
+	applyGlobals: () => applyGlobals,
 	createDump: () => createDump,
 	detectToolMajor: () => detectToolMajor,
 	ensureDatabaseExists: () => ensureDatabaseExists,
@@ -20777,7 +21726,8 @@ var backup_service_exports = /* @__PURE__ */ __exportAll({
 	pruneBackups: () => pruneBackups,
 	resolvePgBinary: () => resolvePgBinary,
 	restoreDump: () => restoreDump,
-	uploadBackup: () => uploadBackup
+	uploadBackup: () => uploadBackup,
+	validateDump: () => validateDump
 });
 var BackupToolError = class extends Error {
 	hint;
@@ -20787,10 +21737,10 @@ var BackupToolError = class extends Error {
 		this.name = "BackupToolError";
 	}
 };
-/** Locate `pg_dump` / `pg_restore`, honouring an env override. */
+/** Locate `pg_dump` / `pg_restore` / `pg_dumpall`, honouring an env override. */
 function resolvePgBinary(tool, env = process.env) {
-	const override = tool === "pg_dump" ? env.PG_DUMP_PATH : env.PG_RESTORE_PATH;
-	if (override && fs.existsSync(override)) return override;
+	const overrideVar = tool === "pg_dump" ? env.PG_DUMP_PATH : tool === "pg_restore" ? env.PG_RESTORE_PATH : env.PG_DUMPALL_PATH;
+	if (overrideVar && fs.existsSync(overrideVar)) return overrideVar;
 	return resolveLocalBin(tool);
 }
 /** Run `<bin> --version` and extract the major version. */
@@ -20834,6 +21784,11 @@ async function preflight(tool, connectionString, env = process.env) {
 * Produce a custom-format dump on local disk. When `outDir` is omitted the
 * file is written to the OS temp directory (used by the upload path, which
 * cleans it up afterwards).
+*
+* Alongside the `-Fc` dump it writes a `<name>.globals.sql` sidecar via
+* `pg_dumpall --globals-only` so the roles the dump's GRANT/RLS statements
+* depend on can be recreated on restore. Set `includeGlobals: false` to skip
+* it (e.g. when the caller has no privilege to read cluster globals).
 */
 async function createDump(opts) {
 	const env = opts.env ?? process.env;
@@ -20852,17 +21807,92 @@ async function createDump(opts) {
 		stdio: opts.inheritStdio ? "inherit" : "pipe",
 		env: { ...env }
 	});
-	return {
+	const result = {
 		localFile,
 		fileName,
 		sizeBytes: fs.existsSync(localFile) ? fs.statSync(localFile).size : 0
 	};
+	if (opts.includeGlobals !== false) {
+		const dumpallBin = resolvePgBinary("pg_dumpall", env);
+		if (!dumpallBin) throw new BackupToolError("Could not find the 'pg_dumpall' binary needed to capture cluster roles.", "Install the PostgreSQL client tools or set PG_DUMPALL_PATH. To take a role-incomplete backup anyway, pass includeGlobals: false.");
+		const globalsFile = globalsFileForDump(localFile);
+		await execa(dumpallBin, buildPgDumpallGlobalsArgs({
+			connectionString: opts.connectionString,
+			outFile: globalsFile
+		}), {
+			stdio: opts.inheritStdio ? "inherit" : "pipe",
+			env: { ...env }
+		});
+		result.globalsFile = globalsFile;
+		result.globalsSizeBytes = fs.existsSync(globalsFile) ? fs.statSync(globalsFile).size : 0;
+	}
+	return result;
+}
+/**
+* Cheap integrity check on a freshly written dump: it must be non-empty and
+* `pg_restore --list` must parse its table of contents without error. Used
+* before pruning older backups so a corrupt-but-exit-0 dump never becomes
+* the reason the last good backup is deleted.
+*/
+async function validateDump(localFile, env = process.env) {
+	if (!fs.existsSync(localFile)) return {
+		ok: false,
+		reason: `Dump file does not exist: ${localFile}`
+	};
+	if (fs.statSync(localFile).size === 0) return {
+		ok: false,
+		reason: "Dump file is empty (0 bytes)."
+	};
+	const bin = resolvePgBinary("pg_restore", env);
+	if (!bin) return {
+		ok: false,
+		reason: "Could not find 'pg_restore' to verify the dump."
+	};
+	try {
+		await execa(bin, buildPgRestoreListArgs(localFile), {
+			stdio: "pipe",
+			env: { ...env }
+		});
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: `pg_restore --list failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+}
+/**
+* Replay a `pg_dumpall --globals-only` script to recreate cluster roles
+* before a restore, so the dump's GRANT/RLS statements (which reference
+* `rebase_user` and any owner roles) actually apply. Runs statement by
+* statement and tolerates per-statement failures — on a same-cluster restore
+* the roles usually already exist (`CREATE ROLE` → "already exists"), and on
+* a managed provider an `ALTER ROLE <superuser>` may be refused; neither
+* should abort role recreation. Returns how many statements applied vs were
+* skipped.
+*/
+async function applyGlobals(connectionString, globalsSql, log = () => {}) {
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		return await applyGlobalsWith(async (sql) => {
+			await client.query(sql);
+		}, globalsSql, log);
+	} finally {
+		await client.end();
+	}
 }
 /**
 * Restore a custom-format dump into the database named by
 * `connectionString`. Destructive when `clean` is set (drops objects
 * first). Never called automatically — the CLI gates it behind explicit
 * confirmation.
+*
+* Runs with `--exit-on-error` by default: a restore that logs-and-continues
+* past a failed GRANT (because a role was missing) reports success with RLS
+* un-enforced. Callers should recreate roles first (see {@link applyGlobals})
+* and only set `exitOnError: false` deliberately.
 */
 async function restoreDump(opts) {
 	const env = opts.env ?? process.env;
@@ -20872,7 +21902,8 @@ async function restoreDump(opts) {
 		connectionString: opts.connectionString,
 		inputFile: opts.inputFile,
 		clean: opts.clean,
-		noOwner: opts.noOwner
+		noOwner: opts.noOwner,
+		exitOnError: opts.exitOnError
 	}), {
 		stdio: opts.inheritStdio ? "inherit" : "pipe",
 		env: { ...env }
@@ -20949,9 +21980,13 @@ async function listBackups(dest, storage) {
 */
 async function pruneBackups(dest, options, storage) {
 	const toDelete = selectBackupsToPrune(await listBackups(dest, storage), options);
-	for (const key of toDelete) if (dest.kind === "local") {
-		if (fs.existsSync(key)) fs.unlinkSync(key);
-	} else if (storage) await storage.deleteObject(key, dest.bucket);
+	await pruneWith(toDelete, dest.kind === "local" ? async (key) => {
+		if (!fs.existsSync(key)) throw new Error(`not found: ${key}`);
+		fs.unlinkSync(key);
+	} : async (key) => {
+		if (!storage) throw new BackupToolError("Storage backend required to prune object backups.");
+		await storage.deleteObject(key, dest.bucket);
+	});
 	return toDelete;
 }
 //#endregion
@@ -21016,7 +22051,7 @@ function createBackupCron(config) {
 		enabled: config.enabled ?? true,
 		timeoutSeconds: 3600,
 		async handler({ log }) {
-			const { createDump, pruneBackups, uploadBackup } = await Promise.resolve().then(() => backup_service_exports);
+			const { createDump, pruneBackups, uploadBackup, validateDump } = await Promise.resolve().then(() => backup_service_exports);
 			const { destination } = config;
 			if (destination.kind !== "local" && !config.storage) throw new Error(`Backup destination is ${destination.kind} but no storage controller was provided. Pass the backend's configured StorageController to createBackupCron({ storage }).`);
 			log(`Starting backup of "${dbName}"…`);
@@ -21028,15 +22063,23 @@ function createBackupCron(config) {
 				excludeSchemas
 			});
 			log(`Dump created: ${dump.fileName} (${formatBytes(dump.sizeBytes)})`);
+			const check = await validateDump(dump.localFile);
+			if (!check.ok) {
+				if (destination.kind !== "local" && fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
+				if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) fs.unlinkSync(dump.globalsFile);
+				throw new Error(`New backup failed validation — skipping upload and pruning to protect existing backups. ${check.reason}`);
+			}
 			let storedKey = dump.localFile;
 			try {
 				if (destination.kind !== "local") {
 					const uploaded = await uploadBackup(config.storage, dump.localFile, destination);
 					storedKey = uploaded.storageUrl;
 					log(`Uploaded to ${uploaded.storageUrl}`);
+					if (dump.globalsFile && fs.existsSync(dump.globalsFile)) log(`Uploaded roles sidecar to ${(await uploadBackup(config.storage, dump.globalsFile, destination)).storageUrl}`);
 				}
 			} finally {
 				if (destination.kind !== "local" && fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
+				if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) fs.unlinkSync(dump.globalsFile);
 			}
 			let pruned = [];
 			if (config.retentionDays && config.retentionDays > 0) {
@@ -21153,6 +22196,7 @@ async function ensureAuthTablesExist(db, collection) {
                 email_verification_sent_at TIMESTAMP WITH TIME ZONE,
                 is_anonymous BOOLEAN DEFAULT FALSE NOT NULL,
                 metadata JSONB DEFAULT '{}' NOT NULL,
+                tokens_valid_after TIMESTAMP WITH TIME ZONE,
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
                 updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
             )
@@ -21233,12 +22277,15 @@ async function ensureAuthTablesExist(db, collection) {
             CREATE TABLE IF NOT EXISTS ${sql.raw(refreshTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
                 uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                session_id TEXT NOT NULL DEFAULT gen_random_uuid()::text,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+                revoked BOOLEAN DEFAULT FALSE NOT NULL,
+                rotated_at TIMESTAMP WITH TIME ZONE,
+                session_started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
                 user_agent TEXT,
                 ip_address TEXT,
-                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                CONSTRAINT unique_device_session UNIQUE (uid, user_agent, ip_address)
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
             )
         `);
 		await db.execute(sql`
@@ -21328,6 +22375,7 @@ async function ensureAuthTablesExist(db, collection) {
 			"email_verification_sent_at TIMESTAMP WITH TIME ZONE",
 			"is_anonymous BOOLEAN DEFAULT FALSE NOT NULL",
 			"metadata JSONB DEFAULT '{}' NOT NULL",
+			"tokens_valid_after TIMESTAMP WITH TIME ZONE",
 			"created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL",
 			"updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL"
 		]) await db.execute(sql`
@@ -21344,42 +22392,36 @@ async function ensureAuthTablesExist(db, collection) {
 			for (const { table_schema } of found) {
 				const qualified = `"${table_schema}"."refresh_tokens"`;
 				try {
-					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS user_agent TEXT`);
-					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS ip_address TEXT`);
-					await db.execute(sql`UPDATE ${sql.raw(qualified)} SET user_agent = '' WHERE user_agent IS NULL`);
-					await db.execute(sql`UPDATE ${sql.raw(qualified)} SET ip_address = '' WHERE ip_address IS NULL`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS session_id TEXT`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS revoked BOOLEAN DEFAULT FALSE NOT NULL`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS rotated_at TIMESTAMP WITH TIME ZONE`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ADD COLUMN IF NOT EXISTS session_started_at TIMESTAMP WITH TIME ZONE`);
 					await db.execute(sql`
-                        DELETE FROM ${sql.raw(qualified)} a
-                        USING ${sql.raw(qualified)} b
-                        WHERE a.ctid < b.ctid
-                          AND a.uid = b.uid
-                          AND a.user_agent = b.user_agent
-                          AND a.ip_address = b.ip_address
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_id = gen_random_uuid()::text
+                        WHERE session_id IS NULL
                     `);
-					const uniques = await db.execute(sql`
-                        SELECT conname, pg_get_constraintdef(oid) AS def
-                        FROM pg_constraint
-                        WHERE conrelid = ${sql.raw(`'${qualified}'`)}::regclass AND contype = 'u'
+					await db.execute(sql`
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_started_at = COALESCE(created_at, NOW())
+                        WHERE session_started_at IS NULL
                     `);
-					for (const u of uniques.rows) logger.info(`   ${qualified} unique: ${u.conname} → ${u.def}`);
-					if (uniques.rows.some((u) => {
-						const cols = (u.def.match(/\(([^)]*)\)/)?.[1] || "").split(",").map((c) => c.trim().replace(/"/g, ""));
-						return cols.length === 3 && cols.includes("uid") && cols.includes("user_agent") && cols.includes("ip_address");
-					})) logger.info(`✓ correct device-session unique already present on ${qualified}`);
-					else {
-						await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} DROP CONSTRAINT IF EXISTS unique_device_session`);
-						await db.execute(sql`
-                            ALTER TABLE ${sql.raw(qualified)}
-                                ADD CONSTRAINT unique_device_session UNIQUE (uid, user_agent, ip_address)
-                        `);
-						logger.info(`✅ Added correct unique_device_session constraint to ${qualified}`);
-					}
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_id SET DEFAULT gen_random_uuid()::text`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_started_at SET DEFAULT NOW()`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_id SET NOT NULL`);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} ALTER COLUMN session_started_at SET NOT NULL`);
+					await db.execute(sql`
+                        CREATE INDEX IF NOT EXISTS idx_refresh_tokens_session
+                        ON ${sql.raw(qualified)}(session_id)
+                    `);
+					await db.execute(sql`ALTER TABLE ${sql.raw(qualified)} DROP CONSTRAINT IF EXISTS unique_device_session`);
+					logger.info(`✅ refresh_tokens reconciled for session-scoped rotation: ${qualified}`);
 				} catch (perTableError) {
 					logger.warn(`⚠️  refresh_tokens reconcile failed for ${qualified}: ${perTableError instanceof Error ? perTableError.message : String(perTableError)}`);
 				}
 			}
 		} catch (migrationError) {
-			logger.warn(`⚠️  refresh_tokens device-session migration skipped: ${migrationError instanceof Error ? migrationError.message : String(migrationError)}`);
+			logger.warn(`⚠️  refresh_tokens session migration skipped: ${migrationError instanceof Error ? migrationError.message : String(migrationError)}`);
 		}
 		try {
 			if ((await db.execute(sql`
@@ -21871,34 +22913,31 @@ var UserService = class {
 var RefreshTokenService = class {
 	db;
 	refreshTokensTable;
+	usersTable;
 	constructor(db, tableOrTables) {
 		this.db = db;
-		if (tableOrTables && (tableOrTables.refreshTokens || tableOrTables.users)) this.refreshTokensTable = tableOrTables.refreshTokens || refreshTokens;
-		else this.refreshTokensTable = tableOrTables || refreshTokens;
+		if (tableOrTables && (tableOrTables.refreshTokens || tableOrTables.users)) {
+			this.refreshTokensTable = tableOrTables.refreshTokens || refreshTokens;
+			this.usersTable = tableOrTables.users || users;
+		} else {
+			this.refreshTokensTable = tableOrTables || refreshTokens;
+			this.usersTable = users;
+		}
 	}
-	async createToken(uid, tokenHash, expiresAt, userAgent, ipAddress) {
-		const safeUserAgent = userAgent || "";
-		const safeIpAddress = ipAddress || "";
-		await this.db.insert(this.refreshTokensTable).values({
-			uid,
-			tokenHash,
-			expiresAt,
-			userAgent: safeUserAgent,
-			ipAddress: safeIpAddress
-		}).onConflictDoUpdate({
-			target: [
-				this.refreshTokensTable.uid,
-				this.refreshTokensTable.userAgent,
-				this.refreshTokensTable.ipAddress
-			],
-			set: {
-				tokenHash,
-				expiresAt
-			}
-		});
+	/**
+	* Whether the table actually carries a column, so a host application that
+	* supplied its own `refresh_tokens` table — one that predates session
+	* grouping — degrades instead of throwing on every sign-in.
+	*/
+	has(column) {
+		return Boolean(this.refreshTokensTable[column]);
 	}
-	async findByHash(tokenHash) {
-		const [token] = await this.db.select({
+	col(column) {
+		return this.refreshTokensTable[column];
+	}
+	/** The columns to read back, narrowed to the ones this table has. */
+	selection() {
+		const selection = {
 			id: this.refreshTokensTable.id,
 			uid: this.refreshTokensTable.uid,
 			tokenHash: this.refreshTokensTable.tokenHash,
@@ -21906,9 +22945,94 @@ var RefreshTokenService = class {
 			createdAt: this.refreshTokensTable.createdAt,
 			userAgent: this.refreshTokensTable.userAgent,
 			ipAddress: this.refreshTokensTable.ipAddress
-		}).from(this.refreshTokensTable).where(eq(this.refreshTokensTable.tokenHash, tokenHash));
+		};
+		for (const optional of [
+			"sessionId",
+			"rotatedAt",
+			"revoked",
+			"sessionStartedAt"
+		]) if (this.has(optional)) selection[optional] = this.col(optional);
+		return selection;
+	}
+	async createToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session) {
+		const values = {
+			uid,
+			tokenHash,
+			expiresAt,
+			userAgent: userAgent || "",
+			ipAddress: ipAddress || ""
+		};
+		if (session && this.has("sessionId")) values.sessionId = session.id;
+		if (session && this.has("sessionStartedAt")) values.sessionStartedAt = session.startedAt;
+		await this.db.insert(this.refreshTokensTable).values(values);
+	}
+	async findByHash(tokenHash) {
+		const [token] = await this.db.select(this.selection()).from(this.refreshTokensTable).where(eq(this.refreshTokensTable.tokenHash, tokenHash));
 		return token || null;
 	}
+	/**
+	* Record that a token was rotated away, keeping the row.
+	*
+	* The row is what lets `/auth/refresh` distinguish "you already used this,
+	* here is a fresh one" from "no idea what this is". Deleting it — which is
+	* what this used to do — collapsed both into a 401 and signed the user out
+	* for the crime of losing a response.
+	*/
+	async markRotated(tokenHash) {
+		if (!this.has("rotatedAt")) {
+			await this.deleteByHash(tokenHash);
+			return;
+		}
+		await this.db.update(this.refreshTokensTable).set({ rotatedAt: /* @__PURE__ */ new Date() }).where(eq(this.refreshTokensTable.tokenHash, tokenHash));
+	}
+	/** Final kill of one sign-in: logout, or revoking a device remotely. */
+	async revokeSession(sessionId) {
+		if (!this.has("sessionId")) return;
+		if (this.has("revoked")) {
+			await this.db.update(this.refreshTokensTable).set({
+				revoked: true,
+				...this.has("rotatedAt") ? { rotatedAt: /* @__PURE__ */ new Date() } : {}
+			}).where(eq(this.col("sessionId"), sessionId));
+			return;
+		}
+		await this.db.delete(this.refreshTokensTable).where(eq(this.col("sessionId"), sessionId));
+	}
+	/**
+	* Housekeeping: rotation would otherwise leave a row per refresh forever.
+	* Superseded rows are only needed for as long as a straggler might still
+	* present them, and expired ones are dead weight everywhere.
+	*/
+	async prune(uid, sessionId, supersededBefore) {
+		const uidCol = this.refreshTokensTable.uid;
+		const expiresCol = this.refreshTokensTable.expiresAt;
+		if (!this.has("rotatedAt") || !this.has("sessionId")) {
+			await this.db.delete(this.refreshTokensTable).where(sql`${uidCol} = ${uid} AND ${expiresCol} < NOW()`);
+			return;
+		}
+		const rotatedCol = this.col("rotatedAt");
+		const sessionCol = this.col("sessionId");
+		await this.db.delete(this.refreshTokensTable).where(sql`
+            ${uidCol} = ${uid}
+            AND (
+                ${expiresCol} < NOW()
+                OR (
+                    ${sessionCol} = ${sessionId}
+                    AND ${rotatedCol} IS NOT NULL
+                    AND ${rotatedCol} < ${supersededBefore}
+                )
+            )
+        `);
+	}
+	async getTokensValidAfter(uid) {
+		if (!this.usersTable || !this.usersTable.tokensValidAfter) return null;
+		const [row] = await this.db.select({ tokensValidAfter: this.usersTable.tokensValidAfter }).from(this.usersTable).where(eq(this.usersTable.id, uid));
+		const value = row?.tokensValidAfter;
+		return value ? new Date(value) : null;
+	}
+	async setTokensValidAfter(uid, at) {
+		if (!this.usersTable || !this.usersTable.tokensValidAfter) return;
+		await this.db.update(this.usersTable).set({ tokensValidAfter: at }).where(eq(this.usersTable.id, uid));
+	}
 	async deleteByHash(tokenHash) {
 		await this.db.delete(this.refreshTokensTable).where(eq(this.refreshTokensTable.tokenHash, tokenHash));
 	}
@@ -21916,15 +23040,7 @@ var RefreshTokenService = class {
 		await this.db.delete(this.refreshTokensTable).where(eq(this.refreshTokensTable.uid, uid));
 	}
 	async listForUser(uid) {
-		return await this.db.select({
-			id: this.refreshTokensTable.id,
-			uid: this.refreshTokensTable.uid,
-			tokenHash: this.refreshTokensTable.tokenHash,
-			expiresAt: this.refreshTokensTable.expiresAt,
-			createdAt: this.refreshTokensTable.createdAt,
-			userAgent: this.refreshTokensTable.userAgent,
-			ipAddress: this.refreshTokensTable.ipAddress
-		}).from(this.refreshTokensTable).where(eq(this.refreshTokensTable.uid, uid)).orderBy(this.refreshTokensTable.createdAt);
+		return await this.db.select(this.selection()).from(this.refreshTokensTable).where(eq(this.refreshTokensTable.uid, uid)).orderBy(this.refreshTokensTable.createdAt);
 	}
 	async deleteById(id, uid) {
 		await this.db.delete(this.refreshTokensTable).where(sql`${this.refreshTokensTable.id} = ${id} AND ${this.refreshTokensTable.uid} = ${uid}`);
@@ -22069,8 +23185,23 @@ var PostgresTokenRepository = class {
 		this.passwordResetTokenService = new PasswordResetTokenService(db, tableOrTables);
 		this.magicLinkTokenService = new MagicLinkTokenService(db, tableOrTables);
 	}
-	async createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress) {
-		await this.refreshTokenService.createToken(uid, tokenHash, expiresAt, userAgent, ipAddress);
+	async createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session) {
+		await this.refreshTokenService.createToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session);
+	}
+	async markRefreshTokenRotated(tokenHash) {
+		await this.refreshTokenService.markRotated(tokenHash);
+	}
+	async revokeRefreshTokenSession(sessionId) {
+		await this.refreshTokenService.revokeSession(sessionId);
+	}
+	async pruneRefreshTokens(uid, sessionId, supersededBefore) {
+		await this.refreshTokenService.prune(uid, sessionId, supersededBefore);
+	}
+	async getTokensValidAfter(uid) {
+		return this.refreshTokenService.getTokensValidAfter(uid);
+	}
+	async setTokensValidAfter(uid, at) {
+		await this.refreshTokenService.setTokensValidAfter(uid, at);
 	}
 	async findRefreshTokenByHash(tokenHash) {
 		return this.refreshTokenService.findByHash(tokenHash);
@@ -22236,8 +23367,23 @@ var PostgresAuthRepository = class {
 		};
 	}
 	async deleteRole(_id) {}
-	async createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress) {
-		await this.tokenRepository.createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress);
+	async createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session) {
+		await this.tokenRepository.createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session);
+	}
+	async markRefreshTokenRotated(tokenHash) {
+		await this.tokenRepository.markRefreshTokenRotated(tokenHash);
+	}
+	async revokeRefreshTokenSession(sessionId) {
+		await this.tokenRepository.revokeRefreshTokenSession(sessionId);
+	}
+	async pruneRefreshTokens(uid, sessionId, supersededBefore) {
+		await this.tokenRepository.pruneRefreshTokens(uid, sessionId, supersededBefore);
+	}
+	async getTokensValidAfter(uid) {
+		return this.tokenRepository.getTokensValidAfter(uid);
+	}
+	async setTokensValidAfter(uid, at) {
+		await this.tokenRepository.setTokensValidAfter(uid, at);
 	}
 	async findRefreshTokenByHash(tokenHash) {
 		return this.tokenRepository.findRefreshTokenByHash(tokenHash);
@@ -23322,6 +24468,15 @@ function createPostgresBootstrapper(pgConfig) {
 				logger.warn("⚠️ Could not initialize channel history tables — retained channels will not replay", { error: err });
 			}
 			const directUrl = process.env.DATABASE_DIRECT_URL || pgConfig.connectionString;
+			try {
+				const busSetting = resolveChannelBusSetting(pgConfig.realtime?.bus);
+				if (isChannelBusInstance(busSetting) || busSetting.type !== "memory") await realtimeService.configureChannelBus(createChannelBus(busSetting, {
+					db: schemaAwareDb,
+					directUrl
+				}));
+			} catch (err) {
+				logger.warn("⚠️ [ChannelBus] Could not configure the channel bus — channel broadcast and presence stay per-instance", { error: err });
+			}
 			const validModes = new Set([
 				"auto",
 				"wal",
@@ -23516,6 +24671,6 @@ function createPostgresAdapter(pgConfig) {
 	};
 }
 //#endregion
-export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, DatabasePoolManager, DrizzleConditionBuilder, PostgresBackendDriver, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgRestoreArgs, checkToolServerCompatibility, createAuthSchema, createBackupCron, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, ensureDatabaseExists, generateSchema, getServerVersionMajor, guardPoolAgainstDirtyRelease, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveConnectionString, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, withDatabaseName };
+export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, CHANNEL_BUS_NOTIFY_CHANNEL, DEFAULT_BATCH_WINDOW_MS, DatabasePoolManager, DrizzleConditionBuilder, MemoryChannelBus, PG_NOTIFY_MAX_PAYLOAD_BYTES, PostgresBackendDriver, PostgresChannelBus, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, applyGlobals, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgDumpallGlobalsArgs, buildPgRestoreArgs, buildPgRestoreListArgs, checkToolServerCompatibility, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
 
 //# sourceMappingURL=index.es.js.map