squirreling 0.16.12 → 0.16.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.12",
+  "version": "0.16.13",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",

package/src/expression/evaluate.js

@@ -158,10 +158,14 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       ? { ...context, outerRow: row, outerAliases: new Set(outerScope) }
       : context
     const gen = executeStatement({ query: node.subquery, context: subContext, outerScope }).rows()
-    const { value } = await gen.next()
-    gen.return(undefined)
-    if (!value) return null
-    return value.cells[value.columns[0]]()
+    try {
+      const { value } = await gen.next()
+      if (!value) return null
+      if (!(await gen.next()).done) throw new Error('Scalar subquery returned more than one row')
+      return await value.cells[value.columns[0]]()
+    } finally {
+      await gen.return(undefined)
+    }
   }
 
   // Unary operators

package/src/plan/plan.js

@@ -2,13 +2,16 @@ import { dataSourceColumns } from '../backend/dataSource.js'
 import { derivedAlias } from '../expression/alias.js'
 import { parseSql } from '../parse/parse.js'
 import { findAggregate } from '../validation/aggregates.js'
+import { findWindow } from '../validation/windows.js'
 import { ParseError } from '../validation/parseErrors.js'
 import { ColumnNotFoundError, TableNotFoundError } from '../validation/tables.js'
 import { validateNoIdentifiers, validateScan, validateTableRefs } from '../validation/tables.js'
 import { collectColumnsFromExpr, collectScopeColumns, extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, statementScope, tableFunctionColumnNames } from './columns.js'
+import { andPredicate, collectConjuncts } from './predicates.js'
+import { decorrelateExists, decorrelateScalars } from './subqueries.js'
 
 /**
- * @import { AsyncDataSource, DerivedColumn, ExprNode, FromFunction, FromSubquery, FromTable, IdentifierNode, JoinClause, OrderByItem, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement, WindowFunctionNode } from '../types.js'
+ * @import { AsyncDataSource, DerivedColumn, ExprNode, FromFunction, FromSubquery, FromTable, IdentifierNode, JoinClause, OrderByItem, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement } from '../types.js'
  * @import { HashJoinNode, QueryPlan, SemiJoinNode, TableFunctionNode, WindowSpec } from './types.js'
  */
 
@@ -177,7 +180,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
   const scopeColumns = collectScopeColumns({ select, cteColumns, tables })
   /** @type {Map<string, ExprNode>} */
   const aliases = new Map()
-  const columns = select.columns.map(col => {
+  let columns = select.columns.map(col => {
     if (col.type === 'derived') {
       validateTableRefs(col.expr, scopeTables, scopeColumns)
       const expr = resolveAliases(col.expr, aliases)
@@ -193,7 +196,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
     }
     return col
   })
-  const orderBy = resolveOrderByAliases(select.orderBy, aliases)
+  let orderBy = resolveOrderByAliases(select.orderBy, aliases)
 
   // Validate qualified references in other clauses
   validateTableRefs(select.where, scopeTables, scopeColumns)
@@ -298,9 +301,18 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
     }
     select = { ...select, where: residual }
   }
