@rebasepro/server-postgres 0.10.1-canary.3d09338 → 0.10.1-canary.60301c3

package/dist/index.es.js

@@ -2,8 +2,8 @@ import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
 import { i as __toESM, n as __exportAll, r as __require, t as __commonJSMin } from "./chunk-DSJWtz9O.js";
-import { a as isSchemaAdmin, i as isSQLAdmin, l as isPostgresCollectionConfig, m as Vector, n as getDataSourceCapabilities, o as ANONYMOUS_USER_ID, r as isChannelBusInstance } from "./src-CBgtrPhJ.js";
-import { C as createRelationRefWithData, D as mergeDeep, E as getPolicyNamesForRule, O as camelCase, S as createRelationRef, T as updateDateAutoValues, _ as getTableVarName, a as getJunctionCollectionConfig, b as getDeclaredPrimaryKeys, c as getEffectiveSecurityRules, d as securityRuleToConditions, f as findAnonymousGrants, g as getTableName$1, h as getEnumVarName, i as CollectionRegistry, k as toSnakeCase, l as buildPropertyCallbacks, m as getColumnName, n as detectJunctionTables, o as getJunctionSecurityRules, p as findRelation, r as buildSdkData, s as resolveJunctionSpecs, t as classifyTable, u as policyToPostgres, v as resolveCollectionRelations, w as normalizeToEntityRelation, x as parseIdValues, y as buildCompositeId } from "./src-lcfUP4xg.js";
+import { a as isSchemaAdmin, c as hasForeignKeyOnTarget, d as isPostgresCollectionConfig, g as Vector, i as isSQLAdmin, l as isManyToMany, o as ANONYMOUS_USER_ID, r as isChannelBusInstance } from "./src-D5xBTl32.js";
+import { C as createRelationRefWithData, D as mergeDeep, E as getPolicyNamesForRule, O as camelCase, S as createRelationRef, T as updateDateAutoValues, _ as getTableVarName, a as getJunctionCollectionConfig, b as getDeclaredPrimaryKeys, c as getEffectiveSecurityRules, d as securityRuleToConditions, f as findAnonymousGrants, g as getTableName$1, h as getEnumVarName, i as CollectionRegistry, k as toSnakeCase, l as buildPropertyCallbacks, m as getColumnName, n as detectJunctionTables, o as getJunctionSecurityRules, p as findRelation, r as buildSdkData, s as resolveJunctionSpecs, t as classifyTable, u as policyToPostgres, v as resolveCollectionRelations, w as normalizeToEntityRelation, x as parseIdValues, y as buildCompositeId } from "./src-3VmUJ8Xn.js";
 import { Client, Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { ApiError, createEmailService, extractUserFromToken, loadCollectionsFromDirectory, logger, safeCompare } from "@rebasepro/server";
@@ -413,28 +413,32 @@ var DrizzleConditionBuilder = class {
 	*                   it and the final step correlating to the outer row.
 	*/
 	static buildRelationScopeCondition(relation, parent, parentId, targetTable, targetIdColumn, registry) {
-		if (relation.joinPath && relation.joinPath.length > 0) {
-			const { table, idColumn } = parent();
-			return this.buildJoinPathScopeCondition(relation.joinPath, table, idColumn, parentId, targetTable, registry);
-		}
-		if (relation.through) {
-			const junctionTable = registry.getTable(relation.through.table);
-			if (!junctionTable) throw new Error(`Junction table not found: ${relation.through.table}`);
-			const sourceCol = junctionTable[relation.through.sourceColumn];
-			const targetCol = junctionTable[relation.through.targetColumn];
-			if (!sourceCol || !targetCol) throw new Error(`Junction columns '${relation.through.sourceColumn}'/'${relation.through.targetColumn}' not found in '${relation.through.table}'`);
-			return sql`EXISTS (SELECT 1 FROM ${junctionTable} WHERE ${targetCol} = ${targetIdColumn} AND ${sourceCol} = ${parentId})`;
-		}
-		if (relation.foreignKeyOnTarget) {
-			const fkColumn = targetTable[relation.foreignKeyOnTarget];
-			if (!fkColumn) throw new Error(`Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation '${relation.relationName}'. A many-to-many relation needs \`through\` instead.`);
-			return eq(fkColumn, parentId);
-		}
-		if (relation.localKey) {
-			const { table, idColumn } = parent();
-			return sql`${targetIdColumn} = (SELECT ${sql.identifier(relation.localKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
+		switch (relation.kind) {
+			case "via": {
+				const { table, idColumn } = parent();
+				return this.buildJoinPathScopeCondition(relation.joinPath, table, idColumn, parentId, targetTable, registry);
+			}
+			case "manyToMany": {
+				const { table: junctionName, sourceColumn, targetColumn } = relation.through;
+				const junctionTable = registry.getTable(junctionName);
+				if (!junctionTable) throw new Error(`Junction table not found: ${junctionName}`);
+				const sourceCol = junctionTable[sourceColumn];
+				const targetCol = junctionTable[targetColumn];
+				if (!sourceCol || !targetCol) throw new Error(`Junction columns '${sourceColumn}'/'${targetColumn}' not found in '${junctionName}'`);
+				return sql`EXISTS (SELECT 1 FROM ${junctionTable} WHERE ${targetCol} = ${targetIdColumn} AND ${sourceCol} = ${parentId})`;
+			}
+			case "hasOne":
+			case "hasMany": {
+				const fkColumn = targetTable[relation.foreignKeyOnTarget];
+				if (!fkColumn) throw new Error(`Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation '${relation.relationName}'.`);
+				return eq(fkColumn, parentId);
+			}
+			case "belongsTo": {
+				const { table, idColumn } = parent();
+				return sql`${targetIdColumn} = (SELECT ${sql.identifier(relation.localKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
+			}
+			default: throw new Error(`Unknown relation kind: ${JSON.stringify(relation)}`);
 		}
-		throw new Error(`Relation '${relation.relationName}' declares no \`foreignKeyOnTarget\`, \`through\`, \`joinPath\` or \`localKey\`, so there is no way to tell which target rows belong to a parent.`);
 	}
 	/**
 	* `EXISTS` for an explicit `joinPath`.
@@ -572,58 +576,43 @@ var DrizzleConditionBuilder = class {
 	/**
 	* Build relation-based conditions for different relation types
 	*/
+	/**
+	* 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, parentId, targetTable, parentTable, parentIdColumn, targetIdColumn, registry) {
-		console.debug("🔍 [buildRelationConditions] Building conditions for relation:", {
-			relationName: relation.relationName,
-			cardinality: relation.cardinality,
-			direction: relation.direction,
-			hasThrough: !!relation.through,
-			hasForeignKeyOnTarget: !!relation.foreignKeyOnTarget,
-			inverseRelationName: relation.inverseRelationName,
-			parentId
-		});
 		const joinConditions = [];
 		const whereConditions = [];
-		if (relation.joinPath && relation.joinPath.length > 0) {
-			console.debug("🔍 [buildRelationConditions] Using joinPath logic");
-			const { joins, finalCondition } = this.buildJoinPathConditions(relation.joinPath, targetTable, parentTable, parentIdColumn, parentId, registry);
-			joinConditions.push(...joins);
-			whereConditions.push(finalCondition);
-		} else if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
-			console.debug("🔍 [buildRelationConditions] Using owning many-to-many with explicit through");
-			const junctionResult = this.buildJunctionTableConditions(relation.through, targetIdColumn, parentId, registry);
-			joinConditions.push(junctionResult.join);
-			whereConditions.push(junctionResult.condition);
-		} else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") {
-			console.debug("🔍 [buildRelationConditions] Using inverse many-to-many with explicit through");
-			const junctionResult = this.buildInverseJunctionTableConditions(relation.through, targetIdColumn, parentId, registry);
-			joinConditions.push(junctionResult.join);
-			whereConditions.push(junctionResult.condition);
-		} else if (relation.cardinality === "many" && relation.direction === "inverse" && !relation.through) {
-			console.debug("🔍 [buildRelationConditions] Handling inverse many relationship without explicit through");
-			const junctionInfo = this.findCorrespondingJunctionTable(relation, registry);
-			if (junctionInfo) {
-				console.debug("🔍 [buildRelationConditions] Found junction info for inverse many-to-many, building junction conditions");
-				const junctionResult = this.buildInverseJunctionTableConditions(junctionInfo, targetIdColumn, parentId, registry);
+		switch (relation.kind) {
+			case "via": {
+				const { joins, finalCondition } = this.buildJoinPathConditions(relation.joinPath, targetTable, parentTable, parentIdColumn, parentId, registry);
+				joinConditions.push(...joins);
+				whereConditions.push(finalCondition);
+				break;
+			}
+			case "manyToMany": {
+				const junctionResult = this.buildJunctionTableConditions(relation.through, targetIdColumn, parentId, registry);
 				joinConditions.push(junctionResult.join);
 				whereConditions.push(junctionResult.condition);
-			} else if (relation.foreignKeyOnTarget) {
-				console.debug("🔍 [buildRelationConditions] No junction table found, treating as inverse one-to-many with foreign key on target");
-				const simpleCondition = this.buildSimpleRelationCondition(relation, targetTable, parentTable, parentId);
-				whereConditions.push(simpleCondition);
-			} else {
-				logger.error("🔍 [buildRelationConditions] Failed to find junction table info and no foreign key specified");
-				throw new Error(`Cannot resolve inverse many relation '${relation.relationName}'. Either specify 'through' property, ensure corresponding owning relation exists with junction table configuration, or specify 'foreignKeyOnTarget' for one-to-many relationships.`);
+				break;
 			}
-		} else {
-			console.debug("🔍 [buildRelationConditions] Using simple relation logic - THIS IS WHERE THE ERROR MIGHT OCCUR");
-			const simpleCondition = this.buildSimpleRelationCondition(relation, targetTable, parentTable, parentId);
-			whereConditions.push(simpleCondition);
+			case "hasOne":
+			case "hasMany":
+			case "belongsTo":
+				whereConditions.push(this.buildSimpleRelationCondition(relation, targetTable, parentTable, parentId));
+				break;
+			default: throw new Error(`Unknown relation kind: ${JSON.stringify(relation)}`);
 		}
-		console.debug("🔍 [buildRelationConditions] Final result:", {
-			joinConditionsCount: joinConditions.length,
-			whereConditionsCount: whereConditions.length
-		});
 		return {
 			joinConditions,
 			whereConditions
@@ -763,48 +752,24 @@ var DrizzleConditionBuilder = class {
 		};
 	}
 	/**
-	* Build conditions for inverse junction table (many-to-many) relations
-	*/
-	static buildInverseJunctionTableConditions(through, targetIdColumn, parentId, registry) {
-		const junctionTable = registry.getTable(through.table);
-		if (!junctionTable) throw new Error(`Junction table not found: ${through.table}`);
-		const junctionSourceCol = junctionTable[through.sourceColumn];
-		const junctionTargetCol = junctionTable[through.targetColumn];
-		if (!junctionSourceCol) throw new Error(`Source column '${through.sourceColumn}' not found in junction table '${through.table}'`);
-		if (!junctionTargetCol) throw new Error(`Target column '${through.targetColumn}' not found in junction table '${through.table}'`);
-		const condition = Array.isArray(parentId) ? inArray(junctionSourceCol, parentId) : eq(junctionSourceCol, parentId);
-		return {
-			join: {
-				table: junctionTable,
-				condition: eq(targetIdColumn, junctionTargetCol)
-			},
-			condition
-		};
-	}
-	/**
-	* 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.
 	*/
 	static buildSimpleRelationCondition(relation, targetTable, parentTable, parentId) {
-		if (relation.direction === "owning" && relation.localKey) {
-			const targetIdCol = Object.values(targetTable).find((col) => col.primary);
-			if (!targetIdCol) {
-				const idCol = Object.values(targetTable).find((col) => col.name === "id");
-				if (!idCol) throw new Error("No primary key or \"id\" column found in target table");
-				return Array.isArray(parentId) ? inArray(idCol, parentId) : eq(idCol, parentId);
-			}
-			return Array.isArray(parentId) ? inArray(targetIdCol, parentId) : eq(targetIdCol, parentId);
-		} else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
-			const foreignKeyCol = targetTable[relation.foreignKeyOnTarget];
-			if (!foreignKeyCol) throw new Error(`Foreign key column '${relation.foreignKeyOnTarget}' not found in target table. This might be a many-to-many relationship that requires a junction table. Consider using 'through' property or ensure the corresponding owning relation exists with junction table configuration.`);
-			return Array.isArray(parentId) ? inArray(foreignKeyCol, parentId) : eq(foreignKeyCol, parentId);
-		} else if (relation.direction === "inverse" && relation.cardinality === "many" && relation.inverseRelationName) throw new Error(`Inverse many-to-many relation '${relation.relationName}' requires a junction table. Either specify 'through' property or ensure the corresponding owning relation exists with junction table configuration.`);
-		else if (relation.direction === "inverse" && relation.cardinality === "one" && relation.inverseRelationName) {
-			const inferredForeignKeyName = `${relation.inverseRelationName}_id`;
-			const foreignKeyCol = targetTable[inferredForeignKeyName];
-			if (!foreignKeyCol) throw new Error(`Auto-inferred foreign key column '${inferredForeignKeyName}' not found in target table for inverse relation '${relation.relationName}'. Please specify 'foreignKeyOnTarget' explicitly.`);
-			console.debug(`🔍 [DrizzleConditionBuilder] Auto-inferred foreign key '${inferredForeignKeyName}' for inverse relation '${relation.relationName}'`);
-			return Array.isArray(parentId) ? inArray(foreignKeyCol, parentId) : eq(foreignKeyCol, parentId);
-		} else throw new Error(`Relation '${relation.relationName}' lacks proper configuration. For many-to-many relations, use 'through' property. For simple relations, use 'localKey' or 'foreignKeyOnTarget'.`);
+		const match = (column) => Array.isArray(parentId) ? inArray(column, parentId) : eq(column, parentId);
+		if (relation.kind === "belongsTo") {
+			const targetIdCol = Object.values(targetTable).find((col) => col.primary) ?? Object.values(targetTable).find((col) => col.name === "id");
+			if (!targetIdCol) throw new Error(`No primary key or "id" column in the target table of relation '${relation.relationName}'.`);
+			return match(targetIdCol);
+		}
+		const foreignKeyCol = targetTable[relation.foreignKeyOnTarget];
+		if (!foreignKeyCol) throw new Error(`Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation '${relation.relationName}'. A link through a junction is \`kind: "manyToMany"\`.`);
+		return match(foreignKeyCol);
 	}
 	/**
 	* Combine multiple conditions with AND operator
@@ -859,16 +824,23 @@ var DrizzleConditionBuilder = class {
 		return query;
 	}
 	/**
-	* 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(baseCountQuery, relation, parentId, targetTable, parentTable, parentIdColumn, targetIdColumn, registry, additionalFilters) {
-		if (relation.joinPath && relation.joinPath.length > 0) return this.buildJoinPathCountQuery(baseCountQuery, relation.joinPath, targetTable, parentTable, parentIdColumn, parentId, registry, additionalFilters);
-		else if (relation.through && relation.cardinality === "many" && relation.direction === "owning") return this.buildJunctionCountQuery(baseCountQuery, relation.through, targetIdColumn, parentId, registry, additionalFilters);
-		else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") return this.buildInverseJunctionCountQuery(baseCountQuery, relation.through, targetIdColumn, parentId, registry, additionalFilters);
-		else {
-			const allConditions = [this.buildSimpleRelationCondition(relation, targetTable, parentTable, parentId)];
-			if (additionalFilters) allConditions.push(...additionalFilters);
-			return baseCountQuery.where(and(...allConditions));
+		switch (relation.kind) {
+			case "via": return this.buildJoinPathCountQuery(baseCountQuery, relation.joinPath, targetTable, parentTable, parentIdColumn, parentId, registry, additionalFilters);
+			case "manyToMany": return this.buildJunctionCountQuery(baseCountQuery, relation.through, targetIdColumn, parentId, registry, additionalFilters);
+			case "belongsTo":
+			case "hasOne":
+			case "hasMany": {
+				const allConditions = [this.buildSimpleRelationCondition(relation, targetTable, parentTable, parentId), ...additionalFilters ?? []];
+				return baseCountQuery.where(and(...allConditions));
+			}
+			default: throw new Error(`Unknown relation kind: ${JSON.stringify(relation)}`);
 		}
 	}
 	/**
@@ -909,20 +881,6 @@ var DrizzleConditionBuilder = class {
 		return baseCountQuery.innerJoin(junctionTable, eq(targetIdColumn, junctionTargetCol)).where(and(...baseConditions));
 	}
 	/**
-	* Build inverse junction table conditions for count queries
-	*/
-	static buildInverseJunctionCountQuery(baseCountQuery, through, targetIdColumn, parentId, registry, additionalFilters) {
-		const junctionTable = registry.getTable(through.table);
-		if (!junctionTable) throw new Error(`Junction table not found: ${through.table}`);
-		const junctionSourceCol = junctionTable[through.sourceColumn];
-		const junctionTargetCol = junctionTable[through.targetColumn];
-		if (!junctionSourceCol) throw new Error(`Source column '${through.sourceColumn}' not found in junction table '${through.table}'`);
-		if (!junctionTargetCol) throw new Error(`Target column '${through.targetColumn}' not found in junction table '${through.table}'`);
-		const baseConditions = [eq(junctionSourceCol, parentId)];
-		if (additionalFilters && additionalFilters.length > 0) baseConditions.push(...additionalFilters);
-		return baseCountQuery.innerJoin(junctionTable, eq(targetIdColumn, junctionTargetCol)).where(and(...baseConditions));
-	}
-	/**
 	* Helper method to extract table names from columns
 	*/
 	static getTableNamesFromColumns(columns) {
@@ -937,49 +895,6 @@ var DrizzleConditionBuilder = class {
 		return [getColumnName(columns)];
 	}
 	/**
-	* Find the corresponding junction table for an inverse many-to-many relation
-	*/
-	static findCorrespondingJunctionTable(relation, registry) {
-		try {
-			console.debug(`🔍 [findCorrespondingJunctionTable] Looking for junction table for inverse relation '${relation.relationName}' with inverseRelationName '${relation.inverseRelationName}'`);
-			if (!relation.inverseRelationName) {
-				console.debug("🔍 [findCorrespondingJunctionTable] No inverseRelationName specified");
-				return null;
-			}
-			const targetCollection = relation.target();
-			console.debug(`🔍 [findCorrespondingJunctionTable] Target collection: ${targetCollection.slug}`);
-			const targetCollectionRelations = resolveCollectionRelations(targetCollection);
-			console.debug("🔍 [findCorrespondingJunctionTable] Target collection relations:", Object.keys(targetCollectionRelations));
-			const correspondingRelation = targetCollectionRelations[relation.inverseRelationName];
-			if (!correspondingRelation) {
-				console.debug(`🔍 [findCorrespondingJunctionTable] No relation found with key '${relation.inverseRelationName}' on target collection`);
-				return null;
-			}
-			console.debug("🔍 [findCorrespondingJunctionTable] Found relation:", {
-				relationName: correspondingRelation.relationName,
-				cardinality: correspondingRelation.cardinality,
-				direction: correspondingRelation.direction,
-				hasThrough: !!correspondingRelation.through
-			});
-			if (correspondingRelation.cardinality !== "many" || correspondingRelation.direction !== "owning" || !correspondingRelation.through) {
-				console.debug("🔍 [findCorrespondingJunctionTable] Relation is not an owning many-to-many with junction table");
-				return null;
-			}
-			console.debug("🔍 [findCorrespondingJunctionTable] Found matching owning relation with junction table!");
-			const through = correspondingRelation.through;
-			const result = {
-				table: through.table,
-				sourceColumn: through.targetColumn,
-				targetColumn: through.sourceColumn
-			};
-			console.debug("🔍 [findCorrespondingJunctionTable] Returning junction info:", result);
-			return result;
-		} catch (error) {
-			logger.error(`🔍 [findCorrespondingJunctionTable] Error finding corresponding junction table for relation '${relation.relationName}'`, { error });
-			return null;
-		}
-	}
-	/**
 	* Build vector similarity search expressions for pgvector.
 	*
 	* Returns:
@@ -1056,7 +971,7 @@ function serializeDataToServer(row, properties, collection, registry) {
 	const joinPathRelationUpdates = [];
 	const foreignKeys = /* @__PURE__ */ new Set();
 	Object.values(resolvedRelations).forEach((relation) => {
-		if (relation.localKey) foreignKeys.add(relation.localKey);
+		if (relation.kind === "belongsTo") foreignKeys.add(relation.localKey);
 	});
 	for (const [key, value] of Object.entries(row)) {
 		const property = properties[key];
@@ -1068,11 +983,11 @@ function serializeDataToServer(row, properties, collection, registry) {
 		if (property.type === "relation" && collection) {
 			const relation = findRelation(resolvedRelations, key);
 			if (relation) {
-				if (relation.direction === "owning" && relation.localKey) {
+				if (relation.kind === "belongsTo") {
 					const serializedValue = serializePropertyToServer(effectiveValue, property);
 					if (serializedValue !== void 0) result[relation.localKey] = serializedValue;
 					continue;
-				} else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+				} else if (hasForeignKeyOnTarget(relation)) {
 					const serializedValue = serializePropertyToServer(effectiveValue, property);
 					inverseRelationUpdates.push({
 						relationKey: key,
@@ -1080,7 +995,7 @@ function serializeDataToServer(row, properties, collection, registry) {
 						newValue: serializedValue
 					});
 					continue;
-				} else if (relation.direction === "inverse" && relation.joinPath && relation.joinPath.length > 0) {
+				} else if (relation.kind === "via") {
 					const serializedValue = serializePropertyToServer(effectiveValue, property);
 					if (relation.cardinality === "one") joinPathRelationUpdates.push({
 						relationKey: key,
@@ -1093,14 +1008,6 @@ function serializeDataToServer(row, properties, collection, registry) {
 						newValue: serializedValue
 					});
 					continue;
-				} else if (relation.cardinality === "one" && relation.direction === "owning" && relation.joinPath && relation.joinPath.length > 0) {
-					const serializedValue = serializePropertyToServer(effectiveValue, property);
-					joinPathRelationUpdates.push({
-						relationKey: key,
-						relation,
-						newTargetId: serializedValue
-					});
-					continue;
 				}
 			}
 		}
@@ -1186,7 +1093,7 @@ async function parseDataFromServer(data, collection, db, registry) {
 	for (const [propKey, property] of Object.entries(properties)) if (property.type === "relation" && !(propKey in result)) {
 		const relation = findRelation(resolvedRelations, propKey);
 		if (relation) {
-			if (relation.direction === "owning" && relation.localKey && relation.localKey in data) {
+			if (relation.kind === "belongsTo" && relation.localKey in data) {
 				const fkValue = data[relation.localKey];
 				if (fkValue !== null && fkValue !== void 0) try {
 					const targetCollection = relation.target();
@@ -1194,7 +1101,7 @@ async function parseDataFromServer(data, collection, db, registry) {
 				} catch (e) {
 					logger.warn(`Could not resolve target collection for relation property: ${propKey}`, { error: e });
 				}
-			} else if (relation.direction === "inverse" && relation.foreignKeyOnTarget && db && registry) try {
+			} else if (hasForeignKeyOnTarget(relation) && db && registry) try {
 				const targetCollection = relation.target();
 				const targetTable = registry.getTable(getTableName$1(targetCollection));
 				const currentId = buildCompositeId(data, getPrimaryKeys(collection, registry));
@@ -1215,7 +1122,7 @@ async function parseDataFromServer(data, collection, db, registry) {
 			} catch (e) {
 				logger.warn(`Could not resolve inverse relation property: ${propKey}`, { error: e });
 			}
-			else if (relation.direction === "inverse" && relation.joinPath && db && registry) try {
+			else if (relation.kind === "via" && db && registry) try {
 				const targetCollection = relation.target();
 				const pks = getPrimaryKeys(collection, registry);
 				const currentId = buildCompositeId(data, pks);
@@ -1332,11 +1239,10 @@ function parsePropertyFromServer(value, property, collection, propertyKey) {
 		}
 		case "relation":
 			if (typeof value === "string" || typeof value === "number") {
-				let relationDef = property.relation;
+				let relationDef = property.resolvedRelation;
 				if (!relationDef && propertyKey) relationDef = findRelation(resolveCollectionRelations(collection), propertyKey);
-				if (!relationDef) relationDef = collection.relations?.find((rel) => rel.relationName === property.relationName);
 				if (!relationDef) {
-					logger.warn(`Relation not defined in property for key: ${propertyKey || "unknown"}`);
+					logger.warn(`ResolvedRelation not defined in property for key: ${propertyKey || "unknown"}`);
 					return value;
 				}
 				try {
@@ -1436,7 +1342,7 @@ function normalizeScalarValues(data, properties, collection, resolvedRelations,
 	const result = {};
 	const internalFKColumns = /* @__PURE__ */ new Set();
 	Object.values(resolvedRelations).forEach((relation) => {
-		if (relation.localKey && !properties[relation.localKey]) internalFKColumns.add(relation.localKey);
+		if (relation.kind === "belongsTo" && !properties[relation.localKey]) internalFKColumns.add(relation.localKey);
 	});
 	for (const [key, value] of Object.entries(data)) {
 		if (internalFKColumns.has(key)) {
@@ -1574,7 +1480,7 @@ var RelationService = class {
 		const parentTable = this.registry.getTable(getTableName$1(parentCollection));
 		if (!parentTable) throw new Error("Parent table not found");
 		const parentIdCol = parentTable[parentIdInfo.fieldName];
-		if (relation.joinPath && relation.joinPath.length > 0) {
+		if (relation.kind === "via") {
 			let query = this.db.select().from(parentTable).$dynamic();
 			let currentTable = parentTable;
 			for (const join of relation.joinPath) {
@@ -1689,8 +1595,8 @@ var RelationService = class {
 	* `tags` table and delete by primary key.
 	*/
 	async unlinkRelatedEntity(tx, hop, targetId) {
+		if (!isManyToMany(hop.relation)) throw new Error(`Relation '${hop.relationKey}' has no junction table to unlink through`);
 		const through = hop.relation.through;
-		if (!through) throw new Error(`Relation '${hop.relationKey}' has no junction table to unlink through`);
 		const junctionTable = this.registry.getTable(through.table);
 		if (!junctionTable) throw new Error(`Junction table not found: ${through.table}`);
 		const sourceJunctionColumn = junctionTable[through.sourceColumn];
@@ -1720,7 +1626,7 @@ var RelationService = class {
 		if (!parentTable) throw new Error("Parent table not found");
 		const parentIdCol = parentTable[parentIdInfo.fieldName];
 		const parsedParentIds = parentIds.map((id) => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
-		if (relation.joinPath && relation.joinPath.length > 0) {
+		if (relation.kind === "via") {
 			let query = this.db.select().from(parentTable).$dynamic();
 			let currentTable = parentTable;
 			for (const join of relation.joinPath) {
@@ -1749,7 +1655,7 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		if (relation.direction === "owning" && relation.localKey) {
+		if (relation.kind === "belongsTo") {
 			this.assertSingleKeyAddressable(parentCollection, parentPks, relation.localKey);
 			const localKeyCol = parentTable[relation.localKey];
 			if (!localKeyCol) throw new Error(`Local key column '${relation.localKey}' not found in parent table`);
@@ -1783,7 +1689,7 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
 		let query = this.db.select().from(targetTable).$dynamic();
 		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
@@ -1792,8 +1698,7 @@ var RelationService = class {
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
 			let parentId;
-			if (relation.direction === "inverse" && relation.foreignKeyOnTarget) parentId = targetRow[relation.foreignKeyOnTarget];
-			else if (relation.direction === "inverse" && relation.cardinality === "one" && relation.inverseRelationName) parentId = targetRow[`${relation.inverseRelationName}_id`];
+			if (hasForeignKeyOnTarget(relation)) parentId = targetRow[relation.foreignKeyOnTarget];
 			if (parentId !== void 0 && parentIdSet.has(String(parentId))) resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
 		}
 		return resultMap;
@@ -1816,7 +1721,7 @@ var RelationService = class {
 		if (!parentTable) throw new Error("Parent table not found");
 		const parentIdCol = parentTable[parentIdInfo.fieldName];
 		const parsedParentIds = parentIds.map((id) => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
-		if (relation.joinPath && relation.joinPath.length > 0) {
+		if (relation.kind === "via") {
 			let query = this.db.select().from(parentTable).$dynamic();
 			let currentTable = parentTable;
 			for (const join of relation.joinPath) {
@@ -1846,7 +1751,7 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+		if (relation.kind === "manyToMany") {
 			this.assertSingleKeyAddressable(parentCollection, parentPks, `${relation.through.table}.${relation.through.sourceColumn}`);
 			const junctionTable = this.registry.getTable(relation.through.table);
 			if (!junctionTable) {
@@ -1872,7 +1777,7 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
 		let query = this.db.select().from(targetTable).$dynamic();
 		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
@@ -1881,9 +1786,7 @@ var RelationService = class {
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
 			let parentId;
-			if (relation.through && relation.direction === "inverse") parentId = (row[relation.through.table] || row)[relation.through.targetColumn];
-			else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) parentId = targetRow[relation.foreignKeyOnTarget];
-			else if (relation.direction === "inverse" && relation.inverseRelationName) parentId = targetRow[`${relation.inverseRelationName}_id`];
+			if (hasForeignKeyOnTarget(relation)) parentId = targetRow[relation.foreignKeyOnTarget];
 			if (parentId !== void 0 && parentIdSet.has(String(parentId))) {
 				const key = String(parentId);
 				const arr = resultMap.get(key) || [];
@@ -1903,7 +1806,7 @@ var RelationService = class {
 			if (!relation || relation.cardinality !== "many") continue;
 			const targetEntityIds = value && Array.isArray(value) ? value.map((rel) => rel.id) : [];
 			const targetCollection = relation.target();
-			if (relation.joinPath && relation.joinPath.length > 0) {
+			if (relation.kind === "via") {
 				const parentTableName = getTableName$1(collection);
 				const targetTableName = getTableName$1(targetCollection);
 				let junctionTable = void 0;
@@ -1948,7 +1851,7 @@ var RelationService = class {
 					}));
 					if (newLinks.length > 0) await tx.insert(junctionTable).values(newLinks);
 				}
-			} else if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+			} else if (relation.kind === "manyToMany") {
 				const junctionTable = this.registry.getTable(relation.through.table);
 				if (!junctionTable) {
 					logger.warn(`Junction table '${relation.through.table}' not found for relation '${key}' in collection '${collection.slug}'`);
@@ -1973,8 +1876,7 @@ var RelationService = class {
 					}));
 					if (newLinks.length > 0) await tx.insert(junctionTable).values(newLinks);
 				}
-			} else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") logger.warn(`[updateRelationsUsingJoins] Inverse M2M relation '${key}' in collection '${collection.slug}' should be saved from the owning side. Skipping.`);
-			else if (relation.cardinality === "many" && relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+			} else if (relation.cardinality === "many" && hasForeignKeyOnTarget(relation)) {
 				const targetTable = getTableForCollection(targetCollection, this.registry);
 				const targetPks = requirePrimaryKeys(targetCollection, this.registry);
 				const targetIdInfo = targetPks[0];
@@ -2008,28 +1910,20 @@ var RelationService = class {
 				const targetIdInfo = targetPks[0];
 				const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
 				const sourceIdInfo = sourcePks[0];
-				if (relation.direction === "inverse" && relation.joinPath && relation.joinPath.length > 0) {
+				if (relation.kind === "via") {
 					await this.updateInverseJoinPathRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue);
 					continue;
 				}
-				if (relation.cardinality === "many" && relation.direction === "inverse") {
-					const targetCollectionRelations = resolveCollectionRelations(targetCollection);
-					let junctionInfo = null;
-					for (const [relationKey, targetRelation] of Object.entries(targetCollectionRelations)) if (targetRelation.cardinality === "many" && targetRelation.direction === "owning" && targetRelation.through && (targetRelation.relationName === relation.inverseRelationName || relationKey === relation.inverseRelationName)) {
-						junctionInfo = {
-							table: targetRelation.through.table,
-							sourceColumn: targetRelation.through.targetColumn,
-							targetColumn: targetRelation.through.sourceColumn
-						};
-						break;
-					}
-					if (junctionInfo) {
-						await this.updateManyToManyInverseRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue, junctionInfo);
-						continue;
-					}
+				if (isManyToMany(relation)) {
+					await this.updateManyToManyInverseRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue, {
+						table: relation.through.table,
+						sourceColumn: relation.through.sourceColumn,
+						targetColumn: relation.through.targetColumn
+					});
+					continue;
 				}
-				if (!relation.foreignKeyOnTarget) {
-					logger.warn(`Inverse relation '${relation.relationName}' is missing foreignKeyOnTarget property. Skipping.`);
+				if (!hasForeignKeyOnTarget(relation)) {
+					logger.warn(`Relation '${relation.relationName}' has no column on the target to write. Skipping.`);
 					continue;
 				}
 				const foreignKeyColumn = targetTable[relation.foreignKeyOnTarget];
@@ -2055,10 +1949,6 @@ var RelationService = class {
 	*/
 	async updateInverseJoinPathRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue) {
 		try {
-			if (!relation.joinPath || relation.joinPath.length === 0) {
-				logger.warn(`Inverse relation '${relation.relationName}' missing joinPath`);
-				return;
-			}
 			const sourceTableName = getTableName$1(sourceCollection);
 			const targetTableName = getTableName$1(targetCollection);
 			const intermediateTables = relation.joinPath.map((step) => step.table).filter((table) => table !== sourceTableName && table !== targetTableName);
@@ -2258,9 +2148,8 @@ var RelationService = class {
 * to unwrap that same level back out.
 */
 function isJunctionRelation(relation) {
-	if (relation.through) return true;
-	if (relation.joinPath && relation.joinPath.length > 1) return true;
-	return false;
+	if (isManyToMany(relation)) return true;
+	return relation.kind === "via" && relation.joinPath.length > 1;
 }
 /**
 * Reach the target row inside a junction row.
@@ -2450,7 +2339,7 @@ function resolveNestedPath(path, registry) {
 * such a path addresses the *link*, not the row.
 */
 function isJunctionBackedRelation(relation) {
-	return Boolean(relation.through) || Boolean(relation.joinPath && relation.joinPath.length > 1);
+	return relation.shared;
 }
 /**
 * Reject a nested write whose final segment is a to-one relation.
@@ -2463,7 +2352,10 @@ function isJunctionBackedRelation(relation) {
 * one.
 */
 function assertWritableThrough(hop, path) {
-	if (hop.relation.cardinality !== "many") throw ApiError.badRequest(`"${path}" ends in the to-one relation '${hop.relationKey}', which cannot be written through: the foreign key for a to-one relation lives on '${hop.parentCollection.slug}', not on '${hop.targetCollection.slug}'. Write the target row at "${hop.targetCollection.slug}" and set '${hop.relationKey}' on the parent instead.`, "RELATION_NOT_WRITABLE");
+	const { relation } = hop;
+	if (relation.writable && relation.cardinality === "many") return;
+	if (!relation.writable) throw ApiError.badRequest(`"${path}" ends in '${hop.relationKey}', a \`via\` relation. Rebase will not infer how to write through an arbitrary join chain — write the row at "${hop.targetCollection.slug}" directly.`, "RELATION_NOT_WRITABLE");
+	throw ApiError.badRequest(`"${path}" ends in the to-one relation '${hop.relationKey}', which cannot be written through: the foreign key for a to-one relation lives on '${hop.parentCollection.slug}', not on '${hop.targetCollection.slug}'. Write the target row at "${hop.targetCollection.slug}" and set '${hop.relationKey}' on the parent instead.`, "RELATION_NOT_WRITABLE");
 }
 //#endregion
 //#region src/services/FetchService.ts
@@ -2502,7 +2394,7 @@ var FetchService = class {
 		let orderByField = table[orderBy];
 		if (!orderByField && collection) {
 			const property = collection.properties[orderBy];
-			if (property && property.type === "relation" && "relation" in property && property.relation?.direction === "owning") orderByField = table[`${orderBy}_id`];
+			if (property && property.type === "relation" && "relation" in property && property.resolvedRelation?.kind === "belongsTo") orderByField = table[`${orderBy}_id`];
 		}
 		return orderByField;
 	}
@@ -2523,7 +2415,7 @@ var FetchService = class {
 		for (const [key, relation] of Object.entries(resolvedRelations)) {
 			if (!shouldInclude(key)) continue;
 			const drizzleRelName = relation.relationName || key;
-			if (relation.joinPath && relation.joinPath.length > 0) continue;
+			if (relation.kind === "via") continue;
 			if (relation.cardinality === "many" && isJunctionRelation(relation)) {
 				const targetFkName = this.getJunctionTargetRelationName(relation, collection);
 				if (targetFkName) withConfig[drizzleRelName] = { with: { [targetFkName]: true } };
@@ -2537,7 +2429,7 @@ var FetchService = class {
 	* For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
 	*/
 	getJunctionTargetRelationName(relation, _collection) {
-		if (relation.through) return relation.through.targetColumn.replace(/_id$/, "_id");
+		if (isManyToMany(relation)) return relation.through.targetColumn.replace(/_id$/, "_id");
 		return null;
 	}
 	/**
@@ -2547,7 +2439,7 @@ var FetchService = class {
 	*/
 	async resolveJoinPathRelations(row, collection, collectionPath, parsedId, _databaseId) {
 		const resolvedRelations = resolveCollectionRelations(collection);
-		const promises = Object.entries(resolvedRelations).filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0).map(async ([key, relation]) => {
+		const promises = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via").map(async ([key, relation]) => {
 			try {
 				const relatedRows = await this.relationService.fetchRelatedEntities(collectionPath, parsedId, key, { limit: relation.cardinality === "one" ? 1 : void 0 });
 				if (relation.cardinality === "one" && relatedRows.length > 0) {
@@ -2569,7 +2461,7 @@ var FetchService = class {
 		const resolvedRelations = resolveCollectionRelations(collection);
 		const propertyKeys = new Set(Object.keys(collection.properties || {}));
 		const shouldInclude = (key) => !include || include.length === 0 || include[0] === "*" || include.includes(key);
-		const joinPathRelations = Object.entries(resolvedRelations).filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0 && propertyKeys.has(key) && shouldInclude(key));
+		const joinPathRelations = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via" && propertyKeys.has(key) && shouldInclude(key));
 		if (joinPathRelations.length === 0) return;
 		const parentIdOf = (row) => {
 			const address = buildCompositeId(row, idInfoArray);
@@ -2723,7 +2615,7 @@ var FetchService = class {
 			return flatRow;
 		} catch (e) {
 			if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-				logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+				logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
 				logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
 			}
 			logger.warn(`[FetchService] db.query.findFirst failed for ${collectionPath}, falling back to db.select`, { error: e });
@@ -2774,7 +2666,7 @@ var FetchService = class {
 			return (await qb.findMany(queryOpts)).map((row) => toCmsRow(row, collection, this.registry));
 		} catch (e) {
 			if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-				logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+				logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
 				logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
 			}
 			logger.warn(`[FetchService] db.query.findMany failed for ${collectionPath}, falling back to db.select`, { error: e });
@@ -2989,7 +2881,7 @@ var FetchService = class {
 			return restRows;
 		} catch (e) {
 			if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-				logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+				logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
 				logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
 			}
 			logger.warn(`[fetchCollectionForRest] db.query.findMany failed for ${collectionPath}, falling back`, { error: e });
@@ -3052,7 +2944,7 @@ var FetchService = class {
 			return restRow;
 		} catch (e) {
 			if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-				logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+				logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
 				logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
 			}
 			logger.warn(`[fetchOneForRest] db.query.findFirst failed for ${collectionPath}, falling back`, { error: e });
@@ -3200,7 +3092,7 @@ var FetchService = class {
 		if (parentIds.length === 0) return /* @__PURE__ */ new Map();
 		const relation = resolveCollectionRelations(getCollectionByPath(parentCollectionPath, this.registry))[relationKey];
 		if (!relation) {
-			logger.warn(`[batchFetchManyRelatedRows] Relation '${relationKey}' not found, skipping`);
+			logger.warn(`[batchFetchManyRelatedRows] ResolvedRelation '${relationKey}' not found, skipping`);
 			return /* @__PURE__ */ new Map();
 		}
 		const entityMap = await this.relationService.batchFetchRelatedEntitiesMany(parentCollectionPath, parentIds, relationKey, relation);
@@ -3425,7 +3317,7 @@ var PersistService = class {
 			assertWritableThrough(hop, collectionPath);
 			if (!await this.relationService.isRelated(hop, id)) throw ApiError.notFound(`No row "${id}" in "${collectionPath}" to delete.`);
 			if (isJunctionBackedRelation(hop.relation)) {
-				if (!hop.relation.through) throw ApiError.badRequest(`"${collectionPath}" reaches '${hop.targetCollection.slug}' through a multi-hop joinPath, so there is no single link to remove. Delete the row at "${hop.targetCollection.slug}" directly if that is what you meant.`, "RELATION_NOT_UNLINKABLE");
+				if (!isManyToMany(hop.relation)) throw ApiError.badRequest(`"${collectionPath}" reaches '${hop.targetCollection.slug}' through a multi-hop joinPath, so there is no single link to remove. Delete the row at "${hop.targetCollection.slug}" directly if that is what you meant.`, "RELATION_NOT_UNLINKABLE");
 				await this.relationService.unlinkRelatedEntity(this.db, hop, id);
 				return;
 			}
@@ -3461,16 +3353,13 @@ var PersistService = class {
 	* do, and first — stamped the parent's own foreign key onto the child row.
 	*/
 	resolveParentForeignKeyColumn(hop) {
-		const { relation, relationKey, targetCollection } = hop;
-		if (relation.foreignKeyOnTarget) return relation.foreignKeyOnTarget;
-		if (relation.joinPath && relation.joinPath.length === 1) {
-			const joinStep = relation.joinPath[0];
-			const targetTableName = getTableName$1(targetCollection);
-			if (joinStep.table !== targetTableName) logger.warn(`Join step for relation '${relationKey}' targets '${joinStep.table}', not the target table '${targetTableName}'.`);
-			return DrizzleConditionBuilder.getColumnNamesFromColumns(joinStep.on.to)[0];
+		const { relation } = hop;
+		switch (relation.kind) {
+			case "hasOne":
+			case "hasMany": return relation.foreignKeyOnTarget;
+			case "via": return relation.joinPath.length === 1 ? DrizzleConditionBuilder.getColumnNamesFromColumns(relation.joinPath[0].on.to)[0] : void 0;
+			default: return;
 		}
-		if (relation.joinPath && relation.joinPath.length > 1) return;
-		throw ApiError.badRequest(`Relation '${relationKey}' on '${hop.parentCollection.slug}' cannot be written through: it declares no \`foreignKeyOnTarget\` (the column on '${targetCollection.slug}' that records the parent) and no \`joinPath\`.`, "RELATION_NOT_WRITABLE");
 	}
 	/**
 	* Save an row (create or update)
@@ -3493,7 +3382,7 @@ var PersistService = class {
 				const parentPks = getPrimaryKeys(hop.parentCollection, this.registry);
 				return parseIdValues(hop.parentId, parentPks)[parentPks[0].fieldName];
 			};
-			if (hop.relation.through) junctionTableInfo = {
+			if (isManyToMany(hop.relation)) junctionTableInfo = {
 				parentCollection: hop.parentCollection,
 				parentId: parentIdForWrite(),
 				relation: hop.relation,
@@ -5546,12 +5435,8 @@ var getDrizzleColumn = (propName, prop, collection, collections) => {
 			break;
 		case "relation": {
 			const refProp = prop;
-			const relation = findRelation(resolveCollectionRelations(collection), refProp.relationName ?? propName);
-			if (!relation || relation.direction !== "owning" || relation.cardinality !== "one") return null;
-			if (!relation.localKey) {
-				logger.warn(`Could not generate column for owning relation '${relation.relationName}' on '${collection.name}': 'localKey' is not defined.`);
-				return null;
-			}
+			const relation = findRelation(resolveCollectionRelations(collection), refProp.relation?.relationName ?? propName);
+			if (!relation || relation.kind !== "belongsTo") return null;
 			if (collection.properties[relation.localKey] && propName !== relation.localKey) return null;
 			let targetCollection;
 			try {
@@ -5645,33 +5530,17 @@ var generateSinglePolicyCode = (collection, rule, operation, policyName, resolve
 */
 var computeSharedRelationName = (rel, sourceCollection, _collections) => {
 	const fallback = rel.relationName ?? toSnakeCase(rel.target().slug);
-	if (rel.direction === "owning" && rel.cardinality === "one" && rel.localKey) {
+	if (rel.kind === "belongsTo") {
 		const normalisedKey = resolvePropertyKeyForColumn(sourceCollection, rel.localKey);
 		return `${getTableName$1(sourceCollection)}_${normalisedKey}`;
 	}
-	if (rel.direction === "inverse" && rel.cardinality === "many" && rel.foreignKeyOnTarget) try {
+	if (rel.kind === "hasMany" || rel.kind === "hasOne") try {
 		const targetCollection = rel.target();
 		const normalisedFK = resolvePropertyKeyForColumn(targetCollection, rel.foreignKeyOnTarget);
 		return `${getTableName$1(targetCollection)}_${normalisedFK}`;
 	} catch {
 		return fallback;
 	}
-	if (rel.direction === "inverse" && rel.cardinality === "one") {
-		if (rel.foreignKeyOnTarget) try {
-			const targetCollection = rel.target();
-			const normalisedFK = resolvePropertyKeyForColumn(targetCollection, rel.foreignKeyOnTarget);
-			return `${getTableName$1(targetCollection)}_${normalisedFK}`;
-		} catch {
-			return fallback;
-		}
-		try {
-			const targetCollection = rel.target();
-			const targetResolvedRelations = resolveCollectionRelations(targetCollection);
-			const correspondingRelation = Object.values(targetResolvedRelations).find((targetRel) => targetRel.direction === "owning" && targetRel.cardinality === "one" && targetRel.localKey && targetRel.target().slug === sourceCollection.slug);
-			if (correspondingRelation && correspondingRelation.localKey) return `${getTableName$1(targetCollection)}_${correspondingRelation.localKey}`;
-		} catch {}
-		return fallback;
-	}
 	return fallback;
 };
 var generateSchema = async (collections, stripPolicies = false) => {
@@ -5736,7 +5605,7 @@ var generateSchema = async (collections, stripPolicies = false) => {
 		const tableName = getTableName$1(collection);
 		if (tableName) allTablesToGenerate.set(tableName, { collection });
 		const resolvedRelations = resolveCollectionRelations(collection);
-		for (const relation of Object.values(resolvedRelations)) if (relation.through) {
+		for (const relation of Object.values(resolvedRelations)) if (isManyToMany(relation)) {
 			const junctionTableName = relation.through.table;
 			if (!allTablesToGenerate.has(junctionTableName)) allTablesToGenerate.set(junctionTableName, {
 				collection: {
@@ -5751,7 +5620,7 @@ var generateSchema = async (collections, stripPolicies = false) => {
 	}
 	for (const [tableName, { collection, isJunction, relation, sourceCollection }] of allTablesToGenerate.entries()) {
 		const tableVarName = getTableVarName(tableName);
-		if (isJunction && relation && sourceCollection && relation.through) {
+		if (isJunction && relation && sourceCollection && isManyToMany(relation)) {
 			const targetCollection = relation.target();
 			const schema = (isPostgresCollectionConfig(targetCollection) ? targetCollection.schema : void 0) || (isPostgresCollectionConfig(sourceCollection) ? sourceCollection.schema : void 0);
 			const tableCreator = schema ? `${schema}Schema.table` : "pgTable";
@@ -5805,7 +5674,7 @@ var generateSchema = async (collections, stripPolicies = false) => {
 		const tableRelations = [];
 		if (isJunction) {
 			const relationInfo = Array.from(allTablesToGenerate.values()).find((v) => v.isJunction && getTableName$1(v.collection) === tableName);
-			if (relationInfo && relationInfo.relation && relationInfo.sourceCollection && relationInfo.relation.through) {
+			if (relationInfo && relationInfo.relation && relationInfo.sourceCollection && isManyToMany(relationInfo.relation)) {
 				const { relation, sourceCollection } = relationInfo;
 				const targetCollection = relation.target();
 				const sourceTableVar = getTableVarName(getTableName$1(sourceCollection));
@@ -5817,7 +5686,7 @@ var generateSchema = async (collections, stripPolicies = false) => {
 				let inverseRelationName = null;
 				try {
 					const targetRelations = resolveCollectionRelations(targetCollection);
-					for (const [, targetRel] of Object.entries(targetRelations)) if (targetRel.direction === "inverse" && targetRel.cardinality === "many" && targetRel.inverseRelationName === owningRelationName) {
+					for (const [, targetRel] of Object.entries(targetRelations)) if (targetRel.kind !== "belongsTo" && targetRel.cardinality === "many" && targetRel.relationName === owningRelationName) {
 						inverseRelationName = targetRel.relationName ?? null;
 						break;
 					}
@@ -5833,27 +5702,25 @@ var generateSchema = async (collections, stripPolicies = false) => {
 				const target = rel.target();
 				const targetTableVar = getTableVarName(getTableName$1(target));
 				const drizzleRelationName = computeSharedRelationName(rel, collection, collections);
-				const deduplicationKey = `${drizzleRelationName}::${rel.direction}`;
+				const deduplicationKey = `${drizzleRelationName}::${rel.kind}`;
 				if (emittedRelationNames.has(deduplicationKey)) continue;
 				emittedRelationNames.add(deduplicationKey);
-				if (rel.cardinality === "one") {
-					if (rel.direction === "owning" && rel.localKey) tableRelations.push(`    "${relationKey}": one(${targetTableVar}, {\n        fields: [${tableVarName}.${rel.localKey}],\n        references: [${targetTableVar}.${getPrimaryKeyName(target)}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
-					else if (rel.direction === "inverse") tableRelations.push(`    "${relationKey}": one(${targetTableVar}, {\n        relationName: \"${drizzleRelationName}\"\n    })`);
-				} else if (rel.cardinality === "many") {
-					if (rel.direction === "inverse" && rel.foreignKeyOnTarget) tableRelations.push(`    "${relationKey}": many(${targetTableVar}, { relationName: \"${drizzleRelationName}\" })`);
-					else if (rel.through) {
+				switch (rel.kind) {
+					case "belongsTo":
+						tableRelations.push(`    "${relationKey}": one(${targetTableVar}, {\n        fields: [${tableVarName}.${rel.localKey}],\n        references: [${targetTableVar}.${getPrimaryKeyName(target)}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
+						break;
+					case "hasOne":
+						tableRelations.push(`    "${relationKey}": one(${targetTableVar}, {\n        relationName: \"${drizzleRelationName}\"\n    })`);
+						break;
+					case "hasMany":
+						tableRelations.push(`    "${relationKey}": many(${targetTableVar}, { relationName: \"${drizzleRelationName}\" })`);
+						break;
+					case "manyToMany": {
 						const junctionTableVar = getTableVarName(rel.through.table);
 						tableRelations.push(`    "${relationKey}": many(${junctionTableVar}, { relationName: \"${drizzleRelationName}\" })`);
-					} else if (rel.direction === "inverse" && rel.inverseRelationName) try {
-						const targetResolvedRelations = resolveCollectionRelations(rel.target());
-						const correspondingRelation = Object.values(targetResolvedRelations).find((targetRel) => targetRel.direction === "owning" && targetRel.cardinality === "many" && targetRel.through && targetRel.relationName === rel.inverseRelationName);
-						if (correspondingRelation && correspondingRelation.through) {
-							const junctionTableVar = getTableVarName(correspondingRelation.through.table);
-							tableRelations.push(`    "${relationKey}": many(${junctionTableVar}, { relationName: \"${drizzleRelationName}\" })`);
-						} else logger.warn(`Could not find corresponding owning many-to-many relation for inverse relation '${relationKey}' on '${collection.name}'`);
-					} catch (e) {
-						logger.warn(`Could not resolve inverse many-to-many relation '${relationKey}'`, { error: e });
+						break;
 					}
+					case "via": break;
 				}
 			} catch (e) {
 				logger.warn(`Could not generate relation ${relationKey} for ${collection.name}`, { error: e });
@@ -5861,10 +5728,10 @@ var generateSchema = async (collections, stripPolicies = false) => {
 			for (const otherCollection of collections) {
 				if (otherCollection.slug === collection.slug) continue;
 				const otherRelations = resolveCollectionRelations(otherCollection);
-				for (const [otherKey, otherRel] of Object.entries(otherRelations)) if (otherRel.direction === "inverse" && otherRel.foreignKeyOnTarget) try {
+				for (const [otherKey, otherRel] of Object.entries(otherRelations)) if (hasForeignKeyOnTarget(otherRel)) try {
 					if (otherRel.target().slug === collection.slug) {
 						const drizzleRelationName = computeSharedRelationName(otherRel, otherCollection, collections);
-						const deduplicationKey = `${drizzleRelationName}::owning`;
+						const deduplicationKey = `${drizzleRelationName}::belongsTo`;
 						if (!emittedRelationNames.has(deduplicationKey)) {
 							const otherTableVar = getTableVarName(getTableName$1(otherCollection));
 							const drizzleFieldKey = resolvePropertyKeyForColumn(collection, otherRel.foreignKeyOnTarget);
@@ -5986,8 +5853,8 @@ function collectJunctionLinks(registry) {
 			continue;
 		}
 		for (const [relationKey, relation] of Object.entries(relations)) {
-			const through = relation?.through;
-			if (!through?.table) continue;
+			if (!isManyToMany(relation)) continue;
+			const through = relation.through;
 			const key = `${collection.slug}::${relationKey}::${through.table}`;
 			if (seen.has(key)) continue;
 			seen.add(key);
@@ -9080,8 +8947,8 @@ var PostgresCollectionRegistry = class extends CollectionRegistry {
 	*/
 	getRelationKeysForCollection(collectionPath) {
 		const collection = this.getCollectionByPath(collectionPath);
-		if (!collection || !getDataSourceCapabilities(collection.engine).supportsRelations || !collection.relations) return [];
-		return collection.relations.map((r) => r.relationName || r.localKey || "").filter(Boolean);
+		if (!collection) return [];
+		return Object.keys(resolveCollectionRelations(collection));
 	}
 };
 //#endregion
@@ -18032,6 +17899,178 @@ function formatBytes(bytes) {
 	return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
 //#endregion
+//#region src/collections/validate-relations.ts
+/**
+* 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) {
+	const names = /* @__PURE__ */ new Set();
+	for (const [key, col] of Object.entries(getTableColumns(table))) {
+		names.add(key);
+		const dbName = col?.name;
+		if (dbName) names.add(dbName);
+	}
+	return names;
+}
+var quote = (xs) => Array.from(xs).map((s) => `\`${s}\``).join(", ");
+/** `on.from` / `on.to` accept a single column or a composite tuple. */
+var asColumns = (value) => 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.
+*/
+function findRelationDefects(collections, registry) {
+	const defects = [];
+	const registeredSlugs = new Set(registry.getCollections().map((c) => c.slug));
+	for (const collection of collections) {
+		const sourceTableName = getTableName$1(collection);
+		const sourceTable = registry.getTable(sourceTableName);
+		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;
+			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;
+			}
+			if (!registeredSlugs.has(targetCollection.slug)) continue;
+			const targetTableName = getTableName$1(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]]) 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;
+					}
+					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;
+					}
+					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: throw new Error(`Unhandled relation kind: ${JSON.stringify(relation)}`);
+			}
+		}
+	}
+	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.
+*/
+function assertRelationsResolve(collections, registry) {
+	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\nEach of these would return no rows at query time rather than reporting an error, so they are fatal at boot instead.
+
+` + lines.join("\n\n") + "\n");
+}
+//#endregion
 //#region src/collections/buildRegistry.ts
 /**
 * Build the collection registry for a driver.
@@ -18056,8 +18095,163 @@ function buildCollectionRegistry(schema) {
 	if (schema.enums) registry.registerEnums(schema.enums);
 	if (schema.relations) registry.registerRelations(schema.relations);
 	warnOnKeysTheAdminCannotResolve(registry.getCollections(), registry);
+	assertRelationsResolve(registry.getCollections(), registry);
 	return registry;
 }
+/** Key under which the version is stored in the auth schema's meta table. */
+var 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`.
+*/
+var 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.
+*/
+var 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.
+*/
+var AuthSchemaVersionError = class extends Error {
+	databaseVersion;
+	runtimeVersion;
+	constructor(databaseVersion, runtimeVersion) {
+		super(`Auth schema version mismatch: the database is at version ${databaseVersion}, but this runtime understands version ${runtimeVersion}.\n\nA 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.
+
+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.
+*/
+function resolveAuthSchema(collection) {
+	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.
+*/
+async function readAuthSchemaVersion(db, authSchema) {
+	const qualified = `"${authSchema}"."schema_meta"`;
+	if (!(await db.execute(sql`SELECT to_regclass(${qualified}) IS NOT NULL AS present`)).rows[0]?.present) return null;
+	const raw = (await db.execute(sql`
+        SELECT value FROM ${sql.raw(qualified)} WHERE key = ${VERSION_KEY}
+    `)).rows[0]?.value;
+	if (raw === void 0) return null;
+	const parsed = Number.parseInt(raw, 10);
+	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.
+*/
+async function assertAuthSchemaCompatible(db, authSchema) {
+	const databaseVersion = await readAuthSchemaVersion(db, authSchema);
+	if (databaseVersion !== null && databaseVersion > 2) throw new AuthSchemaVersionError(databaseVersion, 2);
+}
+/**
+* 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.
+*/
+async function stampAuthSchemaVersion(db, authSchema) {
+	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(2)})
+        ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = NOW()
+    `);
+}
+/**
+* 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.
+*/
+async function probeAuthSchema(db, authSchema) {
+	const problems = [];
+	let databaseVersion = null;
+	try {
+		databaseVersion = await readAuthSchemaVersion(db, authSchema);
+		if (databaseVersion !== null && databaseVersion > 2) problems.push(`database is at auth schema version ${databaseVersion}, this runtime understands 2 — it was migrated by a newer framework version`);
+		const refreshTokens = `"${authSchema}"."refresh_tokens"`;
+		if (!(await db.execute(sql`SELECT to_regclass(${refreshTokens}) IS NOT NULL AS present`)).rows[0]?.present) return {
+			healthy: problems.length === 0,
+			databaseVersion,
+			runtimeVersion: 2,
+			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.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`);
+		if ((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}
+        `)).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) {
+		problems.push(`auth schema probe failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return {
+		healthy: problems.length === 0,
+		databaseVersion,
+		runtimeVersion: 2,
+		problems
+	};
+}
 //#endregion
 //#region src/auth/ensure-tables.ts
 /**
@@ -18069,6 +18263,7 @@ function buildCollectionRegistry(schema) {
 */
 async function ensureAuthTablesExist(db, collection) {
 	logger.info("🔍 Checking auth tables...");
+	await assertAuthSchemaCompatible(db, resolveAuthSchema(collection));
 	try {
 		let usersTableName = "\"rebase\".\"users\"";
 		let userIdType = "TEXT";
@@ -18449,8 +18644,10 @@ async function ensureAuthTablesExist(db, collection) {
 		} catch (rlsReconcileError) {
 			logger.warn(`⚠️  Could not reconcile FORCE ROW LEVEL SECURITY on auth tables: ${rlsReconcileError instanceof Error ? rlsReconcileError.message : String(rlsReconcileError)}`);
 		}
+		await stampAuthSchemaVersion(db, authSchema);
 		logger.info("✅ Auth tables ready");
 	} catch (error) {
+		if (error instanceof AuthSchemaVersionError) throw error;
 		logger.error("❌ Failed to create auth tables", { error });
 		logger.warn("⚠️ Continuing without creating auth tables.");
 	}
@@ -20548,7 +20745,8 @@ function createPostgresBootstrapper(pgConfig) {
 				userService,
 				roleService: userService,
 				emailService,
-				authRepository
+				authRepository,
+				schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection))
 			};
 		},
 		async initializeHistory(config, driverResult) {
@@ -20576,7 +20774,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionSchema(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionTables } = await import("./ensure-collection-tables-BVvtkkRm.js");
+			const { ensureCollectionTables } = await import("./ensure-collection-tables-DGMYK0fr.js");
 			return { applied: (await ensureCollectionTables({ async query(text) {
 				const result = await internals.db.execute(sql.raw(text));
 				return { rows: result.rows ?? (Array.isArray(result) ? result : []) };