@dbsp/nql 1.1.0 → 1.3.0

package/dist/index.js

@@ -1,6 +1,9 @@
-import { isRankingWindowFunction } from '@dbsp/types';
+import { NQL_INTERNAL_COMPILER_OPTIONS, isNqlBindingRef, getNqlBindingRefName, createNqlBindingRef } from '@dbsp/types/internal';
+import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isParamIntent, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction } from '@dbsp/types';
 import { createToken, Lexer, CstParser } from 'chevrotain';
 
+// src/compiler/index.ts
+
 // src/errors/types.ts
 var NqlErrorCodes = {
   // Lexer errors
@@ -107,8 +110,83 @@ var ColumnValidator = class _ColumnValidator {
     return rel?.target;
   }
 };
-
-// src/compiler/expression-utils.ts
+var FORBIDDEN_PARAM_NAMES = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+function isReservedAutoParamName(name) {
+  return name.startsWith("__p");
+}
+function assertParamNameAllowed(name, ctx) {
+  if (FORBIDDEN_PARAM_NAMES.has(name)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Named parameter :${name} is reserved and cannot be bound`
+    );
+  }
+  if (!ctx?.allowInternalParams && isReservedAutoParamName(name)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Named parameter :${name} uses the reserved __p namespace`
+    );
+  }
+}
+function assertParamValueAllowed(name, value) {
+  if (value === void 0) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Named parameter :${name} must not be undefined; use null to bind SQL NULL`
+    );
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Named parameter :${name} must be a finite number`
+    );
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      assertParamValueAllowed(`${name}[${i}]`, value[i]);
+    }
+  }
+}
+function validateParamsMap(params, ctx) {
+  for (const key of Object.getOwnPropertyNames(params)) {
+    assertParamNameAllowed(key, ctx);
+    assertParamValueAllowed(key, params[key]);
+  }
+}
+function resolveNamedParam(ctx, name) {
+  assertParamNameAllowed(name, ctx);
+  if (!Object.hasOwn(ctx.params, name)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Named parameter :${name} is not bound`
+    );
+  }
+  const value = ctx.params[name];
+  assertParamValueAllowed(name, value);
+  return { kind: "param", value };
+}
+function assertIntegerCount(value, label) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `${label} must resolve to a non-negative safe integer`
+    );
+  }
+}
+function resolveIntegerCount(count, ctx, label) {
+  if (typeof count === "number") {
+    assertIntegerCount(count, label);
+    return count;
+  }
+  const param = resolveNamedParam(ctx, count.name);
+  const { value } = param;
+  assertIntegerCount(value, label);
+  return { ...param, value };
+}
 function expressionToField(expr, aliasContext) {
   if (expr.type === "path") {
     const segments = expr.segments;
@@ -119,8 +197,16 @@ function expressionToField(expr, aliasContext) {
   }
   return null;
 }
-function expressionToValue(expr) {
+function expressionToValue(expr, ctx) {
   switch (expr.type) {
+    case "namedParam":
+      if (!ctx) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_UNREACHABLE,
+          `Cannot resolve named parameter :${expr.name} without compiler context`
+        );
+      }
+      return resolveNamedParam(ctx, expr.name);
     case "string":
       return expr.value;
     case "number":
@@ -130,25 +216,25 @@ function expressionToValue(expr) {
     case "null":
       return null;
     case "path":
-      return { $ref: expr.segments.join(".") };
+      return createNqlBindingRef(expr.segments.join("."));
     case "function": {
       return {
         $fn: expr.name,
-        $args: expr.args.map((a) => expressionToValue(a))
+        $args: expr.args.map((a) => expressionToValue(a, ctx))
       };
     }
     case "binary": {
       const binary = expr;
       return {
         $op: binary.operator,
-        $left: expressionToValue(binary.left),
-        $right: expressionToValue(binary.right)
+        $left: expressionToValue(binary.left, ctx),
+        $right: expressionToValue(binary.right, ctx)
       };
     }
     case "unary": {
       const unary = expr;
       if (unary.operator === "-") {
-        const operand = expressionToValue(unary.operand);
+        const operand = expressionToValue(unary.operand, ctx);
         if (typeof operand === "number") {
           return -operand;
         }
@@ -174,6 +260,11 @@ function expressionToValue(expr) {
 }
 function expressionToSql(expr) {
   switch (expr.type) {
+    case "namedParam":
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Named parameter :${expr.name} cannot be used as SQL structure; use nqlRaw() for trusted dynamic structure`
+      );
     case "path":
       return expr.segments.join(".");
     case "string":
@@ -217,12 +308,18 @@ function expressionToRangeValue(expr) {
   if (expr.type === "string") {
     return expr.value;
   }
+  if (expr.type === "namedParam") {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_UNREACHABLE,
+      `Named parameter :${expr.name} must be resolved by the caller`
+    );
+  }
   throw new Error(
     `Range operator requires a range literal or scalar value, got ${expr.type}`
   );
 }
 function resolveFilterValue(expr, ctx, aliasContext, outerAliases) {
-  if (!aliasContext) return expressionToValue(expr);
+  if (!aliasContext) return expressionToValue(expr, ctx);
   if (expr.type === "path") {
     const segments = expr.segments;
     if (segments.length > 1 && segments[0] === aliasContext) {
@@ -259,7 +356,7 @@ function resolveFilterValue(expr, ctx, aliasContext, outerAliases) {
       scope: "outer"
     };
   }
-  return expressionToValue(expr);
+  return expressionToValue(expr, ctx);
 }
 function mapComparisonOperator(op) {
   switch (op) {
@@ -280,15 +377,9 @@ function mapComparisonOperator(op) {
   }
 }
 function isAggregateFunction(name) {
-  return [
-    "count",
-    "sum",
-    "avg",
-    "min",
-    "max",
-    "array_agg",
-    "string_agg"
-  ].includes(name.toLowerCase());
+  return NQL_SELECT_AGGREGATE_FUNCTIONS.includes(
+    name.toLowerCase()
+  );
 }
 function validateWhereField(ctx, field, aliasContext, originalExpr) {
   if (!ctx.validator) return;
@@ -309,35 +400,325 @@ function validateWhereField(ctx, field, aliasContext, originalExpr) {
     ctx.validator.validateColumn(ctx.currentRelationTarget, field);
     return;
   }
-  if (ctx.currentFromTable && !field.includes(".")) {
-    ctx.validator.validateColumn(ctx.currentFromTable, field);
+  if (ctx.currentFromTable && !field.includes(".")) {
+    ctx.validator.validateColumn(ctx.currentFromTable, field);
+  }
+}
+function coerceToStringKey(expr, contextLabel, ctx) {
+  if (expr.type === "path") {
+    const segments = expr.segments;
+    if (segments.length > 1) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `${contextLabel} must be a string literal or a single identifier, not a dotted path`
+      );
+    }
+    const key = expressionToField(expr);
+    if (!key) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `${contextLabel} must be a string literal or a single identifier`
+      );
+    }
+    return key;
+  }
+  if (expr.type === "string") {
+    return expr.value;
+  }
+  if (expr.type === "namedParam") {
+    const param = resolveNamedParam(ctx, expr.name);
+    const value = param.value;
+    if (typeof value !== "string") {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `${contextLabel} named parameter :${expr.name} must resolve to a string`
+      );
+    }
+    return param;
+  }
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `${contextLabel} must be a string literal`
+  );
+}
+
+// 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);
+    }
+  }
+  if (returning) {
+    return {
+      mutation: { ...mutation, returning }
+    };
+  }
+  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, fns, bindings);
+    case "upsert_from":
+      return compileUpsertFrom(mutation, ctx, fns, bindings);
+  }
+}
+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 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);
+  }
+  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: "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 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
+      )
+    };
+  }
+  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"
+    );
+  }
+  return {
+    type: "update",
+    table: update.table,
+    set,
+    allowAll: true
+  };
+}
+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
+      )
+    };
+  }
+  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"
+    );
+  }
+  return {
+    type: "delete",
+    table: del.table,
+    allowAll: true
+  };
+}
+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
+        )
+      }
+    }
+  };
+}
+function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
+  ctx.validator?.validateTable(upsertFrom.table);
+  const sourceQuery = bindings?.get(upsertFrom.source);
+  if (!sourceQuery) {
+    ctx.validator?.validateTable(upsertFrom.source);
+  }
+  for (const col of upsertFrom.conflictColumns) {
+    ctx.validator?.validateColumn(upsertFrom.table, col);
+  }
+  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);
+      }
+    }
+  }
+  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
+          };
+        }
+      }
+    }
+    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 coerceToStringKey(expr, contextLabel) {
-  if (expr.type === "path") {
-    const segments = expr.segments;
-    if (segments.length > 1) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        `${contextLabel} must be a string literal or a single identifier, not a dotted path`
-      );
+function extractBindName(stmt) {
+  if (stmt.type === "query") {
+    for (const clause of stmt.clauses) {
+      if (clause.type === "bind") return clause.name;
     }
-    const key = expressionToField(expr);
-    if (!key) {
-      throw new NqlSemanticException(
-        NqlErrorCodes.SEM_INVALID_SYNTAX,
-        `${contextLabel} must be a string literal or a single identifier`
-      );
+  } else if (stmt.type === "mutationPipeline") {
+    for (const clause of stmt.clauses) {
+      if (clause.type === "bind") return clause.name;
     }
-    return key;
-  }
-  if (expr.type === "string") {
-    return expr.value;
   }
-  throw new NqlSemanticException(
-    NqlErrorCodes.SEM_INVALID_SYNTAX,
-    `${contextLabel} must be a string literal`
-  );
+  return void 0;
 }
 
 // src/compiler/include-builder.ts
@@ -435,10 +816,9 @@ function compileQuery(query, ctx, fns, bindings) {
     const clause = query.clauses[i];
     switch (clause.type) {
       case "where": {
-        const condition = fns.compileExpression(
-          clause.condition,
-          ctx,
-          fns
+        const condition = resolveBindingsInWhere(
+          fns.compileExpression(clause.condition, ctx, fns),
+          bindings
         );
         if (groupByIndex >= 0 && i > groupByIndex) {
           havingConditions.push(condition);
@@ -474,15 +854,25 @@ function compileQuery(query, ctx, fns, bindings) {
         break;
       case "limit": {
         const lc = clause;
+        const count = resolveIntegerCount(
+          lc.count,
+          ctx,
+          lc.relation ? "per-include limit" : "limit"
+        );
         if (lc.relation) {
-          includeLimits.set(lc.relation, lc.count);
+          const includeLimit = isParamIntent(count) ? count.value : count;
+          includeLimits.set(lc.relation, includeLimit);
         } else {
-          limit = lc.count;
+          limit = count;
         }
         break;
       }
       case "offset":
-        offset = clause.count;
+        offset = resolveIntegerCount(
+          clause.count,
+          ctx,
+          "offset"
+        );
         break;
       case "lock": {
         const lc = clause;
@@ -647,6 +1037,14 @@ function compileOrderItem(item, ctx) {
     }
     return { field, direction: item.direction };
   }
+  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.'
+    );
+  }
   const sqlExpr = expressionToSql(item.expression);
   return { field: sqlExpr, direction: item.direction };
 }
@@ -809,6 +1207,9 @@ function getISOWeekCount(year) {
 }
 
 // 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") {
@@ -872,7 +1273,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
       aliasContext,
       outerAliases
     );
-    return {
+    const intent2 = {
       kind: "comparison",
       field: baseField,
       operator: operator2,
@@ -880,6 +1281,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
       jsonPath: jsonLeft.path,
       jsonMode: jsonLeft.mode
     };
+    return intent2;
   }
   if (comp.left.type === "function") {
     const fn = comp.left.name.toLowerCase();
@@ -897,7 +1299,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
           `${fn}() first argument must be a field reference`
         );
       }
-      const keys = comp.left.args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`));
+      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,
@@ -905,7 +1307,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
         aliasContext,
         outerAliases
       );
-      return {
+      const intent2 = {
         kind: "comparison",
         field: baseField,
         operator: operator2,
@@ -913,6 +1315,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
         jsonPath: keys,
         jsonMode: fn === "json_extract" ? "json" : "text"
       };
+      return intent2;
     }
   }
   const field = expressionToField(comp.left, aliasContext);
@@ -924,20 +1327,22 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
   }
   validateWhereField(ctx, field, aliasContext, comp.left);
   if (comp.operator === "like") {
+    const pattern = coerceToStringKey(comp.right, "LIKE pattern", ctx);
     return {
       kind: "like",
       field,
-      pattern: coerceToStringKey(comp.right, "LIKE pattern")
+      pattern
     };
   }
   const operator = mapComparisonOperator(comp.operator);
   const value = resolveFilterValue(comp.right, ctx, aliasContext, outerAliases);
-  return {
+  const intent = {
     kind: "comparison",
     field,
     operator,
     value
   };
+  return intent;
 }
 function compileRange(expr, ctx, _fns, aliasContext, outerAliases) {
   const rangeExpr = expr;
@@ -965,12 +1370,13 @@ function compileRange(expr, ctx, _fns, aliasContext, outerAliases) {
       "Range operator requires either a range literal or scalar value"
     );
   }
-  return {
+  const result = {
     kind: "range",
     field,
     operator: rangeExpr.operator,
     value: rangeValue
   };
+  return result;
 }
 function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
   if (expr.type === "any") {
@@ -983,11 +1389,12 @@ function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
       );
     }
     validateWhereField(ctx, field2, aliasContext, anyExpr.column);
-    const rawValues = ctx.params[anyExpr.paramName];
+    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 but received ${rawValues === void 0 ? "undefined (parameter not bound)" : typeof rawValues}`
+        `ANY(:${anyExpr.paramName}) requires an array argument`
       );
     }
     if (rawValues.length > ctx.maxAnyItems) {
@@ -996,8 +1403,12 @@ function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
         `ANY(:${anyExpr.paramName}) array length ${rawValues.length} exceeds maximum of ${ctx.maxAnyItems}`
       );
     }
