@rebasepro/server-postgres 0.10.1-canary.d8d45b2 → 0.10.1-canary.ed78a2c

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";

package/src/collections/PostgresCollectionRegistry.ts

@@ -1,5 +1,5 @@
-import { CollectionRegistry } from "@rebasepro/common";
-import { type CollectionConfig, type Relation, getDataSourceCapabilities } from "@rebasepro/types";
+import { CollectionRegistry, resolveCollectionRelations } from "@rebasepro/common";
+import { type CollectionConfig } from "@rebasepro/types";
 import { PgEnum, PgTable } from "drizzle-orm/pg-core";
 import { Relations } from "drizzle-orm";
 import { CollectionRegistryInterface } from "../interfaces";
@@ -95,8 +95,13 @@ export class PostgresCollectionRegistry extends CollectionRegistry implements Co
      */
     getRelationKeysForCollection(collectionPath: string): string[] {
         const collection = this.getCollectionByPath(collectionPath);
-        if (!collection || !getDataSourceCapabilities(collection.engine).supportsRelations || !collection.relations) return [];
-        return collection.relations!.map((r: Relation) => r.relationName || r.localKey || "").filter(Boolean);
+        if (!collection) return [];
+        // Resolved, not authored. `relationName` is optional at the authoring
+        // surface and defaults to the property key or the target's slug, so
+        // reading the raw field dropped every relation that relied on the
+        // default — and never saw relations declared inline on a property at
+        // all, since those are not in the `relations` array.
+        return Object.keys(resolveCollectionRelations(collection));
     }
 
 }

package/src/collections/buildRegistry.ts

@@ -4,6 +4,7 @@ import { CollectionConfig } from "@rebasepro/types";
 import { logger } from "@rebasepro/server";
 import { PostgresCollectionRegistry } from "./PostgresCollectionRegistry";
 import { warnOnKeysTheAdminCannotResolve } from "../services/collection-helpers";
