@rebasepro/server-postgres 0.12.1-canary.g4e7bcbf → 0.12.1-canary.g6861540

package/dist/index.es.js

@@ -2,11 +2,11 @@ import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
 import { a as guardPoolAgainstDirtyRelease, i as createReadReplicaConnection, n as createDirectDatabaseConnection, o as pinSearchPath, r as createPostgresDatabaseConnection } from "./connection-BuZ97wsr.js";
-import { C as updateDateAutoValues, D as mergeDeep, E as getPolicyNamesForRule, M as hasForeignKeyOnTarget, N as isManyToMany, O as camelCase, P as Vector, S as normalizeToEntityRelation, _ as buildCompositeId, a as getJunctionSecurityRules, b as createRelationRef, c as policyToPostgres, d as findRelation, f as getColumnName, g as resolveCollectionRelations, h as getTableVarName, i as getJunctionCollectionConfig, k as toSnakeCase, l as securityRuleToConditions, m as getTableName$1, n as CollectionRegistry, o as resolveJunctionSpecs, p as getEnumVarName, r as resolveStringColumnLength, s as getEffectiveSecurityRules, t as buildSdkData, u as findAnonymousGrants, v as getDeclaredPrimaryKeys, w as generateForeignKeyName, x as createRelationRefWithData, y as parseIdValues } from "./src-BkdpiQdw.js";
+import { C as updateDateAutoValues, D as mergeDeep, E as getPolicyNamesForRule, M as hasForeignKeyOnTarget, N as isManyToMany, O as camelCase, P as Vector, S as normalizeToEntityRelation, _ as buildCompositeId, a as getJunctionSecurityRules, b as createRelationRef, c as policyToPostgres, d as findRelation, f as getColumnName, g as resolveCollectionRelations, h as getTableVarName, i as getJunctionCollectionConfig, k as toSnakeCase, l as securityRuleToConditions, m as getTableName$1, n as CollectionRegistry, o as resolveJunctionSpecs, p as getEnumVarName, r as resolveStringColumnLength, s as getEffectiveSecurityRules, t as buildSdkData, u as findAnonymousGrants, v as getDeclaredPrimaryKeys, w as generateForeignKeyName, x as createRelationRefWithData, y as parseIdValues } from "./src-CzbghKwf.js";
 import { n as isPostgresCollectionConfig, r as isRelationalCollectionConfig } from "./src-DoU9yPqq.js";
 import { t as ANONYMOUS_USER_ID } from "./policy-CeA1JcxP.js";
 import { t as createPostgresWebSocket } from "./websocket-B2LsrINK.js";
