@dbsp/nql 1.0.4 → 1.2.0

package/dist/index.js

@@ -1,6 +1,9 @@
-import { isRankingWindowFunction } from '@dbsp/types';
+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 { 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":
@@ -134,21 +220,21 @@ function expressionToValue(expr) {
     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;
@@ -313,7 +404,7 @@ function validateWhereField(ctx, field, aliasContext, originalExpr) {
     ctx.validator.validateColumn(ctx.currentFromTable, field);
   }
 }
-function coerceToStringKey(expr, contextLabel) {
+function coerceToStringKey(expr, contextLabel, ctx) {
   if (expr.type === "path") {
     const segments = expr.segments;
     if (segments.length > 1) {
@@ -334,6 +425,17 @@ function coerceToStringKey(expr, contextLabel) {
   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`
@@ -387,6 +489,21 @@ function applyIncludeLimit(includes, path, limit) {
 }
 
 // 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 compileQuery(query, ctx, fns, bindings) {
   const setClauseIndex = query.clauses.findIndex(
     (c) => c.type === "setOperation"
@@ -459,15 +576,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;
@@ -569,6 +696,12 @@ function getExplicitColumnCount(intent) {
 }
 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 = {
     table: query.table,
     clauses: query.clauses.slice(0, setClauseIndex)
@@ -576,7 +709,7 @@ function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
   const left = compileQuery(leftQuery, ctx, fns, bindings);
   let right;
   if (setClause.right) {
-    right = compileQuery(setClause.right, ctx, fns, bindings);
+    right = compileNestedQuery(setClause.right, ctx, fns, bindings);
   } else if (setClause.boundName) {
     const bound = bindings?.get(setClause.boundName);
     if (!bound) {
@@ -626,6 +759,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 };
 }
@@ -646,7 +787,7 @@ function compileWithQuery(astNode, ctx, fns) {
   try {
     const ctes = [];
     for (const cte of astNode.ctes) {
-      const bodyResult = compileQuery(cte.query, ctx, fns);
+      const bodyResult = compileNestedQuery(cte.query, ctx, fns);
       if ("kind" in bodyResult && bodyResult.kind === "setOperation") {
         throw new NqlSemanticException(
           NqlErrorCodes.SEM_UNKNOWN_TABLE,
@@ -788,6 +929,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") {
@@ -851,7 +995,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
       aliasContext,
       outerAliases
     );
-    return {
+    const intent2 = {
       kind: "comparison",
       field: baseField,
       operator: operator2,
@@ -859,6 +1003,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();
@@ -876,7 +1021,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,
@@ -884,7 +1029,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
         aliasContext,
         outerAliases
       );
-      return {
+      const intent2 = {
         kind: "comparison",
         field: baseField,
         operator: operator2,
@@ -892,6 +1037,7 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
         jsonPath: keys,
         jsonMode: fn === "json_extract" ? "json" : "text"
       };
+      return intent2;
     }
   }
   const field = expressionToField(comp.left, aliasContext);
@@ -903,20 +1049,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;
@@ -944,12 +1092,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") {
@@ -962,11 +1111,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) {
@@ -975,8 +1125,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);
@@ -1005,7 +1159,11 @@ function compileMembership(expr, ctx, fns, aliasContext, outerAliases) {
       return expandDateRangeList(field, dateRangeValues, inExpr.negated);
     }
   } else if ("type" in inExpr.values && inExpr.values.type === "subquery") {
-    const subquery = fns.compileQuery(inExpr.values.query, ctx);
+    const subquery = compileNestedQuery(
+      inExpr.values.query,
+      ctx,
+      fns
+    );
     const result2 = {
       kind: "in",
       field,
@@ -1052,27 +1210,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);
@@ -1112,12 +1271,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) {
@@ -1133,7 +1293,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,
@@ -1154,7 +1314,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,
@@ -1167,12 +1327,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;
@@ -1266,8 +1427,9 @@ function compileExpression(expr, ctx, fns, aliasContext, outerAliases) {
       );
   }
 }
-
-// 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);
@@ -1315,7 +1477,7 @@ function compileInsert(insert, ctx) {
     const rowColumns = /* @__PURE__ */ new Set();
     for (const assignment of row) {
       rowColumns.add(assignment.column);
-      rowValues[assignment.column] = expressionToValue(assignment.value);
+      assignMutationValue(rowValues, assignment.column, assignment.value, ctx);
     }
     for (const col of allColumns) {
       if (!rowColumns.has(col)) {
@@ -1331,7 +1493,11 @@ function compileInsert(insert, ctx) {
   };
 }
 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",
@@ -1343,7 +1509,9 @@ function compileInsertFrom(insertFrom, ctx, fns, bindings) {
     ...insertFrom.where !== void 0 && {
       where: fns.compileExpression(insertFrom.where, ctx, fns)
     },
-    ...insertFrom.limit !== void 0 && { limit: insertFrom.limit }
+    ...insertFrom.limit !== void 0 && {
+      limit: resolveIntegerCount(insertFrom.limit, ctx, "insert-from limit")
+    }
   };
 }
 function compileUpdate(update, ctx, fns, bindings) {
@@ -1352,7 +1520,7 @@ function compileUpdate(update, ctx, fns, bindings) {
   const set = {};
   for (const assignment of update.assignments) {
     ctx.validator?.validateColumn(update.table, assignment.column);
-    set[assignment.column] = expressionToValue(assignment.value);
+    assignMutationValue(set, assignment.column, assignment.value, ctx);
   }
   if (update.where) {
     return {
@@ -1365,6 +1533,11 @@ function compileUpdate(update, 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,
@@ -1385,6 +1558,11 @@ function compileDelete(del, 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,
@@ -1396,11 +1574,16 @@ function compileUpsert(upsert, ctx) {
   const values = {};
   for (const assignment of upsert.assignments) {
     ctx.validator?.validateColumn(upsert.table, assignment.column);
-    values[assignment.column] = expressionToValue(assignment.value);
+    assignMutationValue(values, assignment.column, assignment.value, ctx);
   }
   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."
+    );
+  }
   return {
     type: "upsert",
     table: upsert.table,
@@ -1410,7 +1593,14 @@ function compileUpsert(upsert, ctx) {
   };
 }
 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",
@@ -1426,7 +1616,9 @@ function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
     ...upsertFrom.where !== void 0 && {
       where: fns.compileExpression(upsertFrom.where, ctx, fns)
     },
-    ...upsertFrom.limit !== void 0 && { limit: upsertFrom.limit }
+    ...upsertFrom.limit !== void 0 && {
+      limit: resolveIntegerCount(upsertFrom.limit, ctx, "upsert-from limit")
+    }
   };
 }
 function extractReturningColumns(clause, ctx) {
@@ -1454,7 +1646,7 @@ function resolveBindingsInWhere(where, bindings) {
     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) {
+      if (!isParamIntent(val) && val && typeof val === "object" && "$ref" in val) {
         const ref = val.$ref;
         if (bindings.has(ref)) {
           const boundQuery = bindings.get(ref);
@@ -1507,6 +1699,77 @@ function extractBindName(stmt) {
   }
   return void 0;
 }
+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 resolveLagLeadOffset(expr, ctx) {
+  if (expr.type === "number") {
+    const resolved = resolveIntegerCount(expr.value, ctx, "lag/lead offset");
+    return isParamIntent(resolved) ? resolved.value : resolved;
+  }
+  if (expr.type === "namedParam") {
+    const resolved = resolveIntegerCount(expr, ctx, "lag/lead offset");
+    return isParamIntent(resolved) ? resolved.value : resolved;
+  }
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    "lag/lead offset must resolve to a non-negative safe integer"
+  );
+}
+function throwUnsupportedSelectFunction(fn) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Unsupported function in SELECT context: ${fn}()`
+  );
+}
+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;
+  }
+  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;
+  }
+  const targetTable = ctx.validator.resolveRelationTarget(
+    ctx.currentFromTable,
+    segments[0]
+  );
+  if (targetTable) {
+    ctx.validator.validateColumn(targetTable, segments[segments.length - 1]);
+  }
+}
+function expressionToValidatedField(expr, ctx) {
+  const field = expressionToField(expr);
+  if (field && expr.type === "path") {
+    validateSelectPathExpression(expr, ctx);
+  }
+  return field;
+}
 function compileSelectClause(clause, ctx, fns) {
   if (clause.items.length === 1 && clause.items[0]?.type === "star") {
     return { type: "all" };
@@ -1530,12 +1793,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;
@@ -1548,6 +1806,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: "*" };
@@ -1567,6 +1859,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 = "*";
@@ -1576,56 +1869,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);
       }
