linkgress-orm 0.4.80 → 0.4.83

package/dist/query/query-builder.js

@@ -121,11 +121,22 @@ const MOCK_ROW_CHAIN_ID = Symbol('linkgressMockChainId');
 const navigationPathSignature = (path) => path
     .map(step => `${step.alias}:${step.targetTable}:${(step.foreignKeys ?? []).join('+')}:${(step.matches ?? []).join('+')}:${step.isMandatory ? 1 : 0}:${step.sourceAlias ?? ''}`)
     .join('>');
-/** A reference mock row: `Object.create(prototype)` plus its two own state slots. */
-const mintReferenceMockRow = (prototype) => {
+/**
+ * A reference mock row: `Object.create(prototype)` plus its own state slots.
+ *
+ * `chainId` is the identity of the row this navigation hangs off, and it is propagated so the
+ * field refs minted from the nav row answer "which query do I belong to?" the same way a plain
+ * column ref does. Without it a navigation ref is anonymous, and an outer correlation written
+ * THROUGH a navigation (`l.city!.name`) is indistinguishable from the inner table's own
+ * navigation of the same name — which is precisely the misbinding isForeignChainRef exists to
+ * catch. Undefined stays undefined: rows minted outside a chain (collection mocks) keep the
+ * anonymity their own callers rely on.
+ */
+const mintReferenceMockRow = (prototype, chainId) => {
     const mock = Object.create(prototype);
     mock[MOCK_ROW_FIELD_REFS] = {};
     mock[MOCK_ROW_NAV_CACHE] = {};
+    mock[MOCK_ROW_CHAIN_ID] = chainId;
     return mock;
 };
 /**
@@ -272,30 +283,21 @@ const NUMERIC_REGEX = /^-?\d+(\.\d+)?$/;
  * Query builder for a table
  */
 /**
- * Monotonic sequence for query-chain identities. Every root builder gets a
- * fresh id; derived builders inherit it (navigation sub-builders are handed the
- * parent's id, so a nav ref shares its root's chain). Field refs bake the id so a
- * standalone subquery can tell its OWN refs from ones leaking in from an OUTER
- * chain — see isForeignChainRef.
- */
-let chainIdSeq = 0;
-/**
- * Whether `ref` was minted by a query chain OTHER than `chainId` — i.e. it is a
- * correlation to an enclosing query rather than something this builder owns.
+ * Monotonic sequence for query-chain identities. Every root builder gets a fresh id and
+ * derived builders inherit it, so every field ref can say which query it belongs to — which is
+ * what lets a subquery tell its OWN refs from ones leaking in from an OUTER chain (see
+ * isForeignChainRef).
  *
- * Alias identity alone cannot answer this. A subquery's own navigation aliases are its
- * relation NAMES, and a relation name may coincide with an outer table's alias: a child
- * with a `library` navigation, correlated against a parent table also called `library`.
- * Resolving such a ref by name makes the builder join a second, inner copy of the parent
- * and bind the correlation to it, which turns the predicate into a comparison of the inner
- * row with itself — true for every row, no SQL error, no type error. Singular table names
- * (`library` + `shelf.library`) produce that collision as a matter of course; the
- * plural-table/singular-nav convention (`users` + `post.user`) hides it.
+ * Navigation rows inherit the id of the row they hang off (`mintReferenceMockRow`), so
+ * `outer.nav.col` carries the OUTER chain while `inner.nav.col` carries the inner one even
+ * when both render under the same alias. That propagation is load-bearing: without it a
+ * correlation written through a navigation is anonymous and indistinguishable from the inner
+ * table's own navigation of the same name.
  *
- * Returns false when either side lacks an id, so refs from paths that do not stamp one keep
- * their previous, name-based treatment.
+ * `CollectionQueryBuilder` deliberately stamps nothing — its refs are anonymous by design, so
+ * "carries an id at all" is what marks a correlation on that path.
  */
-const isForeignChainRef = (ref, chainId) => ref?.__chainId != null && chainId != null && ref.__chainId !== chainId;
+let chainIdSeq = 0;
 class QueryBuilder {
     constructor(schema, client, whereCond, limit, offset, orderBy, executor, manualJoins, joinCounter, collectionStrategy, schemaRegistry) {
         /** @internal Chain identity — see chainIdSeq. */
@@ -524,13 +526,13 @@ class QueryBuilder {
                             return cachedRow;
                         }
                         if (holder.prototype !== undefined && mock_row_cache_1.MockRowCache.isEnabled()) {
-                            return (navCache[relName] = mintReferenceMockRow(holder.prototype));
+                            return (navCache[relName] = mintReferenceMockRow(holder.prototype, slots[MOCK_ROW_CHAIN_ID]));
                         }
                         const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema, schemaRegistry, // Pass schema registry for nested navigation resolution
                         [], // Empty navigation path for first level navigation
                         sourceTableName // Pass source table name for lateral join correlation
                         );
-                        return (navCache[relName] = refBuilder.createMockTargetRow(holder));
+                        return (navCache[relName] = refBuilder.createMockTargetRow(holder, slots[MOCK_ROW_CHAIN_ID]));
                     },
                     enumerable: false,
                     configurable: true,
@@ -699,7 +701,7 @@ class QueryBuilder {
                         [], // Empty navigation path for first level navigation
                         schema.name // Pass source table name for lateral join correlation
                         );
-                        return (navCache[relName] = refBuilder.createMockTargetRow());
+                        return (navCache[relName] = refBuilder.createMockTargetRow(undefined, slots[MOCK_ROW_CHAIN_ID]));
                     },
                     enumerable: false,
                     configurable: true,