+  const scalar = decorrelateScalars({
+    select, columns, orderBy, scopeAliases, scopeColumns, sourceAlias, tables, cteColumns,
+    rewriteProjection: !useGrouping && !windows.length,
+    planQuery: query => planStatement({ stmt: query, tables, ctePlans, cteColumns }),
+  })
+  columns = scalar.columns
+  select = scalar.select
+  orderBy = scalar.orderBy
+  const { scalarJoins, scalarWhere } = scalar
   if (!select.joins.length) {
     hints.where = select.where
-    if (!needsBuffering && !select.distinct && !semiJoins.length) {
+    if (!needsBuffering && !select.distinct && !semiJoins.length && !scalarWhere) {
       hints.limit = select.limit
       hints.offset = select.offset
     }
@@ -313,7 +325,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
 
   // Add JOINs
   if (select.joins.length) {
-    plan = planJoin({ left: plan, joins: select.joins, leftTable: sourceAlias, ctePlans, cteColumns, perTableColumns, tables, outerScope })
+    plan = planJoin({ from: select.from, left: plan, joins: select.joins, leftTable: sourceAlias, ctePlans, cteColumns, perTableColumns, tables, outerScope })
   }
 
   // Whether FROM resolved to our own direct table scan
@@ -330,6 +342,17 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
 
   for (const semiJoin of semiJoins) plan = { ...semiJoin, left: plan }
 
+  for (const joinScalar of scalarJoins) plan = joinScalar(plan)
+  if (scalarWhere) plan = { type: 'Filter', condition: scalarWhere, child: plan }
+
+  // Bare stars must only include the original query's relations.
+  columns = scalarJoins.length ? columns.flatMap(col =>
+    col.type === 'star' && !col.table
+      ? [sourceAlias, ...select.joins.map(join => join.alias ?? join.table)]
+        .filter(alias => alias !== undefined).map(table => ({ ...col, table }))
+      : [col]
+  ) : columns
+
   if (useGrouping) {
     // Aggregation path: GROUP BY or scalar aggregate
     // HAVING is integrated into aggregate nodes for access to group context
@@ -389,7 +412,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
     // So the order is: Sort -> Project -> Distinct -> Limit
 
     // Fast path for SELECT * without joins
-    const isPassthrough = select.columns.length === 1 && select.columns[0].type === 'star' && !select.joins.length
+    const isPassthrough = select.columns.length === 1 && select.columns[0].type === 'star' && !select.joins.length && !scalarJoins.length
     if (!isPassthrough) {
       let projectColumns = columns
       // When parent only needs specific columns, drop unneeded projections
@@ -401,7 +424,9 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
       // Normalize identifiers to match the child's cell-key layout, so the
       // Project executor can look up cells by exact name instead of relying
       // on the evaluator's suffix-search fallback.
-      const sourceColumns = inferSelectSourceColumns({ select, cteColumns, tables })
+      const sourceColumns = inferSelectSourceColumns({ select, cteColumns, tables }).map(name =>
+        scalarJoins.length && !name.includes('.') ? `${sourceAlias}.${name}` : name
+      )
       projectColumns = projectColumns.map(col =>
         col.type === 'derived'
           ? { ...col, expr: normalizeIdentifiers(col.expr, sourceColumns) }
@@ -414,7 +439,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
       plan = { type: 'Distinct', child: plan }
     }
 
-    if (!(isOwnScan && !needsBuffering && !select.distinct && !semiJoins.length) && (select.limit !== undefined || select.offset)) {
+    if (!(isOwnScan && !needsBuffering && !select.distinct && !semiJoins.length && !scalarWhere) && (select.limit !== undefined || select.offset)) {
       if (select.limit !== undefined) pushLimitIntoSort(plan, select.limit, select.offset)
       plan = { type: 'Limit', limit: select.limit, offset: select.offset, child: plan }
     }
@@ -545,6 +570,7 @@ function planTableFunction(from) {
 
 /**
  * @param {object} options
+ * @param {FromTable | FromSubquery | FromFunction | undefined} options.from
  * @param {QueryPlan} options.left - the left side of the join (FROM or previous joins)
  * @param {JoinClause[]} options.joins - array of join clauses
  * @param {string} options.leftTable - name/alias of the left table
@@ -555,9 +581,10 @@ function planTableFunction(from) {
  * @param {string[]} [options.outerScope] - aliases from an outer query (for correlated subqueries)
  * @returns {QueryPlan}
  */
-function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumns, tables, outerScope }) {
+function planJoin({ from, left, joins, leftTable, ctePlans, cteColumns, perTableColumns, tables, outerScope }) {
   let plan = left
   let currentLeftTable = leftTable
+  const sources = [from]
 
   // Running scope for lateral UNNEST arg validation — excludes the current
   // join's own alias (self-reference) and later joins (forward reference).
@@ -569,6 +596,7 @@ function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumn
 
   for (const join of joins) {
     const rightTable = join.alias ?? join.table
+    sources.push(join.fromFunction ?? joinSource(join))
 
     // LATERAL table function: right side references left-side columns.
     if (join.fromFunction) {
@@ -641,7 +669,7 @@ function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumn
       // `USING (cols)` desugars to an equi-condition `left.col = right.col` per
       // column, which routes through the hash-join path like any other ON.
       const condition = join.on ?? (join.using && buildUsingCondition(join.using, join))
-      const keys = condition && extractEquiKeys({ condition, leftTable: currentLeftTable, rightTable })
+      const keys = condition && extractEquiKeys({ condition, owner: joinColumnOwner(sources, tables, cteColumns), using: !!join.using })
       if (keys) {
         /** @type {HashJoinNode} */
         const hashJoin = {
@@ -853,11 +881,11 @@ function buildUsingCondition(using, pos) {
  *
  * @param {object} options
  * @param {ExprNode} options.condition
- * @param {string} options.leftTable
- * @param {string} options.rightTable
+ * @param {(expr: ExprNode) => string} options.owner
+ * @param {boolean} options.using
  * @returns {{ leftKeys: ExprNode[], rightKeys: ExprNode[], residual?: ExprNode } | undefined}
  */
-function extractEquiKeys({ condition, leftTable, rightTable }) {
+function extractEquiKeys({ condition, owner, using }) {
   /** @type {ExprNode[]} */
   const conjuncts = []
   collectConjuncts(condition, conjuncts)
@@ -868,7 +896,7 @@ function extractEquiKeys({ condition, leftTable, rightTable }) {
   /** @type {ExprNode[]} */
   const residuals = []
   for (const conjunct of conjuncts) {
-    const eq = classifyEquiConjunct(conjunct, leftTable, rightTable)
+    const eq = classifyEquiConjunct(conjunct, owner, using)
     if (eq) {
       leftKeys.push(eq.leftKey)
       rightKeys.push(eq.rightKey)
@@ -887,23 +915,6 @@ function extractEquiKeys({ condition, leftTable, rightTable }) {
   return residual ? { leftKeys, rightKeys, residual } : { leftKeys, rightKeys }
 }
 
-/**
- * Walks an ON expression, flattening top-level AND conjuncts. Non-AND nodes
- * are pushed verbatim. Used to expose individual predicates so equi-keys can
- * be lifted out of an AND chain.
- *
- * @param {ExprNode} node
- * @param {ExprNode[]} out
- */
-function collectConjuncts(node, out) {
-  if (node.type === 'binary' && node.op === 'AND') {
-    collectConjuncts(node.left, out)
-    collectConjuncts(node.right, out)
-    return
-  }
-  out.push(node)
-}
-
 /**
  * Push local ON and WHERE conjuncts according to which side is preserved.
  * Only recurse through this SELECT's join chain, never through shared CTEs
@@ -926,27 +937,11 @@ function pushJoinPredicates(plan, where, select, tables, cteColumns, inherited =
   const rightSource = joinSource(last)
   const sources = [...leftSources, rightSource]
   const aliases = sources.map(source => fromAlias(source))
-  const columns = sources.map(source => source?.type === 'subquery'
-    ? inferStatementColumns({ stmt: source.query, tables, cteColumns })
-    : source?.type === 'table'
-      ? cteColumns?.get(source.table?.toLowerCase()) ?? dataSourceColumns(tables[source.table])
-      : [])
+  const owner = joinColumnOwner(sources, tables, cteColumns)
+  const columns = sources.map(source => sourceColumns(source, tables, cteColumns))
   if (new Set(aliases).size !== aliases.length ||
       columns.some(names => aliases.some(alias => names.includes(alias)))) return where
 
-  /**
-   * @param {ExprNode} expr
-   * @returns {'left' | 'right' | 'literal' | 'unsafe'}
-   */
-  function owner(expr) {
-    if (expr.type === 'literal') return 'literal'
-    if (expr.type !== 'identifier') return 'unsafe'
-    const matches = columns.map((names, i) => names.includes(expr.name) ? i : -1).filter(i => i >= 0)
-    const index = expr.prefix ? aliases.indexOf(expr.prefix) : matches.length === 1 ? matches[0] : -1
-    if (index < 0 || !columns[index].includes(expr.name)) return 'unsafe'
-    return index < leftSources.length ? 'left' : 'right'
-  }
-
   // Do not change the interpretation of ambiguous or misoriented hash keys.
   if (plan.type === 'HashJoin' && (plan.leftKeys.some(key => owner(key) !== 'left') ||
       plan.rightKeys.some(key => owner(key) !== 'right'))) return where
@@ -1122,39 +1117,59 @@ function rejectsNulls(expr, isMissing) {
 }
 
 /**
- * @param {ExprNode | undefined} left
- * @param {ExprNode} right
- * @returns {ExprNode}
+ * @param {FromTable | FromSubquery | FromFunction | undefined} source
+ * @param {Record<string, AsyncDataSource>} [tables]
+ * @param {Map<string, string[]>} [cteColumns]
+ * @returns {string[]}
+ */
+function sourceColumns(source, tables, cteColumns) {
+  if (source?.type === 'subquery') return inferStatementColumns({ stmt: source.query, tables, cteColumns })
+  if (source?.type === 'function') return tableFunctionColumnNames(source)
+  if (source?.type === 'table') return cteColumns?.get(source.table.toLowerCase()) ?? (tables?.[source.table] ? dataSourceColumns(tables[source.table]) : [])
+  return []
+}
+
+/**
+ * Resolve references against every visible source, not the synthetic alias
+ * used to merge rows from earlier joins. Unknown or ambiguous references
+ * remain residual predicates rather than becoming incorrectly oriented keys.
+ *
+ * @param {(FromTable | FromSubquery | FromFunction | undefined)[]} sources
+ * @param {Record<string, AsyncDataSource>} [tables]
+ * @param {Map<string, string[]>} [cteColumns]
+ * @returns {(expr: ExprNode) => 'left' | 'right' | 'literal' | 'unsafe'}
  */
-function andPredicate(left, right) {
-  return left
-    ? { type: 'binary', op: 'AND', left, right, positionStart: left.positionStart, positionEnd: right.positionEnd }
-    : right
+function joinColumnOwner(sources, tables, cteColumns) {
+  const aliases = sources.map(source => fromAlias(source))
+  const columns = sources.map(source => sourceColumns(source, tables, cteColumns))
+  const unsafe = new Set(aliases).size !== aliases.length ||
+    columns.some(names => aliases.some(alias => alias !== undefined && names.includes(alias)))
+  return function owner(expr) {
+    if (expr.type === 'literal') return 'literal'
+    if (unsafe || expr.type !== 'identifier') return 'unsafe'
+    const matches = columns.map((names, i) => names.includes(expr.name) ? i : -1).filter(i => i >= 0)
+    const index = expr.prefix ? aliases.indexOf(expr.prefix) : matches.length === 1 ? matches[0] : -1
+    if (index < 0) return 'unsafe'
+    if (columns[index].length && !columns[index].includes(expr.name)) return 'unsafe'
+    return index === sources.length - 1 ? 'right' : 'left'
+  }
 }
 
 /**
- * Returns the (leftKey, rightKey) pair for an equi conjunct, oriented so
- * leftKey references the left input and rightKey references the right input.
- * Returns undefined when the conjunct is not a `<identifier> = <identifier>`
- * predicate. When the prefixes don't unambiguously identify a side, falls
- * through to the original orientation — matches the prior single-equi
- * behavior so unprefixed columns still produce a hash join.
+ * Orient only equalities whose identifiers belong to opposite inputs.
+ * USING explicitly binds its unqualified identifiers to their respective sides.
  *
  * @param {ExprNode} conjunct
- * @param {string} leftTable
- * @param {string} rightTable
+ * @param {(expr: ExprNode) => string} owner
+ * @param {boolean} using
  * @returns {{ leftKey: ExprNode, rightKey: ExprNode } | undefined}
  */
-function classifyEquiConjunct(conjunct, leftTable, rightTable) {
+function classifyEquiConjunct(conjunct, owner, using) {
   if (conjunct.type !== 'binary' || conjunct.op !== '=') return undefined
   const { left, right } = conjunct
   if (left.type !== 'identifier' || right.type !== 'identifier') return undefined
-  const leftRefsRight = left.prefix === rightTable
-  const rightRefsLeft = right.prefix === leftTable
-  if (leftRefsRight && rightRefsLeft) {
-    return { leftKey: right, rightKey: left }
-  }
-  return { leftKey: left, rightKey: right }
+  if (using || owner(left) === 'left' && owner(right) === 'right') return { leftKey: left, rightKey: right }
+  if (owner(left) === 'right' && owner(right) === 'left') return { leftKey: right, rightKey: left }
 }
 
 /**
@@ -1297,47 +1312,6 @@ function expectNoWindowFunction(expr, clause) {
   }
 }
 
-/**
- * @param {ExprNode | undefined} expr
- * @returns {WindowFunctionNode | undefined}
- */
-function findWindow(expr) {
-  if (!expr) return undefined
-  if (expr.type === 'window') return expr
-  if (expr.type === 'binary') return findWindow(expr.left) || findWindow(expr.right)
-  if (expr.type === 'unary') return findWindow(expr.argument)
-  if (expr.type === 'function') {
-    for (const arg of expr.args) {
-      const found = findWindow(arg)
-      if (found) return found
-    }
-    return undefined
-  }
-  if (expr.type === 'cast') return findWindow(expr.expr)
-  if (expr.type === 'subscript') return findWindow(expr.expr) || findWindow(expr.index)
-  if (expr.type === 'in valuelist') {
-    const found = findWindow(expr.expr)
-    if (found) return found
-    for (const val of expr.values) {
-      const f = findWindow(val)
-      if (f) return f
-    }
-    return undefined
-  }
-  if (expr.type === 'case') {
-    if (expr.caseExpr) {
-      const f = findWindow(expr.caseExpr)
-      if (f) return f
-    }
-    for (const w of expr.whenClauses) {
-      const f = findWindow(w.condition) || findWindow(w.result)
-      if (f) return f
-    }
-    if (expr.elseResult) return findWindow(expr.elseResult)
-  }
-  return undefined
-}
-
 /**
  * Checks if every SELECT column is a plain COUNT(*).
  *
@@ -1356,54 +1330,3 @@ function isAllCountStar(columns) {
     !col.expr.filter
   )
 }
-
-/**
- * Pulls plain equality correlations out of a row-preserving EXISTS query.
- * Limits and aggregation must stay on the per-outer-row execution path.
- *
- * @param {Statement} query
- * @param {string[]} outerScope
- * @param {Record<string, AsyncDataSource>} [tables]
- * @param {Map<string, string[]>} [cteColumns]
- * @returns {{ query: SelectStatement, left: IdentifierNode[] } | undefined}
- */
-function decorrelateExists(query, outerScope, tables, cteColumns) {
-  if (query.type !== 'select' || query.limit !== undefined || query.offset ||
-      query.groupBy.length || query.having ||
-      query.columns.some(col => col.type === 'derived' && (findAggregate(col.expr) || col.expr.type === 'window'))) return
-  const scope = statementScope(query) ?? []
-  /** @type {IdentifierNode[]} */
-  const left = []
-  /** @type {DerivedColumn[]} */
-  const columns = []
-  /** @type {ExprNode[]} */
-  const conjuncts = []
-  if (query.where) collectConjuncts(query.where, conjuncts)
-  /** @type {ExprNode | undefined} */
-  let where
-  for (const term of conjuncts) {
-    const previousKeys = columns.length
-    if (term.type === 'binary' && term.op === '=' && term.left.type === 'identifier' && term.right.type === 'identifier') {
-      for (const [inner, outer] of [[term.left, term.right], [term.right, term.left]]) {
-        if (inner.prefix && scope.includes(inner.prefix) && outer.prefix &&
-            outerScope.includes(outer.prefix) && !scope.includes(outer.prefix)) {
-          left.push(outer)
-          columns.push({ type: 'derived', expr: inner, alias: `__exists_key_${columns.length}`, positionStart: inner.positionStart, positionEnd: inner.positionEnd })
-          break
-        }
-      }
-      if (columns.length > previousKeys) continue
-    }
-    where = andPredicate(where, term)
-  }
-  if (!left.length) return
-  // Check every remaining clause, including nested subqueries and projections,
-  // before discarding the projection and ordering that EXISTS does not read.
-  /** @type {IdentifierNode[]} */
-  const remaining = []
-  collectColumnsFromExpr({ type: 'subquery', subquery: { ...query, where }, positionStart: query.positionStart, positionEnd: query.positionEnd }, remaining, undefined, {
-    tables, cteColumns, outerAliases: new Set(outerScope),
-  })
-  if (remaining.length) return
-  return { query: { ...query, columns, where, distinct: false, orderBy: [] }, left }
-}

package/src/plan/predicates.js

@@ -0,0 +1,29 @@
+/** @import { ExprNode } from '../types.js' */
+
+/**
+ * Walks an ON expression, flattening top-level AND conjuncts. Non-AND nodes
+ * are pushed verbatim. Used to expose individual predicates so equi-keys can
+ * be lifted out of an AND chain.
+ *
+ * @param {ExprNode} node
+ * @param {ExprNode[]} out
+ */
+export function collectConjuncts(node, out) {
+  if (node.type === 'binary' && node.op === 'AND') {
+    collectConjuncts(node.left, out)
+    collectConjuncts(node.right, out)
+    return
+  }
+  out.push(node)
+}
+
+/**
+ * @param {ExprNode | undefined} left
+ * @param {ExprNode} right
+ * @returns {ExprNode}
+ */
+export function andPredicate(left, right) {
+  return left
+    ? { type: 'binary', op: 'AND', left, right, positionStart: left.positionStart, positionEnd: right.positionEnd }
+    : right
+}

package/src/plan/subqueries.js

@@ -0,0 +1,285 @@
+import { derivedAlias } from '../expression/alias.js'
+import { findAggregate } from '../validation/aggregates.js'
+import { findWindow } from '../validation/windows.js'
+import { collectColumnsFromExpr, statementScope } from './columns.js'
+import { andPredicate, collectConjuncts } from './predicates.js'
+
+/**
+ * @import { AsyncDataSource, DerivedColumn, ExprNode, IdentifierNode, OrderByItem, SelectColumn, SelectStatement, Statement } from '../types.js'
+ * @import { QueryPlan } from './types.js'
+ */
+
+/**
+ * Replaces eligible scalar aggregates with grouped LEFT JOINs and exact
+ * empty-group values. Returns correlated WHERE terms for filtering after joins.
+ *
+ * @param {object} options
+ * @param {SelectStatement} options.select
+ * @param {SelectColumn[]} options.columns
+ * @param {OrderByItem[]} options.orderBy
+ * @param {string[]} options.scopeAliases
+ * @param {Set<string>} options.scopeColumns
+ * @param {string | undefined} options.sourceAlias
+ * @param {boolean} options.rewriteProjection
+ * @param {(query: SelectStatement) => QueryPlan} options.planQuery
+ * @param {Record<string, AsyncDataSource>} [options.tables]
+ * @param {Map<string, string[]>} [options.cteColumns]
+ * @returns {{ select: SelectStatement, columns: SelectColumn[], orderBy: OrderByItem[], scalarJoins: ((left: QueryPlan) => QueryPlan)[], scalarWhere: ExprNode | undefined }}
+ */
+export function decorrelateScalars({ select, columns, orderBy, scopeAliases, scopeColumns, sourceAlias, rewriteProjection, planQuery, tables, cteColumns }) {
+  columns = [...columns]
+  // Keep original expressions for source column demand; synthetic scalar cells
+  // are computed above the scan and must never appear in pushdown hints.
+  /** @type {((left: QueryPlan) => QueryPlan)[]} */
+  const scalarJoins = []
+  /**
+   * @param {ExprNode} expr
+   * @returns {ExprNode}
+   */
+  function rewriteScalar(expr) {
+    if (expr.type !== 'subquery' || select.limit === 0) return expr
+    const query = expr.subquery
+    if (query.type !== 'select' || query.columns.length !== 1) return expr
+    const column = query.columns[0]
+    if (column.type !== 'derived' || !findAggregate(column.expr) || findWindow(column.expr)) return expr
+    // Reuse EXISTS' residual-reference check without discarding the aggregate.
+    const keys = decorrelateExists(query, scopeAliases, tables, cteColumns, true)
+    if (!keys) return expr
+    const inner = keys.query.columns.map(col => col.type === 'derived' ? col.expr : column.expr)
+    // Hash equality is only equivalent to scalar equality for matching known
+    // primitive types. Unknown schemas and coercive comparisons stay per-row.
+    if (inner.some((key, i) => {
+      if (key.type !== 'identifier') return true
+      const type = correlationType(query, key, tables, cteColumns)
+      return !type || type !== correlationType(select, keys.left[i], tables, cteColumns)
+    })) return expr
+    let name = `__scalar_${scalarJoins.length}`
+    while ([...scopeColumns, ...scopeAliases].some(col => col === name || col.startsWith(name + '_'))) name += '_'
+    const position = { positionStart: expr.positionStart, positionEnd: expr.positionEnd }
+    const valueName = name + '_value'
+    const keyName = name + '_key'
+    const emptyAlias = name + '_empty'
+    const innerKey = scalarCorrelationKey(inner)
+    const outerKey = scalarCorrelationKey(keys.left)
+    /** @type {IdentifierNode} */
+    const joinedKey = { ...position, type: 'identifier', prefix: name, name: keyName }
+    /** @type {SelectStatement} */
+    const grouped = {
+      ...keys.query,
+      groupBy: [innerKey],
+      // Evaluate the original projection before introducing synthetic aliases.
+      columns: [
+        { ...column, alias: valueName },
+        { ...position, type: 'derived', expr: innerKey, alias: keyName },
+      ],
+    }
+    const right = planQuery(grouped)
+    const scope = statementScope(query) ?? []
+    // A scalar aggregate over zero rows computes the exact empty-group value,
+    // including COUNT arithmetic and aggregate expressions with lazy branches.
+    /** @type {QueryPlan} */
+    const empty = {
+      type: 'Subquery', scope,
+      child: {
+        type: 'ScalarAggregate', columns: [{ ...column, alias: valueName }],
+        child: { type: 'Limit', limit: 0, child: { type: 'SingleRow' } },
+      },
+    }
+    /** @type {ExprNode | undefined} */
+    let residual
+    for (const key of keys.left) {
+      // Map treats NaN as equal to itself; SQL equality does not.
+      residual = andPredicate(residual, { ...position, type: 'binary', op: '=', left: key, right: key })
+    }
+    scalarJoins.push(left => ({
+      type: 'HashJoin', joinType: 'LEFT', leftAlias: sourceAlias ?? '', rightAlias: name,
+      leftKeys: [outerKey], rightKeys: [{ ...joinedKey, prefix: undefined }], residual,
+      right: { type: 'Subquery', child: right, scope },
+      left: {
+        type: 'NestedLoopJoin', joinType: 'INNER', leftAlias: sourceAlias ?? '', rightAlias: emptyAlias, right: empty,
+        condition: { ...position, type: 'literal', value: true }, left,
+      },
+    }))
+    return {
+      ...position, type: 'case',
+      whenClauses: [{
+        ...position,
+        condition: { ...position, type: 'unary', op: 'IS NULL', argument: joinedKey },
+        result: { ...position, type: 'identifier', prefix: emptyAlias, name: valueName },
+      }],
+      elseResult: { ...position, type: 'identifier', prefix: name, name: valueName },
+    }
+  }
+  // Outer aggregates need group-aware placement, so retain their existing path.
+  if (rewriteProjection) {
+    for (let i = 0; i < columns.length; i++) {
+      const col = columns[i]
+      if (col.type === 'derived') {
+        const before = scalarJoins.length
+        const expr = mapScalarExpressions(col.expr, rewriteScalar)
+        if (scalarJoins.length > before) columns[i] = { ...col, alias: col.alias ?? derivedAlias(col.expr), expr }
+      }
+    }
+    orderBy = orderBy.map(term => ({ ...term, expr: mapScalarExpressions(term.expr, rewriteScalar) }))
+  }
+  /** @type {ExprNode | undefined} */
+  let scalarWhere
+  if (select.where) {
+    /** @type {ExprNode[]} */
+    const terms = []
+    collectConjuncts(select.where, terms)
+    /** @type {ExprNode | undefined} */
+    let scanWhere
+    for (const term of terms) {
+      const before = scalarJoins.length
+      const rewritten = mapScalarExpressions(term, rewriteScalar)
+      if (scalarJoins.length > before) scalarWhere = andPredicate(scalarWhere, rewritten)
+      else scanWhere = andPredicate(scanWhere, term)
+    }
+    select = { ...select, where: scanWhere }
+  }
+  return { select, columns, orderBy, scalarJoins, scalarWhere }
+}
+
+/**
+ * Pulls plain equality correlations out of EXISTS or scalar aggregate queries.
+ * Limits, HAVING, and existing grouping stay on the per-outer-row path.
+ *
+ * @param {Statement} query
+ * @param {string[]} outerScope
+ * @param {Record<string, AsyncDataSource>} [tables]
+ * @param {Map<string, string[]>} [cteColumns]
+ * @param {boolean} [aggregate]
+ * @returns {{ query: SelectStatement, left: IdentifierNode[] } | undefined}
+ */
+export function decorrelateExists(query, outerScope, tables, cteColumns, aggregate = false) {
+  if (query.type !== 'select' || query.limit !== undefined || query.offset ||
+      query.groupBy.length || query.having ||
+      !aggregate && query.columns.some(col => col.type === 'derived' && (findAggregate(col.expr) || col.expr.type === 'window'))) return
+  const scope = statementScope(query) ?? []
+  /** @type {IdentifierNode[]} */
+  const left = []
+  /** @type {DerivedColumn[]} */
+  const columns = []
+  /** @type {ExprNode[]} */
+  const conjuncts = []
+  if (query.where) collectConjuncts(query.where, conjuncts)
+  /** @type {ExprNode | undefined} */
+  let where
+  for (const term of conjuncts) {
+    const previousKeys = columns.length
+    if (term.type === 'binary' && term.op === '=' && term.left.type === 'identifier' && term.right.type === 'identifier') {
+      for (const [inner, outer] of [[term.left, term.right], [term.right, term.left]]) {
+        if (inner.prefix && scope.includes(inner.prefix) && outer.prefix &&
+            outerScope.includes(outer.prefix) && !scope.includes(outer.prefix)) {
+          left.push(outer)
+          columns.push({ type: 'derived', expr: inner, alias: `__exists_key_${columns.length}`, positionStart: inner.positionStart, positionEnd: inner.positionEnd })
+          break
+        }
+      }
+      if (columns.length > previousKeys) continue
+    }
+    where = andPredicate(where, term)
+  }
+  if (!left.length) return
+  // Check every remaining clause, including nested subqueries and projections,
+  // before discarding the projection and ordering that EXISTS does not read.
+  /** @type {IdentifierNode[]} */
+  const remaining = []
+  collectColumnsFromExpr({ type: 'subquery', subquery: { ...query, where }, positionStart: query.positionStart, positionEnd: query.positionEnd }, remaining, undefined, {
+    tables, cteColumns, outerAliases: new Set(outerScope),
+  })
+  if (remaining.length) return
+  return { query: { ...query, columns, where, distinct: false, orderBy: [] }, left }
+}
+
+/**
+ * Rewrites scalar expressions without entering a nested lexical query scope.
+ * @param {ExprNode} node
+ * @param {(node: ExprNode) => ExprNode} rewrite
+ * @returns {ExprNode}
+ */
+function mapScalarExpressions(node, rewrite) {
+  if (!node) return node
+  if (node.type === 'unary') {
+    return { ...node, argument: mapScalarExpressions(node.argument, rewrite) }
+  }
+  if (node.type === 'binary') {
+    return { ...node, left: mapScalarExpressions(node.left, rewrite), right: mapScalarExpressions(node.right, rewrite) }
+  }
+  if (node.type === 'function') {
+    return { ...node, args: node.args.map(arg => mapScalarExpressions(arg, rewrite)) }
+  }
+  if (node.type === 'cast') {
+    return { ...node, expr: mapScalarExpressions(node.expr, rewrite) }
+  }
+  if (node.type === 'in valuelist') {
+    return {
+      ...node,
+      expr: mapScalarExpressions(node.expr, rewrite),
+      values: node.values.map(v => mapScalarExpressions(v, rewrite)),
+    }
+  }
+  if (node.type === 'subscript') {
+    return {
+      ...node,
+      expr: mapScalarExpressions(node.expr, rewrite),
+      index: mapScalarExpressions(node.index, rewrite),
+    }
+  }
+  if (node.type === 'case') {
+    return {
+      ...node,
+      caseExpr: mapScalarExpressions(node.caseExpr, rewrite),
+      whenClauses: node.whenClauses.map(w => ({
+        ...w,
+        condition: mapScalarExpressions(w.condition, rewrite),
+        result: mapScalarExpressions(w.result, rewrite),
+      })),
+      elseResult: mapScalarExpressions(node.elseResult, rewrite),
+    }
+  }
+  return rewrite(node)
+}
+
+/**
+ * Looks up a correlation column's declared primitive type in its lexical scope.
+ * Derived relations and CTEs need type propagation before they can use this rewrite.
+ * @param {SelectStatement} query
+ * @param {IdentifierNode} key
+ * @param {Record<string, AsyncDataSource>} [tables]
+ * @param {Map<string, string[]>} [cteColumns]
+ * @returns {string | undefined}
+ */
+function correlationType(query, key, tables, cteColumns) {
+  const { from } = query
+  const table = from?.type === 'table' && (from.alias ?? from.table) === key.prefix ? from.table
+    : query.joins.find(join => !join.subquery && !join.fromFunction && (join.alias ?? join.table) === key.prefix)?.table
+  if (!table || cteColumns?.has(table)) return
+  const type = tables?.[table]?.schema?.fields.find(field => field.name === key.name)?.dataType.type
+  return type && ['string', 'number', 'bigint', 'boolean'].includes(type) ? type : undefined
+}
+
+/**
+ * Encodes composite keys with length-prefixed components so ordinary hash
+ * grouping and joins cannot confuse tuple boundaries. CONCAT propagates NULL.
+ * @param {ExprNode[]} keys
+ * @returns {ExprNode}
+ */
+function scalarCorrelationKey(keys) {
+  if (keys.length === 1) return keys[0]
+  const { positionStart, positionEnd } = keys[0]
+  const position = { positionStart, positionEnd }
+  return {
+    ...position, type: 'function', funcName: 'CONCAT',
+    args: keys.flatMap(key => {
+      /** @type {ExprNode} */
+      const text = { ...position, type: 'cast', expr: key, toType: 'TEXT' }
+      return [
+        /** @type {ExprNode} */ { ...position, type: 'function', funcName: 'LENGTH', args: [text] },
+        /** @type {ExprNode} */ { ...position, type: 'literal', value: ':' },
+        text,
+      ]
+    }),
+  }
+}

package/src/validation/windows.js

@@ -0,0 +1,42 @@
+/** @import { ExprNode, WindowFunctionNode } from '../types.js' */
+
+/**
+ * @param {ExprNode | undefined} expr
+ * @returns {WindowFunctionNode | undefined}
+ */
+export function findWindow(expr) {
+  if (!expr) return undefined
+  if (expr.type === 'window') return expr
+  if (expr.type === 'binary') return findWindow(expr.left) || findWindow(expr.right)
+  if (expr.type === 'unary') return findWindow(expr.argument)
+  if (expr.type === 'function') {
+    for (const arg of expr.args) {
+      const found = findWindow(arg)
+      if (found) return found
+    }
+    return undefined
+  }
+  if (expr.type === 'cast') return findWindow(expr.expr)
+  if (expr.type === 'subscript') return findWindow(expr.expr) || findWindow(expr.index)
+  if (expr.type === 'in valuelist') {
+    const found = findWindow(expr.expr)
+    if (found) return found
+    for (const val of expr.values) {
+      const f = findWindow(val)
+      if (f) return f
+    }
+    return undefined
+  }
+  if (expr.type === 'case') {
+    if (expr.caseExpr) {
+      const f = findWindow(expr.caseExpr)
+      if (f) return f
+    }
+    for (const w of expr.whenClauses) {
+      const f = findWindow(w.condition) || findWindow(w.result)
+      if (f) return f
+    }
+    if (expr.elseResult) return findWindow(expr.elseResult)
+  }
+  return undefined
+}