-import { A as serverVersionNumToMajor, C as globalsFileForDump, D as parseDbNameFromUrl, E as parseBackupTimestamp, M as withDatabaseName, O as parsePgToolMajor, S as checkToolServerCompatibility, T as parseBackupDestination, _ as buildBackupFilename, a as detectToolMajor, b as buildPgRestoreArgs, c as listBackups, d as resolvePgBinary, f as restoreDump, g as selectBackupsToPrune, h as require_source, i as createDump, j as splitGlobalsStatements, k as resolveConnectionString, l as preflight, m as validateDump, n as applyGlobals, o as ensureDatabaseExists, p as uploadBackup, s as getServerVersionMajor, t as BackupToolError, u as pruneBackups, v as buildPgDumpArgs, w as joinStorageKey, x as buildPgRestoreListArgs, y as buildPgDumpallGlobalsArgs } from "./backup-service-DLb2drIH.js";
+import { A as parsePgToolMajor, C as checkToolServerCompatibility, D as parseBackupDestination, E as joinStorageKey, M as serverVersionNumToMajor, N as splitGlobalsStatements, O as parseBackupTimestamp, P as withDatabaseName, S as buildRowSecurityPgOptions, T as globalsFileForDump, _ as buildBackupFilename, a as detectToolMajor, b as buildPgRestoreArgs, c as listBackups, d as resolvePgBinary, f as restoreDump, g as selectBackupsToPrune, h as require_source, i as createDump, j as resolveConnectionString, k as parseDbNameFromUrl, l as preflight, m as validateDump, n as applyGlobals, o as ensureDatabaseExists, p as uploadBackup, s as getServerVersionMajor, t as BackupToolError, u as pruneBackups, v as buildPgDumpArgs, w as diagnoseRowSecurityDumpFailure, x as buildPgRestoreListArgs, y as buildPgDumpallGlobalsArgs } from "./backup-service-CD8o_1Sl.js";
 import { Client, Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { ApiError, createEmailService, loadCollectionsFromDirectory, logger } from "@rebasepro/server";
@@ -50,6 +50,39 @@ function resolveClientListLimit(rawLimit, opts = {}) {
 	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
 }
 //#endregion
+//#region ../common/src/util/email.ts
+/**
+* Email normalization — one implementation, because the database enforces it.
+*
+* `ensureAuthTablesExist` puts a `UNIQUE INDEX ON users (lower(email))` on the
+* auth table. That index decides what "the same address" means, and it does not
+* trim: to Postgres, `' foo@bar.com'` and `'foo@bar.com'` are two addresses and
+* both may exist. So every write that reaches the column has to agree with
+* every read, exactly, or the two disagree in the one direction that matters —
+* a row that exists and cannot be found.
+*
+* That is not hypothetical. The lookup path trimmed and the admin create paths
+* did not, so a user created through `POST /api/data/users` or
+* `POST /api/auth/admin/users` with a stray space was stored untrimmed,
+* survived the unique index alongside the real address, and was unreachable by
+* login forever after. The HTTP auth routes were unaffected only because Zod's
+* `.email()` happens to reject surrounding whitespace — a guard on a different
+* layer, for a different reason, that the admin paths do not sit behind.
+*
+* It lives in `common` because `server`, `server-postgres` and `server-mongo`
+* all write this column and must agree exactly, and `common` is the only
+* package all three already depend on.
+*/
+/**
+* Canonical form of an email address: trimmed, lower-cased.
+*
+* Non-strings pass through untouched, so this is safe to apply to a value out
+* of a partial update payload whose type is not known yet.
+*/
+function normalizeEmail(email) {
+	return typeof email === "string" ? email.trim().toLowerCase() : email;
+}
+//#endregion
 //#region ../common/src/util/callbacks.ts
 /**
 * Helper function to recursively check if there are any callbacks in the properties.
@@ -282,6 +315,35 @@ function requirePrimaryKeys(collection, registry) {
 	return keys;
 }
 /**
+* The column on the *source* table that a `hasOne`/`hasMany` link points at.
+*
+* `sourceKey` is authored when the two sides join on a natural key — an
+* external identity id, a SKU — and left off when they join on the row id,
+* which is the overwhelming majority. That makes `undefined` the only optional
+* field on a resolved relation, so it gets exactly one reader: this function.
+* Every consumer that needs the column asks here, and none of them re-derives
+* "or else the primary key" for itself. That is the whole point — the fallback
+* chains this codebase removed from relation resolution were dangerous because
+* they were *duplicated* and could disagree, not because they existed.
+*/
+function sourceKeyField(relation, sourceCollection, registry) {
+	if (relation.sourceKey) return relation.sourceKey;
+	return requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+/**
+* Whether this link joins on something other than the source's primary key.
+*
+* Callers that hold a parent *id* — which is most of them, since an id is what
+* a URL carries — must translate it to the source key's value before it can be
+* compared with the target's foreign key. Those that hold the parent *row*, or
+* that build a correlated subquery over the source table, can read the column
+* directly and skip the lookup.
+*/
+function joinsOnNaturalKey(relation, sourceCollection, registry) {
+	if (!relation.sourceKey) return false;
+	return relation.sourceKey !== requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+/**
 * Collections whose key the *browser* cannot resolve, and what it will do
 * instead.
 *
@@ -452,7 +514,9 @@ var DrizzleConditionBuilder = class {
 			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);
+				if (!relation.sourceKey) return eq(fkColumn, parentId);
+				const { table, idColumn } = parent();
+				return sql`${fkColumn} = (SELECT ${sql.identifier(relation.sourceKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
 			}
 			case "belongsTo": {
 				const { table, idColumn } = parent();
@@ -542,12 +606,16 @@ var DrizzleConditionBuilder = class {
 					column: foreignKey
 				};
 			}
-			if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) return {
-				kind: "relation",
-				relation,
-				registry,
-				sourceIdColumn
-			};
+			if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) {
+				const correlationColumn = hasForeignKeyOnTarget(relation) && relation.sourceKey ? columnAt(relation.sourceKey) : sourceIdColumn;
+				if (!correlationColumn) throw new Error(`\`sourceKey: "${relation.sourceKey}"\` on relation '${relation.relationName}' is not a column on '${collectionPath}', so a filter on that relation has nothing to correlate against.`);
+				return {
+					kind: "relation",
+					relation,
+					registry,
+					sourceIdColumn: correlationColumn
+				};
+			}
 		}
 		for (const guess of [`${field}_id`, generateForeignKeyName(field)]) {
 			const foreignKey = columnAt(guess);
@@ -1346,8 +1414,9 @@ async function parseDataFromServer(data, collection, db, registry) {
 			} 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));
-				if (targetTable && currentId) {
+				const pks = getPrimaryKeys(collection, registry);
+				const currentId = relation.sourceKey ? data[relation.sourceKey] : buildCompositeId(data, pks);
+				if (targetTable && currentId !== void 0 && currentId !== null && currentId !== "") {
 					const foreignKeyColumn = targetTable[relation.foreignKeyOnTarget];
 					if (foreignKeyColumn) {
 						const relatedRows = await db.select().from(targetTable).where(eq(foreignKeyColumn, currentId)).limit(relation.cardinality === "one" ? 1 : 100);
@@ -1719,8 +1788,67 @@ var RelationService = class {
 	* reading. Left alone it would silently match on the first key column and
 	* hand a tenant's rows to its neighbour — say so instead.
 	*/
-	assertSingleKeyAddressable(parentCollection, parentPks, via) {
-		if (parentPks.length > 1) throw new Error(`Relation on '${parentCollection.slug}' uses '${via}', a single foreign-key column, but '${parentCollection.slug}' is keyed on ${parentPks.map((k) => `'${k.fieldName}'`).join(" + ")}. One column cannot reference a composite key — express this relation with \`joinPath\`, whose \`on.from\`/\`on.to\` take every key column.`);
+	assertSingleKeyAddressable(parentCollection, parentPks, via, relation) {
+		if (relation && hasForeignKeyOnTarget(relation) && relation.sourceKey) return;
+		if (parentPks.length > 1) throw new Error(`Relation on '${parentCollection.slug}' uses '${via}', a single foreign-key column, but '${parentCollection.slug}' is keyed on ${parentPks.map((k) => `'${k.fieldName}'`).join(" + ")}. One column cannot reference a composite key — give the relation a \`sourceKey\` naming a single unique column to point at, or express it with \`joinPath\`, whose \`on.from\`/\`on.to\` take every key column.`);
+	}
+	/**
+	* What the target's foreign key holds, for each of these parent rows.
+	*
+	* Ordinarily the parent's id, and then this is free. When the relation
+	* declares a `sourceKey` the two are different values, and the mapping
+	* between them lives in the source table — so it costs one SELECT, issued
+	* once for the whole batch rather than per parent.
+	*
+	* Both directions come back because both are needed and deriving one from
+	* the other by hand is how a batch loader ends up attributing a child to the
+	* wrong parent: reads translate id → key to build the WHERE, and then
+	* translate key → id to attribute each row that comes back.
+	*/
+	/**
+	* The value a related row's foreign key must hold to belong to this parent.
+	*
+	* `undefined` when the parent's source key is null — which is not an error
+	* here, only in the callers that were about to write it. Exposed for
+	* {@link PersistService}, which stamps this onto a child created under a
+	* nested path and would otherwise write the id and lose the row.
+	*/
+	async parentKeyValue(parentCollection, relation, parentId, db = this.db) {
+		const { keyByParentId } = await this.resolveSourceKeys(parentCollection, relation, [parentId], db);
+		return keyByParentId.get(String(parentId));
+	}
+	async resolveSourceKeys(parentCollection, relation, parentIds, db = this.db) {
+		const keyByParentId = /* @__PURE__ */ new Map();
+		const parentIdByKey = /* @__PURE__ */ new Map();
+		const parentPks = requirePrimaryKeys(parentCollection, this.registry);
+		if (!joinsOnNaturalKey(relation, parentCollection, this.registry)) {
+			for (const id of parentIds) {
+				const value = parseIdValues(id, parentPks)[parentPks[0].fieldName];
+				keyByParentId.set(String(id), value);
+				parentIdByKey.set(String(value), id);
+			}
+			return {
+				keyByParentId,
+				parentIdByKey
+			};
+		}
+		const field = sourceKeyField(relation, parentCollection, this.registry);
+		const parentTable = getTableForCollection(parentCollection, this.registry);
+		if (!parentTable[field]) throw new Error(`\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not a column on '${parentCollection.slug}'. It names a column on the source table, not on the target.`);
+		const rows = await db.select().from(parentTable).where(this.parentKeyCondition(parentTable, parentPks, parentIds));
+		for (const row of rows) {
+			const keyValue = row[field];
+			if (keyValue === null || keyValue === void 0) continue;
+			const parentId = buildCompositeId(row, parentPks);
+			keyByParentId.set(String(parentId), keyValue);
+			const existing = parentIdByKey.get(String(keyValue));
+			if (existing !== void 0 && String(existing) !== String(parentId)) throw new Error(`\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not unique on '${parentCollection.slug}': rows '${existing}' and '${parentId}' both hold '${keyValue}'. Add a unique constraint — a link that addresses more than one source row cannot say which one a related row belongs to.`);
+			parentIdByKey.set(String(keyValue), parentId);
+		}
+		return {
+			keyByParentId,
+			parentIdByKey
+		};
 	}
 	/**
 	* Fetch rows related to a parent row through a specific relation
@@ -1779,6 +1907,8 @@ var RelationService = class {
 			}
 			return rows;
 		}
+		const matchValue = hasForeignKeyOnTarget(relation) ? (await this.resolveSourceKeys(parentCollection, relation, [parentId])).keyByParentId.get(String(parentId)) : parsedParentId;
+		if (matchValue === void 0) return [];
 		let query = this.db.select().from(targetTable).$dynamic();
 		const additionalFilters = [];
 		if (options.searchString) {
@@ -1787,7 +1917,7 @@ var RelationService = class {
 			const searchCombined = DrizzleConditionBuilder.combineConditionsWithOr(searchConditions);
 			if (searchCombined) additionalFilters.push(searchCombined);
 		}
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentId, targetTable, parentTable, parentIdCol, idField, this.registry, additionalFilters);
+		query = applyDynamicRelationQuery(query, query, relation, matchValue, targetTable, parentTable, parentIdCol, idField, this.registry, additionalFilters);
 		if (options.limit) query = query.limit(options.limit);
 		const results = await query;
 		if (!results || !Array.isArray(results)) return [];
@@ -1830,8 +1960,10 @@ 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];
+		const matchValue = hasForeignKeyOnTarget(relation) ? (await this.resolveSourceKeys(parentCollection, relation, [parentId])).keyByParentId.get(String(parentId)) : parsedParentId;
+		if (matchValue === void 0) return 0;
 		let query = this.db.select({ count: sql`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
-		query = DrizzleConditionBuilder.buildRelationCountQuery(query, relation, parsedParentId, targetTable, parentTable, parentIdCol, targetIdField, this.registry, additionalFilters);
+		query = DrizzleConditionBuilder.buildRelationCountQuery(query, relation, matchValue, targetTable, parentTable, parentIdCol, targetIdField, this.registry, additionalFilters);
 		const result = await query;
 		return Number(result[0]?.count || 0);
 	}
@@ -1958,17 +2090,24 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName, relation);
+		const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation) ? await this.resolveSourceKeys(parentCollection, relation, parentIds) : {
+			keyByParentId: /* @__PURE__ */ new Map(),
+			parentIdByKey: /* @__PURE__ */ new Map()
+		};
+		const matchValues = hasForeignKeyOnTarget(relation) ? [...keyByParentId.values()] : parsedParentIds;
+		if (matchValues.length === 0) return /* @__PURE__ */ new Map();
 		let query = this.db.select().from(targetTable).$dynamic();
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
+		query = applyDynamicRelationQuery(query, query, relation, matchValues, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
 		const resultMap = /* @__PURE__ */ new Map();
-		const parentIdSet = new Set(parsedParentIds.map(String));
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
-			let parentId;
-			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));
+			if (!hasForeignKeyOnTarget(relation)) continue;
+			const foreignKeyValue = targetRow[relation.foreignKeyOnTarget];
+			if (foreignKeyValue === void 0 || foreignKeyValue === null) continue;
+			const parentId = parentIdByKey.get(String(foreignKeyValue));
+			if (parentId !== void 0) resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
 		}
 		return resultMap;
 	}
