@quereus/quereus 4.5.0 → 4.7.0

package/dist/src/planner/building/select.js

@@ -4,19 +4,21 @@ import { StatusCode } from '../../common/types.js';
 import { SingleRowNode } from '../nodes/single-row.js';
 import { buildTableReference } from './table.js';
 import { isMaintainedTable } from '../../schema/derivation.js';
+import { isViewSchema } from '../../schema/view.js';
 import { AliasedScope } from '../scopes/aliased.js';
 import { RegisteredScope } from '../scopes/registered.js';
 import { MultiScope } from '../scopes/multi.js';
 import { ShadowScope } from '../scopes/shadow.js';
+import { EmptyScope } from '../scopes/empty.js';
 import { ProjectNode } from '../nodes/project-node.js';
-import { buildExpression } from './expression.js';
+import { buildComparison, buildExpression } from './expression.js';
 import { FilterNode } from '../nodes/filter.js';
 import { buildTableFunctionCall } from './table-function.js';
 import { CTEReferenceNode } from '../nodes/cte-reference-node.js';
 import { JoinNode } from '../nodes/join-node.js';
-import { resolveComparisonCollation, collationConflictError } from '../analysis/comparison-collation.js';
 import { EXISTENCE_FLAG_TYPE } from '../nodes/join-utils.js';
 import { ColumnReferenceNode } from '../nodes/reference.js';
+import { BinaryOpNode } from '../nodes/scalar.js';
 import { TEXT_TYPE } from '../../types/builtin-types.js';
 import { ValuesNode } from '../nodes/values-node.js';
 import { createLogger } from '../../common/logger.js';
@@ -25,14 +27,15 @@ import { AssertedKeysNode } from '../nodes/asserted-keys-node.js';
 import { computeLensAssertedKeyFds } from '../../schema/lens-prover.js';
 import { buildLensAuxiliaryAccessMarker } from './lens-auxiliary-access.js';
 // Import decomposed functionality
-import { buildWithContext } from './select-context.js';
+import { buildWithContext, enterStoredBodyEnv } from './select-context.js';
+import { storedBodyContext } from '../stored-body-context.js';
 import { buildCompoundSelect } from './select-compound.js';
 import { analyzeSelectColumns, buildStarProjections } from './select-projections.js';
-import { buildAggregatePhase, buildFinalAggregateProjections } from './select-aggregates.js';
+import { buildAggregatePhase, buildFinalAggregateProjections, buildGroupedWindowContext } from './select-aggregates.js';
 import { buildWindowPhase } from './select-window.js';
 import { buildFinalProjections, applyDistinct, applyOrderBy, applyLimitOffset, createProjectionOutputScope } from './select-modifiers.js';
 import { SortNode } from '../nodes/sort.js';
-import { buildSelectListAsts, resolveOrdinalReference } from './select-ordinal.js';
+import { buildOrdinalAwareExpression, buildSelectListEntries } from './select-ordinal.js';
 import { buildInsertStmt } from './insert.js';
 import { buildUpdateStmt } from './update.js';
 import { buildDeleteStmt } from './delete.js';