-    const values2 = rawValues;
-    return { kind: "any", field: field2, values: values2 };
+    const result2 = {
+      kind: "any",
+      field: field2,
+      values: valuesParam
+    };
+    return result2;
   }
   const inExpr = expr;
   const field = expressionToField(inExpr.expression, aliasContext);
@@ -1077,27 +1488,28 @@ function compileBetween(expr, ctx, _fns, aliasContext, outerAliases) {
     aliasContext,
     outerAliases
   );
-  if (lower !== null && typeof lower !== "number" && typeof lower !== "string" && !(lower instanceof Date)) {
-    const got = typeof lower === "object" ? "path reference" : JSON.stringify(lower);
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      `BETWEEN lower bound must be a literal number, string, or date \u2014 got ${got}. Use a param or hardcoded value.`
-    );
-  }
-  if (upper !== null && typeof upper !== "number" && typeof upper !== "string" && !(upper instanceof Date)) {
-    const got = typeof upper === "object" ? "path reference" : JSON.stringify(upper);
-    throw new NqlSemanticException(
-      NqlErrorCodes.SEM_INVALID_SYNTAX,
-      `BETWEEN upper bound must be a literal number, string, or date \u2014 got ${got}. Use a param or hardcoded value.`
-    );
-  }
+  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: { lower, upper }
+    value
   };
 }
