@quereus/quereus 4.5.0 → 4.7.0

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

@@ -11,12 +11,14 @@ import { StatusCode } from '../../common/types.js';
 import { CapabilityDetectors } from '../framework/characteristics.js';
 import { resolveFunctionSchema } from './schema-resolution.js';
 import { isAggregateFunctionSchema } from '../../schema/function.js';
-import { expressionToString } from '../../emit/ast-stringify.js';
-import { resolveOrdinalReference } from './select-ordinal.js';
+import { expressionToString, expressionToIdentityString } from '../../emit/ast-stringify.js';
+import { buildOrdinalAwareExpression, resolveOrdinalReference } from './select-ordinal.js';
+import { collectDefinedAttrIds } from '../analysis/equi-correlation.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
 /**
  * Processes GROUP BY, aggregates, and HAVING clauses
  */
-export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasAggregates, projections, hasWrappedAggregates = false, selectListAsts = []) {
+export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasAggregates, projections, hasWrappedAggregates = false, selectList = [], starProjectionsByColumn = new Map()) {
     const hasGroupBy = stmt.groupBy && stmt.groupBy.length > 0;
     // Pre-collect aggregate functions from the HAVING clause that are not already
     // present in the SELECT list. These need to be added to the AggregateNode so
@@ -35,7 +37,7 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // 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);
+    const orderByHasAggregates = orderByContainsAggregates(stmt.orderBy, selectContext, selectList);
     let hasOrderByOnlyAggregates = false;
     if (orderByHasAggregates && (hasAggregates || hasGroupBy)) {
         const orderByAggs = collectOrderByAggregates(stmt.orderBy, selectContext, aggregates);
@@ -73,13 +75,10 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // 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, selectListAsts);
+    currentInput = handlePreAggregateSort(currentInput, stmt, selectContext, hasAggregates, !!hasGroupBy, orderByHasAggregates, selectList);
     // Build GROUP BY expressions, resolving 1-based positional references against the SELECT list.
     const groupByExpressions = stmt.groupBy ?
-        stmt.groupBy.map(expr => {
-            const resolved = resolveOrdinalReference(expr, selectListAsts, 'GROUP BY');
-            return buildExpression(selectContext, resolved ?? expr, false);
-        }) : [];
+        stmt.groupBy.map(expr => buildOrdinalAwareExpression(selectContext, expr, selectList, 'GROUP BY', false)) : [];
     // Validate aggregate/non-aggregate mixing (must run after groupByExpressions are built
     // so we can check column-coverage of SELECT projections against GROUP BY)
     validateAggregateProjections(projections, hasAggregates, !!hasGroupBy, groupByExpressions);
@@ -110,7 +109,22 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
     // Determine if final projection is needed.
     // Force a final projection when HAVING-only or ORDER-BY-only aggregates were
     // added, to strip them from the output (they exist only for those clauses).
-    const needsFinalProjection = hasHavingOnlyAggregates || hasOrderByOnlyAggregates || hasWrappedAggregates || checkNeedsFinalProjection(projections);
+    const needsFinalProjection = hasHavingOnlyAggregates || hasOrderByOnlyAggregates || hasWrappedAggregates || checkNeedsFinalProjection(projections)
+        // A GROUP BY with no aggregate functions has no other projection step: the
+        // select list must be projected over the AggregateNode output here, or the
+        // output would be the raw group keys in GROUP BY order.
+        // NOTE: the `!hasAggregates` guard is load-bearing. Forcing the projection for
+        // every grouped query changes the plan shape of a grouped materialized-view body
+        // (`select k, count(*), sum(a) … group by k`) and re-routes its incremental
+        // maintenance from residual-recompute to full-rebuild — see
+        // test/incremental/delta-aggregate.spec.ts. So the aggregate case is decided by
+        // exact shape agreement instead (`aggregateOutputIsSelectList` below), which
+        // leaves that body's bare-aggregate plan intact.
+        || Boolean(hasGroupBy && !hasAggregates && projections.length > 0)
+        // With aggregates present the AggregateNode may still be the root of the query.
+        // That is only sound when its own output already IS the select list; otherwise
+        // the grouping keys it advertises leak into (or reorder) the result.
+        || !aggregateOutputIsSelectList(stmt, projections, aggregates, groupByExpressions, starProjectionsByColumn, selectContext);
     return {
         output: currentInput,
         aggregateScope: aggregateOutputScope,
@@ -127,15 +141,16 @@ export function buildAggregatePhase(input, stmt, selectContext, aggregates, hasA
 /**
  * Handles pre-aggregate sorting for special cases
  */
-function handlePreAggregateSort(input, stmt, selectContext, hasAggregates, hasGroupBy, orderByHasAggregates, selectListAsts) {
+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
+        // 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 resolved = resolveOrdinalReference(orderByClause.expr, selectListAsts, 'ORDER BY');
-            const expression = buildExpression(selectContext, resolved ?? orderByClause.expr);
+            const expression = buildOrdinalAwareExpression(selectContext, orderByClause.expr, selectList, 'ORDER BY');
             return {
                 expression,
                 direction: orderByClause.direction,
@@ -146,6 +161,254 @@ function handlePreAggregateSort(input, stmt, selectContext, hasAggregates, hasGr
     }
     return input;
 }
+/**
+ * Builds the coverage test for a grouped query. `groupedOutputAttributes` is the
+ * AggregateNode's output attributes (group keys followed by aggregate results),
+ * needed only when the expressions to be checked were built against the aggregate
+ * output scope.
+ */
+export function buildGroupByCoverage(groupByExpressions, groupedOutputAttributes = []) {
+    const attrIds = new Set();
+    const fingerprints = new Set();
+    for (const expr of groupByExpressions) {
+        if (CapabilityDetectors.isColumnReference(expr)) {
+            attrIds.add(expr.attributeId);
+        }
+        fingerprints.add(expressionToIdentityString(expr.expression));
+    }
+    for (const attr of groupedOutputAttributes) {
+        attrIds.add(attr.id);
+    }
+    return { attrIds, fingerprints };
+}
+/**
+ * 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}.
+ */
+export function assertGroupByCoverage(node, coverage) {
+    const ungrouped = findUngroupedColumnRef(node, coverage);
+    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);
+}
+/**
+ * Builds the {@link GroupKeyIndex} for a grouped query's GROUP BY list. The output
+ * column index is the key's position in that list, which is its position on the
+ * AggregateNode's output row.
+ */
+export function indexGroupKeys(groupByExpressions) {
+    const byFingerprint = new Map();
+    const byBaseAttrId = new Map();
+    groupByExpressions.forEach((expr, index) => {
+        const fp = expressionToIdentityString(expr.expression);
+        if (!byFingerprint.has(fp))
+            byFingerprint.set(fp, index);
+        if (CapabilityDetectors.isColumnReference(expr)) {
+            const attrId = expr.attributeId;
+            if (!byBaseAttrId.has(attrId))
+                byBaseAttrId.set(attrId, index);
+        }
+    });
+    return { byFingerprint, byBaseAttrId };
+}
+/**
+ * Builds the {@link GroupedWindowContext} for a grouped, windowed 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}.
+ */
+export function buildGroupedWindowContext(groupByExpressions, outputAttributes, aggregateInput) {
+    return {
+        groupKeys: indexGroupKeys(groupByExpressions),
+        outputAttributes,
+        aggregateInputAttrIds: collectDefinedAttrIds(aggregateInput, child => !isCteDefinition(child)),
+        outputAttrIds: new Set(outputAttributes.map(attr => attr.id)),
+    };
+}
+/**
+ * True for a CTE *definition* — the node a `with` clause builds once and every
+ * reference to that CTE then points at, as opposed to the per-reference
+ * CTEReferenceNode that mints its own attribute ids.
+ *
+ * Two consequences for the window phase, and one shape that needs both. A CTE body
+ * is a closed scope: it cannot name a column of the query that references it, so
+ * nothing inside it is ever a reference to this query's grouping key. And the SAME
+ * body node is reachable from this query's FROM clause and from a subquery inside a
+ * window specification that references the same CTE, so counting its internal
+ * attribute ids as this query's pre-grouping columns makes the body's own columns
+ * look ungrouped:
+ *
+ *   with c as (select a, b from wg where b <> '')
+ *   select a, row_number() over (order by (select count(*) from c z)) from c group by a
+ *
+ * — which rejected at plan time with "Column 'b' must appear in the GROUP BY clause",
+ * naming a column the user never wrote in the window specification.
+ */
+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.
+ *
+ * Two match rules, in order at each node:
+ *
+ * 1. The whole subtree's identity fingerprint equals a GROUP BY expression's — covers
+ *    `group by a || '!'` + `over (order by a || '!')`, and nested occurrences such
+ *    as `over (order by upper(a || '!'))` because the walk recurses. Identifier case
+ *    is folded, so `group by A || '!'` matches too; quoted literals are byte-exact,
+ *    so `a || 'X'` and `a || 'x'` remain different keys.
+ *
+ *    Unconditional above any subquery, where the expression is written in this query's
+ *    own scope. INSIDE a subquery it is guarded by {@link readsOnlyAggregateInput} —
+ *    every column reference in the subtree must be a pre-grouping column of THIS query
+ *    — because there the same text can name something else entirely: under `group by
+ *    a`, a bare `a` written inside `over (order by (select … where t.a = a))` names the
+ *    subquery's own `t.a` and yet fingerprints as `a`, so an unguarded rule 1 would
+ *    silently rewrite it into the outer group column and change what the query means.
+ *    The guard cannot replace the top-level case: `group by (select max(t.b) from wg t
+ *    where t.a = wg.a)` repeated verbatim in the specification is a legal grouping key
+ *    whose subtree also reads the subquery's own columns.
+ * 2. The node is a column reference whose attribute id is the *base* attribute id of
+ *    a bare-column grouping key — covers `group by a` + `over (order by wg.a)` and
+ *    `over (order by w.a)`. Both spellings fall through to the same base attribute
+ *    the group key was built from, so the match is qualifier-independent. It needs no
+ *    guard at any depth: attribute ids are minted per relation instance, so only a
+ *    reference that genuinely resolves to this query's grouping column can match.
+ *
+ * Otherwise recurse into every child, relational ones included, rebuilding through
+ * `withChildren` — a correlated reference to a grouping key can live arbitrarily deep
+ * inside a subquery in the window specification, and it must be redirected there too
+ * or it reaches the runtime as a base-table attribute the grouped row never carried.
+ *
+ * NOTE: rule 1 matches by AST text, so a subtree that *reads* like a grouping key but
+ * resolves to something else could be redirected wrongly. Within one query the guard
+ * above closes that off; the residue is a subtree of ENCLOSING-query references that
+ * happens to spell a grouping key (`group by a` in an inner query whose window spec
+ * says `outer_alias.a`… only when that fingerprints identically). This is the same
+ * limitation the select list already carries through the shared {@link GroupKeyIndex};
+ * fixing it means comparing resolved attribute identity rather than text, for both
+ * callers at once.
+ */
+export function redirectToGroupKeys(node, context, scope) {
+    return redirectNode(node, context, scope);
+}
+/**
+ * {@link redirectToGroupKeys} over any plan node — the walk crosses relational
+ * boundaries, so it cannot be typed scalar-to-scalar throughout.
+ *
+ * `insideSubquery` records whether the walk has crossed a relational child; it gates
+ * rule 1 (see {@link redirectToGroupKeys}).
+ *
+ * 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.
+ */
+function redirectNode(node, context, scope, insideSubquery = false) {
+    if ('expression' in node) {
+        const expression = node.expression;
+        const fingerprintIndex = context.groupKeys.byFingerprint.get(expressionToIdentityString(expression));
+        if (fingerprintIndex !== undefined && (!insideSubquery || readsOnlyAggregateInput(node, context))) {
+            return buildGroupKeyColumnRef(scope, context.outputAttributes[fingerprintIndex], expression, fingerprintIndex);
+        }
+        if (CapabilityDetectors.isColumnReference(node)) {
+            const baseIndex = context.groupKeys.byBaseAttrId.get(node.attributeId);
+            if (baseIndex !== undefined) {
+                return buildGroupKeyColumnRef(scope, context.outputAttributes[baseIndex], expression, baseIndex);
+            }
+            return node;
+        }
+    }
+    const newChildren = [];
+    let changed = false;
+    for (const child of node.getChildren()) {
+        // A CTE definition holds nothing this walk could legally rewrite, and is shared
+        // with the rest of the plan — descending would fingerprint its whole body for
+        // nothing. See {@link isCteDefinition}.
+        const rewritten = isCteDefinition(child)
+            ? child
+            : redirectNode(child, context, scope, insideSubquery || isRelationalNode(child));
+        if (rewritten !== child)
+            changed = true;
+        newChildren.push(rewritten);
+    }
+    return changed ? node.withChildren(newChildren) : node;
+}
+/**
+ * True when every column reference in `node`'s subtree names a column the grouped
+ * query could have read before it grouped — i.e. the whole subtree belongs to THIS
+ * query rather than to a subquery inside it or to an enclosing query. A subtree with
+ * no column references at all (a constant) trivially qualifies.
+ */
+function readsOnlyAggregateInput(node, context) {
+    if (CapabilityDetectors.isColumnReference(node)) {
+        return context.aggregateInputAttrIds.has(node.attributeId);
+    }
+    for (const child of node.getChildren()) {
+        if (!readsOnlyAggregateInput(child, context))
+            return false;
+    }
+    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.
+ *
+ * Distinct from {@link assertGroupByCoverage} in exactly two ways, both required by
+ * the fact that a window expression may contain a subquery:
+ *
+ * - it descends into relational children, so a correlated reference buried in a
+ *   subquery is checked rather than skipped;
+ * - it flags a column reference only when the attribute id is one of THIS query's
+ *   pre-grouping columns. A reference to anything else — the subquery's own columns,
+ *   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}.
+ */
+export function assertGroupedWindowCoverage(node, context) {
+    const ungrouped = findUngroupedWindowColumnRef(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);
+}
+/**
+ * The first pre-grouping column reference in `node` that the grouped row cannot carry.
+ *
+ * `insideSubquery` tracks whether the walk has crossed into a relational child, and
+ * gates the aggregate exemption. THIS query's own aggregates read pre-grouping columns
+ * by definition (`over (order by count(b) desc)` against a select list that computes
+ * `count(b)`), and those sit at the top level. An aggregate reached through a subquery
+ * belongs to the subquery, and its arguments may correlate back out — `over (order by
+ * (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) {
+    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;
+    }
+    for (const child of node.getChildren()) {
+        if (isCteDefinition(child))
+            continue;
+        const found = findUngroupedWindowColumnRef(child, context, insideSubquery || isRelationalNode(child));
+        if (found)
+            return found;
+    }
+    return null;
+}
 /**
  * Validates that aggregate and non-aggregate projections don't mix inappropriately.
  * With GROUP BY, every non-aggregate column reference in the SELECT list must
@@ -162,19 +425,11 @@ function validateAggregateProjections(projections, hasAggregates, hasGroupBy, gr
     }
     if (!hasGroupBy)
         return;
-    const groupByAttrIds = new Set();
-    const groupByExprFingerprints = new Set();
-    for (const expr of groupByExpressions) {
-        if (CapabilityDetectors.isColumnReference(expr)) {
-            groupByAttrIds.add(expr.attributeId);
-        }
-        groupByExprFingerprints.add(expressionToString(expr.expression));
-    }
+    // The SELECT list is built against the pre-aggregate scope, so no aggregate
+    // output attributes participate.
+    const coverage = buildGroupByCoverage(groupByExpressions);
     for (const proj of projections) {
-        const ungrouped = findUngroupedColumnRef(proj.node, groupByAttrIds, groupByExprFingerprints);
-        if (ungrouped) {
-            throw new QuereusError('Cannot mix aggregate and non-aggregate columns in SELECT list without GROUP BY', StatusCode.ERROR);
-        }
+        assertGroupByCoverage(proj.node, coverage);
     }
 }
 /**
@@ -184,18 +439,18 @@ function validateAggregateProjections(projections, hasAggregates, hasGroupBy, gr
  * 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).
  */
-function findUngroupedColumnRef(node, groupByAttrIds, groupByExprFingerprints) {
+function findUngroupedColumnRef(node, coverage) {
     if (CapabilityDetectors.isAggregateFunction(node)) {
         return null;
     }
     if ('expression' in node) {
-        const fp = expressionToString(node.expression);
-        if (groupByExprFingerprints.has(fp)) {
+        const fp = expressionToIdentityString(node.expression);
+        if (coverage.fingerprints.has(fp)) {
             return null;
         }
     }
     if (CapabilityDetectors.isColumnReference(node)) {
-        if (!groupByAttrIds.has(node.attributeId)) {
+        if (!coverage.attrIds.has(node.attributeId)) {
             return node;
         }
         return null;
@@ -203,7 +458,7 @@ function findUngroupedColumnRef(node, groupByAttrIds, groupByExprFingerprints) {
     for (const child of node.getChildren()) {
         if (isRelationalNode(child))
             continue;
-        const found = findUngroupedColumnRef(child, groupByAttrIds, groupByExprFingerprints);
+        const found = findUngroupedColumnRef(child, coverage);
         if (found)
             return found;
     }
@@ -276,6 +531,16 @@ function createAggregateOutputScope(parentScope, aggregateNode, groupByExpressio
     });
     // Register aggregate columns by their aliases. An alias colliding with a
     // group-key base name (or another alias) is ambiguous as a bare reference.
+    //
+    // NOTE: an un-aliased aggregate's `alias` is its whole rendered expression, and
+    // this key is lowercased — so two aggregates differing only in a quoted literal's
+    // case (`count(nullif(b,'A'))` / `count(nullif(b,'a'))`) register one ambiguous
+    // key here even though they are correctly distinct aggregates. Harmless today:
+    // nothing resolves an aggregate through this scope by its rendered text (HAVING /
+    // ORDER BY / window specs go through `findMatchingAggregate`, which compares
+    // literal-exact identity strings), and only a quoted identifier spelled exactly
+    // like the rendering could reach it. If such a lookup path is ever added, key
+    // these registrations off `expressionToIdentityString` instead of `toLowerCase`.
     aggregates.forEach((agg, index) => {
         const columnIndex = groupByExpressions.length + index;
         const attr = aggregateAttributes[columnIndex];
@@ -350,24 +615,101 @@ function buildHavingFilter(input, havingClause, selectContext, aggregateOutputSc
     // source columns (registered as a fallback) land on source attribute IDs.
     // We accept both flavors of "grouped" attribute, plus any subtree whose AST
     // fingerprint matches a GROUP BY expression.
-    const allowedAttrIds = new Set();
-    const groupByExprFingerprints = new Set();
-    for (const expr of groupByExpressions) {
-        if (CapabilityDetectors.isColumnReference(expr)) {
-            allowedAttrIds.add(expr.attributeId);
-        }
-        groupByExprFingerprints.add(expressionToString(expr.expression));
-    }
-    for (let i = 0; i < groupByExpressions.length + aggregates.length; i++) {
-        allowedAttrIds.add(aggregateAttributes[i].id);
-    }
-    const ungrouped = findUngroupedColumnRef(havingExpression, allowedAttrIds, groupByExprFingerprints);
+    const coverage = buildGroupByCoverage(groupByExpressions, aggregateAttributes.slice(0, groupByExpressions.length + aggregates.length));
+    const ungrouped = findUngroupedColumnRef(havingExpression, coverage);
     if (ungrouped) {
         throw new QuereusError(`HAVING references non-grouped column '${ungrouped.expression.name}'; ` +
             `HAVING may only reference GROUP BY columns or aggregate expressions`, StatusCode.ERROR, undefined, ungrouped.expression.loc?.start.line, ungrouped.expression.loc?.start.column);
     }
     return new FilterNode(hybridScope, input, havingExpression);
 }
+/**
+ * True when the AggregateNode's own output already IS the SELECT list, column for
+ * column — its GROUP BY keys in GROUP BY order, then its aggregate results in
+ * SELECT order, and nothing left over.
+ *
+ * An AggregateNode advertises *every* grouping key it computes, so with no
+ * projection above it the query's declared result shape is the aggregate's shape,
+ * not the select list's. `select count(*) from t group by g` therefore hands back
+ * `g` as well as the count, and `select count(*) c, g from t group by g` hands the
+ * two back in aggregate order rather than select-list order. Only an exact
+ * positional match makes skipping the final projection sound.
+ *
+ * Callers reach this only after the other `needsFinalProjection` terms answered
+ * "no", which means every entry in `projections` is a bare, non-renaming
+ * {@link ColumnReferenceNode}; a group key is matched by attribute id so a
+ * qualified `select t.k … group by k` still counts as agreement.
+ *
+ * The agreement this establishes is a *build-time* one, so an optimizer rule that
+ * reshapes the aggregate must keep it. `rule-groupby-fd-simplification` drops a
+ * functionally-determined group key and re-emits it as a picker `min`, which lands
+ * at a different output position; it caps that rewrite with an order-restoring
+ * `Project` precisely so this build-time agreement still holds at runtime.
+ */
+function aggregateOutputIsSelectList(stmt, projections, aggregates, groupByExpressions, starProjectionsByColumn, selectContext) {
+    // `projections` holds the expanded star columns *and* the non-aggregate SELECT-list
+    // columns. Stars are walked from `starProjectionsByColumn` below, so drop them from
+    // the cursor's list by object identity — that keeps the remaining entries in
+    // SELECT-list order no matter how buildSelectStmt interleaves the two groups
+    // (it assembles them in written select-list order).
+    const starProjections = new Set();
+    for (const expanded of starProjectionsByColumn.values()) {
+        for (const starProjection of expanded)
+            starProjections.add(starProjection);
+    }
+    const nonStarProjections = projections.filter(projection => !starProjections.has(projection));
+    let columnCursor = 0;
+    let aggregateCount = 0;
+    let nextGroupKey = 0;
+    let sawAggregate = false;
+    /** Does this select-list node reference exactly the group key we expect next? */
+    const claimsNextGroupKey = (node) => {
+        const key = groupByExpressions[nextGroupKey];
+        if (!key || sawAggregate)
+            return false;
+        if (!CapabilityDetectors.isColumnReference(node) || !CapabilityDetectors.isColumnReference(key))
+            return false;
+        return node.attributeId === key.attributeId;
+    };
+    for (const column of stmt.columns) {
+        if (column.type === 'all') {
+            for (const starProjection of starProjectionsByColumn.get(column) ?? []) {
+                if (!claimsNextGroupKey(starProjection.node))
+                    return false;
+                nextGroupKey++;
+            }
+            continue;
+        }
+        if (column.type !== 'column')
+            continue;
+        if (containsAggregateFunction(column.expr, selectContext)) {
+            // An aggregate result column claims the next aggregate output slot. Those
+            // slots all follow the group keys, so nothing may claim a key after one.
+            sawAggregate = true;
+            aggregateCount++;
+            continue;
+        }
+        const projection = nonStarProjections[columnCursor++];
+        if (!projection || !claimsNextGroupKey(projection.node))
+            return false;
+        nextGroupKey++;
+    }
+    return nextGroupKey === groupByExpressions.length && aggregateCount === aggregates.length;
+}
+/**
+ * True when a SELECT-list expression contains an aggregate function call.
+ *
+ * NOTE: resolves a function schema per function node while walking, once per prepare
+ * of a grouped query, on top of the walk analyzeSelectColumns already does. Not
+ * measured; if preparing wide grouped select lists ever shows up as slow, have
+ * analyzeSelectColumns publish its per-column aggregate/non-aggregate verdict
+ * instead of re-deriving it here.
+ */
+function containsAggregateFunction(expr, selectContext) {
+    const found = [];
+    findAggregateFunctionExprs(expr, selectContext, found);
+    return found.length > 0;
+}
 /**
  * Checks if a final projection is needed for complex expressions or for
  * aliasing simple column refs whose alias differs from the underlying column.
@@ -451,6 +793,17 @@ function findAggregateFunctionExprs(expr, ctx, results) {
             break;
     }
 }
+/**
+ * Every aggregate function call inside an AST expression, in source order.
+ * Does not descend into an aggregate's own arguments (nested aggregates are
+ * invalid SQL). Exported for callers that need to *inspect* the aggregates in a
+ * clause rather than collect them into the AggregateNode.
+ */
+export function collectAggregateFunctionExprs(expr, ctx) {
+    const found = [];
+    findAggregateFunctionExprs(expr, ctx, found);
+    return found;
+}
 /**
  * Collects aggregate functions from a HAVING clause AST that are not already
  * present in the existing aggregates list. Returns new aggregates to add.
@@ -473,17 +826,21 @@ function collectOrderByAggregates(orderBy, selectContext, existingAggregates) {
 }
 /**
  * Returns true if any ORDER BY clause expression contains an aggregate function call.
+ *
+ * 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(*)`.
  */
-function orderByContainsAggregates(orderBy, selectContext) {
+function orderByContainsAggregates(orderBy, selectContext, selectList) {
     if (!orderBy || orderBy.length === 0)
         return false;
-    const found = [];
-    for (const clause of orderBy) {
-        findAggregateFunctionExprs(clause.expr, selectContext, found);
-        if (found.length > 0)
-            return true;
-    }
-    return false;
+    return orderBy.some(clause => {
+        const entry = resolveOrdinalReference(clause.expr, selectList, 'ORDER BY');
+        return containsAggregateFunction(entry?.expr ?? clause.expr, selectContext);
+    });
 }
 /**
  * Given a list of aggregate function call AST nodes, builds aggregate plan nodes
@@ -496,26 +853,27 @@ function dedupeNewAggregates(funcExprs, selectContext, existingAggregates) {
     const existingKeys = new Set();
     for (const agg of existingAggregates) {
         if (CapabilityDetectors.isAggregateFunction(agg.expression)) {
-            const aggNode = agg.expression;
-            existingKeys.add(expressionToString(aggNode.expression).toLowerCase());
+            existingKeys.add(expressionToIdentityString(agg.expression.expression));
         }
     }
     const newAggregates = [];
+    const newKeys = new Set();
     for (const funcExpr of funcExprs) {
-        const key = expressionToString(funcExpr).toLowerCase();
+        const key = expressionToIdentityString(funcExpr);
         if (existingKeys.has(key))
             continue;
-        if (newAggregates.some(a => a.alias.toLowerCase() === key))
+        if (newKeys.has(key))
             continue;
         const aggNode = buildFunctionCall(selectContext, funcExpr, true);
         newAggregates.push({ expression: aggNode, alias: expressionToString(funcExpr) });
+        newKeys.add(key);
     }
     return newAggregates;
 }
 /**
  * Builds final projections for the complete SELECT list in aggregate context
  */
-export function buildFinalAggregateProjections(stmt, selectContext, aggregateOutputScope, aggregateNode, aggregates, groupByExpressions) {
+export function buildFinalAggregateProjections(stmt, selectContext, aggregateOutputScope, aggregateNode, aggregates, groupByExpressions, starProjectionsByColumn = new Map()) {
     const finalProjections = [];
     const aggregateAttributes = aggregateNode.getAttributes();
     // Build context with aggregates so buildFunctionCall can resolve aggregate references
@@ -540,19 +898,36 @@ export function buildFinalAggregateProjections(stmt, selectContext, aggregateOut
     // it and the unique group-key FD is silently dropped at the projection
     // (`keysOf(root) = []`). Referencing the aggregate group column keeps the key
     // and republishes it under exactly its grouping collation (trivially sound).
-    const groupByFingerprints = new Map();
-    groupByExpressions.forEach((expr, index) => {
-        const fp = expressionToString(expr.expression);
-        if (!groupByFingerprints.has(fp))
-            groupByFingerprints.set(fp, index);
-    });
+    //
+    // 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);
     for (const column of stmt.columns) {
+        if (column.type === 'all') {
+            for (const starProj of starProjectionsByColumn.get(column) ?? []) {
+                const gbIdx = starGroupKeyIndex(starProj, groupKeys.byBaseAttrId);
+                if (gbIdx === undefined) {
+                    // validateAggregateProjections already rejected every star column that
+                    // is not a grouping key, so reaching here means the two disagree.
+                    throw new QuereusError(`Internal: SELECT * column '${starProj.alias ?? '?'}' is not a GROUP BY key`, StatusCode.INTERNAL);
+                }
+                const starRef = starProj.node;
+                const colRef = buildGroupKeyColumnRef(aggregateOutputScope, aggregateAttributes[gbIdx], starRef.expression, gbIdx);
+                finalProjections.push({
+                    node: colRef,
+                    alias: starProj.alias,
+                    attributeId: colRef.attributeId
+                });
+            }
+            continue;
+        }
         if (column.type === 'column') {
             // Bare columns (`type === 'column'`) already resolve against the aggregate
             // group symbol (registered under the column name) in recompute, so their
             // key survives; only non-bare group expressions need the direct reference.
             const gbIdx = column.expr.type !== 'column'
-                ? groupByFingerprints.get(expressionToString(column.expr))
+                ? groupKeys.byFingerprint.get(expressionToIdentityString(column.expr))
                 : undefined;
             if (gbIdx !== undefined) {
                 const colRef = buildGroupKeyColumnRef(aggregateOutputScope, aggregateAttributes[gbIdx], column.expr, gbIdx);
@@ -583,6 +958,15 @@ export function buildFinalAggregateProjections(stmt, selectContext, aggregateOut
     }
     return finalProjections;
 }
+/**
+ * Resolves one expanded `SELECT *` column to the GROUP BY index it was grouped on,
+ * or `undefined` if it is not a bare reference to a grouping key.
+ */
+function starGroupKeyIndex(starProj, groupKeyByAttrId) {
+    if (!CapabilityDetectors.isColumnReference(starProj.node))
+        return undefined;
+    return groupKeyByAttrId.get(starProj.node.attributeId);
+}
 /**
  * Synthesizes a bare {@link ColumnReferenceNode} to an AggregateNode group output
  * column for a SELECT-list item that fingerprint-matches a GROUP BY expression.
@@ -594,8 +978,8 @@ export function buildFinalAggregateProjections(stmt, selectContext, aggregateOut
  * keeps the same name `ProjectNode.buildOutputType` would have produced for the
  * recomputed expression.
  */
-function buildGroupKeyColumnRef(aggregateOutputScope, groupAttr, selectExpr, columnIndex) {
+function buildGroupKeyColumnRef(scope, groupAttr, selectExpr, columnIndex) {
     const colExpr = { type: 'column', name: expressionToString(selectExpr) };
-    return new ColumnReferenceNode(aggregateOutputScope, colExpr, groupAttr.type, groupAttr.id, columnIndex);
+    return new ColumnReferenceNode(scope, colExpr, groupAttr.type, groupAttr.id, columnIndex);
 }
 //# sourceMappingURL=select-aggregates.js.map