@rebasepro/server-postgres 0.11.1-canary.g8caabf3 → 0.11.1-canary.g95e61c2

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, 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-Da-RFMnG.js";
+import { _ as Vector, i as ANONYMOUS_USER_ID, l as isPostgresCollectionConfig, n as isSQLAdmin, o as hasForeignKeyOnTarget, r as isSchemaAdmin, s as isManyToMany, t as isChannelBusInstance, u as isRelationalCollectionConfig } from "./src-Zqwaw3P5.js";
+import { A as toSnakeCase, C as createRelationRefWithData, D as getPolicyNamesForRule, E as generateForeignKeyName, O as mergeDeep, 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 camelCase, 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-BbFOPJ1S.js";
 import { Client, Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { ApiError, createEmailService, extractUserFromToken, loadCollectionsFromDirectory, logger, safeCompare } from "@rebasepro/server";
@@ -372,6 +372,28 @@ function deriveRowAddress(row, collection, registry) {
 //#endregion
 //#region src/utils/drizzle-conditions.ts
 /**
+* Process-wide default, set once when the driver is constructed.
+*
+* The condition builder is a set of *static* methods reached from a dozen
+* `FetchService` call sites, none of which carry the driver's config — the
+* service is built from `(db, registry)` alone. Threading an option from
+* `createPostgresAdapter` down to each of them would mean touching every
+* intermediate signature to plumb a value that is a single deployment-wide
+* switch. A module-level default set at adapter construction, plus an explicit
+* per-call override for callers that have one (tests, mainly), buys the same
+* control for none of the churn. It is safe by default, so the only reason to
+* set it at all is to opt *out*.
+*/
+var defaultUnknownFilterFieldsMode = "error";
+/** Set the process-wide behaviour for unresolvable filter fields. */
+function configureUnknownFilterFields(mode) {
+	defaultUnknownFilterFieldsMode = mode;
+}
+/** The process-wide behaviour for unresolvable filter fields. */
+function getUnknownFilterFieldsMode() {
+	return defaultUnknownFilterFieldsMode;
+}
+/**
 * Filter values may arrive as relation wire objects — `EntityRelation`
 * instances or their JSON form `{ __type: "relation", id, path }` — e.g. when
 * the admin filters a relation column. SQL comparisons need the raw id, so
@@ -383,6 +405,22 @@ function unwrapRelationFilterValue(value) {
 	return relation ? relation.id : value;
 }
 /**
+* The operand of `in`/`not-in`, as a list.
+*
+* A scalar is the one-element list, because that is what it means and because
+* the wire produces one: `?filter=id.in.5` parses to the string `"5"`, not to
+* `["5"]` — the REST dialect only builds an array when the value is
+* parenthesised. Treating that as malformed and dropping the condition turned
+* a perfectly ordinary query into an unfiltered read.
+*
+* The empty list stays empty. Callers must decide what "no candidates" means
+* for their operator — it is `FALSE` for `in` and `TRUE` for `not-in` — and
+* neither of those is "no condition at all".
+*/
+function toMembershipList(value) {
+	return Array.isArray(value) ? value : [value];
+}
+/**
 * Unified condition builder for Drizzle/PostgreSQL queries.
 *
 * This class uses static methods and satisfies the ConditionBuilderStatic<SQL> type.
@@ -482,24 +520,88 @@ var DrizzleConditionBuilder = class {
 		return sql`EXISTS (SELECT 1 FROM ${parentTable} AS ${sql.identifier(sourceAlias)}${joinsSql} WHERE ${sql.identifier(sourceAlias)}.${sql.identifier(parentIdColumn.name)} = ${parentId} AND ${correlation})`;
 	}
 	/**
+	* What a filter field names, or `undefined` if it names nothing.
+	*
+	* Three ways a field resolves. It may address its column directly; it may
+	* be an owning relation, whose foreign key is a column here; or it may be
+	* a relation whose link lives on another table entirely, which compiles to
+	* a subquery instead of a column. Only a field that resolves to *none* of
+	* them is an error, and by default it is one: see
+	* {@link UnknownFilterFieldsMode} for why silently dropping it is a
+	* data-exposure primitive rather than a convenience.
+	*
+	* For an owning relation the relation's own `localKey` is the authority,
+	* not `<field>_id`. The default local key is `generateForeignKeyName`,
+	* which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
+	* `users` → `user_id` — and it can be overridden outright. Guessing
+	* `<field>_id` therefore misses perfectly ordinary owning relations, and
+	* with this resolution failing closed that miss is a 400 on a filter that
+	* has nothing wrong with it. The guesses stay, last, for callers that hand
+	* over no collection to resolve against.
+	*
+	* The subquery kinds need a registry and the source table's key column on
+	* top of the collection. A caller that supplies neither gets the behaviour
+	* it had before they were compilable — unresolvable, and so fail-closed —
+	* rather than a half-built condition.
+	*/
+	static resolveFilterTarget(table, field, collectionPath, mode, options) {
+		const { collection, registry, sourceIdColumn } = options;
+		const columnAt = (key) => (key in table ? table[key] : void 0) || void 0;
+		const direct = columnAt(field);
+		if (direct) return {
+			kind: "column",
+			column: direct
+		};
+		if (collection) {
+			const relation = resolveCollectionRelations(collection)[field];
+			if (relation?.kind === "belongsTo") {
+				const foreignKey = columnAt(relation.localKey);
+				if (foreignKey) return {
+					kind: "column",
+					column: foreignKey
+				};
+			}
+			if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) return {
+				kind: "relation",
+				relation,
+				registry,
+				sourceIdColumn
+			};
+		}
+		for (const guess of [`${field}_id`, generateForeignKeyName(field)]) {
+			const foreignKey = columnAt(guess);
+			if (foreignKey) return {
+				kind: "column",
+				column: foreignKey
+			};
+		}
+		if (mode === "warn") {
+			logger.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
+			return;
+		}
+		let validFields = [];
+		try {
+			validFields = Object.keys(getTableColumns(table)).sort();
+		} catch {}
+		throw ApiError.badRequest(`Unknown filter field '${field}' on collection '${collectionPath}'` + (validFields.length > 0 ? `. Valid fields: ${validFields.join(", ")}` : ""), "UNKNOWN_FILTER_FIELD", {
+			field,
+			collection: collectionPath,
+			...validFields.length > 0 && { validFields }
+		});
+	}
+	/**
 	* Build filter conditions from FilterValues
 	*/
-	static buildFilterConditions(filter, table, collectionPath) {
+	static buildFilterConditions(filter, table, collectionPath, options = {}) {
+		const mode = options.unknownFields ?? defaultUnknownFilterFieldsMode;
 		const conditions = [];
 		for (const [field, filterParam] of Object.entries(filter)) {
 			if (!filterParam) continue;
-			let fieldColumn = table[field];
-			if (!fieldColumn) {
-				const relationKey = `${field}_id`;
-				if (relationKey in table) fieldColumn = table[relationKey];
-			}
-			if (!fieldColumn) {
-				logger.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
-				continue;
-			}
+			const target = this.resolveFilterTarget(table, field, collectionPath, mode, options);
+			if (!target) continue;
 			const paramsList = Array.isArray(filterParam) && filterParam.length > 0 && Array.isArray(filterParam[0]) ? filterParam : [filterParam];
 			for (const [op, value] of paramsList) {
-				const condition = this.buildSingleFilterCondition(fieldColumn, op, value);
+				const condition = this.compileFilterTarget(target, op, value, field, collectionPath);
 				if (condition) conditions.push(condition);
 			}
 		}
@@ -508,24 +610,175 @@ var DrizzleConditionBuilder = class {
 	/**
 	* Build logical conditions recursively from LogicalCondition or FilterCondition
 	*/
-	static buildLogicalConditions(cond, table, collectionPath) {
+	static buildLogicalConditions(cond, table, collectionPath, options = {}) {
 		if ("type" in cond) {
-			const subSQLs = cond.conditions.map((c) => this.buildLogicalConditions(c, table, collectionPath)).filter((sql) => sql !== null);
+			const subSQLs = cond.conditions.map((c) => this.buildLogicalConditions(c, table, collectionPath, options)).filter((sql) => sql !== null);
 			if (subSQLs.length === 0) return null;
 			return (cond.type === "or" ? or(...subSQLs) : and(...subSQLs)) ?? null;
 		} else {
-			let fieldColumn = table[cond.column];
-			if (!fieldColumn) {
-				const relationKey = `${cond.column}_id`;
-				if (relationKey in table) fieldColumn = table[relationKey];
-			}
-			if (!fieldColumn) {
-				logger.warn(`Filtering by field '${cond.column}', but it does not exist in table for collection '${collectionPath}'`);
-				return null;
-			}
-			return this.buildSingleFilterCondition(fieldColumn, cond.operator, cond.value);
+			const target = this.resolveFilterTarget(table, cond.column, collectionPath, options.unknownFields ?? defaultUnknownFilterFieldsMode, options);
+			if (!target) return null;
+			return this.compileFilterTarget(target, cond.operator, cond.value, cond.column, collectionPath);
 		}
 	}
+	/** Dispatch a resolved filter field onto the shape it actually compiles to. */
+	static compileFilterTarget(target, op, value, field, collectionPath) {
+		return target.kind === "column" ? this.buildSingleFilterCondition(target.column, op, value) : this.buildRelationFilterCondition(target.relation, op, value, target.sourceIdColumn, target.registry, field, collectionPath);
+	}
+	/**
+	* A filter on a relation that owns no column on this row — `EXISTS` over
+	* the rows it reaches.
+	*
+	* `posts` filtered by `tags == <tagId>` is not a comparison on `posts`; it
+	* is a question about the junction:
+	*
+	*     EXISTS (SELECT 1 FROM posts_tags AS j
+	*             WHERE j.post_id = posts.id AND j.tag_id = <tagId>)
+	*
+	* which is {@link buildRelationScopeCondition}'s many-to-many shape with
+	* source and target swapped — there the junction's *target* column
+	* correlates and the source is pinned; here the *source* column correlates
+	* and the target is what the filter constrains.
+	*
+	* `hasMany`/`hasOne` are the same shape one table over: the target row
+	* carries the foreign key, so the correlation is on that key and the
+	* compared column is the target's own id.
+	*
+	* `EXISTS` and not a join, for the reason the scope condition gives: a join
+	* through a junction multiplies the outer rows by the number of matching
+	* links, which duplicates results and silently breaks `limit`/`offset`.
+	*
+	* Everything inside the subquery is referenced by identifier against a
+	* local alias, and only `sourceIdColumn` stays a Drizzle column object —
+	* again see {@link buildRelationScopeCondition}, which explains why a
+	* column object renders against whatever table the surrounding builder
+	* thinks is current and so cannot be used for the inner references. The
+	* alias is also what keeps a self-referential relation unambiguous
+	* (`categories.children`, or a many-to-many whose junction and target are
+	* the same table), where the subquery's table and the outer one coincide.
+	*/
+	static buildRelationFilterCondition(relation, op, value, sourceIdColumn, registry, field, collectionPath) {
+		const alias = "__rel_filter";
+		const ref = (column) => sql`${sql.identifier(alias)}.${sql.identifier(column.name)}`;
+		let scanTable;
+		let correlation;
+		let comparedColumn;
+		if (relation.kind === "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}'`);
+			scanTable = junctionTable;
+			correlation = sql`${ref(sourceCol)} = ${sourceIdColumn}`;
+			comparedColumn = targetCol;
+		} else {
+			const targetCollection = relation.target();
+			const targetTable = registry.getTable(getTableName$1(targetCollection));
+			if (!targetTable) throw new Error(`Table not found for the target of relation '${relation.relationName}' (collection '${targetCollection.slug}')`);
+			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}'.`);
+			const targetIdColumn = this.primaryKeyColumn(targetTable);
+			if (!targetIdColumn) throw new Error(`No primary key or "id" column in the target table of relation '${relation.relationName}', so a filter on it has nothing to match against.`);
+			scanTable = targetTable;
+			correlation = sql`${ref(fkColumn)} = ${sourceIdColumn}`;
+			comparedColumn = targetIdColumn;
+		}
+		const { predicate, negate } = this.buildRelationFilterPredicate(ref(comparedColumn), op, value, field, collectionPath);
+		const where = predicate ? sql`${correlation} AND ${predicate}` : correlation;
+		const exists = sql`EXISTS (SELECT 1 FROM ${scanTable} AS ${sql.identifier(alias)} WHERE ${where})`;
+		return negate ? sql`NOT ${exists}` : exists;
+	}
+	/**
+	* The inner predicate of a relation filter, and whether the `EXISTS`
+	* wrapping it is negated.
+	*
+	* Negation is `NOT EXISTS` of the *positive* predicate, never `EXISTS` of a
+	* negated one. On a many-valued relation the two are different questions:
+	* `EXISTS (… AND tag_id != X)` asks "does some tag differ from X", which is
+	* true of nearly every post with more than one tag and answers nothing
+	* anybody asked. `NOT EXISTS (… AND tag_id = X)` asks "is X absent", which
+	* is what unticking a value in a filter control means — and it makes `==`
+	* and `!=` partition the rows, the way a filter implies they do.
+	*
+	* `is-null`/`is-not-null` drop the predicate entirely: with nothing but the
+	* correlation left, they become "has no related row at all" and "has at
+	* least one", which is the only reading of null a link can have.
+	*
+	* Under RLS, "no related row" means *no row this reader can see*. A junction
+	* with row-level security but no `SELECT` policy for `rebase_user` is opaque
+	* to it, so every row comes back looking unlinked and `is-null` matches all
+	* of them. That is not a leak — the outer table's own policies still decide
+	* which rows exist at all, and the positive direction correctly returns
+	* nothing — but it over-reports, and the cause is a missing junction policy
+	* rather than anything here. Rebase derives one for a declared many-to-many;
+	* a hand-written schema has to supply it.
+	*
+	* `in`/`not-in` against a *null value* mean the same thing, rather than
+	* membership of an empty list. Membership against null is not a membership
+	* question, and the admin's "filter for null values" control emits the
+	* operator that happens to be selected — on a to-many relation that is
+	* always `in` or `not-in`, because those are the only ones the multi-select
+	* can produce. Reading `["in", null]` as an empty list would answer "posts
+	* with no tags" with no posts at all.
+	*
+	* An empty `in` list compiles to `FALSE` rather than being dropped. Dropped
+	* is what the column path does, and dropping a condition widens the result
+	* — the whole reason this resolution fails closed. `in []` matches nothing
+	* and `not-in []` matches everything, and `NOT EXISTS (… AND FALSE)` gives
+	* the second for free.
+	*
+	* Anything else is rejected. Returning `null` for an operator this cannot
+	* express would drop the condition, and the operators the admin offers for
+	* a relation are exactly the six below.
+	*/
+	static buildRelationFilterPredicate(ref, op, value, field, collectionPath) {
+		value = unwrapRelationFilterValue(value);
+		const isNullish = value === null || value === void 0;
+		const equals = () => sql`${ref} = ${value}`;
+		const inList = () => {
+			const values = toMembershipList(value);
+			return values.length === 0 ? sql`FALSE` : sql`${ref} IN (${sql.join(values.map((v) => sql`${v}`), sql`, `)})`;
+		};
+		switch (op) {
+			case "==": return isNullish ? { negate: true } : {
+				predicate: equals(),
+				negate: false
+			};
+			case "!=": return isNullish ? { negate: false } : {
+				predicate: equals(),
+				negate: true
+			};
+			case "in": return isNullish ? { negate: true } : {
+				predicate: inList(),
+				negate: false
+			};
+			case "not-in": return isNullish ? { negate: false } : {
+				predicate: inList(),
+				negate: true
+			};
+			case "is-null": return { negate: true };
+			case "is-not-null": return { negate: false };
+			case "array-contains": return isNullish ? { negate: true } : {
+				predicate: equals(),
+				negate: false
+			};
+			case "array-contains-any": return isNullish ? { negate: true } : {
+				predicate: inList(),
+				negate: false
+			};
+			default: throw ApiError.badRequest(`Operator '${op}' cannot be applied to relation field '${field}' on collection '${collectionPath}'. A relation with no column on this row is filtered by membership: ==, !=, in, not-in, array-contains, array-contains-any, is-null, is-not-null.`, "UNSUPPORTED_RELATION_FILTER_OPERATOR", {
+				field,
+				collection: collectionPath,
+				operator: op
+			});
+		}
+	}
+	/** The column a table's rows are keyed by: its primary key, else `id`. */
+	static primaryKeyColumn(table) {
+		return Object.values(table).find((col) => col.primary) ?? Object.values(table).find((col) => col.name === "id");
+	}
 	/**
 	* Build a single filter condition for a specific operator and value
 	*/
@@ -542,9 +795,11 @@ var DrizzleConditionBuilder = class {
 			case ">=": return sql`${column} >= ${value}`;
 			case "<": return sql`${column} < ${value}`;
 			case "<=": return sql`${column} <= ${value}`;
-			case "in":
-				if (Array.isArray(value) && value.length > 0) return inArray(column, value);
-				return null;
+			case "in": {
+				if (value === null || value === void 0) return sql`${column} IS NULL`;
+				const values = toMembershipList(value);
+				return values.length === 0 ? sql`FALSE` : inArray(column, values);
+			}
 			case "array-contains": {
 				const meta = getColumnMeta(column);
 				if (meta.dataType === "array" || meta.columnType === "PgArray") return sql`${column} @> ARRAY[${value}]`;
@@ -553,6 +808,7 @@ var DrizzleConditionBuilder = class {
 			case "array-contains-any": {
 				const meta = getColumnMeta(column);
 				const isNativeArray = meta.dataType === "array" || meta.columnType === "PgArray";
+				if (Array.isArray(value) && value.length === 0) return sql`FALSE`;
 				if (Array.isArray(value) && value.length > 0) if (isNativeArray) return sql`${column} && ARRAY[${sql.join(value.map((v) => sql`${v}`), sql`, `)}]`;
 				else {
 					const textValues = value.map((v) => String(v));
@@ -561,9 +817,12 @@ var DrizzleConditionBuilder = class {
 				if (isNativeArray) return sql`${column} @> ARRAY[${value}]`;
 				return sql`${column} @> ${JSON.stringify([value])}`;
 			}
-			case "not-in":
-				if (Array.isArray(value) && value.length > 0) return sql`${column} NOT IN (${sql.join(value.map((v) => sql`${v}`), sql`, `)})`;
-				return null;
+			case "not-in": {
+				if (value === null || value === void 0) return sql`${column} IS NOT NULL`;
+				const values = toMembershipList(value);
+				if (values.length === 0) return sql`TRUE`;
+				return sql`${column} NOT IN (${sql.join(values.map((v) => sql`${v}`), sql`, `)})`;
+			}
 			case "like": return sql`${column} LIKE ${String(value)}`;
 			case "ilike": return sql`${column} ILIKE ${String(value)}`;
 			case "not-like": return sql`${column} NOT LIKE ${String(value)}`;
@@ -765,7 +1024,7 @@ var DrizzleConditionBuilder = class {
 	static buildSimpleRelationCondition(relation, targetTable, parentTable, parentId) {
 		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");
+			const targetIdCol = this.primaryKeyColumn(targetTable);
 			if (!targetIdCol) throw new Error(`No primary key or "id" column in the target table of relation '${relation.relationName}'.`);
 			return match(targetIdCol);
 		}
@@ -2382,23 +2641,77 @@ var FetchService = class {
 		return this.db.query?.[tableName];
 	}
 	/**
+	* The context the condition builder needs to compile a filter key that is
+	* not a column name outright.
+	*
+	* Two such keys. An owning relation's key resolves through the collection's
+	* relations to its foreign-key column; a relation whose link lives on the
+	* target table or in a junction resolves to a correlated `EXISTS`, which
+	* needs the registry to reach that other table and this table's key column
+	* to correlate back.
+	*
+	* Looked up rather than passed: every read path already has the path, only
+	* some have the collection, and a path that names no registered collection
+	* (a nested/derived one) is not an error here — the builder simply falls
+	* back to guessing the default key shapes, and a relation filter it cannot
+	* compile stays unresolvable and so fails closed.
+	*/
+	filterContext(collectionPath, table) {
+		const collection = this.registry.getCollectionByPath(collectionPath) ?? void 0;
+		return {
+			collection,
+			registry: this.registry,
+			sourceIdColumn: collection ? this.resolveIdColumn(collection, table) : void 0
+		};
+	}
+	/**
+	* The table column this collection's rows are keyed by, or `undefined`.
+	*
+	* `getPrimaryKeys` rather than `requirePrimaryKeys`: a collection with no
+	* resolvable key is not an error on the filter path — it only means the
+	* relation filters that would correlate on it cannot be compiled, which
+	* the builder already handles by failing that field closed.
+	*/
+	resolveIdColumn(collection, table) {
+		const [idInfo] = getPrimaryKeys(collection, this.registry);
+		if (!idInfo) return void 0;
+		return table[idInfo.fieldName];
+	}
+	/**
 	* Build filter conditions from FilterValues
 	* Delegates to DrizzleConditionBuilder.buildFilterConditions
 	*/
 	buildFilterConditions(filter, table, collectionPath) {
-		return DrizzleConditionBuilder.buildFilterConditions(filter, table, collectionPath);
+		return DrizzleConditionBuilder.buildFilterConditions(filter, table, collectionPath, this.filterContext(collectionPath, table));
 	}
 	/**
 	* Resolves the correct Drizzle column for sorting.
 	* Automatically maps owning relation property keys to their underlying foreign key column.
+	*
+	* The relation's own `localKey` is the authority for that foreign key, not
+	* `<field>_id`. The default local key comes from `generateForeignKeyName`,
+	* which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
+	* `users` → `user_id` — and an author can override it outright. A wrong
+	* guess resolves to nothing, the caller drops the `ORDER BY`, and the rows
+	* come back in whatever order Postgres pleases: paging over that repeats
+	* and skips rows rather than erroring. The guesses stay, last, for a
+	* caller that hands over no collection to resolve against.
 	*/
 	resolveOrderByField(table, orderBy, collection) {
-		let orderByField = table[orderBy];
-		if (!orderByField && collection) {
-			const property = collection.properties[orderBy];
-			if (property && property.type === "relation" && "relation" in property && property.resolvedRelation?.kind === "belongsTo") orderByField = table[`${orderBy}_id`];
+		const columnAt = (key) => (key in table ? table[key] : void 0) || void 0;
+		const direct = columnAt(orderBy);
+		if (direct) return direct;
+		if (collection) {
+			const relation = resolveCollectionRelations(collection)[orderBy];
+			if (relation?.kind === "belongsTo") {
+				const foreignKey = columnAt(relation.localKey);
+				if (foreignKey) return foreignKey;
+			}
+		}
+		for (const guess of [`${orderBy}_id`, generateForeignKeyName(orderBy)]) {
+			const foreignKey = columnAt(guess);
+			if (foreignKey) return foreignKey;
 		}
-		return orderByField;
 	}
 	/**
 	* Build the `with` config for Drizzle's relational query API.
@@ -2510,7 +2823,7 @@ var FetchService = class {
 			if (filterConditions.length > 0) allConditions.push(...filterConditions);
 		}
 		if (options.logical) {
-			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath);
+			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath, this.filterContext(collectionPath, table));
 			if (logicalCondition) allConditions.push(logicalCondition);
 		}
 		if (options.startAfter) {
@@ -2691,7 +3004,7 @@ var FetchService = class {
 			if (filterConditions.length > 0) allConditions.push(...filterConditions);
 		}
 		if (options.logical) {
-			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath);
+			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath, this.filterContext(collectionPath, table));
 			if (logicalCondition) allConditions.push(logicalCondition);
 		}
 		if (vectorMeta?.filter) allConditions.push(vectorMeta.filter);
@@ -3117,6 +3430,18 @@ var FetchService = class {
 * a message that is safe and helpful to show to end-users.
 */
 /**
+* Return the error when it is a deliberate 4xx, otherwise null.
+*
+* A thrown `ApiError` is a decision the server made about the request, not a
+* database failure: its message and code are already written for the client.
+*/
+function asClientFacingError(error) {
+	if (!(error instanceof Error)) return null;
+	const e = error;
+	if (typeof e.statusCode !== "number" || e.statusCode < 400 || e.statusCode >= 500) return null;
+	return e;
+}
+/**
 * Extract the underlying PostgreSQL error from a Drizzle wrapper.
 * Drizzle wraps PG errors in a `cause` property — this function
 * recursively walks the chain until it finds an object with a PG
@@ -3240,14 +3565,27 @@ function pgErrorToFriendlyMessage(pgError, context) {
 /**
 * Sanitize any error into a message safe and helpful for the client.
 *
-* Extracts the PG error from the Drizzle cause chain when possible;
-* falls back to a generic message that doesn't leak SQL.
+* A deliberate 4xx (`ApiError`) passes through untouched — the server already
+* decided what the client should read. Otherwise the PG error is extracted
+* from the Drizzle cause chain, falling back to a generic message that
+* doesn't leak SQL.
 *
 * @param error   - The raw caught error
 * @param context - A human-readable context string (e.g. collection path)
-* @returns An object with `message` (user-friendly) and optional `code` (PG code).
+* @returns An object with `message` (user-friendly) and optional `code`
+*          (the `ApiError` code, or the PG SQLSTATE).
 */
 function sanitizeErrorForClient(error, context) {
+	const clientError = asClientFacingError(error);
+	if (clientError) {
+		const line = `[API ${clientError.statusCode} ${clientError.code ?? "BAD_REQUEST"}] in "${context}": ${clientError.message}`;
+		if (clientError.expected) logger.debug(line);
+		else logger.warn(`⚠️ ${line}`);
+		return {
+			message: clientError.message,
+			...clientError.code && { code: clientError.code }
+		};
+	}
 	const pgError = extractPgError(error);
 	if (pgError) {
 		logger.error(`[PG ${pgError.code}] Error in "${context}"`, {
@@ -20492,6 +20830,7 @@ function isEconnrefused(err) {
 * ```
 */
 function createPostgresBootstrapper(pgConfig) {
+	if (pgConfig.unknownFilterFields) configureUnknownFilterFields(pgConfig.unknownFilterFields);
 	return {
 		type: "postgres",
 		async initializeDriver(config) {
@@ -20671,7 +21010,8 @@ function createPostgresBootstrapper(pgConfig) {
 					for (const col of registeredCollections) {
 						if (col.auth?.enabled) continue;
 						const schemaName = "schema" in col && col.schema ? col.schema : "public";
-						const tableName = registry.hasTableForCollection(col.table ?? col.slug) ? col.table ?? col.slug : col.slug;
+						const declaredTable = isRelationalCollectionConfig(col) ? col.table : void 0;
+						const tableName = registry.hasTableForCollection(declaredTable ?? col.slug) ? declaredTable ?? col.slug : col.slug;
 						const checkName = registry.getTableNames().find((k) => k === tableName || k === col.slug) ?? tableName;
 						const fullCheckName = schemaName === "public" ? checkName : `${schemaName}.${checkName}`;
 						if (!dbTables.has(fullCheckName)) missing.push({
@@ -20778,7 +21118,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionSchema(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionTables } = await import("./ensure-collection-tables-DWEvKSY8.js");
+			const { ensureCollectionTables } = await import("./ensure-collection-tables-CNTcZGvn.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 : []) };
@@ -20827,6 +21167,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, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, 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, 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, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
 
 //# sourceMappingURL=index.es.js.map