@dbsp/adapter-pgsql 1.5.0 → 1.7.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);
 }
@@ -669,9 +663,6 @@ function funcCall(name, args = [], options = {}) {
 function coalesceExpr(args) {
   return { CoalesceExpr: { args } };
 }
-function coalesce(...args) {
-  return funcCall("coalesce", args);
-}
 function sortBy(expr, direction = "DEFAULT", nulls = "DEFAULT") {
   const sb = {
     node: expr,
@@ -885,10 +876,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 +927,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 +3174,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 +3191,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 +3219,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 +3235,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 +3273,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 +3292,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 +3808,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 +4074,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 +4120,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 +4360,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 +4372,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 +4391,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 +4431,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) {
@@ -4434,6 +4483,11 @@ var init_relation_filter = __esm({
 
 // src/subquery-emission.ts
 import { isParamIntent as isParamIntent5 } from "@dbsp/types";
+function isColumnOrderBy(orderBy) {
+  return Array.isArray(orderBy) && orderBy.every(
+    (item) => typeof item === "object" && item !== null && "column" in item && typeof item.column === "string"
+  );
+}
 function assertNoDroppedDecisionModifiers(decision, use) {
   const d = decision;
   const unsupported = [];
@@ -4552,8 +4606,9 @@ function buildPredicateSubquerySelect(use, sourceIntent, decision, ctx, state, d
     ],
     ...whereClause && { whereClause }
   };
-  if (decision.orderBy && decision.orderBy.length > 0) {
-    stmt.sortClause = decision.orderBy.map(
+  const orderBy = isColumnOrderBy(decision.orderBy) ? decision.orderBy : void 0;
+  if (orderBy && orderBy.length > 0) {
+    stmt.sortClause = orderBy.map(
       (o) => sortBy(
         columnRef(o.column, targetAlias, void 0, ctx.naming),
         o.direction ?? "ASC",
@@ -4812,6 +4867,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 +4918,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 +4947,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 +5005,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 +5027,7 @@ var init_join = __esm({
     "use strict";
     init_assert_field();
     init_ast_helpers();
+    init_exists();
     joinIncludeHandler = {
       strategy: "join",
       compile(decision, ctx, _state) {
@@ -4978,15 +5038,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 +5101,22 @@ var init_shared = __esm({
 });
 
 // src/handlers/include/json-agg.ts
+import { resolveJsonAggOrderKey } from "@dbsp/types";
+function isJsonAggOrderBy(orderBy) {
+  return Array.isArray(orderBy) && orderBy.every((item) => typeof item === "string");
+}
+function resolveJsonAggOrderBy(decision, targetTable, ctx) {
+  const table = ctx.model?.getTable(targetTable);
+  if (table) {
+    const orderKey = resolveJsonAggOrderKey(table);
+    return orderKey.columns.length > 0 ? orderKey : void 0;
+  }
+  const decisionOrderBy = isJsonAggOrderBy(decision.orderBy) ? decision.orderBy : void 0;
+  return decisionOrderBy && decisionOrderBy.length > 0 ? {
+    columns: decisionOrderBy,
+    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 +5133,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 +5169,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 +5180,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 +5191,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 +5213,7 @@ var init_json_agg = __esm({
 });
 
 // src/handlers/include/lateral.ts
+import { toColumnList as toColumnList6 } from "@dbsp/types";
 function buildLateralTargets(columns, alias, ctx) {
   if (columns && columns.length > 0 && !(columns.length === 1 && columns[0] === "*")) {
     return columns.map((col) => ({
@@ -5143,12 +5225,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 +5310,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 = toColumnList6(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,
@@ -6184,6 +6270,7 @@ function buildRecursiveScalarSubquery(config) {
     pkColumn,
     fkColumn,
     outerAlias,
+    outerSeedColumn,
     isAncestors,
     maxDepth,
     selectColumn,
@@ -6194,6 +6281,9 @@ function buildRecursiveScalarSubquery(config) {
   const dbPk = naming.toDatabase(pkColumn);
   const dbFk = naming.toDatabase(fkColumn);
   const dbOuter = naming.toDatabase(outerAlias);
+  const dbOuterSeed = naming.toDatabase(
+    outerSeedColumn ?? (isAncestors ? fkColumn : pkColumn)
+  );
   const innerAlias = "__n";
   const anchorSelect = {
     targetList: [
@@ -6262,7 +6352,7 @@ function buildRecursiveScalarSubquery(config) {
           ColumnRef: {
             fields: [
               { String: { sval: dbOuter } },
-              { String: { sval: dbFk } }
+              { String: { sval: dbOuterSeed } }
             ]
           }
         }
@@ -6282,7 +6372,7 @@ function buildRecursiveScalarSubquery(config) {
           ColumnRef: {
             fields: [
               { String: { sval: dbOuter } },
-              { String: { sval: dbPk } }
+              { String: { sval: dbOuterSeed } }
             ]
           }
         }
@@ -6346,15 +6436,7 @@ function buildRecursiveScalarSubquery(config) {
       }
     ],
     fromClause: [
-      // FROM __rc
-      {
-        RangeVar: {
-          relname: cteAlias,
-          inh: true,
-          relpersistence: "p"
-        }
-      },
-      // INNER JOIN table AS __n
+      // FROM __rc INNER JOIN table AS __n
       {
         JoinExpr: {
           jointype: "JOIN_INNER",
@@ -6437,7 +6519,7 @@ function buildRecursiveScalarSubquery(config) {
             },
             integerNode(maxDepth)
           ),
-          // pk <> ALL(__visited) — cycle detection
+          // pk <> ALL(__visited) - cycle detection
           {
             A_Expr: {
               kind: "AEXPR_OP_ALL",
@@ -6482,20 +6564,35 @@ function buildRecursiveScalarSubquery(config) {
     targetList: [
       {
         ResTarget: {
-          val: coalesce(
-            funcCall("json_agg", [
-              {
-                ColumnRef: {
-                  fields: [
-                    { String: { sval: cteAlias } },
-                    { String: { sval: dbSelectCol } }
-                  ]
+          val: coalesceExpr([
+            funcCall(
+              "json_agg",
+              [
+                {
+                  ColumnRef: {
+                    fields: [
+                      { String: { sval: cteAlias } },
+                      { String: { sval: dbSelectCol } }
+                    ]
+                  }
                 }
+              ],
+              {
+                orderBy: [
+                  sortBy({
+                    ColumnRef: {
+                      fields: [
+                        { String: { sval: cteAlias } },
+                        { String: { sval: "__depth" } }
+                      ]
+                    }
+                  })
+                ]
               }
-            ]),
+            ),
             // Empty array fallback: '[]'::json
-            typeCast(stringNode("[]"), "json")
-          )
+            typeCast({ A_Const: { sval: { sval: "[]" } } }, "json")
+          ])
         }
       }
     ],
@@ -6954,6 +7051,11 @@ var init_relation = __esm({
 });
 
 // src/handlers/expression/window.ts
+function isWindowOrderBy(orderBy) {
+  return Array.isArray(orderBy) && orderBy.every(
+    (item) => typeof item === "object" && item !== null && "column" in item && typeof item.column === "string"
+  );
+}
 function buildSortBy(column, direction, ctx) {
   const tableAlias = ctx.currentAlias ?? ctx.rootTable;
   const colRef = columnRef(column, tableAlias, void 0, ctx.naming);
@@ -6966,7 +7068,7 @@ function buildSortBy(column, direction, ctx) {
 }
 function buildWindowDef(decision, ctx) {
   const partition = decision.partition;
-  const orderBy = decision.orderBy;
+  const orderBy = isWindowOrderBy(decision.orderBy) ? decision.orderBy : void 0;
   const frame = decision.frame;
   const tableAlias = ctx.currentAlias ?? ctx.rootTable;
   const windowDef = { frameOptions: WINDOW_FRAME_DEFAULT };
@@ -7229,7 +7331,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 toColumnList7
 } from "@dbsp/types";
 import {
   getNqlBindingRefName,
@@ -8295,10 +8398,12 @@ init_case_value();
 init_custom();
 init_expression();
 init_param_value();
+init_pseudo();
 init_window();
 init_include();
 init_shared();
 init_handlers();
+init_exists();
 init_types();
 init_utils();
 init_intent_to_decisions();
@@ -8336,7 +8441,25 @@ function assertNqlSelectWindowFunctionAllowed(functionName) {
     throw new UnsupportedNqlSelectFunctionError(functionName);
   }
 }
+function trustedRelationHasMultipleHops(relation) {
+  if (typeof relation !== "string") return relation.length > 1;
+  return relation.split(".").length > 1;
+}
+function isJsonAggOrderBy2(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 = isJsonAggOrderBy2(pd.orderBy) ? pd.orderBy : void 0;
+  const expressionOrderBy = isExpressionOrderBy(pd.orderBy) ? pd.orderBy : void 0;
+  const handlerOrderBy = jsonAggOrderBy ?? expressionOrderBy?.map((o) => ({
+    column: o.field,
+    direction: o.direction?.toUpperCase() ?? "ASC"
+  }));
   const derivedFkColumns = deriveFkColumns(
     pd,
     pd.sourceTable ?? rootTable,
@@ -8371,6 +8494,7 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     relationType: pd.relationType,
     foreignKey: pd.foreignKey,
     parentKey: pd.parentKey,
+    orderByFallback: pd.orderByFallback,
     dataType: pd.dataType,
     traversal: pd.traversal,
     pkColumn: pd.pkColumn,
@@ -8385,10 +8509,7 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     include: pd.include?.map(
       (c) => mapToHandlerDecision(c, rootTable, defaultPk, deriveFk)
     ),
-    orderBy: pd.orderBy?.map((o) => ({
-      column: o.field,
-      direction: o.direction?.toUpperCase() ?? "ASC"
-    })),
+    orderBy: handlerOrderBy,
     partition: pd.partitionBy,
     jsonPath: pd.jsonPath,
     jsonMode: pd.jsonMode,
@@ -8767,6 +8888,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,18 +9068,11 @@ 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"}).`
-      );
-    }
-    const relatedAlias = `rc_${this.bindingRelationColumnSubqueryIndex++}`;
+  allocateBindingRelationAlias() {
+    return `rc_${this.bindingRelationColumnSubqueryIndex++}`;
+  }
+  buildCorrelatedRelationRefs(fields, plan) {
+    const relatedAlias = this.allocateBindingRelationAlias();
     const relatedTable = rangeVar(
       fields.targetTable,
       relatedAlias,
@@ -8964,28 +9085,255 @@ var PlanCompiler = class _PlanCompiler {
       void 0,
       this.naming
     );
-    const relatedJoinColumn = columnRef(
-      fields.targetColumn,
+    return {
       relatedAlias,
-      void 0,
-      this.naming
-    );
-    const bindingJoinColumn = columnRef(
-      fields.sourceColumn,
-      plan.rootTable,
-      void 0,
-      this.naming
+      relatedTable,
+      relatedColumn
+    };
+  }
+  bindingRelationHasCompleteManyToManyProof(fields) {
+    return (fields.relationType === "manyToMany" || fields.relationType === "belongsToMany") && fields.through !== void 0 && fields.throughSourceColumn !== void 0 && fields.throughTargetColumn !== void 0;
+  }
+  bindingRelationName(fields) {
+    return typeof fields.relation === "string" ? fields.relation : fields.relation.join(".");
+  }
+  bindingRelationNameLooksRecursive(fields) {
+    const relationName = this.bindingRelationName(fields).toLowerCase();
+    return relationName === "ascendant" || relationName === "descendant";
+  }
+  compileBindingRecursiveRelationColumnSubquery(fields, plan, dialectCapabilities) {
+    const recursive = fields.recursive;
+    if (recursive === void 0) {
+      throw new Error(
+        `NQL binding recursive relation-column proof for '${plan.rootTable}' is missing recursive metadata.`
+      );
+    }
+    if (fields.cardinality !== "many") {
+      throw new Error(
+        `NQL binding recursive relation-column proof for '${plan.rootTable}' must use cardinality 'many'.`
+      );
+    }
+    if (fields.sourceColumn.length !== 1) {
+      throw new Error(
+        `NQL binding recursive relation-column proof for '${plan.rootTable}' must carry exactly one projected seed column.`
+      );
+    }
+    if (dialectCapabilities?.supportsRecursiveCTE === false) {
+      throw new Error(
+        `Recursive NQL binding relation columns require a dialect with supportsRecursiveCTE; current dialect (${dialectCapabilities.name}) declared it unsupported.`
+      );
+    }
+    assertDialectCapability(
+      dialectCapabilities,
+      "supportsJsonAgg",
+      "JSON aggregation for NQL binding relation columns is"
     );
-    return {
-      SubLink: {
-        subLinkType: "EXPR_SUBLINK",
-        subselect: selectStmt({
-          targetList: [{ ResTarget: { val: relatedColumn } }],
-          from: [relatedTable],
-          where: eqExpr(relatedJoinColumn, bindingJoinColumn)
-        })
+    const seedColumn = fields.sourceColumn[0];
+    if (!seedColumn) {
+      throw new Error(
+        `NQL binding recursive relation-column proof for '${plan.rootTable}' is missing its projected seed column.`
+      );
+    }
+    const relatedAlias = this.allocateBindingRelationAlias();
+    return buildRecursiveScalarSubquery({
+      cteAlias: `__${relatedAlias}`,
+      table: fields.targetTable,
+      pkColumn: recursive.targetKeyColumn,
+      fkColumn: recursive.selfRefColumn,
+      outerAlias: plan.rootTable,
+      outerSeedColumn: seedColumn,
+      isAncestors: recursive.direction === "up",
+      maxDepth: recursive.maxDepth,
+      selectColumn: fields.selectedColumn,
+      ctx: this.createHandlerContext(plan, plan.rootTable)
+    });
+  }
+  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.recursive !== void 0) {
+      return this.compileBindingRecursiveRelationColumnSubquery(
+        fields,
+        plan,
+        dialectCapabilities
+      );
+    }
+    if (this.bindingRelationNameLooksRecursive(fields)) {
+      throw new Error(
+        `NQL binding recursive relation-column proof for '${plan.rootTable}' is missing recursive metadata.`
+      );
+    }
+    const isManyToManyRelation = fields.relationType === "manyToMany" || fields.relationType === "belongsToMany";
+    const hasCompleteManyToManyProof = this.bindingRelationHasCompleteManyToManyProof(fields);
+    if (isManyToManyRelation && (fields.cardinality !== "many" || !hasCompleteManyToManyProof)) {
+      if (fields.cardinality !== "many") {
+        throw new Error(
+          `NQL binding relation-column proof for '${plan.rootTable}' is manyToMany but must use cardinality 'many' with complete junction proof (through, throughSourceColumn, throughTargetColumn) (ref-#192).`
+        );
       }
-    };
+      throw new Error(
+        `NQL binding relation-column proof for '${plan.rootTable}' is manyToMany but missing complete junction proof (through, throughSourceColumn, throughTargetColumn) (ref-#192).`
+      );
+    }
+    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" && fields.relationType !== "manyToMany" && fields.relationType !== "belongsToMany") {
+        throw new Error(
+          `NQL binding relation-column proof for '${plan.rootTable}' has cardinality 'many' but relationType '${fields.relationType ?? "unknown"}' is not supported; only hasMany or manyToMany can be aggregated (ref-#192).`
+        );
+      }
+      if ((fields.relationType === "manyToMany" || fields.relationType === "belongsToMany") && !hasCompleteManyToManyProof) {
+        throw new Error(
+          `NQL binding relation-column proof for '${plan.rootTable}' is manyToMany but missing complete junction proof (through, throughSourceColumn, throughTargetColumn) (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);
+      const junctionAlias = hasCompleteManyToManyProof ? this.allocateBindingRelationAlias() : void 0;
+      const handlerContext = this.createHandlerContext(plan);
+      const fromNode = hasCompleteManyToManyProof ? innerJoin(
+        relatedTable,
+        rangeVar(
+          fields.through,
+          junctionAlias,
+          this.schemaForRangeVar(plan, fields.through),
+          this.naming
+        ),
+        buildKeyCorrelation(
+          relatedAlias,
+          fields.targetColumn,
+          junctionAlias,
+          [fields.throughTargetColumn],
+          handlerContext
+        )
+      ) : relatedTable;
+      const whereNode = hasCompleteManyToManyProof ? buildKeyCorrelation(
+        junctionAlias,
+        [fields.throughSourceColumn],
+        plan.rootTable,
+        fields.sourceColumn,
+        handlerContext
+      ) : buildKeyCorrelation(
+        relatedAlias,
+        fields.targetColumn,
+        plan.rootTable,
+        fields.sourceColumn,
+        handlerContext
+      );
+      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: [fromNode],
+            where: whereNode
+          })
+        }
+      };
+    }
+    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());
@@ -9369,7 +9717,8 @@ var PlanCompiler = class _PlanCompiler {
           if (trusted?.selectedColumn !== void 0) {
             const node2 = this.compileBindingRelationColumnSubquery(
               trusted,
-              plan
+              plan,
+              this.dialectCapabilities
             );
             targetList.push({
               ResTarget: {
@@ -10106,12 +10455,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 +10491,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 = toColumnList7(decision.sourceColumn);
+    const targetColumn = toColumnList7(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);
@@ -10570,6 +10931,12 @@ function buildSequenceClause(verb, seqName, seq, includeCycleNoCycle = false) {
   }
   return `${parts.join(" ")};`;
 }
+function failSafeUnknownDownChange(kind) {
+  return {
+    sql: `-- WARNING: Cannot reverse unsupported SchemaChange kind "${kind}"`,
+    destructive: true
+  };
+}
 function isChangeSupported(kind, caps) {
   switch (kind) {
     case "create_enum":
@@ -11022,188 +11389,381 @@ function changeToUpSQL(change, schemaName) {
 function changeToDownSQL(change, schemaName) {
   switch (change.kind) {
     case "create_table":
-      return `DROP TABLE IF EXISTS ${qualifyTable(change.table, schemaName)} CASCADE;`;
+      return {
+        sql: `DROP TABLE IF EXISTS ${qualifyTable(change.table, schemaName)} CASCADE;`,
+        destructive: true
+      };
     case "drop_table":
-      return `-- WARNING: Cannot reverse drop_table "${change.table}" -- table data was lost`;
+      return {
+        sql: `-- WARNING: Cannot reverse drop_table "${change.table}" -- table data was lost`,
+        destructive: true
+      };
     case "add_column":
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP COLUMN ${quoteIdent2(change.column, "alias")} CASCADE;`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP COLUMN ${quoteIdent2(change.column, "alias")} CASCADE;`,
+        destructive: true
+      };
     case "drop_column":
-      return `-- WARNING: Cannot reverse drop_column "${change.table}"."${change.column}" -- column data was lost`;
+      return {
+        sql: `-- WARNING: Cannot reverse drop_column "${change.table}"."${change.column}" -- column data was lost`,
+        destructive: true
+      };
     case "alter_column_type": {
       const fromType = change.meta?.fromType;
       if (!fromType) {
-        return `-- WARNING: Cannot reverse alter_column_type "${change.table}"."${change.column}" -- missing migration metadata`;
+        return {
+          sql: `-- WARNING: Cannot reverse alter_column_type "${change.table}"."${change.column}" -- missing migration metadata`,
+          destructive: true
+        };
       }
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} TYPE ${fromType};`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} TYPE ${fromType};`,
+        destructive: true
+      };
     }
     case "alter_column_nullable": {
       const oldNullable = change.meta?.oldNullable;
       if (oldNullable === void 0) {
-        return `-- WARNING: Cannot reverse alter_column_nullable "${change.table}"."${change.column}" -- missing migration metadata`;
+        return {
+          sql: `-- WARNING: Cannot reverse alter_column_nullable "${change.table}"."${change.column}" -- missing migration metadata`,
+          destructive: true
+        };
       }
       const action = oldNullable ? "DROP NOT NULL" : "SET NOT NULL";
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} ${action};`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} ${action};`,
+        // Allowlisted: restores the recorded prior nullability metadata.
+        destructive: false
+      };
     }
     case "alter_column_default": {
       const oldDefault = change.meta?.oldDefault;
       if (oldDefault === void 0) {
-        return `-- WARNING: Cannot reverse alter_column_default "${change.table}"."${change.column}" -- missing migration metadata`;
+        return {
+          sql: `-- WARNING: Cannot reverse alter_column_default "${change.table}"."${change.column}" -- missing migration metadata`,
+          destructive: true
+        };
       }
       if (oldDefault === null) {
-        return `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} DROP DEFAULT;`;
+        return {
+          sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} DROP DEFAULT;`,
+          // Allowlisted: restores the recorded prior state of "no default".
+          destructive: false
+        };
       }
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} SET DEFAULT ${formatDefault(oldDefault)};`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ALTER COLUMN ${quoteIdent2(change.column, "alias")} SET DEFAULT ${formatDefault(oldDefault)};`,
+        // Allowlisted: restores the recorded prior default value.
+        destructive: false
+      };
     }
     case "add_primary_key": {
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${quoteIdent2(pkName(change.table), "alias")} CASCADE;`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${quoteIdent2(pkName(change.table), "alias")} CASCADE;`,
+        destructive: true
+      };
+    }
+    case "drop_primary_key": {
+      const columns = change.meta?.columns;
+      if (Array.isArray(columns) && columns.length > 0) {
+        const pkCols = columns.map((n) => quoteIdent2(n, "alias")).join(", ");
+        return {
+          sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ADD CONSTRAINT ${quoteIdent2(pkName(change.table), "alias")} PRIMARY KEY (${pkCols});`,
+          // Allowlisted: re-adds the dropped primary-key constraint from metadata.
+          destructive: false
+        };
+      }
+      return {
+        sql: `-- WARNING: Cannot reverse drop_primary_key "${change.table}" -- columns unknown`,
+        destructive: true
+      };
     }
-    case "drop_primary_key":
-      return `-- WARNING: Cannot reverse drop_primary_key "${change.table}" -- columns unknown`;
     case "add_foreign_key": {
       const fk = change.meta?.fk;
-      if (!fk) return void 0;
+      if (!fk) return { sql: void 0, destructive: true };
       const constraintName = quoteIdent2(
         fkName(change.table, fk.columns),
         "alias"
       );
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${constraintName} CASCADE;`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${constraintName} CASCADE;`,
+        destructive: true
+      };
+    }
+    case "drop_foreign_key": {
+      const fk = change.meta?.fk;
+      if (!fk) {
+        return {
+          sql: `-- WARNING: Cannot reverse drop_foreign_key "${change.table}" -- FK definition was lost`,
+          destructive: true
+        };
+      }
+      return {
+        sql: generateAddFKSQL(change.table, fk, schemaName),
+        // Allowlisted: re-adds the dropped foreign-key constraint from metadata.
+        destructive: false
+      };
     }
-    case "drop_foreign_key":
-      return `-- WARNING: Cannot reverse drop_foreign_key "${change.table}" -- FK definition was lost`;
     case "alter_foreign_key": {
       const oldFk = change.meta?.oldFk;
-      if (!oldFk) {
-        return `-- WARNING: Cannot reverse alter_foreign_key "${change.table}" -- missing migration metadata`;
-      }
       const fk = change.meta?.fk;
+      if (!oldFk || !fk) {
+        return {
+          sql: `-- WARNING: Cannot reverse alter_foreign_key "${change.table}" -- missing migration metadata`,
+          destructive: true
+        };
+      }
       const constraintName = quoteIdent2(
         fkName(change.table, fk.columns),
         "alias"
       );
       const drop = `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${constraintName};`;
       const add = generateAddFKSQL(change.table, oldFk, schemaName);
-      return `${drop}
-${add}`;
+      return { sql: `${drop}
+${add}`, destructive: false };
     }
     case "create_index": {
       const idx = change.meta?.index;
-      if (!idx) return void 0;
+      if (!idx) return { sql: void 0, destructive: true };
       const indexName = quoteIdent2(
         idxName(change.table, idx.columns, idx.name),
         "alias"
       );
       const schemaPrefix = schemaName ? `${quoteIdent2(schemaName, "alias")}.` : "";
-      return `DROP INDEX IF EXISTS ${schemaPrefix}${indexName};`;
+      return {
+        sql: `DROP INDEX IF EXISTS ${schemaPrefix}${indexName};`,
+        destructive: true
+      };
+    }
+    case "drop_index": {
+      const idx = change.meta?.index;
+      if (!idx) {
+        return {
+          sql: `-- WARNING: Cannot reverse drop_index "${change.table}" -- index definition was lost`,
+          destructive: true
+        };
+      }
+      return {
+        sql: upCreateIndex(change, schemaName),
+        // Allowlisted: re-creates the dropped index from metadata.
+        destructive: false
+      };
     }
-    case "drop_index":
-      return `-- WARNING: Cannot reverse drop_index "${change.table}" -- index definition was lost`;
     case "add_check_constraint": {
       const check = change.meta?.check;
-      if (!check) return void 0;
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${quoteIdent2(check.name, "alias")};`;
+      if (!check) return { sql: void 0, destructive: true };
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} DROP CONSTRAINT IF EXISTS ${quoteIdent2(check.name, "alias")};`,
+        destructive: true
+      };
     }
     case "drop_check_constraint": {
       const check = change.meta?.check;
-      if (!check) return void 0;
+      if (!check) return { sql: void 0, destructive: true };
       validateSqlExpression(
         check.expression,
         "migration check constraint (down)"
       );
-      return "DO $$ BEGIN ALTER TABLE " + qualifyTable(change.table, schemaName) + " ADD CONSTRAINT " + quoteIdent2(check.name, "alias") + " " + check.expression + "; EXCEPTION WHEN duplicate_object THEN NULL; END $$;";
+      return {
+        sql: "DO $$ BEGIN ALTER TABLE " + qualifyTable(change.table, schemaName) + " ADD CONSTRAINT " + quoteIdent2(check.name, "alias") + " " + check.expression + "; EXCEPTION WHEN duplicate_object THEN NULL; END $$;",
+        // Allowlisted: re-adds the dropped CHECK constraint from metadata.
+        destructive: false
+      };
     }
     case "create_enum": {
       const enumDef = change.meta?.enum;
-      if (!enumDef) return void 0;
+      if (!enumDef) return { sql: void 0, destructive: true };
       const enumName = schemaName ? `${quoteIdent2(schemaName, "alias")}.${quoteIdent2(enumDef.name, "alias")}` : quoteIdent2(enumDef.name, "alias");
-      return `DROP TYPE IF EXISTS ${enumName} CASCADE;`;
+      return {
+        sql: `DROP TYPE IF EXISTS ${enumName} CASCADE;`,
+        destructive: true
+      };
     }
     case "drop_enum": {
       const enumDef = change.meta?.enum;
-      if (!enumDef) return void 0;
+      if (!enumDef) return { sql: void 0, destructive: true };
       const enumName = schemaName ? `${quoteIdent2(schemaName, "alias")}.${quoteIdent2(enumDef.name, "alias")}` : quoteIdent2(enumDef.name, "alias");
       const values = enumDef.values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
-      return `CREATE TYPE ${enumName} AS ENUM (${values});`;
+      return {
+        sql: `CREATE TYPE ${enumName} AS ENUM (${values});`,
+        // Allowlisted: re-creates the dropped enum type from metadata.
+        destructive: false
+      };
     }
     case "alter_enum_add_value":
-      return `-- ALTER TYPE ADD VALUE cannot be reversed in PostgreSQL`;
+      return {
+        sql: `-- ALTER TYPE ADD VALUE cannot be reversed in PostgreSQL`,
+        destructive: true
+      };
     case "alter_column_collation": {
-      return `-- WARNING: Cannot reverse alter_column_collation "${change.table}"."${change.column}" -- previous collation unknown`;
+      return {
+        sql: `-- WARNING: Cannot reverse alter_column_collation "${change.table}"."${change.column}" -- previous collation unknown`,
+        destructive: true
+      };
     }
     case "alter_column_identity": {
       const col = change.meta?.column;
       const prevIdentity = change.meta?.previousIdentity;
-      if (!col) return void 0;
+      if (!col) return { sql: void 0, destructive: true };
       const table = qualifyTable(change.table, schemaName);
       const column = quoteIdent2(change.column, "alias");
       if (prevIdentity && !col.identity) {
         const gen2 = prevIdentity === "always" ? "ALWAYS" : "BY DEFAULT";
-        return `ALTER TABLE ${table} ALTER COLUMN ${column} ADD GENERATED ${gen2} AS IDENTITY;`;
+        return {
+          sql: `ALTER TABLE ${table} ALTER COLUMN ${column} ADD GENERATED ${gen2} AS IDENTITY;`,
+          // Allowlisted: re-adds the previously recorded identity metadata.
+          destructive: false
+        };
       }
       if (!prevIdentity && col.identity) {
-        return `ALTER TABLE ${table} ALTER COLUMN ${column} DROP IDENTITY IF EXISTS;`;
+        return {
+          sql: `ALTER TABLE ${table} ALTER COLUMN ${column} DROP IDENTITY IF EXISTS;`,
+          destructive: true
+        };
+      }
+      if (!prevIdentity && !col.identity) {
+        return {
+          sql: `-- WARNING: Cannot reverse alter_column_identity "${change.table}"."${change.column}" -- missing previous identity metadata`,
+          destructive: true
+        };
       }
       const gen = prevIdentity === "always" ? "ALWAYS" : "BY DEFAULT";
-      return `ALTER TABLE ${table} ALTER COLUMN ${column} SET GENERATED ${gen};`;
+      return {
+        sql: `ALTER TABLE ${table} ALTER COLUMN ${column} SET GENERATED ${gen};`,
+        // Allowlisted: restores the recorded prior identity generation mode.
+        destructive: false
+      };
     }
     case "add_comment": {
       const target = change.meta?.target;
       if (target === "table") {
-        return `COMMENT ON TABLE ${qualifyTable(change.table, schemaName)} IS NULL;`;
+        return {
+          sql: `COMMENT ON TABLE ${qualifyTable(change.table, schemaName)} IS NULL;`,
+          destructive: true
+        };
       }
-      return `COMMENT ON COLUMN ${qualifyTable(change.table, schemaName)}.${quoteIdent2(change.column, "alias")} IS NULL;`;
+      return {
+        sql: `COMMENT ON COLUMN ${qualifyTable(change.table, schemaName)}.${quoteIdent2(change.column, "alias")} IS NULL;`,
+        destructive: true
+      };
     }
     case "drop_comment": {
-      return `-- WARNING: Cannot reverse drop_comment "${change.table}"${change.column ? `."${change.column}"` : ""} -- comment text was lost`;
+      const target = change.meta?.target;
+      const comment = change.meta?.comment;
+      if (typeof comment === "string") {
+        const escaped = comment.replace(/'/g, "''");
+        if (target === "table") {
+          return {
+            sql: `COMMENT ON TABLE ${qualifyTable(change.table, schemaName)} IS '${escaped}';`,
+            // Allowlisted: re-adds the dropped table comment from metadata.
+            destructive: false
+          };
+        }
+        if (target === "column") {
+          return {
+            sql: `COMMENT ON COLUMN ${qualifyTable(change.table, schemaName)}.${quoteIdent2(change.column, "alias")} IS '${escaped}';`,
+            // Allowlisted: re-adds the dropped column comment from metadata.
+            destructive: false
+          };
+        }
+      }
+      return {
+        sql: `-- WARNING: Cannot reverse drop_comment "${change.table}"${change.column ? `."${change.column}"` : ""} -- comment text was lost`,
+        destructive: true
+      };
     }
     case "create_extension": {
       const ext = change.meta?.extension;
-      if (ext == null) return void 0;
-      return `DROP EXTENSION IF EXISTS ${quoteExtensionName(ext)} CASCADE;`;
+      if (ext == null) return { sql: void 0, destructive: true };
+      return {
+        sql: `DROP EXTENSION IF EXISTS ${quoteExtensionName(ext)} CASCADE;`,
+        destructive: true
+      };
     }
     case "drop_extension": {
       const ext = change.meta?.extension;
-      if (ext == null) return void 0;
-      return `CREATE EXTENSION IF NOT EXISTS ${quoteExtensionName(ext)};`;
+      if (ext == null) return { sql: void 0, destructive: true };
+      return {
+        sql: `CREATE EXTENSION IF NOT EXISTS ${quoteExtensionName(ext)};`,
+        // Allowlisted: re-creates the dropped extension from metadata.
+        destructive: false
+      };
     }
     case "create_sequence": {
       const seq = change.meta?.sequence;
-      if (!seq) return void 0;
+      if (!seq) return { sql: void 0, destructive: true };
       const seqName = schemaName ? `${quoteIdent2(schemaName, "alias")}.${quoteIdent2(seq.name, "alias")}` : quoteIdent2(seq.name, "alias");
-      return `DROP SEQUENCE IF EXISTS ${seqName} CASCADE;`;
+      return {
+        sql: `DROP SEQUENCE IF EXISTS ${seqName} CASCADE;`,
+        destructive: true
+      };
     }
     case "alter_sequence": {
       const prevSeq = change.meta?.previousSequence;
       if (!prevSeq) {
-        return `-- WARNING: Cannot reverse alter_sequence "${change.table}" -- missing migration metadata`;
+        return {
+          sql: `-- WARNING: Cannot reverse alter_sequence "${change.table}" -- missing migration metadata`,
+          destructive: true
+        };
       }
       const seqName = schemaName ? `${quoteIdent2(schemaName, "alias")}.${quoteIdent2(prevSeq.name, "alias")}` : quoteIdent2(prevSeq.name, "alias");
-      return buildSequenceClause("ALTER SEQUENCE", seqName, prevSeq, true);
+      return {
+        sql: buildSequenceClause("ALTER SEQUENCE", seqName, prevSeq, true),
+        // Allowlisted: restores the recorded prior sequence metadata.
+        destructive: false
+      };
     }
     case "drop_sequence": {
       const seq = change.meta?.sequence;
-      if (!seq) return void 0;
+      if (!seq) return { sql: void 0, destructive: true };
       const seqName = schemaName ? `${quoteIdent2(schemaName, "alias")}.${quoteIdent2(seq.name, "alias")}` : quoteIdent2(seq.name, "alias");
-      return buildSequenceClause("CREATE SEQUENCE", seqName, seq);
+      return {
+        sql: buildSequenceClause("CREATE SEQUENCE", seqName, seq),
+        // Allowlisted: re-creates the dropped sequence from metadata.
+        destructive: false
+      };
     }
     case "validate_constraint":
-      return `-- VALIDATE CONSTRAINT cannot be reversed in PostgreSQL (table: "${change.table}")`;
+      return {
+        sql: `-- VALIDATE CONSTRAINT cannot be reversed in PostgreSQL (table: "${change.table}")`,
+        destructive: true
+      };
     case "enable_rls":
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} DISABLE ROW LEVEL SECURITY;`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} DISABLE ROW LEVEL SECURITY;`,
+        destructive: true
+      };
     case "disable_rls":
-      return `ALTER TABLE ${qualifyTable(change.table, schemaName)} ENABLE ROW LEVEL SECURITY;`;
+      return {
+        sql: `ALTER TABLE ${qualifyTable(change.table, schemaName)} ENABLE ROW LEVEL SECURITY;`,
+        // Allowlisted: re-enables the previously present RLS security control.
+        destructive: false
+      };
     case "create_policy": {
       const policy = change.meta?.policy;
-      if (!policy) return void 0;
-      return `DROP POLICY IF EXISTS ${quoteIdent2(policy.name, "alias")} ON ${qualifyTable(change.table, schemaName)};`;
+      if (!policy) return { sql: void 0, destructive: true };
+      return {
+        sql: `DROP POLICY IF EXISTS ${quoteIdent2(policy.name, "alias")} ON ${qualifyTable(change.table, schemaName)};`,
+        destructive: true
+      };
     }
     case "drop_policy": {
       const policy = change.meta?.policy;
-      if (!policy) return void 0;
-      return buildPolicySQL(change.table, policy, schemaName);
+      if (!policy) return { sql: void 0, destructive: true };
+      return {
+        sql: buildPolicySQL(change.table, policy, schemaName),
+        // Allowlisted: re-creates the dropped RLS policy from metadata.
+        destructive: false
+      };
     }
+    default:
+      return failSafeUnknownDownChange(change.kind);
   }
 }
 function generateDownSQL(diff, options) {
+  return generateDownMigrationSQL(diff, options).statements;
+}
+function generateDownMigrationSQL(diff, options) {
   const schemaName = options?.schemaName;
   const includeDestructive = options?.includeDestructive ?? true;
   const changes = includeDestructive ? diff.changes : diff.changes.filter((c) => !c.destructive);
@@ -11252,13 +11812,15 @@ function generateDownSQL(diff, options) {
     phases[phase].push(change);
   }
   const statements = [];
+  let destructive = false;
   for (let i = phases.length - 1; i >= 0; i--) {
     for (const change of phases[i]) {
-      const sql = changeToDownSQL(change, schemaName);
-      if (sql) statements.push(sql);
+      const down = changeToDownSQL(change, schemaName);
+      destructive = down.destructive || destructive;
+      if (down.sql) statements.push(down.sql);
     }
   }
-  return statements;
+  return { statements, destructive };
 }
 function generateCreateTableSQL(table, schemaName) {
   const qualTable = qualifyTable(table.name, schemaName);
@@ -11551,29 +12113,36 @@ function generateCreatePolicy(tableName, policy, schemaName, naming) {
 // src/ddl/migration-file.ts
 function generateMigrationFile(diff, options) {
   const upStatements = generateMigrationSQL(diff, options);
-  const downStatements = generateDownSQL(diff, options);
+  const downMigration = generateDownMigrationSQL(diff, options);
+  const downStatements = downMigration.statements;
+  const destructiveHeader = `-- dbsp:destructive: ${downMigration.destructive ? "true" : "false"}`;
   const header = options?.name ? `-- Migration: ${options.name}
 -- Generated by: dbsp migrate dev
 -- Date: ${(/* @__PURE__ */ new Date()).toISOString()}
+${destructiveHeader}
 
-` : "";
+` : `${destructiveHeader}
+
+`;
   const upSection = upStatements.length > 0 ? `${upStatements.join(";\n\n")};
 ` : "";
   const downSection = downStatements.length > 0 ? `${downStatements.join(";\n\n")};
 ` : "";
-  return `${header}${upSection}
--- DOWN
+  const separatorPrefix = upSection.length > 0 ? "\n" : "";
+  return `${header}${upSection}${separatorPrefix}-- DOWN
 
 ${downSection}`;
 }
 function parseMigrationFile(content) {
+  const destructive = parseDestructiveHeader(content);
   const separatorRegex = /^\s*-- DOWN\s*$/m;
   const match = separatorRegex.exec(content);
   if (!match) {
     return {
       upStatements: splitStatements(content),
       downStatements: [],
-      hasDown: false
+      hasDown: false,
+      destructive
     };
   }
   const upContent = content.slice(0, match.index);
@@ -11581,9 +12150,36 @@ function parseMigrationFile(content) {
   return {
     upStatements: splitStatements(upContent),
     downStatements: splitStatements(downContent),
-    hasDown: true
+    hasDown: true,
+    destructive
   };
 }
+function parseDestructiveHeader(content) {
+  let destructive;
+  let found = false;
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    if (/^--\s*DOWN\s*$/i.test(trimmed)) {
+      break;
+    }
+    if (!trimmed.startsWith("--")) {
+      break;
+    }
+    const match = /^--\s*dbsp:destructive:\s*(true|false)\s*$/i.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+    if (found) {
+      return void 0;
+    }
+    found = true;
+    destructive = match[1]?.toLowerCase() === "true";
+  }
+  return found ? destructive : void 0;
+}
 function isDestructiveDown(downStatements) {
   const destructivePatterns = [
     /DROP\s+TABLE/i,
@@ -12706,6 +13302,7 @@ function vectorDims(column) {
 // src/introspection.ts
 init_assert_field();
 import { ModelIRImpl } from "@dbsp/core";
+import { buildRelationKeyFields } from "@dbsp/types";
 function parseExpressionsList(raw) {
   const results = [];
   let depth = 0;
@@ -13261,7 +13858,10 @@ function inferRelations(fksByConstraint, filteredTables) {
   for (const [, fk] of fksByConstraint) {
     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 relationFk = {
+      columns: fk.cols,
+      references: { table: fk.target, columns: fk.refs }
+    };
     const belongsToKey = `${fk.source}.${belongsToName}`;
     if (!relations.has(belongsToKey)) {
       relations.set(belongsToKey, {
@@ -13269,7 +13869,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         type: "belongsTo",
         source: fk.source,
         target: fk.target,
-        foreignKey: fkCol,
+        ...buildRelationKeyFields(relationFk, "belongsTo"),
         cardinality: "one",
         optionality: "optional",
         includeStrategy: "auto",
@@ -13285,7 +13885,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         type: "hasMany",
         source: fk.target,
         target: fk.source,
-        foreignKey: fkCol,
+        ...buildRelationKeyFields(relationFk, "inverse"),
         cardinality: "many",
         optionality: "optional",
         includeStrategy: "auto",
@@ -14188,6 +14788,7 @@ import { getNqlBindingRefName as getNqlBindingRefName2, isNqlBindingRef as isNql
 
 // src/adapter-compiler-includes.ts
 init_ast_helpers();
+import { toColumnList as toColumnList8 } from "@dbsp/types";
 init_handlers();
 function compileSubqueryInclude(info, parentIds, _options, deps) {
   const schemaName = deps.schemaName;
@@ -14199,7 +14800,12 @@ function compileSubqueryInclude(info, parentIds, _options, deps) {
       parameters: []
     };
   }
-  const fkColumns = Array.isArray(info.foreignKey) ? info.foreignKey : [info.foreignKey];
+  const fkColumns = toColumnList8(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 +14853,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 +14898,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 = toColumnList8(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 +14993,7 @@ import {
   POSTGRESQL_CAPABILITIES,
   plan as planFn
 } from "@dbsp/core";
+import { toColumnList as toColumnList11 } from "@dbsp/types";
 
 // src/adapter-compiler-select.ts
 init_assert_field();
@@ -14383,6 +15001,7 @@ init_ast_helpers();
 init_binding_registry();
 init_compile_where();
 import { countDistinctRelationPathsByName } from "@dbsp/core";
+import { toColumnList as toColumnList10 } from "@dbsp/types";
 init_compiler_utils();
 init_types();
 init_intent_to_decisions();
@@ -14392,6 +15011,7 @@ init_param_ref();
 init_assert_field();
 init_intent_to_decisions();
 import { deriveRelationPathFromIntentPath } from "@dbsp/core";
+import { toColumnList as toColumnList9 } from "@dbsp/types";
 function findExistsIntents(where) {
   if (!where || typeof where !== "object") return [];
   const w = where;
@@ -14412,7 +15032,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 = toColumnList9(rel.foreignKey);
+  const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
   const relationType = rel.type;
   return { target: rel.target, foreignKey, relationType };
 }
@@ -14635,7 +15256,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 ? toColumnList9(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 +15367,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 = toColumnList9(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 +15427,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 ? toColumnList9(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 +15741,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 +15762,10 @@ 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.targetOrderKey && context.targetOrderKey.length > 0 ? { orderBy: context.targetOrderKey } : {},
+    ...context.orderByFallback ? { orderByFallback: true } : {},
     ...context.intentPath && { intentPath: context.intentPath },
     ...limit != null && { limit }
   };
@@ -15164,6 +15791,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 +15812,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 +15836,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 = toColumnList9(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 +15863,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" ? toColumnList9(rel.targetKey).length > 0 ? toColumnList9(rel.targetKey) : [defaultPk] : toColumnList9(rel.sourceKey).length > 0 ? toColumnList9(rel.sourceKey) : [defaultPk],
       columns,
       joinType: inc.join,
       ...conditions && { conditions }
@@ -15390,9 +16021,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 = toColumnList10(rel.foreignKey);
+      const fkColumns = rawFk.length > 0 ? rawFk : [deriveFk(isBelongsTo ? rootTable : rel.target, defaultPk)];
+      const sourceKey = toColumnList10(rel.sourceKey);
+      const targetKey = toColumnList10(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 +16389,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 = toColumnList10(rawFk);
+    const parentKey = toColumnList10(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 +16456,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 = toColumnList11(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 +16476,13 @@ function resolveExistsRelation(sourceTable, relation, model) {
     return {
       targetTable,
       ...fk2 !== void 0 && { sourceColumn: fk2 },
-      targetColumn: "id"
+      targetColumn: toColumnList11(rel.targetKey).length > 0 ? toColumnList11(rel.targetKey) : ["id"]
     };
   }
   const fk = resolveMutationExistsForeignKey(rel.foreignKey, relationName);
   return {
     targetTable,
-    sourceColumn: rel.sourceKey ?? "id",
+    sourceColumn: toColumnList11(rel.sourceKey).length > 0 ? toColumnList11(rel.sourceKey) : ["id"],
     ...fk !== void 0 && { targetColumn: fk }
   };
 }
@@ -17769,6 +18404,9 @@ function orderedNqlBindingNames(bundle) {
   }
   return names;
 }
+function runtimeBindingSourceTable(bundle, name) {
+  return bundle.mutationBindings?.get(name)?.table ?? bundle.bindings?.get(name)?.from;
+}
 function mapRuntimeBindingColumnType(type) {
   switch (type) {
     case "string":
@@ -17821,13 +18459,13 @@ function resolveRuntimeBindingColumnType(bindingName, sourceTable, columnName) {
   );
   if (column === void 0) {
     throw new Error(
-      `NQL runtime binding '${bindingName}' cannot resolve projected column '${columnName}' on source mutation table '${sourceTable.name}'.`
+      `NQL runtime binding '${bindingName}' cannot resolve projected column '${columnName}' on source table '${sourceTable.name}'.`
     );
   }
   const dbType = column.originalDbType?.trim() || mapRuntimeBindingColumnType(column.type);
   if (dbType === void 0 || dbType.trim() === "") {
     throw new Error(
-      `NQL runtime binding '${bindingName}' cannot resolve a PostgreSQL type for projected column '${columnName}' on source mutation table '${sourceTable.name}'.`
+      `NQL runtime binding '${bindingName}' cannot resolve a PostgreSQL type for projected column '${columnName}' on source table '${sourceTable.name}'.`
     );
   }
   const typeName = dbType.trim();
@@ -17850,7 +18488,7 @@ function resolveRuntimeBindingColumnTypes(name, binding, model, sourceTableName)
   const sourceTable = findRuntimeBindingSourceTable(model, sourceTableName);
   if (sourceTable === void 0) {
     throw new Error(
-      `NQL runtime binding '${name}' cannot resolve source mutation table '${sourceTableName}' in the model.`
+      `NQL runtime binding '${name}' cannot resolve source table '${sourceTableName}' in the model.`
     );
   }
   return binding.columns.map(
@@ -17877,7 +18515,7 @@ function compileNqlRuntimeBindingCte(name, binding, naming, parameterOffset, sou
   const columnSql = binding.columns.map((column) => quoteIdent2(naming.toDatabase(column), "column")).join(", ");
   if (sourceTable === void 0) {
     throw new Error(
-      `NQL runtime binding '${name}' cannot materialize a typed relation because its source mutation table is unavailable.`
+      `NQL runtime binding '${name}' cannot materialize a typed relation because its source table is unavailable.`
     );
   }
   const projectedColumns = binding.columns.map((column) => quoteIdent2(naming.toDatabase(column), "column")).join(", ");
@@ -18086,7 +18724,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(
@@ -18152,7 +18790,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
           runtimeBinding,
           naming,
           parameters.length,
-          bundle.mutationBindings?.get(name)?.table,
+          runtimeBindingSourceTable(bundle, name),
           deps.schemaName,
           deps.model
         );
@@ -18180,6 +18818,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 },