@@ -2046,17 +2185,24 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName, relation);
+		const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation) ? await this.resolveSourceKeys(parentCollection, relation, parentIds) : {
+			keyByParentId: /* @__PURE__ */ new Map(),
+			parentIdByKey: /* @__PURE__ */ new Map()
+		};
+		const matchValues = hasForeignKeyOnTarget(relation) ? [...keyByParentId.values()] : parsedParentIds;
+		if (matchValues.length === 0) return /* @__PURE__ */ new Map();
 		let query = this.db.select().from(targetTable).$dynamic();
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
+		query = applyDynamicRelationQuery(query, query, relation, matchValues, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
 		const resultMap = /* @__PURE__ */ new Map();
-		const parentIdSet = new Set(parsedParentIds.map(String));
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
-			let parentId;
-			if (hasForeignKeyOnTarget(relation)) parentId = targetRow[relation.foreignKeyOnTarget];
-			if (parentId !== void 0 && parentIdSet.has(String(parentId))) {
+			if (!hasForeignKeyOnTarget(relation)) continue;
+			const foreignKeyValue = targetRow[relation.foreignKeyOnTarget];
+			if (foreignKeyValue === void 0 || foreignKeyValue === null) continue;
+			const parentId = parentIdByKey.get(String(foreignKeyValue));
+			if (parentId !== void 0) {
 				const key = String(parentId);
 				const arr = resultMap.get(key) || [];
 				arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
@@ -2155,14 +2301,13 @@ var RelationService = class {
 					logger.warn(`Invalid inverse-many config for relation '${key}' in collection '${collection.slug}'`);
 					continue;
 				}
-				const parentPks = requirePrimaryKeys(collection, this.registry);
-				const parentIdInfo = parentPks[0];
-				const parsedParentId = parseIdValues(id, parentPks)[parentIdInfo.fieldName];
+				const parentKeyValue = (await this.resolveSourceKeys(collection, relation, [id], tx)).keyByParentId.get(String(id));
+				if (parentKeyValue === void 0) throw new Error(`Cannot write relation '${key}' on '${collection.slug}': row '${id}' has no value in \`sourceKey: "${sourceKeyField(relation, collection, this.registry)}"\`, so there is nothing for the related rows to point at.`);
 				if (targetEntityIds.length > 0) {
 					const parsedTargetIds = targetEntityIds.map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(and(eq(fkCol, parsedParentId), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parsedParentId }).where(inArray(targetIdCol, parsedTargetIds));
-				} else await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(fkCol, parsedParentId));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(and(eq(fkCol, parentKeyValue), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parentKeyValue }).where(inArray(targetIdCol, parsedTargetIds));
+				} else await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(fkCol, parentKeyValue));
 			} else logger.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
 		}
 	}