+function assertBetweenBoundValueAllowed(position, expr, value) {
+  if (value === null || typeof value === "number" || typeof value === "string" || typeof value === "bigint" || value instanceof Date) {
+    return;
+  }
+  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);
@@ -1137,12 +1549,13 @@ function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
         aliasContext,
         outerAliases
       );
-      return {
+      const intent2 = {
         kind: "jsonContains",
         field: jsonField2,
         value: jsonValue2,
         reversed: fn === "json_contained_by"
       };
+      return intent2;
     }
     if (fn === "json_exists") {
       if (expr.args.length < 2) {
@@ -1158,7 +1571,7 @@ function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
           `${fn}() first argument must be a field reference`
         );
       }
-      const key = coerceToStringKey(expr.args[1], `${fn}() key`);
+      const key = coerceToStringKey(expr.args[1], `${fn}() key`, ctx);
       return {
         kind: "jsonExists",
         field: jsonField2,
@@ -1179,7 +1592,7 @@ function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
     );
   }
   if (jsonComp.operator === "?") {
-    const key = coerceToStringKey(jsonComp.right, "? operator key");
+    const key = coerceToStringKey(jsonComp.right, "? operator key", ctx);
     return {
       kind: "jsonExists",
       field: jsonField,
@@ -1192,12 +1605,13 @@ function compileJson(expr, ctx, _fns, aliasContext, outerAliases) {
     aliasContext,
     outerAliases
   );
-  return {
+  const intent = {
     kind: "jsonContains",
     field: jsonField,
     value: jsonValue,
     reversed: jsonComp.operator === "<@"
   };
+  return intent;
 }
 function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
   const relFilter = expr;
@@ -1242,321 +1656,125 @@ function expandDateRangeList(field, patterns, negated) {
           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}`
-      );
-  }
-}
-
-// src/compiler/compile-mutation.ts
-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);
-    }
-  }
-  if (returning) {
-    return {
-      mutation: { ...mutation, returning }
-    };
-  }
-  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);
-  }
-}
-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 values = [];
-  for (const row of insert.rows) {
-    const rowValues = {};
-    const rowColumns = /* @__PURE__ */ new Set();
-    for (const assignment of row) {
-      rowColumns.add(assignment.column);
-      rowValues[assignment.column] = expressionToValue(assignment.value);
-    }
-    for (const col of allColumns) {
-      if (!rowColumns.has(col)) {
-        rowValues[col] = void 0;
-      }
-    }
-    values.push(rowValues);
-  }
-  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: "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: insertFrom.limit }
-  };
-}
-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);
-    set[assignment.column] = expressionToValue(assignment.value);
-  }
-  if (update.where) {
-    return {
-      type: "update",
-      table: update.table,
-      set,
-      where: resolveBindingsInWhere(
-        fns.compileExpression(update.where, ctx, fns),
-        bindings
-      )
-    };
-  }
-  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"
-    );
-  }
-  return {
-    type: "update",
-    table: update.table,
-    set,
-    allowAll: true
-  };
-}
-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
-      )
-    };
-  }
-  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 result = conditions.length === 1 ? conditions[0] : { kind: "or", conditions };
+  if (negated) {
+    return { kind: "not", condition: result };
   }
-  return {
-    type: "delete",
-    table: del.table,
-    allowAll: true
-  };
+  return result;
 }
-function compileUpsert(upsert, ctx) {
-  ctx.validator?.validateTable(upsert.table);
-  const values = {};
-  for (const assignment of upsert.assignments) {
-    ctx.validator?.validateColumn(upsert.table, assignment.column);
-    values[assignment.column] = expressionToValue(assignment.value);
-  }
-  for (const col of upsert.conflictColumns) {
-    ctx.validator?.validateColumn(upsert.table, col);
-  }
-  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."
-    );
+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}`
+      );
   }
-  return {
-    type: "upsert",
-    table: upsert.table,
-    values: [values],
-    onConflict: { columns: upsert.conflictColumns },
-    action: { type: "doUpdate", set: values }
+}
+function paramExpressionIntent(param, alias) {
+  const intent = { ...param };
+  if (alias !== void 0) intent.as = alias;
+  return intent;
+}
+function literalExpressionIntent(value, alias) {
+  const intent = {
+    kind: "literal",
+    value
   };
+  if (alias !== void 0) intent.as = alias;
+  return intent;
 }
