@rebasepro/server-postgres 0.9.1-canary.ff338b5 → 0.10.1-canary.18115ba

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";
@@ -353,7 +353,7 @@ function getDeclaredSubcollections(collection) {
 /**
 * The id a request without a logged-in user reports as `auth.uid()`.
 *
-* A user-context request always sets `app.user_id`: blank would read back as
+* A user-context request always sets `app.uid`: blank would read back as
 * `NULL`, and `NULL` is how the trusted server context is recognised, so an
 * anonymous visitor would be promoted to server privileges. The driver
 * therefore substitutes this sentinel at the single chokepoint where the GUC
@@ -2134,7 +2134,7 @@ function getSubcollections(collection) {
 * It handles:
 * - `field = 'literal'`
 * - `field != 'literal'`
-* - `field = current_setting('app.user_id')`
+* - `field = current_setting('app.uid')` (or the legacy `app.user_id`)
 * - `A AND B`, `A OR B` — only where the keyword is at the top level
 * - `true`
 * - `IN (...)` (as optimistic true)
@@ -2335,7 +2335,7 @@ function findAnonymousGrants(expr) {
 	return found;
 }
 function parseOperand(str) {
-	if (/current_setting\s*\(\s*'app\.user_id'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) return policy.authUid();
+	if (/current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) return policy.authUid();
 	const stringMatch = str.match(/^'(.+)'$/);
 	if (stringMatch) return policy.literal(stringMatch[1]);
 	if (/^\w+$/.test(str)) return policy.field(str);
@@ -8182,7 +8182,7 @@ async function ensureAppRole(run, schemas) {
 * SECURITY: this function is only ever called on the **user** path (the server
 * context uses the base/owner driver and never calls it). The default policies
 * treat `auth.uid() IS NULL` as the trusted server context, and `auth.uid()`
-* is `NULLIF(current_setting('app.user_id'), '')` — so an EMPTY user id would
+* is `NULLIF(current_setting('app.uid'), '')` — so an EMPTY user id would
 * be read as NULL and silently escalate a user request to server privileges.
 * Coerce empty/blank ids to `ANONYMOUS_USER_ID` here, at the single chokepoint,
 * rather than trusting every caller (e.g. realtime subscription auth) to do it.
@@ -8190,14 +8190,15 @@ 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.uid', ${uid}, 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)
     `);
@@ -8343,6 +8344,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),
@@ -8996,6 +8998,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;
 	}
@@ -9137,15 +9178,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);
@@ -9172,7 +9213,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());
@@ -9308,27 +9349,65 @@ 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(),
-		userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+		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.userId, table.userAgent, table.ipAddress) }));
+	}, (table) => ({ sessionIdx: index("idx_refresh_tokens_session").on(table.sessionId) }));
 	/**
 	* Password reset tokens for forgot password flow
 	*/
 	const passwordResetTokens = tableCreator("password_reset_tokens", {
 		id: uuid("id").defaultRandom().primaryKey(),
-		userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+		uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
 		tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
 		expiresAt: timestamp("expires_at").notNull(),
 		usedAt: timestamp("used_at"),
@@ -9347,7 +9426,7 @@ function createAuthSchema(usersSchemaName = "rebase") {
 	*/
 	const userIdentities = tableCreator("user_identities", {
 		id: uuid("id").defaultRandom().primaryKey(),
-		userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+		uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
 		provider: varchar("provider", { length: 50 }).notNull(),
 		providerId: varchar("provider_id", { length: 255 }).notNull(),
 		profileData: jsonb("profile_data"),
@@ -9359,7 +9438,7 @@ function createAuthSchema(usersSchemaName = "rebase") {
 	*/
 	const mfaFactors = tableCreator("mfa_factors", {
 		id: uuid("id").defaultRandom().primaryKey(),
-		userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+		uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
 		factorType: varchar("factor_type", { length: 20 }).notNull(),
 		secretEncrypted: varchar("secret_encrypted", { length: 500 }).notNull(),
 		friendlyName: varchar("friendly_name", { length: 255 }),
@@ -9385,14 +9464,14 @@ function createAuthSchema(usersSchemaName = "rebase") {
 		}),
 		recoveryCodes: tableCreator("recovery_codes", {
 			id: uuid("id").defaultRandom().primaryKey(),
-			userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+			uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
 			codeHash: varchar("code_hash", { length: 255 }).notNull(),
 			usedAt: timestamp("used_at"),
 			createdAt: timestamp("created_at").defaultNow().notNull()
 		}),
 		magicLinkTokens: tableCreator("magic_link_tokens", {
 			id: uuid("id").defaultRandom().primaryKey(),
-			userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+			uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
 			tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
 			expiresAt: timestamp("expires_at").notNull(),
 			usedAt: timestamp("used_at"),
@@ -9420,20 +9499,20 @@ var usersRelations = relations(users, ({ many }) => ({
 	magicLinkTokens: many(magicLinkTokens)
 }));
 var refreshTokensRelations = relations(refreshTokens, ({ one }) => ({ user: one(users, {
-	fields: [refreshTokens.userId],
+	fields: [refreshTokens.uid],
 	references: [users.id]
 }) }));
 var passwordResetTokensRelations = relations(passwordResetTokens, ({ one }) => ({ user: one(users, {
-	fields: [passwordResetTokens.userId],
+	fields: [passwordResetTokens.uid],
 	references: [users.id]
 }) }));
 var userIdentitiesRelations = relations(userIdentities, ({ one }) => ({ user: one(users, {
-	fields: [userIdentities.userId],
+	fields: [userIdentities.uid],
 	references: [users.id]
 }) }));
 var mfaFactorsRelations = relations(mfaFactors, ({ one, many }) => ({
 	user: one(users, {
-		fields: [mfaFactors.userId],
+		fields: [mfaFactors.uid],
 		references: [users.id]
 	}),
 	challenges: many(mfaChallenges)
@@ -9443,11 +9522,11 @@ var mfaChallengesRelations = relations(mfaChallenges, ({ one }) => ({ factor: on
 	references: [mfaFactors.id]
 }) }));
 var recoveryCodesRelations = relations(recoveryCodes, ({ one }) => ({ user: one(users, {
-	fields: [recoveryCodes.userId],
+	fields: [recoveryCodes.uid],
 	references: [users.id]
 }) }));
 var magicLinkTokensRelations = relations(magicLinkTokens, ({ one }) => ({ user: one(users, {
-	fields: [magicLinkTokens.userId],
+	fields: [magicLinkTokens.uid],
 	references: [users.id]
 }) }));
 //#endregion
@@ -10280,6 +10359,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";
@@ -10295,6 +10635,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;
@@ -10471,6 +10831,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 ?? {});
@@ -10681,12 +11044,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);
@@ -10718,7 +11081,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,
@@ -10810,12 +11173,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);
@@ -10831,7 +11194,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,
@@ -10957,15 +11320,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;
@@ -10973,6 +11388,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());
@@ -11053,6 +11517,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;
@@ -11394,20 +11861,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")
 						};
@@ -11423,11 +11890,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");
@@ -11465,7 +11932,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,
@@ -11599,7 +12066,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
 								}));
@@ -11644,6 +12111,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");
@@ -11750,14 +12232,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, {
@@ -20708,14 +21191,71 @@ 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`
+            CREATE OR REPLACE FUNCTION ${sql.raw(`"${authSchema}"`)}.sync_uid_user_id() RETURNS trigger AS $$
+            BEGIN
+                IF NEW.uid IS NULL AND NEW.user_id IS NOT NULL THEN
+                    NEW.uid := NEW.user_id;
+                ELSIF NEW.user_id IS NULL AND NEW.uid IS NOT NULL THEN
+                    NEW.user_id := NEW.uid;
+                END IF;
+                RETURN NEW;
+            END $$ LANGUAGE plpgsql
+        `);
+		for (const authTable of [
+			"user_identities",
+			"refresh_tokens",
+			"password_reset_tokens",
+			"magic_link_tokens",
+			"mfa_factors",
+			"recovery_codes"
+		]) {
+			const qualified = `"${authSchema}"."${authTable}"`;
+			await db.execute(sql`
+                DO $$
+                DECLARE
+                    has_legacy boolean;
+                    has_uid    boolean;
+                BEGIN
+                    SELECT
+                        bool_or(column_name = 'user_id'),
+                        bool_or(column_name = 'uid')
+                    INTO has_legacy, has_uid
+                    FROM information_schema.columns
+                    WHERE table_schema = ${sql.raw(`'${authSchema}'`)}
+                      AND table_name = ${sql.raw(`'${authTable}'`)};
+
+                    -- Table absent, or already uid-only (a fresh install, or
+                    -- phase 2 already run): nothing to do.
+                    IF has_legacy IS NOT TRUE THEN
+                        RETURN;
+                    END IF;
+
+                    IF has_uid IS NOT TRUE THEN
+                        EXECUTE ${sql.raw(`'ALTER TABLE ${qualified} ADD COLUMN uid ${userIdType} REFERENCES ${usersTableName}(id) ON DELETE CASCADE'`)};
+                        EXECUTE ${sql.raw(`'UPDATE ${qualified} SET uid = user_id WHERE uid IS NULL'`)};
+                        EXECUTE ${sql.raw(`'CREATE INDEX IF NOT EXISTS idx_${authTable}_uid ON ${qualified}(uid)'`)};
+                    END IF;
+
+                    -- New code inserts uid and never user_id, so the legacy
+                    -- column can no longer be NOT NULL. The trigger below
+                    -- backfills it, but the constraint is checked first.
+                    EXECUTE ${sql.raw(`'ALTER TABLE ${qualified} ALTER COLUMN user_id DROP NOT NULL'`)};
+
+                    EXECUTE ${sql.raw(`'DROP TRIGGER IF EXISTS sync_uid_user_id ON ${qualified}'`)};
+                    EXECUTE ${sql.raw(`'CREATE TRIGGER sync_uid_user_id BEFORE INSERT OR UPDATE ON ${qualified} FOR EACH ROW EXECUTE FUNCTION "${authSchema}".sync_uid_user_id()'`)};
+                END $$
+            `);
+		}
+		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(userIdentitiesTable)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 provider TEXT NOT NULL,
                 provider_id TEXT NOT NULL,
                 profile_data JSONB,
@@ -20726,18 +21266,21 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_user_identities_user 
-            ON ${sql.raw(userIdentitiesTable)}(user_id)
+            ON ${sql.raw(userIdentitiesTable)}(uid)
         `);
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(refreshTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                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 (user_id, user_agent, ip_address)
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
             )
         `);
 		await db.execute(sql`
@@ -20746,12 +21289,12 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user 
-            ON ${sql.raw(refreshTokensTableName)}(user_id)
+            ON ${sql.raw(refreshTokensTableName)}(uid)
         `);
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(passwordResetTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
@@ -20764,13 +21307,13 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_password_reset_tokens_user 
-            ON ${sql.raw(passwordResetTokensTableName)}(user_id)
+            ON ${sql.raw(passwordResetTokensTableName)}(uid)
         `);
 		const magicLinkTokensTableName = `"${authSchema}"."magic_link_tokens"`;
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(magicLinkTokensTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 token_hash TEXT NOT NULL UNIQUE,
                 expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
@@ -20783,7 +21326,7 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_magic_link_tokens_user 
-            ON ${sql.raw(magicLinkTokensTableName)}(user_id)
+            ON ${sql.raw(magicLinkTokensTableName)}(uid)
         `);
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(appConfigTableName)} (
@@ -20797,7 +21340,10 @@ async function ensureAuthTablesExist(db, collection) {
 			await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext('rebase_auth_functions_init'))`);
 			await tx.execute(sql`
                 CREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$
-                    SELECT NULLIF(current_setting('app.user_id', true), '');
+                    SELECT COALESCE(
+                        NULLIF(current_setting('app.uid', true), ''),
+                        NULLIF(current_setting('app.user_id', true), '')
+                    );
                 $$ LANGUAGE sql STABLE
             `);
 			await tx.execute(sql`
@@ -20824,12 +21370,54 @@ 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`
                 ALTER TABLE ${sql.raw(usersTableName)}
                 ADD COLUMN IF NOT EXISTS ${sql.raw(columnDef)}
             `);
+		try {
+			const found = (await db.execute(sql`
+                SELECT table_schema, table_name
+                FROM information_schema.tables
+                WHERE table_name = 'refresh_tokens'
+            `)).rows;
+			logger.info(`🔍 refresh_tokens reconcile: found ${found.length} table(s): ${found.map((r) => `"${r.table_schema}"."${r.table_name}"`).join(", ") || "(none)"}`);
+			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 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`
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_id = gen_random_uuid()::text
+                        WHERE session_id IS NULL
+                    `);
+					await db.execute(sql`
+                        UPDATE ${sql.raw(qualified)}
+                        SET session_started_at = COALESCE(created_at, NOW())
+                        WHERE session_started_at IS NULL
+                    `);
+					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 session migration skipped: ${migrationError instanceof Error ? migrationError.message : String(migrationError)}`);
+		}
 		try {
 			if ((await db.execute(sql`
                 SELECT EXISTS (
@@ -20860,7 +21448,7 @@ async function ensureAuthTablesExist(db, collection) {
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(mfaFactorsTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 factor_type TEXT NOT NULL DEFAULT 'totp',
                 secret_encrypted TEXT NOT NULL,
                 friendly_name TEXT,
@@ -20871,7 +21459,7 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_mfa_factors_user
-            ON ${sql.raw(mfaFactorsTableName)}(user_id)
+            ON ${sql.raw(mfaFactorsTableName)}(uid)
         `);
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(mfaChallengesTableName)} (
@@ -20890,7 +21478,7 @@ async function ensureAuthTablesExist(db, collection) {
 		await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(recoveryCodesTableName)} (
                 id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                uid ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
                 code_hash TEXT NOT NULL,
                 used_at TIMESTAMP WITH TIME ZONE,
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
@@ -20898,7 +21486,7 @@ async function ensureAuthTablesExist(db, collection) {
         `);
 		await db.execute(sql`
             CREATE INDEX IF NOT EXISTS idx_recovery_codes_user
-            ON ${sql.raw(recoveryCodesTableName)}(user_id)
+            ON ${sql.raw(recoveryCodesTableName)}(uid)
         `);
 		try {
 			const authTablePairs = [
@@ -20979,7 +21567,7 @@ var UserService = class {
 	* Run a privileged auth write with an explicitly cleared RLS context.
 	*
 	* The auth services run on the base/owner connection, which by design
-	* carries a NULL `app.user_id` so the `auth.uid() IS NULL` server-escape
+	* carries a NULL `app.uid` so the `auth.uid() IS NULL` server-escape
 	* in the default policies applies. That NULL is normally guaranteed by
 	* `set_config(..., is_local = true)` resetting at transaction end — but a
 	* GUC that survives on a pooled connection (or a connection role that
@@ -20993,7 +21581,8 @@ var UserService = class {
 	async withServerContext(fn) {
 		return await this.db.transaction(async (tx) => {
 			await tx.execute(sql`
-                SELECT set_config('app.user_id', '', true),
+                SELECT set_config('app.uid', '', true),
+                       set_config('app.user_id', '', true),
                        set_config('app.user_roles', '', true),
                        set_config('app.jwt', '', true)
             `);
@@ -21115,19 +21704,19 @@ var UserService = class {
 	async getUserByIdentity(provider, providerId) {
 		const userIdCol = getColumn(this.usersTable, "id");
 		if (!userIdCol) return null;
-		const result = await this.db.select({ user: this.usersTable }).from(this.usersTable).innerJoin(this.userIdentitiesTable, eq(userIdCol, this.userIdentitiesTable.userId)).where(sql`${this.userIdentitiesTable.provider} = ${provider} AND ${this.userIdentitiesTable.providerId} = ${providerId}`).limit(1);
+		const result = await this.db.select({ user: this.usersTable }).from(this.usersTable).innerJoin(this.userIdentitiesTable, eq(userIdCol, this.userIdentitiesTable.uid)).where(sql`${this.userIdentitiesTable.provider} = ${provider} AND ${this.userIdentitiesTable.providerId} = ${providerId}`).limit(1);
 		if (result.length === 0) return null;
 		return this.mapRowToUser(result[0].user);
 	}
-	async getUserIdentities(userId) {
+	async getUserIdentities(uid) {
 		const schema = getTableConfig(this.userIdentitiesTable).schema || "public";
 		return (await this.db.execute(sql`
-            SELECT id, user_id, provider, provider_id, profile_data, created_at, updated_at
+            SELECT id, uid, provider, provider_id, profile_data, created_at, updated_at
             FROM ${sql.raw(`"${schema}"."user_identities"`)}
-            WHERE user_id = ${userId}
+            WHERE uid = ${uid}
         `)).rows.map((row) => ({
 			id: row.id,
-			userId: row.user_id,
+			uid: row.uid,
 			provider: row.provider,
 			providerId: row.provider_id,
 			profileData: row.profile_data ?? null,
@@ -21135,9 +21724,9 @@ var UserService = class {
 			updatedAt: row.updated_at
 		}));
 	}
-	async linkUserIdentity(userId, provider, providerId, profileData) {
+	async linkUserIdentity(uid, provider, providerId, profileData) {
 		await this.withServerContext(async (db) => db.insert(this.userIdentitiesTable).values({
-			userId,
+			uid,
 			provider,
 			providerId,
 			profileData: profileData || null
@@ -21256,10 +21845,10 @@ var UserService = class {
 	/**
 	* Get roles for a user from database (inline TEXT[] column)
 	*/
-	async getUserRoles(userId) {
+	async getUserRoles(uid) {
 		const usersTableName = this.getQualifiedUsersTableName();
 		const result = await this.db.execute(sql`
-            SELECT roles FROM ${sql.raw(usersTableName)} WHERE id = ${userId}
+            SELECT roles FROM ${sql.raw(usersTableName)} WHERE id = ${uid}
         `);
 		if (result.rows.length === 0) return [];
 		return (result.rows[0].roles ?? []).map((id) => ({
@@ -21273,10 +21862,10 @@ var UserService = class {
 	/**
 	* Get role IDs for a user
 	*/
-	async getUserRoleIds(userId) {
+	async getUserRoleIds(uid) {
 		const usersTableName = this.getQualifiedUsersTableName();
 		const result = await this.db.execute(sql`
-            SELECT roles FROM ${sql.raw(usersTableName)} WHERE id = ${userId}
+            SELECT roles FROM ${sql.raw(usersTableName)} WHERE id = ${uid}
         `);
 		if (result.rows.length === 0) return [];
 		return result.rows[0].roles ?? [];
@@ -21284,98 +21873,172 @@ var UserService = class {
 	/**
 	* Set roles for a user (replaces existing roles)
 	*/
-	async setUserRoles(userId, roleIds) {
+	async setUserRoles(uid, roleIds) {
 		const usersTableName = this.getQualifiedUsersTableName();
 		const rolesArray = `{${roleIds.join(",")}}`;
 		await this.withServerContext(async (db) => db.execute(sql`
             UPDATE ${sql.raw(usersTableName)}
             SET roles = ${rolesArray}::text[], updated_at = NOW()
-            WHERE id = ${userId}
+            WHERE id = ${uid}
         `));
 	}
 	/**
 	* Assign a specific role to new user (appends if not present)
 	*/
-	async assignDefaultRole(userId, roleId) {
+	async assignDefaultRole(uid, roleId) {
 		const usersTableName = this.getQualifiedUsersTableName();
 		await this.withServerContext(async (db) => db.execute(sql`
             UPDATE ${sql.raw(usersTableName)}
             SET roles = array_append(roles, ${roleId}), updated_at = NOW()
-            WHERE id = ${userId} AND NOT (${roleId} = ANY(roles))
+            WHERE id = ${uid} AND NOT (${roleId} = ANY(roles))
         `));
 	}
 	/**
 	* Get user with their roles
 	*/
-	async getUserWithRoles(userId) {
-		const user = await this.getUserById(userId);
+	async getUserWithRoles(uid) {
+		const user = await this.getUserById(uid);
 		if (!user) return null;
 		return {
 			user,
-			roles: await this.getUserRoles(userId)
+			roles: await this.getUserRoles(uid)
 		};
 	}
 };
 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;
-	}
-	async createToken(userId, tokenHash, expiresAt, userAgent, ipAddress) {
-		const safeUserAgent = userAgent || "";
-		const safeIpAddress = ipAddress || "";
-		await this.db.insert(this.refreshTokensTable).values({
-			userId,
-			tokenHash,
-			expiresAt,
-			userAgent: safeUserAgent,
-			ipAddress: safeIpAddress
-		}).onConflictDoUpdate({
-			target: [
-				this.refreshTokensTable.userId,
-				this.refreshTokensTable.userAgent,
-				this.refreshTokensTable.ipAddress
-			],
-			set: {
-				tokenHash,
-				expiresAt
-			}
-		});
+		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 findByHash(tokenHash) {
-		const [token] = await this.db.select({
+	/**
+	* 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]);
+	}
+	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,
-			userId: this.refreshTokensTable.userId,
+			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.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));
 	}
-	async deleteAllForUser(userId) {
-		await this.db.delete(this.refreshTokensTable).where(eq(this.refreshTokensTable.userId, userId));
+	async deleteAllForUser(uid) {
+		await this.db.delete(this.refreshTokensTable).where(eq(this.refreshTokensTable.uid, uid));
 	}
-	async listForUser(userId) {
-		return await this.db.select({
-			id: this.refreshTokensTable.id,
-			userId: this.refreshTokensTable.userId,
-			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.userId, userId)).orderBy(this.refreshTokensTable.createdAt);
+	async listForUser(uid) {
+		return await this.db.select(this.selection()).from(this.refreshTokensTable).where(eq(this.refreshTokensTable.uid, uid)).orderBy(this.refreshTokensTable.createdAt);
 	}
-	async deleteById(id, userId) {
-		await this.db.delete(this.refreshTokensTable).where(sql`${this.refreshTokensTable.id} = ${id} AND ${this.refreshTokensTable.userId} = ${userId}`);
+	async deleteById(id, uid) {
+		await this.db.delete(this.refreshTokensTable).where(sql`${this.refreshTokensTable.id} = ${id} AND ${this.refreshTokensTable.uid} = ${uid}`);
 	}
 };
 /**
@@ -21396,14 +22059,14 @@ var PasswordResetTokenService = class {
 	/**
 	* Create a password reset token
 	*/
-	async createToken(userId, tokenHash, expiresAt) {
+	async createToken(uid, tokenHash, expiresAt) {
 		const tableName = this.getQualifiedPasswordResetTokensTableName();
 		await this.db.execute(sql`
             DELETE FROM ${sql.raw(tableName)} 
-            WHERE user_id = ${userId} AND used_at IS NULL
+            WHERE uid = ${uid} AND used_at IS NULL
         `);
 		await this.db.insert(this.passwordResetTokensTable).values({
-			userId,
+			uid,
 			tokenHash,
 			expiresAt
 		});
@@ -21413,13 +22076,13 @@ var PasswordResetTokenService = class {
 	*/
 	async findValidByHash(tokenHash) {
 		const [token] = await this.db.select({
-			userId: this.passwordResetTokensTable.userId,
+			uid: this.passwordResetTokensTable.uid,
 			expiresAt: this.passwordResetTokensTable.expiresAt
 		}).from(this.passwordResetTokensTable).where(eq(this.passwordResetTokensTable.tokenHash, tokenHash));
 		if (!token) return null;
 		const tableName = this.getQualifiedPasswordResetTokensTableName();
 		const result = await this.db.execute(sql`
-            SELECT user_id, expires_at 
+            SELECT uid, expires_at 
             FROM ${sql.raw(tableName)} 
             WHERE token_hash = ${tokenHash} 
               AND used_at IS NULL 
@@ -21428,7 +22091,7 @@ var PasswordResetTokenService = class {
 		if (result.rows.length === 0) return null;
 		const row = result.rows[0];
 		return {
-			userId: row.user_id,
+			uid: row.uid,
 			expiresAt: new Date(row.expires_at)
 		};
 	}
@@ -21441,8 +22104,8 @@ var PasswordResetTokenService = class {
 	/**
 	* Delete all tokens for a user
 	*/
-	async deleteAllForUser(userId) {
-		await this.db.delete(this.passwordResetTokensTable).where(eq(this.passwordResetTokensTable.userId, userId));
+	async deleteAllForUser(uid) {
+		await this.db.delete(this.passwordResetTokensTable).where(eq(this.passwordResetTokensTable.uid, uid));
 	}
 	/**
 	* Clean up expired tokens
@@ -21470,14 +22133,14 @@ var MagicLinkTokenService = class {
 		const name = getTableName(this.magicLinkTokensTable);
 		return `"${getTableConfig(this.magicLinkTokensTable).schema || "public"}"."${name}"`;
 	}
-	async createToken(userId, tokenHash, expiresAt) {
+	async createToken(uid, tokenHash, expiresAt) {
 		const tableName = this.getQualifiedTableName();
 		await this.db.execute(sql`
             DELETE FROM ${sql.raw(tableName)} 
-            WHERE user_id = ${userId} AND used_at IS NULL
+            WHERE uid = ${uid} AND used_at IS NULL
         `);
 		await this.db.insert(this.magicLinkTokensTable).values({
-			userId,
+			uid,
 			tokenHash,
 			expiresAt
 		});
@@ -21485,7 +22148,7 @@ var MagicLinkTokenService = class {
 	async findValidByHash(tokenHash) {
 		const tableName = this.getQualifiedTableName();
 		const result = await this.db.execute(sql`
-            SELECT user_id, expires_at 
+            SELECT uid, expires_at 
             FROM ${sql.raw(tableName)} 
             WHERE token_hash = ${tokenHash} 
               AND used_at IS NULL 
@@ -21494,7 +22157,7 @@ var MagicLinkTokenService = class {
 		if (result.rows.length === 0) return null;
 		const row = result.rows[0];
 		return {
-			userId: row.user_id,
+			uid: row.uid,
 			expiresAt: new Date(row.expires_at)
 		};
 	}
@@ -21517,8 +22180,23 @@ var PostgresTokenRepository = class {
 		this.passwordResetTokenService = new PasswordResetTokenService(db, tableOrTables);
 		this.magicLinkTokenService = new MagicLinkTokenService(db, tableOrTables);
 	}
-	async createRefreshToken(userId, tokenHash, expiresAt, userAgent, ipAddress) {
-		await this.refreshTokenService.createToken(userId, 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);
@@ -21526,17 +22204,17 @@ var PostgresTokenRepository = class {
 	async deleteRefreshToken(tokenHash) {
 		await this.refreshTokenService.deleteByHash(tokenHash);
 	}
-	async deleteAllRefreshTokensForUser(userId) {
-		await this.refreshTokenService.deleteAllForUser(userId);
+	async deleteAllRefreshTokensForUser(uid) {
+		await this.refreshTokenService.deleteAllForUser(uid);
 	}
-	async listRefreshTokensForUser(userId) {
-		return this.refreshTokenService.listForUser(userId);
+	async listRefreshTokensForUser(uid) {
+		return this.refreshTokenService.listForUser(uid);
 	}
-	async deleteRefreshTokenById(id, userId) {
-		await this.refreshTokenService.deleteById(id, userId);
+	async deleteRefreshTokenById(id, uid) {
+		await this.refreshTokenService.deleteById(id, uid);
 	}
-	async createPasswordResetToken(userId, tokenHash, expiresAt) {
-		await this.passwordResetTokenService.createToken(userId, tokenHash, expiresAt);
+	async createPasswordResetToken(uid, tokenHash, expiresAt) {
+		await this.passwordResetTokenService.createToken(uid, tokenHash, expiresAt);
 	}
 	async findValidPasswordResetToken(tokenHash) {
 		return this.passwordResetTokenService.findValidByHash(tokenHash);
@@ -21544,14 +22222,14 @@ var PostgresTokenRepository = class {
 	async markPasswordResetTokenUsed(tokenHash) {
 		await this.passwordResetTokenService.markAsUsed(tokenHash);
 	}
-	async deleteAllPasswordResetTokensForUser(userId) {
-		await this.passwordResetTokenService.deleteAllForUser(userId);
+	async deleteAllPasswordResetTokensForUser(uid) {
+		await this.passwordResetTokenService.deleteAllForUser(uid);
 	}
 	async deleteExpiredTokens() {
 		await this.passwordResetTokenService.deleteExpired();
 	}
-	async createMagicLinkToken(userId, tokenHash, expiresAt) {
-		await this.magicLinkTokenService.createToken(userId, tokenHash, expiresAt);
+	async createMagicLinkToken(uid, tokenHash, expiresAt) {
+		await this.magicLinkTokenService.createToken(uid, tokenHash, expiresAt);
 	}
 	async findValidMagicLinkToken(tokenHash) {
 		return this.magicLinkTokenService.findValidByHash(tokenHash);
@@ -21586,11 +22264,11 @@ var PostgresAuthRepository = class {
 	async getUserByIdentity(provider, providerId) {
 		return this.userService.getUserByIdentity(provider, providerId);
 	}
-	async getUserIdentities(userId) {
-		return this.userService.getUserIdentities(userId);
+	async getUserIdentities(uid) {
+		return this.userService.getUserIdentities(uid);
 	}
-	async linkUserIdentity(userId, provider, providerId, profileData) {
-		return this.userService.linkUserIdentity(userId, provider, providerId, profileData);
+	async linkUserIdentity(uid, provider, providerId, profileData) {
+		return this.userService.linkUserIdentity(uid, provider, providerId, profileData);
 	}
 	async updateUser(id, data) {
 		return this.userService.updateUser(id, data);
@@ -21616,20 +22294,20 @@ var PostgresAuthRepository = class {
 	async getUserByVerificationToken(token) {
 		return this.userService.getUserByVerificationToken(token);
 	}
-	async getUserRoles(userId) {
-		return this.userService.getUserRoles(userId);
+	async getUserRoles(uid) {
+		return this.userService.getUserRoles(uid);
 	}
-	async getUserRoleIds(userId) {
-		return this.userService.getUserRoleIds(userId);
+	async getUserRoleIds(uid) {
+		return this.userService.getUserRoleIds(uid);
 	}
-	async setUserRoles(userId, roleIds) {
-		await this.userService.setUserRoles(userId, roleIds);
+	async setUserRoles(uid, roleIds) {
+		await this.userService.setUserRoles(uid, roleIds);
 	}
-	async assignDefaultRole(userId, roleId) {
-		await this.userService.assignDefaultRole(userId, roleId);
+	async assignDefaultRole(uid, roleId) {
+		await this.userService.assignDefaultRole(uid, roleId);
 	}
-	async getUserWithRoles(userId) {
-		return this.userService.getUserWithRoles(userId);
+	async getUserWithRoles(uid) {
+		return this.userService.getUserWithRoles(uid);
 	}
 	async getRoleById(id) {
 		return {
@@ -21684,8 +22362,23 @@ var PostgresAuthRepository = class {
 		};
 	}
 	async deleteRole(_id) {}
-	async createRefreshToken(userId, tokenHash, expiresAt, userAgent, ipAddress) {
-		await this.tokenRepository.createRefreshToken(userId, 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);
@@ -21693,17 +22386,17 @@ var PostgresAuthRepository = class {
 	async deleteRefreshToken(tokenHash) {
 		await this.tokenRepository.deleteRefreshToken(tokenHash);
 	}
-	async deleteAllRefreshTokensForUser(userId) {
-		await this.tokenRepository.deleteAllRefreshTokensForUser(userId);
+	async deleteAllRefreshTokensForUser(uid) {
+		await this.tokenRepository.deleteAllRefreshTokensForUser(uid);
 	}
-	async listRefreshTokensForUser(userId) {
-		return this.tokenRepository.listRefreshTokensForUser(userId);
+	async listRefreshTokensForUser(uid) {
+		return this.tokenRepository.listRefreshTokensForUser(uid);
 	}
-	async deleteRefreshTokenById(id, userId) {
-		await this.tokenRepository.deleteRefreshTokenById(id, userId);
+	async deleteRefreshTokenById(id, uid) {
+		await this.tokenRepository.deleteRefreshTokenById(id, uid);
 	}
-	async createPasswordResetToken(userId, tokenHash, expiresAt) {
-		await this.tokenRepository.createPasswordResetToken(userId, tokenHash, expiresAt);
+	async createPasswordResetToken(uid, tokenHash, expiresAt) {
+		await this.tokenRepository.createPasswordResetToken(uid, tokenHash, expiresAt);
 	}
 	async findValidPasswordResetToken(tokenHash) {
 		return this.tokenRepository.findValidPasswordResetToken(tokenHash);
@@ -21711,14 +22404,14 @@ var PostgresAuthRepository = class {
 	async markPasswordResetTokenUsed(tokenHash) {
 		await this.tokenRepository.markPasswordResetTokenUsed(tokenHash);
 	}
-	async deleteAllPasswordResetTokensForUser(userId) {
-		await this.tokenRepository.deleteAllPasswordResetTokensForUser(userId);
+	async deleteAllPasswordResetTokensForUser(uid) {
+		await this.tokenRepository.deleteAllPasswordResetTokensForUser(uid);
 	}
 	async deleteExpiredTokens() {
 		await this.tokenRepository.deleteExpiredTokens();
 	}
-	async createMagicLinkToken(userId, tokenHash, expiresAt) {
-		await this.tokenRepository.createMagicLinkToken(userId, tokenHash, expiresAt);
+	async createMagicLinkToken(uid, tokenHash, expiresAt) {
+		await this.tokenRepository.createMagicLinkToken(uid, tokenHash, expiresAt);
 	}
 	async findValidMagicLinkToken(tokenHash) {
 		return this.tokenRepository.findValidMagicLinkToken(tokenHash);
@@ -21731,11 +22424,11 @@ var PostgresAuthRepository = class {
 		if (!this._mfaService) this._mfaService = new MfaService(this.db);
 		return this._mfaService;
 	}
-	async createMfaFactor(userId, factorType, secretEncrypted, friendlyName) {
-		return this.getMfaService().createMfaFactor(userId, factorType, secretEncrypted, friendlyName);
+	async createMfaFactor(uid, factorType, secretEncrypted, friendlyName) {
+		return this.getMfaService().createMfaFactor(uid, factorType, secretEncrypted, friendlyName);
 	}
-	async getMfaFactors(userId) {
-		return this.getMfaService().getMfaFactors(userId);
+	async getMfaFactors(uid) {
+		return this.getMfaService().getMfaFactors(uid);
 	}
 	async getMfaFactorById(factorId) {
 		return this.getMfaService().getMfaFactorById(factorId);
@@ -21743,8 +22436,8 @@ var PostgresAuthRepository = class {
 	async verifyMfaFactor(factorId) {
 		return this.getMfaService().verifyMfaFactor(factorId);
 	}
-	async deleteMfaFactor(factorId, userId) {
-		return this.getMfaService().deleteMfaFactor(factorId, userId);
+	async deleteMfaFactor(factorId, uid) {
+		return this.getMfaService().deleteMfaFactor(factorId, uid);
 	}
 	async createMfaChallenge(factorId, ipAddress) {
 		return this.getMfaService().createMfaChallenge(factorId, ipAddress);
@@ -21755,20 +22448,20 @@ var PostgresAuthRepository = class {
 	async verifyMfaChallenge(challengeId) {
 		return this.getMfaService().verifyMfaChallenge(challengeId);
 	}
-	async createRecoveryCodes(userId, codeHashes) {
-		return this.getMfaService().createRecoveryCodes(userId, codeHashes);
+	async createRecoveryCodes(uid, codeHashes) {
+		return this.getMfaService().createRecoveryCodes(uid, codeHashes);
 	}
-	async useRecoveryCode(userId, codeHash) {
-		return this.getMfaService().useRecoveryCode(userId, codeHash);
+	async useRecoveryCode(uid, codeHash) {
+		return this.getMfaService().useRecoveryCode(uid, codeHash);
 	}
-	async getUnusedRecoveryCodeCount(userId) {
-		return this.getMfaService().getUnusedRecoveryCodeCount(userId);
+	async getUnusedRecoveryCodeCount(uid) {
+		return this.getMfaService().getUnusedRecoveryCodeCount(uid);
 	}
-	async deleteAllRecoveryCodes(userId) {
-		return this.getMfaService().deleteAllRecoveryCodes(userId);
+	async deleteAllRecoveryCodes(uid) {
+		return this.getMfaService().deleteAllRecoveryCodes(uid);
 	}
-	async hasVerifiedMfaFactors(userId) {
-		return this.getMfaService().hasVerifiedMfaFactors(userId);
+	async hasVerifiedMfaFactors(uid) {
+		return this.getMfaService().hasVerifiedMfaFactors(uid);
 	}
 };
 /**
@@ -21785,16 +22478,16 @@ var MfaService = class {
 	qualify(tableName) {
 		return `"${this.schemaName}"."${tableName}"`;
 	}
-	async createMfaFactor(userId, factorType, secretEncrypted, friendlyName) {
+	async createMfaFactor(uid, factorType, secretEncrypted, friendlyName) {
 		const tableName = this.qualify("mfa_factors");
 		const row = (await this.db.execute(sql`
-            INSERT INTO ${sql.raw(tableName)} (user_id, factor_type, secret_encrypted, friendly_name)
-            VALUES (${userId}, ${factorType}, ${secretEncrypted}, ${friendlyName ?? null})
-            RETURNING id, user_id, factor_type, friendly_name, verified, created_at, updated_at
+            INSERT INTO ${sql.raw(tableName)} (uid, factor_type, secret_encrypted, friendly_name)
+            VALUES (${uid}, ${factorType}, ${secretEncrypted}, ${friendlyName ?? null})
+            RETURNING id, uid, factor_type, friendly_name, verified, created_at, updated_at
         `)).rows[0];
 		return {
 			id: row.id,
-			userId: row.user_id,
+			uid: row.uid,
 			factorType: row.factor_type,
 			friendlyName: row.friendly_name ?? void 0,
 			verified: row.verified,
@@ -21802,16 +22495,16 @@ var MfaService = class {
 			updatedAt: new Date(row.updated_at)
 		};
 	}
-	async getMfaFactors(userId) {
+	async getMfaFactors(uid) {
 		const tableName = this.qualify("mfa_factors");
 		return (await this.db.execute(sql`
-            SELECT id, user_id, factor_type, friendly_name, verified, created_at, updated_at
+            SELECT id, uid, factor_type, friendly_name, verified, created_at, updated_at
             FROM ${sql.raw(tableName)}
-            WHERE user_id = ${userId}
+            WHERE uid = ${uid}
             ORDER BY created_at
         `)).rows.map((row) => ({
 			id: row.id,
-			userId: row.user_id,
+			uid: row.uid,
 			factorType: row.factor_type,
 			friendlyName: row.friendly_name ?? void 0,
 			verified: row.verified,
@@ -21822,7 +22515,7 @@ var MfaService = class {
 	async getMfaFactorById(factorId) {
 		const tableName = this.qualify("mfa_factors");
 		const result = await this.db.execute(sql`
-            SELECT id, user_id, factor_type, secret_encrypted, friendly_name, verified, created_at, updated_at
+            SELECT id, uid, factor_type, secret_encrypted, friendly_name, verified, created_at, updated_at
             FROM ${sql.raw(tableName)}
             WHERE id = ${factorId}
         `);
@@ -21830,7 +22523,7 @@ var MfaService = class {
 		const row = result.rows[0];
 		return {
 			id: row.id,
-			userId: row.user_id,
+			uid: row.uid,
 			factorType: row.factor_type,
 			secretEncrypted: row.secret_encrypted,
 			friendlyName: row.friendly_name ?? void 0,
@@ -21847,11 +22540,11 @@ var MfaService = class {
             WHERE id = ${factorId}
         `);
 	}
-	async deleteMfaFactor(factorId, userId) {
+	async deleteMfaFactor(factorId, uid) {
 		const tableName = this.qualify("mfa_factors");
 		await this.db.execute(sql`
             DELETE FROM ${sql.raw(tableName)}
-            WHERE id = ${factorId} AND user_id = ${userId}
+            WHERE id = ${factorId} AND uid = ${uid}
         `);
 	}
 	async createMfaChallenge(factorId, ipAddress) {
@@ -21895,43 +22588,43 @@ var MfaService = class {
             WHERE id = ${challengeId}
         `);
 	}
-	async createRecoveryCodes(userId, codeHashes) {
+	async createRecoveryCodes(uid, codeHashes) {
 		const tableName = this.qualify("recovery_codes");
 		await this.db.execute(sql`
-            DELETE FROM ${sql.raw(tableName)} WHERE user_id = ${userId}
+            DELETE FROM ${sql.raw(tableName)} WHERE uid = ${uid}
         `);
 		for (const hash of codeHashes) await this.db.execute(sql`
-                INSERT INTO ${sql.raw(tableName)} (user_id, code_hash)
-                VALUES (${userId}, ${hash})
+                INSERT INTO ${sql.raw(tableName)} (uid, code_hash)
+                VALUES (${uid}, ${hash})
             `);
 	}
-	async useRecoveryCode(userId, codeHash) {
+	async useRecoveryCode(uid, codeHash) {
 		const tableName = this.qualify("recovery_codes");
 		return (await this.db.execute(sql`
             UPDATE ${sql.raw(tableName)}
             SET used_at = NOW()
-            WHERE user_id = ${userId} AND code_hash = ${codeHash} AND used_at IS NULL
+            WHERE uid = ${uid} AND code_hash = ${codeHash} AND used_at IS NULL
             RETURNING id
         `)).rows.length > 0;
 	}
-	async getUnusedRecoveryCodeCount(userId) {
+	async getUnusedRecoveryCodeCount(uid) {
 		const tableName = this.qualify("recovery_codes");
 		return (await this.db.execute(sql`
             SELECT COUNT(*)::int as count FROM ${sql.raw(tableName)}
-            WHERE user_id = ${userId} AND used_at IS NULL
+            WHERE uid = ${uid} AND used_at IS NULL
         `)).rows[0].count;
 	}
-	async deleteAllRecoveryCodes(userId) {
+	async deleteAllRecoveryCodes(uid) {
 		const tableName = this.qualify("recovery_codes");
 		await this.db.execute(sql`
-            DELETE FROM ${sql.raw(tableName)} WHERE user_id = ${userId}
+            DELETE FROM ${sql.raw(tableName)} WHERE uid = ${uid}
         `);
 	}
-	async hasVerifiedMfaFactors(userId) {
+	async hasVerifiedMfaFactors(uid) {
 		const tableName = this.qualify("mfa_factors");
 		return (await this.db.execute(sql`
             SELECT COUNT(*)::int as count FROM ${sql.raw(tableName)}
-            WHERE user_id = ${userId} AND verified = TRUE
+            WHERE uid = ${uid} AND verified = TRUE
         `)).rows[0].count > 0;
 	}
 };
@@ -22171,6 +22864,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",
@@ -22230,13 +22937,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";
@@ -22757,6 +23457,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",