@@ -2177,8 +2322,7 @@ var RelationService = class {
 				const targetTable = getTableForCollection(targetCollection, this.registry);
 				const targetPks = requirePrimaryKeys(targetCollection, this.registry);
 				const targetIdInfo = targetPks[0];
-				const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
-				const sourceIdInfo = sourcePks[0];
+				requirePrimaryKeys(sourceCollection, this.registry)[0];
 				if (relation.kind === "via") {
 					await this.updateInverseJoinPathRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue);
 					continue;
@@ -2200,13 +2344,14 @@ var RelationService = class {
 					logger.warn(`Foreign key column '${relation.foreignKeyOnTarget}' not found in target table for relation '${relation.relationName}'`);
 					continue;
 				}
-				const parsedSourceId = parseIdValues(sourceEntityId, sourcePks)[sourceIdInfo.fieldName];
-				if (newValue === null || newValue === void 0) await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, parsedSourceId));
+				const sourceKeyValue = (await this.resolveSourceKeys(sourceCollection, relation, [sourceEntityId], tx)).keyByParentId.get(String(sourceEntityId));
+				if (sourceKeyValue === void 0) throw new Error(`Cannot write relation '${relation.relationName}' on '${sourceCollection.slug}': row '${sourceEntityId}' has no value in \`sourceKey: "${sourceKeyField(relation, sourceCollection, this.registry)}"\`, so there is nothing for the related row to point at.`);
+				if (newValue === null || newValue === void 0) await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, sourceKeyValue));
 				else {
 					const parsedNewTargetId = parseIdValues(newValue, targetPks)[targetIdInfo.fieldName];
 					const targetIdField = targetTable[targetIdInfo.fieldName];
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, parsedSourceId));
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parsedSourceId }).where(eq(targetIdField, parsedNewTargetId));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, sourceKeyValue));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: sourceKeyValue }).where(eq(targetIdField, parsedNewTargetId));
 				}
 			} catch (e) {
 				logger.warn(`Failed to update inverse relation '${relation.relationName}'`, { error: e });
@@ -3797,10 +3942,11 @@ var PersistService = class {
 			} else {
 				const targetColumnName = this.resolveParentForeignKeyColumn(hop);
 				if (targetColumnName) {
-					const parsedParentId = parentIdForWrite();
+					const parentKeyValue = hasForeignKeyOnTarget(hop.relation) ? await this.relationService.parentKeyValue(hop.parentCollection, hop.relation, hop.parentId) : parentIdForWrite();
+					if (parentKeyValue === void 0) throw ApiError.badRequest(`Cannot create under "${collectionPath}": the parent row has no value in \`sourceKey\`, so the new row has nothing to point at.`);
 					const existingValue = effectiveValues[targetColumnName];
-					if (existingValue !== void 0 && existingValue !== null && existingValue !== parsedParentId) logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent id '${parsedParentId}'.`);
-					effectiveValues[targetColumnName] = parsedParentId;
+					if (existingValue !== void 0 && existingValue !== null && existingValue !== parentKeyValue) logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent key '${parentKeyValue}'.`);
+					effectiveValues[targetColumnName] = parentKeyValue;
 				}
 			}
 		}