-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 resolveLagLeadOffset(expr, ctx) {
+  if (expr.type === "number") {
+    const resolved = resolveIntegerCount(expr.value, ctx, "lag/lead offset");
+    return isParamIntent(resolved) ? resolved.value : resolved;
   }
-  for (const col of upsertFrom.conflictColumns) {
-    ctx.validator?.validateColumn(upsertFrom.table, col);
+  if (expr.type === "namedParam") {
+    const resolved = resolveIntegerCount(expr, ctx, "lag/lead offset");
+    return isParamIntent(resolved) ? resolved.value : resolved;
   }
-  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: upsertFrom.limit }
-  };
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    "lag/lead offset must resolve to a non-negative safe integer"
+  );
 }
-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);
-      }
-    }
-  }
-  return columns;
+function throwUnsupportedSelectFunction(fn) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Unsupported function in SELECT context: ${fn}()`
+  );
 }
-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 (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
-          };
-        }
-      }
-    }
-    return where;
+var SELECT_SCALAR_FUNCTION_NAMES = /* @__PURE__ */ new Set([
+  ...NQL_SELECT_AGGREGATE_FUNCTIONS,
+  ...NQL_SELECT_JSON_FUNCTIONS,
+  ...NQL_SELECT_SCALAR_FUNCTIONS
+]);
+function validateSelectPathExpression(expr, ctx) {
+  if (!ctx.currentFromTable || !ctx.validator) return;
+  const { segments } = expr;
+  if (segments.length === 1) {
+    ctx.validator.validateColumn(ctx.currentFromTable, segments[0]);
+    return;
   }
-  if (where.kind === "not") {
-    const notWhere = where;
-    const resolved = resolveBindingsInWhere(notWhere.condition, bindings);
-    return resolved === notWhere.condition ? where : { kind: "not", condition: resolved };
+  const firstSegmentLower = segments[0].toLowerCase();
+  if (ctx.pseudoColumnKeywords.has(firstSegmentLower)) {
+    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]);
+    }
+    return;
   }
-  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;
+  const targetTable = ctx.validator.resolveRelationTarget(
+    ctx.currentFromTable,
+    segments[0]
+  );
+  if (targetTable) {
+    ctx.validator.validateColumn(targetTable, segments[segments.length - 1]);
   }
-  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;
-    }
+function expressionToValidatedField(expr, ctx) {
+  const field = expressionToField(expr);
+  if (field && expr.type === "path") {
+    validateSelectPathExpression(expr, ctx);
   }
-  return void 0;
+  return field;
 }
 function compileSelectClause(clause, ctx, fns) {
   if (clause.items.length === 1 && clause.items[0]?.type === "star") {
@@ -1581,12 +1799,7 @@ function compileSelectClause(clause, ctx, fns) {
     } else if (item.type === "expression") {
       const expr = item.expression;
       if (expr.type === "path" && expr.segments.length === 1 && !item.alias) {
-        if (ctx.currentFromTable) {
-          ctx.validator?.validateColumn(
-            ctx.currentFromTable,
-            expr.segments[0]
-          );
-        }
+        validateSelectPathExpression(expr, ctx);
         simpleFields.push(expr.segments[0]);
       } else {
         hasExpressions = true;
@@ -1599,6 +1812,40 @@ function compileSelectClause(clause, ctx, fns) {
   }
   return { type: "expressions", columns: expressions };
 }
+function expressionToSelectValue(valueExpr, ctx, fns) {
+  const field = expressionToValidatedField(valueExpr, ctx);
+  if (field) return field;
+  if (valueExpr.type === "namedParam") {
+    return expressionToValue(valueExpr, ctx);
+  }
+  if (valueExpr.type === "string" || valueExpr.type === "number" || valueExpr.type === "boolean") {
+    return valueExpr.value;
+  }
+  if (valueExpr.type === "null") {
+    return null;
+  }
+  if (valueExpr.type === "rangeLiteral" || valueExpr.type === "dateRange") {
+    return valueExpr.value;
+  }
+  return compileExpressionToIntent(valueExpr, ctx, fns);
+}
+function expressionToFunctionArg(valueExpr, ctx, fns) {
+  const field = expressionToValidatedField(valueExpr, ctx);
+  if (field) return field;
+  if (valueExpr.type === "namedParam") {
+    return expressionToValue(valueExpr, ctx);
+  }
+  if (valueExpr.type === "string" || valueExpr.type === "number" || valueExpr.type === "boolean") {
+    return literalExpressionIntent(valueExpr.value);
+  }
+  if (valueExpr.type === "null") {
+    return literalExpressionIntent(null);
+  }
+  if (valueExpr.type === "rangeLiteral" || valueExpr.type === "dateRange") {
+    return literalExpressionIntent(valueExpr.value);
+  }
+  return compileExpressionToIntent(valueExpr, ctx, fns);
+}
 function compileSelectExpression(item, ctx, fns) {
   if (item.type === "star") {
     return { kind: "column", column: "*" };
@@ -1618,6 +1865,7 @@ function compileSelectExpression(item, ctx, fns) {
     const fn = expr.name.toLowerCase();
     if (isAggregateFunction(fn)) {
       let field;
+      let firstArgAsExtraArg;
       if (expr.args.length === 0) {
         if (fn === "count") {
           field = "*";
@@ -1627,56 +1875,72 @@ function compileSelectExpression(item, ctx, fns) {
           );
         }
       } else {
-        field = expressionToField(expr.args[0]) ?? expressionToSql(expr.args[0]);
-        if (ctx.currentFromTable && field !== "*" && !field.includes(".")) {
-          ctx.validator?.validateColumn(ctx.currentFromTable, field);
+        const firstArg = expr.args[0];
+        const firstField = expressionToValidatedField(firstArg, ctx);
+        if (firstField) {
+          field = firstField;
+        } else if (firstArg.type === "namedParam") {
+          firstArgAsExtraArg = [expressionToValue(firstArg, ctx)];
+        } else {
+          field = expressionToSql(firstArg);
         }
       }
-      const extraArgs = expr.args.length > 1 ? expr.args.slice(1).map((a) => expressionToField(a) ?? expressionToValue(a)) : void 0;
-      return {
+      const extraArgs = expr.args.length > 1 ? expr.args.slice(1).map(
+        (a) => expressionToValidatedField(a, ctx) ?? expressionToSelectValue(a, ctx, fns)
+      ) : void 0;
+      const aggregateArgs = firstArgAsExtraArg ? [...firstArgAsExtraArg, ...extraArgs ?? []] : extraArgs;
+      const aggregateIntent = {
         kind: "aggregate",
         function: fn,
-        field,
+        ...field !== void 0 && { field },
         ...exprItem.alias !== void 0 && { as: exprItem.alias },
         ...expr.distinct && { distinct: true },
-        ...extraArgs && { extraArgs }
+        ...aggregateArgs && { extraArgs: aggregateArgs }
       };
+      return aggregateIntent;
     }
-    const jsonIntent = compileJsonFunction(fn, expr.args, exprItem.alias);
+    const jsonIntent = compileJsonFunction(fn, expr.args, exprItem.alias, ctx);
     if (jsonIntent) return jsonIntent;
+    if (!SELECT_SCALAR_FUNCTION_NAMES.has(fn)) {
+      throwUnsupportedSelectFunction(fn);
+    }
     return {
       kind: "function",
-      name: expr.name,
-      args: expr.args.map((a) => expressionToField(a) ?? expressionToValue(a)),
+      name: fn,
+      args: expr.args.map((a) => expressionToFunctionArg(a, ctx, fns)),
       ...exprItem.alias !== void 0 && { as: exprItem.alias }
     };
   }
   if (expr.type === "window") {
     const windowExpr = expr;
     const fn = windowExpr.function.toLowerCase();
+    if (!isNqlSelectWindowFunctionAllowed(fn)) {
+      throwUnsupportedSelectFunction(fn);
+    }
+    const windowFn = fn;
     let field;
     if (windowExpr.args.length > 0) {
-      field = expressionToField(windowExpr.args[0]) ?? expressionToSql(windowExpr.args[0]);
+      field = expressionToValidatedField(windowExpr.args[0], ctx) ?? expressionToSql(windowExpr.args[0]);
     }
     let offset;
     let defaultValue;
-    if (fn === "lag" || fn === "lead") {
+    if (windowFn === "lag" || windowFn === "lead") {
       if (windowExpr.args.length > 1) {
-        offset = expressionToValue(windowExpr.args[1]);
+        offset = resolveLagLeadOffset(windowExpr.args[1], ctx);
       }
       if (windowExpr.args.length > 2) {
-        defaultValue = expressionToValue(windowExpr.args[2]);
+        defaultValue = expressionToValue(windowExpr.args[2], ctx);
       }
     }
     const partitionBy = windowExpr.partitionBy.length > 0 ? windowExpr.partitionBy.map((e) => {
-      const f = expressionToField(e) ?? expressionToSql(e);
+      const f = expressionToValidatedField(e, ctx) ?? expressionToSql(e);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
         ctx.validator?.validateColumn(ctx.currentFromTable, f);
       }
       return f;
     }) : void 0;
     const orderBy = windowExpr.orderBy.length > 0 ? windowExpr.orderBy.map((o) => {
-      const f = expressionToField(o.expression) ?? expressionToSql(o.expression);
+      const f = expressionToValidatedField(o.expression, ctx) ?? expressionToSql(o.expression);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
         ctx.validator?.validateColumn(ctx.currentFromTable, f);
       }
@@ -1686,19 +1950,19 @@ function compileSelectExpression(item, ctx, fns) {
       ...partitionBy && { partitionBy },
       ...orderBy && { orderBy }
     };
-    const alias = exprItem.alias ?? fn;
-    if (isRankingWindowFunction(fn)) {
+    const alias = exprItem.alias ?? windowFn;
+    if (isRankingWindowFunction(windowFn)) {
       return {
         kind: "window",
-        function: fn,
+        function: windowFn,
         alias,
         over
       };
     }
-    if (fn === "lag" || fn === "lead") {
+    if (windowFn === "lag" || windowFn === "lead") {
       return {
         kind: "window",
-        function: fn,
+        function: windowFn,
         field: field ?? "",
         alias,
         ...offset !== void 0 && { offset },
@@ -1708,7 +1972,7 @@ function compileSelectExpression(item, ctx, fns) {
     }
     return {
       kind: "window",
-      function: fn,
+      function: windowFn,
       ...field !== void 0 && { field },
       alias,
       over
@@ -1723,9 +1987,7 @@ function compileSelectExpression(item, ctx, fns) {
   }
   if (expr.type === "path" && expr.segments.length === 1) {
     const column = expr.segments[0];
-    if (ctx.currentFromTable) {
-      ctx.validator?.validateColumn(ctx.currentFromTable, column);
-    }
+    validateSelectPathExpression(expr, ctx);
     if (exprItem.alias) {
       return { kind: "columnAlias", column, alias: exprItem.alias };
     }
@@ -1734,26 +1996,32 @@ function compileSelectExpression(item, ctx, fns) {
   if (expr.type === "path" && expr.segments.length > 1) {
     return compileMultiSegmentPath(expr, exprItem, ctx);
   }
+  if (expr.type === "namedParam") {
+    return paramExpressionIntent(
+      expressionToValue(expr, ctx),
+      exprItem.alias
+    );
+  }
   if (expr.type === "binary" && ["+", "-", "*", "/", "%"].includes(expr.operator)) {
-    const leftField = expressionToField(expr.left);
-    const rightField = expressionToField(expr.right);
+    const leftField = expressionToValidatedField(expr.left, ctx);
+    const rightField = expressionToValidatedField(expr.right, ctx);
     return {
       kind: "arithmetic",
-      left: leftField ?? expressionToValue(expr.left),
+      left: leftField ?? expressionToSelectValue(expr.left, ctx, fns),
       operator: expr.operator,
-      right: rightField ?? expressionToValue(expr.right),
+      right: rightField ?? expressionToSelectValue(expr.right, ctx, fns),
       ...exprItem.alias !== void 0 && { as: exprItem.alias }
     };
   }
   if (expr.type === "unary") {
     const unary = expr;
     if (unary.operator === "-") {
-      const operandField = expressionToField(unary.operand);
+      const operandField = expressionToValidatedField(unary.operand, ctx);
       return {
         kind: "arithmetic",
         left: -1,
         operator: "*",
-        right: operandField ?? expressionToValue(unary.operand),
+        right: operandField ?? expressionToSelectValue(unary.operand, ctx, fns),
         ...exprItem.alias !== void 0 && { as: exprItem.alias }
       };
     }
@@ -1763,7 +2031,7 @@ function compileSelectExpression(item, ctx, fns) {
     return compileCaseExpression(expr, exprItem, ctx, fns);
   }
   if (expr.type === "jsonAccess") {
-    const baseField = expressionToField(expr.base);
+    const baseField = expressionToValidatedField(expr.base, ctx);
     if (!baseField) {
       throw new Error("JSON access base must be a field reference");
     }
@@ -1775,6 +2043,15 @@ function compileSelectExpression(item, ctx, fns) {
       ...exprItem.alias !== void 0 && { as: exprItem.alias }
     };
   }
+  if (expr.type === "string" || expr.type === "number" || expr.type === "boolean" || expr.type === "null" || expr.type === "rangeLiteral" || expr.type === "dateRange") {
+    if (expr.type === "null") {
+      return literalExpressionIntent(null, exprItem.alias);
+    }
+    if (expr.type === "rangeLiteral" || expr.type === "dateRange") {
+      return literalExpressionIntent(expr.value, exprItem.alias);
+    }
+    return literalExpressionIntent(expr.value, exprItem.alias);
+  }
   throw new Error(
     `Unsupported expression type in SELECT: ${expr.type}. This expression cannot be compiled to IntentAST. Consider extending the grammar or using a supported expression.`
   );
@@ -1850,21 +2127,25 @@ function compileMultiSegmentPath(expr, item, ctx) {
 }
 function compileCaseExpression(caseExpr, item, ctx, fns) {
   if (caseExpr.subject) {
-    const subjectField = expressionToField(caseExpr.subject);
+    const subjectField = expressionToValidatedField(caseExpr.subject, ctx);
     if (!subjectField) {
       throw new Error("Simple CASE subject must be a column reference");
     }
+    const when = caseExpr.whenClauses.map((wc) => {
+      const condition = {
+        kind: "comparison",
+        field: subjectField,
+        operator: "eq",
+        value: expressionToValue(wc.condition, ctx)
+      };
+      return {
+        condition,
+        result: compileExpressionToIntent(wc.result, ctx, fns)
+      };
+    });
     return {
       kind: "case",
-      when: caseExpr.whenClauses.map((wc) => ({
-        condition: {
-          kind: "comparison",
-          field: subjectField,
-          operator: "eq",
-          value: expressionToValue(wc.condition)
-        },
-        result: compileExpressionToIntent(wc.result, ctx, fns)
-      })),
+      when,
       ...caseExpr.elseClause && {
         else: compileExpressionToIntent(caseExpr.elseClause, ctx, fns)
       },
@@ -1891,21 +2172,28 @@ function compileExpressionToIntent(expr, ctx, fns) {
         `CASE WHEN condition left side must be a column path, got ${cmp.left.type}`
       );
     }
+    validateSelectPathExpression(cmp.left, ctx);
+    if (cmp.right.type === "path") {
+      validateSelectPathExpression(cmp.right, ctx);
+    }
     const column = cmp.left.segments.join(".");
-    const value = expressionToValue(cmp.right);
-    return {
+    const value = expressionToValue(cmp.right, ctx);
+    const intent = {
       kind: "comparison",
       column,
       operator: cmp.operator,
       value
     };
+    return intent;
   }
-  if (expr.type === "string" || expr.type === "number" || expr.type === "boolean" || expr.type === "null") {
-    const value = expr.type === "null" ? null : expr.value;
-    return {
-      kind: "literal",
-      value
-    };
+  if (expr.type === "string" || expr.type === "number" || expr.type === "boolean" || expr.type === "null" || expr.type === "namedParam") {
+    if (expr.type === "namedParam") {
+      return expressionToValue(expr, ctx);
+    }
+    if (expr.type === "null") {
+      return literalExpressionIntent(null);
+    }
+    return literalExpressionIntent(expr.value);
   }
   const selectItem = {
     type: "expression",
@@ -1913,13 +2201,20 @@ function compileExpressionToIntent(expr, ctx, fns) {
   };
   return compileSelectExpression(selectItem, ctx, fns);
 }
-var JSON_FUNCTION_NAMES = /* @__PURE__ */ new Set([
-  "json_extract",
-  "json_extract_text",
-  "json_path",
-  "json_path_text"
-]);
-function compileJsonFunction(fn, args, alias) {
+var JSON_FUNCTION_NAMES = new Set(
+  NQL_SELECT_JSON_FUNCTIONS
+);
+function compileJsonPathArgs(fn, args, ctx) {
+  const keys = args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`, ctx));
+  const firstArg = args[1];
+  const first = keys[0];
+  if (args.length === 2 && firstArg?.type === "string" && typeof first === "string" && first?.startsWith("{") && first.endsWith("}")) {
+    const inner = first.slice(1, -1);
+    return inner.length === 0 ? [] : inner.split(",");
+  }
+  return keys;
+}
+function compileJsonFunction(fn, args, alias, ctx) {
   if (!JSON_FUNCTION_NAMES.has(fn)) return null;
   if (args.length < 2) {
     throw new NqlSemanticException(
@@ -1935,7 +2230,7 @@ function compileJsonFunction(fn, args, alias) {
     );
   }
   if (fn === "json_extract" || fn === "json_extract_text") {
-    const keys = args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`));
+    const keys = args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`, ctx));
     return {
       kind: "jsonExtract",
       field,
@@ -1945,13 +2240,11 @@ function compileJsonFunction(fn, args, alias) {
     };
   }
   if (fn === "json_path" || fn === "json_path_text") {
-    const keys = args.slice(1).map((a) => coerceToStringKey(a, `${fn}() path argument`));
-    const first = keys[0];
-    const pathStr = keys.length === 1 && first?.startsWith("{") && first.endsWith("}") ? first : `{${keys.join(",")}}`;
+    const path = compileJsonPathArgs(fn, args, ctx);
     return {
       kind: "jsonPathExtract",
       field,
-      path: pathStr,
+      path,
       mode: fn === "json_path" ? "json" : "text",
       ...alias !== void 0 && { as: alias }
     };
@@ -1972,6 +2265,10 @@ var DEFAULT_RECURSIVE_KEYWORDS = [
 ];
 
 // src/compiler/index.ts
+function allowsInternalParams(options) {
+  const internalOptions = options?.[NQL_INTERNAL_COMPILER_OPTIONS];
+  return internalOptions?.allowInternalParams === true;
+}
 var NqlCompiler = class {
   ctx;
   fns;
@@ -1989,15 +2286,19 @@ var NqlCompiler = class {
         );
       }
     }
+    const params = options?.params ?? {};
+    const allowInternalParams = allowsInternalParams(options);
+    validateParamsMap(params, { allowInternalParams });
     this.ctx = {
       currentFromTable: void 0,
       currentRelationTarget: void 0,
       pseudoColumnKeywords,
       recursiveKeywords,
       validator,
-      params: options?.params ?? {},
+      params,
       maxAnyItems: maxAnyItemsRaw ?? MAX_ANY_ITEMS,
-      allowUnfilteredMutations: options?.allowUnfilteredMutations ?? false
+      allowUnfilteredMutations: options?.allowUnfilteredMutations ?? false,
+      allowInternalParams
     };
     this.fns = {
       compileQuery: (query, ctx) => compileQuery(query, ctx, this.fns),
@@ -2440,6 +2741,11 @@ var allTokens = [
   // ? (no conflict with other tokens)
 ];
 var NqlLexer = new Lexer(allTokens);
+
+// src/lexer/index.ts
+function tokenize(input) {
+  return NqlLexer.tokenize(input);
+}
 var NqlParser = class extends CstParser {
   constructor() {
     super(allTokens, {
@@ -2587,7 +2893,7 @@ var NqlParser = class extends CstParser {
     this.SUBRULE(this.orderList);
   });
   /**
-   * limit_clause = "limit" [ident_segment ("." ident_segment)*] NUMBER ;
+   * limit_clause = "limit" [ident_segment ("." ident_segment)*] (NUMBER | NAMED_PARAM) ;
    */
   limitClause = this.RULE("limitClause", () => {
     this.CONSUME(Limit);
@@ -2598,14 +2904,29 @@ var NqlParser = class extends CstParser {
         this.SUBRULE2(this.identSegment);
       });
     });
-    this.CONSUME(NumberLiteral);
+    this.SUBRULE(this.numericValueAtom);
   });
   /**
-   * offset_clause = "offset" NUMBER ;
+   * offset_clause = "offset" (NUMBER | NAMED_PARAM) ;
    */
   offsetClause = this.RULE("offsetClause", () => {
     this.CONSUME(Offset);
-    this.CONSUME(NumberLiteral);
+    this.SUBRULE(this.numericValueAtom);
+  });
+  /**
+   * numeric_value_atom = NUMBER | NAMED_PARAM ;
+   *
+   * Structural-position durability rule: value positions that consume scalar
+   * values may add `NamedParam` here and validate the resolved value in the
+   * compiler. Structural positions such as identifiers, directions, lock modes,
+   * and traversal depth hints must not consume this helper; use nqlRaw()/builder
+   * APIs for trusted dynamic structure.
+   */
+  numericValueAtom = this.RULE("numericValueAtom", () => {
+    this.OR([
+      { ALT: () => this.CONSUME(NumberLiteral) },
+      { ALT: () => this.CONSUME(NamedParam) }
+    ]);
   });
   /**
    * lock_clause = lock_strength [ lock_wait_policy ] ;
@@ -2869,7 +3190,7 @@ var NqlParser = class extends CstParser {
     ]);
   });
   /**
-   * range_op_suffix = range_op (range_literal | literal) ;
+   * range_op_suffix = range_op (range_literal | literal | named_param_expr) ;
    * Example: overlaps [1,10) or contains (0,100) or contains 25
    * Note: contains can take a scalar value (e.g., contains 25 checks if range contains the value)
    */
@@ -2877,7 +3198,8 @@ var NqlParser = class extends CstParser {
     this.SUBRULE(this.rangeOp);
     this.OR([
       { ALT: () => this.SUBRULE(this.rangeLiteral) },
-      { ALT: () => this.SUBRULE2(this.literal) }
+      { ALT: () => this.SUBRULE2(this.literal) },
+      { ALT: () => this.SUBRULE(this.namedParamExpr) }
     ]);
   });
   /**
@@ -3118,10 +3440,12 @@ var NqlParser = class extends CstParser {
     });
   });
   /**
-   * primary_expr = literal | case_expr | path_expr | func_call | "(" expr ")" | "(" scalar_subquery ")" ;
+   * primary_expr = named_param_expr | literal | case_expr | path_expr | func_call | "(" expr ")" | "(" scalar_subquery ")" ;
    */
   primaryExpr = this.RULE("primaryExpr", () => {
     this.OR([
+      // Bound value parameter: :paramName
+      { ALT: () => this.SUBRULE(this.namedParamExpr) },
       // Range literal in value context (unambiguous: starts with '[')
       {
         GATE: () => this.LA(1).tokenType === LBracket,
@@ -3159,6 +3483,12 @@ var NqlParser = class extends CstParser {
       }
     ]);
   });
+  /**
+   * named_param_expr = NAMED_PARAM ;
+   */
+  namedParamExpr = this.RULE("namedParamExpr", () => {
+    this.CONSUME(NamedParam);
+  });
   /**
    * Check if at start of scalar subquery (ident | ...)
    */
@@ -3515,7 +3845,7 @@ var NqlParser = class extends CstParser {
     ]);
   });
   /**
-   * insert_from_stmt = "insert" "into" ident_segment "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+   * insert_from_stmt = "insert" "into" ident_segment "from" ident_segment [ "where" boolean_expr ] [ "limit" numeric_value_atom ] ;
    * @example insert into archived_users from users where active = false limit 100
    */
   insertFromStmt = this.RULE("insertFromStmt", () => {
@@ -3530,7 +3860,7 @@ var NqlParser = class extends CstParser {
     });
     this.OPTION2(() => {
       this.CONSUME(Limit);
-      this.CONSUME(NumberLiteral);
+      this.SUBRULE(this.numericValueAtom);
     });
   });
   /**
@@ -3590,7 +3920,7 @@ var NqlParser = class extends CstParser {
     });
   });
   /**
-   * upsert_from_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+   * upsert_from_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "from" ident_segment [ "where" boolean_expr ] [ "limit" numeric_value_atom ] ;
    * @example upsert into authors on id from counts
    * @example upsert into authors on (id, email) from counts where active = true
    */
