@rebasepro/server-postgres 0.22.0 → 0.24.0

package/dist/{BranchService-CucnFcSE.js → BranchService-BRt78gfa.js}

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from "module";
 __createRequire(import.meta.url);
 import { r as __exportAll } from "./__vite-browser-external-BnuHet1e.js";
-import { d as extractPgError, u as extractCauseMessage } from "./cli-errors-Dka89exj.js";
+import { d as extractPgError, u as extractCauseMessage } from "./cli-errors-DsA-K9uP.js";
 import { sql } from "drizzle-orm";
 import { revokeInternalTableSql } from "@rebasepro/common";
 //#region src/services/BranchService.ts
@@ -106,9 +106,20 @@ function toBranchDbName(name) {
 var BranchService = class {
 	db;
 	poolManager;
-	constructor(db, poolManager) {
+	home;
+	/**
+	* @param db    A connection on the server the branches are made on. Branch
+	*              DDL runs here.
+	* @param home  Where branches are kept. Without one, the database the
+	*              pool manager's connection string names, and `db`'s registry.
+	*/
+	constructor(db, poolManager, home) {
 		this.db = db;
 		this.poolManager = poolManager;
+		this.home = home ?? {
+			database: async () => poolManager.defaultDatabaseName,
+			registry: async () => db
+		};
 	}
 	/**
 	* Refuse a branch mutation the connected server cannot honour.
@@ -130,8 +141,9 @@ var BranchService = class {
 	* Idempotent — safe to call on every startup.
 	*/
 	async ensureBranchMetadataTable() {
-		await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
-		await this.db.execute(sql.raw(`
+		const registry = await this.home.registry();
+		await registry.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+		await registry.execute(sql.raw(`
             CREATE TABLE IF NOT EXISTS ${BRANCHES_TABLE} (
                 name         TEXT PRIMARY KEY,
                 db_name      TEXT NOT NULL UNIQUE,
@@ -140,7 +152,7 @@ var BranchService = class {
                 metadata     JSONB DEFAULT '{}'
             );
         `));
-		await this.db.execute(sql.raw(revokeInternalTableSql("rebase", "branches")));
+		await registry.execute(sql.raw(revokeInternalTableSql("rebase", "branches")));
 	}
 	/**
 	* Create a new branch database by templating the source database.
@@ -155,8 +167,8 @@ var BranchService = class {
 		await this.assertBranchingSupported();
 		if (options?.source) validateIdentifier(options.source, "source database name");
 		const dbName = toBranchDbName(name);
-		const sourceDb = options?.source || this.poolManager.defaultDatabaseName;
-		if ((await this.db.execute(sql`SELECT name FROM rebase.branches WHERE name = ${name} OR db_name = ${dbName}`)).rows.length > 0) throw new Error(`Branch "${name}" already exists.`);
+		const sourceDb = options?.source || await this.home.database();
+		if ((await (await this.home.registry()).execute(sql`SELECT name FROM rebase.branches WHERE name = ${name} OR db_name = ${dbName}`)).rows.length > 0) throw new Error(`Branch "${name}" already exists.`);
 		await this.poolManager.disconnectDatabase(sourceDb);
 		if (options?.force) {
 			if (await this.terminateConnections(sourceDb) > 0) await new Promise((resolve) => setTimeout(resolve, 250));
@@ -170,10 +182,11 @@ var BranchService = class {
 			throw describeBranchDdlError(err, dbName);
 		}
 		const now = /* @__PURE__ */ new Date();
-		await this.db.execute(sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at)
+		await (await this.home.registry()).execute(sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at)
                 VALUES (${name}, ${dbName}, ${sourceDb}, ${now.toISOString()})`);
 		return {
 			name,
+			database: dbName,
 			parentDatabase: sourceDb,
 			createdAt: now
 		};
@@ -185,11 +198,12 @@ var BranchService = class {
 	async deleteBranch(name, options) {
 		await this.assertBranchingSupported();
 		assertValidBranchName(name);
-		if (toBranchDbName(name) === this.poolManager.defaultDatabaseName) throw new Error("Cannot delete the main database.");
-		const existingRows = (await this.db.execute(sql`SELECT db_name FROM rebase.branches WHERE name = ${name}`)).rows;
+		const mainDatabase = await this.home.database();
+		if (toBranchDbName(name) === mainDatabase) throw new Error("Cannot delete the main database.");
+		const existingRows = (await (await this.home.registry()).execute(sql`SELECT db_name FROM rebase.branches WHERE name = ${name}`)).rows;
 		if (existingRows.length === 0) throw new Error(`Branch "${name}" not found.`);
 		const dbName = existingRows[0].db_name;
-		if (dbName === this.poolManager.defaultDatabaseName) throw new Error("Cannot delete the main database.");
+		if (dbName === mainDatabase) throw new Error("Cannot delete the main database.");
 		await this.poolManager.disconnectDatabase(dbName);
 		if (options?.force) {
 			if (await this.terminateConnections(dbName) > 0) await new Promise((resolve) => setTimeout(resolve, 250));
@@ -201,7 +215,7 @@ var BranchService = class {
 			if (extractPgError(err)?.code === PG_OBJECT_IN_USE) throw new Error(`Cannot delete branch "${name}": the database has active connections.\n` + await this.describeBlockingConnections(dbName));
 			throw describeBranchDdlError(err, dbName);
 		}
-		await this.db.execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);
+		await (await this.home.registry()).execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);
 	}
 	/**
 	* Who is holding the database open, in words a developer can act on.
@@ -268,7 +282,7 @@ var BranchService = class {
 	*/
 	async pruneCandidates() {
 		return {
-			rows: (await this.db.execute(sql.raw(`
+			rows: (await (await this.home.registry()).execute(sql.raw(`
             SELECT name, db_name, created_at FROM ${BRANCHES_TABLE} ORDER BY created_at
         `))).rows.map((row) => ({
 				name: row.name,
@@ -282,7 +296,7 @@ var BranchService = class {
 	}
 	/** Remove a metadata row whose database is already gone. */
 	async forgetBranchRow(name) {
-		await this.db.execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);
+		await (await this.home.registry()).execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);
 	}
 	/**
 	* Drop a database by name, with no metadata row required.
@@ -295,7 +309,7 @@ var BranchService = class {
 	*/
 	async dropDatabase(dbName) {
 		validateIdentifier(dbName, "database name");
-		if (dbName === this.poolManager.defaultDatabaseName) throw new Error("Cannot delete the main database.");
+		if (dbName === await this.home.database()) throw new Error("Cannot delete the main database.");
 		await this.poolManager.disconnectDatabase(dbName);
 		try {
 			await this.db.execute(sql.raw(`DROP DATABASE "${dbName.replace(/"/g, "\"\"")}"`));
@@ -308,9 +322,10 @@ var BranchService = class {
 	* Optionally fetches database sizes from pg_database.
 	*/
 	async listBranches() {
-		return (await this.db.execute(sql.raw(`
+		return (await (await this.home.registry()).execute(sql.raw(`
             SELECT 
                 b.name,
+                b.db_name,
                 b.parent_db,
                 b.created_at,
                 pg_database_size(b.db_name) as size_bytes
@@ -319,6 +334,7 @@ var BranchService = class {
             ORDER BY b.created_at DESC
         `))).rows.map((row) => ({
 			name: row.name,
+			database: row.db_name,
 			parentDatabase: row.parent_db,
 			createdAt: new Date(row.created_at),
 			sizeBytes: row.size_bytes != null ? Number(row.size_bytes) : void 0
@@ -329,7 +345,7 @@ var BranchService = class {
 	*/
 	async getBranchInfo(name) {
 		assertValidBranchName(name);
-		const rows = (await this.db.execute(sql`
+		const rows = (await (await this.home.registry()).execute(sql`
             SELECT
                 b.name,
                 b.db_name,
@@ -348,6 +364,7 @@ var BranchService = class {
 		} catch {}
 		return {
 			name: row.name,
+			database: row.db_name,
 			parentDatabase: row.parent_db,
 			createdAt: new Date(row.created_at),
 			sizeBytes
@@ -357,4 +374,4 @@ var BranchService = class {
 //#endregion
 export { BranchService_exports as n, BranchingUnsupportedError as r, BranchService as t };
 
-//# sourceMappingURL=BranchService-CucnFcSE.js.map
+//# sourceMappingURL=BranchService-BRt78gfa.js.map

package/dist/BranchService-BRt78gfa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchService-BRt78gfa.js","names":[],"sources":["../src/services/BranchService.ts"],"sourcesContent":["/**\n * BranchService\n *\n * Manages database branching by creating/deleting PostgreSQL databases\n * using `CREATE DATABASE ... TEMPLATE`. Branch metadata is stored in the\n * `rebase.branches` table in the default (main) database, following the\n * same `rebase` schema convention used by entity_history, auth, etc.\n */\n\nimport { sql } from \"drizzle-orm\";\nimport { BranchInfo } from \"@rebasepro/types\";\nimport { revokeInternalTableSql } from \"@rebasepro/common\";\nimport { DrizzleClient } from \"../interfaces\";\nimport { BranchRow } from \"../branch-prune\";\nimport { DatabasePoolManager } from \"../databasePoolManager\";\nimport { extractPgError, extractCauseMessage } from \"../utils/pg-error-utils\";\n\n/** Internal prefix applied to branch database names to avoid collisions. */\nconst BRANCH_DB_PREFIX = \"rb_\";\n\n/** `duplicate_database` — the target database name is already taken. */\nconst PG_DUPLICATE_DATABASE = \"42P04\";\n\n/** `object_in_use` — the database still has connections attached. */\nconst PG_OBJECT_IN_USE = \"55006\";\n\n/**\n * Describe a failed branch DDL statement in terms a user can act on.\n *\n * Drizzle reports failures as `Failed query: <sql> params:` and hides the real\n * PostgreSQL error in the `cause` chain, so matching on `err.message` never sees\n * the actual problem. Match on the PG error code instead — it survives wrapping\n * and, unlike the message text, is not locale-dependent.\n */\nfunction describeBranchDdlError(err: unknown, fallbackContext: string): Error {\n    const pgError = extractPgError(err);\n\n    if (pgError?.code === PG_DUPLICATE_DATABASE) {\n        return new Error(`Database \"${fallbackContext}\" already exists on the server. Choose a different branch name.`);\n    }\n    if (pgError?.code === PG_OBJECT_IN_USE) {\n        return new Error(\n            `Cannot complete the operation: the database \"${fallbackContext}\" has active connections. ` +\n            \"Close other clients or connections and try again.\"\n        );\n    }\n\n    // Unknown failure: surface the real PG message rather than the Drizzle\n    // wrapper, which would otherwise show the raw SQL and no reason at all.\n    const detail = pgError?.message ?? extractCauseMessage(err);\n    if (detail) return new Error(detail);\n    return err instanceof Error ? err : new Error(String(err));\n}\n\n/** Fully-qualified metadata table in the rebase schema. */\nconst BRANCHES_TABLE = \"rebase.branches\";\n\n/**\n * The connected server cannot branch, so nothing was done.\n *\n * A refusal, not a fault: typed so the transports can forward it intact.\n * `websocket.ts` answers it with its own code and message rather than letting\n * it fall into the generic handler, which suppresses the text in production —\n * and the text is the only part that says what to do instead.\n */\nexport class BranchingUnsupportedError extends Error {\n    /** Wire code, forwarded verbatim to the client. */\n    readonly code = \"BRANCHING_UNSUPPORTED\";\n\n    constructor(message: string) {\n        super(message);\n        this.name = \"BranchingUnsupportedError\";\n    }\n}\n\n/**\n * What to say when the server serves one database.\n *\n * Deliberately the same argument the CLI's `refuseBranchOnManagedDatabase`\n * makes, because it is the same refusal — it just used to be available only to\n * whoever came in through argv. One paragraph, because this one has to fit in a\n * toast as well as a terminal.\n */\nconst BRANCHING_UNSUPPORTED_MESSAGE =\n    \"Branching does not work on the managed development database. It copies a database with \"\n    + \"CREATE DATABASE ... TEMPLATE, and the managed database is PGlite, which serves exactly one — \"\n    + \"the copy would be the original, and every write you meant to sandbox would land in it. \"\n    + \"Branching needs a real Postgres: run `rebase dev --docker`, or uncomment DATABASE_URL in .env \"\n    + \"to point at your own.\";\n\n/**\n * Validate that a user-provided identifier only contains safe characters.\n * Throws if the value contains characters outside [a-zA-Z0-9_-].\n */\nfunction validateIdentifier(value: string, label: string): void {\n    if (!/^[a-zA-Z0-9_-]+$/.test(value)) {\n        throw new Error(`Invalid ${label}: only letters, digits, underscores, and hyphens are allowed.`);\n    }\n}\n\n/**\n * Postgres truncates identifiers at NAMEDATALEN-1 = 63 bytes, and does it\n * silently. The prefix comes out of the same budget.\n */\nconst MAX_BRANCH_NAME_LENGTH = 63 - BRANCH_DB_PREFIX.length;\n\n/**\n * Check a user-provided branch name, and otherwise leave it exactly as given.\n *\n * This used to strip everything outside [a-zA-Z0-9_], so `my-feature` was\n * quietly created as `myfeature`: the name you typed was not the name `list`\n * gave back. Nothing ever needed that. Every identifier this service builds is\n * double-quoted (see `CREATE DATABASE` below), which is what makes a hyphen\n * safe, and `validateIdentifier` has always accepted hyphens for the `--from`\n * source database — the two disagreed about the same character class.\n *\n * Refusing a name we cannot represent is better than representing a different\n * one, which is also why the length is checked here rather than left to\n * Postgres, whose answer to an over-long identifier is a silent rename.\n */\nfunction assertValidBranchName(name: string): void {\n    validateIdentifier(name, \"branch name\");\n    if (name.length > MAX_BRANCH_NAME_LENGTH) {\n        throw new Error(\n            `Branch name \"${name}\" is too long: ${name.length} characters, maximum ${MAX_BRANCH_NAME_LENGTH}. ` +\n            \"Postgres truncates identifiers past 63 bytes, which would give the branch a name you did not choose.\"\n        );\n    }\n}\n\n/**\n * Convert a user-facing branch name to the actual PostgreSQL database name.\n */\nfunction toBranchDbName(name: string): string {\n    assertValidBranchName(name);\n    return `${BRANCH_DB_PREFIX}${name}`;\n}\n\n/**\n * Where a server's branches are kept: the main database — what a branch is\n * copied from unless told otherwise, and what may never be dropped — and the\n * connection whose `rebase.branches` records them.\n */\nexport interface BranchHome {\n    /** The main database's name. */\n    database(): Promise<string>;\n    /**\n     * A connection on the database the registry is in. Asked for at each use:\n     * a pool to the main database is closed before it is copied.\n     */\n    registry(): Promise<DrizzleClient>;\n}\n\nexport class BranchService {\n    private readonly home: BranchHome;\n\n    /**\n     * @param db    A connection on the server the branches are made on. Branch\n     *              DDL runs here.\n     * @param home  Where branches are kept. Without one, the database the\n     *              pool manager's connection string names, and `db`'s registry.\n     */\n    constructor(\n        private db: DrizzleClient,\n        private poolManager: DatabasePoolManager,\n        home?: BranchHome\n    ) {\n        this.home = home ?? {\n            database: async () => poolManager.defaultDatabaseName,\n            registry: async () => db\n        };\n    }\n\n    /**\n     * Refuse a branch mutation the connected server cannot honour.\n     *\n     * The check lives here rather than in the CLI's argv parsing because the\n     * CLI is not the only caller: Studio reaches `createBranch` over the\n     * websocket, and before this it got \"Branch created successfully\" and a\n     * detail pane promising isolation for a database that is the parent.\n     *\n     * Reads only, and only mutations are guarded: `listBranches` on a managed\n     * database is an honest empty list, and refusing it would turn the Branches\n     * pane into a failure with a \"Try again\" that can never succeed.\n     */\n    private async assertBranchingSupported(): Promise<void> {\n        if (await this.poolManager.servesOneDatabase()) {\n            throw new BranchingUnsupportedError(BRANCHING_UNSUPPORTED_MESSAGE);\n        }\n    }\n\n    /**\n     * Ensure the `rebase.branches` metadata table exists in the default database.\n     * Idempotent — safe to call on every startup.\n     */\n    async ensureBranchMetadataTable(): Promise<void> {\n        // Create the rebase schema (idempotent — may already exist from auth/history init)\n        const registry = await this.home.registry();\n        await registry.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);\n\n        await registry.execute(sql.raw(`\n            CREATE TABLE IF NOT EXISTS ${BRANCHES_TABLE} (\n                name         TEXT PRIMARY KEY,\n                db_name      TEXT NOT NULL UNIQUE,\n                parent_db    TEXT NOT NULL,\n                created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n                metadata     JSONB DEFAULT '{}'\n            );\n        `));\n\n        // Not a collection, so no RLS — and it names every branch database on\n        // this server. The driver's schema-wide grant reaches it, so revoke.\n        await registry.execute(sql.raw(revokeInternalTableSql(\"rebase\", \"branches\")));\n    }\n\n    /**\n     * Create a new branch database by templating the source database.\n     *\n     * Uses `CREATE DATABASE ... TEMPLATE` for an instant, full-fidelity copy\n     * of both schema and data.\n     *\n     * @param name   User-facing branch name (e.g., \"feature_auth\")\n     * @param options.source  Source database to clone; defaults to the main database.\n     */\n    async createBranch(\n        name: string,\n        options?: { source?: string; force?: boolean }\n    ): Promise<BranchInfo> {\n        await this.assertBranchingSupported();\n\n        if (options?.source) {\n            validateIdentifier(options.source, \"source database name\");\n        }\n\n        const dbName = toBranchDbName(name);\n        const sourceDb = options?.source || await this.home.database();\n\n        // Check if branch already exists\n        const existing = await (await this.home.registry()).execute(\n            sql`SELECT name FROM rebase.branches WHERE name = ${name} OR db_name = ${dbName}`\n        );\n        if ((existing.rows as unknown[]).length > 0) {\n            throw new Error(`Branch \"${name}\" already exists.`);\n        }\n\n        // Disconnect any idle pools to the source DB so TEMPLATE works.\n        // CREATE DATABASE ... TEMPLATE requires no other connections to the template.\n        //\n        // This only reaches pools inside *this* process. The CLI runs as its own\n        // process, so a `rebase dev` holding the database open is untouched by\n        // it — which is why the failure below has to name what is connected, and\n        // why `--force` exists.\n        await this.poolManager.disconnectDatabase(sourceDb);\n\n        if (options?.force) {\n            const closed = await this.terminateConnections(sourceDb);\n            if (closed > 0) {\n                // Postgres reports the backend as gone before its slot is\n                // actually free, and CREATE DATABASE then fails on a connection\n                // that no longer exists. One short settle beats a confusing retry.\n                await new Promise((resolve) => setTimeout(resolve, 250));\n            }\n        }\n\n        // Create the database using the source as a template.\n        // Note: Identifiers must be double-quoted, not parameterized.\n        const safeDbName = dbName.replace(/\"/g, '\"\"');\n        const safeSourceDb = sourceDb.replace(/\"/g, '\"\"');\n        try {\n            await this.db.execute(\n                sql.raw(`CREATE DATABASE \"${safeDbName}\" TEMPLATE \"${safeSourceDb}\"`)\n            );\n        } catch (err) {\n            const pgError = extractPgError(err);\n            if (pgError?.code === PG_OBJECT_IN_USE) {\n                // The template — not the new database — is the one still in use.\n                throw new Error(\n                    `Cannot create branch: the source database \"${sourceDb}\" has active connections.\\n`\n                    + await this.describeBlockingConnections(sourceDb)\n                );\n            }\n            throw describeBranchDdlError(err, dbName);\n        }\n\n        // Record metadata in the registry — asked for again, as copying the\n        // main database closed any pool on it.\n        const now = new Date();\n        await (await this.home.registry()).execute(\n            sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at)\n                VALUES (${name}, ${dbName}, ${sourceDb}, ${now.toISOString()})`\n        );\n\n        return {\n            name,\n            database: dbName,\n            parentDatabase: sourceDb,\n            createdAt: now\n        };\n    }\n\n    /**\n     * Delete a branch database and remove its metadata.\n     * Cannot delete the main/default database.\n     */\n    async deleteBranch(name: string, options?: { force?: boolean }): Promise<void> {\n        await this.assertBranchingSupported();\n\n        assertValidBranchName(name);\n\n        // Safety, first pass: a request that would target the default database\n        // is refused before any metadata is read, so the answer costs nothing\n        // and cannot depend on what a row happens to say.\n        const mainDatabase = await this.home.database();\n        if (toBranchDbName(name) === mainDatabase) {\n            throw new Error(\"Cannot delete the main database.\");\n        }\n\n        // Verify the branch exists, and take the database name from the row\n        // rather than deriving it again. A branch created before names stopped\n        // being stripped is recorded as `rb_myfeature` while `my-feature` now\n        // derives `rb_my-feature`; re-deriving would drop a database this row\n        // never named — or, if that name happened to exist, somebody else's.\n        // The stored value is the only one that is true by construction.\n        const existing = await (await this.home.registry()).execute(\n            sql`SELECT db_name FROM rebase.branches WHERE name = ${name}`\n        );\n        const existingRows = existing.rows as Record<string, unknown>[];\n        if (existingRows.length === 0) {\n            throw new Error(`Branch \"${name}\" not found.`);\n        }\n        const dbName = existingRows[0].db_name as string;\n\n        // Safety, second pass: the first checked a name we derived, this checks\n        // the one we are about to drop. They differ for any row written under\n        // the old scheme, and it is this one that governs.\n        if (dbName === mainDatabase) {\n            throw new Error(\"Cannot delete the main database.\");\n        }\n\n        // Disconnect any pools to this branch before dropping. Same limit as\n        // `createBranch`: in-process pools only.\n        await this.poolManager.disconnectDatabase(dbName);\n\n        if (options?.force) {\n            const closed = await this.terminateConnections(dbName);\n            if (closed > 0) await new Promise((resolve) => setTimeout(resolve, 250));\n        }\n\n        // Drop the database\n        const safeDbName = dbName.replace(/\"/g, '\"\"');\n        try {\n            await this.db.execute(sql.raw(`DROP DATABASE \"${safeDbName}\"`));\n        } catch (err) {\n            const pgError = extractPgError(err);\n            if (pgError?.code === PG_OBJECT_IN_USE) {\n                throw new Error(\n                    `Cannot delete branch \"${name}\": the database has active connections.\\n`\n                    + await this.describeBlockingConnections(dbName)\n                );\n            }\n            throw describeBranchDdlError(err, dbName);\n        }\n\n        // Remove metadata\n        await (await this.home.registry()).execute(\n            sql`DELETE FROM rebase.branches WHERE name = ${name}`\n        );\n    }\n\n    /**\n     * Who is holding the database open, in words a developer can act on.\n     *\n     * `CREATE DATABASE ... TEMPLATE` and `DROP DATABASE` both require that no\n     * other session is connected, and the one thing the old message could not\n     * say is the only thing worth knowing: *which* session. \"Close other\n     * clients or connections and try again\" is advice you cannot follow when\n     * you do not know there is a `rebase dev` in another terminal — and that is\n     * the common case, because wanting a branch and running the app are the\n     * same moment.\n     *\n     * `application_name` is the useful column: node-postgres sends none by\n     * default, so a Rebase process shows as `(unnamed)` while DBeaver, pgAdmin\n     * and psql all name themselves. Counting by it separates \"my own dev\n     * server\" from \"the GUI I forgot about\" without any guessing.\n     *\n     * Best-effort by construction: this runs while reporting a failure, and a\n     * diagnostic that throws would replace a real error with its own.\n     */\n    private async describeBlockingConnections(dbName: string): Promise<string> {\n        try {\n            const result = await this.db.execute(sql`\n                SELECT coalesce(nullif(application_name, ''), '(unnamed)') AS app,\n                       count(*)::int AS n\n                  FROM pg_stat_activity\n                 WHERE datname = ${dbName}\n                   AND pid <> pg_backend_pid()\n                 GROUP BY 1\n                 ORDER BY 2 DESC, 1\n            `);\n            const rows = result.rows as Record<string, unknown>[];\n            if (rows.length === 0) {\n                // The blocker went away between the failure and this query, or\n                // it is a session Postgres does not attribute to this database.\n                return \"  Retry — whatever was connected has since disconnected.\";\n            }\n\n            const listed = rows\n                .map((row) => `    ${row.n} × ${String(row.app)}`)\n                .join(\"\\n\");\n\n            return `  Connected right now:\\n${listed}\\n`\n                + \"  A running `rebase dev` is the usual one — stop it, or re-run with --force to\\n\"\n                + \"  disconnect them for you.\";\n        } catch {\n            return \"  Close other clients and connections, or re-run with --force.\";\n        }\n    }\n\n    /**\n     * Disconnect every other session on a database, and say how many.\n     *\n     * `pg_terminate_backend` rather than `pg_cancel_backend`: cancelling a\n     * query leaves the session connected, and a connected session is exactly\n     * what blocks the operation.\n     *\n     * The current backend is excluded — terminating the connection running this\n     * statement would abort the command that asked for it.\n     */\n    private async terminateConnections(dbName: string): Promise<number> {\n        const result = await this.db.execute(sql`\n            SELECT pg_terminate_backend(pid)\n              FROM pg_stat_activity\n             WHERE datname = ${dbName}\n               AND pid <> pg_backend_pid()\n        `);\n\n        return (result.rows as unknown[]).length;\n    }\n\n    /**\n     * Everything prune needs to decide, in two queries.\n     *\n     * Reads the rows and the server's database list rather than joining them,\n     * so the *disagreements* between the two are visible — a row whose database\n     * is gone and a database with no row are the two things prune exists to\n     * find, and a join hides both.\n     */\n    async pruneCandidates(): Promise<{ rows: BranchRow[]; databases: string[] }> {\n        const rowResult = await (await this.home.registry()).execute(sql.raw(`\n            SELECT name, db_name, created_at FROM ${BRANCHES_TABLE} ORDER BY created_at\n        `));\n        const rows = (rowResult.rows as Record<string, unknown>[]).map((row) => ({\n            name: row.name as string,\n            dbName: row.db_name as string,\n            createdAt: new Date(row.created_at as string)\n        }));\n\n        const dbResult = await this.db.execute(sql`\n            SELECT datname FROM pg_database WHERE NOT datistemplate\n        `);\n        const databases = (dbResult.rows as Record<string, unknown>[]).map((row) => String(row.datname));\n\n        return { rows, databases };\n    }\n\n    /** Remove a metadata row whose database is already gone. */\n    async forgetBranchRow(name: string): Promise<void> {\n        await (await this.home.registry()).execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);\n    }\n\n    /**\n     * Drop a database by name, with no metadata row required.\n     *\n     * `deleteBranch` deliberately takes its database name from the row, because\n     * the row is the only value that is true by construction. Prune has the\n     * opposite job — the cases it handles are exactly the ones where row and\n     * database disagree — so it needs to name a database directly. Guarded the\n     * same way regardless: the main database is never droppable.\n     */\n    async dropDatabase(dbName: string): Promise<void> {\n        validateIdentifier(dbName, \"database name\");\n        if (dbName === await this.home.database()) {\n            throw new Error(\"Cannot delete the main database.\");\n        }\n\n        await this.poolManager.disconnectDatabase(dbName);\n        try {\n            await this.db.execute(sql.raw(`DROP DATABASE \"${dbName.replace(/\"/g, '\"\"')}\"`));\n        } catch (err) {\n            throw describeBranchDdlError(err, dbName);\n        }\n    }\n\n    /**\n     * List all branches recorded in the metadata table.\n     * Optionally fetches database sizes from pg_database.\n     */\n    async listBranches(): Promise<BranchInfo[]> {\n        const result = await (await this.home.registry()).execute(sql.raw(`\n            SELECT \n                b.name,\n                b.db_name,\n                b.parent_db,\n                b.created_at,\n                pg_database_size(b.db_name) as size_bytes\n            FROM ${BRANCHES_TABLE} b\n            JOIN pg_database d ON d.datname = b.db_name\n            ORDER BY b.created_at DESC\n        `));\n\n        return (result.rows as Record<string, unknown>[]).map((row) => ({\n            name: row.name as string,\n            database: row.db_name as string,\n            parentDatabase: row.parent_db as string,\n            createdAt: new Date(row.created_at as string),\n            sizeBytes: row.size_bytes != null ? Number(row.size_bytes) : undefined\n        }));\n    }\n\n    /**\n     * Get info about a specific branch.\n     */\n    async getBranchInfo(name: string): Promise<BranchInfo | undefined> {\n        assertValidBranchName(name);\n\n        const result = await (await this.home.registry()).execute(sql`\n            SELECT\n                b.name,\n                b.db_name,\n                b.parent_db,\n                b.created_at\n            FROM rebase.branches b\n            WHERE b.name = ${name}\n        `);\n\n        const rows = result.rows as Record<string, unknown>[];\n        if (rows.length === 0) return undefined;\n\n        const row = rows[0];\n\n        // Attempt to get size — may fail if the DB was externally dropped.\n        // Same reason as `deleteBranch`: the size of a re-derived name is the\n        // size of some other database, or of nothing.\n        let sizeBytes: number | undefined;\n        try {\n            const dbName = row.db_name as string;\n            const sizeResult = await this.db.execute(\n                sql`SELECT pg_database_size(${dbName}) as size_bytes`\n            );\n            const sizeRows = sizeResult.rows as Record<string, unknown>[];\n            if (sizeRows.length > 0 && sizeRows[0].size_bytes != null) {\n                sizeBytes = Number(sizeRows[0].size_bytes);\n            }\n        } catch {\n            // Database might not exist anymore\n        }\n\n        return {\n            name: row.name as string,\n            database: row.db_name as string,\n            parentDatabase: row.parent_db as string,\n            createdAt: new Date(row.created_at as string),\n            sizeBytes\n        };\n    }\n}\n"],"mappings":"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"}

package/dist/PostgresBackendDriver.d.ts

@@ -3,7 +3,7 @@ import { BranchService } from "./services/BranchService.js";
 import { RealtimeService, type SubscriptionAuthContext } from "./services/realtimeService.js";
 import { DatabasePoolManager } from "./databasePoolManager.js";
 import { DrizzleClient } from "./interfaces.js";
-import { DatabaseAdmin, DataDriver, DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, ListenCollectionProps, ListenOneProps, RebaseCallContext, RebaseServerClient, RebaseSdkData, RestFetchService, BatchWriteProps, SaveManyProps, SaveProps, UpdateManyProps, UpdateRelationPivotProps, DeleteManyProps, TableMetadata, User } from "@rebasepro/types";
+import { DatabaseAdmin, SQLAdmin, DataDriver, DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, ListenCollectionProps, ListenOneProps, RebaseCallContext, RebaseServerClient, RebaseSdkData, RestFetchService, BatchWriteProps, SaveManyProps, SaveProps, SqlScriptResult, UpdateManyProps, UpdateRelationPivotProps, DeleteManyProps, TableMetadata, User } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry.js";
 import { HistoryService } from "./history/HistoryService.js";
 /**
@@ -20,6 +20,16 @@ import { HistoryService } from "./history/HistoryService.js";
  * not be fixed alone and left disagreeing with the rest.
  */
 export declare function isRoleSwitchingOptedOut(): boolean;
+/**
+ * The main database, when this process serves a branch of it.
+ *
+ * `rebase dev` on a checkout switched to a branch connects to the branch, and
+ * names the database it was branched from in `REBASE_BRANCH_PARENT_DATABASE`.
+ * Branches are kept there — the registry, and the default source of a new
+ * one — as they are when the main database itself is served: a branch's own
+ * `rebase.branches` is a snapshot, taken before its row was written.
+ */
+export declare function branchParentDatabase(): string | undefined;
 /**
  * The role a statement will actually have run as, given the role it asked for.
  *
@@ -31,6 +41,17 @@ export declare function isRoleSwitchingOptedOut(): boolean;
 export declare function effectiveSqlRole(requestedRole?: string): string;
 /** How {@link effectiveSqlRole} names "whatever role the connection holds". */
 export declare const CONNECTION_OWNER = "<connection owner>";
+/**
+ * The role a console statement ran as, given the role it asked for — said to
+ * the console with its rows, so it can say when that is not the role picked.
+ *
+ * The requested role whenever role switching is on: a statement that cannot
+ * assume its role is refused, never run as anyone else. With
+ * `DISABLE_DB_ROLE_SWITCHING`, every statement runs as the connection owner,
+ * named by asking a session of its own on the same database — a role the
+ * session already held is then still the one requested.
+ */
+export declare function sqlRoleRanAs(admin: Pick<SQLAdmin, "executeSql">, requestedRole: string, database: string | undefined): Promise<string>;
 /**
  * A statement named a database role the connection cannot assume.
  *
@@ -170,7 +191,7 @@ export declare class PostgresBackendDriver implements DataDriver {
      * collection, not left raw).
      */
     applyAfterReadForRest(rows: Record<string, unknown>[], path: string): Promise<Record<string, unknown>[]>;
-    fetchCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, vectorSearch }: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
+    fetchCollection<M extends Record<string, unknown>>({ path, collection, startAfter, ...query }: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
     /**
      * Listen to a collection: the rows now, then again after every change.
      *
@@ -223,7 +244,43 @@ export declare class PostgresBackendDriver implements DataDriver {
      * collection is readable by its own members in the first place.
      */
     private resolveCallerTenants;
-    save<M extends Record<string, unknown>>({ path, id, values, collection, status, upsert, onConflict }: SaveProps<M>): Promise<Record<string, unknown>>;
+    /**
+     * Where an update reads the row it addresses before writing it.
+     *
+     * The path itself, except through a many-to-many relation: there the path
+     * names the parent's set, and an update may *link* a row that exists but is
+     * not in that set yet (the persistence layer attaches it). Read through the
+     * path, such a row is absent, so it is read from its own collection.
+     */
+    private storedRowPath;
+    /**
+     * The stored row an upsert's key names, if this caller can address it —
+     * with its address and the values to update it with.
+     *
+     * Read as the caller reads: their policies and `beforeQuery` scope. On the
+     * trusted plane for its fields only, like {@link resolveCallerTenants}:
+     * the key columns are the server's to see.
+     *
+     * Soft-deleted rows are read too, and a key one of them holds is refused
+     * with `ROW_IN_TRASH` (see {@link rowInTrashError}). Hidden, it was not
+     * found here, the write went down the create pipeline, and the INSERT's
+     * conflict branch wrote into the trashed row: `201 Created`, hooks told
+     * "new", a second `create` in history, and the row still in the trash.
+     *
+     * `undefined` when the key is incomplete (the write is a plain insert,
+     * which is the persistence layer's rule too), when a key value is not a
+     * plain value, or when no such row is visible. None of those can write a
+     * stored row wrongly: the statement's own conflict branch sets only what
+     * the caller sent, only on a row in their scope, and never on one in the
+     * trash.
+     *
+     * The values drop the key and the conflict target, which the stored row
+     * already has: a natural-key upsert carrying a key the caller invented
+     * must not move the row onto it.
+     */
+    private findUpsertTarget;
+    save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    private saveInFrame;
     /**
      * Write many rows through the same pipeline as {@link save}.
      *
@@ -298,11 +355,25 @@ export declare class PostgresBackendDriver implements DataDriver {
      * body that cannot work never costs a rollback.
      */
     batchWrite<M extends Record<string, unknown>>({ operations }: BatchWriteProps<M>): Promise<(Record<string, unknown> | null)[]>;
-    delete<M extends Record<string, unknown>>({ row, collection, hard }: DeleteProps<M>): Promise<void>;
+    delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
+    private deleteInFrame;
     deleteAll(path: string): Promise<void>;
     updateRelationPivot({ path, targetId, pivot }: UpdateRelationPivotProps): Promise<void>;
     checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
     count<M extends Record<string, unknown>>({ path, collection, filter, logical, searchString, vectorSearch, withDeleted }: FetchCollectionProps<M>): Promise<number>;
+    /** The answer to {@link appDatabaseName}, once it has been given. */
+    private appDatabase?;
+    /**
+     * The database this driver's own connection is on: the app's, which every
+     * data request and the CMS read and write.
+     *
+     * Asked of the connection rather than read off the admin connection
+     * string, which can name another database — the server's `postgres`, or
+     * the main database while this process runs on a branch. The SQL console
+     * preselects this name, a statement sent to it runs on this connection,
+     * and branching copies it by default.
+     */
+    appDatabaseName(): Promise<string>;
     private getTargetDb;
     /**
      * Build one statement, binding `$n` placeholders as real parameters.
@@ -316,7 +387,48 @@ export declare class PostgresBackendDriver implements DataDriver {
         database?: string;
         role?: string;
         params?: unknown[];
+        isolateSession?: boolean;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * Run a script a person wrote — the Studio console — and describe its
+     * result. See `SQLAdmin.runSqlScript` and `services/sql-script.ts`.
+     */
+    runSqlScript(sqlText: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<SqlScriptResult>;
+    /**
+     * `SET ROLE` for the rest of a session of a script's own — not `SET LOCAL`
+     * inside a transaction, which a `COMMIT` in the script ends, and every
+     * statement after it ran as the connection owner. The session is reset
+     * after the script, so the role does not outlive it.
+     *
+     * The same refusals as {@link executeSqlOn}: a role the session already
+     * has is no switch; `DISABLE_DB_ROLE_SWITCHING` runs as the owner on
+     * purpose; and a connection that may not `SET ROLE` refuses, never falls
+     * back to the owner.
+     */
+    private assumeSessionRole;
+    /**
+     * Run `fn` on a session of its own, and put that session back the way it
+     * was handed out before anything else can use it.
+     *
+     * For SQL a person wrote — the Studio editor. It may `SET ROLE`,
+     * `SET SESSION AUTHORIZATION` or `set_config(…, false)`, which outlive the
+     * statement (and a transaction's commit) and stay on the connection. On a
+     * pooled one they were inherited by whatever checked it out next: an auth
+     * lookup, the job store or history running as `rebase_user`, on one
+     * connection in N, until a restart. `SET SESSION AUTHORIZATION DEFAULT`
+     * clears the role as well, which `RESET ALL` does not.
+     *
+     * On a pool, `role` is assumed for the whole session, and a transaction
+     * the SQL leaves open is rolled back and the run refused — see
+     * `onOwnSession`. `fn` is then handed no role: there is nothing left to
+     * switch. A handle that is already one session (PGlite in process, a
+     * single client) is reset in place, and `fn` switches the role itself.
+     */
+    private onIsolatedSession;
+    private executeSqlOn;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     /**

package/dist/auth/services.d.ts

@@ -1,7 +1,6 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { type RebasePgTable } from "../types.js";
-import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, RefreshTokenSession, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server";
-export type { Role };
+import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RefreshTokenInfo, RefreshTokenSession, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, AccountAccessState, PendingEmailChange } from "@rebasepro/server";
 export interface AuthSchemaTables {
     users: RebasePgTable;
     refreshTokens: RebasePgTable;
@@ -38,6 +37,8 @@ export declare class UserService implements UserRepository {
     private db;
     private usersTable;
     private userIdentitiesTable;
+    /** Read by `getAccountAccessState`, to say whether one sign-in is still live. */
+    private refreshTokensTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedUsersTableName;
     /**
@@ -73,15 +74,21 @@ export declare class UserService implements UserRepository {
     getUserByEmail(email: string): Promise<UserData | null>;
     getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
     getUserIdentities(uid: string): Promise<UserIdentityData[]>;
+    /**
+     * @see UserRepository.unlinkUserIdentity — scoped to the user as well as
+     * the identity, so it can only ever detach an identity from the account
+     * it names.
+     */
+    unlinkUserIdentity(uid: string, provider: string, providerId: string): Promise<void>;
     linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
     deleteUser(id: string): Promise<void>;
     listUsers(): Promise<UserData[]>;
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
     /**
-     * Update user's password hash
+     * Update user's password hash; `null` removes the password.
      */
-    updatePassword(id: string, passwordHash: string): Promise<void>;
+    updatePassword(id: string, passwordHash: string | null): Promise<void>;
     /**
      * Set email verification status
      */
@@ -94,10 +101,6 @@ export declare class UserService implements UserRepository {
      * Find user by email verification token
      */
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-    /**
-     * Get roles for a user from database (inline TEXT[] column)
-     */
-    getUserRoles(uid: string): Promise<Role[]>;
     /**
      * Get role IDs for a user
      */
@@ -110,12 +113,53 @@ export declare class UserService implements UserRepository {
      * Assign a specific role to new user (appends if not present)
      */
     assignDefaultRole(uid: string, roleId: string): Promise<void>;
+    /**
+     * One read of what an access token is judged against: whether the account
+     * exists, its roles, and its revocation watermark. See
+     * `TokenRepository.getAccountAccessState`.
+     *
+     * The watermark is read only where the table declares it, as
+     * `RefreshTokenService.getTokensValidAfter` reads it — a table without the
+     * column has no watermark rather than an error on every request.
+     */
+    getAccountAccessState(uid: string, sessionId?: string): Promise<AccountAccessState | null>;
+    /**
+     * Whether the users table has `disabled_at`. `ensureAuthTablesExist` adds
+     * it to every auth table at boot, but the app's own drizzle object may
+     * predate it, so the database is asked — once — rather than the object.
+     */
+    private disabledColumn?;
+    private hasDisabledColumn;
+    /**
+     * Whether the users table has the address-change columns. Added at boot to
+     * every auth table, but the app's drizzle object never declares them, so
+     * the database is asked — once — as for `disabled_at`.
+     */
+    private emailChangeColumns?;
+    private hasEmailChangeColumns;
+    private requireEmailChangeColumns;
+    /** @see UserRepository.setPendingEmailChange */
+    setPendingEmailChange(uid: string, change: {
+        email: string;
+        tokenHash: string;
+    } | null): Promise<void>;
+    /** @see UserRepository.getPendingEmailChange */
+    getPendingEmailChange(uid: string): Promise<PendingEmailChange | null>;
+    /** @see UserRepository.findPendingEmailChange */
+    findPendingEmailChange(tokenHash: string): Promise<{
+        user: UserData;
+        change: PendingEmailChange;
+    } | null>;
+    /** @see UserRepository.applyPendingEmailChange — one write, held to the token. */
+    applyPendingEmailChange(uid: string, tokenHash: string): Promise<UserData | null>;
+    /** @see UserRepository.setUserDisabled */
+    setUserDisabled(uid: string, disabled: boolean): Promise<void>;
     /**
      * Get user with their roles
      */
     getUserWithRoles(uid: string): Promise<{
         user: UserData;
-        roles: Role[];
+        roles: string[];
     } | null>;
 }
 export declare class RefreshTokenService {
@@ -132,7 +176,7 @@ export declare class RefreshTokenService {
     private col;
     /** The columns to read back, narrowed to the ones this table has. */
     private selection;
-    createToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    createToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<boolean>;
     /**
      * Build a {@link RefreshTokenInfo} out of a row of {@link selection}.
      *
@@ -161,7 +205,17 @@ export declare class RefreshTokenService {
      * for the crime of losing a response.
      */
     markRotated(tokenHash: string): Promise<void>;
-    /** Final kill of one sign-in: logout, or revoking a device remotely. */
+    /**
+     * Final kill of one sign-in: logout, or revoking a device remotely.
+     *
+     * Lock first, write second, in one transaction. A rotation in flight
+     * holds a share lock on its parent — a row of this session — until the
+     * token it mints is committed (see `createToken`), so the lock here waits
+     * for it, and the write, being a new statement, reads a snapshot that has
+     * that token in it. A lone UPDATE would work from a snapshot taken before
+     * the token existed and leave it live: the sign-out a refresh in flight
+     * used to undo.
+     */
     revokeSession(sessionId: string): Promise<void>;
     /**
      * Housekeeping: rotation would otherwise leave a row per refresh forever.
@@ -175,6 +229,12 @@ export declare class RefreshTokenService {
     deleteAllForUser(uid: string): Promise<void>;
     listForUser(uid: string): Promise<RefreshTokenInfo[]>;
     deleteById(id: string, uid: string): Promise<void>;
+    /**
+     * Every token past its expiry, whoever holds it. `prune` clears a user's
+     * expired rows when that user refreshes; a session nobody comes back to
+     * is only ever cleared here.
+     */
+    deleteExpired(): Promise<void>;
 }
 /**
  * Password reset token service
@@ -219,6 +279,8 @@ export declare class MagicLinkTokenService {
     private getQualifiedTableName;
     createToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidByHash(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
+    /** Links and email codes past their expiry, used or not. */
+    deleteExpired(): Promise<void>;
     markAsUsed(tokenHash: string): Promise<void>;
 }
 /**
@@ -231,7 +293,7 @@ export declare class PostgresTokenRepository implements TokenRepository {
     private passwordResetTokenService;
     private magicLinkTokenService;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
-    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<boolean>;
     markRefreshTokenRotated(tokenHash: string): Promise<void>;
     revokeRefreshTokenSession(sessionId: string): Promise<void>;
     pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
@@ -246,6 +308,10 @@ export declare class PostgresTokenRepository implements TokenRepository {
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
     deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
+    /**
+     * @see TokenRepository.deleteExpiredTokens — reset links, magic links and
+     * email codes, and refresh tokens, each past its own expiry.
+     */
     deleteExpiredTokens(): Promise<void>;
     createMagicLinkToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
@@ -267,28 +333,35 @@ export declare class PostgresAuthRepository implements AuthRepository {
     getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
     getUserIdentities(uid: string): Promise<UserIdentityData[]>;
     linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    unlinkUserIdentity(uid: string, provider: string, providerId: string): Promise<void>;
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
     deleteUser(id: string): Promise<void>;
     listUsers(): Promise<UserData[]>;
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
-    updatePassword(id: string, passwordHash: string): Promise<void>;
+    updatePassword(id: string, passwordHash: string | null): Promise<void>;
     setEmailVerified(id: string, verified: boolean): Promise<void>;
     setVerificationToken(id: string, token: string | null): Promise<void>;
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-    getUserRoles(uid: string): Promise<RoleData[]>;
     getUserRoleIds(uid: string): Promise<string[]>;
     setUserRoles(uid: string, roleIds: string[]): Promise<void>;
     assignDefaultRole(uid: string, roleId: string): Promise<void>;
     getUserWithRoles(uid: string): Promise<{
         user: UserData;
-        roles: RoleData[];
+        roles: string[];
+    } | null>;
+    getAccountAccessState(uid: string, sessionId?: string): Promise<AccountAccessState | null>;
+    setUserDisabled(uid: string, disabled: boolean): Promise<void>;
+    setPendingEmailChange(uid: string, change: {
+        email: string;
+        tokenHash: string;
+    } | null): Promise<void>;
+    getPendingEmailChange(uid: string): Promise<PendingEmailChange | null>;
+    findPendingEmailChange(tokenHash: string): Promise<{
+        user: UserData;
+        change: PendingEmailChange;
     } | null>;
-    getRoleById(id: string): Promise<RoleData | null>;
-    listRoles(): Promise<RoleData[]>;
-    createRole(_data: CreateRoleData): Promise<RoleData>;
-    updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
-    deleteRole(_id: string): Promise<void>;
-    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    applyPendingEmailChange(uid: string, tokenHash: string): Promise<UserData | null>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<boolean>;
     markRefreshTokenRotated(tokenHash: string): Promise<void>;
     revokeRefreshTokenSession(sessionId: string): Promise<void>;
     pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
@@ -357,13 +430,17 @@ export declare class MfaService implements MfaRepository {
     createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
     getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
     /**
-     * Count one failed guess against a challenge and report the new total.
+     * Count one guess against a challenge and report the new total. The route
+     * claims it before judging the code, so the total it returns is what the
+     * cap is decided on.
      *
      * Incremented in the database rather than in the route so that guesses
      * arriving in parallel — the shape any real brute-force takes — cannot
      * share a single increment.
      */
     recordMfaChallengeAttempt(challengeId: string): Promise<number>;
+    /** Challenges past their five minutes, answered or not. */
+    deleteExpiredChallenges(): Promise<void>;
     verifyMfaChallenge(challengeId: string): Promise<void>;
     createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
     useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;