@@ -741,6 +743,11 @@ class SelectQueryBuilder {
         return schema ? `"${schema}"."${tableName}"` : `"${tableName}"`;
     }
     constructor(schema, client, selector, whereCond, limit, offset, orderBy, executor, manualJoins, joinCounter, isDistinct, schemaRegistry, ctes, collectionStrategy, chainId) {
+        /**
+         * @internal Aliases the WHERE correlated on, recorded by `detectAndAddJoinsFromCondition`
+         * so the shadow check can be re-run after the SELECT list has contributed its joins.
+         */
+        this.correlatedAliasesFromCondition = new Set();
         this.orderByFields = [];
         this.manualJoins = [];
         this.joinCounter = 0;
@@ -1017,7 +1024,7 @@ class SelectQueryBuilder {
      *   .select(g => ({ street: g.key.street, count: g.count() }))
      */
     groupBy(selector) {
-        return new grouped_query_1.GroupedQueryBuilder(this.schema, this.client, this.selector, selector, this.whereCond, this.executor, this.manualJoins, this.joinCounter, this.schemaRegistry);
+        return new grouped_query_1.GroupedQueryBuilder(this.schema, this.client, this.selector, selector, this.whereCond, this.executor, this.manualJoins, this.joinCounter, this.schemaRegistry, this.chainId);
     }
     /**
      * Add a LEFT JOIN with a subquery
@@ -1263,7 +1270,7 @@ class SelectQueryBuilder {
                         [], // Empty navigation path for first level navigation
                         schema.name // Pass source table name for lateral join correlation
                         );
-                        return (navCache[relName] = refBuilder.createMockTargetRow());
+                        return (navCache[relName] = refBuilder.createMockTargetRow(undefined, slots[MOCK_ROW_CHAIN_ID]));
                     },
                     enumerable: false,
                     configurable: true,
@@ -3728,7 +3735,7 @@ ${joinClauses.join('\n')}`;
                             return cachedRow;
                         }
                         if (holder.prototype !== undefined && mock_row_cache_1.MockRowCache.isEnabled()) {
-                            return (navCache[relName] = mintReferenceMockRow(holder.prototype));
+                            return (navCache[relName] = mintReferenceMockRow(holder.prototype, slots[MOCK_ROW_CHAIN_ID]));
                         }
                         const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema, // Pass the target schema directly
                         schemaRegistry, // Pass schema registry for nested resolution
@@ -3736,7 +3743,7 @@ ${joinClauses.join('\n')}`;
                         sourceTableName // Pass source table name for lateral join correlation
                         );
                         // Return a mock object that exposes the target table's columns
-                        return (navCache[relName] = refBuilder.createMockTargetRow(holder));
+                        return (navCache[relName] = refBuilder.createMockTargetRow(holder, slots[MOCK_ROW_CHAIN_ID]));
                     },
                     enumerable: false,
                     configurable: true,
@@ -3887,7 +3894,7 @@ ${joinClauses.join('\n')}`;
                 const columnName = nestedValue.__dbColumnName;
                 // Add JOIN if needed for navigation fields
                 if (tableAlias !== this.schema.name) {
-                    const relConfig = this.schema.relations[tableAlias];
+                    const relConfig = this.relationForRef(nestedValue, tableAlias);
                     if (relConfig && !joins.find(j => j.alias === tableAlias)) {
                         let targetSchema;
                         if (relConfig.targetTableBuilder) {
@@ -4031,7 +4038,7 @@ ${joinClauses.join('\n')}`;
                 const columnName = nestedValue.__dbColumnName;
                 // Add JOIN if needed for navigation fields
                 if (tableAlias !== this.schema.name) {
-                    const relConfig = this.schema.relations[tableAlias];
+                    const relConfig = this.relationForRef(nestedValue, tableAlias);
                     if (relConfig && !joins.find(j => j.alias === tableAlias)) {
                         let targetSchema;
                         if (relConfig.targetTableBuilder) {
@@ -4082,6 +4089,12 @@ ${joinClauses.join('\n')}`;
             return;
         }
         for (const [_key, value] of Object.entries(selection)) {
+            // A ref from another chain is a correlation to an enclosing query, which already has
+            // that table in scope — resolving it here would join a second copy of it into this
+            // subquery. Same rule as the WHERE path; see isForeignChainRef.
+            if ((0, query_utils_2.isForeignChainRef)(value, this.chainId)) {
+                continue;
+            }
             if (value && typeof value === 'object' && '__tableAlias' in value && '__dbColumnName' in value) {
                 // This is a FieldRef with a table alias
                 const tableAlias = value.__tableAlias;
@@ -4101,6 +4114,9 @@ ${joinClauses.join('\n')}`;
                 // SqlFragment may contain navigation property references
                 const fieldRefs = value.getFieldRefs();
                 for (const fieldRef of fieldRefs) {
+                    if ((0, query_utils_2.isForeignChainRef)(fieldRef, this.chainId)) {
+                        continue;
+                    }
                     if ('__tableAlias' in fieldRef && fieldRef.__tableAlias) {
                         const tableAlias = fieldRef.__tableAlias;
                         if (tableAlias && tableAlias !== this.schema.name) {
@@ -4123,6 +4139,25 @@ ${joinClauses.join('\n')}`;
             }
         }
     }
+    /**
+     * The relation `ref` navigates, or `undefined` when `ref` does not belong to this query.
+     *
+     * Every inline "field ref -> relation -> JOIN" site routes through here instead of reading
+     * `this.schema.relations[alias]` directly, because the alias alone cannot tell a navigation
+     * of OURS from a correlation to an enclosing query: a relation name may equal an outer
+     * table's alias (a child's `library` navigation against a parent table also called
+     * `library`). Joining on that name pulls a second copy of the outer table into this query
+     * and rebinds the correlation to it — the predicate then compares the inner row with
+     * itself and is true for every row, with no SQL error and no type error to show for it.
+     *
+     * See isForeignChainRef for how the two are told apart.
+     */
+    relationForRef(ref, tableAlias) {
+        if ((0, query_utils_2.isForeignChainRef)(ref, this.chainId)) {
+            return undefined;
+        }
+        return this.schema.relations[tableAlias];
+    }
     /**
      * Resolve all navigation joins by finding the correct path through the schema graph
      * This handles multi-level navigation like task.level.createdBy
@@ -4197,7 +4232,7 @@ ${joinClauses.join('\n')}`;
         const tableAlias = fieldRef.__tableAlias;
         if (tableAlias && tableAlias !== this.schema.name && !joins.some(j => j.alias === tableAlias)) {
             // This references a related table - find the relation and add a JOIN
-            const relation = this.schema.relations[tableAlias];
+            const relation = this.relationForRef(fieldRef, tableAlias);
             if (relation && relation.type === 'one') {
                 // Get target schema from targetTableBuilder if available
                 let targetSchema;
@@ -4233,7 +4268,7 @@ ${joinClauses.join('\n')}`;
             // CORRELATION, not one of our navigations, and the outer query already has that
             // table in scope. Joining it here would resolve the alias against OUR relations and
             // pull in a second, inner copy of the outer table — see isForeignChainRef.
-            if (isForeignChainRef(fieldRef, this.chainId)) {
+            if ((0, query_utils_2.isForeignChainRef)(fieldRef, this.chainId)) {
                 if ('__tableAlias' in fieldRef && fieldRef.__tableAlias) {
                     correlatedAliases.add(fieldRef.__tableAlias);
                 }
@@ -4255,18 +4290,11 @@ ${joinClauses.join('\n')}`;
                 }
             }
         }
-        // A correlation whose alias is ALSO one of our own navigation aliases cannot be
-        // rendered: both would occupy the same identifier in one scope, our join would shadow
-        // the outer table, and the correlation predicate would bind to the inner row — the
-        // silent wrong answer this whole path exists to prevent. Same contract as the
-        // same-table guard in extractOuterFieldRefs: refuse loudly rather than misbind.
-        for (const alias of correlatedAliases) {
-            if (allTableAliases.has(alias)) {
-                throw new Error(`Correlated subquery over table "${this.schema.name}" both correlates to an outer "${alias}" and joins its own "${alias}" navigation. `
-                    + `Both would use the alias "${alias}", so the inner join would shadow the outer table and the correlation would silently bind to the inner row. `
-                    + `Traverse the navigation in the OUTER query, correlate on a plain key column instead of the navigation, or rename the navigation property.`);
-            }
-        }
+        // Kept for the second, wider check once the SELECT list has added its own joins: the
+        // colliding navigation can be named ONLY in the projection, which this method never sees.
+        this.correlatedAliasesFromCondition = correlatedAliases;
+        // Refuse the one shape that cannot be rendered — see assertNoCorrelatedAliasShadowing.
+        (0, query_utils_2.assertNoCorrelatedAliasShadowing)(this.schema.name, correlatedAliases, allTableAliases);
         // Resolve all joins through the schema graph
         this.resolveJoinsForTableAliases(allTableAliases, joins);
     }
@@ -4287,6 +4315,10 @@ ${joinClauses.join('\n')}`;
         this.detectAndAddJoinsFromSelection(selection, joins);
         // Scan WHERE condition for navigation property references and add JOINs
         this.detectAndAddJoinsFromCondition(this.whereCond, joins);
+        // Repeat the shadow check now that the SELECT list has contributed its joins: the colliding
+        // navigation can be named ONLY in the projection, where the WHERE-time check cannot see it.
+        // EXISTS ignores the select list, so nothing else would catch that shape.
+        (0, query_utils_2.assertNoCorrelatedAliasShadowing)(this.schema.name, this.correlatedAliasesFromCondition, new Set(joins.map(join => join.alias)));
         // Handle case where selection is a single value (not an object with properties)
         if (selection instanceof conditions_1.SqlFragment) {
             // Single SQL fragment - just build it directly
@@ -4357,7 +4389,7 @@ ${joinClauses.join('\n')}`;
                         const tableAlias = value.__tableAlias;
                         const columnName = value.__dbColumnName;
                         // Find the relation config for this navigation
-                        const relConfig = this.schema.relations[tableAlias];
+                        const relConfig = this.relationForRef(value, tableAlias);
                         if (relConfig) {
                             // Add JOIN if not already added
                             if (!joins.find(j => j.alias === tableAlias)) {
@@ -4459,7 +4491,7 @@ ${joinClauses.join('\n')}`;
                                         const firstValue = value[tableAlias];
                                         if (firstValue && typeof firstValue === 'object' && '__tableAlias' in firstValue) {
                                             const alias = firstValue.__tableAlias;
-                                            const relConfig = this.schema.relations[alias];
+                                            const relConfig = this.relationForRef(firstValue, alias);
                                             if (relConfig && relConfig.type === 'one') {
                                                 // This is a reference navigation - select all fields from the target table
                                                 // Performance: Use cached target schema
@@ -4757,6 +4789,10 @@ ${joinClauses.join('\n')}`;
         this.detectAndAddJoinsFromSelection(selection, joins);
         // Scan WHERE condition for navigation property references and add JOINs
         this.detectAndAddJoinsFromCondition(this.whereCond, joins);
+        // Repeat the shadow check now that the SELECT list has contributed its joins: the colliding
+        // navigation can be named ONLY in the projection, where the WHERE-time check cannot see it.
+        // EXISTS ignores the select list, so nothing else would catch that shape.
+        (0, query_utils_2.assertNoCorrelatedAliasShadowing)(this.schema.name, this.correlatedAliasesFromCondition, new Set(joins.map(join => join.alias)));
         // Handle case where selection is a single value (not an object with properties)
         if (selection instanceof conditions_1.SqlFragment) {
             const sqlBuildContext = {
@@ -4831,7 +4867,7 @@ ${joinClauses.join('\n')}`;
                     if ('__tableAlias' in value && value.__tableAlias && typeof value.__tableAlias === 'string') {
                         const tableAlias = value.__tableAlias;
                         const columnName = value.__dbColumnName;
-                        const relConfig = this.schema.relations[tableAlias];
+                        const relConfig = this.relationForRef(value, tableAlias);
                         if (relConfig && !joins.find(j => j.alias === tableAlias)) {
                             let targetSchema;
                             if (relConfig.targetTableBuilder) {
@@ -5861,7 +5897,7 @@ ${joinClauses.join('\n')}`;
                 // correlation whatever it is called, and reading it as our own navigation (because a
                 // relation happens to carry the same name) is what silently misbinds the predicate.
                 // See isForeignChainRef.
-                if (tableAlias !== currentTableName && isForeignChainRef(ref, this.chainId)) {
+                if (tableAlias !== currentTableName && (0, query_utils_2.isForeignChainRef)(ref, this.chainId)) {
                     outerRefs.push(ref);
                 }
                 else if (tableAlias !== currentTableName && !this.schema.relations[tableAlias]) {
@@ -5949,7 +5985,7 @@ class ReferenceQueryBuilder {
      * Create a mock object that exposes the target table's columns
      * This allows accessing related fields like: p.user.username
      */
-    createMockTargetRow(holder) {
+    createMockTargetRow(holder, chainId) {
         if (this.targetTableSchema) {
             // Prototype-level cache — see MockRowCache's doc. Everything the getters close over
             // is fully determined by (target schema object identity, relationName, sourceAlias,
@@ -5976,7 +6012,7 @@ class ReferenceQueryBuilder {
                     holder.prototype = prototype;
                 }
             }
-            return mintReferenceMockRow(prototype);
+            return mintReferenceMockRow(prototype, chainId);
         }
         else {
             // Fallback: use the shared nested proxy that supports deep property access
@@ -6020,6 +6056,8 @@ class ReferenceQueryBuilder {
                             __fieldName: colName,
                             __dbColumnName: dbColumnName,
                             __tableAlias: tableAlias, // Alias for SQL generation
+                            // Identity of the query this navigation hangs off — see mintReferenceMockRow.
+                            __chainId: slots[MOCK_ROW_CHAIN_ID],
                             __sourceTable: sourceTable, // Actual table name for mapper lookup
                             __mapper: mapper, // Include mapper for toDriver transformation in conditions
                             __sqlType: columnSqlTypes[colName], // Column SQL type — lets flag* emit width-exact mask casts
@@ -6103,7 +6141,7 @@ class ReferenceQueryBuilder {
                             let cached = navCache[relName];
                             if (cached === undefined) {
                                 if (holder.prototype !== undefined && mock_row_cache_1.MockRowCache.isEnabled()) {
-                                    cached = navCache[relName] = mintReferenceMockRow(holder.prototype);
+                                    cached = navCache[relName] = mintReferenceMockRow(holder.prototype, slots[MOCK_ROW_CHAIN_ID]);
                                 }
                                 else {
                                     const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, nestedTargetSchema, // Pass the target schema directly
@@ -6111,7 +6149,7 @@ class ReferenceQueryBuilder {
                                     extendedNavPath, // Pass navigation path for nested collections
                                     parentSourceAlias ? tableAlias : '' // Only set source if tracking path
                                     );
-                                    cached = navCache[relName] = refBuilder.createMockTargetRow(holder);
+                                    cached = navCache[relName] = refBuilder.createMockTargetRow(holder, slots[MOCK_ROW_CHAIN_ID]);
                                 }
                             }
                             return cached;
@@ -6306,14 +6344,14 @@ class CollectionQueryBuilder {
                                 return cachedRow;
                             }
                             if (holder.prototype !== undefined && mock_row_cache_1.MockRowCache.isEnabled()) {
-                                return (navCache[relName] = mintReferenceMockRow(holder.prototype));
+                                return (navCache[relName] = mintReferenceMockRow(holder.prototype, slots[MOCK_ROW_CHAIN_ID]));
                             }
                             const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, undefined, // Don't pass schema, force registry lookup
                             schemaRegistry, // Pass schema registry for nested resolution
                             [], // Empty navigation path - this is the first reference in the chain
                             targetTable // Source alias is this collection's target table
                             );
-                            return (navCache[relName] = refBuilder.createMockTargetRow(holder));
+                            return (navCache[relName] = refBuilder.createMockTargetRow(holder, slots[MOCK_ROW_CHAIN_ID]));
                         },
                         enumerable: false,
                         configurable: true,
@@ -6545,11 +6583,22 @@ class CollectionQueryBuilder {
     }
     /**
      * Get field references from this condition.
-     * Returns empty since EXISTS subqueries are self-contained correlated subqueries.
-     * Required for duck-typing compatibility with Condition interface when used in WHERE clauses.
+     *
+     * Only the ones belonging to an ENCLOSING query are surfaced. Those are correlations, and
+     * the outer query has to have their tables in scope for the subquery to reference them: a
+     * lambda saying `l.city!.name` needs the OUTER query to join `city`, or the emitted
+     * `"city"."name"` has no FROM-clause entry to bind to. Reporting them here is what lets the
+     * parent's join detection see the requirement.
+     *
+     * Our OWN refs stay hidden, as they always were — they are emitted inside this subquery and
+     * must not drag joins into the parent. Required for duck-typing compatibility with the
+     * Condition interface when used in WHERE clauses.
      */
     getFieldRefs() {
-        return [];
+        if (!this.whereCond) {
+            return [];
+        }
+        return this.whereCond.getFieldRefs().filter(ref => (0, query_utils_2.isForeignChainRef)(ref, undefined));
     }
     /**
      * Build SQL for this collection as a correlated EXISTS subquery.
@@ -6596,38 +6645,11 @@ class CollectionQueryBuilder {
         // the statement failed with `missing FROM-clause entry for table "<alias>"`.
         // Reuses the selector path's machinery: seed aliases + chains from the
         // condition's FieldRefs, then resolve multi-hop paths against the target schema.
-        if (this.whereCond) {
-            const joinedAliases = new Set([
-                ...this.navigationPath.map(nav => nav.alias),
-                ...this.selectManyJoins.map(nav => nav.alias),
-            ]);
-            const targetSchema = this.schemaRegistry?.get(targetTable);
-            if (targetSchema) {
-                const whereJoins = [];
-                const whereAliases = new Set();
-                for (const ref of this.whereCond.getFieldRefs()) {
-                    const refAlias = ref?.__tableAlias;
-                    // Direct columns of the target arrive under the `__collection_<table>__`
-                    // marker (rewritten below) or the bare table name — neither needs a join.
-                    if (!refAlias || refAlias === targetTable || refAlias.startsWith('__collection_') || joinedAliases.has(refAlias)) {
-                        continue;
-                    }
-                    this.addNavigationJoinForFieldRef(ref, whereJoins, targetTable, targetSchema, whereAliases);
-                }
-                if (whereAliases.size > 0) {
-                    this.resolveNavigationJoins(whereAliases, whereJoins, targetSchema);
-                }
-                for (const nav of whereJoins) {
-                    if (joinedAliases.has(nav.alias)) {
-                        continue;
-                    }
-                    joinedAliases.add(nav.alias);
-                    const joinType = nav.isMandatory ? 'JOIN' : 'LEFT JOIN';
-                    const fk = nav.foreignKeys[0];
-                    const pk = (nav.matches && nav.matches.length > 0) ? nav.matches[0] : 'id';
-                    allJoins.push(`${joinType} "${nav.targetTable}" "${nav.alias}" ON "${nav.sourceAlias}"."${fk}" = "${nav.alias}"."${pk}"`);
-                }
-            }
+        for (const nav of this.resolveWhereNavigationJoins(sourceTable)) {
+            const joinType = nav.isMandatory ? 'JOIN' : 'LEFT JOIN';
+            const fk = nav.foreignKeys[0];
+            const pk = (nav.matches && nav.matches.length > 0) ? nav.matches[0] : 'id';
+            allJoins.push(`${joinType} "${nav.targetTable}" "${nav.alias}" ON "${nav.sourceAlias}"."${fk}" = "${nav.alias}"."${pk}"`);
         }
         const navJoinsSQL = allJoins.join('\n');
         // Build WHERE clause: correlation + additional conditions
@@ -6741,10 +6763,89 @@ class CollectionQueryBuilder {
      * Add a navigation JOIN for a FieldRef if it references a related table
      * Handles multi-level navigation by recursively resolving the join chain
      */
+    /**
+     * The joins required by REFERENCE navigations inside this collection's OWN where-condition,
+     * e.g. `shelves.where(s => eq(s.city!.name, 'Rural'))`.
+     *
+     * Navigation joins used to be derived from SELECTORS only, which left a where-navigated
+     * alias unjoined. Both collection render paths need this and neither can rely on the other:
+     * an `exists()` aggregation has no selector at all, and a collection in a PROJECTION has one
+     * that says nothing about the where-clause. Emitting it in one place is what keeps the two
+     * paths answering the same question — the projection path previously bound such an alias to
+     * whatever the OUTER query happened to have joined under that name (silently wrong under
+     * `lateral`) or failed with `missing FROM-clause entry` when it had not.
+     *
+     * `correlationAlias` is the parent's alias in the collection's implicit correlation; a
+     * navigation of ours named the same would shadow it, which cannot be rendered.
+     */
+    resolveWhereNavigationJoins(correlationAlias) {
+        if (!this.whereCond) {
+            return [];
+        }
+        const targetSchema = this.schemaRegistry?.get(this.targetTable);
+        if (!targetSchema) {
+            return [];
+        }
+        const alreadyJoined = new Set([
+            ...this.navigationPath.map(nav => nav.alias),
+            ...this.selectManyJoins.map(nav => nav.alias),
+        ]);
+        const whereJoins = [];
+        const whereAliases = new Set();
+        for (const ref of this.whereCond.getFieldRefs()) {
+            const refAlias = ref?.__tableAlias;
+            // Correlations to the enclosing row are filtered inside `addNavigationJoinForFieldRef` —
+            // the choke point shared with the selector loops. Direct columns of the target arrive
+            // under the `__collection_<table>__` marker or the bare table name; neither needs a join.
+            if (!refAlias || refAlias === this.targetTable || refAlias.startsWith('__collection_') || alreadyJoined.has(refAlias)) {
+                continue;
+            }
+            this.addNavigationJoinForFieldRef(ref, whereJoins, this.targetTable, targetSchema, whereAliases);
+        }
+        if (whereAliases.size > 0) {
+            this.resolveNavigationJoins(whereAliases, whereJoins, targetSchema);
+        }
+        // A navigation of ours named like the collection's PARENT needs care: the collection's
+        // correlation to that parent is implicit and always present, so both want one alias.
+        //
+        // Whether that is a problem depends on whether the navigation is the INVERSE of the
+        // collection's own foreign key:
+        //
+        // - Same key pair (`userEshop.cards` correlating on `card.user_id = user_eshop.id`, and
+        //   the card's own `userEshop` navigation joining on exactly that) — the navigation IS
+        //   the parent row. The join would be the identity, so it is dropped and the alias keeps
+        //   denoting the parent, which is what the reference meant. Rendering the join instead
+        //   would shadow the correlation and detach every child from its parent.
+        // - A DIFFERENT key pair — the navigation points at another row of the parent's table, so
+        //   the alias would have to mean two things at once. That cannot be rendered; refuse it.
+        const sameKeys = (a, b) => {
+            const left = a ?? [];
+            const right = b ?? [];
+            return left.length === right.length && left.every((key, index) => key === right[index]);
+        };
+        const inverseOfCollectionKey = (nav) => sameKeys(nav.foreignKeys, this.foreignKeys) && sameKeys(nav.matches, this.matches);
+        const clashing = whereJoins.filter(nav => nav.alias === correlationAlias);
+        (0, query_utils_2.assertNoCorrelatedAliasShadowing)(this.targetTable, [correlationAlias], new Set(clashing.filter(nav => !inverseOfCollectionKey(nav)).map(nav => nav.alias)));
+        return whereJoins.filter(nav => !alreadyJoined.has(nav.alias) && nav.alias !== correlationAlias);
+    }
     addNavigationJoinForFieldRef(fieldRef, joins, sourceAlias, sourceSchema, allTableAliases, joinedAliases) {
         if (!fieldRef || typeof fieldRef !== 'object' || !('__tableAlias' in fieldRef)) {
             return;
         }
+        // A ref carrying a chain id was minted by the ENCLOSING query, not by this collection:
+        // it is a correlation to the outer row, which the outer query already has in scope.
+        // Refs this builder mints carry none — marker-aliased columns AND navigation traversals
+        // alike — so this separates `s.library.name` (ours: join it) from `l.name` (outer: leave
+        // it) even though both render under the alias `library`. Joining the latter pulls a
+        // second copy of the outer table into the subquery and binds the correlation to it,
+        // which silently makes the predicate compare the inner row with itself.
+        //
+        // Guarded HERE rather than at each caller because this method is the single choke point
+        // through which the WHERE loop and all three selector loops resolve a ref into a join.
+        // See isForeignChainRef.
+        if ((0, query_utils_2.isForeignChainRef)(fieldRef, undefined)) {
+            return;
+        }
         const tableAlias = fieldRef.__tableAlias;
         // If this references the target table directly, no join needed
         if (!tableAlias || tableAlias === this.targetTable) {
@@ -7327,6 +7428,14 @@ class CollectionQueryBuilder {
                 this.detectNavigationJoins(selectorResult, navigationJoins, this.targetTable, this.targetTableSchema);
             }
         }
+        // The selector says nothing about the collection's own WHERE, so a navigation used only
+        // there would render unjoined — and then bind to whatever the OUTER query has under that
+        // alias instead of failing. Same resolution the inline EXISTS path uses.
+        for (const nav of this.resolveWhereNavigationJoins(this.sourceTable)) {
+            if (!navigationJoins.some(existing => existing.alias === nav.alias)) {
+                navigationJoins.push(nav);
+            }
+        }
         // Step 5b: Merge navigation path joins (for intermediate tables in navigation chains)
         // These joins are needed when accessing a collection through a chain like:
         // ln.edition.book.category.formats