@quereus/quereus 4.11.0 → 4.12.1

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

@@ -14,6 +14,7 @@ import { isAggregateFunctionSchema } from '../../schema/function.js';
 import { expressionToString, expressionToIdentityString } from '../../emit/ast-stringify.js';
 import { buildOrdinalAwareExpression, resolveOrdinalReference } from './select-ordinal.js';
 import { collectDefinedAttrIds } from '../analysis/equi-correlation.js';
+import { walkAstNodes } from '../analysis/predicate-shape.js';
 import { PlanNodeType } from '../nodes/plan-node-type.js';
 /**
  * Processes GROUP BY, aggregates, and HAVING clauses
@@ -32,14 +33,17 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
             hasHavingOnlyAggregates = true;
         }
     }
-    // Detect aggregate function references in ORDER BY. They are only legal when
-    // the query is otherwise an aggregate query (has aggregates in SELECT/HAVING
-    // or has a GROUP BY). When legal, any ORDER BY aggregate not already present
-    // in the SELECT or HAVING aggregate list must be added to the AggregateNode
-    // so it is computed and available to the post-aggregate sort.
-    const orderByHasAggregates = orderByContainsAggregates(stmt.orderBy, selectContext, selectList);
+    // Decide where this query's ORDER BY has to run (see
+    // `orderByNeedsPostAggregateSort`). Aggregate function references in ORDER BY are
+    // only legal when the query is otherwise an aggregate query (has aggregates in
+    // SELECT/HAVING or has a GROUP BY). When legal, any ORDER BY aggregate not already
+    // present in the SELECT or HAVING aggregate list must be added to the AggregateNode
+    // so it is computed and available to the post-aggregate sort. An ORDER BY that only
+    // names a SELECT-list alias adds nothing here — the alias resolves through a scope
+    // later — so `hasOrderByOnlyAggregates` stays false for it.
+    const needsPostAggregateSort = orderByNeedsPostAggregateSort(stmt.orderBy, selectContext, selectList);
     let hasOrderByOnlyAggregates = false;
-    if (orderByHasAggregates && (hasAggregates || hasGroupBy)) {
+    if (needsPostAggregateSort && (hasAggregates || hasGroupBy)) {
         const orderByAggs = collectOrderByAggregates(stmt.orderBy, selectContext, aggregates);
         if (orderByAggs.length > 0) {
             aggregates.push(...orderByAggs);
@@ -72,10 +76,10 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // After (optional) early HAVING filter we continue with the existing pipeline
     // ----------------------------------------------------------------------------
     // Handle pre-aggregate sorting for ORDER BY without GROUP BY. Skip when the
-    // ORDER BY contains aggregates — those need to run against the post-aggregate
-    // row(s), not the per-input rows.
-    const preAggregateSort = Boolean(hasAggregates && !hasGroupBy && stmt.orderBy && stmt.orderBy.length > 0 && !orderByHasAggregates);
-    currentInput = handlePreAggregateSort(currentInput, stmt, selectContext, hasAggregates, !!hasGroupBy, orderByHasAggregates, selectList);
+    // ORDER BY names an aggregate or a SELECT-list alias — neither can be evaluated
+    // against the per-input rows; they need the post-aggregate row(s).
+    const preAggregateSort = Boolean(hasAggregates && !hasGroupBy && stmt.orderBy && stmt.orderBy.length > 0 && !needsPostAggregateSort);
+    currentInput = handlePreAggregateSort(currentInput, stmt, selectContext, preAggregateSort, selectList);
     // Build GROUP BY expressions, resolving 1-based positional references against the SELECT list.
     const groupByExpressions = stmt.groupBy ?
         stmt.groupBy.map(expr => buildOrdinalAwareExpression(selectContext, expr, selectList, 'GROUP BY', false)) : [];
@@ -85,8 +89,20 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // Create AggregateNode
     const aggregateNode = new AggregateNode(selectContext.scope, currentInput, groupByExpressions, aggregates);
     currentInput = aggregateNode;
+    // A GROUPED query's post-aggregate expressions — HAVING below, the rebuilt SELECT
+    // list, a window phase's specifications and function arguments, the sort keys —
+    // are all built against scopes that fall through to the pre-aggregate select scope,
+    // so a legal spelling of a grouping key can bind to a base-table attribute the
+    // grouped row does not carry. Every such expression reaches the fix through ONE
+    // entry point, {@link redirectPostAggregate}, off this one context — built here,
+    // the moment the AggregateNode exists, so no post-aggregate site can run before it
+    // does. An aggregate query with no GROUP BY has no grouping keys to redirect onto
+    // and gets none.
+    const groupedRedirectContext = groupByExpressions.length > 0
+        ? buildGroupedRedirectContext(groupByExpressions, aggregateNode.getAttributes(), aggregateNode.getRelations()[0])
+        : undefined;
     // Create aggregate output scope
-    const aggregateOutputScope = createAggregateOutputScope(selectContext.scope, currentInput, groupByExpressions, aggregates);
+    const aggregateOutputScope = createAggregateOutputScope(selectContext.scope, currentInput, groupByExpressions, aggregates, projections);
     // Build the aggregates planning context entries so downstream builders
     // (final projection, ORDER BY) can resolve aggregate function references
     // to ColumnReferenceNodes against the AggregateNode output.
@@ -104,7 +120,7 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // Handle HAVING clause *after* aggregation only when we did not already push
     // it below the AggregateNode.
     if (stmt.having && !shouldPushHavingBelowAggregate) {
-        currentInput = buildHavingFilter(currentInput, stmt.having, selectContext, aggregateOutputScope, aggregates, groupByExpressions);
+        currentInput = buildHavingFilter(currentInput, stmt.having, selectContext, aggregateOutputScope, aggregates, groupByExpressions, groupedRedirectContext);
     }
     // Determine if final projection is needed.
     // Force a final projection when HAVING-only or ORDER-BY-only aggregates were
@@ -134,32 +150,27 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
         groupByExpressions,
         hasHavingOnlyAggregates,
         hasOrderByOnlyAggregates,
-        orderByHasAggregates,
+        orderByNeedsPostAggregateSort: needsPostAggregateSort,
         aggregatesContext,
+        groupedRedirectContext,
     };
 }
 /**
- * Handles pre-aggregate sorting for special cases
+ * Sorts the per-input rows BELOW the AggregateNode when the caller decided this
+ * query takes the pre-aggregate sort (see the `preAggregateSort` computation in
+ * {@link buildAggregatePhase}); otherwise passes `input` through untouched.
  */