@@ -3621,7 +3951,7 @@ var NqlParser = class extends CstParser {
     });
     this.OPTION2(() => {
       this.CONSUME(Limit);
-      this.CONSUME(NumberLiteral);
+      this.SUBRULE(this.numericValueAtom);
     });
   });
   /**
@@ -3916,6 +4246,12 @@ function buildRangeOp(left, suffixNode, visit) {
     const scalar = visit(asCstNode(suffixCtx.literal[0]));
     return { type: "rangeOp", operator, left, scalar };
   }
+  if (suffixCtx.namedParamExpr) {
+    const scalar = visit(
+      asCstNode(suffixCtx.namedParamExpr[0])
+    );
+    return { type: "rangeOp", operator, left, scalar };
+  }
   throw new NqlSemanticException(
     NqlErrorCodes.SEM_INVALID_SYNTAX,
     "Range op suffix missing range literal or scalar value"
@@ -4091,6 +4427,7 @@ function visitUnaryExpr(ctx, visit) {
   return expr;
 }
 function visitPrimaryExpr(ctx, visit) {
+  if (ctx.namedParamExpr) return visit(asCstNode(ctx.namedParamExpr[0]));
   if (ctx.rangeLiteral) return visit(asCstNode(ctx.rangeLiteral[0]));
   if (ctx.literal) return visit(asCstNode(ctx.literal[0]));
   if (ctx.caseExpr) return visit(asCstNode(ctx.caseExpr[0]));
@@ -4105,6 +4442,14 @@ function visitPrimaryExpr(ctx, visit) {
     "Invalid primary expression"
   );
 }
+function visitNamedParamExpr(ctx) {
+  const token = ctx.NamedParam?.[0];
+  const raw = token ? getImage(token) : ":unknown";
+  return {
+    type: "namedParam",
+    name: raw.slice(1)
+  };
+}
 function visitCaseExpr(ctx, visit) {
   const whenClauses = [];
   let subject;
@@ -4488,7 +4833,7 @@ function visitInsertFromStmt(ctx, visit) {
     table: target,
     source,
     where: ctx.booleanExpr ? visit(asCstNode(ctx.booleanExpr[0])) : void 0,
-    limit: ctx.NumberLiteral ? parseInt(getImage(ctx.NumberLiteral[0]), 10) : void 0
+    limit: ctx.numericValueAtom ? visit(asCstNode(ctx.numericValueAtom[0])) : void 0
   };
 }
 function visitUpdateStmt(ctx, visit) {
@@ -4563,7 +4908,7 @@ function visitUpsertFromStmt(ctx, visit) {
     conflictColumns,
     source,
     where: ctx.booleanExpr ? visit(asCstNode(ctx.booleanExpr[0])) : void 0,
-    limit: ctx.NumberLiteral ? parseInt(getImage(ctx.NumberLiteral[0]), 10) : void 0
+    limit: ctx.numericValueAtom ? visit(asCstNode(ctx.numericValueAtom[0])) : void 0
   };
 }
 function visitAssignmentList(ctx, visit) {
@@ -4671,8 +5016,8 @@ function visitOrderClause(ctx, visit) {
   return { type: "orderBy", items };
 }
 function visitLimitClause(ctx, visit) {
-  requireFirst(ctx, "NumberLiteral", "Limit clause missing number");
-  const count = parseInt(getImage(ctx.NumberLiteral[0]), 10);
+  requireFirst(ctx, "numericValueAtom", "Limit clause missing number");
+  const count = visit(asCstNode(ctx.numericValueAtom[0]));
   const segments = ctx.identSegment;
   if (segments && segments.length > 0) {
     const parts = [];
@@ -4683,13 +5028,23 @@ function visitLimitClause(ctx, visit) {
   }
   return { type: "limit", count };
 }
-function visitOffsetClause(ctx) {
-  requireFirst(ctx, "NumberLiteral", "Offset clause missing number");
+function visitOffsetClause(ctx, visit) {
+  requireFirst(ctx, "numericValueAtom", "Offset clause missing number");
   return {
     type: "offset",
-    count: parseInt(getImage(ctx.NumberLiteral[0]), 10)
+    count: visit(asCstNode(ctx.numericValueAtom[0]))
   };
 }
+function visitNumericValueAtom(ctx) {
+  if (ctx.NumberLiteral) {
+    return parseInt(getImage(ctx.NumberLiteral[0]), 10);
+  }
+  if (ctx.NamedParam) {
+    const raw = getImage(ctx.NamedParam[0]);
+    return { type: "namedParam", name: raw.slice(1) };
+  }
+  unreachable("Invalid numeric value");
+}
 function visitSelectList(ctx, visit) {
   const items = [];
   if (ctx.selectItem) {
@@ -4816,7 +5171,10 @@ var NqlCstVisitor = class extends BaseCstVisitor {
     return visitLimitClause(ctx, this.v);
   }
   offsetClause(ctx) {
-    return visitOffsetClause(ctx);
+    return visitOffsetClause(ctx, this.v);
+  }
+  numericValueAtom(ctx) {
+    return visitNumericValueAtom(ctx);
   }
   selectList(ctx) {
     return visitSelectList(ctx, this.v);
@@ -4899,6 +5257,9 @@ var NqlCstVisitor = class extends BaseCstVisitor {
   primaryExpr(ctx) {
     return visitPrimaryExpr(ctx, this.v);
   }
+  namedParamExpr(ctx) {
+    return visitNamedParamExpr(ctx);
+  }
   // -- CASE --
   caseExpr(ctx) {
     return visitCaseExpr(ctx, this.v);
@@ -5087,13 +5448,16 @@ function compile(input, schema, options, compilerOptions) {
       warnings: parseResult.warnings
     };
   } catch (err) {
-    const code = err instanceof NqlSemanticException ? err.code : NqlErrorCodes.SEM_UNREACHABLE;
+    const semanticError = err instanceof NqlSemanticException;
+    const code = semanticError ? err.code : NqlErrorCodes.SEM_UNREACHABLE;
     return {
       success: false,
       errors: [
         {
           code,
-          message: err instanceof Error ? err.message : String(err)
+          message: err instanceof Error ? err.message : String(err),
+          location: semanticError ? err.location : void 0,
+          suggestion: semanticError ? err.suggestion : void 0
         }
       ],
       warnings: []
@@ -5105,6 +5469,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 */
@@ -5120,7 +5485,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 */
@@ -5149,8 +5513,9 @@ function hasColumnValidatorShape(obj) {
 /* v8 ignore start — defensive: parser guarantees target and source identifiers -- @preserve */
 /* v8 ignore next — defensive: parser guarantees withQuery, query, or mutationPipeline -- @preserve */
 /* v8 ignore next — defensive: parser guarantees one of the clause alternatives -- @preserve */
+/* v8 ignore next — defensive: parser guarantees NumberLiteral or NamedParam -- @preserve */
 /* v8 ignore next — defensive: parser guarantees query or identSegment -- @preserve */
 
-export { NqlCompiler, NqlCstVisitor, NqlLexer, NqlParser, allTokens, compile, createCompiler, cstToAst, nqlVisitor, parse, parseCst };
+export { NqlCompiler, NqlCstVisitor, NqlLexer, NqlParser, allTokens, compile, createCompiler, cstToAst, nqlVisitor, parse, parseCst, tokenize };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map