@@ -53,12 +56,19 @@ export function buildSelectStmt(ctx, stmt, parentCTEs = new Map(),
  * expose only their declared columns.
  */
 preserveInputColumns = true) {
-    // Apply schema path from statement if present
+    // A sub-select copied out of a stored view / MV body by the write-through lowering carries
+    // that body's whole naming environment on the AST node (`AST.StoredBodyEnv`, stamped by
+    // `mapNestedSelects` in `mutation/scope-transform.ts` from `buildViewMutation`). Re-enter
+    // it here — home schema, the body's declared `with schema` path, and the body's own
+    // leading `with` clause as this fragment's parent CTE namespace, in that order. A
+    // pass-through for every other statement; see `enterStoredBodyEnv`.
+    const { ctx: storedCtx, parentCTEs: storedParentCTEs } = enterStoredBodyEnv(ctx, stmt.storedBodyEnv, parentCTEs);
+    // A fragment's OWN `with schema` clause outranks the carried path.
     const contextWithSchemaPath = stmt.schemaPath
-        ? { ...ctx, schemaPath: stmt.schemaPath }
-        : ctx;
+        ? { ...storedCtx, schemaPath: stmt.schemaPath }
+        : storedCtx;
     // Phase 0: Handle WITH clause if present
-    const { contextWithCTEs, cteNodes } = buildWithContext(contextWithSchemaPath, stmt, parentCTEs);
+    const { contextWithCTEs, cteNodes } = buildWithContext(contextWithSchemaPath, stmt, storedParentCTEs);
     // Handle compound set operations (UNION / INTERSECT / EXCEPT)
     if (stmt.compound) {
         return buildCompoundSelect(stmt, contextWithCTEs, cteNodes, (ctx, stmt, parentCTEs) => buildSelectStmt(ctx, stmt, parentCTEs));
@@ -74,6 +84,11 @@ preserveInputColumns = true) {
         throw new QuereusError('SELECT with multiple FROM sources (joins) not supported.', StatusCode.UNSUPPORTED, undefined, stmt.from[1].loc?.start.line, stmt.from[1].loc?.start.column);
     }
     // Phase 2: Create the main scope for this SELECT statement
+    // NOTE: the `|| ft.scope` fallback only fires for the FROM-less SingleRowNode, which
+    // buildFrom never registers. Every scope buildFrom does register is own-only (see
+    // registerColumnScope); a node's own `.scope` is the enclosing chain, so if this
+    // fallback ever starts firing for a real source it silently reinstates the chaining
+    // this ShadowScope exists to replace.
     const columnScopes = fromTables.map(ft => ctx.outputScopes.get(ft) || ft.scope).filter(Boolean);
     const selectScope = new ShadowScope([...columnScopes, contextWithCTEs.scope]);
     let selectContext = { ...contextWithCTEs, scope: selectScope };
@@ -100,29 +115,53 @@ preserveInputColumns = true) {
     // Build projections based on the SELECT list
     const projections = [];
     // Analyze SELECT columns
-    const { projections: columnProjections, aggregates, windowFunctions, hasAggregates: hasAggregatesInSelect, hasWindowFunctions, hasWrappedAggregates } = analyzeSelectColumns(stmt.columns, selectContext, input);
+    const { projectionsByColumn, aggregates, windowFunctions, hasAggregates: hasAggregatesInSelect, hasWindowFunctions, hasWrappedAggregates } = analyzeSelectColumns(stmt.columns, selectContext, input);
     // `hasAggregates` may grow as buildAggregatePhase collects HAVING-only or
     // ORDER-BY-only aggregates; track it locally so the post-aggregate branch
     // is taken when those promote a non-aggregate query into an aggregate one.
     let hasAggregates = hasAggregatesInSelect;
-    // Handle SELECT * separately
+    // Assemble the projection list in WRITTEN select-list order, expanding each star
+    // in place. Output columns follow the order the user wrote them — a star ahead of
+    // a named column emits its columns first, behind it emits them last — which is what
+    // SQLite/PostgreSQL do, and what the grouped path (`buildFinalAggregateProjections`,
+    // which walks `stmt.columns` itself) has always done.
+    //
+    // Star expansions are also kept keyed by their AST column so the aggregate path can
+    // expand each star back to *its own* columns — a select list may hold more than
+    // one star (`select a.*, b.* from a join b`).
+    const starProjectionsByColumn = new Map();
     for (const column of stmt.columns) {
         if (column.type === 'all') {
-            const starProjections = buildStarProjections(column, input, selectScope);
-            projections.push(...starProjections);
+            const expanded = buildStarProjections(column, input, selectScope);
+            starProjectionsByColumn.set(column, expanded);
+            projections.push(...expanded);
+            continue;
         }
+        // Non-star column. Aggregate items produced no projection (they are routed
+        // into the aggregate phase instead) and are simply absent from the map.
+        const columnProjection = projectionsByColumn.get(column);
+        if (columnProjection)
+            projections.push(columnProjection);
     }
-    // Add non-star projections
-    projections.push(...columnProjections);
-    // Build the source-order AST list of SELECT-list output columns (with stars expanded)
+    // Build the source-order list of SELECT-list output columns (with stars expanded)
     // for resolving GROUP BY / ORDER BY positional ordinals.
-    const selectListAsts = buildSelectListAsts(stmt.columns, input);
+    const selectListEntries = buildSelectListEntries(stmt.columns, input);
     // Process aggregates if present
-    const aggregateResult = buildAggregatePhase(input, stmt, selectContext, aggregates, hasAggregates, projections, hasWrappedAggregates, selectListAsts);
+    const aggregateResult = buildAggregatePhase(input, stmt, selectContext, aggregates, hasAggregates, projections, hasWrappedAggregates, selectListEntries, starProjectionsByColumn);
     input = aggregateResult.output;
     let preAggregateSort = aggregateResult.preAggregateSort;
     let orderByAppliedEarly = false;
     let aggregateProjectionScope;
+    // Set when the query is BOTH grouped and windowed: the grouped select-list
+    // projection list, to be projected above the window phase's WindowNode.
+    let windowSelectProjections;
+    // Also set only for a grouped, windowed query: what the aggregate's rows carry,
+    // so the window phase can redirect a window specification onto them and reject
+    // one that reads anything else.
+    let windowGroupedContext;
+    // The node whose output attributes ARE this SELECT's result columns, once one
+    // exists. A positional ORDER BY binds to its Nth attribute (see applyOrderBy).
+    let orderByOutputRelation;
     // Update context if we have aggregates
     if (aggregateResult.aggregateScope) {
         // HAVING-only or ORDER-BY-only aggregates may have promoted this into an
@@ -144,22 +183,50 @@ preserveInputColumns = true) {
             !preAggregateSort &&
             !hasWindowFunctions &&
             stmt.orderBy && stmt.orderBy.length > 0) {
-            input = applyOrderBy(input, stmt, selectContext, preAggregateSort, undefined, true, selectListAsts);
+            input = applyOrderBy(input, stmt, selectContext, preAggregateSort, undefined, true, selectListEntries);
             orderByAppliedEarly = true;
         }
-        // Build final projections if needed
-        if (aggregateResult.needsFinalProjection && aggregateResult.aggregateNode && aggregateResult.groupByExpressions) {
-            const finalProjections = buildFinalAggregateProjections(stmt, selectContext, aggregateResult.aggregateScope, aggregateResult.aggregateNode, aggregates, aggregateResult.groupByExpressions);
-            // When HAVING-only or ORDER-BY-only aggregates were added, don't preserve
-            // input columns so they are stripped from the output (they exist only for
-            // those clauses).
-            const preserveForAggregate = preserveInputColumns &&
-                !aggregateResult.hasHavingOnlyAggregates &&
-                !aggregateResult.hasOrderByOnlyAggregates;
-            input = new ProjectNode(selectScope, input, finalProjections, undefined, undefined, preserveForAggregate);
-            // Expose final-projection output column names (including SELECT-list aliases)
-            // so subsequent ORDER BY can reference aliases like the non-aggregate path.
-            aggregateProjectionScope = createProjectionOutputScope(input);
+        // A grouped, windowed query's window specifications and function arguments are
+        // built against the aggregate-output scope but fall through to the pre-aggregate
+        // select scope for anything the aggregate does not carry. Some of what falls
+        // through is a legal grouping key under another spelling and some is a genuinely
+        // ungrouped column, so hand the window phase both halves: the maps that redirect
+        // the former onto the aggregate's own output columns, and the strict coverage
+        // test that rejects the latter at plan time. The aggregate's source relation goes
+        // along so both halves can tell which references belong to THIS query — a window
+        // specification may contain a subquery, whose own columns and whose correlated
+        // references to an enclosing query are neither redirected nor rejected.
+        if (hasWindowFunctions &&
+            aggregateResult.aggregateNode &&
+            aggregateResult.groupByExpressions &&
+            aggregateResult.groupByExpressions.length > 0) {
+            windowGroupedContext = buildGroupedWindowContext(aggregateResult.groupByExpressions, aggregateResult.aggregateNode.getAttributes(), aggregateResult.aggregateNode.getRelations()[0]);
+        }
+        // Build final projections if needed. A window function in the select list also
+        // forces one: the window phase projects the select list ABOVE its WindowNode, so
+        // the grouped select list must be materialized as a projection list here even when
+        // the AggregateNode's own output would otherwise have been the result shape.
+        if ((aggregateResult.needsFinalProjection || hasWindowFunctions) && aggregateResult.aggregateNode && aggregateResult.groupByExpressions) {
+            const finalProjections = buildFinalAggregateProjections(stmt, selectContext, aggregateResult.aggregateScope, aggregateResult.aggregateNode, aggregates, aggregateResult.groupByExpressions, starProjectionsByColumn);
+            if (hasWindowFunctions) {
+                // Hand the grouped select list to the window phase instead of projecting it
+                // here: the WindowNode must sit between the aggregate output and the final
+                // projection, so there is exactly ONE projection and it is above the window.
+                windowSelectProjections = finalProjections;
+            }
+            else {
+                // When HAVING-only or ORDER-BY-only aggregates were added, don't preserve
+                // input columns so they are stripped from the output (they exist only for
+                // those clauses).
+                const preserveForAggregate = preserveInputColumns &&
+                    !aggregateResult.hasHavingOnlyAggregates &&
+                    !aggregateResult.hasOrderByOnlyAggregates;
+                input = new ProjectNode(selectScope, input, finalProjections, undefined, undefined, preserveForAggregate);
+                // Expose final-projection output column names (including SELECT-list aliases)
+                // so subsequent ORDER BY can reference aliases like the non-aggregate path.
+                aggregateProjectionScope = createProjectionOutputScope(input);
+                orderByOutputRelation = input;
+            }
         }
     }
     // Handle window functions if present
@@ -181,15 +248,14 @@ preserveInputColumns = true) {
                 if (orderByClause.expr.type === 'column') {
                     const orderColumn = orderByClause.expr.name.toLowerCase();
                     if (!selectedColumns.has(orderColumn)) {
-                        // Apply ORDER BY before window projections
-                        const sortKeys = stmt.orderBy.map(orderBy => {
-                            const resolved = resolveOrdinalReference(orderBy.expr, selectListAsts, 'ORDER BY');
-                            return {
-                                expression: buildExpression(selectContext, resolved ?? orderBy.expr),
-                                direction: orderBy.direction,
-                                nulls: orderBy.nulls
-                            };
-                        });
+                        // Apply ORDER BY before window projections. This sort sits BELOW the
+                        // window projection, so a positional reference resolves through the
+                        // select list (no output attributes exist yet to bind to).
+                        const sortKeys = stmt.orderBy.map(orderBy => ({
+                            expression: buildOrdinalAwareExpression(selectContext, orderBy.expr, selectListEntries, 'ORDER BY'),
+                            direction: orderBy.direction,
+                            nulls: orderBy.nulls
+                        }));
                         input = new SortNode(selectContext.scope, input, sortKeys);
                         preWindowSort = true;
                         break;
@@ -197,7 +263,10 @@ preserveInputColumns = true) {
                 }
             }
         }
