@dbsp/adapter-pgsql 1.1.1 → 1.2.1

package/dist/index.js

@@ -1074,6 +1074,19 @@ var init_param_ref = __esm({
   }
 });
 
+// src/handlers/expression/param-value.ts
+function bindParameter(value, state) {
+  const idx = ++state.paramIndex;
+  state.parameters.push(value);
+  return createParamRef(idx);
+}
+var init_param_value = __esm({
+  "src/handlers/expression/param-value.ts"() {
+    "use strict";
+    init_param_ref();
+  }
+});
+
 // src/handlers/expression/case-value.ts
 function resolveCaseValue(value, alias, schema, naming, state, nestedCaseHandler) {
   if (value === null || value === void 0) {
@@ -1083,12 +1096,12 @@ function resolveCaseValue(value, alias, schema, naming, state, nestedCaseHandler
     return columnRef(value, alias, schema, naming);
   }
   if (typeof value !== "object") {
-    const idx = ++state.paramIndex;
-    state.parameters.push(value);
-    return createParamRef(idx);
+    return bindParameter(value, state);
   }
   const expr = value;
   switch (expr.kind) {
+    case "param":
+      return bindParameter(expr.value, state);
     case "literal":
       if (expr.value === null || expr.value === void 0)
         return nullConstNode();
@@ -1099,11 +1112,7 @@ function resolveCaseValue(value, alias, schema, naming, state, nestedCaseHandler
           return integerNode(expr.value);
         return floatNode(String(expr.value));
       }
-      {
-        const idx = ++state.paramIndex;
-        state.parameters.push(expr.value);
-        return createParamRef(idx);
-      }
+      return bindParameter(expr.value, state);
     case "column":
       return columnRef(expr.column, alias, schema, naming);
     case "arithmetic": {
@@ -1139,9 +1148,7 @@ function resolveCaseValue(value, alias, schema, naming, state, nestedCaseHandler
       }
     // falls through
     default: {
-      const idx = ++state.paramIndex;
-      state.parameters.push(value);
-      return createParamRef(idx);
+      return bindParameter(value, state);
     }
   }
 }
@@ -1149,7 +1156,7 @@ var init_case_value = __esm({
   "src/handlers/expression/case-value.ts"() {
     "use strict";
     init_ast_helpers();
-    init_param_ref();
+    init_param_value();
   }
 });
 
@@ -1348,7 +1355,9 @@ function compileExpressionIntent(intent, ctx, state) {
     }
     case "relationColumn": {
       const rc = intent;
-      const alias = state.aliases.get(rc.relation) ?? rc.relation;
+      const relationSegments = rc.relation.split(".");
+      const leaf = relationSegments[relationSegments.length - 1] ?? rc.relation;
+      const alias = state.aliases.get(rc.relation) ?? state.aliases.get(leaf) ?? leaf;
       return columnRef(rc.column, alias, void 0, ctx.naming);
     }
     case "case": {
@@ -1428,7 +1437,17 @@ function handleAggregateExpression(expr, rootTable, decisions, applyFilter) {
   const aggAs = expr.as;
   const aggDistinct = expr.distinct;
   const aggFilter = expr.filter;
-  if (aggFunc === "count" && !aggField) {
+  const aggExtraArgs = Array.isArray(expr.extraArgs) ? expr.extraArgs : void 0;
+  if (!aggField && aggExtraArgs?.length) {
+    const decision = {
+      type: "selectNqlFunction",
+      function: aggFunc,
+      args: aggExtraArgs,
+      table: rootTable
+    };
+    if (aggAs) decision.alias = aggAs;
+    decisions.push(decision);
+  } else if (aggFunc === "count" && !aggField) {
     const decision = {
       type: "selectFunction",
       function: "count",
@@ -1480,6 +1499,16 @@ function handleRawExpression(expr, rootTable, decisions) {
   if (expr.as) decision.alias = expr.as;
   decisions.push(decision);
 }
+function handleFunctionExpression(expr, rootTable, decisions) {
+  const decision = {
+    type: "selectNqlFunction",
+    function: expr.name,
+    args: expr.args ?? [],
+    table: rootTable
+  };
+  if (expr.as) decision.alias = expr.as;
+  decisions.push(decision);
+}
 function handleWindowExpression(expr, rootTable, decisions) {
   const windowFunc = expr.function;
   const windowAlias = expr.alias;
@@ -1592,6 +1621,7 @@ var init_select_expression_handlers = __esm({
       aggregate: (expr, rootTable, decisions, applyFilter) => handleAggregateExpression(expr, rootTable, decisions, applyFilter),
       coalesce: (expr, rootTable, decisions) => handleCoalesceExpression(expr, rootTable, decisions),
       raw: (expr, rootTable, decisions) => handleRawExpression(expr, rootTable, decisions),
+      function: (expr, rootTable, decisions) => handleFunctionExpression(expr, rootTable, decisions),
       window: (expr, rootTable, decisions) => handleWindowExpression(expr, rootTable, decisions),
       case: (expr, rootTable, decisions, applyFilter, convertCondition) => handleCaseExpression(
         expr,
@@ -1601,7 +1631,8 @@ var init_select_expression_handlers = __esm({
         convertCondition
       ),
       relationColumn: (expr, rootTable, decisions) => handleRelationColumnExpression(expr, rootTable, decisions),
-      // pseudoColumn: intentional no-op — planner hints, not SQL
+      pseudoColumn: () => {
+      },
       arithmetic: (expr, rootTable, decisions) => handleArithmeticExpression(expr, rootTable, decisions),
       jsonExtract: (expr, rootTable, decisions) => handleJsonExtractExpression(expr, rootTable, decisions),
       jsonPathExtract: (expr, rootTable, decisions) => handleJsonPathExtractExpression(expr, rootTable, decisions),
@@ -1612,12 +1643,17 @@ var init_select_expression_handlers = __esm({
       ref: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
       param: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
       cast: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
-      unary: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions)
+      unary: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
+      subquery: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
+      namedArg: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
+      star: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions),
+      array: (expr, rootTable, decisions) => handleCustomExpressionSelect(expr, rootTable, decisions)
     };
   }
 });
 
 // src/intent-to-decisions.ts
+import { isParamIntent } from "@dbsp/types";
 function intentToDecisions(intent, rootTable) {
   const decisions = [];
   if (intent.select) {
@@ -1680,16 +1716,18 @@ function convertSelect(select, rootTable) {
     const columns = select.columns;
     for (const exprUnknown of columns) {
       const expr = exprUnknown;
-      const handler = EXPRESSION_HANDLERS[expr.kind];
-      if (handler) {
-        handler(
-          expr,
-          rootTable,
-          decisions,
-          applyFilterCondition,
-          convertWhereCondition
-        );
+      const kind = typeof expr.kind === "string" ? expr.kind : String(expr.kind);
+      const handler = EXPRESSION_HANDLERS[kind];
+      if (!handler) {
+        throw new UnknownSelectExpressionKindError(kind);
       }
+      handler(
+        expr,
+        rootTable,
+        decisions,
+        (decision, filter, table) => applyFilterCondition(decision, filter, table),
+        (condition, table) => convertWhereCondition(condition, table)
+      );
     }
     return decisions;
   }
@@ -1822,10 +1860,12 @@ function isOuterRef(value) {
 function containsOuterRef(where) {
   if (!where || typeof where !== "object") return false;
   const w = where;
+  if (isParamIntent(w)) return false;
   if (isOuterRef(w)) return true;
   for (const value of Object.values(w)) {
     if (Array.isArray(value)) {
-      for (const item of value) {
+      for (let i = 0; i < value.length; i++) {
+        const item = value[i];
         if (containsOuterRef(item)) return true;
       }
     } else if (typeof value === "object" && value !== null) {
@@ -2122,7 +2162,7 @@ function convertWhereCondition(condition, rootTable) {
         table: rootTable
       };
     }
-    case "jsonContains":
+    case "jsonContains": {
       return {
         type: "where",
         column: cond.field,
@@ -2130,6 +2170,7 @@ function convertWhereCondition(condition, rootTable) {
         value: cond.value,
         table: rootTable
       };
+    }
     case "any":
       return {
         type: "where",
@@ -2186,10 +2227,20 @@ function convertOrderBy(order, rootTable) {
   }
   return decision;
 }
+var UnknownSelectExpressionKindError;
 var init_intent_to_decisions = __esm({
   "src/intent-to-decisions.ts"() {
     "use strict";
     init_select_expression_handlers();
+    UnknownSelectExpressionKindError = class extends Error {
+      constructor(kind) {
+        super(`Unknown SELECT expression kind: ${kind}`);
+        this.kind = kind;
+        this.name = "UnknownSelectExpressionKindError";
+      }
+      kind;
+      code = "ERR_ADAPTER_UNKNOWN_SELECT_EXPRESSION_KIND";
+    };
   }
 });
 
@@ -2750,12 +2801,24 @@ var init_compiler_utils = __esm({
   }
 });
 
+// src/param-intent.ts
+import { isParamIntent as isParamIntent2 } from "@dbsp/types";
+function unwrapParamIntent(value) {
+  return isParamIntent2(value) ? value.value : value;
+}
+var init_param_intent = __esm({
+  "src/param-intent.ts"() {
+    "use strict";
+  }
+});
+
 // src/handlers/where/utils.ts
-import { isFieldRef } from "@dbsp/types";
+import { isFieldRef, isParamIntent as isParamIntent3 } from "@dbsp/types";
 function buildColumnRef(column, ctx) {
   if (column.includes(".")) {
-    const dotIndex = column.indexOf(".");
-    const table = column.substring(0, dotIndex);
+    const dotIndex = column.lastIndexOf(".");
+    const relation = column.substring(0, dotIndex);
+    const table = ctx.aliases?.get(relation) ?? relation;
     const col = column.substring(dotIndex + 1);
     return columnRef(col, table, void 0, ctx.naming);
   }
@@ -2763,15 +2826,27 @@ function buildColumnRef(column, ctx) {
   return columnRef(column, alias, void 0, ctx.naming);
 }
 function buildParamRef(value, state) {
-  if (isParamRef(value)) {
-    state.parameters.push(value.value);
-    return createParamRef(value.paramIndex);
+  const boundValue = unwrapParamIntent(value);
+  if (isParamRef(boundValue)) {
+    state.parameters.push(boundValue.value);
+    return createParamRef(boundValue.paramIndex);
   }
   state.paramIndex++;
-  state.parameters.push(value);
+  state.parameters.push(boundValue);
   return createParamRef(state.paramIndex);
 }
-function compileValue(value, state, columnType) {
+function compileValue(value, state, columnType, forceParam = false) {
+  const boundValue = unwrapParamIntent(value);
+  if (isParamIntent3(value)) {
+    const idx2 = ++state.paramIndex;
+    state.parameters.push(boundValue);
+    return columnType ? createTypeCastParamRef(idx2, columnType) : createParamRef(idx2);
+  }
+  if (forceParam) {
+    const idx2 = ++state.paramIndex;
+    state.parameters.push(boundValue);
+    return columnType ? createTypeCastParamRef(idx2, columnType) : createParamRef(idx2);
+  }
   if (value === null || value === void 0) {
     return nullConstNode();
   }
@@ -2783,7 +2858,10 @@ function compileValue(value, state, columnType) {
   state.parameters.push(value);
   return columnType ? createTypeCastParamRef(idx, columnType) : createParamRef(idx);
 }
-function compileValueOrFieldRef(value, ctx, state, columnType) {
+function compileValueOrFieldRef(value, ctx, state, columnType, forceParam = false) {
+  if (forceParam || isParamIntent3(value)) {
+    return compileValue(value, state, columnType, true);
+  }
   if (isFieldRef(value)) {
     const alias = value.scope === "outer" ? ctx.outerAlias ?? ctx.rootTable : ctx.currentAlias ?? ctx.rootTable;
     return columnRef(value.column, alias, void 0, ctx.naming);
@@ -2803,9 +2881,11 @@ var init_utils = __esm({
   "src/handlers/where/utils.ts"() {
     "use strict";
     init_ast_helpers();
+    init_param_intent();
     init_param_ref();
     init_validate();
     init_types();
+    init_param_intent();
   }
 });
 
@@ -2835,6 +2915,7 @@ var init_any = __esm({
   "src/handlers/where/any.ts"() {
     "use strict";
     init_compiler_utils();
+    init_param_intent();
     init_param_ref();
     init_types();
     init_utils();
@@ -2845,7 +2926,8 @@ var init_any = __esm({
         if (!column) {
           throw new Error("ANY handler requires a column");
         }
-        const values = Array.isArray(decision.values) ? decision.values : [];
+        const rawValues = unwrapParamIntent(decision.values);
+        const values = Array.isArray(rawValues) ? rawValues : [];
         const columnNode = buildColumnRef(column, ctx);
         let pgBaseType;
         if (decision.dataType) {
@@ -2875,6 +2957,7 @@ var betweenHandler;
 var init_between = __esm({
   "src/handlers/where/between.ts"() {
     "use strict";
+    init_param_intent();
     init_param_ref();
     init_utils();
     betweenHandler = {
@@ -2884,16 +2967,18 @@ var init_between = __esm({
         if (!column) {
           throw new Error("BETWEEN handler requires a column");
         }
-        const range = decision.value;
+        const range = unwrapParamIntent(decision.value);
         if (!Array.isArray(range) || range.length !== 2) {
           throw new Error("BETWEEN condition requires [min, max] array");
         }
         const columnNode = buildColumnRef(column, ctx);
+        const minValue = unwrapParamIntent(range[0]);
+        const maxValue = unwrapParamIntent(range[1]);
         const minIdx = ++state.paramIndex;
-        state.parameters.push(range[0]);
+        state.parameters.push(minValue);
         const minNode = createParamRef(minIdx);
         const maxIdx = ++state.paramIndex;
-        state.parameters.push(range[1]);
+        state.parameters.push(maxValue);
         const maxNode = createParamRef(maxIdx);
         return {
           A_Expr: {
@@ -2969,6 +3054,7 @@ var init_custom_expression = __esm({
   "src/handlers/where/custom-expression.ts"() {
     "use strict";
     init_ast_helpers();
+    init_param_intent();
     init_param_ref();
     init_custom();
     OP_MAP = {
@@ -2994,7 +3080,7 @@ var init_custom_expression = __esm({
           return leftNode;
         }
         const idx = ++state.paramIndex;
-        state.parameters.push(decision.value);
+        state.parameters.push(unwrapParamIntent(decision.value));
         const rightNode = createParamRef(idx);
         const rawOp = decision.subqueryOperator ?? decision.operator ?? "=";
         const sqlOp = OP_MAP[rawOp];
@@ -3202,6 +3288,7 @@ var init_exists = __esm({
 });
 
 // src/handlers/where/in.ts
+import { isParamIntent as isParamIntent4 } from "@dbsp/types";
 function createInExpr(columnNode, state, values, columnType) {
   state.paramIndex++;
   state.parameters.push(values);
@@ -3228,11 +3315,22 @@ function createNotInExpr(columnNode, state, values, columnType) {
     }
   };
 }
+function isWholeArrayParamList(value) {
+  return value.length === 1 && isParamIntent4(value[0]) && Array.isArray(value[0].value);
+}
+function unwrapCompilerInListValues(value) {
+  const values = [];
+  for (const item of value) {
+    values.push(unwrapParamIntent(item));
+  }
+  return values;
+}
 var inHandler;
 var init_in = __esm({
   "src/handlers/where/in.ts"() {
     "use strict";
     init_ast_helpers();
+    init_param_intent();
     init_param_ref();
     init_types();
     init_utils();
@@ -3241,7 +3339,7 @@ var init_in = __esm({
       compile(decision, ctx, state) {
         const operator = decision.operator ?? "in";
         const column = decision.column;
-        const value = decision.value;
+        const value = unwrapParamIntent(decision.value);
         if (!column) {
           throw new Error("In handler requires a column");
         }
@@ -3251,7 +3349,7 @@ var init_in = __esm({
             `[in handler] Received a non-array value for operator '${operator}' on column '${column}'. This is a compiler bug: ${hint}. File a bug report.`
           );
         }
-        const values = value;
+        const values = isWholeArrayParamList(value) ? value[0].value : unwrapCompilerInListValues(value);
         if (values.length === 0) {
           if (operator === COLLECTION_OPERATORS.NOT_IN || operator === "notIn") {
             return booleanConstNode(true);
@@ -3494,6 +3592,7 @@ var RANGE_OP_MAP, rangeHandler;
 var init_range = __esm({
   "src/handlers/where/range.ts"() {
     "use strict";
+    init_param_intent();
     init_param_ref();
     init_types();
     init_utils();
@@ -3511,11 +3610,14 @@ var init_range = __esm({
         }
         const operator = decision.operator ?? "contains";
         const pgOp = RANGE_OP_MAP[operator] ?? operator;
-        const value = decision.value;
+        const rawValue = decision.value;
+        const value = unwrapParamIntent(rawValue);
         const columnNode = buildColumnRef(column, ctx);
         let paramValue;
         let isScalar = false;
-        if (isRangeValue(value)) {
+        if (value !== rawValue) {
+          paramValue = value;
+        } else if (isRangeValue(value)) {
           const lower = value.lower ?? "";
           const upper = value.upper ?? "";
           paramValue = `[${lower},${upper})`;
@@ -3699,7 +3801,7 @@ function handleExpressionIntent(intent, ctx, handlerCtx) {
     return leftNode;
   }
   const idx = ++ctx.paramState.paramIndex;
-  ctx.paramState.parameters.push(exprIntent.value);
+  ctx.paramState.parameters.push(unwrapParamIntent(exprIntent.value));
   const rightNode = createParamRef(idx);
   const sqlOp = OP_MAP2[exprIntent.operator] ?? "=";
   return binaryExpr(sqlOp, leftNode, rightNode);
@@ -3981,9 +4083,13 @@ function compileWhereIntent(intent, ctx) {
     if (exprRefResult !== null) return exprRefResult;
   }
   const needsColumn = intent.kind === "comparison" || intent.kind === "null";
+  const rawIntent = intent;
   const bridged = needsColumn ? {
     ...intent,
-    column: intent.field
+    column: rawIntent.field,
+    ..."value" in rawIntent && {
+      value: rawIntent.value
+    }
   } : intent;
   return dispatcher(bridged, handlerCtx, ctx.paramState);
 }
@@ -3999,6 +4105,7 @@ var init_compile_where = __esm({
     init_utils();
     init_intent_to_decisions();
     init_naming_plugin();
+    init_param_intent();
     init_param_ref();
     registerWhereDispatcherFactory(createWhereDispatcher);
     OP_MAP2 = {
@@ -4037,7 +4144,8 @@ var init_raw_exists = __esm({
           subIntent,
           state.paramIndex,
           ctx.naming,
-          ctx.schema
+          ctx.schema,
+          "rawExists"
         );
         if (innerParams) {
           for (const p of innerParams) {
@@ -4169,6 +4277,7 @@ var init_relation_filter = __esm({
 });
 
 // src/subquery-emission.ts
+import { isParamIntent as isParamIntent5 } from "@dbsp/types";
 function assertNoDroppedDecisionModifiers(decision, use) {
   const d = decision;
   const unsupported = [];
@@ -4287,6 +4396,12 @@ function buildPredicateSubquerySelect(use, sourceIntent, decision, ctx, state, d
   if (decision.limit != null) {
     if (typeof decision.limit === "number") {
       stmt.limitCount = integerNode(decision.limit);
+    } else if (isParamIntent5(decision.limit)) {
+      state.parameters.push(unwrapParamIntent(decision.limit));
+      state.paramIndex++;
+      stmt.limitCount = {
+        ParamRef: { number: state.paramIndex }
+      };
     } else {
       const limitObj = decision.limit;
       if (typeof limitObj.paramIndex !== "number") {
@@ -4304,6 +4419,7 @@ var init_subquery_emission = __esm({
     "use strict";
     init_ast_helpers();
     init_intent_to_decisions();
+    init_param_intent();
   }
 });
 
@@ -4714,12 +4830,13 @@ var init_join = __esm({
         const targets = [];
         const columns = decision.columns;
         const columnAliases = decision.columnAliases;
+        const hydrationPrefix = decision.hydrationPrefix ?? relation ?? targetAlias;
         if (columns && columns.length > 0) {
           if (columns.length === 1 && columns[0] === "*") {
             targets.push(starTarget(targetAlias, ctx.naming));
           } else {
             for (const col of columns) {
-              const outputAlias = columnAliases?.[col] ?? `${relation}.${col}`;
+              const outputAlias = columnAliases?.[col] ?? `${hydrationPrefix}.${col}`;
               targets.push(columnTarget(col, outputAlias, targetAlias, ctx.naming));
             }
           }
@@ -5048,6 +5165,7 @@ __export(handlers_exports, {
   genericWindowHandler: () => genericWindowHandler,
   getExpressionHandler: () => getExpressionHandler,
   getIncludeHandler: () => getIncludeHandler,
+  getNqlSafeExpressionHandler: () => getNqlSafeExpressionHandler,
   getRegisteredOperators: () => getRegisteredOperators,
   getRegistryStats: () => getRegistryStats,
   getWhereHandler: () => getWhereHandler,
@@ -5158,6 +5276,10 @@ function getExpressionHandler(type) {
   }
   return handler;
 }
+function getNqlSafeExpressionHandler(type) {
+  const handler = expressionHandlers.get(type);
+  return handler?.nqlSafe === true ? handler : void 0;
+}
 function getIncludeHandler(strategy) {
   const handler = includeHandlers.get(strategy);
   if (!handler) {
@@ -5179,7 +5301,7 @@ function ensureHandlersRegistered() {
   handlersInitialized = true;
   registerAllWhereHandlers();
 }
-function normalizeToDecision(input) {
+function normalizeToDecision(input, ctx) {
   if (input.column !== void 0) {
     const raw2 = input;
     if (raw2.jsonPath && raw2.jsonPath.length > 0) {
@@ -5202,7 +5324,7 @@ function normalizeToDecision(input) {
       type: op3,
       operator: op3,
       conditions: (raw.conditions ?? []).map(
-        (c) => normalizeToDecision(c)
+        (c) => normalizeToDecision(c, ctx)
       )
     };
   }
@@ -5214,7 +5336,7 @@ function normalizeToDecision(input) {
   switch (kind) {
     case "comparison": {
       if (raw.jsonPath) {
-        return {
+        const decision = {
           type: "where",
           column: raw.field,
           operator: "jsonComparison",
@@ -5222,6 +5344,7 @@ function normalizeToDecision(input) {
           jsonPath: raw.jsonPath,
           jsonMode: raw.jsonMode ?? "text"
         };
+        return decision;
       }
       return {
         type: "where",
@@ -5235,7 +5358,7 @@ function normalizeToDecision(input) {
         type: "and",
         operator: "and",
         conditions: (raw.conditions ?? []).map(
-          (c) => normalizeToDecision(c)
+          (c) => normalizeToDecision(c, ctx)
         )
       };
     case "or":
@@ -5243,14 +5366,14 @@ function normalizeToDecision(input) {
         type: "or",
         operator: "or",
         conditions: (raw.conditions ?? []).map(
-          (c) => normalizeToDecision(c)
+          (c) => normalizeToDecision(c, ctx)
         )
       };
     case "not":
       return {
         type: "not",
         operator: "not",
-        conditions: [normalizeToDecision(raw.condition)]
+        conditions: [normalizeToDecision(raw.condition, ctx)]
       };
     case "null":
       return {
@@ -5274,7 +5397,7 @@ function normalizeToDecision(input) {
         );
         const rawSelect = sub.select;
         const selectColumn = typeof rawSelect === "string" ? rawSelect : isSelectWithFields(rawSelect) ? rawSelect.fields?.[0] ?? "*" : "*";
-        const subConditions = sub.where ? [normalizeToDecision(sub.where)] : [];
+        const subConditions = sub.where ? [normalizeToDecision(sub.where, ctx)] : [];
         const rawLimit = sub.limit;
         const rawOrderBy = sub.orderBy;
         return {
@@ -5309,13 +5432,14 @@ function normalizeToDecision(input) {
         operator: raw.caseInsensitive ? "ilike" : "like",
         value: raw.pattern
       };
-    case "jsonContains":
+    case "jsonContains": {
       return {
         type: "where",
         column: raw.field,
         operator: raw.reversed ? "jsonContainedBy" : "jsonContains",
         value: raw.value
       };
+    }
     case "jsonExists":
       return {
         type: "where",
@@ -5326,7 +5450,7 @@ function normalizeToDecision(input) {
     case "exists":
     case "notExists": {
       const relation = raw.relation;
-      const conditions = raw.where ? [normalizeToDecision(raw.where)] : void 0;
+      const conditions = raw.where ? [normalizeToDecision(raw.where, ctx)] : void 0;
       const targetTable = raw.targetTable ?? relation;
       const sourceColumn = raw.sourceColumn;
       const targetColumn = raw.targetColumn;
@@ -5355,7 +5479,7 @@ function normalizeToDecision(input) {
 function createWhereDispatcher() {
   return (decision, ctx, state) => {
     ensureHandlersRegistered();
-    const normalized = normalizeToDecision(decision);
+    const normalized = normalizeToDecision(decision, ctx);
     const rawOperator = normalized.operator ?? "=";
     const operator = OPERATOR_ALIASES[rawOperator] ?? rawOperator;
     const handler = getWhereHandler(operator);
@@ -5508,16 +5632,18 @@ function resolveOperand(operand, ctx, state) {
     const alias = ctx.currentAlias ?? ctx.rootTable;
     return columnRef(operand, alias, void 0, ctx.naming);
   }
-  const idx = ++state.paramIndex;
-  state.parameters.push(operand);
-  return createParamRef(idx);
+  if (typeof operand === "object" && operand !== null && "kind" in operand && ctx.compileNqlSelectExpression) {
+    return ctx.compileNqlSelectExpression(operand, ctx, state);
+  }
+  return bindParameter(unwrapParamIntent(operand), state);
 }
 var arithmeticHandler;
 var init_arithmetic = __esm({
   "src/handlers/expression/arithmetic.ts"() {
     "use strict";
     init_ast_helpers();
-    init_param_ref();
+    init_param_intent();
+    init_param_value();
     arithmeticHandler = {
       types: ["arithmetic", "math", "calc"],
       compile(decision, ctx, state) {
@@ -5552,8 +5678,9 @@ var init_case = __esm({
   "src/handlers/expression/case.ts"() {
     "use strict";
     init_ast_helpers();
-    init_param_ref();
+    init_param_intent();
     init_case_value();
+    init_param_value();
     caseHandler = {
       types: ["case", "CASE", "caseWhen"],
       compile(decision, ctx, state) {
@@ -5599,13 +5726,12 @@ var init_case = __esm({
         const tableAlias = ctx.currentAlias ?? ctx.rootTable;
         const testExpr = columnRef(column, tableAlias, void 0, ctx.naming);
         const args = conditions.map((cond) => {
-          const whenParamNumber = ++state.paramIndex;
           const whenDecision = cond.when;
-          state.parameters.push(whenDecision.value ?? cond.when);
-          const whenExpr = createParamRef(whenParamNumber);
-          const thenParamNumber = ++state.paramIndex;
-          state.parameters.push(cond.then);
-          const thenResult = createParamRef(thenParamNumber);
+          const whenExpr = bindParameter(
+            unwrapParamIntent(whenDecision.value ?? cond.when),
+            state
+          );
+          const thenResult = bindParameter(unwrapParamIntent(cond.then), state);
           const caseWhen = {
             expr: whenExpr,
             result: thenResult
@@ -5614,9 +5740,7 @@ var init_case = __esm({
         });
         let defresult;
         if (elseValue !== void 0) {
-          const paramNumber = ++state.paramIndex;
-          state.parameters.push(elseValue);
-          defresult = createParamRef(paramNumber);
+          defresult = bindParameter(unwrapParamIntent(elseValue), state);
         }
         const caseExpr = {
           arg: testExpr,
@@ -5642,18 +5766,21 @@ function buildValueNode(value, ctx, state) {
       return columnRef(decision.column, tableAlias, void 0, ctx.naming);
     }
   }
-  const paramNumber = ++state.paramIndex;
-  state.parameters.push(value);
-  return createParamRef(paramNumber);
+  if (typeof value === "object" && value !== null && "kind" in value && ctx.compileNqlSelectExpression) {
+    return ctx.compileNqlSelectExpression(value, ctx, state);
+  }
+  return bindParameter(unwrapParamIntent(value), state);
 }
 var coalesceHandler, nullIfHandler, greatestHandler, leastHandler;
 var init_coalesce = __esm({
   "src/handlers/expression/coalesce.ts"() {
     "use strict";
     init_ast_helpers();
-    init_param_ref();
+    init_param_intent();
+    init_param_value();
     coalesceHandler = {
       types: ["coalesce", "COALESCE", "ifNull", "nvl"],
+      nqlSafe: true,
       compile(decision, ctx, state) {
         const args = decision.args;
         const column = decision.column;
@@ -5693,9 +5820,7 @@ var init_coalesce = __esm({
         }
         const tableAlias = ctx.currentAlias ?? ctx.rootTable;
         const colRef = columnRef(column, tableAlias, void 0, ctx.naming);
-        const paramNumber = ++state.paramIndex;
-        state.parameters.push(value);
-        const valueRef = createParamRef(paramNumber);
+        const valueRef = bindParameter(unwrapParamIntent(value), state);
         return {
           NullIfExpr: {
             args: [colRef, valueRef]
@@ -5793,11 +5918,30 @@ var init_column = __esm({
 });
 
 // src/handlers/expression/json.ts
+function normalizeJsonPathArgs(args) {
+  if (!args || args.length === 0) return [];
+  if (args.length === 1) {
+    const first = args[0];
+    const unwrappedFirst = unwrapParamIntent(first);
+    if (first !== unwrappedFirst) {
+      return unwrappedFirst;
+    }
+    if (Array.isArray(first)) {
+      return first.map(unwrapParamIntent);
+    }
+    if (typeof first === "string" && first.startsWith("{") && first.endsWith("}")) {
+      const inner = first.slice(1, -1);
+      return inner.length === 0 ? [] : inner.split(",");
+    }
+  }
+  return args.map(unwrapParamIntent);
+}
 var jsonExtractHandler, jsonPathExtractHandler;
 var init_json2 = __esm({
   "src/handlers/expression/json.ts"() {
     "use strict";
     init_ast_helpers();
+    init_param_intent();
     init_utils();
     jsonExtractHandler = {
       types: ["jsonExtract"],
@@ -5834,10 +5978,10 @@ var init_json2 = __esm({
           throw new Error("JSON path extract handler requires a column");
         }
         const mode = decision.jsonMode ?? "text";
-        const arrayLiteral = decision.args?.[0] ?? "{}";
+        const path = normalizeJsonPathArgs(decision.args);
         const alias = ctx.currentAlias ?? ctx.rootTable;
         const left = columnRef(column, alias, void 0, ctx.naming);
-        const right = compileValue(arrayLiteral, state);
+        const right = compileValue(path, state);
         const op3 = mode === "text" ? "#>>" : "#>";
         return {
           A_Expr: {
@@ -6432,6 +6576,8 @@ var rawHandler, sqlFunctionHandler, literalHandler;
 var init_raw = __esm({
   "src/handlers/expression/raw.ts"() {
     "use strict";
+    init_param_intent();
+    init_param_value();
     rawHandler = {
       types: ["raw", "RAW", "rawSql", "rawExpression"],
       compile(decision, ctx, _state) {
@@ -6466,17 +6612,9 @@ var init_raw = __esm({
         if (args && Array.isArray(args)) {
           for (const arg of args) {
             if (typeof arg === "object" && arg !== null && "type" in arg) {
-              const paramNumber = ++state.paramIndex;
-              state.parameters.push(arg);
-              argNodes.push({
-                ParamRef: { number: paramNumber }
-              });
+              argNodes.push(bindParameter(unwrapParamIntent(arg), state));
             } else {
-              const paramNumber = ++state.paramIndex;
-              state.parameters.push(arg);
-              argNodes.push({
-                ParamRef: { number: paramNumber }
-              });
+              argNodes.push(bindParameter(unwrapParamIntent(arg), state));
             }
           }
         }
@@ -6550,7 +6688,7 @@ var init_relation = __esm({
         if (relation.includes(".")) {
           const segments = relation.split(".");
           const leaf = segments[segments.length - 1];
-          alias = state.aliases.get(leaf) ?? state.aliases.get(relation) ?? leaf;
+          alias = state.aliases.get(relation) ?? state.aliases.get(leaf) ?? leaf;
         } else {
           alias = state.aliases.get(relation) ?? relation;
         }
@@ -6698,13 +6836,9 @@ function createLagLeadHandler(funcName, types) {
       const colRef = columnRef(column, tableAlias, void 0, ctx.naming);
       const args = [colRef];
       const offset = decision.args?.[0] ?? 1;
-      const offsetParamNumber = ++state.paramIndex;
-      state.parameters.push(offset);
-      args.push(createParamRef(offsetParamNumber));
+      args.push(bindParameter(unwrapParamIntent(offset), state));
       if (decision.value !== void 0) {
-        const defaultParamNumber = ++state.paramIndex;
-        state.parameters.push(decision.value);
-        args.push(createParamRef(defaultParamNumber));
+        args.push(bindParameter(unwrapParamIntent(decision.value), state));
       }
       return buildWindowFunction(funcName, args, decision, ctx);
     }
@@ -6730,7 +6864,8 @@ var init_window = __esm({
   "src/handlers/expression/window.ts"() {
     "use strict";
     init_ast_helpers();
-    init_param_ref();
+    init_param_intent();
+    init_param_value();
     WINDOW_FRAME_DEFAULT = 1034;
     rowNumberHandler = createNoArgWindowHandler("row_number", [
       "rowNumber",
@@ -6747,9 +6882,7 @@ var init_window = __esm({
       types: ["ntile", "NTILE"],
       compile(decision, ctx, state) {
         const n = decision.value ?? decision.args?.[0] ?? 4;
-        const paramNumber = ++state.paramIndex;
-        state.parameters.push(n);
-        const nRef = createParamRef(paramNumber);
+        const nRef = bindParameter(unwrapParamIntent(n), state);
         return buildWindowFunction("ntile", [nRef], decision, ctx);
       }
     };
@@ -6790,15 +6923,11 @@ var init_window = __esm({
         }
         if (decision.args && Array.isArray(decision.args)) {
           for (const arg of decision.args) {
-            const paramNumber = ++state.paramIndex;
-            state.parameters.push(arg);
-            args.push(createParamRef(paramNumber));
+            args.push(bindParameter(unwrapParamIntent(arg), state));
           }
         }
         if (decision.value !== void 0) {
-          const defaultParamNumber = ++state.paramIndex;
-          state.parameters.push(decision.value);
-          args.push(createParamRef(defaultParamNumber));
+          args.push(bindParameter(unwrapParamIntent(decision.value), state));
         }
         return buildWindowFunction(funcName, args, decision, ctx);
       }
@@ -6915,6 +7044,12 @@ init_ast_helpers();
 // src/compiler.ts
 init_assert_field();
 init_ast_helpers();
+import { InvalidOperationError as InvalidOperationError2 } from "@dbsp/core";
+import {
+  isParamIntent as isParamIntent6,
+  NQL_SELECT_SCALAR_FUNCTION_ALLOWLIST,
+  NQL_SELECT_WINDOW_FUNCTION_ALLOWLIST
+} from "@dbsp/types";
 
 // src/pgsql-deparser.ts
 function deparse(node) {
@@ -7972,6 +8107,7 @@ function deparseQuoted(ast) {
 init_case_value();
 init_custom();
 init_expression();
+init_param_value();
 init_window();
 init_include();
 init_shared();
@@ -7980,9 +8116,39 @@ init_types();
 init_utils();
 init_intent_to_decisions();
 init_naming_plugin();
+init_param_intent();
 init_param_ref();
 init_subquery_emission();
+init_validate();
 registerWhereDispatcherFactory(createWhereDispatcher);
+var UnhandledNqlSelectExpressionKindError = class extends Error {
+  constructor(kind) {
+    super(`Unhandled NQL SELECT expression intent kind: ${kind}`);
+    this.kind = kind;
+    this.name = "UnhandledNqlSelectExpressionKindError";
+  }
+  kind;
+  code = "ERR_ADAPTER_UNHANDLED_NQL_SELECT_EXPRESSION_KIND";
+};
+var UnsupportedNqlSelectFunctionError = class extends Error {
+  constructor(functionName) {
+    super(`Unsupported function in SELECT context: ${functionName}()`);
+    this.functionName = functionName;
+    this.name = "UnsupportedNqlSelectFunctionError";
+  }
+  functionName;
+  code = "ERR_ADAPTER_UNSUPPORTED_NQL_SELECT_FUNCTION";
+};
+function assertNqlSelectScalarFunctionAllowed(functionName) {
+  if (!NQL_SELECT_SCALAR_FUNCTION_ALLOWLIST.has(functionName.toLowerCase())) {
+    throw new UnsupportedNqlSelectFunctionError(functionName);
+  }
+}
+function assertNqlSelectWindowFunctionAllowed(functionName) {
+  if (!NQL_SELECT_WINDOW_FUNCTION_ALLOWLIST.has(functionName.toLowerCase())) {
+    throw new UnsupportedNqlSelectFunctionError(functionName);
+  }
+}
 function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
   return {
     type: pd.type,
@@ -8006,6 +8172,8 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     strategy: pd.choice === "subquery" ? "json_agg" : pd.choice,
     relation: pd.relation ?? pd.relationName,
     relationName: pd.relationName,
+    relationPath: pd.relationPath,
+    hydrationPrefix: pd.hydrationPrefix,
     relationType: pd.relationType,
     foreignKey: pd.foreignKey,
     parentKey: pd.parentKey,
@@ -8058,6 +8226,77 @@ function isPrecompiledJoinDecision(d) {
 function isBatchValuesJoinDecision(d) {
   return isPrecompiledJoinDecision(d) && d.batchValuesParams !== void 0;
 }
+function getRelationIdentityPath(decision, rootTable) {
+  if (decision.relationPath) return decision.relationPath;
+  const relationName = decision.relationName ?? decision.relation;
+  if (!relationName && !decision.targetTable) return void 0;
+  const source = decision.sourceTable ?? rootTable;
+  const target = decision.targetTable ?? "";
+  const sourceColumn = decision.sourceColumn ?? decision.foreignKey ?? "";
+  return `__legacy__:${source}:${relationName ?? target}:${sourceColumn}:${target}`;
+}
+function getParentRelationPath(relationPath) {
+  if (!relationPath || relationPath.startsWith("__legacy__:")) return void 0;
+  const lastDot = relationPath.lastIndexOf(".");
+  return lastDot > 0 ? relationPath.slice(0, lastDot) : void 0;
+}
+function mergeColumnLists(current, next) {
+  if (!current) return next ? [...next] : void 0;
+  if (!next) return current;
+  if (current.includes("*") || next.includes("*")) return ["*"];
+  const merged = [...current];
+  for (const column of next) {
+    if (!merged.includes(column)) merged.push(column);
+  }
+  return merged;
+}
+function mergeDuplicateJoinIncludeDecisions(decisions, rootTable) {
+  const merged = [];
+  const seenByPath = /* @__PURE__ */ new Map();
+  for (const decision of decisions) {
+    const identityPath = decision.type === "includeStrategy" && decision.choice === "join" ? getRelationIdentityPath(decision, rootTable) : void 0;
+    if (!identityPath) {
+      merged.push(decision);
+      continue;
+    }
+    const existing = seenByPath.get(identityPath);
+    if (!existing) {
+      const copy = {
+        ...decision,
+        ...decision.columns ? { columns: [...decision.columns] } : {},
+        ...decision.columnAliases ? { columnAliases: { ...decision.columnAliases } } : {},
+        ...decision.conditions ? { conditions: [...decision.conditions] } : {}
+      };
+      seenByPath.set(identityPath, copy);
+      merged.push(copy);
+      continue;
+    }
+    const existingJoinType = existing.joinType ?? "left";
+    const nextJoinType = decision.joinType ?? "left";
+    if (existingJoinType !== nextJoinType) {
+      throw new InvalidOperationError2(
+        "include",
+        `Conflicting join options for relation path '${identityPath}'. Already registered as ${existingJoinType}, got ${nextJoinType}.`
+      );
+    }
+    const mutable = existing;
+    const columns = mergeColumnLists(existing.columns, decision.columns);
+    if (columns) mutable.columns = columns;
+    if (decision.columnAliases) {
+      mutable.columnAliases = {
+        ...decision.columnAliases,
+        ...existing.columnAliases ?? {}
+      };
+    }
+    if (decision.conditions && decision.conditions.length > 0) {
+      mutable.conditions = [
+        ...existing.conditions ?? [],
+        ...decision.conditions
+      ];
+    }
+  }
+  return merged;
+}
 function renumberParamRefsInAst(node, offset) {
   if (offset === 0) return node;
   return renumberNode(node, offset);
@@ -8114,13 +8353,14 @@ var PlanCompiler = class _PlanCompiler {
   /** CTE nodes from include handlers (e.g., CTE strategy) */
   pendingCtes = [];
   /**
-   * Maps joined targetTable → alias for multi-hop FK resolution.
-   * Populated as join decisions are compiled so later hops can find
-   * the correct source alias (e.g., 'symbols' → 'callee').
+   * Maps relation-dotted include path → JOIN alias for multi-hop FK resolution.
+   * Populated as join decisions are compiled so later hops can find the
+   * correct source alias (e.g., 'callee.file' reads parent path 'callee').
    */
   joinAliasMap = /* @__PURE__ */ new Map();
   /**
    * Tracks all join aliases in use for the current query.
+   * Entries are stored in emitted database-alias space, after naming.toDatabase().
    * Ensures no two JOINs share the same alias (DOUBLE-ALIAS prevention).
    */
   usedJoinAliases = /* @__PURE__ */ new Set();
@@ -8136,6 +8376,7 @@ var PlanCompiler = class _PlanCompiler {
     return {
       naming: this.naming,
       rootTable: this.currentRootTable,
+      aliases: this.resolvedJoinAliases(),
       maxRecursiveDepth: 100,
       defaultPkColumnName: this.defaultPk,
       deriveFkColumnName: this.deriveFk,
@@ -8143,6 +8384,31 @@ var PlanCompiler = class _PlanCompiler {
       ...this.model != null && { model: this.model }
     };
   }
+  findAliasForLegacySourceTable(sourceTable) {
+    let alias;
+    for (const entry of this.joinAliasMap.values()) {
+      if (entry.targetTable === sourceTable) alias = entry.alias;
+    }
+    return alias;
+  }
+  emittedJoinAlias(alias) {
+    const dbAlias = this.naming.toDatabase(alias);
+    validateIdentifier(dbAlias, "alias");
+    return dbAlias;
+  }
+  resolvedJoinAliases() {
+    const aliases = /* @__PURE__ */ new Map();
+    for (const [relationPath, entry] of this.joinAliasMap) {
+      const isLegacyPath = relationPath.startsWith("__legacy__:");
+      if (!isLegacyPath) {
+        aliases.set(relationPath, entry.alias);
+      }
+      if (entry.relationName && (isLegacyPath || relationPath === entry.relationName)) {
+        aliases.set(entry.relationName, entry.alias);
+      }
+    }
+    return aliases;
+  }
   /**
    * Dispatch a PlanDecision through the unified WHERE handler system.
    * Bridges PlanCompiler's state to handler types, calls dispatcher, syncs back.
@@ -8293,7 +8559,21 @@ var PlanCompiler = class _PlanCompiler {
       const combined = condNodes.length === 1 ? condNodes[0] : andExpr(...condNodes);
       handlerDecision._compiledFilterWhere = combined;
     }
-    const sourceAlias = decision.sourceTable && decision.sourceTable !== plan.rootTable ? this.joinAliasMap.get(decision.sourceTable) ?? decision.sourceTable : plan.rootTable;
+    const relationIdentityPath = decision.choice === "join" ? getRelationIdentityPath(decision, plan.rootTable) : void 0;
+    const requestedJoinType = decision.joinType ?? "left";
+    const existingJoin = relationIdentityPath ? this.joinAliasMap.get(relationIdentityPath) : void 0;
+    if (existingJoin) {
+      if (existingJoin.joinType !== requestedJoinType) {
+        throw new InvalidOperationError2(
+          "include",
+          `Conflicting join options for relation path '${relationIdentityPath}'. Already registered as ${existingJoin.joinType}, got ${requestedJoinType}.`
+        );
+      }
+      return {};
+    }
+    const parentRelationPath = getParentRelationPath(relationIdentityPath);
+    const parentAlias = parentRelationPath ? this.joinAliasMap.get(parentRelationPath)?.alias : void 0;
+    const sourceAlias = parentAlias ?? (decision.sourceTable && decision.sourceTable !== plan.rootTable ? this.findAliasForLegacySourceTable(decision.sourceTable) ?? decision.sourceTable : plan.rootTable);
     const ctx = {
       ...this.handlerCtx(),
       currentAlias: sourceAlias
@@ -8310,11 +8590,13 @@ var PlanCompiler = class _PlanCompiler {
       const candidateAlias = handlerDecision.relation ?? handlerDecision.targetTable ?? handlerDecision.relationName;
       if (candidateAlias) {
         let alias = candidateAlias;
+        let emittedAlias = this.emittedJoinAlias(alias);
         let counter = 1;
-        while (this.usedJoinAliases.has(alias)) {
+        while (this.usedJoinAliases.has(emittedAlias)) {
           alias = `${candidateAlias}_${counter++}`;
+          emittedAlias = this.emittedJoinAlias(alias);
         }
-        this.usedJoinAliases.add(alias);
+        this.usedJoinAliases.add(emittedAlias);
         finalJoinAlias = alias;
         if (alias !== candidateAlias) {
           handlerDecision.relation = alias;
@@ -8323,11 +8605,15 @@ var PlanCompiler = class _PlanCompiler {
     }
     const result = handler.compile(handlerDecision, ctx, handlerState);
     this.state.paramIndex = handlerState.paramIndex;
-    if (decision.choice === "join" && decision.targetTable && (finalJoinAlias ?? decision.relationName)) {
-      this.joinAliasMap.set(
-        decision.targetTable,
-        finalJoinAlias ?? decision.relationName
-      );
+    if (decision.choice === "join" && relationIdentityPath && finalJoinAlias) {
+      this.joinAliasMap.set(relationIdentityPath, {
+        alias: finalJoinAlias,
+        joinType: requestedJoinType,
+        ...decision.targetTable && { targetTable: decision.targetTable },
+        ...(decision.relationName ?? decision.relation) && {
+          relationName: decision.relationName ?? decision.relation
+        }
+      });
     }
     const out = {};
     if (result.targets) out.targets = result.targets;
@@ -8353,6 +8639,7 @@ var PlanCompiler = class _PlanCompiler {
     this.rawJoins = [];
     this.pendingCtes = [];
     this.joinAliasMap = /* @__PURE__ */ new Map();
+    this.usedJoinAliases = /* @__PURE__ */ new Set();
     const queryType = this.detectQueryType(plan.decisions);
     let ast;
     switch (queryType) {
@@ -8398,11 +8685,14 @@ var PlanCompiler = class _PlanCompiler {
       naming: this.naming,
       rootTable: plan.rootTable,
       currentAlias: currentAlias ?? plan.rootTable,
+      aliases: this.resolvedJoinAliases(),
       maxRecursiveDepth: 100,
       defaultPkColumnName: this.defaultPk,
       deriveFkColumnName: this.deriveFk,
       ...plan.schema ?? this.schema ? { schema: plan.schema ?? this.schema } : {},
-      ...this.model != null && { model: this.model }
+      ...this.model != null && { model: this.model },
+      compileSubquery: (query, paramOffset) => this.compileExpressionSubquery(query, paramOffset),
+      compileNqlSelectExpression: (value, handlerCtx, state) => this.compileNqlFunctionArg(value, handlerCtx, state)
     };
   }
   /** Build a fresh HandlerCompilerState sharing the current parameter array. */
@@ -8411,10 +8701,251 @@ var PlanCompiler = class _PlanCompiler {
       parameters: this.state.parameters,
       paramIndex: this.state.paramIndex,
       ctes: /* @__PURE__ */ new Map(),
-      aliases: /* @__PURE__ */ new Map(),
+      aliases: this.resolvedJoinAliases(),
       joins: []
     };
   }
+  compileExpressionSubquery(query, paramOffset) {
+    const innerCompiler = new _PlanCompiler({
+      naming: this.naming,
+      ...this.schema !== void 0 && {
+        schema: this.schema
+      },
+      defaultPkColumnName: this.defaultPk,
+      deriveFkColumnName: this.deriveFk
+    });
+    const innerPlan = {
+      rootTable: query.from,
+      decisions: intentToDecisions(query, query.from)
+    };
+    const innerResult = innerCompiler.compile(innerPlan);
+    const renumbered = renumberParamRefsInAst(innerResult.ast, paramOffset);
+    return { ast: renumbered, parameters: innerResult.parameters };
+  }
+  compileGenericNqlFunction(functionName, args, ctx, state) {
+    assertNqlSelectScalarFunctionAllowed(functionName);
+    validateIdentifier(functionName, "function");
+    const argNodes = args.map(
+      (arg) => this.compileNqlFunctionArg(arg, ctx, state)
+    );
+    return funcCall(functionName, argNodes);
+  }
+  compileNqlFunctionArg(arg, ctx, state) {
+    if (typeof arg === "string") {
+      return buildColumnRef(arg, ctx);
+    }
+    if (typeof arg === "object" && arg !== null) {
+      const record = arg;
+      if (typeof record.$ref === "string") {
+        return buildColumnRef(record.$ref, ctx);
+      }
+      if (typeof record.kind !== "string") {
+        const legacyKind = typeof record.$op === "string" ? `$op:${record.$op}` : typeof record.$fn === "string" ? `$fn:${record.$fn}` : "object";
+        throw new UnhandledNqlSelectExpressionKindError(legacyKind);
+      }
+      switch (record.kind) {
+        case "column":
+          if (typeof record.column !== "string") {
+            throw new Error("NQL column expression requires a column name");
+          }
+          return buildColumnRef(record.column, ctx);
+        case "columnAlias":
+          if (typeof record.column !== "string") {
+            throw new Error(
+              "NQL columnAlias expression requires a column name"
+            );
+          }
+          return buildColumnRef(record.column, ctx);
+        case "relationColumn": {
+          const relation = record.relation;
+          const column = record.column;
+          if (typeof relation !== "string" || typeof column !== "string") {
+            throw new Error(
+              "NQL relationColumn expression requires relation and column"
+            );
+          }
+          return buildColumnRef(`${relation}.${column}`, ctx);
+        }
+        case "param":
+          if (!("value" in record)) {
+            throw new Error("NQL param expression requires a value");
+          }
+          return bindParameter(record.value, state);
+        case "literal":
+          if (!("value" in record)) {
+            throw new Error("NQL literal expression requires a value");
+          }
+          return compileValue(record.value, state);
+        case "function": {
+          const nestedName = record.name;
+          const nestedArgs = record.args;
+          if (typeof nestedName !== "string") {
+            throw new Error("NQL function argument requires a function name");
+          }
+          return this.compileGenericNqlFunction(
+            nestedName,
+            Array.isArray(nestedArgs) ? nestedArgs : [],
+            ctx,
+            state
+          );
+        }
+        case "coalesce": {
+          const handler = getExpressionHandler("coalesce");
+          return handler.compile(
+            {
+              type: "coalesce",
+              args: Array.isArray(record.fields) ? record.fields : []
+            },
+            ctx,
+            state
+          );
+        }
+        case "aggregate": {
+          const fn4 = record.function;
+          if (typeof fn4 !== "string") {
+            throw new Error(
+              "NQL aggregate expression requires a function name"
+            );
+          }
+          const aggregateArgs = [];
+          if (record.field === "*") {
+            aggregateArgs.push({ kind: "star" });
+          } else if (typeof record.field === "string") {
+            aggregateArgs.push(record.field);
+          }
+          if (Array.isArray(record.extraArgs)) {
+            aggregateArgs.push(...record.extraArgs);
+          }
+          return this.compileGenericNqlFunction(fn4, aggregateArgs, ctx, state);
+        }
+        case "arithmetic": {
+          const operator = record.operator;
+          if (typeof operator !== "string") {
+            throw new Error("NQL arithmetic expression requires an operator");
+          }
+          if (!("left" in record) || !("right" in record)) {
+            throw new Error(
+              "NQL arithmetic expression requires left and right operands"
+            );
+          }
+          const handler = getExpressionHandler("arithmetic");
+          return handler.compile(
+            {
+              type: "arithmetic",
+              operator,
+              args: [record.left, record.right]
+            },
+            ctx,
+            state
+          );
+        }
+        case "case":
+          return this.compileNqlCaseExpressionArg(record, ctx, state);
+        case "jsonExtract": {
+          const handler = getExpressionHandler("jsonExtract");
+          return handler.compile(
+            {
+              type: "jsonExtract",
+              column: record.field,
+              args: Array.isArray(record.path) ? record.path : [],
+              jsonMode: record.mode
+            },
+            ctx,
+            state
+          );
+        }
+        case "jsonPathExtract": {
+          const handler = getExpressionHandler("jsonPathExtract");
+          return handler.compile(
+            {
+              type: "jsonPathExtract",
+              column: record.field,
+              args: Array.isArray(record.path) ? [record.path] : typeof record.path === "string" ? [record.path] : [],
+              jsonMode: record.mode
+            },
+            ctx,
+            state
+          );
+        }
+        case "window":
+          return genericWindowHandler.compile(
+            {
+              type: "window",
+              function: record.function,
+              column: record.field,
+              args: typeof record.offset === "number" ? [record.offset] : void 0,
+              value: record.defaultValue,
+              partition: record.over?.partitionBy,
+              orderBy: record.over?.orderBy?.map((item) => ({
+                column: item.field,
+                direction: item.direction?.toUpperCase()
+              }))
+            },
+            ctx,
+            state
+          );
+        case "customOp":
+        case "customFn":
+        case "ref":
+        case "cast":
+        case "unary":
+        case "namedArg":
+        case "star":
+        case "array":
+        case "subquery":
+          return compileExpressionIntent(
+            record,
+            ctx,
+            state
+          );
+        default:
+          throw new UnhandledNqlSelectExpressionKindError(record.kind);
+      }
+    }
+    return compileValue(arg, state);
+  }
+  compileNqlCaseExpressionArg(expr, ctx, state) {
+    const whenClauses = expr.when;
+    if (!Array.isArray(whenClauses) || whenClauses.length === 0) {
+      throw new Error("NQL CASE expression requires at least one WHEN clause");
+    }
+    const dispatcher = createWhereDispatcher();
+    const args = whenClauses.map((branch) => {
+      const condition = branch.condition;
+      const result = branch.result;
+      const conditionDecision = convertWhereCondition(
+        condition,
+        ctx.rootTable
+      );
+      if (!conditionDecision) {
+        throw new Error("NQL CASE WHEN condition could not be compiled");
+      }
+      const whenNode = dispatcher(
+        mapToHandlerDecision(
+          conditionDecision,
+          ctx.rootTable,
+          this.defaultPk,
+          this.deriveFk
+        ),
+        ctx,
+        state
+      );
+      const thenNode = this.compileNqlFunctionArg(result, ctx, state);
+      return {
+        CaseWhen: {
+          expr: whenNode,
+          result: thenNode
+        }
+      };
+    });
+    const defresult = expr.else !== void 0 ? this.compileNqlFunctionArg(expr.else, ctx, state) : void 0;
+    return {
+      CaseExpr: {
+        args,
+        ...defresult !== void 0 ? { defresult } : {}
+      }
+    };
+  }
   /**
    * Compile a SELECT-list target via expression handler.
    * Wraps the node in a ResTarget and pushes it onto targetList.
@@ -8468,6 +8999,41 @@ var PlanCompiler = class _PlanCompiler {
         });
         break;
       }
+      case "selectNqlFunction": {
+        ensureExpressionHandlersRegistered();
+        const funcType = decision.function;
+        if (!funcType) break;
+        assertNqlSelectScalarFunctionAllowed(funcType);
+        const ctx = this.createHandlerContext(
+          plan,
+          decision.table ?? plan.rootTable
+        );
+        const state = this.createHandlerState();
+        const safeHandler = getNqlSafeExpressionHandler(funcType);
+        const node = safeHandler ? safeHandler.compile(
+          mapToHandlerDecision(
+            decision,
+            plan.rootTable,
+            this.defaultPk,
+            this.deriveFk
+          ),
+          ctx,
+          state
+        ) : this.compileGenericNqlFunction(
+          funcType,
+          decision.args ?? [],
+          ctx,
+          state
+        );
+        this.state.paramIndex = state.paramIndex;
+        targetList.push({
+          ResTarget: {
+            val: node,
+            ...decision.alias ? { name: this.naming.toDatabase(decision.alias) } : {}
+          }
+        });
+        break;
+      }
       case "selectExpression": {
         if (decision.expressionType === "case") {
           const caseNode = this.compileCaseExpression(decision);
@@ -8564,6 +9130,7 @@ var PlanCompiler = class _PlanCompiler {
       case "selectWindow": {
         const winFuncName = decision.function;
         if (!winFuncName) break;
+        assertNqlSelectWindowFunctionAllowed(winFuncName);
         const winHandler = genericWindowHandler;
         const ctx = this.createHandlerContext(
           plan,
@@ -8592,11 +9159,7 @@ var PlanCompiler = class _PlanCompiler {
    * Compile an includeStrategy decision and register its results.
    * Pushes targets onto targetList, raw joins / CTEs onto instance collections.
    */
-  compileIncludeDecision(decision, plan, targetList) {
-    const includeResult = this.compileIncludeViaHandler(decision, plan);
-    if (includeResult.targets) {
-      targetList.push(...includeResult.targets);
-    }
+  registerIncludeCompilationResult(includeResult) {
     if (includeResult.rawJoin) {
       this.rawJoins.push(includeResult.rawJoin);
     }
@@ -8607,6 +9170,27 @@ var PlanCompiler = class _PlanCompiler {
       this.pendingCtes.push(includeResult.cte);
     }
   }
+  compileIncludeDecision(decision, plan, targetList, precompiled) {
+    const includeResult = precompiled ?? this.compileIncludeViaHandler(decision, plan);
+    if (includeResult.targets) {
+      targetList.push(...includeResult.targets);
+    }
+    if (!precompiled) {
+      this.registerIncludeCompilationResult(includeResult);
+    }
+  }
+  compileJoinIncludeAllocationPass(decisions, plan) {
+    const includeResults = /* @__PURE__ */ new Map();
+    for (const decision of decisions) {
+      if (decision.type !== "includeStrategy" || decision.choice !== "join") {
+        continue;
+      }
+      const includeResult = this.compileIncludeViaHandler(decision, plan);
+      includeResults.set(decision, includeResult);
+      this.registerIncludeCompilationResult(includeResult);
+    }
+    return includeResults;
+  }
   /**
    * Fold a WHERE-family decision into an existing where expression.
    * Returns the updated (or new) where node.
@@ -8726,7 +9310,11 @@ var PlanCompiler = class _PlanCompiler {
     if (decision.choice !== "join" || !decision.conditions || decision.conditions.length === 0) {
       return where;
     }
-    const joinAlias = decision.relationName;
+    const relationIdentityPath = getRelationIdentityPath(
+      decision,
+      this.currentRootTable
+    );
+    const joinAlias = (relationIdentityPath ? this.joinAliasMap.get(relationIdentityPath)?.alias : void 0) ?? decision.relationName;
     for (const cond of decision.conditions) {
       const condExpr = this.dispatchWhere(
         cond,
@@ -8736,6 +9324,14 @@ var PlanCompiler = class _PlanCompiler {
     }
     return where;
   }
+  reserveManualJoinAliases(decisions) {
+    for (const decision of decisions) {
+      if (decision.type !== "join") continue;
+      const alias = decision.alias ?? decision.targetTable;
+      if (!alias) continue;
+      this.usedJoinAliases.add(this.emittedJoinAlias(alias));
+    }
+  }
   /**
    * Apply a single join decision to the FROM clause in-place.
    * Chains multiple joins by wrapping from[0] as the left-arg each time.
@@ -8800,14 +9396,11 @@ var PlanCompiler = class _PlanCompiler {
    */
   compileGroupByDecision(decision) {
     const gbCol = decision.column;
-    const gbDot = gbCol.indexOf(".");
+    const gbDot = gbCol.lastIndexOf(".");
     if (gbDot !== -1) {
-      return columnRef(
-        gbCol.slice(gbDot + 1),
-        gbCol.slice(0, gbDot),
-        void 0,
-        this.naming
-      );
+      const relation = gbCol.slice(0, gbDot);
+      const alias = this.resolvedJoinAliases().get(relation) ?? relation;
+      return columnRef(gbCol.slice(gbDot + 1), alias, void 0, this.naming);
     }
     return columnRef(gbCol, decision.table, void 0, this.naming);
   }
@@ -8853,19 +9446,31 @@ var PlanCompiler = class _PlanCompiler {
     return selectStmt(options);
   }
   compileSelect(plan) {
+    const decisions = mergeDuplicateJoinIncludeDecisions(
+      plan.decisions,
+      plan.rootTable
+    );
+    this.reserveManualJoinAliases(decisions);
+    const includeJoinResults = this.compileJoinIncludeAllocationPass(
+      decisions,
+      plan
+    );
+    this.state.aliases = this.resolvedJoinAliases();
     const targetList = [];
     const from = this.compileFromClause(plan);
     let where;
     const orderBy = [];
+    const orderByDecisions = [];
     const groupBy = [];
     let having;
     let limit;
     let offset;
     let distinct = false;
-    for (const decision of plan.decisions) {
+    for (const decision of decisions) {
       switch (decision.type) {
         case "select":
         case "selectFunction":
+        case "selectNqlFunction":
         case "selectExpression":
         case "selectRelationColumn":
         case "selectPseudoColumn":
@@ -8875,7 +9480,12 @@ var PlanCompiler = class _PlanCompiler {
           this.compileSelectTarget(decision, plan, targetList);
           break;
         case "includeStrategy":
-          this.compileIncludeDecision(decision, plan, targetList);
+          this.compileIncludeDecision(
+            decision,
+            plan,
+            targetList,
+            includeJoinResults.get(decision)
+          );
           where = this.compileIncludeWhereConditions(decision, where);
           break;
         case "where":
@@ -8888,8 +9498,7 @@ var PlanCompiler = class _PlanCompiler {
           this.compileJoinDecision(decision, plan, from);
           break;
         case "orderBy": {
-          const obNode = this.compileOrderByDecision(decision, plan);
-          if (obNode) orderBy.push(obNode);
+          orderByDecisions.push(decision);
           break;
         }
         case "groupBy":
@@ -8903,6 +9512,10 @@ var PlanCompiler = class _PlanCompiler {
         case "limit":
           if (typeof decision.limit === "number") {
             limit = integerNode(decision.limit);
+          } else if (isParamIntent6(decision.limit)) {
+            this.state.parameters.push(unwrapParamIntent(decision.limit));
+            this.state.paramIndex++;
+            limit = createParamRef(this.state.paramIndex);
           } else if (decision.limit?.paramIndex !== void 0) {
             limit = createParamRef(decision.limit.paramIndex);
             this.state.parameters.push(void 0);
@@ -8911,6 +9524,10 @@ var PlanCompiler = class _PlanCompiler {
         case "offset":
           if (typeof decision.offset === "number") {
             offset = integerNode(decision.offset);
+          } else if (isParamIntent6(decision.offset)) {
+            this.state.parameters.push(unwrapParamIntent(decision.offset));
+            this.state.paramIndex++;
+            offset = createParamRef(this.state.paramIndex);
           } else if (decision.offset?.paramIndex !== void 0) {
             offset = createParamRef(decision.offset.paramIndex);
             this.state.parameters.push(void 0);
@@ -8928,6 +9545,10 @@ var PlanCompiler = class _PlanCompiler {
           break;
       }
     }
+    for (const decision of orderByDecisions) {
+      const obNode = this.compileOrderByDecision(decision, plan);
+      if (obNode) orderBy.push(obNode);
+    }
     this.flushPendingJoins(from, plan);
     return this.buildSelectStmt(
       targetList,
@@ -12520,8 +13141,10 @@ function matchGlob(pattern, value) {
 init_ast_helpers();
 init_compiler_utils();
 init_handlers();
+init_param_intent();
 init_param_ref();
 import { isSqlRaw } from "@dbsp/core";
+import { isParamIntent as isParamIntent7 } from "@dbsp/types";
 function buildReturningList(columns, tableRef, ctx) {
   if (!columns || columns.length === 0) return void 0;
   const { naming } = ctx;
@@ -12779,7 +13402,7 @@ function compileInsertFrom(config, ctx, state) {
   }
   let limitCount;
   if (config.limit !== void 0) {
-    limitCount = { A_Const: { ival: { ival: config.limit } } };
+    limitCount = limitToNode(config.limit, state);
   }
   const sourceRelation = {
     relname: dbSourceTable,
@@ -12854,7 +13477,7 @@ function compileUpsertFrom(config, ctx, state) {
   }
   let limitCount;
   if (config.limit !== void 0) {
-    limitCount = { A_Const: { ival: { ival: config.limit } } };
+    limitCount = limitToNode(config.limit, state);
   }
   const sourceRelation = {
     relname: dbSourceTable,
@@ -12928,11 +13551,22 @@ var RANGE_TYPES = /* @__PURE__ */ new Set([
   "int8range",
   "numrange"
 ]);
-function valueToNode(value, state, dbType) {
-  if (value === null || value === void 0) {
+function valueToNode(value, state, dbType, forceParam = false) {
+  const isParam = isParamIntent7(value);
+  const boundValue = unwrapParamIntent(value);
+  if (boundValue === null || boundValue === void 0) {
+    if (forceParam || isParam) {
+      state.parameters.push(boundValue);
+      state.paramIndex++;
+      return dbType && RANGE_TYPES.has(dbType) ? createTypeCastParamRef(state.paramIndex, dbType) : {
+        ParamRef: {
+          number: state.paramIndex
+        }
+      };
+    }
     return { A_Const: { isnull: true } };
   }
-  state.parameters.push(value);
+  state.parameters.push(boundValue);
   state.paramIndex++;
   if (dbType && RANGE_TYPES.has(dbType)) {
     return createTypeCastParamRef(state.paramIndex, dbType);
@@ -12943,6 +13577,18 @@ function valueToNode(value, state, dbType) {
     }
   };
 }
+function limitToNode(limit, state) {
+  if (isParamIntent7(limit)) {
+    state.parameters.push(unwrapParamIntent(limit));
+    state.paramIndex++;
+    return {
+      ParamRef: {
+        number: state.paramIndex
+      }
+    };
+  }
+  return { A_Const: { ival: { ival: limit } } };
+}
 function compileMutation(decision, ctx, state) {
   const type = decision.type;
   const table = decision.table ?? ctx.rootTable;
@@ -12982,6 +13628,7 @@ function compileMutation(decision, ctx, state) {
 init_ast_helpers();
 init_compiler_utils();
 init_handlers();
+init_param_intent();
 init_param_ref();
 function buildOnConflictClause(config, ctx, state) {
   const naming = ctx.naming;
@@ -13141,7 +13788,7 @@ function compileUnnestUpsert(config, ctx, state) {
 }
 function valueToParam(state, value) {
   if (value !== void 0) {
-    state.parameters.push(value);
+    state.parameters.push(unwrapParamIntent(value));
   }
   state.paramIndex++;
   return {
@@ -13382,7 +14029,7 @@ function compileSubqueryIncludeManyToMany(info, parentIds, schemaName, state, de
 // src/adapter-compiler-mutations.ts
 init_compile_where();
 init_compiler_utils();
-import { InvalidOperationError as InvalidOperationError2, isSqlRaw as isSqlRaw2 } from "@dbsp/core";
+import { InvalidOperationError as InvalidOperationError3, isSqlRaw as isSqlRaw2 } from "@dbsp/core";
 init_handlers();
 function whereIntentAsDecision(where) {
   return where;
@@ -13460,9 +14107,8 @@ function compileInsert2(intent, options, deps) {
   const state = createCompilerState();
   const firstRow = intent.values?.[0] ?? {};
   const columns = Object.keys(firstRow);
-  const values = (intent.values ?? []).map(
-    (row) => columns.map((col) => row[col])
-  );
+  const rows = intent.values ?? [];
+  const values = rows.map((row) => columns.map((col) => row[col]));
   const columnTypes = getColumnTypes(intent.table, columns, deps);
   const config = {
     table: intent.table,
@@ -13473,7 +14119,7 @@ function compileInsert2(intent, options, deps) {
   };
   const maxBatchSize = options?.maxBatchSize;
   if (maxBatchSize !== void 0 && values.length > maxBatchSize) {
-    throw new InvalidOperationError2(
+    throw new InvalidOperationError3(
       "insert",
       `Batch size ${values.length} exceeds maxBatchSize ${maxBatchSize}`
     );
@@ -13549,7 +14195,7 @@ function compileBatchUpdate(intent, _options, deps) {
   };
   const state = createCompilerState();
   if (intent.updates.length === 0) {
-    throw new InvalidOperationError2(
+    throw new InvalidOperationError3(
       "update",
       "batchSet requires at least one row"
     );
@@ -13558,7 +14204,7 @@ function compileBatchUpdate(intent, _options, deps) {
   const matchColumns = [...intent.matchColumns];
   for (const mc of matchColumns) {
     if (!allColumns.includes(mc)) {
-      throw new InvalidOperationError2(
+      throw new InvalidOperationError3(
         "update",
         `Match column "${mc}" not found in update data. Each row must include the match column(s).`
       );
@@ -13581,7 +14227,13 @@ function compileBatchUpdate(intent, _options, deps) {
       naming: deps.naming,
       ...schemaName !== void 0 && { schemaName },
       ...deps.model !== void 0 && { model: deps.model },
-      compileSubquery: (sqIntent, paramOffset) => buildSubqueryFromIntent(sqIntent, paramOffset, deps.naming, schemaName)
+      compileSubquery: (sqIntent, paramOffset) => buildSubqueryFromIntent(
+        sqIntent,
+        paramOffset,
+        deps.naming,
+        schemaName,
+        "rawExists"
+      )
     };
     whereGuard = compileWhereIntent(intent.where, whereCtx);
   }
@@ -13685,7 +14337,7 @@ function compileUpsert2(intent, options, deps) {
   };
   const maxBatchSize = options?.maxBatchSize;
   if (maxBatchSize !== void 0 && values.length > maxBatchSize) {
-    throw new InvalidOperationError2(
+    throw new InvalidOperationError3(
       "upsert",
       `Batch size ${values.length} exceeds maxBatchSize ${maxBatchSize}`
     );
@@ -13738,6 +14390,7 @@ function compileUpsertFrom2(intent, options, deps) {
 init_assert_field();
 init_ast_helpers();
 init_compile_where();
+import { countDistinctRelationPathsByName } from "@dbsp/core";
 init_compiler_utils();
 init_types();
 init_intent_to_decisions();
@@ -13746,6 +14399,7 @@ init_param_ref();
 // src/plan-decision-extractor.ts
 init_assert_field();
 init_intent_to_decisions();
+import { deriveRelationPathFromIntentPath } from "@dbsp/core";
 function findExistsIntents(where) {
   if (!where || typeof where !== "object") return [];
   const w = where;
@@ -13790,7 +14444,9 @@ function resolveIncludeByPath(includes, intentPath, relationName) {
     }
     if (resolved) return resolved;
   }
-  return includes.find((i) => i.relation === relationName);
+  return includes.find(
+    (i) => i.relation === relationName || i.via === relationName
+  );
 }
 function deriveForeignKey(context, deriveFk = defaultFkDerivation, defaultPk = DEFAULT_PK_COLUMN) {
   const fk = context.foreignKey ?? context.sourceFK;
@@ -13815,24 +14471,6 @@ function mapComparisonOperator(op3) {
   };
   return map[op3] ?? "=";
 }
-function valueToNode2(value) {
-  if (typeof value === "string") {
-    return { A_Const: { sval: { sval: value } } };
-  }
-  if (typeof value === "number") {
-    if (Number.isInteger(value)) {
-      return { A_Const: { ival: { ival: value } } };
-    }
-    return { A_Const: { fval: { fval: String(value) } } };
-  }
-  if (typeof value === "boolean") {
-    return { A_Const: { boolval: { boolval: value } } };
-  }
-  if (value === null) {
-    return { A_Const: { isnull: true } };
-  }
-  return { A_Const: { sval: { sval: String(value) } } };
-}
 function convertWhereToDecisions(where, table) {
   if (!where || typeof where !== "object") return [];
   const w = where;
@@ -14499,6 +15137,11 @@ function toIncludeDecision(d, choice, plan, defaultPk = DEFAULT_PK_COLUMN, deriv
     type: "includeStrategy",
     choice: effectiveChoice,
     relationName,
+    relationPath: deriveRelationPathFromIntentPath(
+      Array.isArray(plan.intent?.include) ? plan.intent.include : void 0,
+      context.intentPath,
+      relationName
+    ) ?? relationName,
     targetTable: context.target,
     ...context.sourceTable && { sourceTable: context.sourceTable },
     ...relationType && { relationType },
@@ -14513,6 +15156,11 @@ function toJoinIncludeDecision(d, plan, defaultPk = DEFAULT_PK_COLUMN, deriveFk
   const relationName = context.relation ?? context.includeAlias;
   if (!context.target || !relationName) return void 0;
   const intentPath = context?.intentPath;
+  const relationPath = deriveRelationPathFromIntentPath(
+    Array.isArray(plan.intent?.include) ? plan.intent.include : void 0,
+    intentPath,
+    relationName
+  ) ?? relationName;
   const includeIntent = resolveIncludeByPath(
     plan.intent?.include,
     intentPath,
@@ -14540,6 +15188,7 @@ function toJoinIncludeDecision(d, plan, defaultPk = DEFAULT_PK_COLUMN, deriveFk
     type: "includeStrategy",
     choice: "join",
     relationName,
+    relationPath,
     targetTable: context.target,
     ...context.sourceTable && { sourceTable: context.sourceTable },
     ...relationType && { relationType },
@@ -14585,6 +15234,7 @@ function synthesizeMissingJoinDecisions(plan, coveredRelations, model, defaultPk
       type: "includeStrategy",
       choice: "join",
       relationName: alias,
+      relationPath: alias,
       targetTable: rel.target,
       sourceTable,
       ...rel.type && {
@@ -14881,22 +15531,11 @@ function buildRelationColumnsMap(decisions, includedRelations) {
   }
   return map;
 }
-function findRelationMapKey(map, relationName) {
-  if (map.has(relationName)) return relationName;
-  const suffix = `.${relationName}`;
-  for (const key of map.keys()) {
-    if (key.endsWith(suffix)) return key;
-  }
-  return void 0;
-}
 function injectAndValidateRelationColumns(enrichedUnifiedDecisions, relationColumnsMap, model) {
   if (relationColumnsMap.size === 0) return;
   for (const d of enrichedUnifiedDecisions) {
     if (d.type === "includeStrategy" && d.relationName) {
-      const mapKey = findRelationMapKey(
-        relationColumnsMap,
-        d.relationName
-      );
+      const mapKey = d.relationPath ?? d.relationName;
       const entries = mapKey ? relationColumnsMap.get(mapKey) : void 0;
       if (entries) {
         const mut = d;
@@ -14931,6 +15570,27 @@ function injectAndValidateRelationColumns(enrichedUnifiedDecisions, relationColu
     }
   }
 }
+function applyJoinHydrationPrefixes(decisions) {
+  const usages = [];
+  for (const d of decisions) {
+    if (d.type !== "includeStrategy" || d.choice !== "join" || !d.relationName) {
+      continue;
+    }
+    const relationName = d.relationName;
+    const relationPath = d.relationPath ?? relationName;
+    usages.push({ relationName, relationPath });
+  }
+  const pathCountsByRelation = countDistinctRelationPathsByName(usages);
+  for (const d of decisions) {
+    if (d.type !== "includeStrategy" || d.choice !== "join" || !d.relationName) {
+      continue;
+    }
+    const relationName = d.relationName;
+    const relationPath = d.relationPath ?? relationName;
+    const usesFullPath = (pathCountsByRelation.get(relationName) ?? 0) > 1;
+    d.hydrationPrefix = usesFullPath ? relationPath : relationName;
+  }
+}
 function enrichRangeDecisions(allDecisions, model, rootTable) {
   if (!model) return;
   for (let i = 0; i < allDecisions.length; i++) {
@@ -15019,6 +15679,7 @@ function compileSelect(plan, options, deps) {
       ...allUnifiedIncludeDecisions
     ];
     stripJoinColumnsForAggregation(enrichedUnifiedDecisions, execIntent);
+    applyJoinHydrationPrefixes(enrichedUnifiedDecisions);
     const includedRelations = new Set(
       enrichedUnifiedDecisions.filter((d) => d.type === "includeStrategy").map((d) => d.relationName).filter(Boolean)
     );
@@ -15116,6 +15777,7 @@ function compileWithIncludes(plan, options, deps) {
 init_ast_helpers();
 init_compiler_utils();
 init_handlers();
+init_utils();
 init_param_ref();
 
 // src/recursive/cte-compiler.ts
@@ -15829,6 +16491,7 @@ function buildEdgeTableRecursiveCte(config) {
 // src/adapter-compiler-recursive.ts
 function compileRecursive(report, _model, _options, deps) {
   const schemaName = deps.schemaName;
+  const state = createCompilerState();
   const intent = report.intent;
   const traversal = intent.traversal;
   const trackPath = intent.track?.path !== void 0;
@@ -15848,7 +16511,7 @@ function compileRecursive(report, _model, _options, deps) {
     const selectColumns = Array.from(/* @__PURE__ */ new Set([nodeIdColumn, ...startSelect]));
     const edgeFrom = traversal.direction === "in" ? traversal.edgeTo : traversal.edgeFrom;
     const edgeTo = traversal.direction === "in" ? traversal.edgeFrom : traversal.edgeTo;
-    const anchorWhere = intent.start.where ? buildRecursiveAnchorWhere(intent.start.where, "__n", deps) : void 0;
+    const anchorWhere = intent.start.where ? buildRecursiveAnchorWhere(intent.start.where, "__n", deps, state) : void 0;
     const base = {
       cteAlias: intent.cteName,
       table,
@@ -15974,11 +16637,10 @@ function compileRecursive(report, _model, _options, deps) {
   const sql = deparseQuoted({ SelectStmt: selectStmt2 });
   return {
     sql,
-    parameters: []
+    parameters: state.parameters
   };
 }
-function compileCteQuery(intent, _options, deps) {
-  const schemaName = deps.schemaName;
+function compileCteQuery(intent, options, deps) {
   const state = createCompilerState();
   const allCteParams = [];
   const cteSqlFragments = [];
@@ -15992,8 +16654,8 @@ function compileCteQuery(intent, _options, deps) {
       isRecursive = true;
       const { sql: cteSql, params: cteParams } = buildRawCte(
         cte,
-        schemaName,
-        deps
+        deps,
+        options
       );
       allCteParams.push(...cteParams);
       cteSqlFragments.push(cteSql);
@@ -16011,12 +16673,7 @@ function compileCteQuery(intent, _options, deps) {
           isAmbiguous: false
         }
       };
-      const innerCompileOptions = schemaName !== void 0 ? { schemaName } : {};
-      const innerCompiled = compileSelect(
-        innerPlanReport,
-        innerCompileOptions,
-        deps
-      );
+      const innerCompiled = compileSelect(innerPlanReport, options, deps);
       const currentParamOffset = allCteParams.length;
       const renumberedInnerSql = currentParamOffset > 0 ? innerCompiled.sql.replace(
         /\$([0-9]+)/g,
@@ -16031,7 +16688,6 @@ function compileCteQuery(intent, _options, deps) {
       );
     }
   }
-  const outerCompileOptions = schemaName !== void 0 ? { schemaName } : {};
   const outerPlanReport = {
     rootTable: intent.query.from,
     decisions: [],
@@ -16044,11 +16700,7 @@ function compileCteQuery(intent, _options, deps) {
       isAmbiguous: false
     }
   };
-  const outerCompiled = compileSelect(
-    outerPlanReport,
-    outerCompileOptions,
-    deps
-  );
+  const outerCompiled = compileSelect(outerPlanReport, options, deps);
   const cteParamCount = allCteParams.length;
   const renumberedOuterSql = cteParamCount > 0 ? outerCompiled.sql.replace(
     /\$([0-9]+)/g,
@@ -16114,8 +16766,7 @@ function buildUnnestCte(cte, state, deps) {
     }
   };
 }
-function buildRawCte(cte, schemaName, deps) {
-  const compileOptions = schemaName !== void 0 ? { schemaName } : {};
+function buildRawCte(cte, deps, options) {
   const basePlanReport = {
     rootTable: cte.base.from,
     decisions: [],
@@ -16124,7 +16775,7 @@ function buildRawCte(cte, schemaName, deps) {
     intent: cte.base,
     metadata: { planningTimeMs: 0, relationsAnalyzed: 0, isAmbiguous: false }
   };
-  const baseCompiled = compileSelect(basePlanReport, compileOptions, deps);
+  const baseCompiled = compileSelect(basePlanReport, options, deps);
   const stepPlanReport = {
     rootTable: cte.step.from,
     decisions: [],
@@ -16133,7 +16784,7 @@ function buildRawCte(cte, schemaName, deps) {
     intent: cte.step,
     metadata: { planningTimeMs: 0, relationsAnalyzed: 0, isAmbiguous: false }
   };
-  const stepCompiled = compileSelect(stepPlanReport, compileOptions, deps);
+  const stepCompiled = compileSelect(stepPlanReport, options, deps);
   const baseParamCount = baseCompiled.parameters.length;
   const renumberedStepSql = baseParamCount > 0 ? stepCompiled.sql.replace(
     /\$([0-9]+)/g,
@@ -16159,7 +16810,7 @@ function buildRawCte(cte, schemaName, deps) {
     params: allParams
   };
 }
-function buildRecursiveAnchorWhere(where, tableAlias, deps) {
+function buildRecursiveAnchorWhere(where, tableAlias, deps, state) {
   if (!where || typeof where !== "object") {
     return { A_Const: { boolval: { boolval: true } } };
   }
@@ -16176,7 +16827,7 @@ function buildRecursiveAnchorWhere(where, tableAlias, deps) {
         }
       };
       const op3 = mapComparisonOperator(w.operator);
-      const right = valueToNode2(w.value);
+      const right = compileValue(w.value, state, void 0, true);
       return {
         A_Expr: {
           kind: "AEXPR_OP",
@@ -16188,14 +16839,14 @@ function buildRecursiveAnchorWhere(where, tableAlias, deps) {
     }
     case "and": {
       const conditions = w.conditions.map(
-        (c) => buildRecursiveAnchorWhere(c, tableAlias, deps)
+        (c) => buildRecursiveAnchorWhere(c, tableAlias, deps, state)
       );
       if (conditions.length === 1) return conditions[0];
       return { BoolExpr: { boolop: "AND_EXPR", args: conditions } };
     }
     case "or": {
       const conditions = w.conditions.map(
-        (c) => buildRecursiveAnchorWhere(c, tableAlias, deps)
+        (c) => buildRecursiveAnchorWhere(c, tableAlias, deps, state)
       );
       if (conditions.length === 1) return conditions[0];
       return { BoolExpr: { boolop: "OR_EXPR", args: conditions } };
@@ -16374,12 +17025,12 @@ function compileLeafOrBranch(intent, compileFn) {
   const result = compileFn(intent);
   return { sql: result.sql, parameters: result.parameters };
 }
-function createLeafCompileFn(adapter, model, planFn2) {
+function createLeafCompileFn(adapter, model, planFn2, options) {
   return (query) => {
     const planReport = planFn2(query, model, {
       dialectCapabilities: adapter.dialectCapabilities
     });
-    return adapter.compile(planReport, { model });
+    return adapter.compile(planReport, { ...options, model });
   };
 }
 
@@ -16498,6 +17149,15 @@ function mapFetchDirection(direction) {
 
 // src/pgsql-adapter.ts
 init_validate();
+function renumberSqlParams(sql, offset) {
+  if (offset === 0) return sql;
+  return sql.replace(/\$(\d+)/g, (_match, num) => {
+    return `$${Number.parseInt(num, 10) + offset}`;
+  });
+}
+function isCompiledNqlQuery(input) {
+  return !("intent" in input) && ("query" in input || "cteQuery" in input || "mutation" in input || "setOperation" in input || "bindings" in input || "mutationBindings" in input);
+}
 var PgsqlAdapter = class _PgsqlAdapter {
   pool;
   client;
@@ -16577,6 +17237,124 @@ var PgsqlAdapter = class _PgsqlAdapter {
       deriveFk: this.deriveFk
     };
   }
+  requireNqlCompileModel(options) {
+    const model = options?.model ?? this.model;
+    if (model === void 0) {
+      throw new Error(
+        "Compiling an NQL bundle requires a model. Pass { model } to adapter.compile(compiledNql, { model }) or configure the adapter with a model."
+      );
+    }
+    return model;
+  }
+  compileNqlMutation(bundle, options) {
+    const mutation = bundle.mutation;
+    if (mutation === void 0) {
+      throw new Error("NQL bundle did not contain a mutation intent.");
+    }
+    switch (mutation.type) {
+      case "insert":
+        return compileInsert2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+      case "insert_from":
+        return compileInsertFrom2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+      case "update":
+        return compileUpdate2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+      case "delete":
+        return compileDelete2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+      case "upsert":
+        return compileUpsert2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+      case "upsert_from":
+        return compileUpsertFrom2(
+          mutation,
+          options,
+          this.buildCompileDeps(options)
+        );
+    }
+    throw new Error(
+      `Unsupported NQL mutation type: ${mutation.type}`
+    );
+  }
+  compileNqlBundleLeaf(bundle, options) {
+    if (bundle.query !== void 0) {
+      const model = this.requireNqlCompileModel(options);
+      const planReport = planFn(bundle.query, model, {
+        dialectCapabilities: this.dialectCapabilities
+      });
+      return compileSelect(
+        planReport,
+        options,
+        this.buildCompileDeps(options)
+      );
+    }
+    if (bundle.cteQuery !== void 0) {
+      return compileCteQuery(
+        bundle.cteQuery,
+        options,
+        this.buildCompileDeps(options)
+      );
+    }
+    if (bundle.setOperation !== void 0) {
+      const model = this.requireNqlCompileModel(options);
+      return this.compileSetOperation(
+        bundle.setOperation,
+        model,
+        options
+      );
+    }
+    if (bundle.mutation !== void 0) {
+      return this.compileNqlMutation(bundle, options);
+    }
+    throw new Error("NQL bundle did not contain a compilable intent.");
+  }
+  compileNqlBundle(bundle, options) {
+    const ctes = [];
+    const parameters = [];
+    for (const [name, queryIntent] of bundle.bindings ?? []) {
+      const cteName = quoteIdent2(name, "alias");
+      const bindingBundle = bundle.mutationBindings?.has(name) ? { mutation: bundle.mutationBindings.get(name) } : { query: queryIntent };
+      const compiled2 = this.compileNqlBundleLeaf(bindingBundle, options);
+      ctes.push(
+        `${cteName} as (${renumberSqlParams(compiled2.sql, parameters.length)})`
+      );
+      parameters.push(...compiled2.parameters);
+    }
+    const leafBundle = {
+      ...bundle.query !== void 0 && { query: bundle.query },
+      ...bundle.cteQuery !== void 0 && { cteQuery: bundle.cteQuery },
+      ...bundle.mutation !== void 0 && { mutation: bundle.mutation },
+      ...bundle.returning !== void 0 && { returning: bundle.returning },
+      ...bundle.setOperation !== void 0 && {
+        setOperation: bundle.setOperation
+      }
+    };
+    const compiled = this.compileNqlBundleLeaf(leafBundle, options);
+    if (ctes.length === 0) {
+      return compiled;
+    }
+    return {
+      sql: `WITH ${ctes.join(", ")} ${renumberSqlParams(compiled.sql, parameters.length)}`,
+      parameters: [...parameters, ...compiled.parameters]
+    };
+  }
   /**
    * Returns the pool/client executor, or throws if in compile-only mode.
    */
@@ -16616,6 +17394,9 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * Compile a plan to executable SQL.
    */
   compile(plan, options) {
+    if (isCompiledNqlQuery(plan)) {
+      return this.compileNqlBundle(plan, options);
+    }
     return compileSelect(plan, options, this.buildCompileDeps(options));
   }
   /**
@@ -16779,8 +17560,8 @@ var PgsqlAdapter = class _PgsqlAdapter {
   /**
    * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
    */
-  compileSetOperation(intent, model, _options) {
-    const compileFn = createLeafCompileFn(this, model, planFn);
+  compileSetOperation(intent, model, options) {
+    const compileFn = createLeafCompileFn(this, model, planFn, options);
     const result = compileSetOperation(intent, compileFn);
     return {
       sql: result.sql,