@dbsp/adapter-pgsql 1.5.0 → 1.6.0

package/dist/index.js

@@ -588,12 +588,6 @@ function binaryExpr(operator, left, right, kind = "AEXPR_OP") {
 function eqExpr(left, right) {
   return binaryExpr("=", left, right);
 }
-function fkCorrelation(col1, alias1, col2, alias2, naming) {
-  return eqExpr(
-    columnRef(col1, alias1, void 0, naming),
-    columnRef(col2, alias2, void 0, naming)
-  );
-}
 function neExpr(left, right) {
   return binaryExpr("<>", left, right);
 }
@@ -885,10 +879,23 @@ function jsonAggSubquery(targetTable, whereExpr, alias, schemaName, naming = ide
       }
     };
   }
+  const aggOrder = options?.orderBy && options.orderBy.length > 0 ? options.orderBy.map(
+    (col) => sortBy(
+      jsonAggOrderByExpression(
+        col,
+        targetAlias,
+        naming,
+        options.orderByFallback === true
+      ),
+      "ASC",
+      "LAST"
+    )
+  ) : void 0;
   const jsonAggCall = {
     FuncCall: {
       funcname: [stringNode("json_agg")],
-      args: [toJsonbCall]
+      args: [toJsonbCall],
+      ...aggOrder && { agg_order: aggOrder }
     }
   };
   const fromTable = rangeVar(targetTable, targetAlias, schemaName, naming);
@@ -923,11 +930,9 @@ function jsonAggSubquery(targetTable, whereExpr, alias, schemaName, naming = ide
     }
   };
 }