-        input = buildWindowPhase(input, windowFunctions, selectContext, stmt);
+        input = buildWindowPhase(input, windowFunctions, selectContext, windowSelectProjections ?? projections, windowGroupedContext);
+        // The window phase ends in a ProjectNode over the SELECT list, so that node's
+        // attributes are this query's result columns.
+        orderByOutputRelation = input;
         // Update context to include window output columns
         const windowOutputScope = new RegisteredScope(selectContext.scope);
         const windowAttributes = input.getAttributes();
@@ -213,15 +282,24 @@ preserveInputColumns = true) {
             preAggregateSort = true;
         }
     }
-    // Handle final projections for non-aggregate, non-window cases
-    if (!hasAggregates && !hasWindowFunctions) {
-        const finalResult = buildFinalProjections(input, projections, selectScope, stmt, selectContext, preserveInputColumns, selectListAsts);
+    // Handle final projections for non-aggregate, non-window cases.
+    // A GROUP BY with no aggregate functions anywhere still went through the
+    // aggregate phase (which built its own final projection against the
+    // AggregateNode output); re-running buildFinalProjections here would emit a
+    // second projection whose column references still point at *pre-aggregate*
+    // attributes, which the AggregateNode does not output.
+    const hasGrouping = Boolean(aggregateResult.aggregateScope);
+    if (!hasGrouping && !hasWindowFunctions) {
+        const finalResult = buildFinalProjections(input, projections, selectScope, stmt, selectContext, preserveInputColumns, selectListEntries);
         input = finalResult.output;
         selectContext = finalResult.finalContext;
         preAggregateSort = finalResult.preAggregateSort;
+        // Either the final ProjectNode, or — for an identity `select *` — the source
+        // itself, whose attributes already ARE the select list.
+        orderByOutputRelation = finalResult.output;
         // Apply final modifiers with projection scope for column alias resolution
         input = applyDistinct(input, stmt, selectScope);
-        input = applyOrderBy(input, stmt, selectContext, preAggregateSort, finalResult.projectionScope, false, selectListAsts);
+        input = applyOrderBy(input, stmt, selectContext, preAggregateSort, finalResult.projectionScope, false, selectListEntries, orderByOutputRelation);
         input = applyLimitOffset(input, stmt, selectContext, finalResult.projectionScope);
     }
     else {
@@ -233,7 +311,7 @@ preserveInputColumns = true) {
         if (!orderByAppliedEarly) {
             // In the aggregate path, ORDER BY may legally reference aggregates; in the
             // window path it may reference window outputs. Both are now in selectContext.
-            input = applyOrderBy(input, stmt, selectContext, preAggregateSort, aggregateProjectionScope, hasAggregates, selectListAsts);
+            input = applyOrderBy(input, stmt, selectContext, preAggregateSort, aggregateProjectionScope, hasAggregates, selectListEntries, orderByOutputRelation);
         }
         input = applyLimitOffset(input, stmt, selectContext, aggregateProjectionScope);
     }
@@ -255,9 +333,17 @@ export function buildValuesStmt(ctx, stmt) {
 /**
  * Registers each column of a relational node as a symbol in a new scope,
  * wrapped with an AliasedScope for qualified name resolution.
+ *
+ * The scope is deliberately parented on {@link EmptyScope} — a FROM source's scope
+ * holds ONLY its own columns and answers "no" for anything else. The fallback to the
+ * enclosing query is composed exactly once by each consumer (`buildSelectStmt`'s
+ * `ShadowScope`, `buildJoin`'s ON-condition and LATERAL `ShadowScope`s). Chaining each
+ * source scope to the caller's scope instead would make `MultiScope`'s first-match reach
+ * the outer scope through peer #1 before peer #2 is ever consulted, so a join's own
+ * right-hand source loses name lookup to a same-named enclosing symbol.
  */
-function registerColumnScope(parentScope, node, scopeName, alias) {
-    const registered = new RegisteredScope(parentScope);
+function registerColumnScope(node, scopeName, alias) {
+    const registered = new RegisteredScope(EmptyScope.instance);
     const attributes = node.getAttributes();
     node.getType().columns.forEach((c, i) => {
         const attr = attributes[i];
@@ -286,8 +372,12 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
     let columnScope;
     if (fromClause.type === 'table') {
         const tableName = fromClause.table.name.toLowerCase();
-        // Check if this is a CTE reference
-        if (cteNodes.has(tableName)) {
+        // Check if this is a CTE reference. A schema-qualified name (`main.c`) names a
+        // schema object, never a CTE — CTEs live in no schema — so a qualifier sends the
+        // name straight to the ordinary view / table resolution below, even when a
+        // same-named CTE is in scope. Matches the write path (`resolveCteTarget`) and
+        // SQLite / PostgreSQL.
+        if (!fromClause.table.schema && cteNodes.has(tableName)) {
             const cteNode = cteNodes.get(tableName);
             // Check if this is an internal recursive CTE reference
             if (CapabilityDetectors.isRecursiveCTERef(cteNode)) {
@@ -297,7 +387,7 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                     internalRefNode = new AliasNode(parentContext.scope, cteNode, fromClause.alias.toLowerCase());
                 }
                 fromTable = internalRefNode;
-                columnScope = registerColumnScope(parentContext.scope, fromTable, tableName, fromClause.alias?.toLowerCase() ?? tableName);
+                columnScope = registerColumnScope(fromTable, tableName, fromClause.alias?.toLowerCase() ?? tableName);
             }
             else {
                 // Regular CTE reference - cache by CTE name + alias to ensure consistent attribute IDs
@@ -318,33 +408,32 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                     const attrs = cteRefNode.getAttributes();
                     logger(`Created new CTE reference ${cacheKey}, attrs=[${attrs.map(a => a.id).join(',')}]`);
                 }
-                columnScope = registerColumnScope(parentContext.scope, cteRefNode, tableName, fromClause.alias?.toLowerCase() ?? tableName);
+                columnScope = registerColumnScope(cteRefNode, tableName, fromClause.alias?.toLowerCase() ?? tableName);
                 fromTable = cteRefNode;
             }
         }
         else {
-            // Check if this is a view
-            const schemaName = fromClause.table.schema || parentContext.db.schemaManager.getCurrentSchemaName();
-            const viewSchema = parentContext.db.schemaManager.getView(schemaName, fromClause.table.name);
-            let maintainedTable = viewSchema ? undefined : parentContext.db.schemaManager.getMaintainedTable(schemaName, fromClause.table.name);
-            if (!viewSchema && !maintainedTable && !fromClause.table.schema) {
-                // An unqualified name resolves through the schema path below
-                // (buildTableReference); mirror that here so a path-resolved
-                // maintained table still gets the stale re-validation guard.
-                const pathResolved = parentContext.db.schemaManager.findTable(fromClause.table.name, undefined, parentContext.schemaPath);
-                if (isMaintainedTable(pathResolved))
-                    maintainedTable = pathResolved;
-            }
+            // Check if this is a view. An unqualified name resolves through the
+            // schema search path — one path entry at a time, that schema's tables
+            // and views checked together — exactly as `buildTableReference` below
+            // resolves a plain table name.
+            const resolvedItem = parentContext.db.schemaManager.findSchemaItem(fromClause.table.name, fromClause.table.schema, parentContext.schemaPath);
+            const viewSchema = isViewSchema(resolvedItem) ? resolvedItem : undefined;
+            const maintainedTable = !isViewSchema(resolvedItem) && isMaintainedTable(resolvedItem) ? resolvedItem : undefined;
             if (viewSchema) {
                 // Build the view's body. The body is a QueryExpr — today only
                 // SELECT and VALUES bodies plan; DML bodies are rejected at
                 // CREATE VIEW plan time so we never get here with one.
+                // The body plans under the VIEW's home-schema path (not the
+                // caller's) so its unqualified source names resolve next to the
+                // view — independent of the reading statement's search path.
+                const viewBodyContext = storedBodyContext(parentContext, viewSchema.schemaName);
                 let viewSelectNode;
                 if (viewSchema.selectAst.type === 'select') {
-                    viewSelectNode = buildSelectStmt(parentContext, viewSchema.selectAst, cteNodes);
+                    viewSelectNode = buildSelectStmt(viewBodyContext, viewSchema.selectAst);
                 }
                 else if (viewSchema.selectAst.type === 'values') {
-                    viewSelectNode = buildValuesStmt(parentContext, viewSchema.selectAst);
+                    viewSelectNode = buildValuesStmt(viewBodyContext, viewSchema.selectAst);
                 }
                 else {
                     throw new QuereusError(`View '${viewSchema.name}' has a ${viewSchema.selectAst.type.toUpperCase()} body, which is not yet supported.`, StatusCode.UNSUPPORTED);
@@ -397,7 +486,7 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                 else {
                     fromTable = viewSelectNode;
                 }
-                columnScope = registerColumnScope(parentContext.scope, fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
+                columnScope = registerColumnScope(fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
             }
             else if (maintainedTable) {
                 // Maintained table (materialized view): resolves through the ORDINARY
@@ -409,13 +498,18 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                 if (maintainedTable.derivation.stale) {
                     // Re-validate the body against current source schemas. An
                     // incompatible change (dropped source, dropped column, …) makes
-                    // the body fail to plan — surface the staleness diagnostic.
+                    // the body fail to plan — surface the staleness diagnostic. Under the
+                    // MV's home-schema path, like every other body re-plan: the caller's
+                    // path would make a perfectly resolvable non-`main` body look
+                    // incompatibly changed, hiding the materialized rows behind a false
+                    // staleness error.
+                    const bodyContext = storedBodyContext(parentContext, maintainedTable.schemaName);
                     try {
                         if (maintainedTable.derivation.selectAst.type === 'select') {
-                            buildSelectStmt(parentContext, maintainedTable.derivation.selectAst, cteNodes);
+                            buildSelectStmt(bodyContext, maintainedTable.derivation.selectAst);
                         }
                         else if (maintainedTable.derivation.selectAst.type === 'values') {
-                            buildValuesStmt(parentContext, maintainedTable.derivation.selectAst);
+                            buildValuesStmt(bodyContext, maintainedTable.derivation.selectAst);
                         }
                     }
                     catch (e) {
@@ -428,7 +522,7 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                     tableNode = new AliasNode(parentContext.scope, tableNode, fromClause.alias.toLowerCase());
                 }
                 fromTable = tableNode;
-                columnScope = registerColumnScope(parentContext.scope, fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
+                columnScope = registerColumnScope(fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
             }
             else {
                 // Regular table
@@ -438,7 +532,7 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
                     tableNode = new AliasNode(parentContext.scope, tableNode, fromClause.alias.toLowerCase());
                 }
                 fromTable = tableNode;
-                columnScope = registerColumnScope(parentContext.scope, fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
+                columnScope = registerColumnScope(fromTable, fromClause.table.name.toLowerCase(), fromClause.alias?.toLowerCase() ?? fromClause.table.name.toLowerCase());
             }
         }
     }
@@ -449,7 +543,7 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
             funcNode = new AliasNode(parentContext.scope, funcNode, fromClause.alias.toLowerCase());
         }
         fromTable = funcNode;
-        columnScope = registerColumnScope(parentContext.scope, fromTable, '', fromClause.alias?.toLowerCase() ?? fromClause.name.name.toLowerCase());
+        columnScope = registerColumnScope(fromTable, '', fromClause.alias?.toLowerCase() ?? fromClause.name.name.toLowerCase());
     }
     else if (fromClause.type === 'subquerySource') {
         // Build the subquery body. SubquerySource now carries any QueryExpr;
@@ -485,8 +579,9 @@ export function buildFrom(fromClause, parentContext, cteNodes = new Map()) {
         fromTable = alias
             ? new AliasNode(parentContext.scope, subqueryNode, alias)
             : subqueryNode;
-        // Create scope for subquery columns
-        const subqueryScope = new RegisteredScope(parentContext.scope);
+        // Create scope for subquery columns. Own-only, parented on EmptyScope, for the
+        // same reason as registerColumnScope — see its doc comment.
+        const subqueryScope = new RegisteredScope(EmptyScope.instance);
         const subqueryAttributes = fromTable.getAttributes();
         // Use provided column names or infer from subquery
         const columnNames = fromClause.columns || fromTable.getType().columns.map(c => c.name);
@@ -542,24 +637,24 @@ function buildJoin(joinClause, parentContext, cteNodes) {
     }
     // Create a combined scope for the join that includes both left and right columns
     const combinedScope = new MultiScope([leftScope, rightScope]);
-    // Create a new planning context with the combined scope for condition evaluation
+    // Context for building the ON condition: the join's own two peers first, then the
+    // enclosing query. Both peers are own-only scopes (see registerColumnScope), so
+    // neither can answer for the other, and everything they do not own — a correlated
+    // outer column, a bind parameter — must still resolve, one level later.
     const joinContext = {
         ...parentContext,
-        scope: combinedScope
+        scope: new ShadowScope([combinedScope, parentContext.scope])
     };
     let condition;
     let usingColumns;
-    // Handle ON condition
+    // ON and USING are mutually exclusive spellings of the same predicate (the parser
+    // accepts one or the other), and USING desugars into the ON condition it means.
     if (joinClause.condition) {
         condition = buildExpression(joinContext, joinClause.condition);
     }
-    // Handle USING columns
-    if (joinClause.columns) {
+    else if (joinClause.columns) {
         usingColumns = joinClause.columns;
-        // Convert USING to ON condition: table1.col1 = table2.col1 AND table1.col2 = table2.col2 ...
-        // For now, store the column names and let the emitter handle the condition
-        // TODO: This could be improved by synthesizing the equality conditions here
-        validateUsingCollations(usingColumns, leftNode, rightNode);
+        condition = buildUsingCondition(usingColumns, leftNode.getAttributes(), rightNode.getAttributes(), joinContext.scope);
     }
     // Existence (`exists … as`) flags: mint a stable attribute id per clause (once,
     // here — so it survives `withChildren` rebuilds) and expose each by its `as`
@@ -587,31 +682,67 @@ function buildJoin(joinClause, parentContext, cteNodes) {
     return joinNode;
 }
 /**
- * Plan-time USING (and, when supported, NATURAL) collation-conflict check. USING
- * column pairs never materialize as a `BinaryOpNode`, so `BinaryOpNode.generateType`'s
- * lattice validation — which covers spelled-out ON-clause equi-joins — never sees
- * them, yet every USING comparator (the nested-loop join's, and the merge/bloom
- * key collations once `equi-pair-extractor` admits the pair) resolves each pair
- * through the SAME provenance lattice. Run the resolver here so a `using (c)` over
- * columns with conflicting explicit/declared collations raises the identical
- * ambiguous-collation error as the equivalent `l.c = r.c`, at plan time rather
- * than only as the emitter's loud backstop. A NATURAL join (not yet parsed)
- * desugars to USING pairs and inherits this check for free.
+ * Desugar `using (c1, c2, …)` into the `on l.c1 = r.c1 and l.c2 = r.c2 …` condition
+ * it is defined to mean, so a USING join is *the same plan* an equivalent ON join
+ * builds. Each pair goes through `buildComparison` — the same helper `buildExpression`
+ * uses for a spelled-out `=` — so everything hanging off a real comparison node
+ * applies to USING for free and cannot drift from the ON spelling:
+ *
+ * - cross-type coercion — a JSON column paired with a TEXT one compares structurally,
+ *   an INTEGER paired with a TEXT one numerically (ticket
+ *   `bug-using-join-skips-cross-type-coercion`; before the desugar USING compared
+ *   raw storage classes and matched nothing).
+ * - `BinaryOpNode.generateType`'s collation-lattice validation — a `using (c)` over
+ *   columns with conflicting explicit/declared collations raises the identical
+ *   ambiguous-collation error as `l.c = r.c`, at plan time rather than only as the
+ *   emitter's backstop. Both spellings resolve each pair through the SAME symmetric
+ *   provenance lattice.
+ * - `extractEquiPairs` — hash/merge key selection, collation tagging and the
+ *   semantic-ordering gate, all off the one extractor.
+ *
+ * A NATURAL join (not yet parsed) desugars to USING pairs and inherits all of this.
+ *
+ * Column references are built **from attributes**, not by resolving a synthesized
+ * qualified `AST.ColumnExpr` through the join scope: a USING column can be ambiguous
+ * by name within one side (`a join b using (k) join c using (k)` — the left side of
+ * the second join has two `k` columns). First-match-per-side by name is the pairing
+ * rule USING has always used here.
+ *
+ * NOTE: the nested-loop USING path used to resolve one comparator per column at emit
+ * time; it now evaluates a condition sub-program per row pair, like every ON join.
+ * Only USING joins that fall back to nested loop (cross-type pairs, existence-flag
+ * joins) pay this, and it is not measured. If a USING-heavy workload ever profiles
+ * slower, the fix belongs in the shared ON-condition evaluation path — not in a
+ * restored USING special case.
  */
-function validateUsingCollations(usingColumns, leftNode, rightNode) {
-    const leftAttrs = leftNode.getAttributes();
-    const rightAttrs = rightNode.getAttributes();
-    for (const colName of usingColumns) {
-        const lower = colName.toLowerCase();
-        const leftAttr = leftAttrs.find(a => a.name.toLowerCase() === lower);
-        const rightAttr = rightAttrs.find(a => a.name.toLowerCase() === lower);
-        // A USING column missing from a side is a name-resolution error surfaced
-        // elsewhere (the join's column scope); skip rather than mask it here.
-        if (!leftAttr || !rightAttr)
-            continue;
-        const resolution = resolveComparisonCollation(leftAttr.type, rightAttr.type);
-        if (resolution.kind === 'conflict')
-            throw collationConflictError(resolution);
+export function buildUsingCondition(usingColumns, leftAttrs, rightAttrs, scope) {
+    if (usingColumns.length === 0) {
+        throw new QuereusError('USING clause requires at least one column', StatusCode.ERROR);
+    }
+    const conjuncts = usingColumns.map(colName => buildUsingColumnEquality(colName, leftAttrs, rightAttrs, scope));
+    return conjuncts.reduce((acc, cur) => new BinaryOpNode(acc.scope, { type: 'binary', operator: 'AND', left: acc.expression, right: cur.expression }, acc, cur));
+}
+/** One USING column's `l.c = r.c` conjunct, built exactly as the ON spelling builds it. */
+function buildUsingColumnEquality(colName, leftAttrs, rightAttrs, scope) {
+    const left = buildUsingOperand(colName, leftAttrs, 'left', scope);
+    const right = buildUsingOperand(colName, rightAttrs, 'right', scope);
+    return buildComparison(scope, { type: 'binary', operator: '=', left: left.expression, right: right.expression }, left, right);
+}
+/**
+ * One side's operand for a USING column: a reference to the FIRST attribute of that
+ * name on that side (see the pairing rule on {@link buildUsingCondition}), qualified
+ * by its relation so the synthesized AST reads like the ON spelling.
+ */
+function buildUsingOperand(colName, attrs, side, scope) {
+    const lower = colName.toLowerCase();
+    const index = attrs.findIndex(a => a.name.toLowerCase() === lower);
+    if (index === -1) {
+        throw new QuereusError(`USING column not found on ${side} side of join: ${colName}`, StatusCode.ERROR);
     }
+    const attr = attrs[index];
+    const expr = attr.relationName
+        ? { type: 'column', name: attr.name, table: attr.relationName }
+        : { type: 'column', name: attr.name };
+    return new ColumnReferenceNode(scope, expr, attr.type, attr.id, index);
 }
 //# sourceMappingURL=select.js.map