@rebasepro/server-postgres 0.10.1-canary.6f89f77 → 0.10.1-canary.7801eed

package/dist/utils/drizzle-conditions.d.ts

@@ -1,6 +1,6 @@
 import { SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { FilterValues, WhereFilterOp, Relation, LogicalCondition, FilterCondition } from "@rebasepro/types";
+import { FilterValues, WhereFilterOp, LogicalCondition, FilterCondition, ResolvedRelation } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 /** Drizzle dynamic query builder — accepts innerJoin + where chaining */
 export interface DrizzleDynamicQuery {
@@ -18,6 +18,47 @@ export interface DrizzleDynamicQuery {
  * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;
  */
 export declare class DrizzleConditionBuilder {
+    /**
+     * Express "reachable from this parent through this relation" as a plain
+     * `WHERE` condition on the target table.
+     *
+     * This is the primitive that lets a relation be a *filter* rather than an
+     * addressing scheme. A nested listing used to be served by its own query
+     * builder — `fetchEntitiesUsingJoins`, which grew joins the root pipeline
+     * did not have and lost the options the root pipeline did have (offset,
+     * filter, orderBy, include). Reduced to a condition, the same listing runs
+     * through the ordinary collection query, so it inherits all of them and
+     * there is one read path instead of two.
+     *
+     * The shapes:
+     *   - inverse FK  → `target.<fk> = :parentId`, a column comparison.
+     *   - `through`   → `EXISTS (SELECT 1 FROM junction …)`, correlated on the
+     *                   target's key, so the junction never multiplies rows the
+     *                   way an `INNER JOIN` would.
+     *   - `joinPath`  → the same `EXISTS`, with the path's steps joined inside
+     *                   it and the final step correlating to the outer row.
+     */
+    static buildRelationScopeCondition(relation: ResolvedRelation, 
+    /**
+     * Lazy: only `via` and `belongsTo` need the parent's own table. A
+     * foreign key on the target and a junction are both expressible from
+     * the parent's *id* alone, and requiring the table for them would make
+     * a child listing fail on a parent whose table isn't registered.
+     */
+    parent: () => {
+        table: PgTable<any>;
+        idColumn: AnyPgColumn;
+    }, parentId: string | number, targetTable: PgTable<any>, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): SQL;
+    /**
+     * `EXISTS` for an explicit `joinPath`.
+     *
+     * The path is declared source → target. The subquery replays every step but
+     * the last from inside, and turns the last one into the correlation with the
+     * outer target row — so the target table is never named twice and needs no
+     * alias. Each intermediate table is aliased positionally, which keeps a path
+     * that revisits a table (a self-referencing many-to-many) unambiguous.
+     */
+    private static buildJoinPathScopeCondition;
     /**
      * Build filter conditions from FilterValues
      */
@@ -33,7 +74,21 @@ export declare class DrizzleConditionBuilder {
     /**
      * Build relation-based conditions for different relation types
      */
-    static buildRelationConditions(relation: Relation, parentId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): {
+    /**
+     * Joins and where-conditions that reach a relation's target rows.
+     *
+     * One case per kind. This used to be a chain of six `else if`s over
+     * `cardinality`/`direction`/`through`, ending in
+     * `findCorrespondingJunctionTable` — a search through the *target's* own
+     * relations to work out whether an "inverse many" was a one-to-many or the
+     * far side of a junction. That search is gone: the kind says which it is.
+     *
+     * The owning/inverse split for junctions is gone too. Both variants built
+     * the identical condition — `through` is always written from the declaring
+     * side's point of view — so the second was a distinction without a
+     * difference and one of the places the two could drift apart.
+     */
+    static buildRelationConditions(relation: ResolvedRelation, parentId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): {
         joinConditions: {
             table: PgTable<any>;
             condition: SQL;
@@ -57,11 +112,13 @@ export declare class DrizzleConditionBuilder {
      */
     private static buildJunctionTableConditions;
     /**
-     * Build conditions for inverse junction table (many-to-many) relations
-     */
-    private static buildInverseJunctionTableConditions;
-    /**
-     * Build conditions for simple relations (owning/inverse without join paths)
+     * The condition for a relation whose link is a single column.
+     *
+     * Two cases. It had five: two of them existed only to throw ("should not be
+     * called directly", "lacks proper configuration"), and one guessed a column
+     * name by appending `_id` to `inverseRelationName` when no foreign key had
+     * been resolved. All three were reachable only because the old type let a
+     * relation arrive here under-specified. It cannot now.
      */
     private static buildSimpleRelationCondition;
     /**
@@ -83,11 +140,15 @@ export declare class DrizzleConditionBuilder {
     /**
      * Build relation-based query with joins and conditions
      */
-    static buildRelationQuery<T extends DrizzleDynamicQuery>(baseQuery: T, relation: Relation, parentId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    static buildRelationQuery<T extends DrizzleDynamicQuery>(baseQuery: T, relation: ResolvedRelation, parentId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
     /**
-     * Build count query for relations with proper joins and conditions
+     * A count over a relation's target rows.
+     *
+     * The junction case counts `distinct` because the caller's query joins the
+     * junction; the owning/inverse pair that used to sit here built the same
+     * query twice.
      */
-    static buildRelationCountQuery<T extends DrizzleDynamicQuery>(baseCountQuery: T, relation: Relation, parentId: string | number, targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    static buildRelationCountQuery<T extends DrizzleDynamicQuery>(baseCountQuery: T, relation: ResolvedRelation, parentId: string | number, targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
     /**
      * Build join path conditions for count queries
      */
@@ -96,10 +157,6 @@ export declare class DrizzleConditionBuilder {
      * Build junction table conditions for count queries
      */
     private static buildJunctionCountQuery;
-    /**
-     * Build inverse junction table conditions for count queries
-     */
-    private static buildInverseJunctionCountQuery;
     /**
      * Helper method to extract table names from columns
      */
@@ -108,10 +165,6 @@ export declare class DrizzleConditionBuilder {
      * Helper method to extract column names from columns
      */
     static getColumnNamesFromColumns(columns: string | string[]): string[];
-    /**
-     * Find the corresponding junction table for an inverse many-to-many relation
-     */
-    private static findCorrespondingJunctionTable;
     /**
      * Build vector similarity search expressions for pgvector.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgres",
   "type": "module",
-  "version": "0.10.1-canary.6f89f77",
+  "version": "0.10.1-canary.7801eed",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -47,21 +47,20 @@
     "execa": "^9.6.1",
     "pg": "^8.21.0",
     "ws": "^8.21.0",
-    "@rebasepro/codegen": "0.10.1-canary.6f89f77",
-    "@rebasepro/server": "0.10.1-canary.6f89f77",
-    "@rebasepro/common": "0.10.1-canary.6f89f77",
-    "@rebasepro/utils": "0.10.1-canary.6f89f77",
-    "@rebasepro/types": "0.10.1-canary.6f89f77"
+    "@rebasepro/codegen": "0.10.1-canary.7801eed",
+    "@rebasepro/common": "0.10.1-canary.7801eed",
+    "@rebasepro/server": "0.10.1-canary.7801eed",
+    "@rebasepro/types": "0.10.1-canary.7801eed",
+    "@rebasepro/utils": "0.10.1-canary.7801eed"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.9",
+    "@hono/node-server": "^2.0.11",
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.9.3",
     "@types/pg": "^8.20.0",
     "@types/ws": "^8.18.1",
-    "@vitejs/plugin-react": "^6.0.2",
-    "hono": "^4.12.25",
+    "hono": "^4.12.27",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "typescript": "^6.0.3",

package/src/PostgresBootstrapper.ts

@@ -28,6 +28,7 @@ import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegi
 import { createEmailService, type EmailConfig, type EmailService, logger } from "@rebasepro/server";
 import { getTableName as getCollectionTableName } from "@rebasepro/common";
 import { ensureAuthTablesExist } from "./auth/ensure-tables";
+import { probeAuthSchema, resolveAuthSchema } from "./auth/schema-version";
 import { AuthSchemaTables, PostgresAuthRepository, UserService } from "./auth/services";
 import { createAuthSchema } from "./schema/auth-schema";
 import { HistoryService } from "./history/HistoryService";
@@ -37,6 +38,9 @@ import { buildCollectionsFromSchema, introspectSchema, readRlsStatus } from "./s
 import { buildDrizzleTablesFromSchema, buildDrizzleRelationsFromSchema } from "./schema/dynamic-tables";
 import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, 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";
+import { isChannelBusInstance } from "@rebasepro/types";
 
 export interface PostgresDriverConfig {
     connectionString?: string;
@@ -54,9 +58,13 @@ export interface PostgresDriverConfig {
      */
     introspectionSchema?: string;
     /**
-     * Realtime options. Currently only channel retention, which is opt-in:
-     * without rules here no channel keeps any history and broadcast stays
-     * fire-and-forget. See {@link ChannelRetentionRule}.
+     * Realtime options, both opt-in:
+     *
+     *  - `channels` — retention. Without rules no channel keeps any history and
+     *    broadcast stays fire-and-forget. See {@link ChannelRetentionRule}.
+     *  - `bus` — the cross-instance transport for channel broadcast and
+     *    presence. Defaults to in-process only, which is correct for a single
+     *    instance and wrong for two. See {@link ChannelBusConfig}.
      */
     realtime?: RealtimeChannelsConfig;
 }
@@ -227,8 +235,8 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                         `  The database server is not running or is not accepting\n` +
                         `  connections. Common fixes:\n` +
                         `\n` +
+                        `    • docker compose up -d db          (the service a Rebase scaffold ships)\n` +
                         `    • brew services start postgresql@18\n` +
-                        `    • docker compose up -d postgres\n` +
                         `    • Verify DATABASE_URL in your .env file\n` +
                         `\n` +
                         `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
@@ -337,6 +345,29 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
             // Prefer DATABASE_DIRECT_URL to bypass PgBouncer for LISTEN/NOTIFY.
             const directUrl = process.env.DATABASE_DIRECT_URL || pgConfig.connectionString;
 
+            // ── Cross-instance channel bus ───────────────────────────────────
+            // Entity changes already span instances (CDC / LISTEN below).
+            // Channel broadcast and presence did not — they lived in per-process
+            // maps, so behind two replicas the clients of one were invisible to
+            // the other. Opt-in, and a no-op when left at "memory".
+            try {
+                const busSetting = resolveChannelBusSetting(pgConfig.realtime?.bus);
+                // A supplied instance is always installed; a named built-in only
+                // when it is not the in-process default, so the common case
+                // touches none of this machinery.
+                const wantsBus = isChannelBusInstance(busSetting) || busSetting.type !== "memory";
+                if (wantsBus) {
+                    await realtimeService.configureChannelBus(
+                        createChannelBus(busSetting, {
+                            db: schemaAwareDb as unknown as NodePgDatabase<Record<string, unknown>>,
+                            directUrl
+                        })
+                    );
+                }
+            } catch (err) {
+                logger.warn("⚠️ [ChannelBus] Could not configure the channel bus — channel broadcast and presence stay per-instance", { error: err });
+            }
+
             // Database-level Change Data Capture. When active, realtime events are
             // emitted for EVERY committed write — including ones that bypass the
             // Rebase API (psql, another service's cron, raw SQL, the Studio SQL
@@ -388,6 +419,14 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                             table: getCollectionTableName(c)
                         }))
                         .filter((t) => Boolean(t.table) && registry.hasTableForCollection(t.table));
+                    // Junction tables back no collection, so the list above misses
+                    // them — and a link or unlink is a write nobody would hear
+                    // about. Their rows are the contents of a child list, which is
+                    // as much a change as a write to the rows themselves.
+                    for (const link of collectJunctionLinks(registry)) {
+                        cdcTables.push({ schema: link.schema,
+table: link.table });
+                    }
                     // Provisioning throws only when the connection can't create the
                     // trigger function (insufficient privilege); enableCdc throws when
                     // the LISTEN connection can't be established. Either → fall back.
@@ -593,7 +632,10 @@ table: fullCheckName });
             return { userService,
 roleService: userService,
 emailService,
-authRepository };
+authRepository,
+// Bound to the same schema `ensureAuthTablesExist` just migrated, so the
+// health endpoint reports on the tables auth actually reads.
+schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection)) };
         },
 
         async initializeHistory(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: HistoryService } | undefined> {
@@ -615,6 +657,46 @@ authRepository };
             return internals.realtimeService;
         },
 
+        /**
+         * Create any collection tables, columns and enum types the database is
+         * missing — additively, never destructively.
+         *
+         * This is what lets the managed runtime boot a project against a fresh
+         * database and actually serve it. Before this, only auth tables were
+         * ensured, so a managed tenant came up with working sign-in and a 500 on
+         * every data route.
+         *
+         * Runs through the drizzle handle's underlying session so it uses the
+         * same connection (and therefore the same privileges) the driver already
+         * proved it can bootstrap with.
+         */
+        async ensureCollectionSchema(
+            collections: unknown[],
+            driverResult: InitializedDriver,
+            log?: (message: string) => void
+        ): Promise<{ applied: number }> {
+            const internals = driverResult.internals as PostgresDriverInternals;
+            const { ensureCollectionTables } = await import("./schema/ensure-collection-tables");
+            // Runs through the drizzle handle the driver already bootstrapped
+            // with, so it uses exactly the connection and privileges that were
+            // proven to work. Every statement is DDL or a catalogue read with no
+            // bindable values (schema names are identifiers), and the module
+            // validates them before they reach a string.
+            const queryable = {
+                async query<T>(text: string): Promise<{ rows: T[] }> {
+                    const result = await internals.db.execute(sql.raw(text));
+                    const rows = (result as unknown as { rows?: T[] }).rows;
+                    return { rows: rows ?? (Array.isArray(result) ? (result as T[]) : []) };
+                }
+            };
+            const plan = await ensureCollectionTables(
+                queryable,
+                collections as Parameters<typeof ensureCollectionTables>[1],
+                log
+            );
+            return { applied: plan.actions.length };
+        },
+
         getAdmin(driverResult: InitializedDriver): DatabaseAdmin | undefined {
             const internals = driverResult.internals as PostgresDriverInternals;
             return internals.driver.admin;

package/src/auth/ensure-tables.ts

@@ -2,6 +2,12 @@ import { sql } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { logger } from "@rebasepro/server";
 import type { CollectionConfig } from "@rebasepro/types";
+import {
+    AuthSchemaVersionError,
+    assertAuthSchemaCompatible,
+    resolveAuthSchema,
+    stampAuthSchemaVersion
+} from "./schema-version";
 
 
 /**
@@ -14,6 +20,13 @@ import type { CollectionConfig } from "@rebasepro/types";
 export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: CollectionConfig): Promise<void> {
     logger.info("🔍 Checking auth tables...");
 
+    // Before anything else, and deliberately outside the catch below: refuse to
+    // run against a database that a newer framework version has already
+    // migrated. Everything past this point is best-effort by design, which is
+    // exactly the wrong posture for an incompatibility that would otherwise
+    // surface as a fully booted server failing every login.
+    await assertAuthSchemaCompatible(db, resolveAuthSchema(collection));
+
     try {
         // Resolve dynamic user table name and ID type from the collection
         let usersTableName = '"rebase"."users"';
@@ -588,8 +601,18 @@ 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.
+        await stampAuthSchemaVersion(db, authSchema);
+
         logger.info("✅ Auth tables ready");
     } catch (error) {
+        // The one failure that must not be survived. Continuing here is what
+        // produced a server that answered /health with 200 while every login
+        // returned 500 — the incompatibility is total, so crashing is the
+        // kinder outcome: an orchestrator will not route traffic to a pod that
+        // never came up.
+        if (error instanceof AuthSchemaVersionError) throw error;
         logger.error("❌ Failed to create auth tables", { error });
         logger.warn("⚠️ Continuing without creating auth tables.");
     }

package/src/auth/schema-version.ts

@@ -0,0 +1,260 @@
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { CollectionConfig } from "@rebasepro/types";
+
+/**
+ * The auth schema version this runtime expects to find in the database.
+ *
+ * Bump this whenever a migration in `ensureAuthTablesExist` makes the schema
+ * unreadable by the runtime that came before it — that is, whenever a *previous*
+ * version's auth queries would break against the migrated shape. Additive
+ * changes (a new nullable column nobody older references) do not need a bump.
+ *
+ * History. Note that 1 is a label for an era, not a value any database holds:
+ * stamping did not exist then, so an era-1 database reads as unstamped
+ * (`null`), and 2 is the first version ever actually written. The numbering
+ * starts at 2 only because two schema eras already existed when it was
+ * introduced; it could just as well have started at 1. It is not worth
+ * renumbering now — deployed databases already carry 2, and lowering the
+ * constant would make them look newer than the runtime and refuse the boot.
+ *
+ *   1 — Device-session refresh tokens. A row *was* a session, identified by
+ *       `unique_device_session UNIQUE (uid, user_agent, ip_address)`, and
+ *       `createToken` upserted with `ON CONFLICT (uid, user_agent, ip_address)`.
+ *   2 — Session-scoped, rotation-safe refresh tokens: `session_id`, `revoked`,
+ *       `rotated_at`, `session_started_at`, and `unique_device_session`
+ *       dropped because two live tokens of one session share all three columns.
+ *
+ * The 1 → 2 migration is why this file exists. Dropping the constraint is
+ * one-way: a version-1 runtime deployed afterwards boots perfectly, logs
+ * `✅ Auth tables ready` (its `CREATE TABLE IF NOT EXISTS` never revisits the
+ * existing table, so it cannot re-add the constraint), answers `/health` with
+ * 200 — and then fails every single login and refresh with SQLSTATE 42P10,
+ * because its `ON CONFLICT` names a constraint that no longer exists. A silent
+ * total auth outage behind a green health check. The stamp below turns that
+ * into a boot refusal.
+ */
+export const AUTH_SCHEMA_VERSION = 2;
+
+/** Key under which the version is stored in the auth schema's meta table. */
+const VERSION_KEY = "auth_schema_version";
+
+/**
+ * Columns `refresh_tokens` must have for the current runtime's auth write path
+ * to work. Checked by the health probe so a database that drifted *below* this
+ * runtime is reported as unhealthy rather than discovered one failed login at a
+ * time. Kept in step with the migration in `ensureAuthTablesExist`.
+ */
+const REQUIRED_REFRESH_TOKEN_COLUMNS = ["session_id", "revoked", "rotated_at", "session_started_at"];
+
+/**
+ * A constraint whose *presence* means the database is still at version 1, in a
+ * shape this runtime's rotation logic cannot write to: it makes two live tokens
+ * of one rotating session collide.
+ */
+const RETIRED_REFRESH_TOKEN_CONSTRAINT = "unique_device_session";
+
+/**
+ * Thrown when the database was migrated by a runtime newer than this one.
+ *
+ * Distinct class rather than a bare `Error` because `ensureAuthTablesExist`
+ * wraps its migrations in a catch that deliberately swallows failures and
+ * continues — every other problem there is better survived than crashed on.
+ * This one is not, so the catch rethrows on this type specifically.
+ */
+export class AuthSchemaVersionError extends Error {
+    readonly databaseVersion: number;
+    readonly runtimeVersion: number;
+
+    constructor(databaseVersion: number, runtimeVersion: number) {
+        super(
+            `Auth schema version mismatch: the database is at version ${databaseVersion}, ` +
+            `but this runtime understands version ${runtimeVersion}.\n\n` +
+            "A newer version of the framework has already migrated this database. Running this " +
+            "older runtime against it would boot cleanly and then fail every login and token " +
+            "refresh, because the auth schema it expects no longer exists.\n\n" +
+            "Refusing to start. Deploy a framework version at or above the one that migrated " +
+            "this database, or restore the database from a backup taken before the upgrade."
+        );
+        this.name = "AuthSchemaVersionError";
+        this.databaseVersion = databaseVersion;
+        this.runtimeVersion = runtimeVersion;
+    }
+}
+
+/**
+ * The schema the auth tables live in, derived exactly as `ensureAuthTablesExist`
+ * derives it. Shared so the two cannot drift: a stamp written to one schema and
+ * read from another would read as "never stamped" forever.
+ */
+export function resolveAuthSchema(collection?: CollectionConfig): string {
+    if (!collection) return "rebase";
+    const usersSchema = ("schema" in collection && typeof collection.schema === "string")
+        ? collection.schema
+        : "public";
+    return usersSchema === "public" ? "rebase" : usersSchema;
+}
+
+/**
+ * Read the stamped version, or `null` when the database has never been stamped.
+ *
+ * `null` is not an error and must not be treated as one: every database
+ * provisioned before this file existed is unstamped, and so is every fresh one.
+ * Uses `to_regclass` rather than selecting straight from the table so a missing
+ * schema or table is a `null` rather than a thrown 42P01.
+ */
+export async function readAuthSchemaVersion(
+    db: NodePgDatabase,
+    authSchema: string
+): Promise<number | null> {
+    const qualified = `"${authSchema}"."schema_meta"`;
+    const exists = await db.execute(sql`SELECT to_regclass(${qualified}) IS NOT NULL AS present`);
+    if (!(exists.rows[0] as { present: boolean } | undefined)?.present) return null;
+
+    const result = await db.execute(sql`
+        SELECT value FROM ${sql.raw(qualified)} WHERE key = ${VERSION_KEY}
+    `);
+    const raw = (result.rows[0] as { value: string } | undefined)?.value;
+    if (raw === undefined) return null;
+
+    const parsed = Number.parseInt(raw, 10);
+    // A meta row we cannot parse is treated as unstamped rather than as version
+    // 0: refusing to boot over a garbled string would be a worse failure than
+    // the drift it is meant to catch.
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * Refuse to run against a database a newer runtime has already migrated.
+ *
+ * Deliberately one-directional. A database *older* than this runtime is the
+ * normal upgrade path — the migrations in `ensureAuthTablesExist` are about to
+ * bring it forward, so it is not an error. Only the reverse is unrecoverable.
+ */
+export async function assertAuthSchemaCompatible(
+    db: NodePgDatabase,
+    authSchema: string
+): Promise<void> {
+    const databaseVersion = await readAuthSchemaVersion(db, authSchema);
+    if (databaseVersion !== null && databaseVersion > AUTH_SCHEMA_VERSION) {
+        throw new AuthSchemaVersionError(databaseVersion, AUTH_SCHEMA_VERSION);
+    }
+}
+
+/**
+ * Record that this runtime's migrations have been applied.
+ *
+ * Called at the end of `ensureAuthTablesExist`, so a boot that failed partway
+ * through leaves the older stamp in place and the next boot migrates again.
+ */
+export async function stampAuthSchemaVersion(
+    db: NodePgDatabase,
+    authSchema: string
+): Promise<void> {
+    const qualified = `"${authSchema}"."schema_meta"`;
+    await db.execute(sql`
+        CREATE TABLE IF NOT EXISTS ${sql.raw(qualified)} (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL,
+            updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+    `);
+    await db.execute(sql`
+        INSERT INTO ${sql.raw(qualified)} (key, value)
+        VALUES (${VERSION_KEY}, ${String(AUTH_SCHEMA_VERSION)})
+        ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = NOW()
+    `);
+}
+
+/** What {@link probeAuthSchema} found. */
+export interface AuthSchemaProbeResult {
+    /** False when this runtime cannot be trusted to serve auth against this database. */
+    healthy: boolean;
+    /** The stamped version, or `null` on a database that predates stamping. */
+    databaseVersion: number | null;
+    /** {@link AUTH_SCHEMA_VERSION}. */
+    runtimeVersion: number;
+    /** Human-readable descriptions of each mismatch found. Empty when healthy. */
+    problems: string[];
+}
+
+/**
+ * Check that the auth schema is one this runtime can actually write to.
+ *
+ * Two independent checks, because either alone has a blind spot:
+ *
+ *  - The **stamp** catches a runtime older than the database. It is the precise
+ *    signal, but it is blind on every database provisioned before stamping
+ *    existed — which today is all of them.
+ *  - The **structure** catches a database older than the runtime, and works on
+ *    unstamped databases. It is what makes this useful immediately rather than
+ *    one upgrade cycle from now.
+ *
+ * Never throws: a probe that fails to run reports unhealthy with the reason, so
+ * a broken check surfaces as a degraded health response rather than a 500 from
+ * the health endpoint itself.
+ */
+export async function probeAuthSchema(
+    db: NodePgDatabase,
+    authSchema: string
+): Promise<AuthSchemaProbeResult> {
+    const problems: string[] = [];
+    let databaseVersion: number | null = null;
+
+    try {
+        databaseVersion = await readAuthSchemaVersion(db, authSchema);
+        if (databaseVersion !== null && databaseVersion > AUTH_SCHEMA_VERSION) {
+            problems.push(
+                `database is at auth schema version ${databaseVersion}, this runtime understands ` +
+                `${AUTH_SCHEMA_VERSION} — it was migrated by a newer framework version`
+            );
+        }
+
+        const refreshTokens = `"${authSchema}"."refresh_tokens"`;
+        const present = await db.execute(sql`SELECT to_regclass(${refreshTokens}) IS NOT NULL AS present`);
+        if (!(present.rows[0] as { present: boolean } | undefined)?.present) {
+            // Not a problem in itself: auth may simply not be configured on this
+            // deployment, and the table is created on demand at boot when it is.
+            return { healthy: problems.length === 0, databaseVersion, runtimeVersion: AUTH_SCHEMA_VERSION, problems };
+        }
+
+        const columns = await db.execute(sql`
+            SELECT column_name FROM information_schema.columns
+            WHERE table_schema = ${authSchema} AND table_name = 'refresh_tokens'
+        `);
+        const found = new Set((columns.rows as { column_name: string }[]).map(row => row.column_name));
+        const missing = REQUIRED_REFRESH_TOKEN_COLUMNS.filter(column => !found.has(column));
+        if (missing.length > 0) {
+            problems.push(
+                `refresh_tokens is missing ${missing.join(", ")} — the auth migrations have not been ` +
+                "applied to this database, so token rotation will fail"
+            );
+        }
+
+        const retired = await db.execute(sql`
+            SELECT 1 FROM pg_constraint c
+            JOIN pg_class t ON t.oid = c.conrelid
+            JOIN pg_namespace n ON n.oid = t.relnamespace
+            WHERE n.nspname = ${authSchema}
+              AND t.relname = 'refresh_tokens'
+              AND c.conname = ${RETIRED_REFRESH_TOKEN_CONSTRAINT}
+        `);
+        if (retired.rows.length > 0) {
+            problems.push(
+                `refresh_tokens still carries ${RETIRED_REFRESH_TOKEN_CONSTRAINT} — concurrent token ` +
+                "rotation for one session will fail on it"
+            );
+        }
+    } catch (error: unknown) {
+        problems.push(
+            `auth schema probe failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+    }
+
+    return {
+        healthy: problems.length === 0,
+        databaseVersion,
+        runtimeVersion: AUTH_SCHEMA_VERSION,
+        problems
+    };
+}

package/src/cli-errors.ts

@@ -113,8 +113,8 @@ function formatConnectionRefusedBanner(databaseUrl: string): string {
         `  The database server is not running or is not accepting\n` +
         `  connections. Common fixes:\n` +
         `\n` +
+        `    • docker compose up -d db          (the service a Rebase scaffold ships)\n` +
         `    • brew services start postgresql@18\n` +
-        `    • docker compose up -d postgres\n` +
         `    • Verify DATABASE_URL in your .env file\n` +
         `\n` +
         `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`

package/src/cli-helpers.ts

@@ -1,10 +1,11 @@
+import { isManyToMany } from "@rebasepro/types";
 import path from "path";
 import fs from "fs";
 import { execSync } from "child_process";
 import { pathToFileURL } from "url";
 import chalk from "chalk";
 import { logger } from "@rebasepro/server";
-import type { CollectionConfig, Relation } from "@rebasepro/types";
+import type { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
 import { moduleDir as __helpersDirname } from "./module-dir";
 
 
@@ -53,8 +54,8 @@ export async function getTableIncludesFromCollections(collections: CollectionCon
         }
 
         const resolvedRelations = resolveCollectionRelations(col);
-        for (const relation of Object.values(resolvedRelations) as Relation[]) {
-            if (relation.through) {
+        for (const relation of Object.values(resolvedRelations) as ResolvedRelation[]) {
+            if (isManyToMany(relation)) {
                 const junctionTableName = relation.through.table;
                 const targetCollection = relation.target();
                 const targetSchema = isPostgresCollectionConfig(targetCollection) && targetCollection.schema ? targetCollection.schema : "public";