@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g18cfeb7

package/src/PostgresBootstrapper.ts

@@ -37,7 +37,7 @@ import { ensureHistoryTableExists } from "./history/ensure-history-table";
 import { patchPgArrayNullSafety } from "./utils/pg-array-null-patch";
 import { buildCollectionsFromSchema, introspectSchema, readRlsStatus } from "./schema/introspect-runtime";
 import { buildDrizzleTablesFromSchema, buildDrizzleRelationsFromSchema } from "./schema/dynamic-tables";
-import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, REBASE_USER_ROLE, type RawSqlRunner } from "./security/rls-enforcement";
+import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, warnOnLegacyRlsFunctions, warnOnRoleSchemaCollision, REBASE_USER_ROLE, type RawSqlRunner } from "./security/rls-enforcement";
 import { provisionTriggerCdc, type CdcTableRef } from "./services/cdc/trigger-cdc";
 import { collectJunctionLinks } from "./services/cdc/junction-tables";
 import { createChannelBus, resolveChannelBusSetting } from "./services/channel-bus";
@@ -372,12 +372,22 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                     const res = await schemaAwareDb.execute(sql.raw(text));
                     return (res.rows ?? []) as Record<string, unknown>[];
                 };
+                // Said before anything else touches the schema: if the role and
+                // a schema share a name, unqualified SQL from any tool that does
+                // not pin `search_path` has been landing in the wrong place, and
+                // that is worth knowing before reading the drift report below.
+                await warnOnRoleSchemaCollision(runSql);
+
                 const posture = await detectConnectionPosture(runSql);
                 if (posture.privileged) {
                     const collectionSchemas = registry.getCollections()
                         .map((c) => (c as { schema?: string }).schema)
                         .filter((s): s is string => typeof s === "string");
-                    await ensureAppRole(runSql, ["public", "rebase", "auth", ...collectionSchemas]);
+                    // `auth` is deliberately absent: the RLS helpers moved into
+                    // `rebase`, and granting USAGE on a schema Rebase does not
+                    // own would, on a Supabase database, hand the end-user role
+                    // access to theirs.
+                    await ensureAppRole(runSql, ["public", "rebase", ...collectionSchemas]);
                     driver.rlsUserRole = REBASE_USER_ROLE;
                     realtimeService.rlsUserRole = REBASE_USER_ROLE;
                     logger.info(`🔐 RLS enforcement active: authenticated requests run as "${REBASE_USER_ROLE}" (connection "${posture.role}" bypasses RLS: ${posture.superuser ? "superuser" : posture.bypassRLS ? "BYPASSRLS" : "table owner"})`);
@@ -406,6 +416,11 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                 // a rule that reads as "signed in only" but is true for every
                 // caller grants the data away rather than hiding it.
                 warnOnAnonymousGrants(registry.getCollections() as never);
+
+                // Raw policy SQL written against the pre-1.0 helper schema. It
+                // is rewritten on compile, so this is the only place the project
+                // is ever told the spelling moved.
+                warnOnLegacyRlsFunctions(registry.getCollections() as never);
             }
 
             // Ensure branch metadata table exists when branching is available
@@ -870,6 +885,30 @@ schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection))
                     `🔐 [rls] Could not fully apply policies to "${failure.table}" — it stays locked (denies) until this is resolved: ${failure.error}`
                 );
             }
+
+            // Retire the pre-1.0 `auth` schema now that the policies above no
+            // longer call into it. Deliberately after, and deliberately quiet:
+            // Postgres refuses to drop a function an RLS policy still
+            // references, so on a database where some table has not been
+            // recompiled yet this is expected to fail and succeed on a later
+            // boot. See DROP_LEGACY_AUTH_SCHEMA_SQL for the guards that keep it
+            // off a Supabase `auth` schema.
+            try {
+                const { dropLegacyAuthSchema } = await import("./schema/rls-bootstrap-sql");
+                await dropLegacyAuthSchema(
+                    async (text) => {
+                        const res = await internals.db.execute(sql.raw(text));
+                        return (res.rows ?? []) as Record<string, unknown>[];
+                    },
+                    { info: (m) => logger.info(m), warn: (m) => logger.warn(m) }
+                );
+            } catch (err) {
+                logger.info(
+                    "Left the legacy `auth` schema in place: " +
+                    (err instanceof Error ? err.message : String(err))
+                );
+            }
+
             return { applied: outcome.policiesApplied };
         },
 

