@rebasepro/server-postgres 0.9.1-canary.f0ac103 → 0.9.1-canary.faee831

package/dist/index.es.js

@@ -6524,8 +6524,27 @@ function coerceDeclaredNumbers(row, collection) {
 	return out;
 }
 /** Render one target row in the requested style. */
+/**
+* Drop every column the collection marked `excludeFromApi`.
+*
+* Password hashes and verification tokens have to be readable server-side but
+* must never reach a client — and "never" has to mean every exit from this
+* pipeline, including relation targets, or a secret leaks through whichever
+* path was overlooked. Keyed by both the property name and its column name,
+* since a row can arrive keyed either way depending on the caller.
+*/
+function stripExcluded(row, collection) {
+	const properties = collection.properties;
+	if (!properties) return row;
+	for (const [key, property] of Object.entries(properties)) {
+		if (!property?.excludeFromApi) continue;
+		delete row[key];
+		if (property.columnName) delete row[property.columnName];
+	}
+	return row;
+}
 function renderTarget(targetRow, targetCollection, style, registry) {
-	if (style === "inline") return coerceDeclaredNumbers({ ...targetRow }, targetCollection);
+	if (style === "inline") return stripExcluded(coerceDeclaredNumbers({ ...targetRow }, targetCollection), targetCollection);
 	const address = relationTargetAddress(targetRow, targetCollection, registry);
 	const path = targetCollection.slug;
 	return createRelationRefWithData(address, path, {
@@ -6567,7 +6586,7 @@ function toCmsRow(row, collection, registry) {
 			normalized[key] = relData.map((item) => renderTarget(isJunctionRelation(relation) ? unwrapJunctionRow(item) : item, targetCollection, "ref", registry));
 		} else if (relation.cardinality === "one" && typeof relData === "object" && !Array.isArray(relData)) normalized[key] = renderTarget(relData, relation.target(), "ref", registry);
 	}
-	return normalized;
+	return stripExcluded(normalized, collection);
 }
 /**
 * The row REST serves: every column under its own name, with the value Postgres
@@ -6592,7 +6611,7 @@ function toRestRow(row, collection, registry) {
 		else if (relation && typeof value === "object" && value !== null) flat[key] = renderTarget(value, relation.target(), "inline", registry);
 		else flat[key] = coerceDeclaredNumber(value, collection.properties?.[key]);
 	}
-	return flat;
+	return stripExcluded(flat, collection);
 }
 //#endregion
 //#region src/services/FetchService.ts
@@ -8171,14 +8190,14 @@ async function ensureAppRole(run, schemas) {
 * semantics: it is why `auth.uid() IS NOT NULL` is true for anonymous requests.
 */
 async function applyAuthContext(tx, auth, userRole) {
-	const userId = typeof auth.userId === "string" && auth.userId.trim() !== "" ? auth.userId : ANONYMOUS_USER_ID;
+	const uid = typeof auth.uid === "string" && auth.uid.trim() !== "" ? auth.uid : ANONYMOUS_USER_ID;
 	const normalizedRoles = auth.roles.map((r) => typeof r === "string" ? r : r?.id ?? String(r));
 	await tx.execute(sql`
         SELECT
-            set_config('app.user_id', ${userId}, true),
+            set_config('app.user_id', ${uid}, true),
             set_config('app.user_roles', ${normalizedRoles.join(",")}, true),
             set_config('app.jwt', ${JSON.stringify({
-		sub: userId,
+		sub: uid,
 		roles: auth.roles
 	})}, true)
     `);
@@ -8324,6 +8343,7 @@ var PostgresBackendDriver = class PostgresBackendDriver {
 			executeSql: (...args) => this.executeSql(...args),
 			fetchAvailableDatabases: () => this.fetchAvailableDatabases(),
 			fetchAvailableRoles: () => this.fetchAvailableRoles(),
+			fetchApplicationRoles: () => this.fetchApplicationRoles(),
 			fetchCurrentDatabase: () => this.fetchCurrentDatabase(),
 			fetchUnmappedTables: (...args) => this.fetchUnmappedTables(...args),
 			fetchTableMetadata: (...args) => this.fetchTableMetadata(...args),
@@ -8977,6 +8997,45 @@ var PostgresBackendDriver = class PostgresBackendDriver {
 	async fetchAvailableRoles() {
 		return (await this.executeSql("SELECT rolname FROM pg_roles WHERE pg_has_role(current_user, rolname, 'member') ORDER BY rolname;")).map((r) => r.rolname);
 	}
+	/**
+	* Application-level roles actually in use in this project.
+	*
+	* Distinct from {@link fetchAvailableRoles}, which returns native
+	* PostgreSQL roles from `pg_roles` (`postgres`, `rebase_user`, …). Those
+	* are the roles the SQL editor can `SET ROLE` to. *These* are the strings
+	* held in the users table's `roles` column, injected per-transaction as
+	* `auth.roles()` and matched by `SecurityRule.roles`. Feeding the pg roles
+	* into a `SecurityRule.roles` field produces a condition no user can ever
+	* satisfy, so the two must not be conflated.
+	*
+	* Roles have no registry table — they were migrated out of
+	* `rebase.user_roles` onto an inline `roles TEXT[]` column — so the live
+	* set is derived from what is assigned. A role that is declared in a policy
+	* but held by nobody yet cannot be discovered here; callers that need it
+	* should union in the roles they already know about.
+	*/
+	async fetchApplicationRoles() {
+		const located = await this.executeSql(`
+            SELECT table_schema, table_name
+            FROM information_schema.columns
+            WHERE column_name = 'roles'
+              AND data_type = 'ARRAY'
+              AND table_name = 'users'
+              AND table_schema NOT IN ('information_schema', 'pg_catalog')
+            ORDER BY (table_schema = 'rebase') DESC, table_schema
+            LIMIT 1;
+        `);
+		if (located.length === 0) return [];
+		const schema = located[0].table_schema;
+		const table = located[0].table_name;
+		const qualified = `"${schema.replace(/"/g, "\"\"")}"."${table.replace(/"/g, "\"\"")}"`;
+		return (await this.executeSql(`
+            SELECT DISTINCT unnest(roles) AS role
+            FROM ${qualified}
+            WHERE roles IS NOT NULL
+            ORDER BY role;
+        `)).map((r) => r.role).filter((r) => typeof r === "string" && r.length > 0);
+	}
 	async fetchCurrentDatabase() {
 		return this.poolManager?.defaultDatabaseName;
 	}
@@ -9118,15 +9177,15 @@ var AuthenticatedPostgresBackendDriver = class {
 	async withTransaction(operation, options) {
 		const pendingNotifications = [];
 		const result = await this.delegate.db.transaction(async (tx) => {
-			let userId = this.user?.uid;
-			if (!userId) {
+			let uid = this.user?.uid;
+			if (!uid) {
 				logger.warn("[DataDriver] User ID (uid) is missing for authenticated delegate. Using 'anonymous'. User object", { detail: this.user });
-				userId = "anonymous";
+				uid = "anonymous";
 			}
 			const userRoles = this.user?.roles ?? [];
 			if (!this.user?.roles) logger.warn("[DataDriver] User roles are missing for authenticated delegate. Using empty array. User object", { detail: this.user });
 			await applyAuthContext(tx, {
-				userId,
+				uid,
 				roles: userRoles
 			}, this.delegate.rlsUserRole);
 			const txEntityService = new DataService(tx, this.delegate.registry);
@@ -9153,7 +9212,7 @@ var AuthenticatedPostgresBackendDriver = class {
 	*/
 	injectAuthContext(unsubscribe) {
 		const authContext = {
-			userId: this.user?.uid || "anonymous",
+			uid: this.user?.uid || "anonymous",
 			roles: this.user?.roles ?? []
 		};
 		const entries = Array.from(this.delegate.realtimeService.subscriptions.entries());
@@ -10261,6 +10320,267 @@ var CdcListener = class CdcListener {
 	}
 };
 //#endregion
+//#region src/services/channel-history.ts
+/**
+* Ordered, replayable per-channel message history.
+*
+* Broadcast on its own is fire-and-forget to whoever is connected at the
+* instant it is sent: fine for presence and for "someone saved" notifications,
+* not enough for op-based collaborative editing, where a client that blinks
+* out for two seconds has to resync a whole document rather than catch up on
+* the four operations it missed. This adds the missing half — every retained
+* broadcast gets a per-channel sequence number, and a client can ask for
+* everything after the last one it saw.
+*
+* Three decisions worth stating, because each rules out a simpler-looking one:
+*
+*  - **Retention is server-side and opt-in.** A channel is created by whoever
+*    names it, so a client-supplied history depth would let any visitor commit
+*    the backend to unbounded storage. And presence channels — the common case
+*    — must not pay for this: with no rules configured nothing is written, no
+*    table is created, and `broadcast` runs exactly the code it ran before.
+*
+*  - **Sequence numbers come from the database, not from a counter in this
+*    process.** They have to survive a restart and be shared across instances;
+*    an in-memory counter would restart at 1 after a deploy and hand a
+*    reconnecting client a replay from the wrong era, silently.
+*
+*  - **The cursor row outlives the messages it numbered.** Pruning is what
+*    makes retention affordable, but pruning the cursor along with the messages
+*    would restart the sequence and make `sinceSeq` mean something different
+*    before and after — the worst kind of bug, because replay would still
+*    return rows and they would look plausible. Cursors are tiny and are kept
+*    forever; see {@link prune}, which touches only `channel_messages`.
+*/
+/** How many messages a replay returns when the caller does not say. */
+var DEFAULT_REPLAY_LIMIT = 200;
+/**
+* Hard ceiling on one replay, whatever the caller asks for.
+*
+* A reconnecting client names its own `limit`, so this is the only thing
+* standing between a stale `sinceSeq` and a single frame carrying a channel's
+* entire retained history. A client that is further behind than this is told so
+* via `latestSeq` and can decide to resync wholesale instead of paging.
+*/
+var MAX_REPLAY_LIMIT = 1e3;
+/** Minimum gap between two prunes of the same channel. */
+var PRUNE_THROTTLE_MS = 3e4;
+/**
+* Parse a retention TTL into milliseconds.
+*
+* Accepts a raw millisecond count or a short duration string (`"30s"`, `"15m"`,
+* `"24h"`, `"7d"`). Returns undefined for anything unparseable, which the
+* caller treats as "no TTL" — a misspelt duration must not silently become an
+* aggressive one.
+*/
+function parseTtlMs(ttl) {
+	if (ttl === void 0 || ttl === null) return void 0;
+	if (typeof ttl === "number") return Number.isFinite(ttl) && ttl > 0 ? ttl : void 0;
+	const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/i.exec(ttl);
+	if (!match) {
+		logger.warn(`⚠️ [ChannelHistory] Ignoring unparseable retention ttl "${ttl}" — expected e.g. "30s", "15m", "24h", "7d".`);
+		return;
+	}
+	const value = parseFloat(match[1]);
+	const unit = match[2].toLowerCase();
+	const ms = value * (unit === "ms" ? 1 : unit === "s" ? 1e3 : unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5);
+	return ms > 0 ? ms : void 0;
+}
+/**
+* Whether `channel` is covered by `rule`.
+*
+* Exact match, or a trailing `*` acting as a prefix. Not a general glob: this
+* decides what reaches disk, and a pattern language whose reach is not obvious
+* at a glance is the wrong tool for that job.
+*/
+function channelMatchesRule(channel, rule) {
+	const pattern = rule.match;
+	if (pattern === "*") return true;
+	if (pattern.endsWith("*")) return channel.startsWith(pattern.slice(0, -1));
+	return channel === pattern;
+}
+/**
+* Persistence and replay for retained channels.
+*
+* Inert unless constructed with at least one rule: {@link enabled} is false,
+* {@link ensureTables} does nothing, and {@link retentionFor} answers undefined
+* for every channel, so the realtime service never reaches the SQL below.
+*/
+var ChannelHistoryStore = class {
+	db;
+	rules;
+	/** Resolved rule per channel name, so the match runs once per channel. */
+	resolved = /* @__PURE__ */ new Map();
+	/** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+	lastPruned = /* @__PURE__ */ new Map();
+	tablesReady = false;
+	constructor(db, rules = []) {
+		this.db = db;
+		this.rules = rules.filter((rule) => {
+			if (!rule?.match) {
+				logger.warn("⚠️ [ChannelHistory] Ignoring a retention rule with no `match`.");
+				return false;
+			}
+			if (!(rule.limit !== void 0 || rule.ttl !== void 0)) {
+				logger.warn(`⚠️ [ChannelHistory] Retention rule "${rule.match}" sets neither \`limit\` nor \`ttl\` — ignoring it, as it would retain forever.`);
+				return false;
+			}
+			return true;
+		});
+	}
+	/** Whether any channel retains anything at all. */
+	get enabled() {
+		return this.rules.length > 0;
+	}
+	/**
+	* The retention that applies to `channel`, or undefined when none does.
+	*
+	* First matching rule wins, so callers order them most-specific first.
+	*/
+	retentionFor(channel) {
+		if (!this.enabled || !channel) return void 0;
+		const cached = this.resolved.get(channel);
+		if (cached !== void 0) return cached ?? void 0;
+		const rule = this.rules.find((r) => channelMatchesRule(channel, r));
+		const resolved = rule ? {
+			limit: rule.limit,
+			ttlMs: parseTtlMs(rule.ttl)
+		} : null;
+		this.resolved.set(channel, resolved);
+		return resolved ?? void 0;
+	}
+	/**
+	* Create the history tables. Idempotent, and a no-op when no rule is set —
+	* a deployment that never retains anything gets no schema for it.
+	*/
+	async ensureTables() {
+		if (!this.enabled || 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_messages (
+                channel TEXT NOT NULL,
+                seq BIGINT NOT NULL,
+                event TEXT NOT NULL,
+                payload JSONB,
+                sender_id TEXT,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                PRIMARY KEY (channel, seq)
+            )
+        `);
+		await this.db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_channel_messages_created
+            ON rebase.channel_messages (created_at)
+        `);
+		await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_cursors (
+                channel TEXT PRIMARY KEY,
+                last_seq BIGINT NOT NULL
+            )
+        `);
+		this.tablesReady = true;
+		logger.info(`✅ [ChannelHistory] Retained channels ready (${this.rules.length} rule(s)).`);
+	}
+	/**
+	* Append a broadcast and return the sequence number it was given.
+	*
+	* The sequence is allocated by the same statement that stores the message,
+	* so a crash between the two is not a possibility. `ON CONFLICT DO UPDATE`
+	* takes a row lock on the channel's cursor, which is what makes concurrent
+	* broadcasts to one channel line up in a single order — and what keeps
+	* different channels from contending with each other at all.
+	*/
+	async append(channel, event, payload, senderId) {
+		const row = (await this.db.execute(sql`
+            WITH next AS (
+                INSERT INTO rebase.channel_cursors (channel, last_seq)
+                VALUES (${channel}, 1)
+                ON CONFLICT (channel)
+                DO UPDATE SET last_seq = rebase.channel_cursors.last_seq + 1
+                RETURNING last_seq
+            )
+            INSERT INTO rebase.channel_messages (channel, seq, event, payload, sender_id)
+            SELECT ${channel}, next.last_seq, ${event}, ${JSON.stringify(payload ?? null)}::jsonb, ${senderId ?? null}
+            FROM next
+            RETURNING seq, created_at
+        `)).rows[0];
+		if (!row) throw new Error(`Failed to append to channel history for "${channel}"`);
+		return {
+			seq: Number(row.seq),
+			at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+		};
+	}
+	/**
+	* Everything retained for `channel` after `sinceSeq`, oldest first.
+	*
+	* `latestSeq` is reported whether or not the messages were capped, so a
+	* client that is further behind than one page can tell.
+	*/
+	async replay(channel, sinceSeq = 0, limit = DEFAULT_REPLAY_LIMIT) {
+		const capped = Math.max(1, Math.min(Math.floor(limit) || DEFAULT_REPLAY_LIMIT, MAX_REPLAY_LIMIT));
+		const after = Number.isFinite(sinceSeq) && sinceSeq > 0 ? Math.floor(sinceSeq) : 0;
+		const messages = (await this.db.execute(sql`
+            SELECT seq, event, payload, sender_id, created_at
+            FROM rebase.channel_messages
+            WHERE channel = ${channel} AND seq > ${after}
+            ORDER BY seq ASC
+            LIMIT ${capped}
+        `)).rows.map((row) => ({
+			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)
+		}));
+		const cursorRow = (await this.db.execute(sql`
+            SELECT last_seq FROM rebase.channel_cursors WHERE channel = ${channel}
+        `)).rows[0];
+		return {
+			messages,
+			latestSeq: cursorRow ? Number(cursorRow.last_seq) : 0
+		};
+	}
+	/**
+	* Enforce a channel's retention bounds.
+	*
+	* Throttled per channel, so a burst of operations prunes once rather than
+	* once per message — the cost then tracks elapsed time instead of write
+	* volume, which is what makes retention affordable on a hot channel.
+	*/
+	async prune(channel, retention) {
+		const now = Date.now();
+		if (now - (this.lastPruned.get(channel) ?? 0) < PRUNE_THROTTLE_MS) return 0;
+		this.lastPruned.set(channel, now);
+		let deleted = 0;
+		if (retention.ttlMs !== void 0) {
+			const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND created_at < NOW() - MAKE_INTERVAL(secs => ${retention.ttlMs / 1e3})
+            `);
+			deleted += result.rowCount ?? 0;
+		}
+		if (retention.limit !== void 0 && retention.limit > 0) {
+			const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND seq <= (
+                      SELECT seq FROM rebase.channel_messages
+                      WHERE channel = ${channel}
+                      ORDER BY seq DESC
+                      OFFSET ${Math.floor(retention.limit)} LIMIT 1
+                  )
+            `);
+			deleted += result.rowCount ?? 0;
+		}
+		return deleted;
+	}
+	/** Forget throttle and match caches. Called on shutdown. */
+	clear() {
+		this.resolved.clear();
+		this.lastPruned.clear();
+	}
+};
+//#endregion
 //#region src/services/realtimeService.ts
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 var PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -10276,6 +10596,26 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 	clients = /* @__PURE__ */ new Map();
 	channels = /* @__PURE__ */ new Map();
 	presence = /* @__PURE__ */ new Map();
+	/**
+	* Ordered, replayable history for channels that opt into it.
+	*
+	* Undefined until {@link configureChannelHistory} is called, and inert even
+	* then unless retention rules were supplied — so presence and ephemeral
+	* notification channels never touch it. See `channel-history.ts`.
+	*/
+	channelHistory;
+	/**
+	* One promise chain per retained channel, so that assigning a sequence
+	* number and fanning the message out happen in the same order for every
+	* message on that channel.
+	*
+	* Without it, two concurrent broadcasts can be numbered 4 and 5 by the
+	* database and still reach subscribers as 5 then 4 — live order and replay
+	* order would disagree, which is exactly the divergence sequence numbers
+	* are supposed to rule out. Keyed by channel, so unrelated channels never
+	* wait on each other.
+	*/
+	channelSendQueues = /* @__PURE__ */ new Map();
 	presenceInterval;
 	static PRESENCE_TIMEOUT_MS = 3e4;
 	dataService;
@@ -10452,6 +10792,9 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			case "broadcast":
 				this.broadcastToChannel(clientId, payload?.channel, payload?.event, payload?.payload);
 				break;
+			case "channel_history":
+				await this.handleChannelHistoryRequest(clientId, payload?.channel, payload?.sinceSeq, payload?.limit);
+				break;
 			case "presence_track":
 				this.joinChannel(clientId, payload?.channel);
 				this.trackPresence(clientId, payload?.channel, payload?.state ?? {});
@@ -10662,12 +11005,12 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		if (this.driver) {
 			const collection = this.registry.getCollectionByPath(notifyPath);
 			const activeAuth = authContext || {
-				userId: "anon",
+				uid: "anon",
 				roles: ["anon"]
 			};
 			return await this.db.transaction(async (tx) => {
 				await applyAuthContext(tx, {
-					userId: activeAuth.userId,
+					uid: activeAuth.uid,
 					roles: activeAuth.roles
 				}, this.rlsUserRole);
 				const txEntityService = new DataService(tx, this.registry);
@@ -10699,7 +11042,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 				if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
 					const contextForCallback = {
 						user: {
-							uid: activeAuth.userId,
+							uid: activeAuth.uid,
 							roles: activeAuth.roles
 						},
 						driver: this.driver,
@@ -10791,12 +11134,12 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		if (this.driver) {
 			const collection = this.registry.getCollectionByPath(notifyPath);
 			const activeAuth = authContext || {
-				userId: "anon",
+				uid: "anon",
 				roles: ["anon"]
 			};
 			return await this.db.transaction(async (tx) => {
 				await applyAuthContext(tx, {
-					userId: activeAuth.userId,
+					uid: activeAuth.uid,
 					roles: activeAuth.roles
 				}, this.rlsUserRole);
 				let processedEntity = await new DataService(tx, this.registry).fetchOne(notifyPath, id, collection?.databaseId);
@@ -10812,7 +11155,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 					if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
 						const contextForCallback = {
 							user: {
-								uid: activeAuth.userId,
+								uid: activeAuth.uid,
 								roles: activeAuth.roles
 							},
 							driver: this.driver,
@@ -10938,15 +11281,67 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		}
 		this.removePresence(clientId, channel);
 	}
-	/** Broadcast a message to all clients in a channel except sender */
+	/**
+	* Broadcast a message to all clients in a channel except the sender.
+	*
+	* On a channel with no retention rule this is what it always was: a
+	* synchronous fan-out to whoever is connected, with no sequence number, no
+	* SQL and no await — the body below runs to completion before returning.
+	*
+	* On a retained channel the message is durably numbered first and only then
+	* delivered, through a per-channel queue so that delivery order matches
+	* sequence order. That ordering is the whole point: a client that catches up
+	* with `sinceSeq` has to arrive at the same state as one that never
+	* disconnected.
+	*/
 	broadcastToChannel(clientId, channel, event, payload) {
+		const retention = this.channelHistory?.retentionFor(channel);
+		if (!retention) {
+			this.fanOutBroadcast(clientId, channel, event, payload);
+			return;
+		}
+		const next = (this.channelSendQueues.get(channel) ?? Promise.resolve()).catch(() => {}).then(() => this.persistAndFanOut(clientId, channel, event, payload, retention));
+		this.channelSendQueues.set(channel, next);
+		next.finally(() => {
+			if (this.channelSendQueues.get(channel) === next) this.channelSendQueues.delete(channel);
+		});
+	}
+	/**
+	* Number a broadcast, store it, then deliver it.
+	*
+	* A message that cannot be stored is **not** delivered. Delivering it would
+	* put it in front of live subscribers while leaving it absent from every
+	* future replay — the two views of the channel would disagree permanently,
+	* and no later message could repair the gap. Failing loudly to the sender
+	* instead lets it retry, which for an operation stream is the only outcome
+	* that keeps clients convergent.
+	*/
+	async persistAndFanOut(clientId, channel, event, payload, retention) {
+		let seq;
+		try {
+			({seq} = await this.channelHistory.append(channel, event, payload, clientId));
+		} catch (error) {
+			logger.error(`❌ [ChannelHistory] Could not persist broadcast on "${channel}" — message dropped`, { error });
+			this.sendError(clientId, `Could not persist broadcast on retained channel "${channel}"`, void 0, "CHANNEL_HISTORY_WRITE_FAILED");
+			return;
+		}
+		this.fanOutBroadcast(clientId, channel, event, payload, seq);
+		try {
+			await this.channelHistory.prune(channel, retention);
+		} catch (error) {
+			logger.warn(`⚠️ [ChannelHistory] Prune failed for "${channel}"`, { error });
+		}
+	}
+	/** Deliver a broadcast frame to every member of a channel but the sender. */
+	fanOutBroadcast(clientId, channel, event, payload, seq) {
 		const members = this.channels.get(channel);
 		if (!members) return;
 		const message = JSON.stringify({
 			type: "broadcast",
 			channel,
 			event,
-			payload
+			payload,
+			...seq !== void 0 ? { seq } : {}
 		});
 		for (const memberId of members) {
 			if (memberId === clientId) continue;
@@ -10954,6 +11349,55 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 			if (ws && ws.readyState === WebSocket.OPEN) ws.send(message);
 		}
 	}
+	/**
+	* 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
+	* inert, no schema is created, and broadcast keeps its original
+	* fire-and-forget path.
+	*/
+	async configureChannelHistory(rules) {
+		this.channelHistory = new ChannelHistoryStore(this.db, rules ?? []);
+		if (!this.channelHistory.enabled) return;
+		await this.channelHistory.ensureTables();
+	}
+	/** Whether any channel is configured to retain messages. */
+	isChannelHistoryEnabled() {
+		return this.channelHistory?.enabled ?? false;
+	}
+	/**
+	* Answer a client's catch-up request.
+	*
+	* A channel with no retention rule is answered with `retained: false`
+	* rather than an empty list, so the client can tell "you missed nothing"
+	* apart from "this channel never keeps anything" — the second means its
+	* reconnect strategy has to be a full resync, and silence would leave it
+	* guessing.
+	*/
+	async handleChannelHistoryRequest(clientId, channel, sinceSeq, limit) {
+		if (!channel) return;
+		if (!this.channelHistory?.retentionFor(channel)) {
+			this.sendChannelHistory(clientId, channel, [], false);
+			return;
+		}
+		try {
+			const { messages, latestSeq } = await this.channelHistory.replay(channel, sinceSeq, limit);
+			this.sendChannelHistory(clientId, channel, messages, true, latestSeq);
+		} catch (error) {
+			logger.error(`❌ [ChannelHistory] Replay failed for "${channel}"`, { error });
+			this.sendError(clientId, `Could not replay history for channel "${channel}"`, void 0, "CHANNEL_HISTORY_READ_FAILED");
+		}
+	}
+	sendChannelHistory(clientId, channel, messages, retained, latestSeq) {
+		const ws = this.clients.get(clientId);
+		if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({
+			type: "channel_history",
+			channel,
+			messages,
+			retained,
+			...latestSeq !== void 0 ? { latestSeq } : {}
+		}));
+	}
 	/** Track presence in a channel */
 	trackPresence(clientId, channel, state) {
 		if (!this.presence.has(channel)) this.presence.set(channel, /* @__PURE__ */ new Map());
@@ -11034,6 +11478,9 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		this.subscriptionCallbacks.clear();
 		this.channels.clear();
 		this.presence.clear();
+		await Promise.allSettled([...this.channelSendQueues.values()]);
+		this.channelSendQueues.clear();
+		this.channelHistory?.clear();
 		if (this.presenceInterval) {
 			clearInterval(this.presenceInterval);
 			this.presenceInterval = void 0;
@@ -11375,20 +11822,20 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 					if (authAdapter) try {
 						const adapterUser = authAdapter.verifyToken ? await authAdapter.verifyToken(token) : await authAdapter.verifyRequest(new Request("http://localhost/_ws_auth", { headers: { Authorization: `Bearer ${token}` } }));
 						if (adapterUser) verifiedUser = {
-							userId: adapterUser.uid,
+							uid: adapterUser.uid,
 							roles: adapterUser.roles,
 							isAdmin: adapterUser.isAdmin
 						};
 					} catch {}
 					else if (authConfig?.serviceKey && safeCompare(token, authConfig.serviceKey)) verifiedUser = {
-						userId: "service",
+						uid: "service",
 						roles: ["admin"],
 						isAdmin: true
 					};
 					else {
 						const jwtPayload = extractUserFromToken(token);
 						if (jwtPayload) verifiedUser = {
-							userId: jwtPayload.userId,
+							uid: jwtPayload.uid,
 							roles: jwtPayload.roles ?? [],
 							isAdmin: (jwtPayload.roles ?? []).some((r) => r === "admin")
 						};
@@ -11404,11 +11851,11 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 							type: "AUTH_SUCCESS",
 							requestId,
 							payload: {
-								userId: verifiedUser.userId,
+								uid: verifiedUser.uid,
 								roles: verifiedUser.roles
 							}
 						}));
-						wsDebug(`🔐 [WebSocket Server] Client ${clientId} authenticated as ${verifiedUser.userId}`);
+						wsDebug(`🔐 [WebSocket Server] Client ${clientId} authenticated as ${verifiedUser.uid}`);
 					} else {
 						wsDebug(`[WS] replying AUTH_ERROR for requestId ${requestId} (invalid token)`);
 						sendError("AUTH_ERROR", "INVALID_TOKEN", "Invalid or expired token");
@@ -11446,7 +11893,7 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 					const session = clientSessions.get(clientId);
 					if (typeof driver.withAuth === "function") try {
 						const userForAuth = session?.user ? {
-							uid: session.user.userId,
+							uid: session.user.uid,
 							displayName: null,
 							email: null,
 							photoURL: null,
@@ -11580,7 +12027,7 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 									sql: typeof sql === "string" ? sql.substring(0, 500) : sql,
 									options,
 									resultRows: Array.isArray(result) ? result.length : "unknown",
-									userId: auditSession?.user?.userId ?? "unknown",
+									uid: auditSession?.user?.uid ?? "unknown",
 									roles: auditSession?.user?.roles ?? [],
 									isAdmin: auditSession?.user?.isAdmin ?? false
 								}));
@@ -11625,6 +12072,21 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 							ws.send(JSON.stringify(response));
 						}
 						break;
+					case "FETCH_APPLICATION_ROLES":
+						{
+							wsDebug("👤 [WebSocket Server] Processing FETCH_APPLICATION_ROLES request");
+							const admin = (await getScopedDelegate()).admin;
+							let roles = [];
+							if (isSQLAdmin(admin) && admin.fetchApplicationRoles) roles = await admin.fetchApplicationRoles();
+							wsDebug(`👤 [WebSocket Server] Fetched ${roles.length} application roles.`);
+							const response = {
+								type: "FETCH_APPLICATION_ROLES_SUCCESS",
+								payload: { roles },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
 					case "FETCH_CURRENT_DATABASE":
 						{
 							wsDebug("📚 [WebSocket Server] Processing FETCH_CURRENT_DATABASE request");
@@ -11731,14 +12193,15 @@ function createPostgresWebSocket(server, realtimeService, driver, authConfig, au
 					case "broadcast":
 					case "presence_track":
 					case "presence_untrack":
-					case "presence_state": {
+					case "presence_state":
+					case "channel_history": {
 						wsDebug("🔄 [WebSocket Server] Routing realtime message to RealtimeService:", type);
 						const session = clientSessions.get(clientId);
 						const authContext = session?.user ? {
-							userId: session.user.userId,
+							uid: session.user.uid,
 							roles: session.user.roles ?? []
 						} : {
-							userId: "anon",
+							uid: "anon",
 							roles: ["anon"]
 						};
 						await realtimeService.handleClientMessage(clientId, {
@@ -22152,6 +22615,20 @@ function patchPgArrayNullSafety(tables) {
 	if (patchedCount > 0) logger.debug(`[PgArray] Patched ${patchedCount} array column(s) for null-safety`);
 }
 //#endregion
+//#region src/schema/introspect-db-naming.ts
+/**
+* Naming helpers shared by the introspection modules. These live apart from
+* `introspect-db-logic.ts` because the inference pass needs them too, and
+* importing them from there would close a cycle back through this module.
+*/
+/**
+* Convert a snake_case name to a human-readable Title Case label.
+* e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
+*/
+function humanize(snakeName) {
+	return snakeName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+//#endregion
 //#region src/schema/introspect-db-logic.ts
 var IRREGULAR_SINGULARS = {
 	people: "person",
@@ -22211,13 +22688,6 @@ function singularize(word) {
 	if (lower.endsWith("s") && !lower.endsWith("ss") && !lower.endsWith("us") && !lower.endsWith("is")) return word.slice(0, -1);
 	return word;
 }
-/**
-* Convert a snake_case name to a human-readable Title Case label.
-* e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
-*/
-function humanize(snakeName) {
-	return snakeName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-}
 function getIconForTable(tableName) {
 	const table = tableName.toLowerCase();
 	if (table.includes("user") || table.includes("account") || table.includes("member") || table.includes("customer") || table.includes("client") || table.includes("patient")) return "Users";
@@ -22738,6 +23208,11 @@ function createPostgresBootstrapper(pgConfig) {
 			} catch (err) {
 				logger.warn("⚠️ Could not initialize branch metadata table", { error: err });
 			}
+			try {
+				await realtimeService.configureChannelHistory(pgConfig.realtime?.channels);
+			} catch (err) {
+				logger.warn("⚠️ Could not initialize channel history tables — retained channels will not replay", { error: err });
+			}
 			const directUrl = process.env.DATABASE_DIRECT_URL || pgConfig.connectionString;
 			const validModes = new Set([
 				"auto",