-function jsonAggCorrelation(parentAlias, parentColumn, targetAlias, targetColumn, naming = identityNaming) {
-  return eqExpr(
-    columnRef(targetColumn, targetAlias, void 0, naming),
-    columnRef(parentColumn, parentAlias, void 0, naming)
-  );
+function jsonAggOrderByExpression(entry, targetAlias, naming, castToText) {
+  const ref = columnRef(entry, targetAlias, void 0, naming);
+  return castToText ? typeCast(ref, "text") : ref;
 }
 var STRENGTH_MAP, POLICY_MAP;
 var init_ast_helpers = __esm({
@@ -3172,6 +3177,7 @@ var init_custom_expression = __esm({
 });
 
 // src/handlers/where/exists.ts
+import { toColumnList } from "@dbsp/types";
 function createSubLinkExists(subquery, negated) {
   const subLink = {
     subLinkType: "EXISTS_SUBLINK",
@@ -3188,10 +3194,27 @@ function createSubLinkExists(subquery, negated) {
   }
   return existsNode;
 }
-function buildCorrelation(sourceAlias, sourceColumn, targetAlias, targetColumn, ctx) {
-  const left = columnRef(sourceColumn, sourceAlias, void 0, ctx.naming);
-  const right = columnRef(targetColumn, targetAlias, void 0, ctx.naming);
-  return eqExpr(left, right);
+function buildKeyCorrelation(sourceAlias, sourceCols, targetAlias, targetCols, ctx) {
+  const normalizedSourceCols = toColumnList(sourceCols);
+  const normalizedTargetCols = toColumnList(targetCols);
+  if (normalizedSourceCols.length === 0 || normalizedTargetCols.length === 0 || normalizedSourceCols.length !== normalizedTargetCols.length || normalizedSourceCols.some((column) => column.length === 0) || normalizedTargetCols.some((column) => column.length === 0)) {
+    throw new Error(
+      `Invalid relation correlation: source columns (${normalizedSourceCols.length}) must match target columns (${normalizedTargetCols.length}) and both must be non-empty.`
+    );
+  }
+  const comparisons = normalizedSourceCols.map(
+    (sourceColumn, index) => eqExpr(
+      columnRef(sourceColumn, sourceAlias, void 0, ctx.naming),
+      columnRef(
+        normalizedTargetCols[index],
+        targetAlias,
+        void 0,
+        ctx.naming
+      )
+    )
+  );
+  if (comparisons.length === 1) return comparisons[0];
+  return andExpr(...comparisons);
 }
 function schemaForExistsFromName(ctx, fromName) {
   return schemaForFromName(ctx.schema, fromName, ctx.bindingNames, ctx.naming);
@@ -3199,11 +3222,15 @@ function schemaForExistsFromName(ctx, fromName) {
 function buildExistsSubquery(decision, ctx, state, dispatch) {
   const relation = decision.relation;
   const targetTable = decision.targetTable ?? relation;
-  const sourceColumn = decision.sourceColumn ?? ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
-  const targetColumn = decision.targetColumn ?? (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-    ctx.rootTable,
+  const sourceColumn = decision.sourceColumn ?? [
     ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-  );
+  ];
+  const targetColumn = decision.targetColumn ?? [
+    (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+      ctx.rootTable,
+      ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+    )
+  ];
   if (!targetTable) {
     throw new Error("EXISTS handler requires targetTable or relation");
   }
@@ -3211,7 +3238,7 @@ function buildExistsSubquery(decision, ctx, state, dispatch) {
   const targetAlias = `${targetTable}_exists_${existingAliases}`;
   state.aliases.set(`exists_${targetTable}`, targetAlias);
   const sourceAlias = ctx.currentAlias ?? ctx.rootTable;
-  const correlation = buildCorrelation(
+  const correlation = buildKeyCorrelation(
     sourceAlias,
     sourceColumn,
     targetAlias,
@@ -3249,8 +3276,8 @@ function buildExistsSubquery(decision, ctx, state, dispatch) {
       const joinRelation = inc.relation;
       if (!joinRelation) continue;
       let joinTargetTable = joinRelation;
-      let joinSourceCol;
-      let joinTargetCol;
+      let joinSourceCols;
+      let joinTargetCols;
       let sourceAliasForJoin = targetAlias;
       const model = ctx.model;
       if (model) {
@@ -3268,31 +3295,41 @@ function buildExistsSubquery(decision, ctx, state, dispatch) {
         if (rel) {
           joinTargetTable = rel.target;
           if (rel.type === "belongsTo") {
-            const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : void 0;
-            joinSourceCol = fk;
-            joinTargetCol = ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
+            const fk = toColumnList(rel.foreignKey);
+            joinSourceCols = fk.length > 0 ? fk : void 0;
+            const targetKey = toColumnList(rel.targetKey);
+            joinTargetCols = targetKey.length > 0 ? targetKey : [
+              ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+            ];
           } else {
-            const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : void 0;
-            joinSourceCol = ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
-            joinTargetCol = fk;
+            const fk = toColumnList(rel.foreignKey);
+            const sourceKey = toColumnList(rel.sourceKey);
+            joinSourceCols = sourceKey.length > 0 ? sourceKey : [
+              ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+            ];
+            joinTargetCols = fk.length > 0 ? fk : void 0;
           }
         }
       }
-      if (!joinSourceCol) {
-        joinSourceCol = (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-          joinRelation,
+      if (!joinSourceCols || joinSourceCols.length === 0) {
+        joinSourceCols = [
+          (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+            joinRelation,
+            ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+          )
+        ];
+        joinTargetCols = [
           ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-        );
-        joinTargetCol = ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
+        ];
       }
       const joinAlias = joinRelation;
-      const joinQuals = fkCorrelation(
-        joinSourceCol,
+      const joinQuals = buildKeyCorrelation(
         sourceAliasForJoin,
         // resolved source alias (root or intermediate)
-        joinTargetCol ?? DEFAULT_PK_COLUMN,
+        joinSourceCols,
         joinAlias,
-        ctx.naming
+        joinTargetCols,
+        ctx
       );
       const joinType = inc.joinType === "left" ? "JOIN_LEFT" : "JOIN_INNER";
       const joinRangeVar = rangeVar(
@@ -3774,6 +3811,7 @@ var init_range = __esm({
 });
 
 // src/compile-where.ts
+import { toColumnList as toColumnList2 } from "@dbsp/types";
 import { getTrustedNqlRelationFilterFields as getTrustedNqlRelationFilterFields3 } from "@dbsp/types/internal";
 function toHandlerContext(ctx) {
   return {
@@ -4039,14 +4077,16 @@ function handleRelationFilterIntent(intent, ctx) {
     let singleHopTargetColumn;
     if (resolvedRelation) {
       const rel = resolvedRelation;
-      const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : void 0;
+      const fk = toColumnList2(rel.foreignKey);
       const defaultPk = DEFAULT_PK_COLUMN;
       if (rel.type === "belongsTo") {
-        singleHopSourceColumn = fk ?? defaultFkDerivation(rel.target, defaultPk);
-        singleHopTargetColumn = rel.targetKey ?? defaultPk;
+        singleHopSourceColumn = fk.length > 0 ? fk : [defaultFkDerivation(rel.target, defaultPk)];
+        const targetKey = toColumnList2(rel.targetKey);
+        singleHopTargetColumn = targetKey.length > 0 ? targetKey : [defaultPk];
       } else {
-        singleHopSourceColumn = rel.sourceKey ?? defaultPk;
-        singleHopTargetColumn = fk ?? defaultFkDerivation(ctx.rootTable, defaultPk);
+        const sourceKey = toColumnList2(rel.sourceKey);
+        singleHopSourceColumn = sourceKey.length > 0 ? sourceKey : [defaultPk];
+        singleHopTargetColumn = fk.length > 0 ? fk : [defaultFkDerivation(ctx.rootTable, defaultPk)];
       }
     }
     return compileWhereIntent(
@@ -4083,15 +4123,19 @@ function handleRelationFilterIntent(intent, ctx) {
       );
     }
     hopTargets.push(rel.target);
-    const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : void 0;
+    const fk = toColumnList2(rel.foreignKey);
     const defaultPk = DEFAULT_PK_COLUMN;
     if (rel.type === "belongsTo") {
-      hopSourceColumns.push(fk ?? defaultFkDerivation(rel.target, defaultPk));
-      hopTargetColumns.push(rel.targetKey ?? defaultPk);
+      hopSourceColumns.push(
+        fk.length > 0 ? fk : [defaultFkDerivation(rel.target, defaultPk)]
+      );
+      const targetKey = toColumnList2(rel.targetKey);
+      hopTargetColumns.push(targetKey.length > 0 ? targetKey : [defaultPk]);
     } else {
-      hopSourceColumns.push(rel.sourceKey ?? defaultPk);
+      const sourceKey = toColumnList2(rel.sourceKey);
+      hopSourceColumns.push(sourceKey.length > 0 ? sourceKey : [defaultPk]);
       hopTargetColumns.push(
-        fk ?? defaultFkDerivation(currentSource, defaultPk)
+        fk.length > 0 ? fk : [defaultFkDerivation(currentSource, defaultPk)]
       );
     }
     currentSource = rel.target;
@@ -4319,6 +4363,7 @@ var init_raw_exists = __esm({
 });
 
 // src/handlers/where/relation-filter.ts
+import { toColumnList as toColumnList3 } from "@dbsp/types";
 function getFilterMode(decision) {
   const operator = decision.operator;
   if (operator === "some" || operator === "exists") return "some";
@@ -4330,15 +4375,18 @@ function getFilterMode(decision) {
 function buildJoinFilter(decision, ctx, state, dispatch) {
   const relation = decision.relation;
   const targetTable = decision.targetTable ?? relation;
-  const sourceColumn = requiredColumn(
-    decision.sourceColumn,
-    "sourceColumn",
-    "relation filter"
-  );
-  const targetColumn = decision.targetColumn ?? (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-    ctx.rootTable,
-    ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-  );
+  const sourceColumn = toColumnList3(decision.sourceColumn);
+  if (sourceColumn.length === 0) {
+    throw new Error(
+      "Missing required column 'sourceColumn' in relation filter"
+    );
+  }
+  const targetColumn = decision.targetColumn ?? [
+    (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+      ctx.rootTable,
+      ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+    )
+  ];
   if (!targetTable) {
     throw new Error("Relation filter requires targetTable");
   }
@@ -4346,9 +4394,12 @@ function buildJoinFilter(decision, ctx, state, dispatch) {
   const targetAlias = `${targetTable}_rel_${existingAliases}`;
   state.aliases.set(`rel_${targetTable}`, targetAlias);
   const sourceAlias = ctx.currentAlias ?? ctx.rootTable;
-  const joinCondition = eqExpr(
-    columnRef(sourceColumn, sourceAlias, ctx.schema, ctx.naming),
-    columnRef(targetColumn, targetAlias, ctx.schema, ctx.naming)
+  const joinCondition = buildKeyCorrelation(
+    sourceAlias,
+    sourceColumn,
+    targetAlias,
+    targetColumn,
+    ctx
   );
   const joinExpr2 = {
     jointype: "JOIN_INNER",
@@ -4383,6 +4434,7 @@ var init_relation_filter = __esm({
     "use strict";
     init_assert_field();
     init_ast_helpers();
+    init_exists();
     relationFilterHandler = {
       operators: ["relationFilter", "relation", "is", "isNot"],
       compile(decision, ctx, state, dispatch) {
@@ -4812,6 +4864,7 @@ var init_where = __esm({
 });
 
 // src/handlers/include/cte.ts
+import { toColumnList as toColumnList4 } from "@dbsp/types";
 function buildCteTargets(columns, alias, ctx) {
   if (columns && columns.length > 0 && !columns.every((c) => c === "*")) {
     return columns.filter((col) => col !== "*").map((col) => ({
@@ -4862,12 +4915,12 @@ function buildCTE(cteName, cteSelect, ctx) {
   return { CommonTableExpr: cte };
 }
 function buildCteJoin(cteName, cteAlias, sourceAlias, sourceColumn, targetColumn, ctx) {
-  const joinCondition = fkCorrelation(
-    sourceColumn,
+  const joinCondition = buildKeyCorrelation(
     sourceAlias,
-    targetColumn,
+    sourceColumn,
     cteAlias,
-    ctx.naming
+    targetColumn,
+    ctx
   );
   const cteRef = {
     RangeVar: {
@@ -4891,20 +4944,22 @@ var init_cte = __esm({
     init_assert_field();
     init_ast_helpers();
     init_handlers();
+    init_exists();
     cteIncludeHandler = {
       strategy: "cte",
       compile(decision, ctx, state) {
         const relation = decision.relation;
         const targetTable = decision.targetTable ?? relation;
-        const sourceColumn = requiredColumn(
-          decision.sourceColumn,
-          "sourceColumn",
-          "CTE include"
-        );
-        const targetColumn = decision.targetColumn ?? (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-          ctx.rootTable,
-          ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-        );
+        const sourceColumn = toColumnList4(decision.sourceColumn);
+        if (sourceColumn.length === 0 || sourceColumn.some((col) => col === "")) {
+          throw new Error("Missing required column 'sourceColumn' in CTE include");
+        }
+        const targetColumn = decision.targetColumn ?? [
+          (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+            ctx.rootTable,
+            ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+          )
+        ];
         const columns = decision.columns;
         const conditions = decision.conditions;
         if (!targetTable) {
@@ -4947,13 +5002,14 @@ var init_cte = __esm({
 });
 
 // src/handlers/include/join.ts
+import { toColumnList as toColumnList5 } from "@dbsp/types";
 function buildJoin(targetTable, targetAlias, sourceAlias, sourceColumn, targetColumn, ctx, joinType = "left") {
-  const joinCondition = fkCorrelation(
-    sourceColumn,
+  const joinCondition = buildKeyCorrelation(
     sourceAlias,
-    targetColumn,
+    sourceColumn,
     targetAlias,
-    ctx.naming
+    targetColumn,
+    ctx
   );
   const joinExpr2 = {
     jointype: joinType === "inner" ? "JOIN_INNER" : "JOIN_LEFT",
@@ -4968,6 +5024,7 @@ var init_join = __esm({
     "use strict";
     init_assert_field();
     init_ast_helpers();
+    init_exists();
     joinIncludeHandler = {
       strategy: "join",
       compile(decision, ctx, _state) {
@@ -4978,15 +5035,16 @@ var init_join = __esm({
         }
         const targetAlias = relation ?? targetTable;
         const sourceAlias = ctx.currentAlias ?? ctx.rootTable;
-        const sourceColumn = requiredColumn(
-          decision.sourceColumn,
-          "sourceColumn",
-          "JOIN include"
-        );
-        const targetColumn = decision.targetColumn ?? (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-          ctx.rootTable,
-          ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-        );
+        const sourceColumn = toColumnList5(decision.sourceColumn);
+        if (sourceColumn.length === 0) {
+          throw new Error("Missing required column 'sourceColumn' in JOIN include");
+        }
+        const targetColumn = decision.targetColumn ?? [
+          (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+            ctx.rootTable,
+            ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+          )
+        ];
         const join = buildJoin(
           targetTable,
           targetAlias,
@@ -5040,6 +5098,22 @@ var init_shared = __esm({
 });
 
 // src/handlers/include/json-agg.ts
+import { toColumnList as toColumnList6 } from "@dbsp/types";
+function resolveJsonAggOrderBy(decision, targetTable, ctx) {
+  const table = ctx.model?.getTable(targetTable);
+  if (table) {
+    const pkColumns = toColumnList6(table.primaryKey);
+    const orderIntent = pkColumns.length > 0 ? { columns: pkColumns, fallback: false } : {
+      columns: table.columns.map((col) => col.name),
+      fallback: true
+    };
+    return orderIntent.columns.length > 0 ? orderIntent : void 0;
+  }
+  return decision.targetPrimaryKey && decision.targetPrimaryKey.length > 0 ? {
+    columns: decision.targetPrimaryKey,
+    fallback: decision.orderByFallback === true
+  } : void 0;
+}
 function compileJsonAggRecursive(decision, parentAlias, depth, ctx, _state) {
   const innerAlias = depth === 0 ? "__t__" : `__t${depth}__`;
   const relation = decision.relation ?? decision.relationName;
@@ -5056,12 +5130,12 @@ function compileJsonAggRecursive(decision, parentAlias, depth, ctx, _state) {
     ctx.defaultPkColumnName,
     ctx.deriveFkColumnName
   );
-  let whereExpr = jsonAggCorrelation(
-    parentAlias,
-    sourceColumn,
+  let whereExpr = buildKeyCorrelation(
     innerAlias,
     targetColumn,
-    ctx.naming
+    parentAlias,
+    sourceColumn,
+    ctx
   );
   const compiledFilter = decision._compiledFilterWhere;
   if (compiledFilter) {
@@ -5092,6 +5166,7 @@ function compileJsonAggRecursive(decision, parentAlias, depth, ctx, _state) {
     if (childNodes.length === 0) childNodes = void 0;
   }
   const limit = typeof decision.limit === "number" ? decision.limit : void 0;
+  const orderBy = resolveJsonAggOrderBy(decision, targetTable, ctx);
   return jsonAggSubquery(
     targetTable,
     whereExpr,
@@ -5102,7 +5177,9 @@ function compileJsonAggRecursive(decision, parentAlias, depth, ctx, _state) {
       ...childNodes && { childNodes },
       innerAlias,
       ...limit !== void 0 && { limit },
-      ...decision.columns && { columns: decision.columns }
+      ...decision.columns && { columns: decision.columns },
+      ...orderBy && { orderBy: orderBy.columns },
+      ...orderBy?.fallback && { orderByFallback: true }
     }
   );
 }
@@ -5111,6 +5188,7 @@ var init_json_agg = __esm({
   "src/handlers/include/json-agg.ts"() {
     "use strict";
     init_ast_helpers();
+    init_exists();
     init_shared();
     jsonAggIncludeHandler = {
       strategy: "json_agg",
@@ -5132,6 +5210,7 @@ var init_json_agg = __esm({
 });
 
 // src/handlers/include/lateral.ts
+import { toColumnList as toColumnList7 } from "@dbsp/types";
 function buildLateralTargets(columns, alias, ctx) {
   if (columns && columns.length > 0 && !(columns.length === 1 && columns[0] === "*")) {
     return columns.map((col) => ({
@@ -5143,12 +5222,12 @@ function buildLateralTargets(columns, alias, ctx) {
   return [starTarget(alias, ctx.naming)];
 }
 function buildLateralSubquery(targetTable, innerAlias, outerAlias, sourceColumn, targetColumn, columns, limit, ctx) {
-  const whereClause = fkCorrelation(
-    targetColumn,
+  const whereClause = buildKeyCorrelation(
     innerAlias,
-    sourceColumn,
+    targetColumn,
     outerAlias,
-    ctx.naming
+    sourceColumn,
+    ctx
   );
   const targetList = buildLateralTargets(columns, innerAlias, ctx);
   const stmt = {
@@ -5228,19 +5307,23 @@ var init_lateral = __esm({
     "use strict";
     init_assert_field();
     init_ast_helpers();
+    init_exists();
     init_shared();
     lateralIncludeHandler = {
       strategy: "lateral",
       compile(decision, ctx, state) {
-        const sourceColumn = requiredColumn(
-          decision.sourceColumn,
-          "sourceColumn",
-          "lateral include"
-        );
-        const targetColumn = decision.targetColumn ?? (ctx.deriveFkColumnName ?? defaultFkDerivation)(
-          ctx.rootTable,
-          ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
-        );
+        const sourceColumn = toColumnList7(decision.sourceColumn);
+        if (sourceColumn.length === 0) {
+          throw new Error(
+            "Missing required column 'sourceColumn' in lateral include"
+          );
+        }
+        const targetColumn = decision.targetColumn ?? [
+          (ctx.deriveFkColumnName ?? defaultFkDerivation)(
+            ctx.rootTable,
+            ctx.defaultPkColumnName ?? DEFAULT_PK_COLUMN
+          )
+        ];
         const outerAlias = ctx.currentAlias ?? ctx.rootTable;
         const { joins, targets } = compileLateralCascade(
           decision,
@@ -7229,7 +7312,8 @@ import { InvalidOperationError as InvalidOperationError2 } from "@dbsp/core";
 import {
   isParamIntent as isParamIntent6,
   NQL_SELECT_SCALAR_FUNCTION_ALLOWLIST,
-  NQL_SELECT_WINDOW_FUNCTION_ALLOWLIST
+  NQL_SELECT_WINDOW_FUNCTION_ALLOWLIST,
+  toColumnList as toColumnList8
 } from "@dbsp/types";
 import {
   getNqlBindingRefName,
@@ -8299,6 +8383,7 @@ init_window();
 init_include();
 init_shared();
 init_handlers();
+init_exists();
 init_types();
 init_utils();
 init_intent_to_decisions();
@@ -8336,7 +8421,21 @@ function assertNqlSelectWindowFunctionAllowed(functionName) {
     throw new UnsupportedNqlSelectFunctionError(functionName);
   }
 }
+function trustedRelationHasMultipleHops(relation) {
+  if (typeof relation !== "string") return relation.length > 1;
+  return relation.split(".").length > 1;
+}
+function isJsonAggOrderBy(orderBy) {
+  return Array.isArray(orderBy) && orderBy.every((item) => typeof item === "string");
+}
+function isExpressionOrderBy(orderBy) {
+  return Array.isArray(orderBy) && orderBy.every(
+    (item) => typeof item === "object" && item !== null && "field" in item && typeof item.field === "string"
+  );
+}
 function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
+  const jsonAggOrderBy = isJsonAggOrderBy(pd.orderBy) ? pd.orderBy : void 0;
+  const expressionOrderBy = isExpressionOrderBy(pd.orderBy) ? pd.orderBy : void 0;
   const derivedFkColumns = deriveFkColumns(
     pd,
     pd.sourceTable ?? rootTable,
@@ -8371,6 +8470,8 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     relationType: pd.relationType,
     foreignKey: pd.foreignKey,
     parentKey: pd.parentKey,
+    targetPrimaryKey: pd.targetPrimaryKey ?? jsonAggOrderBy,
+    orderByFallback: pd.orderByFallback,
     dataType: pd.dataType,
     traversal: pd.traversal,
     pkColumn: pd.pkColumn,
@@ -8385,7 +8486,7 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     include: pd.include?.map(
       (c) => mapToHandlerDecision(c, rootTable, defaultPk, deriveFk)
     ),
-    orderBy: pd.orderBy?.map((o) => ({
+    orderBy: expressionOrderBy?.map((o) => ({
       column: o.field,
       direction: o.direction?.toUpperCase() ?? "ASC"
     })),
@@ -8767,6 +8868,13 @@ var PlanCompiler = class _PlanCompiler {
       this.defaultPk,
       this.deriveFk
     );
+    if (handlerDecision.strategy === "json_agg") {
+      assertDialectCapability(
+        this.dialectCapabilities,
+        "supportsJsonAgg",
+        "JSON aggregation for relation includes"
+      );
+    }
     const handler = getIncludeHandler(
       handlerDecision.strategy
     );
@@ -8940,17 +9048,7 @@ var PlanCompiler = class _PlanCompiler {
   isNqlBindingRoot(plan) {
     return hasBindingName(this.bindingNames, plan.rootTable, this.naming);
   }
-  compileBindingRelationColumnSubquery(fields, plan) {
-    if (fields.selectedColumn === void 0) {
-      throw new Error(
-        `NQL binding relation-column proof for '${plan.rootTable}' is missing selectedColumn.`
-      );
-    }
-    if (fields.cardinality !== "one") {
-      throw new Error(
-        `NQL binding relation-column proof for '${plan.rootTable}' is not scalar (cardinality: ${fields.cardinality ?? "unknown"}).`
-      );
-    }
+  buildCorrelatedRelationRefs(fields, plan) {
     const relatedAlias = `rc_${this.bindingRelationColumnSubqueryIndex++}`;
     const relatedTable = rangeVar(
       fields.targetTable,
@@ -8964,29 +9062,145 @@ var PlanCompiler = class _PlanCompiler {
       void 0,
       this.naming
     );
-    const relatedJoinColumn = columnRef(
-      fields.targetColumn,
-      relatedAlias,
-      void 0,
-      this.naming
-    );
-    const bindingJoinColumn = columnRef(
-      fields.sourceColumn,
-      plan.rootTable,
-      void 0,
-      this.naming
-    );
     return {
-      SubLink: {
-        subLinkType: "EXPR_SUBLINK",
-        subselect: selectStmt({
-          targetList: [{ ResTarget: { val: relatedColumn } }],
-          from: [relatedTable],
-          where: eqExpr(relatedJoinColumn, bindingJoinColumn)
-        })
-      }
+      relatedAlias,
+      relatedTable,
+      relatedColumn
     };
   }
+  compileBindingRelationColumnSubquery(fields, plan, dialectCapabilities) {
+    if (fields.selectedColumn === void 0) {
+      throw new Error(
+        `NQL binding relation-column proof for '${plan.rootTable}' is missing selectedColumn.`
+      );
+    }
+    if (fields.cardinality === "one") {
+      const { relatedAlias, relatedTable, relatedColumn } = this.buildCorrelatedRelationRefs(fields, plan);
+      if (fields.hops.length === 0 && trustedRelationHasMultipleHops(fields.relation)) {
+        throw new Error(
+          `NQL binding relation-column proof for '${plan.rootTable}' is dotted but missing resolved hops.`
+        );
+      }
+      if (fields.hops.length > 0) {
+        let fromNode = relatedTable;
+        let previousAlias = relatedAlias;
+        for (let i = 0; i < fields.hops.length; i++) {
+          const hop = fields.hops[i];
+          const hopAlias = `${relatedAlias}_h${i + 1}`;
+          const hopTable = rangeVar(
+            hop.target,
+            hopAlias,
+            this.schemaForRangeVar(plan, hop.target),
+            this.naming
+          );
+          fromNode = innerJoin(
+            fromNode,
+            hopTable,
+            buildKeyCorrelation(
+              hopAlias,
+              hop.joinColumn,
+              previousAlias,
+              hop.fkColumn,
+              this.createHandlerContext(plan)
+            )
+          );
+          previousAlias = hopAlias;
+        }
+        return {
+          SubLink: {
+            subLinkType: "EXPR_SUBLINK",
+            subselect: selectStmt({
+              targetList: [
+                {
+                  ResTarget: {
+                    val: columnRef(
+                      fields.selectedColumn,
+                      previousAlias,
+                      void 0,
+                      this.naming
+                    )
+                  }
+                }
+              ],
+              from: [fromNode],
+              where: buildKeyCorrelation(
+                relatedAlias,
+                fields.targetColumn,
+                plan.rootTable,
+                fields.sourceColumn,
+                this.createHandlerContext(plan)
+              )
+            })
+          }
+        };
+      }
+      return {
+        SubLink: {
+          subLinkType: "EXPR_SUBLINK",
+          subselect: selectStmt({
+            targetList: [{ ResTarget: { val: relatedColumn } }],
+            from: [relatedTable],
+            where: buildKeyCorrelation(
+              relatedAlias,
+              fields.targetColumn,
+              plan.rootTable,
+              fields.sourceColumn,
+              this.createHandlerContext(plan)
+            )
+          })
+        }
+      };
+    }
+    if (fields.cardinality === "many") {
+      if (fields.relationType !== "hasMany") {
+        throw new Error(
+          `NQL binding relation-column proof for '${plan.rootTable}' has cardinality 'many' but relationType '${fields.relationType ?? "unknown"}' is not supported; only hasMany can be aggregated (ref-#192).`
+        );
+      }
+      if (dialectCapabilities?.supportsJsonAgg === false) {
+        throw new Error(
+          "JSON aggregation for NQL binding relation columns is not supported by this adapter"
+        );
+      }
+      const { relatedAlias, relatedTable, relatedColumn } = this.buildCorrelatedRelationRefs(fields, plan);
+      return {
+        SubLink: {
+          subLinkType: "EXPR_SUBLINK",
+          subselect: selectStmt({
+            targetList: [
+              {
+                ResTarget: {
+                  val: coalesceExpr([
+                    funcCall("json_agg", [relatedColumn], {
+                      orderBy: [
+                        sortBy(
+                          typeCast(relatedColumn, "text"),
+                          "DEFAULT",
+                          "LAST"
+                        )
+                      ]
+                    }),
+                    typeCast({ A_Const: { sval: { sval: "[]" } } }, "json")
+                  ])
+                }
+              }
+            ],
+            from: [relatedTable],
+            where: buildKeyCorrelation(
+              relatedAlias,
+              fields.targetColumn,
+              plan.rootTable,
+              fields.sourceColumn,
+              this.createHandlerContext(plan)
+            )
+          })
+        }
+      };
+    }
+    throw new Error(
+      `NQL binding relation-column proof for '${plan.rootTable}' is not scalar (cardinality: ${fields.cardinality ?? "unknown"}).`
+    );
+  }
   compileExpressionSubquery(query, paramOffset) {
     const innerCompiler = new _PlanCompiler(this.childCompilerOptions());
     const innerPlan = {
@@ -9369,7 +9583,8 @@ var PlanCompiler = class _PlanCompiler {
           if (trusted?.selectedColumn !== void 0) {
             const node2 = this.compileBindingRelationColumnSubquery(
               trusted,
-              plan
+              plan,
+              this.dialectCapabilities
             );
             targetList.push({
               ResTarget: {
@@ -10106,12 +10321,22 @@ var PlanCompiler = class _PlanCompiler {
   registerJoinFilter(decision) {
     const targetTable = decision.targetTable;
     const sourceTable = this.currentRootTable;
-    const fkColumn = decision.foreignKey ?? this.deriveFk(targetTable, this.defaultPk);
-    const onCondition = eqExpr(
-      columnRef(this.defaultPk, targetTable, void 0, this.naming),
-      columnRef(fkColumn, sourceTable, void 0, this.naming)
-    );
     const alias = targetTable === sourceTable ? decision.relationName ?? `${targetTable}_join` : void 0;
+    const targetAlias = alias ?? targetTable;
+    const fkColumn = decision.foreignKey ?? [
+      this.deriveFk(targetTable, this.defaultPk)
+    ];
+    const targetKey = decision.parentKey ?? [this.defaultPk];
+    const onCondition = buildKeyCorrelation(
+      targetAlias,
+      targetKey,
+      sourceTable,
+      fkColumn,
+      this.createHandlerContext({
+        rootTable: sourceTable,
+        decisions: []
+      })
+    );
     this.pendingJoins.push({
       type: "JOIN",
       table: targetTable,
@@ -10132,19 +10357,21 @@ var PlanCompiler = class _PlanCompiler {
       this.schemaForRangeVar(plan, decision.targetTable ?? ""),
       this.naming
     );
-    const onCondition = eqExpr(
-      columnRef(
-        requiredColumn(decision.sourceColumn, "sourceColumn", "compileJoin"),
-        void 0,
-        void 0,
-        this.naming
-      ),
-      columnRef(
-        requiredColumn(decision.targetColumn, "targetColumn", "compileJoin"),
-        decision.alias ?? decision.targetTable,
-        void 0,
-        this.naming
-      )
+    const sourceColumn = toColumnList8(decision.sourceColumn);
+    const targetColumn = toColumnList8(decision.targetColumn);
+    if (sourceColumn.length === 0) {
+      throw new Error("Missing required column 'sourceColumn' in compileJoin");
+    }
+    if (targetColumn.length === 0) {
+      throw new Error("Missing required column 'targetColumn' in compileJoin");
+    }
+    const sourceAlias = sourceColumn.length > 1 ? plan.rootTable : "";
+    const onCondition = buildKeyCorrelation(
+      sourceAlias,
+      sourceColumn,
+      decision.alias ?? decision.targetTable ?? "",
+      targetColumn,
+      this.createHandlerContext(plan)
     );
     if (decision.joinType === "left") {
       return leftJoin(baseTable, targetTable, onCondition, decision.alias);
@@ -13262,6 +13489,8 @@ function inferRelations(fksByConstraint, filteredTables) {
     if (!filteredSet.has(fk.source) || !filteredSet.has(fk.target)) continue;
     const belongsToName = deriveRelationName(fk.cols[0], fk.target);
     const fkCol = fk.cols.length === 1 ? fk.cols[0] : fk.cols;
+    const refCol = fk.refs.length === 1 ? fk.refs[0] : fk.refs;
+    const keyOverride = Array.isArray(refCol) || refCol !== DEFAULT_PK_COLUMN ? refCol : void 0;
     const belongsToKey = `${fk.source}.${belongsToName}`;
     if (!relations.has(belongsToKey)) {
       relations.set(belongsToKey, {
@@ -13270,6 +13499,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         source: fk.source,
         target: fk.target,
         foreignKey: fkCol,
+        ...keyOverride !== void 0 && { targetKey: keyOverride },
         cardinality: "one",
         optionality: "optional",
         includeStrategy: "auto",
@@ -13286,6 +13516,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         source: fk.target,
         target: fk.source,
         foreignKey: fkCol,
+        ...keyOverride !== void 0 && { sourceKey: keyOverride },
         cardinality: "many",
         optionality: "optional",
         includeStrategy: "auto",
@@ -14188,6 +14419,7 @@ import { getNqlBindingRefName as getNqlBindingRefName2, isNqlBindingRef as isNql
 
 // src/adapter-compiler-includes.ts
 init_ast_helpers();
+import { toColumnList as toColumnList9 } from "@dbsp/types";
 init_handlers();
 function compileSubqueryInclude(info, parentIds, _options, deps) {
   const schemaName = deps.schemaName;
@@ -14199,7 +14431,12 @@ function compileSubqueryInclude(info, parentIds, _options, deps) {
       parameters: []
     };
   }
-  const fkColumns = Array.isArray(info.foreignKey) ? info.foreignKey : [info.foreignKey];
+  const fkColumns = toColumnList9(info.foreignKey);
+  if (fkColumns.length === 0) {
+    throw new Error(
+      "Subquery include requires at least one foreignKey column."
+    );
+  }
   if (info.through && info.throughSourceKey && info.throughTargetKey) {
     return compileSubqueryIncludeManyToMany(
       info,
@@ -14247,6 +14484,11 @@ function compileSubqueryInclude(info, parentIds, _options, deps) {
     };
   } else {
     const conditions = parentIds.map((id) => {
+      if (!Array.isArray(id) || id.length !== fkColumns.length) {
+        throw new Error(
+          `Subquery include composite key parameter width (${Array.isArray(id) ? id.length : 1}) must match foreignKey width (${fkColumns.length}).`
+        );
+      }
       const idValues = id;
       const colConditions = fkColumns.map((col, idx) => {
         state.parameters.push(idValues[idx]);
@@ -14287,7 +14529,13 @@ function compileSubqueryIncludeManyToMany(info, parentIds, schemaName, state, de
   const throughTable = info.through;
   const throughSourceKey = info.throughSourceKey;
   const throughTargetKey = info.throughTargetKey;
-  const targetPk = Array.isArray(info.sourceKey) ? info.sourceKey[0] : info.sourceKey;
+  const targetPkColumns = toColumnList9(info.sourceKey);
+  if (targetPkColumns.length !== 1) {
+    throw new Error(
+      `Many-to-many subquery include requires a single-column target key; got ${JSON.stringify(targetPkColumns)}.`
+    );
+  }
+  const targetPk = targetPkColumns[0];
   const paramRefs = parentIds.map((id) => {
     state.parameters.push(id);
     state.paramIndex++;
@@ -14376,6 +14624,7 @@ import {
   POSTGRESQL_CAPABILITIES,
   plan as planFn
 } from "@dbsp/core";
+import { toColumnList as toColumnList12 } from "@dbsp/types";
 
 // src/adapter-compiler-select.ts
 init_assert_field();
@@ -14383,6 +14632,7 @@ init_ast_helpers();
 init_binding_registry();
 init_compile_where();
 import { countDistinctRelationPathsByName } from "@dbsp/core";
+import { toColumnList as toColumnList11 } from "@dbsp/types";
 init_compiler_utils();
 init_types();
 init_intent_to_decisions();
@@ -14392,6 +14642,7 @@ init_param_ref();
 init_assert_field();
 init_intent_to_decisions();
 import { deriveRelationPathFromIntentPath } from "@dbsp/core";
+import { toColumnList as toColumnList10 } from "@dbsp/types";
 function findExistsIntents(where) {
   if (!where || typeof where !== "object") return [];
   const w = where;
@@ -14412,7 +14663,8 @@ function findExistsIntents(where) {
 function resolveRelation(model, sourceTable, relationName) {
   const rel = model.getRelation(`${sourceTable}.${relationName}`);
   if (!rel) return void 0;
-  const foreignKey = typeof rel.foreignKey === "string" ? rel.foreignKey : rel.foreignKey?.[0];
+  const foreignKeyColumns = toColumnList10(rel.foreignKey);
+  const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
   const relationType = rel.type;
   return { target: rel.target, foreignKey, relationType };
 }
@@ -14635,7 +14887,8 @@ function buildMultiHopExistsChain(hops, rootTable, outerOperator, innerCondition
   const hopRelations = [];
   for (const hop of hops) {
     const rel = model.getRelation(`${currentSource}.${hop}`);
-    const foreignKey = rel ? typeof rel.foreignKey === "string" ? rel.foreignKey : rel.foreignKey?.[0] : void 0;
+    const foreignKeyColumns = rel ? toColumnList10(rel.foreignKey) : [];
+    const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
     const relationType = rel?.type === "belongsTo" ? "belongsTo" : rel?.type === "hasMany" || rel?.type === "hasOne" ? rel.type : void 0;
     const parentKey = relationType === "belongsTo" ? rel?.targetKey : rel?.sourceKey;
     const target = rel ? rel.target : hop;
@@ -14745,7 +14998,8 @@ function enrichExistsStubsInConditions(conditions, sourceTable, model) {
             `exists('${relation}'): no relation '${relation}' is declared on table '${sourceTable}'. Use rawExists(subquery(...)) for an EXISTS over an undeclared or uncorrelated subquery.`
           );
         }
-        const foreignKey = typeof rel.foreignKey === "string" ? rel.foreignKey : rel.foreignKey?.[0];
+        const foreignKeyColumns = toColumnList10(rel.foreignKey);
+        const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
         const relationType = rel.type === "belongsTo" ? "belongsTo" : rel.type === "hasMany" || rel.type === "hasOne" ? rel.type : void 0;
         const parentKey = relationType === "belongsTo" ? rel.targetKey : rel.sourceKey;
         const targetTable = rel.target;
@@ -14804,7 +15058,8 @@ function buildEnrichedExistsDecision(d, matchingIntent, rootTable, model) {
   const relIR = model && context.relation ? model.getRelation(
     `${sourceTableForRelation}.${context.relation}`
   ) : void 0;
-  const foreignKey = relIR ? typeof relIR.foreignKey === "string" ? relIR.foreignKey : relIR.foreignKey?.[0] : void 0;
+  const foreignKeyColumns = relIR ? toColumnList10(relIR.foreignKey) : [];
+  const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
   const relationType = relIR?.type === "belongsTo" ? "belongsTo" : relIR?.type === "hasMany" || relIR?.type === "hasOne" ? relIR.type : void 0;
   const parentKey = relationType === "belongsTo" ? relIR?.targetKey : relIR?.sourceKey;
   let operator = "exists";
@@ -15117,6 +15372,7 @@ function toIncludeDecision(d, choice, plan, defaultPk = DEFAULT_PK_COLUMN, deriv
   const relationName = resolveIncludeAlias(context);
   if (!context.target || !relationName) return void 0;
   const foreignKey = deriveForeignKey(context, deriveFk, defaultPk) ?? defaultPk;
+  const parentKey = context.parentKey ?? defaultPk;
   const relationType = context.relationType;
   const effectiveChoice = choice === "subquery" ? "json_agg" : choice;
   const includeIntent = resolveIncludeByPath(
@@ -15137,8 +15393,13 @@ function toIncludeDecision(d, choice, plan, defaultPk = DEFAULT_PK_COLUMN, deriv
     targetTable: context.target,
     ...context.sourceTable && { sourceTable: context.sourceTable },
     ...relationType && { relationType },
-    foreignKey: Array.isArray(foreignKey) ? foreignKey[0] : foreignKey,
-    parentKey: defaultPk,
+    foreignKey,
+    parentKey,
+    ...context.targetPrimaryKey && context.targetPrimaryKey.length > 0 ? {
+      targetPrimaryKey: context.targetPrimaryKey,
+      orderBy: context.targetPrimaryKey
+    } : {},
+    ...context.orderByFallback ? { orderByFallback: true } : {},
     ...context.intentPath && { intentPath: context.intentPath },
     ...limit != null && { limit }
   };
@@ -15164,6 +15425,7 @@ function toJoinIncludeDecision(d, plan, defaultPk = DEFAULT_PK_COLUMN, deriveFk
     columns = [defaultPk, ...fields];
   }
   const foreignKey = deriveForeignKey(context, deriveFk, defaultPk) ?? defaultPk;
+  const parentKey = context.parentKey ?? defaultPk;
   const relationType = context.relationType;
   let conditions;
   if (includeIntent?.where) {
@@ -15184,8 +15446,8 @@ function toJoinIncludeDecision(d, plan, defaultPk = DEFAULT_PK_COLUMN, deriveFk
     targetTable: context.target,
     ...context.sourceTable && { sourceTable: context.sourceTable },
     ...relationType && { relationType },
-    foreignKey: Array.isArray(foreignKey) ? foreignKey[0] : foreignKey,
-    parentKey: defaultPk,
+    foreignKey,
+    parentKey,
     columns,
     ...joinType && { joinType },
     ...conditions && { conditions }
@@ -15208,10 +15470,13 @@ function synthesizeMissingJoinDecisions(plan, coveredRelations, model, defaultPk
       (r) => r.name === alias || snakeToCamel(r.name) === alias
     );
     if (!rel) continue;
-    const rawFk = rel.foreignKey ? Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : rel.foreignKey : deriveFk(
-      rel.type === "belongsTo" ? rel.target : sourceTable,
-      defaultPk
-    );
+    const rawFkColumns = toColumnList10(rel.foreignKey);
+    const rawFk = rawFkColumns.length > 0 ? rawFkColumns : [
+      deriveFk(
+        rel.type === "belongsTo" ? rel.target : sourceTable,
+        defaultPk
+      )
+    ];
     let columns = [defaultPk];
     if (inc.select?.type === "fields" && inc.select.fields) {
       const extraFields = inc.select.fields.filter((f) => f !== defaultPk);
@@ -15232,8 +15497,8 @@ function synthesizeMissingJoinDecisions(plan, coveredRelations, model, defaultPk
       ...rel.type && {
         relationType: rel.type
       },
-      foreignKey: Array.isArray(rawFk) ? rawFk[0] : rawFk,
-      parentKey: defaultPk,
+      foreignKey: rawFk,
+      parentKey: rel.type === "belongsTo" ? toColumnList10(rel.targetKey).length > 0 ? toColumnList10(rel.targetKey) : [defaultPk] : toColumnList10(rel.sourceKey).length > 0 ? toColumnList10(rel.sourceKey) : [defaultPk],
       columns,
       joinType: inc.join,
       ...conditions && { conditions }
@@ -15390,9 +15655,12 @@ function compileJoinIntents(joins, rootTable, schemaName, deps) {
         );
       }
       const isBelongsTo = rel.type === "belongsTo";
-      const rawFk = rel.foreignKey ? Array.isArray(rel.foreignKey) ? rel.foreignKey[0] : rel.foreignKey : deriveFk(isBelongsTo ? rootTable : rel.target, defaultPk);
-      const sourceColumn = isBelongsTo ? rawFk : defaultPk;
-      const targetColumn = isBelongsTo ? defaultPk : rawFk;
+      const rawFk = toColumnList11(rel.foreignKey);
+      const fkColumns = rawFk.length > 0 ? rawFk : [deriveFk(isBelongsTo ? rootTable : rel.target, defaultPk)];
+      const sourceKey = toColumnList11(rel.sourceKey);
+      const targetKey = toColumnList11(rel.targetKey);
+      const sourceColumn = isBelongsTo ? fkColumns : sourceKey.length > 0 ? sourceKey : [defaultPk];
+      const targetColumn = isBelongsTo ? targetKey.length > 0 ? targetKey : [defaultPk] : fkColumns;
       const alias = intent.alias ?? intent.relation;
       results.push({
         type: "join",
@@ -15755,10 +16023,11 @@ function compileWithIncludes(plan, options, deps) {
     const relationName = ctx.includeAlias ?? ctx.relation;
     if (!relationName) continue;
     const rawFk = deriveForeignKey(ctx, deps.deriveFk, deps.defaultPk) ?? deps.defaultPk;
-    const fk = Array.isArray(rawFk) ? rawFk[0] : rawFk;
+    const fk = toColumnList11(rawFk);
+    const parentKey = toColumnList11(ctx.parentKey);
     const isBelongsTo = ctx.relationType === "belongsTo";
-    const sourceKey = isBelongsTo ? fk : "id";
-    const targetFk = isBelongsTo ? "id" : fk;
+    const sourceKey = isBelongsTo ? fk : parentKey.length > 0 ? parentKey : [deps.defaultPk];
+    const targetFk = isBelongsTo ? parentKey.length > 0 ? parentKey : [deps.defaultPk] : fk;
     const includeIntent = plan.intent?.include?.find(
       (i) => i.relation === relationName || i.relation === ctx.includeAlias
     );
@@ -15821,14 +16090,14 @@ function prependSourceCte(sql, parameters, sourceName, sourceCte, naming) {
   };
 }
 function resolveMutationExistsForeignKey(foreignKey, relationName) {
-  if (typeof foreignKey === "string") return foreignKey;
-  if (!Array.isArray(foreignKey)) return void 0;
-  if (foreignKey.length > 1) {
+  const columns = toColumnList12(foreignKey);
+  if (columns.length === 0) return void 0;
+  if (columns.some((column) => column.length === 0)) {
     throw new Error(
-      `Mutation exists()/notExists() guards do not support composite foreignKey relations yet: relation '${relationName}' has foreignKey ${JSON.stringify(foreignKey)}. Composite FK correlation is tracked by #179.`
+      `Mutation exists()/notExists() guard relation '${relationName}' has an empty foreignKey column.`
     );
   }
-  return foreignKey[0];
+  return columns;
 }
 function resolveExistsRelation(sourceTable, relation, model) {
   if (!model) return { targetTable: relation };
@@ -15841,13 +16110,13 @@ function resolveExistsRelation(sourceTable, relation, model) {
     return {
       targetTable,
       ...fk2 !== void 0 && { sourceColumn: fk2 },
-      targetColumn: "id"
+      targetColumn: toColumnList12(rel.targetKey).length > 0 ? toColumnList12(rel.targetKey) : ["id"]
     };
   }
   const fk = resolveMutationExistsForeignKey(rel.foreignKey, relationName);
   return {
     targetTable,
-    sourceColumn: rel.sourceKey ?? "id",
+    sourceColumn: toColumnList12(rel.sourceKey).length > 0 ? toColumnList12(rel.sourceKey) : ["id"],
     ...fk !== void 0 && { targetColumn: fk }
   };
 }
@@ -18086,7 +18355,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
         bundle.query.from,
         deps.naming
       );
-      const planReport = queryFromBinding ? createNqlBindingSelectPlan(bundle.query) : planFn2(bundle.query, this.requireNqlCompileModel(options), {
+      const planReport = queryFromBinding ? bundle.plan ?? createNqlBindingSelectPlan(bundle.query) : planFn2(bundle.query, this.requireNqlCompileModel(options), {
         dialectCapabilities: options?.dialectCapabilities ?? this.dialectCapabilities
       });
       return guardCompiledQuery(
@@ -18180,6 +18449,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
     }
     const leafBundle = {
       ...bundle.query !== void 0 && { query: bundle.query },
+      ...bundle.plan !== void 0 && { plan: bundle.plan },
       ...bundle.cteQuery !== void 0 && { cteQuery: bundle.cteQuery },
       ...bundle.mutation !== void 0 && { mutation: bundle.mutation },
       ...bundle.returning !== void 0 && { returning: bundle.returning },