package/src/auth/ensure-tables.ts

@@ -1,7 +1,10 @@
 import { sql } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { logger } from "@rebasepro/server";
+import { revokeInternalTableAccess } from "@rebasepro/common";
 import type { CollectionConfig } from "@rebasepro/types";
+import { AUTH_USERS_COLUMNS, authUsersColumnSql } from "../schema/auth-users-columns";
+import { RLS_BOOTSTRAP_STATEMENTS } from "../schema/rls-bootstrap-sql";
 import {
     AuthSchemaVersionError,
     assertAuthSchemaCompatible,
@@ -44,13 +47,23 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 ? `"${resolvedTable}"`
                 : `"${usersSchema}"."${resolvedTable}"`;
 
-            // Derive ID column type from collection properties
+            // Derive ID column type from collection properties.
+            //
+            // `"increment"`, not `"autoincrement"`. The latter was tested for
+            // here and exists nowhere in the type system — the union is
+            // `boolean | "manual" | "increment" | string` — so the INTEGER branch
+            // was unreachable and an integer-keyed auth collection fell through
+            // to TEXT. Introspection below hid it whenever the table already
+            // existed; on a database where it did not, this created
+            // `id TEXT DEFAULT gen_random_uuid()::text` for a collection that
+            // declares a number, and every `uid` foreign key was typed to match
+            // the wrong thing.
             const idProp = collection.properties?.id;
             if (idProp) {
                 const isId = ("isId" in idProp) ? (idProp as unknown as Record<string, unknown>).isId : undefined;
                 if (isId === "uuid") {
                     userIdType = "UUID";
-                } else if (isId === "autoincrement") {
+                } else if (isId === "increment") {
                     userIdType = "INTEGER";
                 }
                 // Otherwise keep TEXT as default
@@ -129,22 +142,24 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // and long signed URLs that OAuth providers hand back. A limit worth
         // having is a CHECK — alterable without a table rewrite, unlike a type
         // modifier — which is why `email` has one and nothing else does.
+        //
+        // The column list comes from AUTH_USERS_COLUMNS rather than being spelled
+        // out here, because this is not the only place that creates this table:
+        // `db push` and the boot-time collection ensure do too, and when the
+        // three lists were maintained separately they disagreed and boot order
+        // silently decided which shape the database got. The `email` CHECK is
+        // appended rather than listed there — it is a named constraint the
+        // migration below has to be able to add separately, `NOT VALID`, to a
+        // table that already holds rows.
+        const usersColumnDdl = AUTH_USERS_COLUMNS
+            .map((spec) => spec.column === "email"
+                ? `${spec.column} ${authUsersColumnSql(spec)} CONSTRAINT ${emailLengthConstraint} CHECK (length(email) <= 320)`
+                : `${spec.column} ${authUsersColumnSql(spec)}`)
+            .join(",\n                ");
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(usersTableName)} (
                 id ${sql.raw(userIdType)} PRIMARY KEY ${sql.raw(idDefault)},
-                email TEXT NOT NULL CONSTRAINT ${sql.raw(emailLengthConstraint)} CHECK (length(email) <= 320),
-                display_name TEXT,
-                photo_url TEXT,
-                roles TEXT[] DEFAULT '{}' NOT NULL,
-                password_hash TEXT,
-                email_verified BOOLEAN DEFAULT FALSE NOT NULL,
-                email_verification_token TEXT,
-                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
+                ${sql.raw(usersColumnDdl)}
             )
         `);
 
@@ -164,26 +179,51 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // column once no old backend remains (phase 2, contract).
         //
         // Idempotent throughout: every step is guarded on catalogue state.
-        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 [
+        const legacyFkTables = [
             "user_identities",
             "refresh_tokens",
             "password_reset_tokens",
             "magic_link_tokens",
             "mfa_factors",
             "recovery_codes"
-        ]) {
+        ];
+
+        // Only on a database that actually carries the legacy column. This whole
+        // block is a 0.x compatibility shim, and it used to run unconditionally —
+        // so every brand-new database was provisioned with a trigger function
+        // written to reconcile a column it can never have, permanently, as part
+        // of its first boot. A fresh install should not ship someone else's
+        // migration history.
+        // The table list is inlined rather than bound: drizzle expands a JS
+        // array into a parameter TUPLE — `ANY(($2, $3, …))` — which Postgres
+        // rejects, and the thrown error is swallowed by the catch around this
+        // whole function, so auth would silently stop provisioning. These are
+        // module-level constants, not input.
+        const legacyFkTableList = legacyFkTables.map(t => `'${t}'`).join(", ");
+        const legacyUserIdPresent = await db.execute(sql`
+            SELECT 1
+            FROM information_schema.columns
+            WHERE table_schema = ${authSchema}
+              AND table_name IN (${sql.raw(legacyFkTableList)})
+              AND column_name = 'user_id'
+            LIMIT 1
+        `);
+
+        if (legacyUserIdPresent.rows.length > 0) {
+            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 legacyUserIdPresent.rows.length > 0 ? legacyFkTables : []) {
             const qualified = `"${authSchema}"."${authTable}"`;
             await db.execute(sql`
                 DO $$
@@ -335,39 +375,21 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             )
         `);
 
-        // Create the `auth` schema with PostgreSQL RLS helper functions.
-        await db.execute(sql`CREATE SCHEMA IF NOT EXISTS auth`);
-
-        // Use an advisory transaction lock to serialize function recreation during HMR
+        // The RLS helper functions every generated policy calls. They live in
+        // `rebase`, alongside the tables above — Rebase creates exactly one
+        // schema in a user's database. Advisory-locked so concurrent HMR
+        // reloads cannot race on `CREATE OR REPLACE`.
+        //
+        // The same statements the migration preamble carries, from the same
+        // constant — these definitions being identical across the boot path and
+        // the migration stream is the whole point of having them in one place.
+        // One call per statement: this handle speaks the extended query
+        // protocol, which rejects multi-command strings.
         await db.transaction(async (tx) => {
             await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext('rebase_auth_functions_init'))`);
