@dbsp/nql 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { NQL_INTERNAL_COMPILER_OPTIONS } from '@dbsp/types/internal';
-import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isParamIntent, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction } from '@dbsp/types';
+import { NQL_INTERNAL_COMPILER_OPTIONS, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
+import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_VALUE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction, isParamIntent } from '@dbsp/types';
 import { createToken, Lexer, CstParser } from 'chevrotain';
 
 // src/compiler/index.ts
@@ -51,6 +51,7 @@ var ColumnValidator = class _ColumnValidator {
   }
   schema;
   knownCteTables = /* @__PURE__ */ new Set();
+  virtualBindingTables = /* @__PURE__ */ new Map();
   /**
    * Register CTE names so validateTable() skips validation for them.
    * CTE names are not physical tables in the schema, but are valid FROM targets.
@@ -64,6 +65,28 @@ var ColumnValidator = class _ColumnValidator {
   clearKnownCteTables() {
     this.knownCteTables.clear();
   }
+  /**
+   * Register an NQL binding as a virtual table with a concrete output schema.
+   * Binding columns are logical output names, so matching is exact.
+   */
+  addVirtualBindingTable(name, columns) {
+    this.virtualBindingTables.set(name, columns);
+  }
+  /** Clear all registered virtual binding tables (used between compilations). */
+  clearVirtualBindingTables() {
+    this.virtualBindingTables.clear();
+  }
+  isVirtualBindingTable(name) {
+    return name !== void 0 && this.virtualBindingTables.has(name);
+  }
+  getVirtualBindingColumns(name) {
+    return this.virtualBindingTables.get(name);
+  }
+  getTableColumns(name) {
+    const virtualColumns = this.virtualBindingTables.get(name);
+    if (virtualColumns) return virtualColumns;
+    return this.schema.getTable(name)?.columns.map((column) => column.name);
+  }
   /**
    * Convert camelCase to snake_case for column name matching.
    * NQL queries may use either form (e.g., viewCount or view_count).
@@ -79,14 +102,40 @@ var ColumnValidator = class _ColumnValidator {
     if (queryCol === schemaCol) return true;
     return _ColumnValidator.toSnakeCase(queryCol) === _ColumnValidator.toSnakeCase(schemaCol);
   }
+  /**
+   * Resolve a user-authored column spelling to the model column name.
+   * Uses the same exact-or-snake/camel equivalence as validateColumn().
+   */
+  resolveColumnName(table, column) {
+    if (column === "*") return column;
+    const virtualColumns = this.virtualBindingTables.get(table);
+    if (virtualColumns) {
+      return virtualColumns.find((c) => c === column);
+    }
+    const tableInfo = this.schema.getTable(table);
+    if (!tableInfo) return void 0;
+    return tableInfo.columns.find(
+      (c) => _ColumnValidator.columnsMatch(column, c.name)
+    )?.name;
+  }
   validateColumn(table, column) {
     if (column === "*") return;
+    const virtualColumns = this.virtualBindingTables.get(table);
+    if (virtualColumns) {
+      const exists = virtualColumns.some((c) => c === column);
+      if (!exists) {
+        const available = virtualColumns.join(", ") || "(none)";
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_UNKNOWN_COLUMN,
+          `Column '${column}' is not projected by NQL binding '${table}'. Available columns: ${available}`
+        );
+      }
+      return;
+    }
     const tableInfo = this.schema.getTable(table);
     if (!tableInfo) return;