@@ -6152,8 +6298,9 @@ var generateSchema = async (collections, stripPolicies = false) => {
 						if (!emittedRelationNames.has(deduplicationKey)) {
 							const otherTableVar = getTableVarName(getTableName$1(otherCollection));
 							const drizzleFieldKey = resolvePropertyKeyForColumn(collection, otherRel.foreignKeyOnTarget);
+							const referencedKey = otherRel.sourceKey ? resolvePropertyKeyForColumn(otherCollection, otherRel.sourceKey) : getPrimaryKeyName(otherCollection);
 							const synthKey = `_synth_${otherTableVar}_${drizzleFieldKey}`;
-							tableRelations.push(`    "${synthKey}": one(${otherTableVar}, {\n        fields: [${tableVarName}.${drizzleFieldKey}],\n        references: [${otherTableVar}.${getPrimaryKeyName(otherCollection)}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
+							tableRelations.push(`    "${synthKey}": one(${otherTableVar}, {\n        fields: [${tableVarName}.${drizzleFieldKey}],\n        references: [${otherTableVar}.${referencedKey}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
 							emittedRelationNames.add(deduplicationKey);
 						}
 					}
@@ -7311,14 +7458,6 @@ function resolveChannelBusSetting(configured) {
 	return raw === "memory" ? { type: "memory" } : { type: "postgres" };
 }
 /**
-* @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
-* supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
-* config-only callers keep their exact types.
-*/
-function resolveChannelBusConfig(configured) {
-	return resolveChannelBusSetting(configured);
-}
-/**
 * Produce the bus a setting asks for.
 *
 * An instance is handed straight back — constructing it was the application's
@@ -8929,7 +9068,7 @@ function createBackupCron(config) {
 		enabled: config.enabled ?? true,
 		timeoutSeconds: 3600,
 		async handler({ log }) {
-			const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service-DLb2drIH.js").then((n) => n.r);
+			const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service-CD8o_1Sl.js").then((n) => n.r);
 			const { destination } = config;
 			if (destination.kind !== "local" && !config.storage) throw new Error(`Backup destination is ${destination.kind} but no storage controller was provided. Pass the backend's configured StorageController to createBackupCron({ storage }).`);
 			log(`Starting backup of "${dbName}"…`);
@@ -9060,6 +9199,11 @@ function findRelationDefects(collections, registry) {
 						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)}`
 					});
+					if (relation.sourceKey && !sourceColumns.has(relation.sourceKey)) defects.push({
+						...at,
+						problem: `\`sourceKey: "${relation.sourceKey}"\` is not a column on \`${sourceTableName}\``,
+						fix: targetColumns.has(relation.sourceKey) ? `it is a column on the *target* table \`${targetTableName}\` — \`sourceKey\` names the column on this collection that the target's foreign key points at, so it must be one of: ${quote(sourceColumns)}` : `add the column, or set \`sourceKey\` to one of: ${quote(sourceColumns)}`
+					});
 					break;
 				case "manyToMany": {
 					const { table, sourceColumn, targetColumn } = relation.through;
@@ -9811,21 +9955,6 @@ async function ensureAuthTablesExist(db, collection) {
 }
 //#endregion
 //#region src/auth/services.ts
-function getColumnKey(table, ...keys) {
-	if (!table) return void 0;
-	for (const key of keys) {
-		if (key in table) return key;
-		const snake = toSnakeCase(key);
-		if (snake in table) return snake;
-		const camel = camelCase(key);
-		if (camel in table) return camel;
-	}
-}
-function getColumn(table, ...keys) {
-	if (!table) return void 0;
-	const key = getColumnKey(table, ...keys);
-	return key ? table[key] : void 0;
-}
 /**
 * The single definition of what an email address looks like in storage.
 *
@@ -9840,9 +9969,25 @@ function getColumn(table, ...keys) {
 *
 * Whitespace goes too: a trailing space survives the fold and reproduces the
 * problem exactly.
+*
+* Re-exported rather than defined here: `@rebasepro/server` and
+* `@rebasepro/server-mongo` write this column too, and a second copy of this
+* rule is the defect it exists to prevent.
 */
-function normalizeEmail(email) {
-	return typeof email === "string" ? email.trim().toLowerCase() : email;
+function getColumnKey(table, ...keys) {
+	if (!table) return void 0;
+	for (const key of keys) {
+		if (key in table) return key;
+		const snake = toSnakeCase(key);
+		if (snake in table) return snake;
+		const camel = camelCase(key);
+		if (camel in table) return camel;
+	}
+}
+function getColumn(table, ...keys) {
+	if (!table) return void 0;
+	const key = getColumnKey(table, ...keys);
+	return key ? table[key] : void 0;
 }
 /**
 * PostgreSQL implementation of UserRepository.
@@ -11183,6 +11328,31 @@ function humanize(snakeName) {
 	return snakeName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 //#endregion
+//#region src/schema/introspect-db-types.ts
+/**
+* The PostgreSQL type → Rebase property type mapping.
+*
+* Split out of `introspect-db-logic` so that the structural analysis can use it
+* without importing the generator, which imports the analysis. Re-exported from
+* `introspect-db-logic` so existing callers keep their import path.
+*/
+/**
+* Map a PostgreSQL data type to a Rebase property type.
+*/
+function mapPgType(dataType) {
+	const dt = dataType.toLowerCase();
+	if (dt === "interval") return "string";
+	if (dt === "array" || dt.startsWith("_")) return "array";
+	if (dt.includes("int") || dt.includes("numeric") || dt.includes("decimal") || dt.includes("serial") || dt === "real" || dt === "float4" || dt === "float8" || dt === "double precision" || dt === "money") return "number";
+	if (dt.includes("bool")) return "boolean";
+	if (dt.includes("time") || dt.includes("date")) return "date";
+	if (dt === "json" || dt === "jsonb") return "map";
+	if (dt === "bytea") return "binary";
+	if (dt === "inet" || dt === "cidr" || dt === "macaddr" || dt === "macaddr8") return "string";
+	if (dt === "uuid") return "string";
+	return "string";
+}
+//#endregion
 //#region src/schema/introspect-db-logic.ts
 var IRREGULAR_SINGULARS = {
 	people: "person",
@@ -11287,22 +11457,6 @@ function getIconForTable(tableName) {
 	if (table.includes("comment") || table.includes("review") || table.includes("feedback")) return "MessageCircle";
 	return "Database";
 }
-/**
-* Map a PostgreSQL data type to a Rebase property type.
-*/
-function mapPgType(dataType) {
-	const dt = dataType.toLowerCase();
-	if (dt === "interval") return "string";
-	if (dt === "array" || dt.startsWith("_")) return "array";
-	if (dt.includes("int") || dt.includes("numeric") || dt.includes("decimal") || dt.includes("serial") || dt === "real" || dt === "float4" || dt === "float8" || dt === "double precision" || dt === "money") return "number";
-	if (dt.includes("bool")) return "boolean";
-	if (dt.includes("time") || dt.includes("date")) return "date";
-	if (dt === "json" || dt === "jsonb") return "map";
-	if (dt === "bytea") return "binary";
-	if (dt === "inet" || dt === "cidr" || dt === "macaddr" || dt === "macaddr8") return "string";
-	if (dt === "uuid") return "string";
-	return "string";
-}
 function buildEnumMap(enumValues) {
 	const enumMap = /* @__PURE__ */ new Map();
 	for (const ev of enumValues) {
@@ -11322,6 +11476,20 @@ function buildTablesMap(tables, columns, pks, fks) {
 	});
 	return tablesMap;
 }
+/**
+* Join tables, identified by column name.
+*
+* Superseded for the CLI by `classifyTables` in `./introspect-db-structure`,
+* which asks the database instead: two single-column keys, unique together, no
+* payload column, nothing referencing the table. This rule folds away
+* `northwind.order_details` — which has the key shape and carries unit price,
+* quantity and discount — because it recognises `id`, `created_at` and
+* `updated_at` by name and calls everything else a foreign key.
+*
+* Still used by `./introspect-runtime`, which builds collections in memory from
+* a narrower set of catalog queries and has no unique-constraint or row-count
+* data to reason with.
+*/
 function identifyJoinTables(tablesMap) {
 	const joinTables = /* @__PURE__ */ new Set();
 	for (const [tableName, meta] of tablesMap.entries()) if (meta.fks.length === 2) {
@@ -12057,7 +12225,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionSchema(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionTables } = await import("./ensure-collection-tables-CT6xHB1d.js");
+			const { ensureCollectionTables } = await import("./ensure-collection-tables-Da2oGkX2.js");
 			const plan = await ensureCollectionTables({ async query(text) {
 				const result = await internals.db.execute(sql.raw(text));
 				return { rows: result.rows ?? (Array.isArray(result) ? result : []) };
@@ -12082,7 +12250,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionPolicies(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionPolicies } = await import("./ensure-collection-policies-Dv21KDMJ.js");
+			const { ensureCollectionPolicies } = await import("./ensure-collection-policies-BrUVgjz3.js");
 			const outcome = await ensureCollectionPolicies({ async query(text) {
 				const result = await internals.db.execute(sql.raw(text));
 				return { rows: result.rows ?? (Array.isArray(result) ? result : []) };
@@ -12136,6 +12304,6 @@ function createPostgresAdapter(pgConfig) {
 	};
 }
 //#endregion
-export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, CHANNEL_BUS_NOTIFY_CHANNEL, DEFAULT_BATCH_WINDOW_MS, DatabasePoolManager, DrizzleConditionBuilder, MemoryChannelBus, PG_NOTIFY_MAX_PAYLOAD_BYTES, PostgresBackendDriver, PostgresChannelBus, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, applyGlobals, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgDumpallGlobalsArgs, buildPgRestoreArgs, buildPgRestoreListArgs, checkToolServerCompatibility, configureUnknownFilterFields, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, getUnknownFilterFieldsMode, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, pinSearchPath, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, resolveDriftCheckName, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
+export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, CHANNEL_BUS_NOTIFY_CHANNEL, DEFAULT_BATCH_WINDOW_MS, DatabasePoolManager, DrizzleConditionBuilder, MemoryChannelBus, PG_NOTIFY_MAX_PAYLOAD_BYTES, PostgresBackendDriver, PostgresChannelBus, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, applyGlobals, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgDumpallGlobalsArgs, buildPgRestoreArgs, buildPgRestoreListArgs, buildRowSecurityPgOptions, checkToolServerCompatibility, configureUnknownFilterFields, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, diagnoseRowSecurityDumpFailure, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, getUnknownFilterFieldsMode, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, pinSearchPath, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusSetting, resolveConnectionString, resolveDriftCheckName, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
 
 //# sourceMappingURL=index.es.js.map