-
-            // Falls back to the pre-rename `app.user_id` so a database that has
-            // taken the new schema but is still served by an older backend keeps
-            // resolving the principal. Keep in sync with AUTH_BOOTSTRAP_SQL.
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$
-                    SELECT COALESCE(
-                        NULLIF(current_setting('app.uid', true), ''),
-                        NULLIF(current_setting('app.user_id', true), '')
-                    );
-                $$ LANGUAGE sql STABLE
-            `);
-
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$
-                    SELECT COALESCE(
-                        NULLIF(current_setting('app.jwt', true), ''),
-                        '{}'
-                    )::jsonb;
-                $$ LANGUAGE sql STABLE
-            `);
-
-            await tx.execute(sql`
-                CREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$
-                    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');
-                $$ LANGUAGE sql STABLE
-            `);
+            for (const statement of RLS_BOOTSTRAP_STATEMENTS) {
+                await tx.execute(sql.raw(statement));
+            }
         });
 
         // Seed default roles if none exist
@@ -378,26 +400,16 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // database provisioned by an older framework era is missing every
         // column added since. Each column the auth services read or write must
         // be back-filled here, or upgraded deployments break on the first
-        // statement that references it. `email` is deliberately absent: it has
-        // existed since the first era and cannot be added NOT NULL safely.
-        const userColumnBackfills = [
-            "display_name TEXT",
-            "photo_url TEXT",
-            "roles TEXT[] DEFAULT '{}' NOT NULL",
-            "password_hash TEXT",
-            "email_verified BOOLEAN DEFAULT FALSE NOT NULL",
-            "email_verification_token TEXT",
-            "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"
-        ];
-        for (const columnDef of userColumnBackfills) {
+        // statement that references it.
+        //
+        // `email` is skipped: it has existed since the first era, so it is never
+        // the missing one, and `ADD COLUMN … NOT NULL` with no default fails on
+        // a table with rows.
+        for (const spec of AUTH_USERS_COLUMNS) {
+            if (spec.column === "email") continue;
             await db.execute(sql`
                 ALTER TABLE ${sql.raw(usersTableName)}
-                ADD COLUMN IF NOT EXISTS ${sql.raw(columnDef)}
+                ADD COLUMN IF NOT EXISTS ${sql.raw(`${spec.column} ${authUsersColumnSql(spec)}`)}
             `);
         }
 
@@ -407,14 +419,69 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // statement past this point has to tolerate that rather than abort the
         // whole migration block.
         const usersColumns = await db.execute(sql`
-            SELECT column_name, data_type
+            SELECT column_name, data_type, is_nullable, column_default
             FROM information_schema.columns
             WHERE table_schema = ${usersSchema} AND table_name = ${resolvedTable}
         `);
-        const usersColumnTypes = new Map(
-            (usersColumns.rows as { column_name: string; data_type: string }[])
-                .map(row => [row.column_name, row.data_type])
-        );
+        type UsersColumnRow = {
+            column_name: string;
+            data_type: string;
+            is_nullable: "YES" | "NO";
+            column_default: string | null;
+        };
+        const usersColumnRows = usersColumns.rows as UsersColumnRow[];
+        const usersColumnTypes = new Map(usersColumnRows.map(row => [row.column_name, row.data_type]));
+        const usersColumnState = new Map(usersColumnRows.map(row => [row.column_name, row]));
+
+        // ── Migration: restore defaults and NOT NULL that another creator dropped ──
+        // `ADD COLUMN IF NOT EXISTS` above only creates what is MISSING. A column
+        // that exists with the wrong shape stays wrong forever — and until
+        // AUTH_USERS_COLUMNS became the single source, that was the normal
+        // outcome rather than an edge case: whichever of `db push`, boot-ensure
+        // and this function reached the table first decided its constraints, so
+        // a managed deploy ended up with a nullable `email`, a `roles` with no
+        // `'{}'` default, and an `email_verified` that could be NULL.
+        //
+        // Ordered DEFAULT → back-fill → SET NOT NULL, because SET NOT NULL is
+        // checked against existing rows: without the back-fill it throws on the
+        // very databases that need it. `email` can carry no default, so a NULL
+        // there is not repairable automatically — say so and leave the column
+        // alone rather than inventing an address.
+        for (const spec of AUTH_USERS_COLUMNS) {
+            const state = usersColumnState.get(spec.column);
+            if (!state) continue;
+
+            if (spec.default !== undefined && state.column_default === null) {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ALTER COLUMN ${sql.raw(`"${spec.column}"`)} SET DEFAULT ${sql.raw(spec.default)}
+                `);
+                logger.info(`🔧 Restored the default on ${usersTableName}.${spec.column}`);
+            }
+
+            if (!spec.notNull || state.is_nullable !== "YES") continue;
+
+            if (spec.default !== undefined) {
+                await db.execute(sql`
+                    UPDATE ${sql.raw(usersTableName)}
+                    SET ${sql.raw(`"${spec.column}"`)} = ${sql.raw(spec.default)}
+                    WHERE ${sql.raw(`"${spec.column}"`)} IS NULL
+                `);
+            }
+            try {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ALTER COLUMN ${sql.raw(`"${spec.column}"`)} SET NOT NULL
+                `);
+                logger.info(`🔧 Restored NOT NULL on ${usersTableName}.${spec.column}`);
+            } catch (err) {
+                logger.warn(
+                    `⚠️ ${usersTableName}.${spec.column} should be NOT NULL but still holds NULLs, so the ` +
+                    "constraint was not applied. Fill or remove those rows and restart: " +
+                    (err instanceof Error ? err.message : String(err))
+                );
+            }
+        }
 
         // ── Migration: VARCHAR(n) → TEXT on the users string columns ────────
         // Tables created before the widths came off still carry them. Postgres