@@ -1635,19 +1944,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 },
@@ -1657,7 +1966,7 @@ function compileSelectExpression(item, ctx, fns) {
     }
     return {
       kind: "window",
-      function: fn,
+      function: windowFn,
       ...field !== void 0 && { field },
       alias,
       over
@@ -1666,15 +1975,13 @@ function compileSelectExpression(item, ctx, fns) {
   if (expr.type === "subquery") {
     return {
       kind: "subquery",
-      query: fns.compileQuery(expr.query, ctx),
+      query: compileNestedQuery(expr.query, ctx, fns),
       ...exprItem.alias !== void 0 && { as: exprItem.alias }
     };
   }
   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 };
     }
@@ -1683,26 +1990,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 }
       };
     }
@@ -1712,7 +2025,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");
     }
@@ -1724,6 +2037,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.`
   );
@@ -1799,21 +2121,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)
       },
@@ -1840,21 +2166,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",
@@ -1862,13 +2195,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(
@@ -1884,7 +2224,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,
@@ -1894,13 +2234,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 }
     };
@@ -1921,6 +2259,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;
@@ -1938,14 +2280,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 ?? {},
-      maxAnyItems: maxAnyItemsRaw ?? MAX_ANY_ITEMS
+      params,
+      maxAnyItems: maxAnyItemsRaw ?? MAX_ANY_ITEMS,
+      allowUnfilteredMutations: options?.allowUnfilteredMutations ?? false,
+      allowInternalParams
     };
     this.fns = {
       compileQuery: (query, ctx) => compileQuery(query, ctx, this.fns),
@@ -1963,15 +2310,27 @@ var NqlCompiler = class {
     if (program.statements.length === 1) {
       return this.compileSingleStatement(program.statements[0]);
     }
+    for (let i = 0; i < program.statements.length - 1; i++) {
+      const stmt = program.statements[i];
+      const bindName = extractBindName(stmt);
+      if (!bindName) {
+        throw new Error(
+          `Multiple statements require explicit binding: statement ${i + 1} of ${program.statements.length} has no '| bind <name>' clause. Add a \`| bind <name>\` clause to each statement except the last, or pass a single statement.`
+        );
+      }
+    }
     const bindings = /* @__PURE__ */ new Map();
     const mutationBindings = /* @__PURE__ */ new Map();