-function handlePreAggregateSort(input, stmt, selectContext, hasAggregates, hasGroupBy, orderByHasAggregates, selectList) {
-    // Special handling for ORDER BY with aggregates but no GROUP BY.
-    // Skip when ORDER BY itself references aggregates — those must run
-    // post-aggregation, not on the per-row input.
-    if (hasAggregates && !hasGroupBy && stmt.orderBy && stmt.orderBy.length > 0 && !orderByHasAggregates) {
-        // Apply ORDER BY before aggregation. This sort sits BELOW the AggregateNode,
-        // so a positional reference resolves through the select list (no output
-        // attributes exist yet to bind to).
-        const sortKeys = stmt.orderBy.map(orderByClause => {
-            const expression = buildOrdinalAwareExpression(selectContext, orderByClause.expr, selectList, 'ORDER BY');
-            return {
-                expression,
-                direction: orderByClause.direction,
-                nulls: orderByClause.nulls
-            };
-        });
-        return new SortNode(selectContext.scope, input, sortKeys);
-    }
-    return input;
+function handlePreAggregateSort(input, stmt, selectContext, preAggregateSort, selectList) {
+    if (!preAggregateSort)
+        return input;
+    // This sort sits BELOW the AggregateNode, so a positional reference resolves
+    // through the select list (no output attributes exist yet to bind to).
+    const sortKeys = stmt.orderBy.map(orderByClause => ({
+        expression: buildOrdinalAwareExpression(selectContext, orderByClause.expr, selectList, 'ORDER BY'),
+        direction: orderByClause.direction,
+        nulls: orderByClause.nulls
+    }));
+    return new SortNode(selectContext.scope, input, sortKeys);
 }
 /**
  * Builds the coverage test for a grouped query. `groupedOutputAttributes` is the
@@ -167,7 +178,7 @@ function handlePreAggregateSort(input, stmt, selectContext, hasAggregates, hasGr
  * needed only when the expressions to be checked were built against the aggregate
  * output scope.
  */
-export function buildGroupByCoverage(groupByExpressions, groupedOutputAttributes = []) {
+function buildGroupByCoverage(groupByExpressions, groupedOutputAttributes = []) {
     const attrIds = new Set();
     const fingerprints = new Set();
     for (const expr of groupByExpressions) {
@@ -183,10 +194,10 @@ export function buildGroupByCoverage(groupByExpressions, groupedOutputAttributes
 }
 /**
  * Raises the standard GROUP BY coverage error when `node` reads a column the
- * grouped rows do not carry. Used by the SELECT-list check below; the window
- * phase raises the same message from {@link assertGroupedWindowCoverage}.
+ * grouped rows do not carry. Used by the SELECT-list check below; the finished-plan
+ * check raises the same message from {@link assertGroupedPlanCoverage}.
  */
-export function assertGroupByCoverage(node, coverage) {
+function assertGroupByCoverage(node, coverage) {
     const ungrouped = findUngroupedColumnRef(node, coverage);
     if (!ungrouped)
         return;
@@ -197,7 +208,7 @@ export function assertGroupByCoverage(node, coverage) {
  * column index is the key's position in that list, which is its position on the
  * AggregateNode's output row.
  */
-export function indexGroupKeys(groupByExpressions) {
+function indexGroupKeys(groupByExpressions) {
     const byFingerprint = new Map();
     const byBaseAttrId = new Map();
     groupByExpressions.forEach((expr, index) => {
@@ -213,13 +224,13 @@ export function indexGroupKeys(groupByExpressions) {
     return { byFingerprint, byBaseAttrId };
 }
 /**
- * Builds the {@link GroupedWindowContext} for a grouped, windowed query.
+ * Builds the {@link GroupedRedirectContext} for a grouped query.
  * `outputAttributes` is the AggregateNode's attribute list (group keys in GROUP BY
  * order, then the aggregate results); `aggregateInput` is the AggregateNode's
  * source relation, whose whole subtree defines
- * {@link GroupedWindowContext.aggregateInputAttrIds}.
+ * {@link GroupedRedirectContext.aggregateInputAttrIds}.
  */
-export function buildGroupedWindowContext(groupByExpressions, outputAttributes, aggregateInput) {
+function buildGroupedRedirectContext(groupByExpressions, outputAttributes, aggregateInput) {
     return {
         groupKeys: indexGroupKeys(groupByExpressions),
         outputAttributes,
@@ -250,10 +261,35 @@ function isCteDefinition(node) {
     return node.nodeType === PlanNodeType.CTE || node.nodeType === PlanNodeType.RecursiveCTE;
 }
 /**
- * Rewrites every subtree of a window specification / window-function argument that
- * IS a grouping key into a reference to the AggregateNode's output column for that
- * key, so the expression reads the grouped row instead of a base-table column that
- * row does not carry.
+ * The ONE entry point through which every post-aggregate expression of a GROUPED
+ * query reaches the grouping-key redirect: the rebuilt SELECT list, the window
+ * phase's specifications and function arguments, the HAVING predicate, and every
+ * post-aggregate sort key. A builder that constructs an expression above the
+ * AggregateNode calls this rather than remembering the rewrite itself — forgetting
+ * is how the SELECT-list and ORDER BY bugs shipped
+ * (complete/bug-qualified-group-key-in-select-list-breaks-window-query,
+ * complete/bug-order-by-grouping-key-spelling-breaks-window-query).
+ *
+ * A pass-through when `context` is absent (the query has no GROUP BY keys), and when
+ * the expression contains nothing to redirect. That gate is load-bearing, not an
+ * optimization: {@link redirectToGroupKeys} matches a subtree by AST text, so under
+ * `group by a` an ungated pass would also fingerprint a plain `order by a` that
+ * already bound correctly to a projection/window/aggregate OUTPUT attribute — the
+ * clearest hazard being an alias that shadows a grouping key (`select upper(a) as a …
+ * group by a order by a` must sort by the projected `upper(a)`). Only an expression
+ * that actually fell through to a pre-grouping attribute has anything to fix, and
+ * only such an expression is walked.
+ */
+export function redirectPostAggregate(expr, context, scope) {
+    if (!context || !referencesAggregateInput(expr, context))
+        return expr;
+    return redirectToGroupKeys(expr, context, scope);
+}
+/**
+ * Rewrites every subtree of a post-aggregate expression that IS a grouping key into
+ * a reference to the AggregateNode's output column for that key, so the expression
+ * reads the grouped row instead of a base-table column that row does not carry.
+ * Reached only through {@link redirectPostAggregate}.
  *
  * Two match rules, in order at each node:
  *
@@ -294,7 +330,7 @@ function isCteDefinition(node) {
  * fixing it means comparing resolved attribute identity rather than text, for both
  * callers at once.
  */
-export function redirectToGroupKeys(node, context, scope) {
+function redirectToGroupKeys(node, context, scope) {
     return redirectNode(node, context, scope);
 }
 /**
@@ -306,12 +342,24 @@ export function redirectToGroupKeys(node, context, scope) {
  *
  * NOTE: this renders an identity fingerprint at every scalar node it visits, and a
  * fingerprint hit inside a subquery then walks that node's subtree again for the guard
- * — so a window specification containing a large subquery costs more to build than
- * before, once per prepare of the query. Not measured; if preparing such queries ever
- * shows up as slow, memoize the fingerprint per node or bail out of the walk for
- * subtrees that contain no `aggregateInputAttrIds` reference at all.
+ * — so every grouped query pays a walk of its whole SELECT list, plus its window
+ * specifications when it has them, once per prepare. Not measured; if preparing grouped
+ * queries ever shows up as slow, memoize the fingerprint per node or bail out of the
+ * walk for subtrees that contain no `aggregateInputAttrIds` reference at all.
+ *
+ * NOTE: the SELECT-list caller hands us its window-function subtrees too, and the window
+ * phase then throws each of them away — `rewriteWindowFunctions` (select-window.ts)
+ * replaces the whole node with a column reference to the WindowNode's output, looked up
+ * by the `AST.WindowFunctionExpr`'s object identity. A `WindowFunctionCallNode` is
+ * zero-ary, so this walk could never rebuild one anyway — but it is skipped explicitly
+ * below so that lookup's key can never be disturbed and rule 1 can never fingerprint a
+ * window function itself. The window phase redirects its specification expressions
+ * itself and never passes one in.
  */
 function redirectNode(node, context, scope, insideSubquery = false) {
+    if (CapabilityDetectors.isWindowFunction(node)) {
+        return node;
+    }
     if ('expression' in node) {
         const expression = node.expression;
         const fingerprintIndex = context.groupKeys.byFingerprint.get(expressionToIdentityString(expression));
@@ -358,12 +406,96 @@ function readsOnlyAggregateInput(node, context) {
     return true;
 }
 /**
- * Raises the GROUP BY coverage error for a window specification / window-function
- * argument of a GROUPED query that still reads a pre-grouping column after
- * {@link redirectToGroupKeys} has run.
+ * True when `node` names one of THIS query's pre-grouping columns and the AggregateNode's
+ * output row does not carry it — the exact condition that makes a reference above the
+ * aggregate either redirectable ({@link referencesAggregateInput}) or, once the redirect
+ * has run, an ungrouped column ({@link findUngroupedPostAggregateRef}). The two callers ask
+ * it of different subtrees for different purposes, but the predicate is one thing and must
+ * stay one thing: a reference the redirect rewrites is by definition one the coverage check
+ * would otherwise have rejected.
+ */
+function isPreGroupingReference(node, context) {
+    const attrId = node.attributeId;
+    return context.aggregateInputAttrIds.has(attrId) && !context.outputAttrIds.has(attrId);
+}
+/**
+ * True when ANY column reference in `node`'s subtree is a pre-grouping column of this
+ * query — i.e. the expression reads something the AggregateNode's output row does not
+ * carry, and therefore needs {@link redirectToGroupKeys} run over it.
+ *
+ * The opposite question to its neighbour {@link readsOnlyAggregateInput} ("does the
+ * WHOLE subtree belong to this query's pre-grouping input", which guards a fingerprint
+ * match from hijacking a subquery's own identically-spelled column). This one is
+ * {@link redirectPostAggregate}'s *gate*: it answers "is there anything here to
+ * redirect at all". A subtree whose references all resolved through the projection /
+ * window-output / aggregate-output scopes contains none, and must be left alone.
+ *
+ * Per reference the test is {@link isPreGroupingReference}. CTE definition bodies are
+ * skipped for the same reason {@link redirectToGroupKeys} skips them (see
+ * {@link isCteDefinition}).
+ */
+function referencesAggregateInput(node, context) {
+    if (CapabilityDetectors.isColumnReference(node)) {
+        return isPreGroupingReference(node, context);
+    }
+    for (const child of node.getChildren()) {
+        if (isCteDefinition(child))
+            continue;
+        if (referencesAggregateInput(child, context))
+            return true;
+    }
+    return false;
+}
+/**
+ * Boundary check over a GROUPED query's finished plan: no node ABOVE the
+ * AggregateNode may reference an aggregate-input attribute id that is absent from
+ * the aggregate's output. Called once per grouped query, from the end of
+ * `buildSelectStmt`, walking the operator spine from the query root down to — and
+ * stopping at — the AggregateNode itself (whose own input subtree legally reads
+ * pre-grouping columns). Each scalar expression hanging off a spine operator gets
+ * the subquery-aware per-expression check ({@link assertPostAggregateCoverage}).
+ *
+ * This is what turns "a builder forgot to call {@link redirectPostAggregate}" from a
+ * runtime `No row context found for column …` internal error into the user-facing
+ * GROUP BY message at plan time — the SELECT-list and ORDER BY escapes both shipped
+ * exactly that way. It also rejects, at plan time, a post-aggregate expression that
+ * genuinely reads an ungrouped column (directly, or correlated through a subquery).
+ *
+ * NOTE: the stop condition is node IDENTITY, so it holds only while `buildSelectStmt`
+ * *wraps* the aggregate rather than rebuilding it. A future post-aggregate step that
+ * rebuilds the spine through `withChildren` would mint a new AggregateNode, the walk
+ * would run straight past it into the aggregate's own input, and every legal
+ * pre-grouping reference down there (a WHERE conjunct, a join condition) would be
+ * rejected with a user-facing GROUP BY error. If such a step is ever added, locate
+ * the aggregate by node id instead of by reference.
+ *
+ * NOTE: one extra walk of the post-aggregate plan per grouped query per prepare, on
+ * top of the redirect's own walk (see {@link redirectNode}). Measured end-to-end, not
+ * isolated: compiling a six-column grouped query costs ~0.6-0.8 ms against ~0.5 ms for
+ * a comparable ungrouped one, so this walk is bounded well below the surrounding
+ * planning cost. Revisit if preparing grouped queries ever shows up as slow.
+ */
+export function assertGroupedPlanCoverage(node, aggregateNode, context) {
+    if (node === aggregateNode)
+        return;
+    for (const child of node.getChildren()) {
+        if (child === aggregateNode || isCteDefinition(child))
+            continue;
+        if (isRelationalNode(child)) {
+            assertGroupedPlanCoverage(child, aggregateNode, context);
+        }
+        else {
+            assertPostAggregateCoverage(child, context);
+        }
+    }
+}
+/**
+ * Raises the GROUP BY coverage error for a post-aggregate expression of a GROUPED
+ * query that still reads a pre-grouping column after {@link redirectPostAggregate}
+ * has run.
  *
  * Distinct from {@link assertGroupByCoverage} in exactly two ways, both required by
- * the fact that a window expression may contain a subquery:
+ * the fact that a post-aggregate expression may contain a subquery:
  *
  * - it descends into relational children, so a correlated reference buried in a
  *   subquery is checked rather than skipped;
@@ -372,10 +504,10 @@ function readsOnlyAggregateInput(node, context) {
  *   or a correlated reference to an enclosing query — is legal here and is left alone.
  *
  * The aggregate exemption is likewise narrowed to this query's OWN aggregates; see
- * {@link findUngroupedWindowColumnRef}.
+ * {@link findUngroupedPostAggregateRef}.
  */
-export function assertGroupedWindowCoverage(node, context) {
-    const ungrouped = findUngroupedWindowColumnRef(node, context);
+function assertPostAggregateCoverage(node, context) {
+    const ungrouped = findUngroupedPostAggregateRef(node, context);
     if (!ungrouped)
         return;
     throw new QuereusError(`Column '${expressionToString(ungrouped.expression)}' must appear in the GROUP BY clause or be used in an aggregate function`, StatusCode.ERROR, undefined, ungrouped.expression.loc?.start.line, ungrouped.expression.loc?.start.column);
@@ -391,19 +523,17 @@ export function assertGroupedWindowCoverage(node, context) {
  * (select max(wg.b) from wg t))` reads an ungrouped column of this query and must say
  * so at plan time, not die at runtime with "No row context found for column b".
  */
-function findUngroupedWindowColumnRef(node, context, insideSubquery = false) {
+function findUngroupedPostAggregateRef(node, context, insideSubquery = false) {
     if (!insideSubquery && CapabilityDetectors.isAggregateFunction(node)) {
         return null;
     }
     if (CapabilityDetectors.isColumnReference(node)) {
-        const attrId = node.attributeId;
-        const ungrouped = context.aggregateInputAttrIds.has(attrId) && !context.outputAttrIds.has(attrId);
-        return ungrouped ? node : null;
+        return isPreGroupingReference(node, context) ? node : null;
     }
     for (const child of node.getChildren()) {
         if (isCteDefinition(child))
             continue;
-        const found = findUngroupedWindowColumnRef(child, context, insideSubquery || isRelationalNode(child));
+        const found = findUngroupedPostAggregateRef(child, context, insideSubquery || isRelationalNode(child));
         if (found)
             return found;
     }
@@ -438,6 +568,14 @@ function validateAggregateProjections(projections, hasAggregates, hasGroupBy, gr
  * subtree (inner column refs are aggregated), a relational subtree (subqueries
  * resolve their own scope), or any subtree whose AST fingerprint matches a GROUP BY
  * expression (the whole subtree is grouped, e.g. SELECT id+1 ... GROUP BY id+1).
+ *
+ * Not descending into relational children means a correlated subquery in a grouped
+ * SELECT list that reads a genuinely UNGROUPED column of this query
+ * (`select a, (select count(*) from wg t where t.b = wg.b) … group by a`) is not
+ * rejected here. That is fine: the finished-plan check
+ * ({@link assertGroupedPlanCoverage}) IS subquery-aware — it can tell a correlated
+ * reference to THIS query from the subquery's own columns, off
+ * {@link GroupedRedirectContext} — and rejects it at plan time with the same message.
  */
 function findUngroupedColumnRef(node, coverage) {
     if (CapabilityDetectors.isAggregateFunction(node)) {
@@ -465,9 +603,40 @@ function findUngroupedColumnRef(node, coverage) {
     return null;
 }
 /**
- * Creates a scope that includes the aggregate output columns
+ * The names a grouped query's OUTPUT row can be referred to by, as a scope. This is
+ * what a HAVING predicate and (for a grouped, windowed query) a window specification
+ * resolve against, so everything registered here is a name those clauses may use:
+ *
+ * - each GROUP BY key under its own column name, plus its qualified name when the key
+ *   was written qualified (`group by i.id, c.id` registers `i.id` and `c.id`; the bare
+ *   `id` they share becomes ambiguous);
+ * - each aggregate under its SELECT-list alias;
+ * - each grouping key ALSO under the SELECT-list alias of the column that selects it —
+ *   `select a as k … group by a` makes `k` name the group key, in `over (order by k)`
+ *   and in `HAVING` alike. Bare, qualified and computed keys all qualify
+ *   (`select upper(a) as k … group by upper(a)`). This is SQLite-style permissiveness
+ *   rather than strict SQL, and it matches how an aggregate's alias already behaves.
+ *
+ * A registered name SHADOWS a same-named base-table column, because anything not
+ * registered here falls through to the pre-aggregate select scope (window specs) or to
+ * the source-column fallback in {@link buildHavingFilter} (HAVING). So under
+ * `select a as b … group by a`, a bare `b` in either clause is the group key, not the
+ * table's own `b` column. Deliberate, and the same rule aggregate aliases already had.
+ *
+ * NOTE: a select-list alias is the LOWEST-precedence name here — it is skipped when a
+ * grouping key's own name or an aggregate's alias already claims it. `select a as b,
+ * b, count(*) … group by a, b` therefore keeps resolving a bare `b` to the grouping
+ * key `b`, matching both SQLite and PostgreSQL (where an alias never outranks a real
+ * column outside ORDER BY). Marking such a collision ambiguous instead was considered
+ * and rejected: the grouped SELECT list is itself rebuilt against this scope by
+ * {@link buildFinalAggregateProjections}, so an ambiguity minted here would reject the
+ * bare `b` in the select list too — and a select-list column must never be affected by
+ * a sibling's alias. Revisit only if select-list rebuilding stops going through this
+ * scope.
  */
-function createAggregateOutputScope(parentScope, aggregateNode, groupByExpressions, aggregates) {
+function createAggregateOutputScope(parentScope, aggregateNode, groupByExpressions, aggregates, 
+/** Non-aggregate SELECT-list columns (stars expanded), each carrying its alias. */
+projections) {
     const aggregateOutputScope = new RegisteredScope(parentScope);
     const aggregateAttributes = aggregateNode.getAttributes();
     // Mirror the source-side (FROM/JOIN) naming semantics: a qualified reference
@@ -553,6 +722,32 @@ function createAggregateOutputScope(parentScope, aggregateNode, groupByExpressio
             aggregateOutputScope.registerSymbol(aliasKey, (exp, s) => new ColumnReferenceNode(s, exp, agg.expression.getType(), attr.id, columnIndex));
         }
     });
+    // Register each grouping key under the SELECT-list alias of the column that selects
+    // it, so `select a as k … group by a` can say `k` in HAVING and in a window
+    // specification. Skipped for any alias a grouping key's own name or an aggregate
+    // alias already claims (see the NOTE above), and marked ambiguous when two aliases
+    // of DIFFERENT grouping keys share one name (`select a as k, b as k … group by a, b`),
+    // which nothing else in this scope can arbitrate.
+    //
+    // The qualified keys count as "already claims" too: a quoted alias may contain a dot
+    // (`select wg.a as "wg.a" … group by wg.a`), and registering it would re-register a
+    // key this scope already holds — which `registerSymbol` rejects outright, failing a
+    // query that plans fine without the alias. See
+    // backlog/bug-scope-symbol-keys-collide-with-dotted-column-names for why a flat
+    // string key cannot tell a dotted name from a qualified one in the first place.
+    const groupKeys = indexGroupKeys(groupByExpressions);
+    for (const [aliasKey, keyIndexes] of collectAliasedGroupKeys(projections, groupKeys)) {
+        if (bareNameOwners.has(aliasKey) || registeredQualifiedKeys.has(aliasKey))
+            continue;
+        if (keyIndexes.size > 1) {
+            aggregateOutputScope.markAmbiguous(aliasKey);
+            continue;
+        }
+        const [index] = keyIndexes;
+        const attr = aggregateAttributes[index];
+        const keyExpr = groupByExpressions[index];
+        aggregateOutputScope.registerSymbol(aliasKey, (exp, s) => new ColumnReferenceNode(s, exp, keyExpr.getType(), attr.id, index));
+    }
     // Note: the aggregate node advertises exactly its GROUP BY + aggregate columns.
     // Source columns for HAVING / correlated access are resolved through the runtime
     // row-descriptor context and the source-column fallback in buildHavingFilter's
@@ -560,9 +755,62 @@ function createAggregateOutputScope(parentScope, aggregateNode, groupByExpressio
     return aggregateOutputScope;
 }
 /**
- * Builds HAVING filter clause
+ * Every SELECT-list alias that names a grouping key, mapped to the GROUP BY position(s)
+ * it could mean. More than one position means two aliases of different keys collide on
+ * one name.
+ *
+ * A projection is matched to its key the same two ways {@link redirectToGroupKeys}
+ * matches a window expression: by base attribute id for a column reference (so
+ * `select wg.a as k … group by a` and the reverse both land), else by identity
+ * fingerprint of the whole expression (so `select upper(a) as k … group by upper(a)`
+ * lands). A projection matching no key is skipped — in a grouped query it is an
+ * ungrouped SELECT column, which `validateAggregateProjections` has already rejected.
+ *
+ * Aliases are keyed lowercased, matching every other name in the aggregate output scope.
+ * Note that an unaliased `select a` carries no alias and contributes nothing, while a
+ * star-expanded column carries the source column's name as its alias — which for a
+ * grouping key is the name that key already registers, so it costs nothing.
  */
-function buildHavingFilter(input, havingClause, selectContext, aggregateOutputScope, aggregates, groupByExpressions) {
+function collectAliasedGroupKeys(projections, groupKeys) {
+    const aliasTargets = new Map();
+    for (const projection of projections) {
+        if (!projection.alias)
+            continue;
+        const index = groupKeyIndexOf(projection.node, groupKeys);
+        if (index === undefined)
+            continue;
+        const aliasKey = projection.alias.toLowerCase();
+        let targets = aliasTargets.get(aliasKey);
+        if (!targets) {
+            targets = new Set();
+            aliasTargets.set(aliasKey, targets);
+        }
+        targets.add(index);
+    }
+    return aliasTargets;
+}
+/** Which GROUP BY key this SELECT-list expression IS, if any. */
+function groupKeyIndexOf(node, groupKeys) {
+    if (CapabilityDetectors.isColumnReference(node)) {
+        const byAttrId = groupKeys.byBaseAttrId.get(node.attributeId);
+        if (byAttrId !== undefined)
+            return byAttrId;
+    }
+    return groupKeys.byFingerprint.get(expressionToIdentityString(node.expression));
+}
+/**
+ * Builds HAVING filter clause.
+ *
+ * `groupedRedirectContext` is supplied for a GROUPED query. A HAVING reference to a
+ * grouping key under a spelling the hybrid scope does not hold (`having wg.a = 'x'`
+ * against `group by a`, the key nested in `upper(wg.a)`, a computed key written out
+ * again) falls through to a base-table attribute, which happened to read correctly
+ * only because this FilterNode sits directly on the AggregateNode's yield where the
+ * representative source row is still published. {@link redirectPostAggregate} lands
+ * it on the aggregate's own output column instead, so the predicate stays correct
+ * wherever the filter ends up relative to a buffering operator.
+ */
+function buildHavingFilter(input, havingClause, selectContext, aggregateOutputScope, aggregates, groupByExpressions, groupedRedirectContext) {
     const aggregateAttributes = input.getAttributes();
     // Create a hybrid scope that first tries the aggregate output scope,
     // then falls back to the original source scope for column resolution.
@@ -605,7 +853,7 @@ function buildHavingFilter(input, havingClause, selectContext, aggregateOutputSc
             };
         })
     };
-    const havingExpression = buildExpression(havingContext, havingClause, true);
+    const havingExpression = redirectPostAggregate(buildExpression(havingContext, havingClause, true), groupedRedirectContext, hybridScope);
     // Reject HAVING references to non-grouped, non-aggregated columns.
     // With GROUP BY: only GROUP BY columns/expressions and aggregates are allowed.
     // Without GROUP BY (implicit single group, only reachable here when aggregates
@@ -825,23 +1073,74 @@ function collectOrderByAggregates(orderBy, selectContext, existingAggregates) {
     return dedupeNewAggregates(funcExprs, selectContext, existingAggregates);
 }
 /**
- * Returns true if any ORDER BY clause expression contains an aggregate function call.
+ * Decides whether an ungrouped aggregate query's ORDER BY must be sorted ABOVE the
+ * AggregateNode rather than below it (the pre-aggregate sort extension, which is what
+ * makes `select group_concat(b) from t order by a` concatenate in `a` order).
+ *
+ * Three spellings need the post-aggregate placement, because none of them can be
+ * evaluated against the per-input rows the pre-aggregate sort sees:
+ *
+ * - a spelled-out aggregate call (`order by count(*)`);
+ * - a positional reference standing for one — the literal `1` in `select count(*) as c
+ *   from t order by 1` contains no aggregate itself, so it is resolved against the
+ *   SELECT list FIRST. Without that the query fails with "Aggregate function count not
+ *   allowed in this context";
+ * - a bare (unqualified) column name that is a SELECT-list alias (`select count(*) as c
+ *   from t order by c`). The alias only ever exists in the aggregate/projection output
+ *   scope, so a pre-aggregate sort fails with "Column not found: c".
  *
- * A positional reference is resolved against the SELECT list FIRST: the literal `1`
- * in `select count(*) as c from t order by 1` contains no aggregate itself, but it
- * stands for one. Without this the query would take the pre-aggregate sort path and
- * fail with "Aggregate function count not allowed in this context"; with it, it
- * routes to the post-aggregate ORDER BY exactly like the spelled-out
- * `order by count(*)`.
+ * The alias arm makes a select-list alias outrank a same-named source column in an
+ * aggregate ORDER BY, matching SQLite and what the non-aggregate and grouped paths
+ * already do. Qualified names (`order by t.c`) are excluded and keep resolving to the
+ * table's column.
  */
-function orderByContainsAggregates(orderBy, selectContext, selectList) {
+function orderByNeedsPostAggregateSort(orderBy, selectContext, selectList) {
     if (!orderBy || orderBy.length === 0)
         return false;
+    const aliases = selectListAliases(selectList);
     return orderBy.some(clause => {
         const entry = resolveOrdinalReference(clause.expr, selectList, 'ORDER BY');
-        return containsAggregateFunction(entry?.expr ?? clause.expr, selectContext);
+        if (containsAggregateFunction(entry?.expr ?? clause.expr, selectContext))
+            return true;
+        return mentionsSelectListAlias(clause.expr, aliases);
     });
 }
+/** Lower-cased set of the `as` aliases the SELECT list wrote (stars contribute none). */
+function selectListAliases(selectList) {
+    const aliases = new Set();
+    for (const entry of selectList) {
+        if (entry.alias)
+            aliases.add(entry.alias.toLowerCase());
+    }
+    return aliases;
+}
+/**
+ * True when `expr` mentions any of `aliases` as an unqualified column reference.
+ *
+ * NOTE: `walkAstNodes` descends into subquery operands, so `order by (select … where x
+ * = c)` counts as mentioning `c` even when that `c` is the subquery's own column. The
+ * over-approximation only costs the pre-aggregate ordering extension on a one-row
+ * result; a subquery-aware walk is not worth hand-rolling for it.
+ *
+ * `type: 'column'` is not unique to {@link AST.ColumnExpr}: a subquery's SELECT-list
+ * {@link AST.ResultColumnExpr} carries the same tag with an `expr`/`alias` shape and no
+ * `name`, and the reflective walk reaches those too. Match on the `name` string rather
+ * than on the tag alone.
+ */
+function mentionsSelectListAlias(expr, aliases) {
+    if (aliases.size === 0)
+        return false;
+    for (const node of walkAstNodes(expr)) {
+        if (node.type !== 'column')
+            continue;
+        const col = node;
+        if (typeof col.name !== 'string' || col.table)
+            continue;
+        if (aliases.has(col.name.toLowerCase()))
+            return true;
+    }
+    return false;
+}
 /**
  * Given a list of aggregate function call AST nodes, builds aggregate plan nodes
  * for the entries that are not already present in `existingAggregates` (matched by
@@ -871,9 +1170,15 @@ function dedupeNewAggregates(funcExprs, selectContext, existingAggregates) {
     return newAggregates;
 }
 /**
- * Builds final projections for the complete SELECT list in aggregate context
+ * Builds final projections for the complete SELECT list in aggregate context.
+ *
+ * `groupedContext` is supplied whenever the query HAS a GROUP BY (it is `undefined`
+ * for an aggregate query without one, which has no grouping keys to redirect onto).
+ * It is what makes a select-list reference to a grouping key name the AggregateNode's
+ * OWN group output column, whatever spelling the reference used — see
+ * {@link redirectPostAggregate} and the note on the rebuild below.
  */
-export function buildFinalAggregateProjections(stmt, selectContext, aggregateOutputScope, aggregateNode, aggregates, groupByExpressions, starProjectionsByColumn = new Map()) {
+export function buildFinalAggregateProjections(stmt, selectContext, aggregateOutputScope, aggregateNode, aggregates, groupByExpressions, starProjectionsByColumn = new Map(), groupedContext) {
     const finalProjections = [];
     const aggregateAttributes = aggregateNode.getAttributes();
     // Build context with aggregates so buildFunctionCall can resolve aggregate references
@@ -902,7 +1207,11 @@ export function buildFinalAggregateProjections(stmt, selectContext, aggregateOut
     // The same index also maps bare source columns that are themselves group keys
     // straight to the aggregate's group output column, which is what expands
     // `SELECT *` in a grouped query in source-column order rather than GROUP BY order.
-    const groupKeys = indexGroupKeys(groupByExpressions);
+    //
+    // A grouped query's `groupedContext` already carries this index; deriving it twice
+    // for one query is how the two copies drift. Only an aggregate query with no GROUP BY
+    // reaches the fallback, and its `groupByExpressions` is empty.
+    const groupKeys = groupedContext?.groupKeys ?? indexGroupKeys(groupByExpressions);
     for (const column of stmt.columns) {
         if (column.type === 'all') {
             for (const starProj of starProjectionsByColumn.get(column) ?? []) {
@@ -944,7 +1253,22 @@ export function buildFinalAggregateProjections(stmt, selectContext, aggregateOut
                 scope: aggregateOutputScope,
                 aggregates: aggregatesContext
             };
-            const scalarNode = buildExpression(finalContext, column.expr, true);
+            const builtNode = buildExpression(finalContext, column.expr, true);
+            // `aggregateOutputScope` holds a grouping key only under the names the query
+            // literally wrote, so every other legal spelling — a qualifier the GROUP BY did
+            // not use (`select wg.a … group by a`), a FROM-alias qualifier, a key nested in
+            // a bigger expression (`upper(wg.a)`) — falls through to the pre-aggregate
+            // scope and binds to a BASE-TABLE attribute the grouped row does not carry.
+            // Redirect each such subtree onto the aggregate's own group output column,
+            // exactly as the window phase does for a window specification.
+            //
+            // For EVERY grouped query, not only windowed ones: reading the base attribute
+            // off the group's representative source row is right only while this projection
+            // is the aggregate's adjacent consumer, and a WindowNode buffering in between
+            // removes that (docs/runtime.md § Corollary: a published source row reaches only
+            // the adjacent consumer). One query shape must not bind two ways depending on
+            // an unrelated clause.
+            const scalarNode = redirectPostAggregate(builtNode, groupedContext, aggregateOutputScope);
             let attrId = undefined;
             if (CapabilityDetectors.isColumnReference(scalarNode)) {
                 attrId = scalarNode.attributeId;