@@ -717,15 +784,22 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // registration after an upgrade fails with SQLSTATE 42501. Reconcile
         // on boot; only tables actually flagged get the ALTER (and its lock).
         try {
+            // Every table this function creates, not a subset. `magic_link_tokens`
+            // and `schema_meta` were missing here while their six siblings were
+            // listed — so on a database carrying FORCE from the older RLS model,
+            // magic-link sign-in kept failing 42501 after the upgrade that was
+            // supposed to fix exactly that, and only for the one auth method.
             const authTablePairs: [string, string][] = [
                 [usersSchema, resolvedTable],
                 [authSchema, "user_identities"],
                 [authSchema, "refresh_tokens"],
                 [authSchema, "password_reset_tokens"],
+                [authSchema, "magic_link_tokens"],
                 [authSchema, "app_config"],
                 [authSchema, "mfa_factors"],
                 [authSchema, "mfa_challenges"],
-                [authSchema, "recovery_codes"]
+                [authSchema, "recovery_codes"],
+                [authSchema, "schema_meta"]
             ];
             for (const [schemaName, tableName] of authTablePairs) {
                 const forced = await db.execute(sql`
@@ -756,10 +830,35 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             );
         }
 
-        // Stamped last, so a boot that died partway through the migrations above
-        // leaves the older stamp in place and the next boot runs them again.
+        // Stamped last of the MIGRATIONS, so a boot that died partway through
+        // the ones above leaves the older stamp in place and the next boot runs
+        // them again.
         await stampAuthSchemaVersion(db, authSchema);
 
+        // ── Keep the end-user role out of auth's tables ─────────────────────
+        // These carry session token hashes, TOTP secrets and recovery codes, and
+        // none of them has RLS — they are not collections, so nothing ever
+        // compiled a policy for them. Meanwhile the role provisioning grants
+        // `rebase_user` DML on every table in this schema, and its
+        // ALTER DEFAULT PRIVILEGES reaches the ones created right here, after it
+        // ran. So the grant has to come back off; see `revokeInternalTableSql`
+        // for why a revoke rather than an empty RLS policy set.
+        //
+        // After the stamp deliberately: `schema_meta` is created BY the stamp,
+        // so revoking first would leave the one table holding this database's
+        // schema version writable by every signed-in user until the next boot.
+        // Nothing below re-runs the migrations, so the stamp's guarantee holds.
+        await revokeInternalTableAccess(
+            async (text) => { await db.execute(sql.raw(text)); },
+            authSchema,
+            {
+                onError: (table, err) => logger.warn(
+                    `🔐 Could not revoke authenticated-role access to "${authSchema}"."${table}": ` +
+                    (err instanceof Error ? err.message : String(err))
+                )
+            }
+        );
+
         logger.info("✅ Auth tables ready");
     } catch (error) {
         // The one failure that must not be survived. Continuing here is what

package/src/cli-helpers.ts

@@ -86,10 +86,16 @@ export function resolveLocalBin(binName: string): string | null {
     return null;
 }
 
-export async function getTableIncludesFromCollections(collections: CollectionConfig[]): Promise<string[]> {
-    const { getTableName, resolveCollectionRelations } = await import("@rebasepro/common");
+export async function getTableIncludesFromCollections(allCollections: CollectionConfig[]): Promise<string[]> {
+    const { getTableName, resolveCollectionRelations, relationalCollections } = await import("@rebasepro/common");
     const { isPostgresCollectionConfig } = await import("@rebasepro/types");
 
+    // The include list is the inverse of {@link getTableExcludes}: a name on it
+    // is a name Atlas is allowed to drop. A Firestore collection called
+    // `exercises` must not put `public.exercises` here — a real, unrelated table
+    // of that name would lose its protection and be dropped by the next
+    // auto-approved `db push`.
+    const collections = relationalCollections(allCollections);
     const includes: string[] = [];
     for (const col of collections) {
         const tableName = getTableName(col);
@@ -249,13 +255,20 @@ export async function getTableExcludes(
     const queryTables = deps.queryExistingTables ?? queryExistingTables;
 
     const includes = await getIncludes(collectionsPath);
-    // Framework-owned schemas Rebase manages itself — the declarative apply
-    // must never touch them. `auth` holds the helper functions; `rebase` holds
-    // the auth tables (users, refresh_tokens, …) and Atlas's own revision
-    // table. Excluding both the schema object AND its contents keeps Atlas
-    // from planning a `DROP SCHEMA … CASCADE` — which on a live database would
-    // take the user/auth tables with it. `atlas_schema_revisions.*` is kept
-    // for backwards-compatibility with any external revision schema.
+    // Schemas the declarative apply must never touch. `rebase` holds the auth
+    // tables (users, refresh_tokens, …), the RLS helper functions and Atlas's
+    // own revision table. Excluding both the schema object AND its contents
+    // keeps Atlas from planning a `DROP SCHEMA … CASCADE` — which on a live
+    // database would take the user/auth tables with it.
+    // `atlas_schema_revisions.*` is kept for backwards-compatibility with any
+    // external revision schema.
+    //
+    // `auth` stays on this list even though Rebase no longer creates it, and
+    // that is the point: on a database still holding the pre-1.0 schema it must
+    // survive until the guarded cleanup retires it, and on a Supabase database
+    // it is somebody else's and must never be in scope at all. Removing it here
+    // would let a `db push` plan `DROP SCHEMA auth CASCADE` against a live
+    // Supabase installation.
     const excludes: string[] = ["atlas_schema_revisions.*", "auth", "auth.*", "rebase", "rebase.*"];
 
     let existingTables: string[];