+import { assertRelationsResolve } from "./validate-relations";
 
 /**
  * Everything a registry is built from: the collections, and the drizzle schema
@@ -55,5 +56,11 @@ export function buildCollectionRegistry(schema: RegistrySchema): PostgresCollect
     // schema, and nothing serves it one, so only an edit to the config fixes it.
     warnOnKeysTheAdminCannotResolve(registry.getCollections(), registry);
 
+    // And now that the tables resolve: refuse to start on a relation whose
+    // names do not exist. The union checks a relation's shape at compile time;
+    // only here is there a schema to check its *names* against. Every one of
+    // these used to surface as an empty result at query time and nothing else.
+    assertRelationsResolve(registry.getCollections(), registry);
+
     return registry;
 }

package/src/collections/validate-relations.ts

@@ -0,0 +1,280 @@
+import { getTableColumns } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
+
+import { PostgresCollectionRegistry } from "./PostgresCollectionRegistry";
+
+/**
+ * Check every relation against the schema it actually runs on, at boot.
+ *
+ * The tagged union made the *shape* of a relation impossible to get wrong: a
+ * `manyToMany` cannot carry a `foreignKeyOnTarget`, a to-many cannot carry a
+ * `localKey`. What it cannot know is whether any of the names are real —
+ * whether `posts_tags` is a table, whether `author_id` is a column, whether a
+ * `joinPath` connects the tables it claims to. Those are facts about the
+ * database, and the type system never sees them.
+ *
+ * Until now nothing checked them until a query ran, and the failures were the
+ * quiet kind. A missing junction table logged a warning and returned no rows,
+ * so `posts/1/tags` answered `[]` — indistinguishable from a post with no tags.
+ * The relation looked configured, the admin drew the tab, the tab was empty,
+ * and nothing anywhere said why.
+ *
+ * The junction default is the sharp edge this exists for. `through.table`
+ * defaults to the two table names sorted and joined, so renaming a table
+ * silently re-points the relation at a name that was never created. It is the
+ * one default whose output changes when you edit something that looks
+ * unrelated.
+ */
+export interface RelationDefect {
+    /** Slug of the collection declaring the relation. */
+    collection: string;
+    relationName: string;
+    kind: ResolvedRelation["kind"];
+    /** What is wrong, in terms of the schema. */
+    problem: string;
+    /** The edit that fixes it. */
+    fix: string;
+}
+
+/**
+ * Every name a column answers to: the key in the drizzle schema and the real
+ * column name in Postgres. A relation may legitimately be written with either,
+ * and reporting a working relation as broken is worse than not checking.
+ */
+function columnNames(table: PgTable): Set<string> {
+    const names = new Set<string>();
+    for (const [key, col] of Object.entries(getTableColumns(table))) {
+        names.add(key);
+        const dbName = (col as { name?: string })?.name;
+        if (dbName) names.add(dbName);
+    }
+    return names;
+}
+
+const quote = (xs: Iterable<string>) => Array.from(xs).map(s => `\`${s}\``).join(", ");
+
+/** `on.from` / `on.to` accept a single column or a composite tuple. */
+const asColumns = (value: string | string[]): string[] => Array.isArray(value) ? value : [value];
+
+/**
+ * Relations whose names do not resolve against the registered schema.
+ *
+ * Fails open wherever it cannot see enough to be sure — an unregistered source
+ * table, a target belonging to another backend — because a false alarm here
+ * costs more than a missed one: it would block boot on a working app.
+ */
+export function findRelationDefects(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): RelationDefect[] {
+    const defects: RelationDefect[] = [];
+    const registeredSlugs = new Set(registry.getCollections().map(c => c.slug));
+
+    for (const collection of collections) {
+        const sourceTableName = getTableName(collection);
+        const sourceTable = registry.getTable(sourceTableName);
+        // Nothing to check against. Another boot warning already covers this.
+        if (!sourceTable) continue;
+
+        const sourceColumns = columnNames(sourceTable);
+        const relations = resolveCollectionRelations(collection);
+
+        for (const relation of Object.values(relations)) {
+            const at = { collection: collection.slug,
+relationName: relation.relationName,
+kind: relation.kind };
+
+            let targetCollection: CollectionConfig;
+            try {
+                targetCollection = relation.target();
+            } catch (e) {
+                defects.push({
+                    ...at,
+                    problem: `its \`target()\` threw: ${e instanceof Error ? e.message : String(e)}`,
+                    fix: "a target thunk usually throws because of a circular import — make sure it is `() => otherCollection` and not evaluated at module load"
+                });
+                continue;
+            }
+
+            // A target this registry has never heard of belongs to another
+            // backend; its tables are not ours to check.
+            if (!registeredSlugs.has(targetCollection.slug)) continue;
+
+            const targetTableName = getTableName(targetCollection);
+            const targetTable = registry.getTable(targetTableName);
+            if (!targetTable) {
+                defects.push({
+                    ...at,
+                    problem: `it points at collection \`${targetCollection.slug}\`, which has no table \`${targetTableName}\` in the schema`,
+                    fix: `create the \`${targetTableName}\` table, or correct \`table\` on the \`${targetCollection.slug}\` collection`
+                });
+                continue;
+            }
+            const targetColumns = columnNames(targetTable);
+
+            switch (relation.kind) {
+                case "belongsTo": {
+                    if (!sourceColumns.has(relation.localKey)) {
+                        defects.push({
+                            ...at,
+                            problem: `\`localKey: "${relation.localKey}"\` is not a column on \`${sourceTableName}\``,
+                            fix: `add the column, or set \`localKey\` to one of: ${quote(sourceColumns)}`
+                        });
+                    }
+                    break;
+                }
+
+                case "hasOne":
+                case "hasMany": {
+                    if (!targetColumns.has(relation.foreignKeyOnTarget)) {
+                        defects.push({
+                            ...at,
+                            problem: `\`foreignKeyOnTarget: "${relation.foreignKeyOnTarget}"\` is not a column on the target table \`${targetTableName}\``,
+                            fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
+                        });
+                    }
+                    break;
+                }
+
+                case "manyToMany": {
+                    const { table, sourceColumn, targetColumn } = relation.through;
+                    const junction = registry.getTable(table);
+                    if (!junction) {
+                        defects.push({
+                            ...at,
+                            problem: `its junction table \`${table}\` does not exist`,
+                            fix: `create \`${table}\`, or name the real one with \`through: { table: "..." }\`. ` +
+                                "Note that an omitted `through.table` is derived from the two table names sorted " +
+                                "and joined, so renaming a table changes it"
+                        });
+                        break;
+                    }
+                    const junctionColumns = columnNames(junction);
+                    for (const [label, column] of [["sourceColumn", sourceColumn], ["targetColumn", targetColumn]] as const) {
+                        if (!junctionColumns.has(column)) {
+                            defects.push({
+                                ...at,
+                                problem: `\`through.${label}: "${column}"\` is not a column on the junction table \`${table}\``,
+                                fix: `set \`through.${label}\` to one of: ${quote(junctionColumns)}` +
+                                    (label === "sourceColumn" ? " — it is the column naming *this* collection" : "")
+                            });
+                        }
+                    }
+                    break;
+                }
+
+                case "via": {
+                    if (relation.joinPath.length === 0) {
+                        defects.push({
+                            ...at,
+                            problem: "its `joinPath` is empty, so it joins nothing",
+                            fix: "add at least one step, ending at the target's table"
+                        });
+                        break;
+                    }
+
+                    // Walk the chain: each step's `from` names columns on the
+                    // previous table, its `to` names columns on its own.
+                    let prevName = sourceTableName;
+                    let prevColumns = sourceColumns;
+                    let broken = false;
+
+                    for (const [i, step] of relation.joinPath.entries()) {
+                        const stepTable = registry.getTable(step.table);
+                        if (!stepTable) {
+                            defects.push({
+                                ...at,
+                                problem: `step ${i + 1} of its \`joinPath\` joins \`${step.table}\`, which is not a table in the schema`,
+                                fix: `correct \`joinPath[${i}].table\``
+                            });
+                            broken = true;
+                            break;
+                        }
+                        const stepColumns = columnNames(stepTable);
+
+                        for (const column of asColumns(step.on.from)) {
+                            if (!prevColumns.has(column)) {
+                                defects.push({
+                                    ...at,
+                                    problem: `step ${i + 1} joins \`${prevName}.${column}\` → \`${step.table}\`, but \`${column}\` is not a column on \`${prevName}\``,
+                                    fix: `\`joinPath[${i}].on.from\` names columns on ${i === 0 ? "this collection's table" : `the previous step's table (\`${prevName}\`)`}: ${quote(prevColumns)}`
+                                });
+                            }
+                        }
+                        for (const column of asColumns(step.on.to)) {
+                            if (!stepColumns.has(column)) {
+                                defects.push({
+                                    ...at,
+                                    problem: `step ${i + 1} joins into \`${step.table}.${column}\`, but \`${column}\` is not a column on \`${step.table}\``,
+                                    fix: `\`joinPath[${i}].on.to\` names columns on \`${step.table}\`: ${quote(stepColumns)}`
+                                });
+                            }
+                        }
+
+                        if (asColumns(step.on.from).length !== asColumns(step.on.to).length) {
+                            defects.push({
+                                ...at,
+                                problem: `step ${i + 1} compares ${asColumns(step.on.from).length} column(s) against ${asColumns(step.on.to).length}`,
+                                fix: `\`from\` and \`to\` must name the same number of columns in \`joinPath[${i}]\``
+                            });
+                        }
+
+                        prevName = step.table;
+                        prevColumns = stepColumns;
+                    }
+
+                    // The chain has to end where the relation says it points,
+                    // or the rows it returns are not the target's rows.
+                    if (!broken && prevName !== targetTableName) {
+                        defects.push({
+                            ...at,
+                            problem: `its \`joinPath\` ends at \`${prevName}\`, but it targets \`${targetCollection.slug}\` (table \`${targetTableName}\`)`,
+                            fix: `make the last step join \`${targetTableName}\`, or point \`target\` at the collection backed by \`${prevName}\``
+                        });
+                    }
+                    break;
+                }
+
+                default: {
+                    const exhaustive: never = relation;
+                    throw new Error(`Unhandled relation kind: ${JSON.stringify(exhaustive)}`);
+                }
+            }
+        }
+    }
+
+    return defects;
+}
+
+/**
+ * Fail boot on any relation that cannot resolve, listing all of them at once.
+ *
+ * Deliberately fatal rather than a warning. Every one of these produces an
+ * empty result at query time and nothing else — an empty tab, an empty
+ * `include`, a subcollection that looks like it has no rows. A server that
+ * refuses to start is recoverable in a minute; a relation that quietly answers
+ * "nothing" is the kind of bug found in production, weeks later, by a user
+ * asking where their data went.
+ */
+export function assertRelationsResolve(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): void {
+    const defects = findRelationDefects(collections, registry);
+    if (defects.length === 0) return;
+
+    const lines = defects.map(d =>
+        `  • ${d.collection}.${d.relationName} (${d.kind})\n` +
+        `      ${d.problem}\n` +
+        `      fix: ${d.fix}`
+    );
+
+    throw new Error(
+        `${defects.length} relation${defects.length === 1 ? "" : "s"} cannot resolve against the database schema.\n\n` +
+        "Each of these would return no rows at query time rather than reporting an error, " +
+        "so they are fatal at boot instead.\n\n" +
+        lines.join("\n\n") + "\n"
+    );
+}