squirreling 0.16.11 → 0.16.13

package/package.json

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

package/src/execute/aggregates.js

@@ -5,6 +5,7 @@ import { finalizeAccumulator, newAccumulator, updateAccumulator } from './accumu
 import { executePlan, executeScan, selectColumnNames } from './execute.js'
 import { foldEvaluatedRows } from './fold.js'
 import { normalizeScanColumnResult } from './scanColumn.js'
+import { scanFilter } from './scanFilter.js'
 import { sortEntriesByTerms } from './sort.js'
 import { planStreamingAggregates, streamingHashAggregateRows, streamingScalarAggregateRows } from './streamingAggregate.js'
 import { keyify } from './utils.js'
@@ -289,10 +290,12 @@ function tryColumnScanAggregate(plan, { tables, signal }) {
   // Child must be a direct table scan
   if (plan.child.type !== 'Scan') return
   const scanNode = plan.child
-  const { limit, offset, where } = scanNode.hints
+  const { limit, offset } = scanNode.hints
 
   const table = tables[scanNode.table]
   if (!table?.scanColumn) return
+  const { where, residual } = scanFilter(scanNode, dataSourceColumns(table))
+  if (residual) return
 
   // COUNT(*) needs a physical column whose filtered chunk lengths can be
   // counted. Prefer a predicate/projection column, then any table column.

package/src/execute/execute.js

@@ -14,6 +14,7 @@ import { distinctBatches, filterBatches, limitBatches, projectExpressionBatches
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
 import { referencesRowScope } from './rowScope.js'
 import { normalizeScanColumnResult } from './scanColumn.js'
+import { scanFilter } from './scanFilter.js'
 import { executeSort } from './sort.js'
 import { executeSemiJoin } from './semiJoin.js'
 import { addBounds, minBounds, stableRowKey } from './utils.js'
@@ -317,35 +318,51 @@ export function executeScan(plan, context, existingColumnResult) {
   const { tables, signal } = context
   const table = validateTable({ ...plan, tables })
   validateScan({ ...plan, tables })
-  const hasLimitOffset = plan.hints.limit !== undefined || plan.hints.offset // 0 offset is noop
+  const { where, residual } = scanFilter(plan, dataSourceColumns(table))
+  const hints = { ...plan.hints, where }
+  if (residual) {
+    // Keep range and Top-K outside the scan until the engine residual runs.
+    delete hints.limit
+    delete hints.offset
+  }
+  const hasLimitOffset = hints.limit !== undefined || hints.offset // 0 offset is noop
   const scanContext = { ...context, scope: [plan.alias ?? plan.table] }
 
   if (!existingColumnResult && table.prepareScan && table.schema) {
-    const prepared = table.prepareScan(scanRequest(plan, table.schema, scanContext))
-    return executePreparedScan({ plan, prepared, context: scanContext, table })
+    // Derive column demands from the original predicate, including fields
+    // needed by engine residuals, but send only the source-local predicate.
+    const request = scanRequest(plan, table.schema, scanContext)
+    request.filter = where
+    if (residual) {
+      delete request.limit
+      delete request.offset
+      delete request.topK
+    }
+    const prepared = table.prepareScan(request)
+    return finish(executePreparedScan({ plan: { ...plan, hints }, prepared, context: scanContext, table }))
   }
 
   // Fast path: single column scan. As with scan(), hints the source did not
   // apply are handled by the engine over the returned column values.
-  const scanColumnOptions = plan.hints.columns?.length === 1
-    ? plan.hints.where
+  const scanColumnOptions = hints.columns?.length === 1
+    ? hints.where
       // Do not push a filtered range until WHERE is known to be applied: an
       // older source may ignore WHERE but eagerly apply LIMIT/OFFSET.
-      ? { column: plan.hints.columns[0], where: plan.hints.where, signal }
-      : { column: plan.hints.columns[0], ...plan.hints, signal }
+      ? { column: hints.columns[0], where: hints.where, signal }
+      : { column: hints.columns[0], ...hints, signal }
     : undefined
   const columnResult = existingColumnResult ?? (table.scanColumn && scanColumnOptions
     ? normalizeScanColumnResult(table.scanColumn(scanColumnOptions), scanColumnOptions)
     : undefined)
   if (columnResult && scanColumnOptions) {
-    const column = plan.hints.columns[0]
-    const scanRows = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
+    const column = hints.columns[0]
+    const scanRows = computeScanRows(table.numRows, hints.limit, hints.offset)
     const columns = [column]
-    const appliedLimitOffset = plan.hints.where
+    const appliedLimitOffset = hints.where
       ? false
       : columnResult.appliedLimitOffset
-    const residualFilter = plan.hints.where && !columnResult.appliedWhere
-      ? compileBatchExpression(plan.hints.where, columns)
+    const residualFilter = hints.where && !columnResult.appliedWhere
+      ? compileBatchExpression(hints.where, columns)
       : undefined
 
     /** @returns {AsyncIterable<AsyncBatch>} */
@@ -353,28 +370,28 @@ export function executeScan(plan, context, existingColumnResult) {
       /** @type {AsyncIterable<AsyncBatch>} */
       let batches = columnBatches(columnResult.chunks(), signal)
       if (residualFilter) {
-        const targetRows = plan.hints.limit === undefined
+        const targetRows = hints.limit === undefined
           ? undefined
-          : plan.hints.limit + (plan.hints.offset ?? 0)
+          : hints.limit + (hints.offset ?? 0)
         batches = filterBatches(batches, residualFilter, signal, targetRows)
       }
       if (!appliedLimitOffset && hasLimitOffset) {
-        batches = limitBatches(batches, plan.hints.limit, plan.hints.offset, signal)
+        batches = limitBatches(batches, hints.limit, hints.offset, signal)
       }
       return batches
     }
 
-    const canUseBatches = !plan.hints.where || columnResult.appliedWhere || residualFilter !== undefined
+    const canUseBatches = !hints.where || columnResult.appliedWhere || residualFilter !== undefined
     if (canUseBatches) {
-      return batchResult({
+      return finish(batchResult({
         columns,
-        numRows: plan.hints.where ? undefined : scanRows,
+        numRows: hints.where ? undefined : scanRows,
         maxRows: scanRows,
         batches: makeBatches,
         signal,
-      })
+      }))
     }
-    return {
+    return finish({
       columns,
       numRows: undefined,
       maxRows: scanRows,
@@ -395,10 +412,10 @@ export function executeScan(plan, context, existingColumnResult) {
           }
         })()
 
-        result = filterRows(result, plan.hints.where, scanContext, plan.hints.limit)
+        result = filterRows(result, hints.where, scanContext, hints.limit)
         // Filtered LIMIT/OFFSET was intentionally not passed to scanColumn.
         if (!appliedLimitOffset && hasLimitOffset) {
-          result = limitRows(result, plan.hints.limit, plan.hints.offset, signal)
+          result = limitRows(result, hints.limit, hints.offset, signal)
         }
 
         yield* result
@@ -406,7 +423,7 @@ export function executeScan(plan, context, existingColumnResult) {
         // the abort so a truncated scan is not mistaken for a complete one
         signal?.throwIfAborted()
       },
-    }
+    })
   }
 
   if (!table.scan) {
@@ -414,30 +431,30 @@ export function executeScan(plan, context, existingColumnResult) {
   }
 
   // do the scan
-  const scanResult = table.scan({ ...plan.hints, signal })
+  const scanResult = table.scan({ ...hints, signal })
   const { appliedWhere, appliedLimitOffset } = scanResult
 
   // Applied limit/offset without applied where is invalid
-  if (!appliedWhere && appliedLimitOffset && plan.hints.where && hasLimitOffset) {
+  if (!appliedWhere && appliedLimitOffset && hints.where && hasLimitOffset) {
     throw new Error(`Data source "${plan.table}" applied limit/offset without applying where`)
   }
 
-  const scanRows = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
-  return {
-    columns: plan.hints.columns ?? dataSourceColumns(table),
-    numRows: !plan.hints.where ? scanRows : undefined,
+  const scanRows = computeScanRows(table.numRows, hints.limit, hints.offset)
+  return finish({
+    columns: hints.columns ?? dataSourceColumns(table),
+    numRows: !hints.where ? scanRows : undefined,
     maxRows: scanRows,
     async *rows() {
       let result = scanResult.rows()
 
       // Apply WHERE if data source did not
-      if (!appliedWhere && plan.hints.where) {
-        result = filterRows(result, plan.hints.where, scanContext, plan.hints.limit)
+      if (!appliedWhere && hints.where) {
+        result = filterRows(result, hints.where, scanContext, hints.limit)
       }
 
       // Apply LIMIT/OFFSET if data source did not
       if (!appliedLimitOffset && hasLimitOffset) {
-        result = limitRows(result, plan.hints.limit, plan.hints.offset, signal)
+        result = limitRows(result, hints.limit, hints.offset, signal)
       }
 
       yield* result
@@ -446,6 +463,24 @@ export function executeScan(plan, context, existingColumnResult) {
       // the abort so a truncated scan is not mistaken for a complete one
       signal?.throwIfAborted()
     },
+  })
+
+  /**
+   * Apply engine-only predicates and ranges after any source execution path.
+   * @param {QueryResults} source
+   * @returns {QueryResults}
+   */
+  function finish(source) {
+    if (!residual) return source
+    const { limit, offset } = plan.hints
+    return {
+      columns: source.columns,
+      maxRows: computeScanRows(source.maxRows, limit, offset),
+      async *rows() {
+        const filtered = filterRows(source.rows(), residual, scanContext, limit)
+        yield* limitRows(filtered, limit, offset, signal)
+      },
+    }
   }
 }
 

package/src/execute/scanFilter.js

@@ -0,0 +1,81 @@
+/**
+ * @import { ExprNode } from '../types.js'
+ * @import { ScanNode } from '../plan/types.js'
+ */
+
+/**
+ * Translate local conjuncts into physical column names. Keep subqueries and
+ * references outside this scan in the engine. Match scope names exactly, as
+ * expression evaluation does, including quoted identifiers and case.
+ *
+ * @param {ScanNode} plan
+ * @param {string[]} columns
+ * @returns {{ where?: ExprNode, residual?: ExprNode }}
+ */
+export function scanFilter(plan, columns) {
+  const scope = plan.alias ?? plan.table
+
+  /**
+   * @param {ExprNode} node
+   * @returns {{ where?: ExprNode, residual?: ExprNode }}
+   */
+  function split(node) {
+    if (!node) return {}
+    if (node.type === 'binary' && node.op === 'AND') {
+      const left = split(node.left)
+      const right = split(node.right)
+      return {
+        where: combine(left.where, right.where),
+        residual: combine(left.residual, right.residual),
+      }
+    }
+    let safe = true
+    /**
+     * @param {ExprNode} expr
+     * @returns {ExprNode}
+     */
+    function rewrite(expr) {
+      if (!expr) return expr
+      if (expr.type === 'identifier') {
+        if (expr.prefix && expr.prefix !== scope || !columns.includes(expr.name) ||
+            expr.prefix && columns.includes(`${expr.prefix}.${expr.name}`)) {
+          safe = false
+          return expr
+        }
+        if (!expr.prefix) return expr
+        const bare = { ...expr }
+        delete bare.prefix
+        return bare
+      }
+      if (expr.type === 'literal' || expr.type === 'interval') return expr
+      if (expr.type === 'binary') return { ...expr, left: rewrite(expr.left), right: rewrite(expr.right) }
+      if (expr.type === 'unary') return { ...expr, argument: rewrite(expr.argument) }
+      if (expr.type === 'cast') return { ...expr, expr: rewrite(expr.expr) }
+      if (expr.type === 'function') return { ...expr, args: expr.args.map(rewrite), ...expr.filter ? { filter: rewrite(expr.filter) } : {} }
+      if (expr.type === 'in valuelist') return { ...expr, expr: rewrite(expr.expr), values: expr.values.map(rewrite) }
+      if (expr.type === 'subscript') return { ...expr, expr: rewrite(expr.expr), index: rewrite(expr.index) }
+      if (expr.type === 'case') return {
+        ...expr,
+        caseExpr: rewrite(expr.caseExpr),
+        whenClauses: expr.whenClauses.map(w => ({ ...w, condition: rewrite(w.condition), result: rewrite(w.result) })),
+        elseResult: rewrite(expr.elseResult),
+      }
+      safe = false
+      return expr
+    }
+    const where = rewrite(node)
+    return safe ? { where } : { residual: node }
+  }
+  return split(plan.hints.where)
+}
+
+/**
+ * @param {ExprNode} left
+ * @param {ExprNode} right
+ * @returns {ExprNode}
+ */
+function combine(left, right) {
+  if (!left) return right
+  if (!right) return left
+  return { type: 'binary', op: 'AND', left, right, positionStart: left.positionStart, positionEnd: right.positionEnd }
+}

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/types.d.ts

@@ -145,6 +145,7 @@ export interface ScanTopK {
 export interface ScanRequest {
   columns: readonly ColumnDemand[]
   topK?: ScanTopK
+  /** Source-local predicate: identifiers use bare physical column names. */
   filter?: ExprNode
   limit?: number
   offset?: number
@@ -271,7 +272,8 @@ export interface ScanResults {
  */
 export interface ScanOptions {
   columns?: string[] // columns needed (undefined means all columns)
-  where?: ExprNode // where clause
+  /** Source-local predicate: identifiers use bare physical column names. */
+  where?: ExprNode
   // important: only apply limit/offset if where is fully applied by the data source
   // otherwise, the data source must return at least enough rows to ensure the engine
   // can apply limit/offset correctly after filtering
@@ -285,6 +287,7 @@ export interface ScanOptions {
  */
 export interface ScanColumnOptions {
   column: string
+  /** Source-local predicate: identifiers use bare physical column names. */
   where?: ExprNode
   limit?: number
   offset?: number

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
+}