squirreling 0.16.12 → 0.16.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.12",
+  "version": "0.16.14",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -43,7 +43,7 @@
     "@types/node": "26.6.5",
     "@vitest/coverage-v8": "5.0.5",
     "eslint": "10.13.0",
-    "eslint-plugin-jsdoc": "65.4.0",
+    "eslint-plugin-jsdoc": "65.4.1",
     "globals": "17.13.0",
     "typescript": "7.0.2",
     "vitest": "5.0.5"

package/src/execute/aggregates.js

@@ -193,6 +193,18 @@ export function executeHashAggregate(plan, context) {
  * @returns {QueryResults}
  */
 export function executeScalarAggregate(plan, context) {
+  if (context.deferScans && plan.child.type === 'Scan') {
+    const child = executeScan(plan.child, context)
+    return {
+      columns: selectColumnNames(plan.columns, child.columns),
+      numRows: plan.having ? undefined : 1,
+      maxRows: 1,
+      async *rows() {
+        context.signal?.throwIfAborted()
+        yield* executeScalarAggregate(plan, { ...context, deferScans: false }).rows()
+      },
+    }
+  }
   // Fast path: use scanColumn when available
   const columnScan = tryColumnScanAggregate(plan, context)
   if (columnScan?.rows) {

package/src/execute/dynamicFilter.js

@@ -0,0 +1,131 @@
+/**
+ * @import { ExprNode, SqlPrimitive } from '../types.js'
+ * @import { QueryPlan } from '../plan/types.js'
+ */
+
+// Bound filter memory and match the session-index pruning limit.
+const MAX_DYNAMIC_FILTER_KEYS = 256
+
+/**
+ * Bounded, per-column key sets. Once a column exceeds the cap, release it and
+ * stop collecting that column. Unsupported values disable that column too.
+ *
+ * @param {number} count
+ * @param {boolean} [hash] - preserve the hash join's serialized key equivalences
+ * @returns {{ add(values: SqlPrimitive[]): void, apply(plan: QueryPlan, keys: ExprNode[]): QueryPlan }}
+ */
+export function dynamicFilter(count, hash = false) {
+  /** @type {(Set<SqlPrimitive> | undefined)[]} */
+  const sets = Array.from({ length: count }, () => new Set())
+  let active = true
+  return {
+    /**
+     * @param {SqlPrimitive[]} values
+     * @returns {void}
+     */
+    add(values) {
+      if (!active) return
+      // Hash tuple serialization uses delimiters and serializes objects. Do
+      // not prune when those encodings can collide across column boundaries.
+      if (hash && values.some(value => typeof value === 'object' && value !== null ||
+          typeof value === 'string' && (value.includes('|') || ['[', '{', '"'].includes(value[0]) || value === 'null'))) {
+        sets.fill(undefined)
+        active = false
+        return
+      }
+      for (let i = 0; i < sets.length; i++) {
+        const set = sets[i]
+        const value = values[i]
+        if (!set || value == null) continue
+        if (!['string', 'number', 'bigint', 'boolean'].includes(typeof value) ||
+            typeof value === 'number' && !Number.isFinite(value)) {
+          sets[i] = undefined
+          continue
+        }
+        set.add(value)
+        if (hash && count > 1) {
+          if (typeof value === 'boolean') set.add(String(value))
+          if (value === 'true' || value === 'false') set.add(value === 'true')
+        }
+        if (set.size > MAX_DYNAMIC_FILTER_KEYS) sets[i] = undefined
+      }
+      active = sets.some(Boolean)
+    },
+    /**
+     * @param {QueryPlan} plan
+     * @param {ExprNode[]} keys
+     * @returns {QueryPlan}
+     */
+    apply(plan, keys) {
+      for (let i = 0; i < keys.length; i++) {
+        const set = sets[i]
+        if (set?.size) plan = pushFilter(plan, keys[i], [...set])
+      }
+      return plan
+    },
+  }
+}
+
+/**
+ * Only traverse operators that preserve the meaning of a physical column.
+ * Limits, aggregates, windows and projections are deliberate barriers.
+ *
+ * @param {QueryPlan} plan
+ * @param {ExprNode} key
+ * @param {SqlPrimitive[]} values
+ * @returns {QueryPlan}
+ */
+function pushFilter(plan, key, values) {
+  if (key?.type !== 'identifier') return plan
+  if (plan.type === 'Scan') {
+    if (key.prefix && key.prefix !== (plan.alias ?? plan.table) ||
+        plan.hints.limit !== undefined || plan.hints.offset || plan.topK) return plan
+    const position = { positionStart: key.positionStart, positionEnd: key.positionEnd }
+    /** @type {ExprNode} */
+    const filter = {
+      type: 'in valuelist', expr: key, ...position,
+      values: values.map(value => ({ type: 'literal', value, ...position })),
+    }
+    /** @type {ExprNode} */
+    const where = plan.hints.where
+      ? { type: 'binary', op: 'AND', left: plan.hints.where, right: filter, ...position }
+      : filter
+    return { ...plan, hints: { ...plan.hints, where } }
+  }
+  if (plan.type === 'Filter' || plan.type === 'Sort' && !plan.topK || plan.type === 'Distinct') {
+    return { ...plan, child: pushFilter(plan.child, key, values) }
+  }
+  if (plan.type === 'HashJoin' && key.prefix) {
+    // Restrict only preserved inputs of outer joins; restricting an optional
+    // input could turn a formerly matched row into a new null-extended row.
+    const left = plan.joinType === 'INNER' || plan.joinType === 'LEFT'
+      ? pushFilter(plan.left, key, values) : plan.left
+    const right = plan.joinType === 'INNER' || plan.joinType === 'RIGHT'
+      ? pushFilter(plan.right, key, values) : plan.right
+    return { ...plan, left, right }
+  }
+  return plan
+}
+
+/**
+ * Selectivity heuristic when exact filtered cardinalities are unavailable.
+ * Count conjuncts so a date plus a LIKE wins over a lone part-type predicate.
+ *
+ * @param {QueryPlan} plan
+ * @returns {number}
+ */
+export function filterScore(plan) {
+  if (plan.type === 'Scan') return conjuncts(plan.hints.where)
+  if (plan.type === 'Filter') return conjuncts(plan.condition) + filterScore(plan.child)
+  if (plan.type === 'HashJoin' && plan.joinType === 'INNER') return Math.max(filterScore(plan.left), filterScore(plan.right))
+  return 0
+}
+
+/**
+ * @param {ExprNode} expr
+ * @returns {number}
+ */
+function conjuncts(expr) {
+  return !expr ? 0 : expr.type === 'binary' && expr.op === 'AND'
+    ? conjuncts(expr.left) + conjuncts(expr.right) : 1
+}

package/src/execute/execute.js

@@ -1,5 +1,5 @@
 import { selectedRowCount } from '../backend/batch.js'
-import { batchesToRows } from '../backend/batchAdapters.js'
+import { batchesToRows, rowsToBatches } from '../backend/batchAdapters.js'
 import { dataSourceColumns, memorySource } from '../backend/dataSource.js'
 import { derivedAlias } from '../expression/alias.js'
 import { compileBatchExpression } from '../expression/batch.js'
@@ -318,6 +318,37 @@ export function executeScan(plan, context, existingColumnResult) {
   const { tables, signal } = context
   const table = validateTable({ ...plan, tables })
   validateScan({ ...plan, tables })
+  if (context.deferScans && !existingColumnResult) {
+    const size = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
+    const columns = plan.hints.columns ?? dataSourceColumns(table)
+    /** @type {QueryResults} */
+    const deferred = {
+      columns,
+      numRows: plan.hints.where ? undefined : size,
+      maxRows: size,
+      async *rows() {
+        context.signal?.throwIfAborted()
+        yield* executeScan(plan, { ...context, deferScans: false }).rows()
+      },
+    }
+    // Preserve native batch execution above a deferred input. Legacy fallback
+    // remains at the source boundary if a source declines its column path.
+    if (table.prepareScan && table.schema || table.scanColumn && plan.hints.columns?.length === 1) {
+      deferred.batches = async function* deferredBatches() {
+        context.signal?.throwIfAborted()
+        const result = executeScan(plan, { ...context, deferScans: false })
+        if (result.batches) {
+          // Prepared sources may return extra fields or a different order.
+          // Align vectors with the metadata exposed before opening the scan.
+          const indexes = columns.map(column => result.columns.indexOf(column))
+          for await (const batch of result.batches()) {
+            yield { ...batch, columns: indexes.map(index => batch.columns[index]) }
+          }
+        } else yield* rowsToBatches(result.rows(), columns, { signal })
+      }
+    }
+    return deferred
+  }
   const { where, residual } = scanFilter(plan, dataSourceColumns(table))
   const hints = { ...plan.hints, where }
   if (residual) {

package/src/execute/join.js

@@ -1,6 +1,7 @@
 import { evaluateExpr } from '../expression/evaluate.js'
 import { keyify, maxBounds } from './utils.js'
 import { executePlan } from './execute.js'
+import { dynamicFilter, filterScore } from './dynamicFilter.js'
 import { yieldToEventLoop } from './yield.js'
 
 /**
@@ -222,14 +223,18 @@ export function executePositionalJoin(plan, context) {
  * @returns {QueryResults}
  */
 export function executeHashJoin(plan, context) {
-  const left = executePlan({ plan: plan.left, context })
-  const right = executePlan({ plan: plan.right, context })
-  // Build the hash table on the smaller side when both sizes are known,
-  // so joining a small table against a large one buffers the small one.
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
+  const right = executePlan({ plan: plan.right, context: { ...context, deferScans: true } })
+  // Prefer exact sizes, then predicate selectivity, then upper bounds.
+  // A filtered scan's table size is only an upper bound, not its cardinality.
   // Swapping reorders output rows, which SQL leaves unspecified.
   const leftSize = left.numRows ?? left.maxRows
   const rightSize = right.numRows ?? right.maxRows
-  const swap = leftSize !== undefined && rightSize !== undefined && leftSize < rightSize
+  const swap = left.numRows !== undefined && right.numRows !== undefined
+    ? leftSize < rightSize
+    : filterScore(plan.left) !== filterScore(plan.right)
+      ? filterScore(plan.left) > filterScore(plan.right)
+      : leftSize !== undefined && rightSize !== undefined && leftSize < rightSize
   return {
     columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
     async *rows() {
@@ -237,7 +242,7 @@ export function executeHashJoin(plan, context) {
       const rightTable = plan.rightAlias
       const { residual } = plan
       const build = swap ? left : right
-      const probe = swap ? right : left
+      let probe = swap ? right : left
       const buildKeys = swap ? plan.leftKeys : plan.rightKeys
       const probeKeys = swap ? plan.rightKeys : plan.leftKeys
       // Which sides must also emit their unmatched rows
@@ -260,6 +265,7 @@ export function executeHashJoin(plan, context) {
       // otherwise rows with NULL join keys are released immediately.
       /** @type {Map<string | number | bigint | boolean, AsyncRow[]>} */
       const hashMap = new Map()
+      const filters = dynamicFilter(buildKeys.length, true)
       /** @type {AsyncRow[] | undefined} */
       const buildRows = buildOuter ? [] : undefined
       /** @type {string[]} */
@@ -281,6 +287,7 @@ export function executeHashJoin(plan, context) {
         // SQL semantics: NULL never equals anything, so a row with any NULL
         // join key is excluded from the hash table.
         if (keyValues.some(v => v == null)) continue
+        if (!probeOuter) filters.add(keyValues)
         const key = keyify(...keyValues)
         let bucket = hashMap.get(key)
         if (!bucket) {
@@ -295,8 +302,14 @@ export function executeHashJoin(plan, context) {
       /** @type {Set<AsyncRow> | undefined} */
       const matchedBuildRows = buildOuter ? new Set() : undefined
 
+      if (!probeOuter && !hashMap.size && !buildOuter) return
+      if (!probeOuter && hashMap.size) {
+        const filtered = filters.apply(swap ? plan.right : plan.left, probeKeys)
+        probe = executePlan({ plan: filtered, context: { ...context, deferScans: true } })
+      }
+
       // Probe phase: stream the other side
-      for await (const probeRow of probe.rows()) {
+      for await (const probeRow of !probeOuter && !hashMap.size ? [] : probe.rows()) {
         context.signal?.throwIfAborted()
 
         if (!probeCols) {

package/src/execute/semiJoin.js

@@ -1,5 +1,6 @@
 import { evaluateExpr } from '../expression/evaluate.js'
 import { executePlan } from './execute.js'
+import { dynamicFilter } from './dynamicFilter.js'
 import { sqlEquals } from './utils.js'
 import { yieldToEventLoop } from './yield.js'
 
@@ -19,7 +20,7 @@ import { yieldToEventLoop } from './yield.js'
  */
 export function executeSemiJoin(plan, context) {
   if (plan.keys) return executeExistsJoin(plan, context)
-  const left = executePlan({ plan: plan.left, context })
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
   return {
     columns: left.columns,
     maxRows: left.maxRows,
@@ -28,29 +29,30 @@ export function executeSemiJoin(plan, context) {
       const values = new Map()
       let hasNull = false
       let count = 0
-      let built = false
       let rowIndex = 0
-      for await (const row of left.rows()) {
+      const filters = dynamicFilter(1)
+      for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
+        context.signal?.throwIfAborted()
+        if (++count % 4000 === 0) await yieldToEventLoop()
+        const value = await inner.cells[inner.columns[0]]()
+        if (value == null) hasNull = true
+        else {
+          const type = typeof value
+          let group = values.get(type)
+          if (!group) values.set(type, group = new Set())
+          group.add(value)
+          if (!plan.not) filters.add([value])
+        }
+      }
+      if (!plan.not && !values.size || plan.not && hasNull) return
+      const probe = executePlan({
+        plan: plan.not ? plan.left : filters.apply(plan.left, [plan.expr]),
+        context: { ...context, deferScans: true },
+      })
+      for await (const row of probe.rows()) {
         context.signal?.throwIfAborted()
         if (++rowIndex % 4000 === 0) await yieldToEventLoop()
         const value = await evaluateExpr({ node: plan.expr, row, rowIndex, context })
-        if (!built) {
-          for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
-            if (++count % 4000 === 0) {
-              await yieldToEventLoop()
-              context.signal?.throwIfAborted()
-            }
-            const value = await inner.cells[inner.columns[0]]()
-            if (value == null) hasNull = true
-            else {
-              const type = typeof value
-              let group = values.get(type)
-              if (!group) values.set(type, group = new Set())
-              group.add(value)
-            }
-          }
-          built = true
-        }
         const matched = count === 0 ? false : value == null ? null : contains(values, value) ? true : hasNull ? null : false
         if (matched !== null && matched !== plan.not) yield row
       }
@@ -87,36 +89,39 @@ function contains(values, value) {
  * @returns {QueryResults}
  */
 function executeExistsJoin(plan, context) {
-  const left = executePlan({ plan: plan.left, context })
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
   return {
     columns: left.columns,
     maxRows: left.maxRows,
     async *rows() {
       /** @type {KeyTrie} */
       const root = { groups: new Map() }
-      let built = false
       let count = 0
-      for await (const row of left.rows()) {
+      const filters = dynamicFilter(plan.keys?.length ?? 0)
+      for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
         context.signal?.throwIfAborted()
         if (++count % 4000 === 0) await yieldToEventLoop()
-        if (!built) {
-          for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
-            context.signal?.throwIfAborted()
-            if (++count % 4000 === 0) await yieldToEventLoop()
-            const values = await Promise.all(inner.columns.map(col => inner.cells[col]()))
-            if (values.some(value => value == null)) continue
-            let node = root
-            for (const value of values) {
-              const type = typeof value
-              let group = node.groups.get(type)
-              if (!group) node.groups.set(type, group = new Map())
-              let child = group.get(value)
-              if (!child) group.set(value, child = { groups: new Map() })
-              node = child
-            }
-          }
-          built = true
+        const values = await Promise.all(inner.columns.map(col => inner.cells[col]()))
+        if (values.some(value => value == null)) continue
+        if (!plan.not) filters.add(values)
+        let node = root
+        for (const value of values) {
+          const type = typeof value
+          let group = node.groups.get(type)
+          if (!group) node.groups.set(type, group = new Map())
+          let child = group.get(value)
+          if (!child) group.set(value, child = { groups: new Map() })
+          node = child
         }
+      }
+      if (!plan.not && !root.groups.size) return
+      const probe = executePlan({
+        plan: plan.not ? plan.left : filters.apply(plan.left, plan.keys ?? []),
+        context: { ...context, deferScans: true },
+      })
+      for await (const row of probe.rows()) {
+        context.signal?.throwIfAborted()
+        if (++count % 4000 === 0) await yieldToEventLoop()
         const values = await Promise.all((plan.keys ?? []).map(node => evaluateExpr({ node, row, context })))
         const matched = !values.some(value => value == null) && matchesKeys(root, values, 0)
         if (matched !== plan.not) yield row

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

@@ -199,6 +199,8 @@ export interface PlanSqlOptions {
 
 // executePlan(plan, context)
 export interface ExecuteContext {
+  // Delay opening join input scans until their rows are consumed.
+  deferScans?: boolean
   tables: Record<string, AsyncDataSource>
   functions?: Record<string, UserDefinedFunction>
   signal?: AbortSignal

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