+    const materializedBindStatements = /* @__PURE__ */ new Set();
     let lastResult = {};
-    for (const stmt of program.statements) {
+    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) {
         if (lastResult.query) {
           bindings.set(bindName, lastResult.query);
+          materializedBindStatements.add(i);
         } else if (lastResult.mutation?.returning?.length) {
           mutationBindings.set(bindName, lastResult.mutation);
           bindings.set(bindName, {
@@ -1982,9 +2341,18 @@ var NqlCompiler = class {
               fields: [...lastResult.mutation.returning]
             }
           });
+          materializedBindStatements.add(i);
         }
       }
     }
+    for (let i = 0; i < program.statements.length - 1; i++) {
+      const bindName = extractBindName(program.statements[i]);
+      if (bindName && !materializedBindStatements.has(i)) {
+        throw new Error(
+          `statement ${i + 1} of ${program.statements.length} binds '${bindName}' but produces no referenceable result \u2014 a mutation used as a binding must include a \`returning\` clause.`
+        );
+      }
+    }
     const hasMutationBindings = mutationBindings.size > 0;
     if (bindings.size > 0) {
       return {
@@ -2367,6 +2735,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, {
@@ -2514,7 +2887,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);
@@ -2525,14 +2898,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 ] ;
@@ -2796,7 +3184,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)
    */
@@ -2804,7 +3192,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) }
     ]);
   });
   /**
@@ -3045,10 +3434,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,
@@ -3086,6 +3477,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 | ...)
    */
@@ -3442,7 +3839,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", () => {
@@ -3457,7 +3854,7 @@ var NqlParser = class extends CstParser {
     });
     this.OPTION2(() => {
       this.CONSUME(Limit);
-      this.CONSUME(NumberLiteral);
+      this.SUBRULE(this.numericValueAtom);
     });
   });
   /**
@@ -3517,7 +3914,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
    */
@@ -3548,7 +3945,7 @@ var NqlParser = class extends CstParser {
     });
     this.OPTION2(() => {
       this.CONSUME(Limit);
-      this.CONSUME(NumberLiteral);
+      this.SUBRULE(this.numericValueAtom);
     });
   });
   /**
@@ -3843,6 +4240,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"
@@ -4018,6 +4421,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]));
@@ -4032,6 +4436,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;
@@ -4415,7 +4827,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) {
@@ -4490,7 +4902,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) {
@@ -4598,8 +5010,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 = [];
@@ -4610,13 +5022,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) {
@@ -4743,7 +5165,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);
@@ -4826,6 +5251,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);
@@ -5014,13 +5442,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: []
@@ -5076,8 +5507,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