-    const exists = tableInfo.columns.some(
-      (c) => _ColumnValidator.columnsMatch(column, c.name)
-    );
-    if (!exists) {
+    const resolvedColumn = this.resolveColumnName(table, column);
+    if (resolvedColumn === void 0) {
       const available = tableInfo.columns.map((c) => c.name).join(", ");
       throw new NqlSemanticException(
         NqlErrorCodes.SEM_UNKNOWN_COLUMN,
@@ -95,6 +144,7 @@ var ColumnValidator = class _ColumnValidator {
     }
   }
   validateTable(table) {
+    if (this.virtualBindingTables.has(table)) return;
     if (this.knownCteTables.has(table)) return;
     const tableInfo = this.schema.getTable(table);
     if (!tableInfo) {
@@ -105,10 +155,30 @@ var ColumnValidator = class _ColumnValidator {
     }
   }
   resolveRelationTarget(sourceTable, relationName) {
+    if (this.virtualBindingTables.has(sourceTable)) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${sourceTable}' reads from an NQL binding and cannot use relation filters (${relationName}). Relation constructs require a physical model table, not a CTE binding.`
+      );
+    }
     const relations = this.schema.getRelationsFrom(sourceTable);
     const rel = relations.find((r) => r.name === relationName);
     return rel?.target;
   }
+  assertNoBindingRelationConstruct(bindingName, construct, detail) {
+    if (!this.isVirtualBindingTable(bindingName)) return;
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName}' reads from an NQL binding and cannot ${construct} (${detail}). Relation constructs require a physical model table, not a CTE binding.`
+    );
+  }
+  assertNoBindingRelationPath(bindingName, path) {
+    if (!this.isVirtualBindingTable(bindingName)) return;
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName}' reads from an NQL binding and cannot reference relation path '${path}'. Relation paths require a physical model table, not a CTE binding.`
+    );
+  }
 };
 var FORBIDDEN_PARAM_NAMES = /* @__PURE__ */ new Set([
   "__proto__",
@@ -197,6 +267,50 @@ function expressionToField(expr, aliasContext) {
   }
   return null;
 }
+function isBindingTable(ctx, table) {
+  if (table === void 0) return false;
+  return ctx.bindingOutputColumns.has(table) || ctx.validator?.isVirtualBindingTable?.(table) === true;
+}
+function bindingColumns(ctx, table) {
+  if (table === void 0) return void 0;
+  if (ctx.bindingOutputColumns.has(table)) {
+    return ctx.bindingOutputColumns.get(table);
+  }
+  return ctx.validator?.getVirtualBindingColumns?.(table);
+}
+function getKnownBindingColumns(ctx, table) {
+  return bindingColumns(ctx, table);
+}
+function assertNoBindingRelationConstruct(ctx, bindingName, construct, detail) {
+  if (!isBindingTable(ctx, bindingName)) return;
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot ${construct} (${detail}). Relation constructs require a physical model table, not a CTE binding.`
+  );
+}
+function assertNoBindingRelationPath(ctx, bindingName, path) {
+  if (!isBindingTable(ctx, bindingName)) return;
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot reference relation path '${path}'. Relation paths require a physical model table, not a CTE binding.`
+  );
+}
+function validateColumnForTable(ctx, table, column) {
+  if (table === void 0 || column === "*") return;
+  if (isBindingTable(ctx, table)) {
+    const columns = bindingColumns(ctx, table);
+    if (columns === void 0) return;
+    if (!columns.some((c) => c === column)) {
+      const available = columns.join(", ") || "(none)";
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_UNKNOWN_COLUMN,
+        `Column '${column}' is not projected by NQL binding '${table}'. Available columns: ${available}`
+      );
+    }
+    return;
+  }
+  ctx.validator?.validateColumn(table, column);
+}
 function expressionToValue(expr, ctx) {
   switch (expr.type) {
     case "namedParam":
@@ -216,7 +330,23 @@ function expressionToValue(expr, ctx) {
     case "null":
       return null;
     case "path":
-      return { $ref: expr.segments.join(".") };
+      if (ctx) {
+        const field = expr.segments.join(".");
+        const isBindingReference = expr.segments.length === 1 && isBindingTable(ctx, field);
+        if (isBindingReference) {
+          return createNqlBindingRef(field);
+        }
+        const sourceTable = ctx.currentFromTable;
+        const isVirtualBindingSource = sourceTable !== void 0 && isBindingTable(ctx, sourceTable);
+        if (isVirtualBindingSource) {
+          if (field.includes(".")) {
+            assertNoBindingRelationPath(ctx, sourceTable, field);
+          } else {
+            validateColumnForTable(ctx, sourceTable, field);
+          }
+        }
+      }
+      return createNqlBindingRef(expr.segments.join("."));
     case "function": {
       return {
         $fn: expr.name,
@@ -382,6 +512,20 @@ function isAggregateFunction(name) {
   );
 }
 function validateWhereField(ctx, field, aliasContext, originalExpr) {
+  if (!aliasContext && !field.includes(".") && ctx.currentHavingAliases?.has(field)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `HAVING cannot reference SELECT alias '${field}'. PostgreSQL does not allow SELECT aliases in HAVING; repeat the aggregate expression or filter the result in an outer query.`
+    );
+  }
+  if (!aliasContext && ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+    if (field.includes(".")) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    } else {
+      validateColumnForTable(ctx, ctx.currentFromTable, field);
+    }
+    return;
+  }
   if (!ctx.validator) return;
   if (aliasContext) {
     const isInnerScope = originalExpr?.type === "path" && originalExpr.segments.length > 1 && originalExpr.segments[0] === aliasContext;
@@ -400,8 +544,14 @@ function validateWhereField(ctx, field, aliasContext, originalExpr) {
     ctx.validator.validateColumn(ctx.currentRelationTarget, field);
     return;
   }
+  if (ctx.currentFromTable && field.includes(".")) {
+    if (isBindingTable(ctx, ctx.currentFromTable)) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    }
+    return;
+  }
   if (ctx.currentFromTable && !field.includes(".")) {
-    ctx.validator.validateColumn(ctx.currentFromTable, field);
+    validateColumnForTable(ctx, ctx.currentFromTable, field);
   }
 }
 function coerceToStringKey(expr, contextLabel, ctx) {
@@ -442,1262 +592,1843 @@ function coerceToStringKey(expr, contextLabel, ctx) {
   );
 }
 
-// src/compiler/include-builder.ts
-function buildNestedIncludes(paths, flatMode) {
-  const root = { children: /* @__PURE__ */ new Map() };
-  for (const path of paths) {
-    const segments = path.split(".");
-    let node = root;
-    for (const segment of segments) {
-      if (!node.children.has(segment)) {
-        node.children.set(segment, { children: /* @__PURE__ */ new Map() });
-      }
-      node = node.children.get(segment);
-    }
-  }
-  function treeToIncludes(node) {
-    const includes = [];
-    for (const [relation, child] of node.children) {
-      const childIncludes = treeToIncludes(child);
-      const include = {
-        relation,
-        ...flatMode ? { strategy: "flat" } : {},
-        ...childIncludes.length > 0 ? { include: childIncludes } : {}
-      };
-      includes.push(include);
+// src/compiler/compile-mutation.ts
+function assignMutationValue(target, column, value, ctx) {
+  target[column] = expressionToValue(value, ctx);
+}
+function compileMutationPipeline(pipeline, ctx, fns, bindings) {
+  ctx.currentFromTable = pipeline.mutation.table;
+  const mutation = compileMutation(pipeline.mutation, ctx, fns, bindings);
+  let returning;
+  for (const clause of pipeline.clauses) {
+    if (clause.type === "select") {
+      returning = extractReturningColumns(clause, ctx);
     }
-    return includes;
   }
-  return treeToIncludes(root);
-}
-function applyIncludeLimit(includes, path, limit) {
-  const segments = path.split(".");
-  const root = segments[0];
-  const idx = includes.findIndex((inc) => inc.relation === root);
-  if (idx === -1) return;
-  if (segments.length === 1) {
-    includes[idx] = {
-      ...includes[idx],
-      limit,
-      strategy: "flat"
+  if (returning) {
+    return {
+      mutation: { ...mutation, returning }
     };
-  } else {
-    const nested = [...includes[idx]?.include ?? []];
-    applyIncludeLimit(nested, segments.slice(1).join("."), limit);
-    includes[idx] = { ...includes[idx], strategy: "flat", include: nested };
   }
+  return { mutation };
 }
-
-// src/compiler/compile-query.ts
-function compileNestedQuery(query, ctx, fns, bindings) {
-  const savedContext = {
-    currentFromTable: ctx.currentFromTable,
-    currentRelationTarget: ctx.currentRelationTarget
-  };
-  try {
-    if (bindings) {
-      return compileQuery(query, ctx, fns, bindings);
-    }
-    return fns.compileQuery(query, ctx);
-  } finally {
-    ctx.currentFromTable = savedContext.currentFromTable;
-    ctx.currentRelationTarget = savedContext.currentRelationTarget;
+function compileMutation(mutation, ctx, fns, bindings) {
+  switch (mutation.type) {
+    case "insert":
+      return compileInsert(mutation, ctx);
+    case "insert_from":
+      return compileInsertFrom(mutation, ctx, fns, bindings);
+    case "update":
+      return compileUpdate(mutation, ctx, fns, bindings);
+    case "delete":
+      return compileDelete(mutation, ctx, fns, bindings);
+    case "upsert":
+      return compileUpsert(mutation, ctx, fns, bindings);
+    case "upsert_from":
+      return compileUpsertFrom(mutation, ctx, fns, bindings);
   }
 }
-function compileQuery(query, ctx, fns, bindings) {
-  const setClauseIndex = query.clauses.findIndex(
-    (c) => c.type === "setOperation"
-  );
-  if (setClauseIndex >= 0) {
-    return compileSetOperation(query, setClauseIndex, ctx, fns, bindings);
-  }
-  ctx.currentFromTable = query.table;
-  ctx.validator?.validateTable(query.table);
-  let groupByIndex = -1;
-  for (let i = 0; i < query.clauses.length; i++) {
-    if (query.clauses[i]?.type === "groupBy") {
-      groupByIndex = i;
-      break;
+function compileInsert(insert, ctx) {
+  ctx.validator?.validateTable(insert.table);
+  const allColumns = /* @__PURE__ */ new Set();
+  for (const row of insert.rows) {
+    for (const assignment of row) {
+      ctx.validator?.validateColumn(insert.table, assignment.column);
+      allColumns.add(assignment.column);
     }
   }
-  const whereConditions = [];
-  const havingConditions = [];
-  let select;
-  let distinct;
-  const allIncludes = [];
-  let currentIncludeBatch;
-  let groupBy;
-  let orderBy;
-  let limit;
-  let offset;
-  let flatMode = false;
-  let lock;
-  const includeLimits = /* @__PURE__ */ new Map();
-  for (let i = 0; i < query.clauses.length; i++) {
-    const clause = query.clauses[i];
-    switch (clause.type) {
-      case "where": {
-        const condition = fns.compileExpression(
-          clause.condition,
-          ctx,
-          fns
-        );
-        if (groupByIndex >= 0 && i > groupByIndex) {
-          havingConditions.push(condition);
-        } else if (currentIncludeBatch && currentIncludeBatch.length > 0) {
-          const targetInclude = currentIncludeBatch[currentIncludeBatch.length - 1];
-          const mutableInclude = targetInclude;
-          if (targetInclude.where) {
-            mutableInclude.where = {
-              kind: "and",
-              conditions: [targetInclude.where, condition]
-            };
-          } else {
-            mutableInclude.where = condition;
-          }
-        } else {
-          whereConditions.push(condition);
-        }
-        break;
-      }
-      case "select":
-        select = fns.compileSelectClause(clause, ctx, fns);
-        distinct = clause.distinct || void 0;
-        break;
-      case "flat":
-        flatMode = true;
-        break;
-      case "groupBy":
-        groupBy = compileGroupByClause(clause, ctx);
-        currentIncludeBatch = void 0;
-        break;
-      case "orderBy":
-        orderBy = compileOrderByClause(clause, ctx);
-        break;
-      case "limit": {
-        const lc = clause;
-        const count = resolveIntegerCount(
-          lc.count,
-          ctx,
-          lc.relation ? "per-include limit" : "limit"
-        );
-        if (lc.relation) {
-          const includeLimit = isParamIntent(count) ? count.value : count;
-          includeLimits.set(lc.relation, includeLimit);
-        } else {
-          limit = count;
-        }
-        break;
-      }
-      case "offset":
-        offset = resolveIntegerCount(
-          clause.count,
-          ctx,
-          "offset"
-        );
-        break;
-      case "lock": {
-        const lc = clause;
-        lock = { strength: lc.strength, waitPolicy: lc.waitPolicy };
-        break;
+  const values = [];
+  for (const row of insert.rows) {
+    const rowValues = {};
+    const rowColumns = /* @__PURE__ */ new Set();
+    for (const assignment of row) {
+      rowColumns.add(assignment.column);
+      assignMutationValue(rowValues, assignment.column, assignment.value, ctx);
+    }
+    for (const col of allColumns) {
+      if (!rowColumns.has(col)) {
+        rowValues[col] = void 0;
       }
     }
+    values.push(rowValues);
   }
-  if (select && select.type === "expressions") {
-    const relationPaths = /* @__PURE__ */ new Set();
-    for (const expr of select.columns) {
-      if (expr.kind === "relationColumn") {
-        relationPaths.add(expr.relation);
-      }
-    }
-    if (relationPaths.size > 0) {
-      const nestedIncludes = buildNestedIncludes(relationPaths, flatMode);
-      for (const inc of nestedIncludes) {
-        const exists = allIncludes.some(
-          (existing) => existing.relation === inc.relation
-        );
-        if (!exists) {
-          allIncludes.push(inc);
-        }
-      }
-    }
-  }
-  if (flatMode && allIncludes.length > 0) {
-    for (let i = 0; i < allIncludes.length; i++) {
-      const inc = allIncludes[i];
-      if (!inc.strategy) {
-        allIncludes[i] = { ...inc, strategy: "flat" };
-      }
-    }
-  }
-  if (includeLimits.size > 0) {
-    for (const [relation, limitCount] of includeLimits) {
-      const rootRelation = relation.split(".")[0];
-      const targetInclude = allIncludes.find(
-        (inc) => inc.relation === rootRelation
-      );
-      if (!targetInclude) {
-        throw new Error(
-          `limit for relation '${relation}' specified but '${rootRelation}' is not included in the query`
-        );
-      }
-      applyIncludeLimit(allIncludes, relation, limitCount);
-    }
-  }
-  const include = allIncludes.length > 0 ? allIncludes : void 0;
-  let where;
-  if (whereConditions.length === 1) {
-    where = whereConditions[0];
-  } else if (whereConditions.length > 1) {
-    where = { kind: "and", conditions: whereConditions };
-  }
-  let having;
-  if (havingConditions.length === 1) {
-    having = havingConditions[0];
-  } else if (havingConditions.length > 1) {
-    having = { kind: "and", conditions: havingConditions };
+  return {
+    type: "insert",
+    table: insert.table,
+    values
+  };
+}
+function compileInsertFrom(insertFrom, ctx, fns, bindings) {
+  ctx.validator?.validateTable(insertFrom.table);
+  const sourceQuery = bindings?.get(insertFrom.source);
+  if (!sourceQuery) {
+    ctx.validator?.validateTable(insertFrom.source);
   }
+  ctx.currentFromTable = insertFrom.source;
   return {
-    type: "select",
-    from: query.table,
-    ...select !== void 0 && { select },
-    ...where !== void 0 && { where },
-    ...include !== void 0 && { include },
-    ...orderBy !== void 0 && { orderBy },
-    ...groupBy !== void 0 && { groupBy },
-    ...having !== void 0 && { having },
-    ...distinct !== void 0 && { distinct },
-    ...limit !== void 0 && { limit },
-    ...offset !== void 0 && { offset },
-    ...lock !== void 0 && { lock }
+    type: "insert_from",
+    table: insertFrom.table,
+    source: insertFrom.source,
+    ...sourceQuery !== void 0 && { sourceQuery },
+    /* v8 ignore next — NQL grammar does not produce explicit column lists for INSERT FROM -- @preserve */
+    ...insertFrom.columns !== void 0 && { columns: insertFrom.columns },
+    ...insertFrom.where !== void 0 && {
+      where: fns.compileExpression(insertFrom.where, ctx, fns)
+    },
+    ...insertFrom.limit !== void 0 && {
+      limit: resolveIntegerCount(insertFrom.limit, ctx, "insert-from limit")
+    }
   };
 }
-function getExplicitColumnCount(intent) {
-  if ("kind" in intent && intent.kind === "setOperation") {
-    return getExplicitColumnCount(intent.left);
+function compileUpdate(update, ctx, fns, bindings) {
+  ctx.currentFromTable = update.table;
+  ctx.validator?.validateTable(update.table);
+  const set = {};
+  for (const assignment of update.assignments) {
+    ctx.validator?.validateColumn(update.table, assignment.column);
+    assignMutationValue(set, assignment.column, assignment.value, ctx);
   }
-  const q = intent;
-  if (!q.select) return void 0;
-  switch (q.select.type) {
-    case "all":
-      return void 0;
-    /* v8 ignore next — NQL compiler never produces 'fields' in set operations (always expressions or all) -- @preserve */
-    case "fields":
-      return q.select.fields.length;
-    /* v8 ignore next — NQL compiler never produces 'aggregate' SelectIntent directly -- @preserve */
-    case "aggregate":
-      return (q.select.fields?.length ?? 0) + q.select.aggregates.length;
-    case "expressions":
-      return q.select.columns.length;
-    /* v8 ignore next — defensive: exhaustive switch -- @preserve */
-    default:
-      return void 0;
+  if (update.where) {
+    return {
+      type: "update",
+      table: update.table,
+      set,
+      where: resolveBindingsInWhere(
+        fns.compileExpression(update.where, ctx, fns),
+        bindings
+      )
+    };
   }
-}
-function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
-  const setClause = query.clauses[setClauseIndex];
-  if (setClauseIndex < query.clauses.length - 1) {
-    const trailingTypes = query.clauses.slice(setClauseIndex + 1).map((c) => c.type).join(", ");
+  if (!ctx.allowUnfilteredMutations) {
     throw new Error(
-      `Clauses after a set operation are not supported (found: ${trailingTypes}). Wrap the set operation in a subquery or move the clause before the set operation.`
+      "update without a where clause would affect all rows; pass { allowUnfilteredMutations: true } to the compiler to allow an unfiltered update"
     );
   }
-  const leftQuery = {
-    table: query.table,
-    clauses: query.clauses.slice(0, setClauseIndex)
+  return {
+    type: "update",
+    table: update.table,
+    set,
+    allowAll: true
   };
-  const left = compileQuery(leftQuery, ctx, fns, bindings);
-  let right;
-  if (setClause.right) {
-    right = compileNestedQuery(setClause.right, ctx, fns, bindings);
-  } else if (setClause.boundName) {
-    const bound = bindings?.get(setClause.boundName);
-    if (!bound) {
-      throw new Error(
-        `Set operation references unbound name '${setClause.boundName}'. Use | bind ${setClause.boundName} in a preceding statement.`
-      );
-    }
-    right = bound;
-  } else {
-    throw new Error("Set operation missing right operand");
+}
+function compileDelete(del, ctx, fns, bindings) {
+  ctx.currentFromTable = del.table;
+  ctx.validator?.validateTable(del.table);
+  if (del.where) {
+    return {
+      type: "delete",
+      table: del.table,
+      where: resolveBindingsInWhere(
+        fns.compileExpression(del.where, ctx, fns),
+        bindings
+      )
+    };
   }
-  const leftCount = getExplicitColumnCount(left);
-  const rightCount = getExplicitColumnCount(right);
-  if (leftCount !== void 0 && rightCount !== void 0 && leftCount !== rightCount) {
+  if (!ctx.allowUnfilteredMutations) {
     throw new Error(
-      `${setClause.op.toUpperCase()} requires both sides to have the same number of columns (left: ${leftCount}, right: ${rightCount})`
+      "delete without a where clause would affect all rows; pass { allowUnfilteredMutations: true } to the compiler to allow an unfiltered delete"
     );
   }
   return {
-    kind: "setOperation",
-    op: setClause.op,
-    all: setClause.all,
-    left,
-    right
+    type: "delete",
+    table: del.table,
+    allowAll: true
   };
 }
-function compileGroupByClause(clause, ctx) {
-  return clause.expressions.map((expr) => {
-    if (expr.type === "path") {
-      const field = expr.segments.join(".");
-      if (ctx.currentFromTable && !field.includes(".")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, field);
+function compileUpsert(upsert, ctx, fns, bindings) {
+  ctx.currentFromTable = upsert.table;
+  ctx.validator?.validateTable(upsert.table);
+  const values = {};
+  for (const assignment of upsert.assignments) {
+    ctx.validator?.validateColumn(upsert.table, assignment.column);
+    assignMutationValue(values, assignment.column, assignment.value, ctx);
+  }
+  for (const col of upsert.conflictColumns) {
+    ctx.validator?.validateColumn(upsert.table, col);
+  }
+  return {
+    type: "upsert",
+    table: upsert.table,
+    values: [values],
+    onConflict: { columns: upsert.conflictColumns },
+    action: {
+      type: "doUpdate",
+      set: values,
+      ...upsert.where !== void 0 && {
+        where: resolveBindingsInWhere(
+          fns.compileExpression(upsert.where, ctx, fns),
+          bindings
+        )
       }
-      return field;
     }
-    return expressionToSql(expr);
-  });
-}
-function compileOrderByClause(clause, ctx) {
-  return clause.items.map((item) => compileOrderItem(item, ctx));
+  };
 }
-function compileOrderItem(item, ctx) {
-  const field = expressionToField(item.expression);
-  if (field) {
-    if (ctx.currentFromTable && !field.includes(".") && !field.includes("(")) {
-      ctx.validator?.validateColumn(ctx.currentFromTable, field);
-    }
-    return { field, direction: item.direction };
+function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
+  ctx.validator?.validateTable(upsertFrom.table);
+  const sourceQuery = bindings?.get(upsertFrom.source);
+  if (!sourceQuery) {
+    ctx.validator?.validateTable(upsertFrom.source);
   }
-  if (item.expression.type === "namedParam") {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      `Named parameter :${item.expression.name} cannot be used as an ORDER BY expression because ORDER BY is query structure, not a value`,
-      void 0,
-      'Choose a trusted structural path for dynamic ordering, such as nqlRaw("order by ...") or the query builder after validating the requested column and direction.'
-    );
+  for (const col of upsertFrom.conflictColumns) {
+    ctx.validator?.validateColumn(upsertFrom.table, col);
   }
-  const sqlExpr = expressionToSql(item.expression);
-  return { field: sqlExpr, direction: item.direction };
-}
-
-// src/compiler/compile-cte.ts
-function compileWithQuery(astNode, ctx, fns) {
-  const cteNames = /* @__PURE__ */ new Set();
-  for (const cte of astNode.ctes) {
-    if (cteNames.has(cte.name)) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_DUPLICATE_BINDING,
-        `Duplicate CTE name: '${cte.name}'. Each CTE must have a unique name.`
-      );
+  ctx.currentFromTable = upsertFrom.source;
+  return {
+    type: "upsert_from",
+    table: upsertFrom.table,
+    source: upsertFrom.source,
+    conflictColumns: upsertFrom.conflictColumns,
+    ...sourceQuery !== void 0 && { sourceQuery },
+    /* v8 ignore start — NQL grammar does not produce explicit column lists for UPSERT FROM -- @preserve */
+    ...upsertFrom.columns !== void 0 && {
+      columns: upsertFrom.columns
+    },
+    /* v8 ignore stop -- @preserve */
+    ...upsertFrom.where !== void 0 && {
+      where: fns.compileExpression(upsertFrom.where, ctx, fns)
+    },
+    ...upsertFrom.limit !== void 0 && {
+      limit: resolveIntegerCount(upsertFrom.limit, ctx, "upsert-from limit")
+    }
+  };
+}
+function extractReturningColumns(clause, ctx) {
+  const columns = [];
+  for (const item of clause.items) {
+    if (item.type === "star") {
+      return ["*"];
+    }
+    if (item.type === "expression") {
+      const field = expressionToField(item.expression);
+      if (field) {
+        if (ctx.currentFromTable && !field.includes(".")) {
+          ctx.validator?.validateColumn(ctx.currentFromTable, field);
+        }
+        columns.push(item.alias ?? field);
+      }
     }
-    cteNames.add(cte.name);
   }
-  ctx.validator?.addKnownCteTables(cteNames);
-  try {
-    const ctes = [];
-    for (const cte of astNode.ctes) {
-      const bodyResult = compileNestedQuery(cte.query, ctx, fns);
-      if ("kind" in bodyResult && bodyResult.kind === "setOperation") {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_UNKNOWN_TABLE,
-          `Set operations (union/intersect/except) in CTE body are not supported yet. Found in CTE '${cte.name}'.`
-        );
+  return columns;
+}
+function resolveBindingsInWhere(where, bindings) {
+  if (!bindings || bindings.size === 0) return where;
+  if (where.kind === "in") {
+    const inWhere = where;
+    const inValues = inWhere.subquery ? void 0 : inWhere.values;
+    if (inValues && inValues.length === 1) {
+      const val = inValues[0];
+      if (!isParamIntent(val) && isNqlBindingRef(val)) {
+        const ref = getNqlBindingRefName(val);
+        if (bindings.has(ref)) {
+          const boundQuery = bindings.get(ref);
+          const boundSelect = boundQuery.select;
+          const selectFields = boundSelect && "fields" in boundSelect ? boundSelect.fields : void 0;
+          const cteRef = {
+            type: "select",
+            from: ref,
+            ...selectFields && {
+              select: {
+                type: "fields",
+                fields: selectFields
+              }
+            }
+          };
+          return {
+            kind: "in",
+            field: inWhere.field,
+            subquery: cteRef
+          };
+        }
       }
-      ctes.push({
-        kind: "simpleCte",
-        name: cte.name,
-        query: bodyResult
-      });
     }
-    const outerResult = compileQuery(astNode.query, ctx, fns);
-    if ("kind" in outerResult && outerResult.kind === "setOperation") {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_UNKNOWN_TABLE,
-        "Set operations in the outer query of a WITH clause are not supported yet."
-      );
+    return where;
+  }
+  if (where.kind === "not") {
+    const notWhere = where;
+    const resolved = resolveBindingsInWhere(notWhere.condition, bindings);
+    return resolved === notWhere.condition ? where : { kind: "not", condition: resolved };
+  }
+  if (where.kind === "and" || where.kind === "or") {
+    const compound = where;
+    const resolved = compound.conditions.map(
+      (c) => resolveBindingsInWhere(c, bindings)
+    );
+    const changed = resolved.some((r, i) => r !== compound.conditions[i]);
+    return changed ? { kind: compound.kind, conditions: resolved } : where;
+  }
+  return where;
+}
+function extractBindName(stmt) {
+  if (stmt.type === "query") {
+    for (const clause of stmt.clauses) {
+      if (clause.type === "bind") return clause.name;
+    }
+  } else if (stmt.type === "mutationPipeline") {
+    for (const clause of stmt.clauses) {
+      if (clause.type === "bind") return clause.name;
     }
-    const cteQueryIntent = {
-      kind: "cteQuery",
-      ctes,
-      query: outerResult
-    };
-    return { cteQuery: cteQueryIntent };
-  } finally {
-    ctx.validator?.clearKnownCteTables();
   }
+  return void 0;
 }
 
-// src/compiler/date-range-patterns.ts
-var DATE_RANGE_YEAR = /^(\d{4})$/;
-var DATE_RANGE_QUARTER = /^(\d{4})-Q([1-4])$/;
-var DATE_RANGE_MONTH = /^(\d{4})-(\d{2})$/;
-var DATE_RANGE_WEEK = /^(\d{4})-W(\d{2})$/;
-function isDateRangePattern(value) {
-  return DATE_RANGE_YEAR.test(value) || DATE_RANGE_QUARTER.test(value) || DATE_RANGE_MONTH.test(value) || DATE_RANGE_WEEK.test(value);
-}
-var InvalidDateRangeError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidDateRangeError";
-  }
-};
-function expandDateRange(pattern) {
-  let match;
-  match = pattern.match(DATE_RANGE_YEAR);
-  if (match) {
-    const year = Number(match[1]);
-    return {
-      start: `${year}-01-01`,
-      end: `${year + 1}-01-01`
-    };
+// src/compiler/include-builder.ts
+function buildNestedIncludes(paths, flatMode) {
+  const root = { children: /* @__PURE__ */ new Map() };
+  for (const path of paths) {
+    const segments = path.split(".");
+    let node = root;
+    for (const segment of segments) {
+      if (!node.children.has(segment)) {
+        node.children.set(segment, { children: /* @__PURE__ */ new Map() });
+      }
+      node = node.children.get(segment);
+    }
   }
-  match = pattern.match(DATE_RANGE_QUARTER);
-  if (match) {
-    const year = Number(match[1]);
-    const quarter = Number(match[2]);
-    const startMonth = (quarter - 1) * 3 + 1;
-    const endMonth = startMonth + 3;
-    if (endMonth > 12) {
-      return {
-        start: `${year}-${pad(startMonth)}-01`,
-        end: `${year + 1}-01-01`
+  function treeToIncludes(node) {
+    const includes = [];
+    for (const [relation, child] of node.children) {
+      const childIncludes = treeToIncludes(child);
+      const include = {
+        relation,
+        ...flatMode ? { strategy: "flat" } : {},
+        ...childIncludes.length > 0 ? { include: childIncludes } : {}
       };
+      includes.push(include);
     }
-    return {
-      start: `${year}-${pad(startMonth)}-01`,
-      end: `${year}-${pad(endMonth)}-01`
+    return includes;
+  }
+  return treeToIncludes(root);
+}
+function applyIncludeLimit(includes, path, limit) {
+  const segments = path.split(".");
+  const root = segments[0];
+  const idx = includes.findIndex((inc) => inc.relation === root);
+  if (idx === -1) return;
+  if (segments.length === 1) {
+    includes[idx] = {
+      ...includes[idx],
+      limit,
+      strategy: "flat"
     };
+  } else {
+    const nested = [...includes[idx]?.include ?? []];
+    applyIncludeLimit(nested, segments.slice(1).join("."), limit);
+    includes[idx] = { ...includes[idx], strategy: "flat", include: nested };
   }
-  match = pattern.match(DATE_RANGE_MONTH);
-  if (match) {
-    const year = Number(match[1]);
-    const month = Number(match[2]);
-    if (month < 1 || month > 12) {
-      throw new InvalidDateRangeError(
-        `Invalid month '${match[2]}' in date range '${pattern}' \u2014 must be 01-12`
-      );
+}
+
+// src/compiler/compile-query.ts
+var activeBindingScopes = /* @__PURE__ */ new WeakMap();
+var PORTABLE_BINDING_FINAL_FUNCTIONS = /* @__PURE__ */ new Set([
+  ...NQL_SELECT_AGGREGATE_FUNCTIONS,
+  ...NQL_SELECT_VALUE_FUNCTIONS
+]);
+function compileNestedQuery(query, ctx, fns, bindings) {
+  const savedContext = {
+    currentFromTable: ctx.currentFromTable,
+    currentRelationTarget: ctx.currentRelationTarget,
+    currentHavingAliases: ctx.currentHavingAliases
+  };
+  try {
+    const nestedBindings = bindings ?? activeBindingScopes.get(ctx);
+    if (nestedBindings) {
+      return compileQuery(query, ctx, fns, nestedBindings);
     }
-    if (month === 12) {
-      return {
-        start: `${year}-12-01`,
-        end: `${year + 1}-01-01`
-      };
+    return fns.compileQuery(query, ctx);
+  } finally {
+    ctx.currentFromTable = savedContext.currentFromTable;
+    ctx.currentRelationTarget = savedContext.currentRelationTarget;
+    ctx.currentHavingAliases = savedContext.currentHavingAliases;
+  }
+}
+function compileQuery(query, ctx, fns, bindings) {
+  const hadPreviousBindingScope = activeBindingScopes.has(ctx);
+  const previousBindingScope = activeBindingScopes.get(ctx);
+  if (bindings) {
+    activeBindingScopes.set(ctx, bindings);
+  }
+  try {
+    return compileQueryInternal(query, ctx, fns, bindings);
+  } finally {
+    if (hadPreviousBindingScope && previousBindingScope) {
+      activeBindingScopes.set(ctx, previousBindingScope);
+    } else {
+      activeBindingScopes.delete(ctx);
     }
-    return {
-      start: `${year}-${pad(month)}-01`,
-      end: `${year}-${pad(month + 1)}-01`
-    };
   }
-  match = pattern.match(DATE_RANGE_WEEK);
-  if (match) {
-    const year = Number(match[1]);
-    const week = Number(match[2]);
-    const maxWeeks = getISOWeekCount(year);
-    if (week < 1 || week > maxWeeks) {
-      throw new InvalidDateRangeError(
-        `Invalid week 'W${match[2]}' in date range '${pattern}' \u2014 year ${year} has ${maxWeeks} ISO weeks`
-      );
+}
+function collectSelectAliasesFromQuery(query) {
+  const aliases = /* @__PURE__ */ new Set();
+  for (const clause of query.clauses) {
+    if (clause.type !== "select") continue;
+    for (const item of clause.items) {
+      if (item.type === "expression" && item.alias) {
+        aliases.add(item.alias);
+      }
     }
-    const start = isoWeekToDate(year, week);
-    const end = addDays(start, 7);
-    return {
-      start: formatDate(start),
-      end: formatDate(end)
-    };
   }
-  throw new InvalidDateRangeError(
-    `Invalid date range '${pattern}' \u2014 expected YYYY, YYYY-QN, YYYY-MM, or YYYY-WNN`
+  return aliases;
+}
+function throwUnsupportedBindingFinal(bindingName, feature) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot use ${feature} in a binding-final query (#183). Binding-final queries are restricted to portable common-ground SQL over projected binding columns: SELECT (including plain DISTINCT), WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET, and UNION/INTERSECT/EXCEPT.`
   );
 }
-function pad(n) {
-  return n < 10 ? `0${n}` : `${n}`;
+function validateBindingFinalPath(expr, ctx, bindingName) {
+  const { segments } = expr;
+  if (segments.length === 1) {
+    if (ctx.currentHavingAliases?.has(segments[0])) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `HAVING cannot reference SELECT alias '${segments[0]}'. PostgreSQL does not allow SELECT aliases in HAVING; repeat the aggregate expression or filter the result in an outer query.`
+      );
+    }
+    validateColumnForTable(ctx, bindingName, segments[0]);
+    return;
+  }
+  const firstSegment = segments[0];
+  if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      bindingName,
+      "use pseudo-column traversals",
+      firstSegment
+    );
+    return;
+  }
+  assertNoBindingRelationPath(ctx, bindingName, segments.join("."));
 }
-function formatDate(d) {
-  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+function validateBindingFinalFunction(expr, ctx, bindingName) {
+  const fn = expr.name.toLowerCase();
+  if (!PORTABLE_BINDING_FINAL_FUNCTIONS.has(fn)) {
+    throwUnsupportedBindingFinal(bindingName, `function ${expr.name}()`);
+  }
+  for (const arg of expr.args) {
+    validateBindingFinalExpression(arg, ctx, bindingName);
+  }
 }
-function addDays(d, days) {
-  const result = new Date(d.getTime());
-  result.setUTCDate(result.getUTCDate() + days);
-  return result;
-}
-function isoWeekToDate(year, week) {
-  const jan4 = new Date(Date.UTC(year, 0, 4));
-  const jan4Dow = jan4.getUTCDay() || 7;
-  const mondayW1 = new Date(jan4.getTime());
-  mondayW1.setUTCDate(jan4.getUTCDate() - (jan4Dow - 1));
-  const result = new Date(mondayW1.getTime());
-  result.setUTCDate(mondayW1.getUTCDate() + (week - 1) * 7);
-  return result;
+function validateBindingFinalExpression(expr, ctx, bindingName) {
+  switch (expr.type) {
+    case "path":
+      validateBindingFinalPath(expr, ctx, bindingName);
+      break;
+    case "binary":
+      validateBindingFinalExpression(expr.left, ctx, bindingName);
+      validateBindingFinalExpression(expr.right, ctx, bindingName);
+      break;
+    case "unary":
+      validateBindingFinalExpression(expr.operand, ctx, bindingName);
+      break;
+    case "comparison":
+      validateBindingFinalExpression(expr.left, ctx, bindingName);
+      validateBindingFinalExpression(expr.right, ctx, bindingName);
+      break;
+    case "in":
+      validateBindingFinalExpression(expr.expression, ctx, bindingName);
+      if (Array.isArray(expr.values)) {
+        for (const value of expr.values) {
+          validateBindingFinalExpression(value, ctx, bindingName);
+        }
+      } else if (expr.values.type === "dateRange") ; else ;
+      break;
+    case "between":
+      validateBindingFinalExpression(expr.expression, ctx, bindingName);
+      validateBindingFinalExpression(expr.low, ctx, bindingName);
+      validateBindingFinalExpression(expr.high, ctx, bindingName);
+      break;
+    case "isNull":
+      validateBindingFinalExpression(expr.expression, ctx, bindingName);
+      break;
+    case "function":
+      validateBindingFinalFunction(expr, ctx, bindingName);
+      break;
+    case "case":
+      if (expr.subject) {
+        validateBindingFinalExpression(expr.subject, ctx, bindingName);
+      }
+      for (const when of expr.whenClauses) {
+        validateBindingFinalExpression(when.condition, ctx, bindingName);
+        validateBindingFinalExpression(when.result, ctx, bindingName);
+      }
+      if (expr.elseClause) {
+        validateBindingFinalExpression(expr.elseClause, ctx, bindingName);
+      }
+      break;
+    case "relationFilter":
+      assertNoBindingRelationConstruct(
+        ctx,
+        bindingName,
+        "use relation filters",
+        expr.relation.join(".")
+      );
+      break;
+    case "any":
+      throwUnsupportedBindingFinal(bindingName, "ANY(:param)");
+      break;
+    case "rangeOp":
+    case "rangeLiteral":
+      throwUnsupportedBindingFinal(bindingName, "PostgreSQL range operators");
+      break;
+    case "jsonAccess":
+    case "jsonComparison":
+      throwUnsupportedBindingFinal(bindingName, "PostgreSQL JSON operators");
+      break;
+    case "window":
+      throwUnsupportedBindingFinal(bindingName, "window functions");
+      break;
+    case "exists":
+      throwUnsupportedBindingFinal(bindingName, "EXISTS subqueries");
+      break;
+    case "subquery":
+      throwUnsupportedBindingFinal(bindingName, "scalar subqueries");
+      break;
+    case "variable":
+      throwUnsupportedBindingFinal(bindingName, `variable '${expr.name}'`);
+      break;
+    case "namedParam":
+    case "string":
+    case "number":
+    case "boolean":
+    case "null":
+    case "dateRange":
+      break;
+    /* v8 ignore next — defensive: default-reject future expression shapes in binding-final queries -- @preserve */
+    default:
+      throwUnsupportedBindingFinal(
+        bindingName,
+        `expression type '${expr.type ?? "unknown"}'`
+      );
+  }
 }
-function getISOWeekCount(year) {
-  const jan1 = new Date(Date.UTC(year, 0, 1));
-  const dec31 = new Date(Date.UTC(year, 11, 31));
-  const jan1Dow = jan1.getUTCDay();
-  const dec31Dow = dec31.getUTCDay();
-  return jan1Dow === 4 || dec31Dow === 4 ? 53 : 52;
+function validateBindingFinalSelectClause(clause, ctx, bindingName) {
+  const distinctOn = clause.distinctOn;
+  if (distinctOn !== void 0) {
+    throwUnsupportedBindingFinal(bindingName, "DISTINCT ON");
+  }
+  for (const item of clause.items) {
+    switch (item.type) {
+      case "star":
+        break;
+      case "relationStar":
+        assertNoBindingRelationConstruct(
+          ctx,
+          bindingName,
+          "select relation columns",
+          item.relation.join(".")
+        );
+        break;
+      case "expression":
+        if (item.expression.type === "path" && item.expression.segments.length > 1) {
+          const segments = item.expression.segments;
+          const firstSegment = segments[0];
+          if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
+            assertNoBindingRelationConstruct(
+              ctx,
+              bindingName,
+              "use pseudo-column traversals",
+              firstSegment
+            );
+          } else {
+            assertNoBindingRelationConstruct(
+              ctx,
+              bindingName,
+              "select relation columns",
+              segments.slice(0, -1).join(".")
+            );
+          }
+        } else {
+          validateBindingFinalExpression(item.expression, ctx, bindingName);
+        }
+        break;
+      /* v8 ignore next — defensive: default-reject future select item shapes in binding-final queries -- @preserve */
+      default:
+        throwUnsupportedBindingFinal(
+          bindingName,
+          `SELECT item type '${item.type ?? "unknown"}'`
+        );
+    }
+  }
 }
-
-// src/compiler/compile-expression.ts
-function paramValue(value) {
-  return value !== null && typeof value === "object" && value.kind === "param" ? value.value : value;
+function validateBindingFinalQuery(query, ctx) {
+  const groupByIndex = query.clauses.findIndex((c) => c.type === "groupBy");
+  const havingAliases = collectSelectAliasesFromQuery(query);
+  for (let i = 0; i < query.clauses.length; i++) {
+    const clause = query.clauses[i];
+    switch (clause.type) {
+      case "where": {
+        if (groupByIndex >= 0 && i > groupByIndex) {
+          const previousHavingAliases = ctx.currentHavingAliases;
+          ctx.currentHavingAliases = havingAliases;
+          try {
+            validateBindingFinalExpression(clause.condition, ctx, query.table);
+          } finally {
+            ctx.currentHavingAliases = previousHavingAliases;
+          }
+        } else {
+          validateBindingFinalExpression(clause.condition, ctx, query.table);
+        }
+        break;
+      }
+      case "select":
+        validateBindingFinalSelectClause(clause, ctx, query.table);
+        break;
+      case "groupBy":
+        for (const expr of clause.expressions) {
+          validateBindingFinalExpression(expr, ctx, query.table);
+        }
+        break;
+      case "orderBy":
+        for (const item of clause.items) {
+          validateBindingFinalExpression(item.expression, ctx, query.table);
+        }
+        break;
+      case "limit":
+        if (clause.relation) {
+          assertNoBindingRelationConstruct(
+            ctx,
+            query.table,
+            "use relation include limits",
+            clause.relation
+          );
+        }
+        break;
+      case "offset":
+      case "bind":
+      case "setOperation":
+        break;
+      case "flat":
+        throwUnsupportedBindingFinal(query.table, "flat relation include mode");
+        break;
+      case "lock":
+        throwUnsupportedBindingFinal(
+          query.table,
+          "row-level locks (FOR UPDATE / SKIP LOCKED), because locks over a CTE binding are silently ineffective"
+        );
+        break;
+      /* v8 ignore next — defensive: default-reject future clauses in binding-final queries -- @preserve */
+      default:
+        throwUnsupportedBindingFinal(
+          query.table,
+          `clause '${clause.type ?? "unknown"}'`
+        );
+    }
+  }
 }
-var MAX_ANY_ITEMS = 1e4;
-function compileLogical(expr, ctx, fns, aliasContext, outerAliases) {
-  if (expr.type === "binary") {
-    const binary = expr;
-    if (binary.operator === "and") {
-      return {
-        kind: "and",
-        conditions: [
-          compileExpression(binary.left, ctx, fns, aliasContext, outerAliases),
-          compileExpression(binary.right, ctx, fns, aliasContext, outerAliases)
-        ]
-      };
+function compileQueryInternal(query, ctx, fns, bindings) {
+  const bindingSource = bindings?.get(query.table);
+  const isBindingSource = bindingSource !== void 0 || isBindingTable(ctx, query.table);
+  ctx.currentFromTable = query.table;
+  ctx.validator?.validateTable(query.table);
+  if (isBindingSource) {
+    validateBindingFinalQuery(query, ctx);
+  }
+  const setClauseIndex = query.clauses.findIndex(
+    (c) => c.type === "setOperation"
+  );
+  if (setClauseIndex >= 0) {
+    return compileSetOperation(query, setClauseIndex, ctx, fns, bindings);
+  }
+  let groupByIndex = -1;
+  for (let i = 0; i < query.clauses.length; i++) {
+    if (query.clauses[i]?.type === "groupBy") {
+      groupByIndex = i;
+      break;
     }
-    if (binary.operator === "or") {
-      return {
-        kind: "or",
-        conditions: [
-          compileExpression(binary.left, ctx, fns, aliasContext, outerAliases),
-          compileExpression(binary.right, ctx, fns, aliasContext, outerAliases)
-        ]
-      };
+  }
+  const havingAliases = collectSelectAliasesFromQuery(query);
+  const whereConditions = [];
+  const havingConditions = [];
+  let select;
+  let distinct;
+  const allIncludes = [];
+  let currentIncludeBatch;
+  let groupBy;
+  let orderBy;
+  let limit;
+  let offset;
+  let flatMode = false;
+  let lock;
+  const includeLimits = /* @__PURE__ */ new Map();
+  for (let i = 0; i < query.clauses.length; i++) {
+    const clause = query.clauses[i];
+    switch (clause.type) {
+      case "where": {
+        if (groupByIndex >= 0 && i > groupByIndex) {
+          const previousHavingAliases = ctx.currentHavingAliases;
+          ctx.currentHavingAliases = havingAliases;
+          const condition = (() => {
+            try {
+              return resolveBindingsInWhere(
+                fns.compileExpression(
+                  clause.condition,
+                  ctx,
+                  fns
+                ),
+                bindings
+              );
+            } finally {
+              ctx.currentHavingAliases = previousHavingAliases;
+            }
+          })();
+          havingConditions.push(condition);
+        } else if (currentIncludeBatch && currentIncludeBatch.length > 0) {
+          const condition = resolveBindingsInWhere(
+            fns.compileExpression(
+              clause.condition,
+              ctx,
+              fns
+            ),
+            bindings
+          );
+          const targetInclude = currentIncludeBatch[currentIncludeBatch.length - 1];
+          const mutableInclude = targetInclude;
+          if (targetInclude.where) {
+            mutableInclude.where = {
+              kind: "and",
+              conditions: [targetInclude.where, condition]
+            };
+          } else {
+            mutableInclude.where = condition;
+          }
+        } else {
+          const condition = resolveBindingsInWhere(
+            fns.compileExpression(
+              clause.condition,
+              ctx,
+              fns
+            ),
+            bindings
+          );
+          whereConditions.push(condition);
+        }
+        break;
+      }
+      case "select":
+        select = fns.compileSelectClause(clause, ctx, fns);
+        distinct = clause.distinct || void 0;
+        break;
+      case "flat":
+        flatMode = true;
+        break;
+      case "groupBy":
+        groupBy = compileGroupByClause(clause, ctx);
+        currentIncludeBatch = void 0;
+        break;
+      case "orderBy":
+        orderBy = compileOrderByClause(clause, ctx);
+        break;
+      case "limit": {
+        const lc = clause;
+        const count = resolveIntegerCount(
+          lc.count,
+          ctx,
+          lc.relation ? "per-include limit" : "limit"
+        );
+        if (lc.relation) {
+          const includeLimit = isParamIntent(count) ? count.value : count;
+          includeLimits.set(lc.relation, includeLimit);
+        } else {
+          limit = count;
+        }
+        break;
+      }
+      case "offset":
+        offset = resolveIntegerCount(
+          clause.count,
+          ctx,
+          "offset"
+        );
+        break;
+      case "lock": {
+        const lc = clause;
+        lock = { strength: lc.strength, waitPolicy: lc.waitPolicy };
+        break;
+      }
     }
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      `Unsupported binary operator in WHERE: ${binary.operator}`
-    );
   }
-  const unary = expr;
-  if (unary.operator === "not") {
-    return {
-      kind: "not",
-      condition: compileExpression(
-        unary.operand,
-        ctx,
-        fns,
-        aliasContext,
-        outerAliases
-      )
-    };
+  if (select && select.type === "expressions") {
+    const relationPaths = /* @__PURE__ */ new Set();
+    for (const expr of select.columns) {
+      if (expr.kind === "relationColumn") {
+        relationPaths.add(expr.relation);
+      }
+    }
+    if (relationPaths.size > 0) {
+      const nestedIncludes = buildNestedIncludes(relationPaths, flatMode);
+      for (const inc of nestedIncludes) {
+        const exists = allIncludes.some(
+          (existing) => existing.relation === inc.relation
+        );
+        if (!exists) {
+          allIncludes.push(inc);
+        }
+      }
+    }
+  }
+  if (flatMode && allIncludes.length > 0) {
+    for (let i = 0; i < allIncludes.length; i++) {
+      const inc = allIncludes[i];
+      if (!inc.strategy) {
+        allIncludes[i] = { ...inc, strategy: "flat" };
+      }
+    }
+  }
+  if (includeLimits.size > 0) {
+    if (isBindingSource) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${query.table}' reads from an NQL binding and cannot use relation include limits (${[...includeLimits.keys()].join(", ")}). Relation includes require a physical model table, not a CTE binding.`
+      );
+    }
+    for (const [relation, limitCount] of includeLimits) {
+      const rootRelation = relation.split(".")[0];
+      const targetInclude = allIncludes.find(
+        (inc) => inc.relation === rootRelation
+      );
+      if (!targetInclude) {
+        throw new Error(
+          `limit for relation '${relation}' specified but '${rootRelation}' is not included in the query`
+        );
+      }
+      applyIncludeLimit(allIncludes, relation, limitCount);
+    }
+  }
+  const include = allIncludes.length > 0 ? allIncludes : void 0;
+  let where;
+  if (whereConditions.length === 1) {
+    where = whereConditions[0];
+  } else if (whereConditions.length > 1) {
+    where = { kind: "and", conditions: whereConditions };
+  }
+  let having;
+  if (havingConditions.length === 1) {
+    having = havingConditions[0];
+  } else if (havingConditions.length > 1) {
+    having = { kind: "and", conditions: havingConditions };
+  }
+  const compiledQuery = {
+    type: "select",
+    from: query.table,
+    ...select !== void 0 && { select },
+    ...where !== void 0 && { where },
+    ...include !== void 0 && { include },
+    ...orderBy !== void 0 && { orderBy },
+    ...groupBy !== void 0 && { groupBy },
+    ...having !== void 0 && { having },
+    ...distinct !== void 0 && { distinct },
+    ...limit !== void 0 && { limit },
+    ...offset !== void 0 && { offset },
+    ...lock !== void 0 && { lock }
+  };
+  return compiledQuery;
+}
+function getExplicitColumnCount(intent) {
+  if ("kind" in intent && intent.kind === "setOperation") {
+    return getExplicitColumnCount(intent.left);
   }
+  const q = intent;
+  if (!q.select) return void 0;
+  switch (q.select.type) {
+    case "all":
+      return void 0;
+    /* v8 ignore next — NQL compiler never produces 'fields' in set operations (always expressions or all) -- @preserve */
+    case "fields":
+      return q.select.fields.length;
+    /* v8 ignore next — NQL compiler never produces 'aggregate' SelectIntent directly -- @preserve */
+    case "aggregate":
+      return (q.select.fields?.length ?? 0) + q.select.aggregates.length;
+    case "expressions":
+      return q.select.columns.length;
+    /* v8 ignore next — defensive: exhaustive switch -- @preserve */
+    default:
+      return void 0;
+  }
+}
+function expressionOutputColumn(expr) {
+  switch (expr.kind) {
+    case "column":
+      if (expr.column === "*") return void 0;
+      return expr.as ?? expr.column;
+    case "columnAlias":
+      return expr.alias;
+    case "relationColumn":
+      if (expr.column === "*") return void 0;
+      return expr.as;
+    case "aggregate":
+    case "function":
+    case "subquery":
+    case "arithmetic":
+    case "literal":
+    case "case":
+    case "jsonExtract":
+    case "jsonPathExtract":
+    case "customOp":
+    case "customFn":
+    case "array":
+    case "unary":
+    case "param":
+      return expr.as;
+    case "coalesce":
+    case "raw":
+    case "pseudoColumn":
+      return expr.as;
+    case "window":
+      return expr.alias;
+    case "comparison":
+    case "jsonContains":
+    case "jsonExists":
+    case "ref":
+    case "cast":
+    case "namedArg":
+    case "star":
+      return void 0;
+    /* v8 ignore next — defensive: exhaustive switch -- @preserve */
+    default:
+      return void 0;
+  }
+}
+function addUnique(columns, seen, column) {
+  if (seen.has(column)) return;
+  seen.add(column);
+  columns.push(column);
+}
+function resolveSourceOutputColumns(intent, ctx, bindingName) {
+  const bindingColumns2 = getKnownBindingColumns(ctx, intent.from);
+  if (bindingColumns2 !== void 0) return bindingColumns2;
+  const columns = ctx.validator?.getTableColumns(intent.from);
+  if (columns !== void 0) return columns;
   throw new NqlSemanticException(
     NqlErrorCodes.SEM_INVALID_SYNTAX,
-    `Unsupported unary operator: ${unary.operator}`
+    `Cannot compute output schema for NQL binding '${bindingName}' from SELECT * on '${intent.from}' without a concrete table schema.`
   );
 }
-function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
-  const comp = expr;
-  if (comp.left.type === "jsonAccess") {
-    const jsonLeft = comp.left;
-    const baseField = expressionToField(jsonLeft.base, aliasContext);
-    if (!baseField) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        "JSON access base must be a field reference"
-      );
+function getQueryOutputSchema(intent, ctx, bindingName) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addColumn = (column) => addUnique(columns, seen, column);
+  const addSourceColumns = () => {
+    for (const column of resolveSourceOutputColumns(intent, ctx, bindingName)) {
+      addColumn(column);
     }
-    const operator2 = mapComparisonOperator(comp.operator);
-    const value2 = resolveFilterValue(
-      comp.right,
-      ctx,
-      aliasContext,
-      outerAliases
-    );
-    const intent2 = {
-      kind: "comparison",
-      field: baseField,
-      operator: operator2,
-      value: value2,
-      jsonPath: jsonLeft.path,
-      jsonMode: jsonLeft.mode
-    };
-    return intent2;
+  };
+  const { select } = intent;
+  if (!select || select.type === "all") {
+    addSourceColumns();
+    return { columns };
+  }
+  if (select.type === "fields") {
+    for (const field of select.fields) {
+      if (field === "*") {
+        addSourceColumns();
+      } else {
+        addColumn(field);
+      }
+    }
+    return { columns };
   }
-  if (comp.left.type === "function") {
-    const fn = comp.left.name.toLowerCase();
-    if (fn === "json_extract" || fn === "json_extract_text") {
-      if (comp.left.args.length < 2) {
+  if (select.type === "aggregate") {
+    for (const field of select.fields ?? []) {
+      addColumn(field);
+    }
+    for (const aggregate of select.aggregates) {
+      if (!aggregate.as) {
         throw new NqlSemanticException(
           NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() requires at least 2 arguments`
+          `Cannot compute output schema for NQL binding '${bindingName}': aggregate '${aggregate.function}' must use an alias.`
         );
       }
-      const baseField = expressionToField(comp.left.args[0], aliasContext);
-      if (!baseField) {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() first argument must be a field reference`
+      addColumn(aggregate.as);
+    }
+    return { columns };
+  }
+  for (const expr of select.columns) {
+    if (expr.kind === "column" && expr.column === "*") {
+      addSourceColumns();
+      continue;
+    }
+    if (expr.kind === "relationColumn" && expr.column === "*") {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindingName}' from relation SELECT * '${expr.relation}.*'. Use explicit aliases for binding outputs.`
+      );
+    }
+    const outputColumn = expressionOutputColumn(expr);
+    if (!outputColumn) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindingName}': selected expression must use an alias.`
+      );
+    }
+    addColumn(outputColumn);
+  }
+  return { columns };
+}
+function validateNqlExpressionPaths(expr, ctx) {
+  switch (expr.type) {
+    case "path":
+      if (expr.segments.length === 1) {
+        if (ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+          validateColumnForTable(ctx, ctx.currentFromTable, expr.segments[0]);
+        }
+      } else if (ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+        assertNoBindingRelationPath(
+          ctx,
+          ctx.currentFromTable,
+          expr.segments.join(".")
         );
       }
-      const keys = comp.left.args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`, ctx));
-      const operator2 = mapComparisonOperator(comp.operator);
-      const value2 = resolveFilterValue(
-        comp.right,
+      break;
+    case "binary":
+      validateNqlExpressionPaths(expr.left, ctx);
+      validateNqlExpressionPaths(expr.right, ctx);
+      break;
+    case "unary":
+      validateNqlExpressionPaths(expr.operand, ctx);
+      break;
+    case "comparison":
+    case "jsonComparison":
+      validateNqlExpressionPaths(expr.left, ctx);
+      validateNqlExpressionPaths(expr.right, ctx);
+      break;
+    case "rangeOp":
+      validateNqlExpressionPaths(expr.left, ctx);
+      if (expr.scalar) {
+        validateNqlExpressionPaths(expr.scalar, ctx);
+      }
+      break;
+    case "in":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      if (Array.isArray(expr.values)) {
+        for (const value of expr.values) {
+          validateNqlExpressionPaths(value, ctx);
+        }
+      }
+      break;
+    case "any":
+      validateNqlExpressionPaths(expr.column, ctx);
+      break;
+    case "between":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      validateNqlExpressionPaths(expr.low, ctx);
+      validateNqlExpressionPaths(expr.high, ctx);
+      break;
+    case "isNull":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      break;
+    case "function":
+      for (const arg of expr.args) {
+        validateNqlExpressionPaths(arg, ctx);
+      }
+      break;
+    case "window":
+      for (const arg of expr.args) {
+        validateNqlExpressionPaths(arg, ctx);
+      }
+      for (const item of expr.orderBy) {
+        validateNqlExpressionPaths(item.expression, ctx);
+      }
+      for (const partitionBy of expr.partitionBy) {
+        validateNqlExpressionPaths(partitionBy, ctx);
+      }
+      break;
+    case "case":
+      if (expr.subject) {
+        validateNqlExpressionPaths(expr.subject, ctx);
+      }
+      for (const when of expr.whenClauses) {
+        validateNqlExpressionPaths(when.condition, ctx);
+        validateNqlExpressionPaths(when.result, ctx);
+      }
+      if (expr.elseClause) {
+        validateNqlExpressionPaths(expr.elseClause, ctx);
+      }
+      break;
+    case "jsonAccess":
+      validateNqlExpressionPaths(expr.base, ctx);
+      break;
+    case "relationFilter":
+      assertNoBindingRelationConstruct(
         ctx,
-        aliasContext,
-        outerAliases
+        ctx.currentFromTable,
+        "use relation filters",
+        expr.relation.join(".")
       );
-      const intent2 = {
-        kind: "comparison",
-        field: baseField,
-        operator: operator2,
-        value: value2,
-        jsonPath: keys,
-        jsonMode: fn === "json_extract" ? "json" : "text"
-      };
-      return intent2;
-    }
-  }
-  const field = expressionToField(comp.left, aliasContext);
-  if (!field) {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "Left side of comparison must be a field reference"
-    );
-  }
-  validateWhereField(ctx, field, aliasContext, comp.left);
-  if (comp.operator === "like") {
-    const pattern = coerceToStringKey(comp.right, "LIKE pattern", ctx);
-    return {
-      kind: "like",
-      field,
-      pattern
-    };
+      break;
   }
-  const operator = mapComparisonOperator(comp.operator);
-  const value = resolveFilterValue(comp.right, ctx, aliasContext, outerAliases);
-  const intent = {
-    kind: "comparison",
-    field,
-    operator,
-    value
-  };
-  return intent;
 }
-function compileRange(expr, ctx, _fns, aliasContext, outerAliases) {
-  const rangeExpr = expr;
-  const field = expressionToField(rangeExpr.left, aliasContext);
-  if (!field) {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "Left side of range operator must be a field reference"
-    );
-  }
-  validateWhereField(ctx, field, aliasContext, rangeExpr.left);
-  let rangeValue;
-  if (rangeExpr.range) {
-    rangeValue = expressionToRangeValue(rangeExpr.range);
-  } else if (rangeExpr.scalar) {
-    rangeValue = resolveFilterValue(
-      rangeExpr.scalar,
-      ctx,
-      aliasContext,
-      outerAliases
+function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
+  const setClause = query.clauses[setClauseIndex];
+  if (setClauseIndex < query.clauses.length - 1) {
+    const trailingTypes = query.clauses.slice(setClauseIndex + 1).map((c) => c.type).join(", ");
+    throw new Error(
+      `Clauses after a set operation are not supported (found: ${trailingTypes}). Wrap the set operation in a subquery or move the clause before the set operation.`
     );
+  }
+  const leftQuery = {
+    type: "query",
+    table: query.table,
+    clauses: query.clauses.slice(0, setClauseIndex)
+  };
+  const left = compileQuery(leftQuery, ctx, fns, bindings);
+  let right;
+  if (setClause.right) {
+    right = compileNestedQuery(setClause.right, ctx, fns, bindings);
+  } else if (setClause.boundName) {
+    const bound = bindings?.get(setClause.boundName);
+    if (!bound) {
+      throw new Error(
+        `Set operation references unbound name '${setClause.boundName}'. Use | bind ${setClause.boundName} in a preceding statement.`
+      );
+    }
+    right = bound;
   } else {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "Range operator requires either a range literal or scalar value"
+    throw new Error("Set operation missing right operand");
+  }
+  const leftCount = getExplicitColumnCount(left);
+  const rightCount = getExplicitColumnCount(right);
+  if (leftCount !== void 0 && rightCount !== void 0 && leftCount !== rightCount) {
+    throw new Error(
+      `${setClause.op.toUpperCase()} requires both sides to have the same number of columns (left: ${leftCount}, right: ${rightCount})`
     );
   }
-  const result = {
-    kind: "range",
-    field,
-    operator: rangeExpr.operator,
-    value: rangeValue
+  return {
+    kind: "setOperation",
+    op: setClause.op,
+    all: setClause.all,
+    left,
+    right
   };
-  return result;
 }
-function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
-  if (expr.type === "any") {
-    const anyExpr = expr;
-    const field2 = expressionToField(anyExpr.column, aliasContext);
-    if (!field2) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        "ANY expression must reference a field"
-      );
-    }
-    validateWhereField(ctx, field2, aliasContext, anyExpr.column);
-    const valuesParam = resolveNamedParam(ctx, anyExpr.paramName);
-    const rawValues = valuesParam.value;
-    if (!Array.isArray(rawValues)) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        `ANY(:${anyExpr.paramName}) requires an array argument`
-      );
+function compileGroupByClause(clause, ctx) {
+  return clause.expressions.map((expr) => {
+    validateNqlExpressionPaths(expr, ctx);
+    if (expr.type === "path") {
+      const field = expr.segments.join(".");
+      if (ctx.currentFromTable && !field.includes(".")) {
+        validateColumnForTable(ctx, ctx.currentFromTable, field);
+      }
+      return field;
     }
-    if (rawValues.length > ctx.maxAnyItems) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        `ANY(:${anyExpr.paramName}) array length ${rawValues.length} exceeds maximum of ${ctx.maxAnyItems}`
-      );
+    return expressionToSql(expr);
+  });
+}
+function compileOrderByClause(clause, ctx) {
+  return clause.items.map((item) => compileOrderItem(item, ctx));
+}
+function compileOrderItem(item, ctx) {
+  validateNqlExpressionPaths(item.expression, ctx);
+  const field = expressionToField(item.expression);
+  if (field) {
+    if (ctx.currentFromTable && field.includes(".") && isBindingTable(ctx, ctx.currentFromTable)) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    } else if (ctx.currentFromTable && !field.includes(".") && !field.includes("(")) {
+      validateColumnForTable(ctx, ctx.currentFromTable, field);
     }
-    const result2 = {
-      kind: "any",
-      field: field2,
-      values: valuesParam
-    };
-    return result2;
+    return { field, direction: item.direction };
   }
-  const inExpr = expr;
-  const field = expressionToField(inExpr.expression, aliasContext);
-  if (!field) {
+  if (item.expression.type === "namedParam") {
     throw new NqlSemanticException(
       NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "IN expression must reference a field"
+      `Named parameter :${item.expression.name} cannot be used as an ORDER BY expression because ORDER BY is query structure, not a value`,
+      void 0,
+      'Choose a trusted structural path for dynamic ordering, such as nqlRaw("order by ...") or the query builder after validating the requested column and direction.'
     );
   }
-  validateWhereField(ctx, field, aliasContext, inExpr.expression);
-  let values;
-  if (Array.isArray(inExpr.values)) {
-    values = inExpr.values.map(
-      (v) => resolveFilterValue(v, ctx, aliasContext, outerAliases)
-    );
-    const dateRangeValues = values.filter(
-      (v) => typeof v === "string" && isDateRangePattern(v)
-    );
-    if (dateRangeValues.length > 0) {
-      if (dateRangeValues.length !== values.length) {
+  const sqlExpr = expressionToSql(item.expression);
+  return { field: sqlExpr, direction: item.direction };
+}
+
+// src/compiler/compile-cte.ts
+function compileWithQuery(astNode, ctx, fns) {
+  const cteNames = /* @__PURE__ */ new Set();
+  for (const cte of astNode.ctes) {
+    if (cteNames.has(cte.name)) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_DUPLICATE_BINDING,
+        `Duplicate CTE name: '${cte.name}'. Each CTE must have a unique name.`
+      );
+    }
+    cteNames.add(cte.name);
+  }
+  ctx.validator?.addKnownCteTables(cteNames);
+  try {
+    const ctes = [];
+    for (const cte of astNode.ctes) {
+      const bodyResult = compileNestedQuery(cte.query, ctx, fns);
+      if ("kind" in bodyResult && bodyResult.kind === "setOperation") {
         throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          "Cannot mix date range patterns with regular values in IN list. Use all date ranges or all literals."
+          NqlErrorCodes.SEM_UNKNOWN_TABLE,
+          `Set operations (union/intersect/except) in CTE body are not supported yet. Found in CTE '${cte.name}'.`
         );
       }
-      return expandDateRangeList(field, dateRangeValues, inExpr.negated);
+      ctes.push({
+        kind: "simpleCte",
+        name: cte.name,
+        query: bodyResult
+      });
     }
-  } else if ("type" in inExpr.values && inExpr.values.type === "subquery") {
-    const subquery = compileNestedQuery(
-      inExpr.values.query,
-      ctx,
-      fns
-    );
-    const result2 = {
-      kind: "in",
-      field,
-      subquery
-    };
-    if (inExpr.negated) {
-      return { kind: "not", condition: result2 };
+    const outerResult = compileQuery(astNode.query, ctx, fns);
+    if ("kind" in outerResult && outerResult.kind === "setOperation") {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_UNKNOWN_TABLE,
+        "Set operations in the outer query of a WITH clause are not supported yet."
+      );
     }
-    return result2;
-  } else if ("type" in inExpr.values && inExpr.values.type === "dateRange") {
-    return expandDateRangeList(field, [inExpr.values.value], inExpr.negated);
-  } else {
-    values = [];
-  }
-  const result = {
-    kind: "in",
-    field,
-    values
-  };
-  if (inExpr.negated) {
-    return { kind: "not", condition: result };
+    const cteQueryIntent = {
+      kind: "cteQuery",
+      ctes,
+      query: outerResult
+    };
+    return { cteQuery: cteQueryIntent };
+  } finally {
+    ctx.validator?.clearKnownCteTables();
   }
-  return result;
 }
-function compileBetween(expr, ctx, _fns, aliasContext, outerAliases) {
-  const between = expr;
-  const field = expressionToField(between.expression, aliasContext);
-  if (!field) {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "BETWEEN expression must reference a field"
-    );
-  }
-  validateWhereField(ctx, field, aliasContext, between.expression);
-  const lower = resolveFilterValue(
-    between.low,
-    ctx,
-    aliasContext,
-    outerAliases
-  );
-  const upper = resolveFilterValue(
-    between.high,
-    ctx,
-    aliasContext,
-    outerAliases
-  );
-  const lowerValue = paramValue(lower);
-  const upperValue = paramValue(upper);
-  assertBetweenBoundValueAllowed("lower", between.low, lowerValue);
-  assertBetweenBoundValueAllowed("upper", between.high, upperValue);
-  const value = { lower, upper };
-  return {
-    kind: "range",
-    field,
-    operator: "between",
-    value
-  };
+
+// src/compiler/date-range-patterns.ts
+var DATE_RANGE_YEAR = /^(\d{4})$/;
+var DATE_RANGE_QUARTER = /^(\d{4})-Q([1-4])$/;
+var DATE_RANGE_MONTH = /^(\d{4})-(\d{2})$/;
+var DATE_RANGE_WEEK = /^(\d{4})-W(\d{2})$/;
+function isDateRangePattern(value) {
+  return DATE_RANGE_YEAR.test(value) || DATE_RANGE_QUARTER.test(value) || DATE_RANGE_MONTH.test(value) || DATE_RANGE_WEEK.test(value);
 }
-function assertBetweenBoundValueAllowed(position, expr, value) {
-  if (value === null || typeof value === "number" || typeof value === "string" || typeof value === "bigint" || value instanceof Date) {
-    return;
+var InvalidDateRangeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidDateRangeError";
   }
-  const paramSuffix = expr.type === "namedParam" ? `; param :${expr.name}` : "";
-  throw new NqlSemanticException(
-    NqlErrorCodes.SEM_INVALID_SYNTAX,
-    `BETWEEN ${position} bound must be a literal number, string, or date, or a bigint param; got type ${typeof value}${paramSuffix}.`
-  );
-}
-function compileNull(expr, ctx, aliasContext) {
-  const isNull = expr;
-  const field = expressionToField(isNull.expression, aliasContext);
-  if (!field) {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "IS NULL expression must reference a field"
-    );
+};
+function expandDateRange(pattern) {
+  let match;
+  match = pattern.match(DATE_RANGE_YEAR);
+  if (match) {
+    const year = Number(match[1]);
+    return {
+      start: `${year}-01-01`,
+      end: `${year + 1}-01-01`
+    };
+  }
+  match = pattern.match(DATE_RANGE_QUARTER);
+  if (match) {
+    const year = Number(match[1]);
+    const quarter = Number(match[2]);
+    const startMonth = (quarter - 1) * 3 + 1;
+    const endMonth = startMonth + 3;
+    if (endMonth > 12) {
+      return {
+        start: `${year}-${pad(startMonth)}-01`,
+        end: `${year + 1}-01-01`
+      };
+    }
+    return {
+      start: `${year}-${pad(startMonth)}-01`,
+      end: `${year}-${pad(endMonth)}-01`
+    };
   }
-  validateWhereField(ctx, field, aliasContext, isNull.expression);
-  return {
-    kind: "null",
-    field,
-    operator: isNull.negated ? "isNotNull" : "isNull"
-  };
-}
-function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
-  if (expr.type === "function") {
-    const fn = expr.name.toLowerCase();
-    if (fn === "json_contains" || fn === "json_contained_by") {
-      if (expr.args.length < 2) {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() requires 2 arguments: field and value`
-        );
-      }
-      const jsonField2 = expressionToField(expr.args[0], aliasContext);
-      if (!jsonField2) {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() first argument must be a field reference`
-        );
-      }
-      const jsonValue2 = resolveFilterValue(
-        expr.args[1],
-        ctx,
-        aliasContext,
-        outerAliases
+  match = pattern.match(DATE_RANGE_MONTH);
+  if (match) {
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    if (month < 1 || month > 12) {
+      throw new InvalidDateRangeError(
+        `Invalid month '${match[2]}' in date range '${pattern}' \u2014 must be 01-12`
       );
-      const intent2 = {
-        kind: "jsonContains",
-        field: jsonField2,
-        value: jsonValue2,
-        reversed: fn === "json_contained_by"
-      };
-      return intent2;
     }
-    if (fn === "json_exists") {
-      if (expr.args.length < 2) {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() requires 2 arguments: field and key`
-        );
-      }
-      const jsonField2 = expressionToField(expr.args[0], aliasContext);
-      if (!jsonField2) {
-        throw new NqlSemanticException(
-          NqlErrorCodes.SEM_INVALID_SYNTAX,
-          `${fn}() first argument must be a field reference`
-        );
-      }
-      const key = coerceToStringKey(expr.args[1], `${fn}() key`, ctx);
+    if (month === 12) {
       return {
-        kind: "jsonExists",
-        field: jsonField2,
-        key
+        start: `${year}-12-01`,
+        end: `${year + 1}-01-01`
       };
     }
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      `Unsupported function in WHERE context: ${fn}()`
-    );
-  }
-  const jsonComp = expr;
-  const jsonField = expressionToField(jsonComp.left, aliasContext);
-  if (!jsonField) {
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      "Left side of JSON comparison must be a field reference"
-    );
+    return {
+      start: `${year}-${pad(month)}-01`,
+      end: `${year}-${pad(month + 1)}-01`
+    };
   }
-  if (jsonComp.operator === "?") {
-    const key = coerceToStringKey(jsonComp.right, "? operator key", ctx);
+  match = pattern.match(DATE_RANGE_WEEK);
+  if (match) {
+    const year = Number(match[1]);
+    const week = Number(match[2]);
+    const maxWeeks = getISOWeekCount(year);
+    if (week < 1 || week > maxWeeks) {
+      throw new InvalidDateRangeError(
+        `Invalid week 'W${match[2]}' in date range '${pattern}' \u2014 year ${year} has ${maxWeeks} ISO weeks`
+      );
+    }
+    const start = isoWeekToDate(year, week);
+    const end = addDays(start, 7);
     return {
-      kind: "jsonExists",
-      field: jsonField,
-      key
+      start: formatDate(start),
+      end: formatDate(end)
     };
   }
-  const jsonValue = resolveFilterValue(
-    jsonComp.right,
-    ctx,
-    aliasContext,
-    outerAliases
+  throw new InvalidDateRangeError(
+    `Invalid date range '${pattern}' \u2014 expected YYYY, YYYY-QN, YYYY-MM, or YYYY-WNN`
   );
-  const intent = {
-    kind: "jsonContains",
-    field: jsonField,
-    value: jsonValue,
-    reversed: jsonComp.operator === "<@"
-  };
-  return intent;
 }
-function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
-  const relFilter = expr;
-  const nestedOuterAliases = aliasContext ? [...outerAliases ?? [], aliasContext] : outerAliases ?? [];
-  const prevRelationTarget = ctx.currentRelationTarget;
-  if (ctx.currentFromTable && ctx.validator && relFilter.relation[0]) {
-    ctx.currentRelationTarget = ctx.validator.resolveRelationTarget(
-      ctx.currentFromTable,
-      relFilter.relation[0]
-    );
-  }
-  const where = compileExpression(
-    relFilter.condition,
-    ctx,
-    fns,
-    relFilter.alias,
-    nestedOuterAliases
-  );
-  ctx.currentRelationTarget = prevRelationTarget;
-  return {
-    kind: "relationFilter",
-    relation: relFilter.relation,
-    where,
-    mode: relFilter.mode,
-    ...relFilter.alias !== void 0 && { alias: relFilter.alias }
-  };
+function pad(n) {
+  return n < 10 ? `0${n}` : `${n}`;
 }
-function expandDateRangeList(field, patterns, negated) {
-  const conditions = patterns.map((pattern) => {
-    const { start, end } = expandDateRange(pattern);
-    return {
-      kind: "and",
-      conditions: [
-        {
-          kind: "comparison",
-          field,
-          operator: "gte",
-          value: start
-        },
-        {
-          kind: "comparison",
-          field,
-          operator: "lt",
-          value: end
-        }
-      ]
-    };
-  });
-  const result = conditions.length === 1 ? conditions[0] : { kind: "or", conditions };
-  if (negated) {
-    return { kind: "not", condition: result };
-  }
+function formatDate(d) {
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+function addDays(d, days) {
+  const result = new Date(d.getTime());
+  result.setUTCDate(result.getUTCDate() + days);
   return result;
 }
-function compileExpression(expr, ctx, fns, aliasContext, outerAliases) {
-  switch (expr.type) {
-    case "binary":
-    case "unary":
-      return compileLogical(expr, ctx, fns, aliasContext, outerAliases);
-    case "comparison":
-      return compileComparison(expr, ctx, fns, aliasContext, outerAliases);
-    case "rangeOp":
-      return compileRange(expr, ctx, fns, aliasContext, outerAliases);
-    case "in":
-    case "any":
-      return compileMembership(expr, ctx, fns, aliasContext, outerAliases);
-    case "between":
-      return compileBetween(expr, ctx, fns, aliasContext, outerAliases);
-    case "isNull":
-      return compileNull(expr, ctx, aliasContext);
-    case "jsonComparison":
-    case "function":
-      return compileJson(expr, ctx, fns, aliasContext, outerAliases);
-    case "relationFilter":
-      return compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases);
-    case "case":
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        "CASE in WHERE not supported. Use a computed column in SELECT or a relation filter instead."
-      );
-    case "exists":
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        "EXISTS (subquery) is not supported in NQL. Use relation filters instead:\n  orders | with customer | where customer.active = true\n  orders | where exists(customer, active = true)\nThese compile to efficient EXISTS subqueries automatically."
-      );
-    /* v8 ignore next — defensive: all parser-produced expression types are handled above -- @preserve */
-    default:
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        `Unsupported expression type in WHERE: ${expr.type}`
-      );
-  }
+function isoWeekToDate(year, week) {
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Dow = jan4.getUTCDay() || 7;
+  const mondayW1 = new Date(jan4.getTime());
+  mondayW1.setUTCDate(jan4.getUTCDate() - (jan4Dow - 1));
+  const result = new Date(mondayW1.getTime());
+  result.setUTCDate(mondayW1.getUTCDate() + (week - 1) * 7);
+  return result;
 }
-function assignMutationValue(target, column, value, ctx) {
-  target[column] = expressionToValue(value, ctx);
+function getISOWeekCount(year) {
+  const jan1 = new Date(Date.UTC(year, 0, 1));
+  const dec31 = new Date(Date.UTC(year, 11, 31));
+  const jan1Dow = jan1.getUTCDay();
+  const dec31Dow = dec31.getUTCDay();
+  return jan1Dow === 4 || dec31Dow === 4 ? 53 : 52;
 }
-function compileMutationPipeline(pipeline, ctx, fns, bindings) {
-  ctx.currentFromTable = pipeline.mutation.table;
-  const mutation = compileMutation(pipeline.mutation, ctx, fns, bindings);
-  let returning;
-  for (const clause of pipeline.clauses) {
-    if (clause.type === "select") {
-      returning = extractReturningColumns(clause, ctx);
+
+// src/compiler/compile-expression.ts
+function paramValue(value) {
+  return value !== null && typeof value === "object" && value.kind === "param" ? value.value : value;
+}
+var MAX_ANY_ITEMS = 1e4;
+function compileLogical(expr, ctx, fns, aliasContext, outerAliases) {
+  if (expr.type === "binary") {
+    const binary = expr;
+    if (binary.operator === "and") {
+      return {
+        kind: "and",
+        conditions: [
+          compileExpression(binary.left, ctx, fns, aliasContext, outerAliases),
+          compileExpression(binary.right, ctx, fns, aliasContext, outerAliases)
+        ]
+      };
+    }
+    if (binary.operator === "or") {
+      return {
+        kind: "or",
+        conditions: [
+          compileExpression(binary.left, ctx, fns, aliasContext, outerAliases),
+          compileExpression(binary.right, ctx, fns, aliasContext, outerAliases)
+        ]
+      };
     }
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Unsupported binary operator in WHERE: ${binary.operator}`
+    );
   }
-  if (returning) {
+  const unary = expr;
+  if (unary.operator === "not") {
     return {
-      mutation: { ...mutation, returning }
+      kind: "not",
+      condition: compileExpression(
+        unary.operand,
+        ctx,
+        fns,
+        aliasContext,
+        outerAliases
+      )
     };
   }
-  return { mutation };
-}
-function compileMutation(mutation, ctx, fns, bindings) {
-  switch (mutation.type) {
-    case "insert":
-      return compileInsert(mutation, ctx);
-    case "insert_from":
-      return compileInsertFrom(mutation, ctx, fns, bindings);
-    case "update":
-      return compileUpdate(mutation, ctx, fns, bindings);
-    case "delete":
-      return compileDelete(mutation, ctx, fns, bindings);
-    case "upsert":
-      return compileUpsert(mutation, ctx);
-    case "upsert_from":
-      return compileUpsertFrom(mutation, ctx, fns, bindings);
-  }
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Unsupported unary operator: ${unary.operator}`
+  );
 }
-function compileInsert(insert, ctx) {
-  ctx.validator?.validateTable(insert.table);
-  const allColumns = /* @__PURE__ */ new Set();
-  for (const row of insert.rows) {
-    for (const assignment of row) {
-      ctx.validator?.validateColumn(insert.table, assignment.column);
-      allColumns.add(assignment.column);
+function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
+  const comp = expr;
+  if (comp.left.type === "jsonAccess") {
+    const jsonLeft = comp.left;
+    const baseField = expressionToField(jsonLeft.base, aliasContext);
+    if (!baseField) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        "JSON access base must be a field reference"
+      );
     }
+    const operator2 = mapComparisonOperator(comp.operator);
+    const value2 = resolveFilterValue(
+      comp.right,
+      ctx,
+      aliasContext,
+      outerAliases
+    );
+    const intent2 = {
+      kind: "comparison",
+      field: baseField,
+      operator: operator2,
+      value: value2,
+      jsonPath: jsonLeft.path,
+      jsonMode: jsonLeft.mode
+    };
+    return intent2;
   }
-  const values = [];
-  for (const row of insert.rows) {
-    const rowValues = {};
-    const rowColumns = /* @__PURE__ */ new Set();
-    for (const assignment of row) {
-      rowColumns.add(assignment.column);
-      assignMutationValue(rowValues, assignment.column, assignment.value, ctx);
-    }
-    for (const col of allColumns) {
-      if (!rowColumns.has(col)) {
-        rowValues[col] = void 0;
+  if (comp.left.type === "function") {
+    const fn = comp.left.name.toLowerCase();
+    if (fn === "json_extract" || fn === "json_extract_text") {
+      if (comp.left.args.length < 2) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() requires at least 2 arguments`
+        );
+      }
+      const baseField = expressionToField(comp.left.args[0], aliasContext);
+      if (!baseField) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() first argument must be a field reference`
+        );
       }
+      const keys = comp.left.args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`, ctx));
+      const operator2 = mapComparisonOperator(comp.operator);
+      const value2 = resolveFilterValue(
+        comp.right,
+        ctx,
+        aliasContext,
+        outerAliases
+      );
+      const intent2 = {
+        kind: "comparison",
+        field: baseField,
+        operator: operator2,
+        value: value2,
+        jsonPath: keys,
+        jsonMode: fn === "json_extract" ? "json" : "text"
+      };
+      return intent2;
     }
-    values.push(rowValues);
   }
-  return {
-    type: "insert",
-    table: insert.table,
-    values
+  const havingAggregateComparison = compileHavingAggregateComparison(
+    comp,
+    ctx,
+    aliasContext,
+    outerAliases
+  );
+  if (havingAggregateComparison) return havingAggregateComparison;
+  const field = expressionToField(comp.left, aliasContext);
+  if (!field) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "Left side of comparison must be a field reference"
+    );
+  }
+  validateWhereField(ctx, field, aliasContext, comp.left);
+  if (comp.operator === "like") {
+    const pattern = coerceToStringKey(comp.right, "LIKE pattern", ctx);
+    return {
+      kind: "like",
+      field,
+      pattern
+    };
+  }
+  const operator = mapComparisonOperator(comp.operator);
+  const value = resolveFilterValue(comp.right, ctx, aliasContext, outerAliases);
+  const intent = {
+    kind: "comparison",
+    field,
+    operator,
+    value
   };
+  return intent;
 }
-function compileInsertFrom(insertFrom, ctx, fns, bindings) {
-  ctx.validator?.validateTable(insertFrom.table);
-  const sourceQuery = bindings?.get(insertFrom.source);
-  if (!sourceQuery) {
-    ctx.validator?.validateTable(insertFrom.source);
+function compileHavingAggregateComparison(comp, ctx, aliasContext, outerAliases) {
+  if (ctx.currentHavingAliases === void 0 || aliasContext || comp.left.type !== "function") {
+    return null;
   }
-  ctx.currentFromTable = insertFrom.source;
+  const fn = comp.left.name.toLowerCase();
+  if (fn !== "count" || comp.left.args.length !== 0) {
+    return null;
+  }
+  const exprIntent = {
+    kind: "aggregate",
+    function: "count",
+    field: "*"
+  };
   return {
-    type: "insert_from",
-    table: insertFrom.table,
-    source: insertFrom.source,
-    ...sourceQuery !== void 0 && { sourceQuery },
-    /* v8 ignore next — NQL grammar does not produce explicit column lists for INSERT FROM -- @preserve */
-    ...insertFrom.columns !== void 0 && { columns: insertFrom.columns },
-    ...insertFrom.where !== void 0 && {
-      where: fns.compileExpression(insertFrom.where, ctx, fns)
-    },
-    ...insertFrom.limit !== void 0 && {
-      limit: resolveIntegerCount(insertFrom.limit, ctx, "insert-from limit")
-    }
+    kind: "expression",
+    expr: exprIntent,
+    operator: mapComparisonOperator(comp.operator),
+    value: resolveFilterValue(comp.right, ctx, aliasContext, outerAliases)
   };
 }
-function compileUpdate(update, ctx, fns, bindings) {
-  ctx.currentFromTable = update.table;
-  ctx.validator?.validateTable(update.table);
-  const set = {};
-  for (const assignment of update.assignments) {
-    ctx.validator?.validateColumn(update.table, assignment.column);
-    assignMutationValue(set, assignment.column, assignment.value, ctx);
-  }
-  if (update.where) {
-    return {
-      type: "update",
-      table: update.table,
-      set,
-      where: resolveBindingsInWhere(
-        fns.compileExpression(update.where, ctx, fns),
-        bindings
-      )
-    };
+function compileRange(expr, ctx, _fns, aliasContext, outerAliases) {
+  const rangeExpr = expr;
+  const field = expressionToField(rangeExpr.left, aliasContext);
+  if (!field) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "Left side of range operator must be a field reference"
+    );
   }
-  if (!ctx.allowUnfilteredMutations) {
-    throw new Error(
-      "update without a where clause would affect all rows; pass { allowUnfilteredMutations: true } to the compiler to allow an unfiltered update"
+  validateWhereField(ctx, field, aliasContext, rangeExpr.left);
+  let rangeValue;
+  if (rangeExpr.range) {
+    rangeValue = expressionToRangeValue(rangeExpr.range);
+  } else if (rangeExpr.scalar) {
+    rangeValue = resolveFilterValue(
+      rangeExpr.scalar,
+      ctx,
+      aliasContext,
+      outerAliases
+    );
+  } else {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "Range operator requires either a range literal or scalar value"
     );
   }
-  return {
-    type: "update",
-    table: update.table,
-    set,
-    allowAll: true
+  const result = {
+    kind: "range",
+    field,
+    operator: rangeExpr.operator,
+    value: rangeValue
   };
+  return result;
 }
-function compileDelete(del, ctx, fns, bindings) {
-  ctx.currentFromTable = del.table;
-  ctx.validator?.validateTable(del.table);
-  if (del.where) {
-    return {
-      type: "delete",
-      table: del.table,
-      where: resolveBindingsInWhere(
-        fns.compileExpression(del.where, ctx, fns),
-        bindings
-      )
+function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
+  if (expr.type === "any") {
+    const anyExpr = expr;
+    const field2 = expressionToField(anyExpr.column, aliasContext);
+    if (!field2) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        "ANY expression must reference a field"
+      );
+    }
+    validateWhereField(ctx, field2, aliasContext, anyExpr.column);
+    const valuesParam = resolveNamedParam(ctx, anyExpr.paramName);
+    const rawValues = valuesParam.value;
+    if (!Array.isArray(rawValues)) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `ANY(:${anyExpr.paramName}) requires an array argument`
+      );
+    }
+    if (rawValues.length > ctx.maxAnyItems) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `ANY(:${anyExpr.paramName}) array length ${rawValues.length} exceeds maximum of ${ctx.maxAnyItems}`
+      );
+    }
+    const result2 = {
+      kind: "any",
+      field: field2,
+      values: valuesParam
     };
+    return result2;
   }
-  if (!ctx.allowUnfilteredMutations) {
-    throw new Error(
-      "delete without a where clause would affect all rows; pass { allowUnfilteredMutations: true } to the compiler to allow an unfiltered delete"
+  const inExpr = expr;
+  const field = expressionToField(inExpr.expression, aliasContext);
+  if (!field) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "IN expression must reference a field"
     );
   }
-  return {
-    type: "delete",
-    table: del.table,
-    allowAll: true
-  };
-}
-function compileUpsert(upsert, ctx) {
-  ctx.validator?.validateTable(upsert.table);
-  const values = {};
-  for (const assignment of upsert.assignments) {
-    ctx.validator?.validateColumn(upsert.table, assignment.column);
-    assignMutationValue(values, assignment.column, assignment.value, ctx);
+  validateWhereField(ctx, field, aliasContext, inExpr.expression);
+  let values;
+  if (Array.isArray(inExpr.values)) {
+    values = inExpr.values.map(
+      (v) => resolveFilterValue(v, ctx, aliasContext, outerAliases)
+    );
+    const dateRangeValues = values.filter(
+      (v) => typeof v === "string" && isDateRangePattern(v)
+    );
+    if (dateRangeValues.length > 0) {
+      if (dateRangeValues.length !== values.length) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          "Cannot mix date range patterns with regular values in IN list. Use all date ranges or all literals."
+        );
+      }
+      return expandDateRangeList(field, dateRangeValues, inExpr.negated);
+    }
+  } else if ("type" in inExpr.values && inExpr.values.type === "subquery") {
+    const subquery = compileNestedQuery(
+      inExpr.values.query,
+      ctx,
+      fns
+    );
+    const result2 = {
+      kind: "in",
+      field,
+      subquery
+    };
+    if (inExpr.negated) {
+      return { kind: "not", condition: result2 };
+    }
+    return result2;
+  } else if ("type" in inExpr.values && inExpr.values.type === "dateRange") {
+    return expandDateRangeList(field, [inExpr.values.value], inExpr.negated);
+  } else {
+    values = [];
   }
-  for (const col of upsert.conflictColumns) {
-    ctx.validator?.validateColumn(upsert.table, col);
+  const result = {
+    kind: "in",
+    field,
+    values
+  };
+  if (inExpr.negated) {
+    return { kind: "not", condition: result };
   }
-  if (upsert.where) {
-    throw new Error(
-      "conditional upsert is not yet supported: a WHERE clause on `upsert` (ON CONFLICT DO UPDATE ... WHERE) is parsed but cannot be honored by the SQL generator yet. Remove the WHERE, or use a plain conditional update. Tracked for a future release."
+  return result;
+}
+function compileBetween(expr, ctx, _fns, aliasContext, outerAliases) {
+  const between = expr;
+  const field = expressionToField(between.expression, aliasContext);
+  if (!field) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "BETWEEN expression must reference a field"
     );
   }
+  validateWhereField(ctx, field, aliasContext, between.expression);
+  const lower = resolveFilterValue(
+    between.low,
+    ctx,
+    aliasContext,
+    outerAliases
+  );
+  const upper = resolveFilterValue(
+    between.high,
+    ctx,
+    aliasContext,
+    outerAliases
+  );
+  const lowerValue = paramValue(lower);
+  const upperValue = paramValue(upper);
+  assertBetweenBoundValueAllowed("lower", between.low, lowerValue);
+  assertBetweenBoundValueAllowed("upper", between.high, upperValue);
+  const value = { lower, upper };
   return {
-    type: "upsert",
-    table: upsert.table,
-    values: [values],
-    onConflict: { columns: upsert.conflictColumns },
-    action: { type: "doUpdate", set: values }
+    kind: "range",
+    field,
+    operator: "between",
+    value
   };
 }
-function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
-  ctx.validator?.validateTable(upsertFrom.table);
-  const sourceQuery = bindings?.get(upsertFrom.source);
-  if (!sourceQuery) {
-    ctx.validator?.validateTable(upsertFrom.source);
+function assertBetweenBoundValueAllowed(position, expr, value) {
+  if (value === null || typeof value === "number" || typeof value === "string" || typeof value === "bigint" || value instanceof Date) {
+    return;
   }
-  for (const col of upsertFrom.conflictColumns) {
-    ctx.validator?.validateColumn(upsertFrom.table, col);
+  const paramSuffix = expr.type === "namedParam" ? `; param :${expr.name}` : "";
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `BETWEEN ${position} bound must be a literal number, string, or date, or a bigint param; got type ${typeof value}${paramSuffix}.`
+  );
+}
+function compileNull(expr, ctx, aliasContext) {
+  const isNull = expr;
+  const field = expressionToField(isNull.expression, aliasContext);
+  if (!field) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "IS NULL expression must reference a field"
+    );
   }
-  ctx.currentFromTable = upsertFrom.source;
+  validateWhereField(ctx, field, aliasContext, isNull.expression);
   return {
-    type: "upsert_from",
-    table: upsertFrom.table,
-    source: upsertFrom.source,
-    conflictColumns: upsertFrom.conflictColumns,
-    ...sourceQuery !== void 0 && { sourceQuery },
-    /* v8 ignore start — NQL grammar does not produce explicit column lists for UPSERT FROM -- @preserve */
-    ...upsertFrom.columns !== void 0 && {
-      columns: upsertFrom.columns
-    },
-    /* v8 ignore stop -- @preserve */
-    ...upsertFrom.where !== void 0 && {
-      where: fns.compileExpression(upsertFrom.where, ctx, fns)
-    },
-    ...upsertFrom.limit !== void 0 && {
-      limit: resolveIntegerCount(upsertFrom.limit, ctx, "upsert-from limit")
-    }
+    kind: "null",
+    field,
+    operator: isNull.negated ? "isNotNull" : "isNull"
   };
 }
-function extractReturningColumns(clause, ctx) {
-  const columns = [];
-  for (const item of clause.items) {
-    if (item.type === "star") {
-      return ["*"];
-    }
-    if (item.type === "expression") {
-      const field = expressionToField(item.expression);
-      if (field) {
-        if (ctx.currentFromTable && !field.includes(".")) {
-          ctx.validator?.validateColumn(ctx.currentFromTable, field);
-        }
-        columns.push(item.alias ?? field);
+function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
+  if (expr.type === "function") {
+    const fn = expr.name.toLowerCase();
+    if (fn === "json_contains" || fn === "json_contained_by") {
+      if (expr.args.length < 2) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() requires 2 arguments: field and value`
+        );
+      }
+      const jsonField2 = expressionToField(expr.args[0], aliasContext);
+      if (!jsonField2) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() first argument must be a field reference`
+        );
       }
+      const jsonValue2 = resolveFilterValue(
+        expr.args[1],
+        ctx,
+        aliasContext,
+        outerAliases
+      );
+      const intent2 = {
+        kind: "jsonContains",
+        field: jsonField2,
+        value: jsonValue2,
+        reversed: fn === "json_contained_by"
+      };
+      return intent2;
     }
-  }
-  return columns;
-}
-function resolveBindingsInWhere(where, bindings) {
-  if (!bindings || bindings.size === 0) return where;
-  if (where.kind === "in") {
-    const inWhere = where;
-    const inValues = inWhere.subquery ? void 0 : inWhere.values;
-    if (inValues && inValues.length === 1) {
-      const val = inValues[0];
-      if (!isParamIntent(val) && val && typeof val === "object" && "$ref" in val) {
-        const ref = val.$ref;
-        if (bindings.has(ref)) {
-          const boundQuery = bindings.get(ref);
-          const boundSelect = boundQuery.select;
-          const selectFields = boundSelect && "fields" in boundSelect ? boundSelect.fields : void 0;
-          const cteRef = {
-            type: "select",
-            from: ref,
-            ...selectFields && {
-              select: {
-                type: "fields",
-                fields: selectFields
-              }
-            }
-          };
-          return {
-            kind: "in",
-            field: inWhere.field,
-            subquery: cteRef
-          };
-        }
+    if (fn === "json_exists") {
+      if (expr.args.length < 2) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() requires 2 arguments: field and key`
+        );
+      }
+      const jsonField2 = expressionToField(expr.args[0], aliasContext);
+      if (!jsonField2) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `${fn}() first argument must be a field reference`
+        );
       }
+      const key = coerceToStringKey(expr.args[1], `${fn}() key`, ctx);
+      return {
+        kind: "jsonExists",
+        field: jsonField2,
+        key
+      };
     }
-    return where;
-  }
-  if (where.kind === "not") {
-    const notWhere = where;
-    const resolved = resolveBindingsInWhere(notWhere.condition, bindings);
-    return resolved === notWhere.condition ? where : { kind: "not", condition: resolved };
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Unsupported function in WHERE context: ${fn}()`
+    );
   }
-  if (where.kind === "and" || where.kind === "or") {
-    const compound = where;
-    const resolved = compound.conditions.map(
-      (c) => resolveBindingsInWhere(c, bindings)
+  const jsonComp = expr;
+  const jsonField = expressionToField(jsonComp.left, aliasContext);
+  if (!jsonField) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      "Left side of JSON comparison must be a field reference"
     );
-    const changed = resolved.some((r, i) => r !== compound.conditions[i]);
-    return changed ? { kind: compound.kind, conditions: resolved } : where;
   }
-  return where;
+  if (jsonComp.operator === "?") {
+    const key = coerceToStringKey(jsonComp.right, "? operator key", ctx);
+    return {
+      kind: "jsonExists",
+      field: jsonField,
+      key
+    };
+  }
+  const jsonValue = resolveFilterValue(
+    jsonComp.right,
+    ctx,
+    aliasContext,
+    outerAliases
+  );
+  const intent = {
+    kind: "jsonContains",
+    field: jsonField,
+    value: jsonValue,
+    reversed: jsonComp.operator === "<@"
+  };
+  return intent;
 }
-function extractBindName(stmt) {
-  if (stmt.type === "query") {
-    for (const clause of stmt.clauses) {
-      if (clause.type === "bind") return clause.name;
-    }
-  } else if (stmt.type === "mutationPipeline") {
-    for (const clause of stmt.clauses) {
-      if (clause.type === "bind") return clause.name;
+function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
+  const relFilter = expr;
+  const nestedOuterAliases = aliasContext ? [...outerAliases ?? [], aliasContext] : outerAliases ?? [];
+  const prevRelationTarget = ctx.currentRelationTarget;
+  if (ctx.currentFromTable && relFilter.relation[0]) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use relation filters",
+      relFilter.relation.join(".")
+    );
+    if (ctx.validator) {
+      ctx.currentRelationTarget = ctx.validator.resolveRelationTarget(
+        ctx.currentFromTable,
+        relFilter.relation[0]
+      );
     }
   }
-  return void 0;
+  const where = compileExpression(
+    relFilter.condition,
+    ctx,
+    fns,
+    relFilter.alias,
+    nestedOuterAliases
+  );
+  ctx.currentRelationTarget = prevRelationTarget;
+  return {
+    kind: "relationFilter",
+    relation: relFilter.relation,
+    where,
+    mode: relFilter.mode,
+    ...relFilter.alias !== void 0 && { alias: relFilter.alias }
+  };
+}
+function expandDateRangeList(field, patterns, negated) {
+  const conditions = patterns.map((pattern) => {
+    const { start, end } = expandDateRange(pattern);
+    return {
+      kind: "and",
+      conditions: [
+        {
+          kind: "comparison",
+          field,
+          operator: "gte",
+          value: start
+        },
+        {
+          kind: "comparison",
+          field,
+          operator: "lt",
+          value: end
+        }
+      ]
+    };
+  });
+  const result = conditions.length === 1 ? conditions[0] : { kind: "or", conditions };
+  if (negated) {
+    return { kind: "not", condition: result };
+  }
+  return result;
+}
+function compileExpression(expr, ctx, fns, aliasContext, outerAliases) {
+  switch (expr.type) {
+    case "binary":
+    case "unary":
+      return compileLogical(expr, ctx, fns, aliasContext, outerAliases);
+    case "comparison":
+      return compileComparison(expr, ctx, fns, aliasContext, outerAliases);
+    case "rangeOp":
+      return compileRange(expr, ctx, fns, aliasContext, outerAliases);
+    case "in":
+    case "any":
+      return compileMembership(expr, ctx, fns, aliasContext, outerAliases);
+    case "between":
+      return compileBetween(expr, ctx, fns, aliasContext, outerAliases);
+    case "isNull":
+      return compileNull(expr, ctx, aliasContext);
+    case "jsonComparison":
+    case "function":
+      return compileJson(expr, ctx, fns, aliasContext, outerAliases);
+    case "relationFilter":
+      return compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases);
+    case "case":
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        "CASE in WHERE not supported. Use a computed column in SELECT or a relation filter instead."
+      );
+    case "exists":
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        "EXISTS (subquery) is not supported in NQL. Use relation filters instead:\n  orders | with customer | where customer.active = true\n  orders | where exists(customer, active = true)\nThese compile to efficient EXISTS subqueries automatically."
+      );
+    /* v8 ignore next — defensive: all parser-produced expression types are handled above -- @preserve */
+    default:
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Unsupported expression type in WHERE: ${expr.type}`
+      );
+  }
 }
 function paramExpressionIntent(param, alias) {
   const intent = { ...param };
@@ -1738,23 +2469,31 @@ var SELECT_SCALAR_FUNCTION_NAMES = /* @__PURE__ */ new Set([
   ...NQL_SELECT_SCALAR_FUNCTIONS
 ]);
 function validateSelectPathExpression(expr, ctx) {
-  if (!ctx.currentFromTable || !ctx.validator) return;
+  if (!ctx.currentFromTable) return;
   const { segments } = expr;
   if (segments.length === 1) {
-    ctx.validator.validateColumn(ctx.currentFromTable, segments[0]);
+    validateColumnForTable(ctx, ctx.currentFromTable, segments[0]);
     return;
   }
   const firstSegmentLower = segments[0].toLowerCase();
   if (ctx.pseudoColumnKeywords.has(firstSegmentLower)) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use pseudo-column traversals",
+      segments[0]
+    );
     let i = 1;
     while (i < segments.length && ctx.pseudoColumnKeywords.has(segments[i].toLowerCase())) {
       i++;
     }
     if (i < segments.length) {
-      ctx.validator.validateColumn(ctx.currentFromTable, segments[i]);
+      validateColumnForTable(ctx, ctx.currentFromTable, segments[i]);
     }
     return;
   }
+  assertNoBindingRelationPath(ctx, ctx.currentFromTable, segments.join("."));
+  if (!ctx.validator) return;
   const targetTable = ctx.validator.resolveRelationTarget(
     ctx.currentFromTable,
     segments[0]
@@ -1784,6 +2523,12 @@ function compileSelectClause(clause, ctx, fns) {
     } else if (item.type === "relationStar") {
       hasExpressions = true;
       const relation = item.relation.join(".");
+      assertNoBindingRelationConstruct(
+        ctx,
+        ctx.currentFromTable,
+        "select relation columns",
+        relation
+      );
       expressions.push({
         kind: "relationColumn",
         relation,
@@ -1929,14 +2674,14 @@ function compileSelectExpression(item, ctx, fns) {
     const partitionBy = windowExpr.partitionBy.length > 0 ? windowExpr.partitionBy.map((e) => {
       const f = expressionToValidatedField(e, ctx) ?? expressionToSql(e);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, f);
+        validateColumnForTable(ctx, ctx.currentFromTable, f);
       }
       return f;
     }) : void 0;
     const orderBy = windowExpr.orderBy.length > 0 ? windowExpr.orderBy.map((o) => {
       const f = expressionToValidatedField(o.expression, ctx) ?? expressionToSql(o.expression);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, f);
+        validateColumnForTable(ctx, ctx.currentFromTable, f);
       }
       return { field: f, direction: o.direction };
     }) : void 0;
@@ -2054,6 +2799,12 @@ function compileMultiSegmentPath(expr, item, ctx) {
   const segments = expr.segments;
   const firstSegmentLower = segments[0].toLowerCase();
   if (ctx.pseudoColumnKeywords.has(firstSegmentLower)) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use pseudo-column traversals",
+      segments[0]
+    );
     const firstSegment = firstSegmentLower;
     const depthHint = expr.depthHint;
     if (depthHint !== void 0) {
@@ -2081,7 +2832,7 @@ function compileMultiSegmentPath(expr, item, ctx) {
     }
     const targetColumn = segments[i];
     if (ctx.currentFromTable) {
-      ctx.validator?.validateColumn(ctx.currentFromTable, targetColumn);
+      validateColumnForTable(ctx, ctx.currentFromTable, targetColumn);
     }
     const defaultAlias = segments.map((s) => s.toLowerCase()).join(".");
     if (traversals.length === 1) {
@@ -2103,6 +2854,12 @@ function compileMultiSegmentPath(expr, item, ctx) {
   }
   const column = segments[segments.length - 1];
   const relation = segments.slice(0, -1).join(".");
+  assertNoBindingRelationConstruct(
+    ctx,
+    ctx.currentFromTable,
+    "select relation columns",
+    relation
+  );
   if (ctx.currentFromTable && ctx.validator) {
     const targetTable = ctx.validator.resolveRelationTarget(
       ctx.currentFromTable,
@@ -2263,6 +3020,220 @@ function allowsInternalParams(options) {
   const internalOptions = options?.[NQL_INTERNAL_COMPILER_OPTIONS];
   return internalOptions?.allowInternalParams === true;
 }
+function isUnresolvedSelectAllOutputSchemaError(error) {
+  return error instanceof NqlSemanticException && error.message.includes("from SELECT *") && error.message.includes("without a concrete table schema");
+}
+function programSequenceStepFromResult(result, bindName, final, bindingDependencies) {
+  if (result.query) {
+    return {
+      kind: "query",
+      query: result.query,
+      ...bindName !== void 0 && { bindName },
+      final,
+      bindingDependencies
+    };
+  }
+  if (result.mutation) {
+    return {
+      kind: "mutation",
+      mutation: result.mutation,
+      ...bindName !== void 0 && { bindName },
+      final,
+      bindingDependencies
+    };
+  }
+  return void 0;
+}
+function stringArraysEqual(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isNqlAstRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function addReadBindingReference(references, readBindingNames, name) {
+  if (typeof name === "string" && readBindingNames.has(name)) {
+    references.add(name);
+  }
+}
+function withoutLocalCteNames(readBindingNames, ctes) {
+  if (ctes.length === 0) return readBindingNames;
+  const localCteNames = new Set(ctes.map((cte) => cte.name));
+  if (![...localCteNames].some((name) => readBindingNames.has(name))) {
+    return readBindingNames;
+  }
+  return new Set(
+    [...readBindingNames].filter((name) => !localCteNames.has(name))
+  );
+}
+function collectQueryReadBindingReferences(query, readBindingNames, references) {
+  addReadBindingReference(references, readBindingNames, query.table);
+  collectNodeReadBindingReferences(query.clauses, readBindingNames, references);
+}
+function collectWithQueryReadBindingReferences(withQuery, readBindingNames, references) {
+  const scopedReadBindingNames = withoutLocalCteNames(
+    readBindingNames,
+    withQuery.ctes
+  );
+  for (const cte of withQuery.ctes) {
+    collectQueryReadBindingReferences(
+      cte.query,
+      scopedReadBindingNames,
+      references
+    );
+  }
+  collectQueryReadBindingReferences(
+    withQuery.query,
+    scopedReadBindingNames,
+    references
+  );
+}
+function collectInListReadBindingReference(values, readBindingNames, references) {
+  if (!Array.isArray(values) || values.length !== 1) return;
+  const value = values[0];
+  if (!isNqlAstRecord(value) || value.type !== "path") return;
+  const segments = value.segments;
+  if (!Array.isArray(segments) || segments.length !== 1) return;
+  addReadBindingReference(references, readBindingNames, segments[0]);
+}
+function collectNodeReadBindingReferences(node, readBindingNames, references) {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectNodeReadBindingReferences(item, readBindingNames, references);
+    }
+    return;
+  }
+  if (!isNqlAstRecord(node)) return;
+  switch (node.type) {
+    case "query":
+      collectQueryReadBindingReferences(
+        node,
+        readBindingNames,
+        references
+      );
+      return;
+    case "withQuery":
+      collectWithQueryReadBindingReferences(
+        node,
+        readBindingNames,
+        references
+      );
+      return;
+    case "mutationPipeline":
+      collectNodeReadBindingReferences(
+        node.mutation,
+        readBindingNames,
+        references
+      );
+      collectNodeReadBindingReferences(
+        node.clauses,
+        readBindingNames,
+        references
+      );
+      return;
+    case "insert_from":
+    case "upsert_from":
+      addReadBindingReference(references, readBindingNames, node.source);
+      collectNodeReadBindingReferences(
+        node.where,
+        readBindingNames,
+        references
+      );
+      return;
+    case "setOperation":
+      addReadBindingReference(references, readBindingNames, node.boundName);
+      collectNodeReadBindingReferences(
+        node.right,
+        readBindingNames,
+        references
+      );
+      return;
+    case "in":
+      collectNodeReadBindingReferences(
+        node.expression,
+        readBindingNames,
+        references
+      );
+      collectInListReadBindingReference(
+        node.values,
+        readBindingNames,
+        references
+      );
+      collectNodeReadBindingReferences(
+        node.values,
+        readBindingNames,
+        references
+      );
+      return;
+    case "subquery":
+      collectNodeReadBindingReferences(
+        node.query,
+        readBindingNames,
+        references
+      );
+      return;
+  }
+  for (const child of Object.values(node)) {
+    collectNodeReadBindingReferences(child, readBindingNames, references);
+  }
+}
+function collectStatementReadBindingReferences(stmt, readBindingNames) {
+  const references = /* @__PURE__ */ new Set();
+  if (readBindingNames.size === 0) return references;
+  collectNodeReadBindingReferences(stmt, readBindingNames, references);
+  return references;
+}
+function collectCompileResultReadBindingReferences(result, readBindingNames, references) {
+  if (result.query) {
+    addReadBindingReference(references, readBindingNames, result.query.from);
+  }
+}
+function addTransitiveBindingDependency(bindName, bindingDependencies, ordered, seen) {
+  if (seen.has(bindName)) return;
+  seen.add(bindName);
+  for (const dependency of bindingDependencies.get(bindName) ?? []) {
+    addTransitiveBindingDependency(
+      dependency,
+      bindingDependencies,
+      ordered,
+      seen
+    );
+  }
+  ordered.push(bindName);
+}
+function collectTransitiveReadBindingDependencies(directReferences, bindingDependencies) {
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const reference of directReferences) {
+    addTransitiveBindingDependency(
+      reference,
+      bindingDependencies,
+      ordered,
+      seen
+    );
+  }
+  return ordered;
+}
+function rejectReadBindingReferenceAcrossMutation(bindName, definitionIndex, mutationIndex, referenceIndex, statementCount) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `read binding referenced across a mutation (#186): binding '${bindName}' is defined by read-only statement ${definitionIndex + 1} of ${statementCount} and referenced by statement ${referenceIndex + 1} after mutation statement ${mutationIndex + 1}. Read-only bindings are not materialized snapshots; move the reference before the mutation or bind the mutation RETURNING result instead.`
+  );
+}
+function rejectInvalidReadBindingDependencies(statementBindingDependencies, readBindingDefinitions, lastMutationStatement, referenceIndex, statementCount) {
+  for (const referencedBindName of statementBindingDependencies) {
+    const definitionIndex = readBindingDefinitions.get(referencedBindName);
+    if (definitionIndex === void 0) continue;
+    if (lastMutationStatement > definitionIndex) {
+      rejectReadBindingReferenceAcrossMutation(
+        referencedBindName,
+        definitionIndex,
+        lastMutationStatement,
+        referenceIndex,
+        statementCount
+      );
+    }
+  }
+}
 var NqlCompiler = class {
   ctx;
   fns;
@@ -2286,9 +3257,11 @@ var NqlCompiler = class {
     this.ctx = {
       currentFromTable: void 0,
       currentRelationTarget: void 0,
+      currentHavingAliases: void 0,
       pseudoColumnKeywords,
       recursiveKeywords,
       validator,
+      bindingOutputColumns: /* @__PURE__ */ new Map(),
       params,
       maxAnyItems: maxAnyItemsRaw ?? MAX_ANY_ITEMS,
       allowUnfilteredMutations: options?.allowUnfilteredMutations ?? false,
@@ -2304,6 +3277,14 @@ var NqlCompiler = class {
    * Compile an NQL program to IntentAST.
    */
   compile(program) {
+    try {
+      return this.compileProgram(program);
+    } finally {
+      this.ctx.bindingOutputColumns.clear();
+      this.ctx.validator?.clearVirtualBindingTables();
+    }
+  }
+  compileProgram(program) {
     if (program.statements.length === 0) {
       return {};
     }
@@ -2320,30 +3301,121 @@ var NqlCompiler = class {
       }
     }
     const bindings = /* @__PURE__ */ new Map();
+    const bindingOutputSchemas = /* @__PURE__ */ new Map();
     const mutationBindings = /* @__PURE__ */ new Map();
     const materializedBindStatements = /* @__PURE__ */ new Set();
+    const seenBindNames = /* @__PURE__ */ new Map();
+    const nqlProgramSequence = [];
+    const readBindingDefinitions = /* @__PURE__ */ new Map();
+    const definedBindingNames = /* @__PURE__ */ new Set();
+    const bindingDependencies = /* @__PURE__ */ new Map();
+    let lastMutationStatement = -1;
     let lastResult = {};
     for (let i = 0; i < program.statements.length; i++) {
       const stmt = program.statements[i];
-      lastResult = this.compileSingleStatement(stmt, bindings);
       const bindName = extractBindName(stmt);
+      if (bindName) {
+        const previousStatement = seenBindNames.get(bindName);
+        if (previousStatement !== void 0) {
+          throw new NqlSemanticException(
+            NqlErrorCodes.SEM_INVALID_SYNTAX,
+            `NQL binding name '${bindName}' is used more than once (statements ${previousStatement + 1} and ${i + 1}). NQL binding names must be unique.`
+          );
+        }
+        seenBindNames.set(bindName, i);
+      }
+      const readBindingReferences = collectStatementReadBindingReferences(
+        stmt,
+        definedBindingNames
+      );
+      let statementBindingDependencies = collectTransitiveReadBindingDependencies(
+        readBindingReferences,
+        bindingDependencies
+      );
+      rejectInvalidReadBindingDependencies(
+        statementBindingDependencies,
+        readBindingDefinitions,
+        lastMutationStatement,
+        i,
+        program.statements.length
+      );
+      lastResult = this.compileSingleStatement(stmt, bindings);
+      collectCompileResultReadBindingReferences(
+        lastResult,
+        definedBindingNames,
+        readBindingReferences
+      );
+      statementBindingDependencies = collectTransitiveReadBindingDependencies(
+        readBindingReferences,
+        bindingDependencies
+      );
+      rejectInvalidReadBindingDependencies(
+        statementBindingDependencies,
+        readBindingDefinitions,
+        lastMutationStatement,
+        i,
+        program.statements.length
+      );
+      if (stmt.type === "mutationPipeline") {
+        lastMutationStatement = i;
+      }
       if (bindName) {
         if (lastResult.query) {
+          const outputSchema = this.registerQueryBindingOutputSchema(
+            bindName,
+            lastResult.query,
+            bindingOutputSchemas
+          );
           bindings.set(bindName, lastResult.query);
+          if (outputSchema) {
+            this.ctx.validator?.addVirtualBindingTable(
+              bindName,
+              outputSchema.columns
+            );
+          }
           materializedBindStatements.add(i);
+          readBindingDefinitions.set(bindName, i);
+          definedBindingNames.add(bindName);
+          bindingDependencies.set(bindName, statementBindingDependencies);
         } else if (lastResult.mutation?.returning?.length) {
-          mutationBindings.set(bindName, lastResult.mutation);
+          const canonicalBinding = this.canonicalizeMutationBinding(
+            bindName,
+            lastResult.mutation
+          );
+          lastResult = { mutation: canonicalBinding.mutation };
+          mutationBindings.set(bindName, canonicalBinding.mutation);
+          const outputSchema = canonicalBinding.outputSchema;
+          const bindingFields = outputSchema?.columns ?? canonicalBinding.mutation.returning ?? [];
+          this.ctx.bindingOutputColumns.set(bindName, outputSchema?.columns);
           bindings.set(bindName, {
             type: "select",
-            from: lastResult.mutation.table,
+            from: canonicalBinding.mutation.table,
             select: {
               type: "fields",
-              fields: [...lastResult.mutation.returning]
+              fields: [...bindingFields]
             }
           });
+          if (outputSchema) {
+            bindingOutputSchemas.set(bindName, outputSchema);
+            this.ctx.validator?.addVirtualBindingTable(
+              bindName,
+              outputSchema.columns
+            );
+          }
           materializedBindStatements.add(i);
+          definedBindingNames.add(bindName);
+          bindingDependencies.set(bindName, []);
         }
       }
+      const sequenceStep = programSequenceStepFromResult(
+        lastResult,
+        bindName,
+        i === program.statements.length - 1,
+        statementBindingDependencies
+      );
+      if (sequenceStep !== void 0) {
+        nqlProgramSequence.push(sequenceStep);
+      }
     }
     for (let i = 0; i < program.statements.length - 1; i++) {
       const bindName = extractBindName(program.statements[i]);
@@ -2354,15 +3426,68 @@ var NqlCompiler = class {
       }
     }
     const hasMutationBindings = mutationBindings.size > 0;
+    const hasBindingOutputSchemas = bindingOutputSchemas.size > 0;
+    const hasNqlProgramSequence = nqlProgramSequence.length === program.statements.length;
     if (bindings.size > 0) {
       return {
         ...lastResult,
         bindings,
-        ...hasMutationBindings && { mutationBindings }
+        ...hasBindingOutputSchemas && { bindingOutputSchemas },
+        ...hasMutationBindings && { mutationBindings },
+        ...hasNqlProgramSequence && { nqlProgramSequence }
       };
     }
     return lastResult;
   }
+  registerQueryBindingOutputSchema(bindName, query, bindingOutputSchemas) {
+    try {
+      const outputSchema = getQueryOutputSchema(query, this.ctx, bindName);
+      bindingOutputSchemas.set(bindName, outputSchema);
+      this.ctx.bindingOutputColumns.set(bindName, outputSchema.columns);
+      return outputSchema;
+    } catch (error) {
+      if (!this.ctx.validator && isUnresolvedSelectAllOutputSchemaError(error)) {
+        this.ctx.bindingOutputColumns.set(bindName, void 0);
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  canonicalizeMutationBinding(bindName, mutation) {
+    const outputSchema = this.getMutationBindingOutputSchema(
+      bindName,
+      mutation
+    );
+    const returning = mutation.returning;
+    if (returning === void 0 || returning.length === 0 || returning.includes("*") || outputSchema === void 0 || stringArraysEqual(returning, outputSchema.columns)) {
+      return { mutation, outputSchema };
+    }
+    return {
+      mutation: {
+        ...mutation,
+        returning: outputSchema.columns
+      },
+      outputSchema
+    };
+  }
+  getMutationBindingOutputSchema(bindName, mutation) {
+    const returning = mutation.returning;
+    if (!returning || returning.length === 0) return void 0;
+    if (returning.includes("*")) {
+      const columns = this.ctx.validator?.getTableColumns(mutation.table);
+      if (columns !== void 0) return { columns };
+      if (!this.ctx.validator) return void 0;
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindName}' from mutation RETURNING * on '${mutation.table}' without a concrete table schema.`
+      );
+    }
+    return {
+      columns: returning.map(
+        (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
+      )
+    };
+  }
   compileSingleStatement(stmt, bindings) {
     if (stmt.type === "withQuery") {
       return compileWithQuery(stmt, this.ctx, this.fns);
@@ -5463,6 +6588,7 @@ function hasColumnValidatorShape(obj) {
 }
 /* v8 ignore next — '*' columns are validated at call-site before reaching here -- @preserve */
 /* v8 ignore next — graceful degradation: unknown tables skip validation -- @preserve */
+/* v8 ignore next — defensive: bound queries from NQL always have select.fields -- @preserve */
 /* v8 ignore next — defensive: callers always pass valid relation paths -- @preserve */
 /* v8 ignore next — not yet reachable: flat + pre-existing includes requires WITH clause -- @preserve */
 /* v8 ignore stop -- @preserve */
@@ -5478,7 +6604,6 @@ function hasColumnValidatorShape(obj) {
 /* v8 ignore start — defensive: parser guarantees IS NULL LHS is a path -- @preserve */
 /* v8 ignore start — defensive: parser guarantees at least 2 args -- @preserve */
 /* v8 ignore next — defensive: only json_* functions reach WHERE context -- @preserve */
-/* v8 ignore next — defensive: bound queries from NQL always have select.fields -- @preserve */
 /* v8 ignore start — defensive: star items are handled in compileSelectClause before reaching here -- @preserve */
 /* v8 ignore next — defensive: relationStar items are handled in compileSelectClause -- @preserve */
 /* v8 ignore start — defensive: all parser-produced SELECT expression types are handled above -- @preserve */