@dbsp/adapter-pgsql 1.4.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({
@@ -1457,6 +1462,10 @@ var init_custom = __esm({
 });
 
 // src/select-expression-handlers.ts
+import {
+  getTrustedNqlRelationFilterFields,
+  markNqlTrustedRelationFilter
+} from "@dbsp/types/internal";
 function handleColumnExpression(expr, rootTable, decisions) {
   const decision = {
     type: "select",
@@ -1585,14 +1594,18 @@ function handleCaseExpression(expr, rootTable, decisions, _applyFilter, convertC
   decisions.push(decision);
 }
 function handleRelationColumnExpression(expr, rootTable, decisions) {
+  const trusted = getTrustedNqlRelationFilterFields(expr);
+  const trustedRelation = typeof trusted?.relation === "string" ? trusted.relation : trusted?.relation.join(".");
   const decision = {
     type: "selectRelationColumn",
-    relation: expr.relation,
-    column: expr.column ?? "*",
+    relation: trustedRelation ?? expr.relation,
+    column: trusted?.selectedColumn ?? (expr.column ?? "*"),
     table: rootTable
   };
   if (expr.as) decision.alias = expr.as;
-  decisions.push(decision);
+  decisions.push(
+    trusted?.selectedColumn !== void 0 ? markNqlTrustedRelationFilter(decision, trusted) : decision
+  );
 }
 function handleArithmeticExpression(expr, rootTable, decisions) {
   const decision = {
@@ -1690,6 +1703,9 @@ var init_select_expression_handlers = __esm({
 
 // src/intent-to-decisions.ts
 import { isParamIntent } from "@dbsp/types";
+import {
+  getTrustedNqlRelationFilterFields as getTrustedNqlRelationFilterFields2
+} from "@dbsp/types/internal";
 function intentToDecisions(intent, rootTable) {
   const decisions = [];
   if (intent.select) {
@@ -2075,10 +2091,29 @@ function convertNot(cond, rootTable) {
   if (!subDecision) return null;
   return { type: "whereNot", conditions: [subDecision] };
 }
+function formatRelationName(relation) {
+  return typeof relation === "string" ? relation : relation.join(".");
+}
 function convertExistsLike(cond, operator) {
-  const targetTable = cond.relation;
+  const rawRelation = cond.relation;
+  const preResolved = getTrustedNqlRelationFilterFields2(cond);
+  const trustedRelation = preResolved?.relation;
+  const relationName = trustedRelation !== void 0 ? formatRelationName(trustedRelation) : formatRelationName(rawRelation);
+  const targetTable = preResolved?.targetTable ?? rawRelation;
   const subDecisions = cond.where ? convertWhere(cond.where, targetTable) : [];
-  const base = { type: "where", operator, targetTable };
+  const isPreResolved = preResolved !== void 0;
+  const base = {
+    type: "where",
+    operator,
+    targetTable,
+    ...preResolved !== void 0 && {
+      sourceColumn: preResolved.sourceColumn
+    },
+    ...preResolved !== void 0 && {
+      targetColumn: preResolved.targetColumn
+    },
+    ...isPreResolved && { relationName }
+  };
   return subDecisions.length > 0 ? { ...base, conditions: subDecisions } : base;
 }
 function convertSubquery(cond) {
@@ -3142,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",
@@ -3158,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);
@@ -3169,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");
   }
@@ -3181,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,
@@ -3219,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) {
@@ -3238,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(
@@ -3744,6 +3811,8 @@ 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 {
     naming: ctx.naming,
@@ -3937,11 +4006,16 @@ function handleSubqueryIntent(intent, ctx, _handlerCtx) {
 }
 function handleRelationFilterIntent(intent, ctx) {
   const rf = intent;
-  const hops = Array.isArray(rf.relation) ? rf.relation : [rf.relation];
+  const preResolved = getTrustedNqlRelationFilterFields3(rf);
+  const relationPath = preResolved?.relation ?? rf.relation;
+  const hops = Array.isArray(relationPath) ? [...relationPath] : [relationPath];
   const existsKind = rf.mode === "none" || rf.mode === "every" ? "notExists" : "exists";
   const rfWhere = rf.where;
   const isVacuousEvery = rf.mode === "every" && (!rfWhere || typeof rfWhere === "object" && rfWhere.kind === "and" && Array.isArray(rfWhere.conditions) && rfWhere.conditions.length === 0);
   if (isVacuousEvery) {
+    if (preResolved) {
+      return { A_Const: { boolval: { boolval: true } } };
+    }
     if (hops.length <= 1) {
       const relation = hops[0] ?? rf.relation;
       if (!ctx.model) {
@@ -3977,6 +4051,19 @@ function handleRelationFilterIntent(intent, ctx) {
   const innermostWhere = rf.mode === "every" ? { kind: "not", condition: rf.where } : rf.where;
   if (hops.length <= 1) {
     const relation = hops[0] ?? rf.relation;
+    if (preResolved) {
+      return compileWhereIntent(
+        {
+          kind: existsKind,
+          relation,
+          targetTable: preResolved.targetTable,
+          sourceColumn: preResolved.sourceColumn,
+          targetColumn: preResolved.targetColumn,
+          where: innermostWhere
+        },
+        ctx
+      );
+    }
     const resolvedRelation = ctx.model?.getRelation(
       `${ctx.rootTable}.${relation}`
     );
@@ -3990,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(
@@ -4034,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;
@@ -4270,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";
@@ -4281,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");
   }
@@ -4297,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",
@@ -4334,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) {
@@ -4763,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) => ({
@@ -4813,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: {
@@ -4842,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) {
@@ -4898,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",
@@ -4919,6 +5024,7 @@ var init_join = __esm({
     "use strict";
     init_assert_field();
     init_ast_helpers();
+    init_exists();
     joinIncludeHandler = {
       strategy: "join",
       compile(decision, ctx, _state) {
@@ -4929,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,
@@ -4991,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;
@@ -5007,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) {
@@ -5043,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,
@@ -5053,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 }
     }
   );
 }
@@ -5062,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",
@@ -5083,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) => ({
@@ -5094,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 = {
@@ -5179,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,
@@ -7180,9 +7312,14 @@ 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, isNqlBindingRef } from "@dbsp/types/internal";
+import {
+  getNqlBindingRefName,
+  getTrustedNqlRelationFilterFields as getTrustedNqlRelationFilterFields4,
+  isNqlBindingRef
+} from "@dbsp/types/internal";
 
 // src/pgsql-deparser.ts
 function deparse(node) {
@@ -8246,6 +8383,7 @@ init_window();
 init_include();
 init_shared();
 init_handlers();
+init_exists();
 init_types();
 init_utils();
 init_intent_to_decisions();
@@ -8283,7 +8421,27 @@ 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,
+    defaultPk,
+    deriveFk
+  );
   return {
     type: pd.type,
     table: pd.table,
@@ -8294,7 +8452,8 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     paramIndex: pd.paramIndex,
     direction: pd.direction,
     joinType: pd.joinType,
-    ...deriveFkColumns(pd, pd.sourceTable ?? rootTable, defaultPk, deriveFk),
+    sourceColumn: pd.sourceColumn ?? derivedFkColumns.sourceColumn,
+    targetColumn: pd.targetColumn ?? derivedFkColumns.targetColumn,
     targetTable: pd.targetTable,
     function: pd.function,
     args: pd.args,
@@ -8311,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,
@@ -8325,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"
     })),
@@ -8488,6 +8649,8 @@ var PlanCompiler = class _PlanCompiler {
   rawJoins = [];
   /** CTE nodes from include handlers (e.g., CTE strategy) */
   pendingCtes = [];
+  /** Local aliases for binding relation-column scalar subqueries. */
+  bindingRelationColumnSubqueryIndex = 0;
   /**
    * Maps relation-dotted include path → JOIN alias for multi-hop FK resolution.
    * Populated as join decisions are compiled so later hops can find the
@@ -8705,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
     );
@@ -8875,6 +9045,162 @@ var PlanCompiler = class _PlanCompiler {
       this.naming
     );
   }
+  isNqlBindingRoot(plan) {
+    return hasBindingName(this.bindingNames, plan.rootTable, this.naming);
+  }
+  buildCorrelatedRelationRefs(fields, plan) {
+    const relatedAlias = `rc_${this.bindingRelationColumnSubqueryIndex++}`;
+    const relatedTable = rangeVar(
+      fields.targetTable,
+      relatedAlias,
+      this.schemaForRangeVar(plan, fields.targetTable),
+      this.naming
+    );
+    const relatedColumn = columnRef(
+      fields.selectedColumn,
+      relatedAlias,
+      void 0,
+      this.naming
+    );
+    return {
+      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 = {
@@ -9252,6 +9578,28 @@ var PlanCompiler = class _PlanCompiler {
       case "selectRelationColumn":
       case "selectPseudoColumn":
       case "selectArithmetic": {
+        if (decision.type === "selectRelationColumn") {
+          const trusted = getTrustedNqlRelationFilterFields4(decision);
+          if (trusted?.selectedColumn !== void 0) {
+            const node2 = this.compileBindingRelationColumnSubquery(
+              trusted,
+              plan,
+              this.dialectCapabilities
+            );
+            targetList.push({
+              ResTarget: {
+                val: node2,
+                ...decision.alias ? { name: this.naming.toDatabase(decision.alias) } : {}
+              }
+            });
+            break;
+          }
+          if (this.isNqlBindingRoot(plan)) {
+            throw new Error(
+              `NQL binding-final query '${plan.rootTable}' cannot select relation column '${decision.relation ?? "unknown"}.${decision.column ?? "unknown"}' without a trusted compiler proof.`
+            );
+          }
+        }
         ensureExpressionHandlersRegistered();
         const exprType = decision.type === "selectRelationColumn" ? "relationColumn" : decision.type === "selectPseudoColumn" ? "pseudoColumn" : "arithmetic";
         const handler = getExpressionHandler(exprType);
@@ -9973,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,
@@ -9999,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);
@@ -13129,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, {
@@ -13137,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",
@@ -13153,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",
@@ -14055,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;
@@ -14066,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,
@@ -14114,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]);
@@ -14154,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++;
@@ -14243,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();
@@ -14250,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();
@@ -14259,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;
@@ -14279,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 };
 }
@@ -14502,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;
@@ -14612,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;
@@ -14671,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";
@@ -14984,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(
@@ -15004,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 }
   };
@@ -15031,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) {
@@ -15051,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 }
@@ -15075,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);
@@ -15099,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 }
@@ -15257,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",
@@ -15622,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
     );
@@ -15688,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 };
@@ -15708,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 }
   };
 }
@@ -17953,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(
@@ -18047,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 },