@dbsp/adapter-pgsql 1.6.0 → 1.7.0

package/dist/index.js

@@ -663,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,
@@ -4486,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 = [];
@@ -4604,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",
@@ -5098,19 +5101,19 @@ var init_shared = __esm({
 });
 
 // src/handlers/include/json-agg.ts
-import { toColumnList as toColumnList6 } from "@dbsp/types";
+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 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;
+    const orderKey = resolveJsonAggOrderKey(table);
+    return orderKey.columns.length > 0 ? orderKey : void 0;
   }
-  return decision.targetPrimaryKey && decision.targetPrimaryKey.length > 0 ? {
-    columns: decision.targetPrimaryKey,
+  const decisionOrderBy = isJsonAggOrderBy(decision.orderBy) ? decision.orderBy : void 0;
+  return decisionOrderBy && decisionOrderBy.length > 0 ? {
+    columns: decisionOrderBy,
     fallback: decision.orderByFallback === true
   } : void 0;
 }
@@ -5210,7 +5213,7 @@ var init_json_agg = __esm({
 });
 
 // src/handlers/include/lateral.ts
-import { toColumnList as toColumnList7 } from "@dbsp/types";
+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) => ({
@@ -5312,7 +5315,7 @@ var init_lateral = __esm({
     lateralIncludeHandler = {
       strategy: "lateral",
       compile(decision, ctx, state) {
-        const sourceColumn = toColumnList7(decision.sourceColumn);
+        const sourceColumn = toColumnList6(decision.sourceColumn);
         if (sourceColumn.length === 0) {
           throw new Error(
             "Missing required column 'sourceColumn' in lateral include"
@@ -6267,6 +6270,7 @@ function buildRecursiveScalarSubquery(config) {
     pkColumn,
     fkColumn,
     outerAlias,
+    outerSeedColumn,
     isAncestors,
     maxDepth,
     selectColumn,
@@ -6277,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: [
@@ -6345,7 +6352,7 @@ function buildRecursiveScalarSubquery(config) {
           ColumnRef: {
             fields: [
               { String: { sval: dbOuter } },
-              { String: { sval: dbFk } }
+              { String: { sval: dbOuterSeed } }
             ]
           }
         }
@@ -6365,7 +6372,7 @@ function buildRecursiveScalarSubquery(config) {
           ColumnRef: {
             fields: [
               { String: { sval: dbOuter } },
-              { String: { sval: dbPk } }
+              { String: { sval: dbOuterSeed } }
             ]
           }
         }
@@ -6429,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",
@@ -6520,7 +6519,7 @@ function buildRecursiveScalarSubquery(config) {
             },
             integerNode(maxDepth)
           ),
-          // pk <> ALL(__visited) — cycle detection
+          // pk <> ALL(__visited) - cycle detection
           {
             A_Expr: {
               kind: "AEXPR_OP_ALL",
@@ -6565,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")
+          ])
         }
       }
     ],
@@ -7037,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);
@@ -7049,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 };
@@ -7313,7 +7332,7 @@ import {
   isParamIntent as isParamIntent6,
   NQL_SELECT_SCALAR_FUNCTION_ALLOWLIST,
   NQL_SELECT_WINDOW_FUNCTION_ALLOWLIST,
-  toColumnList as toColumnList8
+  toColumnList as toColumnList7
 } from "@dbsp/types";
 import {
   getNqlBindingRefName,
@@ -8379,6 +8398,7 @@ init_case_value();
 init_custom();
 init_expression();
 init_param_value();
+init_pseudo();
 init_window();
 init_include();
 init_shared();
@@ -8425,7 +8445,7 @@ function trustedRelationHasMultipleHops(relation) {
   if (typeof relation !== "string") return relation.length > 1;
   return relation.split(".").length > 1;
 }
-function isJsonAggOrderBy(orderBy) {
+function isJsonAggOrderBy2(orderBy) {
   return Array.isArray(orderBy) && orderBy.every((item) => typeof item === "string");
 }
 function isExpressionOrderBy(orderBy) {
@@ -8434,8 +8454,12 @@ function isExpressionOrderBy(orderBy) {
   );
 }
 function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
-  const jsonAggOrderBy = isJsonAggOrderBy(pd.orderBy) ? pd.orderBy : void 0;
+  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,
@@ -8470,7 +8494,6 @@ 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,
@@ -8486,10 +8509,7 @@ function mapToHandlerDecision(pd, rootTable, defaultPk, deriveFk) {
     include: pd.include?.map(
       (c) => mapToHandlerDecision(c, rootTable, defaultPk, deriveFk)
     ),
-    orderBy: expressionOrderBy?.map((o) => ({
-      column: o.field,
-      direction: o.direction?.toUpperCase() ?? "ASC"
-    })),
+    orderBy: handlerOrderBy,
     partition: pd.partitionBy,
     jsonPath: pd.jsonPath,
     jsonMode: pd.jsonMode,
@@ -9048,8 +9068,11 @@ var PlanCompiler = class _PlanCompiler {
   isNqlBindingRoot(plan) {
     return hasBindingName(this.bindingNames, plan.rootTable, this.naming);
   }
+  allocateBindingRelationAlias() {
+    return `rc_${this.bindingRelationColumnSubqueryIndex++}`;
+  }
   buildCorrelatedRelationRefs(fields, plan) {
-    const relatedAlias = `rc_${this.bindingRelationColumnSubqueryIndex++}`;
+    const relatedAlias = this.allocateBindingRelationAlias();
     const relatedTable = rangeVar(
       fields.targetTable,
       relatedAlias,
@@ -9068,12 +9091,93 @@ var PlanCompiler = class _PlanCompiler {
       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"
+    );
+    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)) {
@@ -9152,9 +9256,14 @@ var PlanCompiler = class _PlanCompiler {
       };
     }
     if (fields.cardinality === "many") {
-      if (fields.relationType !== "hasMany") {
+      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 can be aggregated (ref-#192).`
+          `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) {
@@ -9163,6 +9272,37 @@ var PlanCompiler = class _PlanCompiler {
         );
       }
       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",
@@ -9185,14 +9325,8 @@ var PlanCompiler = class _PlanCompiler {
                 }
               }
             ],
-            from: [relatedTable],
-            where: buildKeyCorrelation(
-              relatedAlias,
-              fields.targetColumn,
-              plan.rootTable,
-              fields.sourceColumn,
-              this.createHandlerContext(plan)
-            )
+            from: [fromNode],
+            where: whereNode
           })
         }
       };
@@ -10357,8 +10491,8 @@ var PlanCompiler = class _PlanCompiler {
       this.schemaForRangeVar(plan, decision.targetTable ?? ""),
       this.naming
     );
-    const sourceColumn = toColumnList8(decision.sourceColumn);
-    const targetColumn = toColumnList8(decision.targetColumn);
+    const sourceColumn = toColumnList7(decision.sourceColumn);
+    const targetColumn = toColumnList7(decision.targetColumn);
     if (sourceColumn.length === 0) {
       throw new Error("Missing required column 'sourceColumn' in compileJoin");
     }
@@ -10797,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":
@@ -11249,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);
@@ -11479,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);
@@ -11778,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);
@@ -11808,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,
@@ -12933,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;
@@ -13488,9 +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 refCol = fk.refs.length === 1 ? fk.refs[0] : fk.refs;
-    const keyOverride = Array.isArray(refCol) || refCol !== DEFAULT_PK_COLUMN ? refCol : void 0;
+    const relationFk = {
+      columns: fk.cols,
+      references: { table: fk.target, columns: fk.refs }
+    };
     const belongsToKey = `${fk.source}.${belongsToName}`;
     if (!relations.has(belongsToKey)) {
       relations.set(belongsToKey, {
@@ -13498,8 +13869,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         type: "belongsTo",
         source: fk.source,
         target: fk.target,
-        foreignKey: fkCol,
-        ...keyOverride !== void 0 && { targetKey: keyOverride },
+        ...buildRelationKeyFields(relationFk, "belongsTo"),
         cardinality: "one",
         optionality: "optional",
         includeStrategy: "auto",
@@ -13515,8 +13885,7 @@ function inferRelations(fksByConstraint, filteredTables) {
         type: "hasMany",
         source: fk.target,
         target: fk.source,
-        foreignKey: fkCol,
-        ...keyOverride !== void 0 && { sourceKey: keyOverride },
+        ...buildRelationKeyFields(relationFk, "inverse"),
         cardinality: "many",
         optionality: "optional",
         includeStrategy: "auto",
@@ -14419,7 +14788,7 @@ import { getNqlBindingRefName as getNqlBindingRefName2, isNqlBindingRef as isNql
 
 // src/adapter-compiler-includes.ts
 init_ast_helpers();
-import { toColumnList as toColumnList9 } from "@dbsp/types";
+import { toColumnList as toColumnList8 } from "@dbsp/types";
 init_handlers();
 function compileSubqueryInclude(info, parentIds, _options, deps) {
   const schemaName = deps.schemaName;
@@ -14431,7 +14800,7 @@ function compileSubqueryInclude(info, parentIds, _options, deps) {
       parameters: []
     };
   }
-  const fkColumns = toColumnList9(info.foreignKey);
+  const fkColumns = toColumnList8(info.foreignKey);
   if (fkColumns.length === 0) {
     throw new Error(
       "Subquery include requires at least one foreignKey column."
@@ -14529,7 +14898,7 @@ function compileSubqueryIncludeManyToMany(info, parentIds, schemaName, state, de
   const throughTable = info.through;
   const throughSourceKey = info.throughSourceKey;
   const throughTargetKey = info.throughTargetKey;
-  const targetPkColumns = toColumnList9(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)}.`
@@ -14624,7 +14993,7 @@ import {
   POSTGRESQL_CAPABILITIES,
   plan as planFn
 } from "@dbsp/core";
-import { toColumnList as toColumnList12 } from "@dbsp/types";
+import { toColumnList as toColumnList11 } from "@dbsp/types";
 
 // src/adapter-compiler-select.ts
 init_assert_field();
@@ -14632,7 +15001,7 @@ init_ast_helpers();
 init_binding_registry();
 init_compile_where();
 import { countDistinctRelationPathsByName } from "@dbsp/core";
-import { toColumnList as toColumnList11 } from "@dbsp/types";
+import { toColumnList as toColumnList10 } from "@dbsp/types";
 init_compiler_utils();
 init_types();
 init_intent_to_decisions();
@@ -14642,7 +15011,7 @@ init_param_ref();
 init_assert_field();
 init_intent_to_decisions();
 import { deriveRelationPathFromIntentPath } from "@dbsp/core";
-import { toColumnList as toColumnList10 } from "@dbsp/types";
+import { toColumnList as toColumnList9 } from "@dbsp/types";
 function findExistsIntents(where) {
   if (!where || typeof where !== "object") return [];
   const w = where;
@@ -14663,7 +15032,7 @@ function findExistsIntents(where) {
 function resolveRelation(model, sourceTable, relationName) {
   const rel = model.getRelation(`${sourceTable}.${relationName}`);
   if (!rel) return void 0;
-  const foreignKeyColumns = toColumnList10(rel.foreignKey);
+  const foreignKeyColumns = toColumnList9(rel.foreignKey);
   const foreignKey = foreignKeyColumns.length > 0 ? foreignKeyColumns : void 0;
   const relationType = rel.type;
   return { target: rel.target, foreignKey, relationType };
@@ -14887,7 +15256,7 @@ function buildMultiHopExistsChain(hops, rootTable, outerOperator, innerCondition
   const hopRelations = [];
   for (const hop of hops) {
     const rel = model.getRelation(`${currentSource}.${hop}`);
-    const foreignKeyColumns = rel ? toColumnList10(rel.foreignKey) : [];
+    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;
@@ -14998,7 +15367,7 @@ 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 foreignKeyColumns = toColumnList10(rel.foreignKey);
+        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;
@@ -15058,7 +15427,7 @@ function buildEnrichedExistsDecision(d, matchingIntent, rootTable, model) {
   const relIR = model && context.relation ? model.getRelation(
     `${sourceTableForRelation}.${context.relation}`
   ) : void 0;
-  const foreignKeyColumns = relIR ? toColumnList10(relIR.foreignKey) : [];
+  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;
@@ -15395,10 +15764,7 @@ function toIncludeDecision(d, choice, plan, defaultPk = DEFAULT_PK_COLUMN, deriv
     ...relationType && { relationType },
     foreignKey,
     parentKey,
-    ...context.targetPrimaryKey && context.targetPrimaryKey.length > 0 ? {
-      targetPrimaryKey: context.targetPrimaryKey,
-      orderBy: context.targetPrimaryKey
-    } : {},
+    ...context.targetOrderKey && context.targetOrderKey.length > 0 ? { orderBy: context.targetOrderKey } : {},
     ...context.orderByFallback ? { orderByFallback: true } : {},
     ...context.intentPath && { intentPath: context.intentPath },
     ...limit != null && { limit }
@@ -15470,7 +15836,7 @@ function synthesizeMissingJoinDecisions(plan, coveredRelations, model, defaultPk
       (r) => r.name === alias || snakeToCamel(r.name) === alias
     );
     if (!rel) continue;
-    const rawFkColumns = toColumnList10(rel.foreignKey);
+    const rawFkColumns = toColumnList9(rel.foreignKey);
     const rawFk = rawFkColumns.length > 0 ? rawFkColumns : [
       deriveFk(
         rel.type === "belongsTo" ? rel.target : sourceTable,
@@ -15498,7 +15864,7 @@ function synthesizeMissingJoinDecisions(plan, coveredRelations, model, defaultPk
         relationType: rel.type
       },
       foreignKey: rawFk,
-      parentKey: rel.type === "belongsTo" ? toColumnList10(rel.targetKey).length > 0 ? toColumnList10(rel.targetKey) : [defaultPk] : toColumnList10(rel.sourceKey).length > 0 ? toColumnList10(rel.sourceKey) : [defaultPk],
+      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 }
@@ -15655,10 +16021,10 @@ function compileJoinIntents(joins, rootTable, schemaName, deps) {
         );
       }
       const isBelongsTo = rel.type === "belongsTo";
-      const rawFk = toColumnList11(rel.foreignKey);
+      const rawFk = toColumnList10(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 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;
@@ -16023,8 +16389,8 @@ 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 = toColumnList11(rawFk);
-    const parentKey = toColumnList11(ctx.parentKey);
+    const fk = toColumnList10(rawFk);
+    const parentKey = toColumnList10(ctx.parentKey);
     const isBelongsTo = ctx.relationType === "belongsTo";
     const sourceKey = isBelongsTo ? fk : parentKey.length > 0 ? parentKey : [deps.defaultPk];
     const targetFk = isBelongsTo ? parentKey.length > 0 ? parentKey : [deps.defaultPk] : fk;
@@ -16090,7 +16456,7 @@ function prependSourceCte(sql, parameters, sourceName, sourceCte, naming) {
   };
 }
 function resolveMutationExistsForeignKey(foreignKey, relationName) {
-  const columns = toColumnList12(foreignKey);
+  const columns = toColumnList11(foreignKey);
   if (columns.length === 0) return void 0;
   if (columns.some((column) => column.length === 0)) {
     throw new Error(
@@ -16110,13 +16476,13 @@ function resolveExistsRelation(sourceTable, relation, model) {
     return {
       targetTable,
       ...fk2 !== void 0 && { sourceColumn: fk2 },
-      targetColumn: toColumnList12(rel.targetKey).length > 0 ? toColumnList12(rel.targetKey) : ["id"]
+      targetColumn: toColumnList11(rel.targetKey).length > 0 ? toColumnList11(rel.targetKey) : ["id"]
     };
   }
   const fk = resolveMutationExistsForeignKey(rel.foreignKey, relationName);
   return {
     targetTable,
-    sourceColumn: toColumnList12(rel.sourceKey).length > 0 ? toColumnList12(rel.sourceKey) : ["id"],
+    sourceColumn: toColumnList11(rel.sourceKey).length > 0 ? toColumnList11(rel.sourceKey) : ["id"],
     ...fk !== void 0 && { targetColumn: fk }
   };
 }
@@ -18038,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":
@@ -18090,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();
@@ -18119,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(
@@ -18146,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(", ");
@@ -18421,7 +18790,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
           runtimeBinding,
           naming,
           parameters.length,
-          bundle.mutationBindings?.get(name)?.table,
+          runtimeBindingSourceTable(bundle, name),
           deps.schemaName,
           deps.model
         );