@dbsp/core 1.3.0 → 1.5.0

package/dist/index.js

@@ -645,7 +645,12 @@ function schemaToModelIR(definition, constraints, extras, options) {
     options
   );
   validateFkTargets(tables);
-  const relations = buildRelations(definition, refsByTable, tableNames);
+  const relations = buildRelations(
+    definition,
+    refsByTable,
+    tableNames,
+    constraints
+  );
   const tableMap = /* @__PURE__ */ new Map();
   for (const table of tables) {
     tableMap.set(table.name, table);
@@ -1057,6 +1062,7 @@ function buildTableConstraints(tableName, constraints) {
         }
       };
       if (fkRef.options.onDelete) fk.onDelete = fkRef.options.onDelete;
+      if (fkRef.options.onUpdate) fk.onUpdate = fkRef.options.onUpdate;
       extraForeignKeys.push(fk);
     }
   }
@@ -1095,7 +1101,7 @@ function normalizeColumnDef(def) {
   }
   return def;
 }
-function buildRelations(_definition, refsByTable, tableNames) {
+function buildRelations(_definition, refsByTable, tableNames, constraints) {
   const relations = [];
   for (const tableName of tableNames) {
     const refs = refsByTable.get(tableName) || [];
@@ -1195,8 +1201,75 @@ function buildRelations(_definition, refsByTable, tableNames) {
       }
     }
   }
+  addCompositeConstraintRelations(relations, tableNames, constraints);
   return relations;
 }
+function relationKey(source, name) {
+  return `${source}.${name}`;
+}
+function pushRelationIfAbsent(relations, relationKeys, relation) {
+  const key = relationKey(relation.source, relation.name);
+  if (relationKeys.has(key)) return;
+  relationKeys.add(key);
+  relations.push(relation);
+}
+function deriveCompositeConstraintRelationName(fkColumn, options) {
+  return deriveLocalRelation(fkColumn, options);
+}
+function addCompositeConstraintRelations(relations, tableNames, constraints) {
+  if (!constraints) return;
+  const tableSet = new Set(tableNames);
+  const relationKeys = new Set(
+    relations.map((relation) => relationKey(relation.source, relation.name))
+  );
+  for (const tableName of tableNames) {
+    const foreignKeys = constraints[tableName]?.foreignKeys;
+    if (!foreignKeys) continue;
+    for (const fkRef of foreignKeys) {
+      if (!tableSet.has(fkRef.target)) continue;
+      const columns = fkRef.options.columns;
+      if (!columns?.length) continue;
+      const references = fkRef.options.references ?? ["id"];
+      if (columns.length === 1 && references.length === 1) continue;
+      const foreignKey = [...columns];
+      const referencedKey = [...references];
+      const belongsToName = deriveCompositeConstraintRelationName(
+        foreignKey[0],
+        fkRef.options
+      );
+      const inverseName = fkRef.options.inverse ?? tableName;
+      const isUnique = fkRef.options.unique ?? false;
+      const inverseType = isUnique ? "hasOne" : "hasMany";
+      const inverseCardinality = isUnique ? "one" : "many";
+      pushRelationIfAbsent(relations, relationKeys, {
+        name: belongsToName,
+        type: "belongsTo",
+        source: tableName,
+        target: fkRef.target,
+        foreignKey,
+        targetKey: referencedKey,
+        cardinality: "one",
+        optionality: fkRef.options.nullable ? "optional" : "required",
+        includeStrategy: "auto",
+        filterStrategy: "auto",
+        joinDefault: "auto"
+      });
+      pushRelationIfAbsent(relations, relationKeys, {
+        name: inverseName,
+        type: inverseType,
+        source: fkRef.target,
+        target: tableName,
+        foreignKey,
+        sourceKey: referencedKey,
+        cardinality: inverseCardinality,
+        optionality: "optional",
+        includeStrategy: "auto",
+        filterStrategy: "auto",
+        joinDefault: "auto"
+      });
+    }
+  }
+}
 function columnTypeToJsType(type) {
   switch (type) {
     // Numeric types → 'number' (includes integer, bigint, decimal)
@@ -1591,6 +1664,9 @@ function isManyToMany(rel) {
   return rel.kind === "manyToMany";
 }
 
+// src/planner.ts
+import { toColumnList } from "@dbsp/types";
+
 // src/dx/errors.ts
 var ExecutionError = class _ExecutionError extends Error {
   name = "ExecutionError";
@@ -2325,14 +2401,21 @@ function generateBidirectionalReasoning(storageHint, strategy) {
 function isSubquerySelectedColumnNonNullable(existsIntent, sourceTable, model) {
   const rel = model.getRelation(`${sourceTable}.${existsIntent.relation}`);
   if (!rel) return false;
-  const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : rel.foreignKey?.[0];
-  if (!fk) return false;
+  const fkColumns = toColumnList(rel.foreignKey);
+  if (fkColumns.length !== 1) return false;
+  const fk = fkColumns[0];
   const targetTableIR = model.getTable(rel.target);
   if (!targetTableIR) return false;
   const column = targetTableIR.columns.find((c) => c.name === fk);
   if (!column) return false;
   return !column.nullable;
 }
+function resolveTargetJsonAggOrderKey(model, targetTable) {
+  const table = model.getTable(targetTable);
+  if (!table) return { columns: [], fallback: false };
+  const pkColumns = toColumnList(table.primaryKey);
+  return pkColumns.length > 0 ? { columns: pkColumns, fallback: false } : { columns: table.columns.map((col2) => col2.name), fallback: true };
+}
 function optimizeInToExists(where, sourceTable, model, negated = false) {
   switch (where.kind) {
     case "in": {
@@ -2343,18 +2426,22 @@ function optimizeInToExists(where, sourceTable, model, negated = false) {
         return where;
       }
       const subSelect = inWhere.subquery.select;
-      if (!subSelect || subSelect.type !== "fields") return where;
+      if (subSelect?.type !== "fields") return where;
       const fields = "fields" in subSelect ? subSelect.fields : void 0;
-      if (!fields || fields.length !== 1) return where;
+      if (fields?.length !== 1) return where;
       const subColumn = fields[0];
       if (!subColumn) return where;
       const relationsFrom = model.getRelationsFrom(sourceTable);
       const sourceTableIR = model.getTable(sourceTable);
-      const sourcePk = typeof sourceTableIR?.primaryKey === "string" ? sourceTableIR.primaryKey : sourceTableIR?.primaryKey?.[0] ?? "id";
+      const sourcePkColumns = toColumnList(sourceTableIR?.primaryKey);
+      if (sourcePkColumns.length > 1) return where;
+      const sourcePk = sourcePkColumns[0] ?? "id";
       let matchedRelation;
       for (const rel of relationsFrom) {
         if (rel.target !== inWhere.subquery.from) continue;
-        const fk = typeof rel.foreignKey === "string" ? rel.foreignKey : rel.foreignKey?.[0];
+        const fkColumns = toColumnList(rel.foreignKey);
+        if (fkColumns.length !== 1) continue;
+        const fk = fkColumns[0];
         if (rel.type === "hasMany" && fk === subColumn && inWhere.field === sourcePk) {
           matchedRelation = rel.name;
           break;
@@ -2656,6 +2743,8 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
   const cascadedJoinType = ancestorIsLeftJoin && include.join === void 0 ? "left" : autoJoinType;
   const explicitJoinType = includeStrategy === "join" ? include.join ?? cascadedJoinType : void 0;
   const includeDecisionId = generateDecisionId(state, "include-strategy");
+  const parentKey = relation.type === "belongsTo" ? relation.targetKey : relation.sourceKey;
+  const targetOrder = resolveTargetJsonAggOrderKey(model, relation.target);
   state.decisions.push({
     id: includeDecisionId,
     type: "include-strategy",
@@ -2669,7 +2758,12 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
       // Foreign key info for json_agg compilation (Phase 3)
       ...relation.foreignKey !== void 0 && {
         foreignKey: relation.foreignKey
-      }
+      },
+      ...parentKey !== void 0 && { parentKey },
+      ...targetOrder.columns.length > 0 && {
+        targetPrimaryKey: targetOrder.columns
+      },
+      ...targetOrder.fallback && { orderByFallback: true }
     },
     choice: includeStrategy,
     // Embed joinType so the adapter's join handler can use it directly
@@ -6163,7 +6257,98 @@ import {
   NqlLexer,
   compile as nqlCompile
 } from "@dbsp/nql";
-import { NQL_INTERNAL_COMPILER_OPTIONS } from "@dbsp/types/internal";
+import { toColumnList as toColumnList2 } from "@dbsp/types";
+import {
+  explainUnsupportedNqlBindingIncludeHop,
+  getTrustedNqlRelationFilterFields,
+  NQL_INTERNAL_COMPILER_OPTIONS
+} from "@dbsp/types/internal";
+
+// src/dx/hydration-utils.ts
+function isRootIncludeDecision(decision) {
+  const intentPath = decision.context.intentPath;
+  return typeof intentPath !== "string" || !intentPath.includes(".include[");
+}
+function hydrateJsonAggIncludes(results, planReport) {
+  const jsonAggDecisions = planReport.decisions.filter(
+    (d) => d.type === "include-strategy" && d.choice === "json_agg" && isRootIncludeDecision(d)
+  );
+  if (jsonAggDecisions.length === 0) {
+    return;
+  }
+  const relationInfo = /* @__PURE__ */ new Map();
+  for (const decision of jsonAggDecisions) {
+    const canonicalName = decision.context?.relation;
+    const includeAlias = decision.context?.includeAlias;
+    const relationType = decision.context?.relationType;
+    const isToOne = relationType === "belongsTo" || relationType === "hasOne";
+    if (typeof canonicalName === "string") {
+      relationInfo.set(canonicalName, {
+        isToOne,
+        includeAlias: typeof includeAlias === "string" ? includeAlias : canonicalName,
+        canonicalName
+      });
+    } else if (typeof includeAlias === "string") {
+      relationInfo.set(includeAlias, { isToOne, includeAlias });
+    }
+  }
+  if (relationInfo.size === 0) {
+    return;
+  }
+  for (const row of results) {
+    if (typeof row !== "object" || row === null) {
+      continue;
+    }
+    const record2 = row;
+    for (const [relationName, info] of relationInfo) {
+      const candidates = [relationName];
+      if (info.includeAlias && info.includeAlias !== relationName) {
+        candidates.push(info.includeAlias);
+      }
+      let actualColumnName = null;
+      for (const baseName of candidates) {
+        const snakeJson = `${baseName}_json`;
+        const camelJson = snakeJson.replace(
+          /_([a-z])/g,
+          (_, c) => c.toUpperCase()
+        );
+        if (snakeJson in record2) {
+          actualColumnName = snakeJson;
+          break;
+        }
+        if (camelJson in record2) {
+          actualColumnName = camelJson;
+          break;
+        }
+      }
+      if (actualColumnName) {
+        const jsonValue = record2[actualColumnName];
+        let parsed;
+        if (typeof jsonValue === "string") {
+          try {
+            parsed = JSON.parse(jsonValue);
+          } catch {
+            parsed = info.isToOne ? null : [];
+          }
+        } else if (Array.isArray(jsonValue)) {
+          parsed = jsonValue;
+        } else if (jsonValue === null || jsonValue === void 0) {
+          parsed = info.isToOne ? null : [];
+        } else {
+          parsed = jsonValue;
+        }
+        if (info.isToOne && Array.isArray(parsed)) {
+          parsed = parsed.length > 0 ? parsed[0] : null;
+        }
+        const outputKey = info.includeAlias ?? relationName;
+        record2[outputKey] = parsed;
+        delete record2[actualColumnName];
+      }
+    }
+  }
+}
+
+// src/dx/nql.ts
 var NQL_RAW_FRAGMENT = /* @__PURE__ */ Symbol("NqlRawFragment");
 function hasNqlBindings(bundle) {
   return (bundle.bindings?.size ?? 0) > 0;
@@ -6186,6 +6371,9 @@ function findBindingFinalRelationFilter(where) {
     case "not":
       return findBindingFinalRelationFilter(where.condition);
     case "relationFilter":
+      if (getTrustedNqlRelationFilterFields(where) !== void 0) {
+        return void 0;
+      }
       return formatBindingRelationPath(where.relation);
     case "exists":
     case "notExists":
@@ -6197,21 +6385,340 @@ function findBindingFinalRelationFilter(where) {
       return void 0;
   }
 }
-function assertBindingFinalQueryCanUseSyntheticPlan(intent) {
-  const relationColumns = intent.select?.type === "expressions" ? intent.select.columns.filter((column) => column.kind === "relationColumn").map((column) => column.relation) : [];
+function bindingFinalIncludeError(bindingName, relation, reason) {
+  return new Error(
+    `NQL binding-final query '${bindingName}' cannot use relation include '${relation}' (ref-#192): ${reason}.`
+  );
+}
+function getBindingRelationMetadata(bundle, bindingName) {
+  return bundle.bindingOutputSchemas?.get(bindingName)?.relationFilters;
+}
+function getScalarBindingRelationsByName(bundle, bindingName) {
+  const metadata = getBindingRelationMetadata(bundle, bindingName);
+  const relations = /* @__PURE__ */ new Map();
+  for (const relation of metadata?.scalarRelations ?? []) {
+    relations.set(relation.relation, relation);
+  }
+  return relations;
+}
+function bindingIncludeNodeShape(include) {
+  return include;
+}
+function virtualRelationIncludeShape(relation) {
+  const relationType = relation.relationType;
+  const foreignKey = relationType === "belongsTo" ? relation.sourceColumn : relationType === "hasOne" || relationType === "hasMany" ? relation.targetColumn : void 0;
+  return {
+    type: relationType,
+    foreignKey,
+    source: relation.sourceTable,
+    target: relation.targetTable
+  };
+}
+var BINDING_INCLUDE_NODE_ONLY_RELATION = {
+  type: "hasMany",
+  foreignKey: "__dbsp_binding_include_node__",
+  source: "__dbsp_binding_include_source__",
+  target: "__dbsp_binding_include_target__"
+};
+function assertSupportedBindingIncludeNodeShape(bindingName, rootIncludeRelation, include, reasonPrefix = "") {
+  const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+    include.relation,
+    BINDING_INCLUDE_NODE_ONLY_RELATION,
+    bindingIncludeNodeShape(include)
+  );
+  if (unsupportedReason) {
+    throw bindingFinalIncludeError(
+      bindingName,
+      rootIncludeRelation,
+      `${reasonPrefix}${unsupportedReason}`
+    );
+  }
+}
+function bindingIncludeCoversRelationPath(include, segments) {
+  const [head, ...tail] = segments;
+  if (!head || include.relation !== head) return false;
+  if (tail.length === 0) return true;
+  return (include.include ?? []).some(
+    (child) => bindingIncludeCoversRelationPath(child, tail)
+  );
+}
+function bindingIncludesCoverRelationPath(includes, relationPath) {
+  const segments = relationPath.split(".");
+  if (segments.some((segment) => segment.length === 0)) return false;
+  return (includes ?? []).some(
+    (include) => bindingIncludeCoversRelationPath(include, segments)
+  );
+}
+function trustedBindingRelationColumnIsAdmitted(column) {
+  if (column.kind !== "relationColumn") return false;
+  const trusted = getTrustedNqlRelationFilterFields(column);
+  if (trusted?.selectedColumn === void 0) return false;
+  const isDotted = column.relation.split(".").length > 1;
+  if (trusted.cardinality === "one") {
+    return !isDotted || trusted.hops.length > 0;
+  }
+  return trusted.cardinality === "many" && trusted.relationType === "hasMany" && !isDotted && trusted.hops.length === 0;
+}
+function assertProvenBindingInclude(bindingName, include, provenRelations) {
+  const proven = provenRelations.get(include.relation);
+  if (!proven) {
+    throw bindingFinalIncludeError(
+      bindingName,
+      include.relation,
+      "the relation is not in the binding proven virtual-relation set"
+    );
+  }
+  const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+    include.relation,
+    virtualRelationIncludeShape(proven),
+    bindingIncludeNodeShape(include)
+  );
+  if (unsupportedReason) {
+    throw bindingFinalIncludeError(
+      bindingName,
+      include.relation,
+      unsupportedReason
+    );
+  }
+  return proven;
+}
+function getProvenBindingIncludes(intent, bundle) {
+  const provenRelations = getScalarBindingRelationsByName(bundle, intent.from);
+  const provenIncludes = /* @__PURE__ */ new Map();
+  for (const include of intent.include ?? []) {
+    const proven = assertProvenBindingInclude(
+      intent.from,
+      include,
+      provenRelations
+    );
+    provenIncludes.set(include.relation, proven);
+  }
+  return provenIncludes;
+}
+function assertBindingFinalQueryCanUseSyntheticPlan(intent, bundle) {
+  getProvenBindingIncludes(intent, bundle);
+  const relationColumns = intent.select?.type === "expressions" ? intent.select.columns.flatMap((column) => {
+    if (column.kind !== "relationColumn") return [];
+    if (column.column === "*" && bindingIncludesCoverRelationPath(intent.include, column.relation)) {
+      return [];
+    }
+    if (trustedBindingRelationColumnIsAdmitted(column)) {
+      return [];
+    }
+    return [column.relation];
+  }) : [];
   const relationFilter = intent.where ? findBindingFinalRelationFilter(intent.where) : void 0;
   const havingRelationFilter = intent.having ? findBindingFinalRelationFilter(intent.having) : void 0;
-  if ((intent.include?.length ?? 0) > 0 || relationColumns.length > 0 || (intent.joins?.length ?? 0) > 0 || relationFilter !== void 0 || havingRelationFilter !== void 0) {
+  if (relationColumns.length > 0 || (intent.joins?.length ?? 0) > 0 || relationFilter !== void 0 || havingRelationFilter !== void 0) {
     throw new Error(
       `NQL binding-final query '${intent.from}' cannot select relation columns, use includes, joins, or relation filters. Relation planning requires a physical model table, not a CTE binding.`
     );
   }
 }
-function createBindingFinalPlan(intent) {
-  assertBindingFinalQueryCanUseSyntheticPlan(intent);
+function createBindingIncludeDecision(intent, include, relation, index, model) {
+  const relationType = relation.relationType;
+  const foreignKey = relationType === "belongsTo" ? relation.sourceColumn : relation.targetColumn;
+  const parentKey = relationType === "belongsTo" ? relation.targetColumn : relation.sourceColumn;
+  const targetOrder = resolveTargetJsonAggOrderKey2(model, relation.targetTable);
+  return {
+    id: `binding-include-${index}`,
+    type: "include-strategy",
+    context: {
+      sourceTable: intent.from,
+      target: relation.targetTable,
+      relation: relation.relation,
+      relationType,
+      foreignKey,
+      parentKey,
+      ...targetOrder.columns.length > 0 && {
+        targetPrimaryKey: targetOrder.columns
+      },
+      ...targetOrder.fallback && { orderByFallback: true },
+      includeAlias: include.relation,
+      intentPath: `include[${index}]`
+    },
+    choice: "json_agg",
+    reasoning: "NQL binding-final include uses proven binding virtual relation metadata and the json_agg include pipeline.",
+    alternatives: []
+  };
+}
+function findModelRelation(model, sourceTable, relationName) {
+  return model.getRelation(`${sourceTable}.${relationName}`) ?? model.getRelationsFrom(sourceTable).find((relation) => relation.name === relationName);
+}
+function parentKeyForRelation(relation) {
+  if (relation.type === "belongsTo") return relation.targetKey;
+  return relation.sourceKey;
+}
+function resolveTargetJsonAggOrderKey2(model, targetTable) {
+  const table = model.getTable(targetTable);
+  if (!table) return { columns: [], fallback: false };
+  const pkColumns = toColumnList2(table.primaryKey);
+  return pkColumns.length > 0 ? { columns: pkColumns, fallback: false } : { columns: table.columns.map((col2) => col2.name), fallback: true };
+}
+function assertSupportedBindingIncludeHop(bindingName, rootIncludeRelation, relationName, relation, include, reasonPrefix = "") {
+  const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
+    relationName,
+    relation,
+    bindingIncludeNodeShape(include)
+  );
+  if (unsupportedReason) {
+    throw bindingFinalIncludeError(
+      bindingName,
+      rootIncludeRelation,
+      `${reasonPrefix}${unsupportedReason}`
+    );
+  }
+}
+function assertSupportedBindingTailIncludeTree(bindingName, rootInclude, sourceTable, includes, model) {
+  for (const include of includes) {
+    assertSupportedBindingIncludeNodeShape(
+      bindingName,
+      rootInclude.relation,
+      include,
+      "tail "
+    );
+    const relation = findModelRelation(model, sourceTable, include.relation);
+    if (!relation) {
+      throw bindingFinalIncludeError(
+        bindingName,
+        rootInclude.relation,
+        `tail relation '${include.relation}' is not declared on table '${sourceTable}'`
+      );
+    }
+    assertSupportedBindingIncludeHop(
+      bindingName,
+      rootInclude.relation,
+      include.relation,
+      relation,
+      include,
+      "tail "
+    );
+    assertSupportedBindingTailIncludeTree(
+      bindingName,
+      rootInclude,
+      relation.target,
+      include.include ?? [],
+      model
+    );
+  }
+}
+function rebaseBindingTailIntentPath(intentPath, includeIndex) {
+  return `include[${includeIndex}]${intentPath ? `.${intentPath}` : ""}`;
+}
+function createBindingTailIncludeDecisions(bindingName, include, firstHopRelation, includeIndex, model) {
+  const nestedIncludes = include.include ?? [];
+  if (nestedIncludes.length === 0) return [];
+  assertSupportedBindingTailIncludeTree(
+    bindingName,
+    include,
+    firstHopRelation.targetTable,
+    nestedIncludes,
+    model
+  );
+  const tailPlan = plan(
+    {
+      type: "select",
+      from: firstHopRelation.targetTable,
+      include: nestedIncludes
+    },
+    model,
+    { defaultIncludeStrategy: "json_agg" }
+  );
+  return tailPlan.decisions.filter((decision) => decision.type === "include-strategy").map((decision, tailIndex) => {
+    const sourceTable = decision.context.sourceTable;
+    const relationName = decision.context.relation;
+    if (!relationName) {
+      throw bindingFinalIncludeError(
+        bindingName,
+        include.relation,
+        "tail include planning produced a decision without a relation name"
+      );
+    }
+    const relation = findModelRelation(model, sourceTable, relationName);
+    if (!relation) {
+      throw bindingFinalIncludeError(
+        bindingName,
+        include.relation,
+        `tail relation '${relationName}' is not declared on table '${sourceTable}'`
+      );
+    }
+    assertSupportedBindingIncludeHop(
+      bindingName,
+      include.relation,
+      relationName,
+      relation,
+      { relation: relationName },
+      "tail "
+    );
+    const baseContext = { ...decision.context };
+    delete baseContext.foreignKey;
+    delete baseContext.parentKey;
+    delete baseContext.targetPrimaryKey;
+    delete baseContext.orderByFallback;
+    const parentKey = parentKeyForRelation(relation);
+    const targetOrder = resolveTargetJsonAggOrderKey2(model, relation.target);
+    return {
+      ...decision,
+      id: `binding-include-${includeIndex}-tail-${tailIndex}`,
+      choice: "json_agg",
+      reasoning: "NQL binding-final tail include uses real-table relation metadata and is forced through the json_agg include pipeline.",
+      context: {
+        ...baseContext,
+        sourceTable: relation.source,
+        target: relation.target,
+        relation: relation.name,
+        relationType: relation.type,
+        ...relation.foreignKey !== void 0 && {
+          foreignKey: relation.foreignKey
+        },
+        // Leave parentKey absent when RelationIR does not specify it so the
+        // adapter applies the same defaultPkColumnName fallback as real-table includes.
+        ...parentKey !== void 0 && { parentKey },
+        ...targetOrder.columns.length > 0 && {
+          targetPrimaryKey: targetOrder.columns
+        },
+        ...targetOrder.fallback && { orderByFallback: true },
+        intentPath: rebaseBindingTailIntentPath(
+          decision.context.intentPath,
+          includeIndex
+        )
+      }
+    };
+  });
+}
+function createBindingFinalPlan(intent, bundle, model, dialectCapabilities) {
+  assertBindingFinalQueryCanUseSyntheticPlan(intent, bundle);
+  const provenIncludes = getProvenBindingIncludes(intent, bundle);
+  const decisions = (intent.include ?? []).flatMap((include, index) => {
+    if (dialectCapabilities?.supportsJsonAgg === false) {
+      throw bindingFinalIncludeError(
+        intent.from,
+        include.relation,
+        "JSON aggregation for binding includes is not supported by this adapter"
+      );
+    }
+    const proven = provenIncludes.get(include.relation);
+    const firstHopDecision = createBindingIncludeDecision(
+      intent,
+      include,
+      proven,
+      index,
+      model
+    );
+    return [
+      firstHopDecision,
+      ...createBindingTailIncludeDecisions(
+        intent.from,
+        include,
+        proven,
+        index,
+        model
+      )
+    ];
+  });
   return {
     rootTable: intent.from,
-    decisions: [],
+    decisions,
     warnings: [],
     ctes: [],
     intent,
@@ -6222,6 +6729,11 @@ function createBindingFinalPlan(intent) {
     }
   };
 }
+function bindingFinalPlanHasJsonAggIncludes(planReport) {
+  return planReport.decisions.some(
+    (decision) => decision.type === "include-strategy" && decision.choice === "json_agg"
+  );
+}
 function nqlRaw(fragment) {
   if (typeof fragment !== "string") {
     throw new TypeError("nqlRaw() expects a string fragment");
@@ -6681,7 +7193,12 @@ var NqlBuilderImpl = class {
         "NQL mutations do not have execution plans; use dump() for SQL and parameters."
       );
     }
-    return isBindingFinalQuery(compiled.bundle) ? createBindingFinalPlan(compiled.intent) : this.planInternal();
+    return isBindingFinalQuery(compiled.bundle) ? createBindingFinalPlan(
+      compiled.intent,
+      compiled.bundle,
+      this.model,
+      this.adapter?.dialectCapabilities
+    ) : this.planInternal();
   }
   dump(meta) {
     const compiledIntent = this.compile();
@@ -6696,7 +7213,12 @@ var NqlBuilderImpl = class {
       );
     }
     const bindingFinalQuery = isBindingFinalQuery(compiledIntent.bundle);
-    const planReport = bindingFinalQuery ? createBindingFinalPlan(compiledIntent.intent) : this.planInternal();
+    const planReport = bindingFinalQuery ? createBindingFinalPlan(
+      compiledIntent.intent,
+      compiledIntent.bundle,
+      this.model,
+      this.adapter?.dialectCapabilities
+    ) : this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6705,7 +7227,10 @@ var NqlBuilderImpl = class {
         ...meta !== void 0 && { meta }
       };
     }
-    const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
+    const finalBundle = this.createFinalNqlStatementBundle(
+      compiledIntent,
+      bindingFinalPlanHasJsonAggIncludes(planReport) ? planReport : void 0
+    );
     const compiled = bindingFinalQuery || hasNqlBindings(finalBundle) ? this.adapter.compile(finalBundle, this.nqlBundleCompileOptions()) : this.adapter.compile(planReport);
     try {
       return this.adapter.createDump(planReport, compiled, meta);
@@ -6757,7 +7282,7 @@ var NqlBuilderImpl = class {
       ...this._schemaName !== void 0 && { schemaName: this._schemaName }
     };
   }
-  createNqlStatementBundle(statement, bindings, runtimeBindings, sourceBundle, bindingDependencies) {
+  createNqlStatementBundle(statement, bindings, runtimeBindings, sourceBundle, bindingDependencies, planReport) {
     const statementBindings = filterMapByRuntimeBindingDependencies(
       bindings,
       sourceBundle.mutationBindings,
@@ -6781,6 +7306,7 @@ var NqlBuilderImpl = class {
     );
     return {
       ...statement,
+      ...planReport !== void 0 && { plan: planReport },
       ...statementBindings.size > 0 && { bindings: statementBindings },
       ...statementBindingOutputSchemas !== void 0 && {
         bindingOutputSchemas: statementBindingOutputSchemas
@@ -6793,7 +7319,7 @@ var NqlBuilderImpl = class {
       }
     };
   }
-  createFinalNqlStatementBundle(compiledIntent) {
+  createFinalNqlStatementBundle(compiledIntent, planReport) {
     const finalStep = createNqlProgramSteps(compiledIntent).at(-1);
     if (compiledIntent.kind === "query") {
       return this.createNqlStatementBundle(
@@ -6801,7 +7327,8 @@ var NqlBuilderImpl = class {
         compiledIntent.bundle.bindings ?? /* @__PURE__ */ new Map(),
         compiledIntent.bundle.runtimeBindings ?? /* @__PURE__ */ new Map(),
         compiledIntent.bundle,
-        finalStep?.bindingDependencies
+        finalStep?.bindingDependencies,
+        planReport
       );
     }
     return this.createNqlStatementBundle(
@@ -6809,7 +7336,8 @@ var NqlBuilderImpl = class {
       compiledIntent.bundle.bindings ?? /* @__PURE__ */ new Map(),
       compiledIntent.bundle.runtimeBindings ?? /* @__PURE__ */ new Map(),
       compiledIntent.bundle,
-      finalStep?.bindingDependencies
+      finalStep?.bindingDependencies,
+      planReport
     );
   }
   runMutationStatement(adapter, bundle, intent, inTransaction) {
@@ -6898,18 +7426,28 @@ var NqlBuilderImpl = class {
             finalRows = rows.transformedRows;
           }
         } else if (step.final) {
+          const planReport = isBindingFinalQuery(compiledIntent.bundle) && compiledIntent.kind === "query" ? createBindingFinalPlan(
+            step.intent,
+            sourceBundle,
+            this.model,
+            txAdapter.dialectCapabilities
+          ) : void 0;
           const statementBundle = this.createNqlStatementBundle(
             { query: step.intent },
             priorBindings,
             runtimeBindings,
             sourceBundle,
-            step.bindingDependencies
+            step.bindingDependencies,
+            planReport !== void 0 && bindingFinalPlanHasJsonAggIncludes(planReport) ? planReport : void 0
           );
           const compiled = txAdapter.compile(
             statementBundle,
             this.nqlBundleCompileOptions()
           );
           finalRows = await txAdapter.execute(compiled);
+          if (planReport !== void 0 && bindingFinalPlanHasJsonAggIncludes(planReport)) {
+            hydrateJsonAggIncludes(finalRows, planReport);
+          }
         }
         if (step.bindName) {
           const boundQuery = sourceBundle.bindings?.get(step.bindName);
@@ -6954,12 +7492,19 @@ var NqlBuilderImpl = class {
           });
         }
       } else {
+        const planReport = step.final && isBindingFinalQuery(compiledIntent.bundle) && compiledIntent.kind === "query" ? createBindingFinalPlan(
+          step.intent,
+          sourceBundle,
+          this.model,
+          adapter.dialectCapabilities
+        ) : void 0;
         const statementBundle = this.createNqlStatementBundle(
           { query: step.intent },
           priorBindings,
           runtimeBindings,
           sourceBundle,
-          step.bindingDependencies
+          step.bindingDependencies,
+          planReport !== void 0 && bindingFinalPlanHasJsonAggIncludes(planReport) ? planReport : void 0
         );
         const compiled = adapter.compile(
           statementBundle,
@@ -6981,7 +7526,12 @@ var NqlBuilderImpl = class {
     }
     const finalStep = steps.at(-1);
     if (finalStep?.kind === "query") {
-      const planReport = isBindingFinalQuery(compiledIntent.bundle) ? createBindingFinalPlan(finalStep.intent) : this.planInternal();
+      const planReport = isBindingFinalQuery(compiledIntent.bundle) ? createBindingFinalPlan(
+        finalStep.intent,
+        compiledIntent.bundle,
+        this.model,
+        this.adapter?.dialectCapabilities
+      ) : this.planInternal();
       const dumpMeta2 = {
         compiledAt: /* @__PURE__ */ new Date(),
         ...this._schemaName !== void 0 && { schema: this._schemaName },
@@ -7057,11 +7607,24 @@ var NqlBuilderImpl = class {
       )).transformedRows;
     }
     if (isBindingFinalQuery(compiledIntent.bundle)) {
+      const planReport2 = createBindingFinalPlan(
+        compiledIntent.intent,
+        compiledIntent.bundle,
+        this.model,
+        adapter.dialectCapabilities
+      );
       const compiled2 = adapter.compile(
-        this.createFinalNqlStatementBundle(compiledIntent),
+        this.createFinalNqlStatementBundle(
+          compiledIntent,
+          bindingFinalPlanHasJsonAggIncludes(planReport2) ? planReport2 : void 0
+        ),
         this.nqlBundleCompileOptions()
       );
-      return adapter.execute(compiled2);
+      const rows = await adapter.execute(compiled2);
+      if (bindingFinalPlanHasJsonAggIncludes(planReport2)) {
+        hydrateJsonAggIncludes(rows, planReport2);
+      }
+      return rows;
     }
     const planReport = this.planInternal();
     const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
@@ -7376,85 +7939,8 @@ async function cursorPaginate(builder, options) {
   };
 }
 
-// src/dx/hydration-utils.ts
-function hydrateJsonAggIncludes(results, planReport) {
-  const jsonAggDecisions = planReport.decisions.filter(
-    (d) => d.type === "include-strategy" && d.choice === "json_agg"
-  );
-  if (jsonAggDecisions.length === 0) {
-    return;
-  }
-  const relationInfo = /* @__PURE__ */ new Map();
-  for (const decision of jsonAggDecisions) {
-    const canonicalName = decision.context?.relation;
-    const includeAlias = decision.context?.includeAlias;
-    const relationType = decision.context?.relationType;
-    const isToOne = relationType === "belongsTo" || relationType === "hasOne";
-    if (typeof canonicalName === "string") {
-      relationInfo.set(canonicalName, {
-        isToOne,
-        includeAlias: typeof includeAlias === "string" ? includeAlias : canonicalName,
-        canonicalName
-      });
-    } else if (typeof includeAlias === "string") {
-      relationInfo.set(includeAlias, { isToOne, includeAlias });
-    }
-  }
-  if (relationInfo.size === 0) {
-    return;
-  }
-  for (const row of results) {
-    if (typeof row !== "object" || row === null) {
-      continue;
-    }
-    const record2 = row;
-    for (const [relationName, info] of relationInfo) {
-      const candidates = [relationName];
-      if (info.includeAlias && info.includeAlias !== relationName) {
-        candidates.push(info.includeAlias);
-      }
-      let actualColumnName = null;
-      for (const baseName of candidates) {
-        const snakeJson = `${baseName}_json`;
-        const camelJson = snakeJson.replace(
-          /_([a-z])/g,
-          (_, c) => c.toUpperCase()
-        );
-        if (snakeJson in record2) {
-          actualColumnName = snakeJson;
-          break;
-        }
-        if (camelJson in record2) {
-          actualColumnName = camelJson;
-          break;
-        }
-      }
-      if (actualColumnName) {
-        const jsonValue = record2[actualColumnName];
-        let parsed;
-        if (typeof jsonValue === "string") {
-          try {
-            parsed = JSON.parse(jsonValue);
-          } catch {
-            parsed = info.isToOne ? null : [];
-          }
-        } else if (Array.isArray(jsonValue)) {
-          parsed = jsonValue;
-        } else if (jsonValue === null || jsonValue === void 0) {
-          parsed = info.isToOne ? null : [];
-        } else {
-          parsed = jsonValue;
-        }
-        if (info.isToOne && Array.isArray(parsed)) {
-          parsed = parsed.length > 0 ? parsed[0] : null;
-        }
-        const outputKey = info.includeAlias ?? relationName;
-        record2[outputKey] = parsed;
-        delete record2[actualColumnName];
-      }
-    }
-  }
-}
+// src/dx/result-hydrator.ts
+import { toColumnList as toColumnList3 } from "@dbsp/types";
 
 // src/dx/relation-paths.ts
 function nonEmptyString(value) {
@@ -7619,7 +8105,7 @@ var ResultHydrator = class {
     for (const includeInfo of subqueryIncludes) {
       const parentIds = [];
       for (const r of results) {
-        const id = this.extractKeyValue(
+        const id = this.extractQueryKeyValue(
           r,
           includeInfo.sourceKey
         );
@@ -7831,14 +8317,16 @@ var ResultHydrator = class {
    * Get the foreign key column name from relation metadata.
    */
   getForeignKeyColumn(foreignKey) {
-    if (!foreignKey) {
+    const columns = toColumnList3(foreignKey);
+    if (columns.length === 0) {
       return "parent_id";
     }
-    if (typeof foreignKey === "string") {
-      return foreignKey;
+    if (columns.length !== 1) {
+      throw new Error(
+        `Recursive include hydration requires a single-column self-referential foreign key; got ${JSON.stringify(columns)}.`
+      );
     }
-    const first = foreignKey[0];
-    return first ?? "parent_id";
+    return columns[0];
   }
   /**
    * Build traversal config for recursive CTE.
@@ -7930,10 +8418,14 @@ var ResultHydrator = class {
    * case (slower but collision-safe for any value content).
    */
   extractKeyValue(obj, key) {
-    if (typeof key === "string") {
-      return obj[key];
+    const columns = toColumnList3(key);
+    if (columns.length === 0) {
+      return void 0;
     }
-    const values = key.map((k) => obj[k]);
+    if (columns.length === 1) {
+      return obj[columns[0]];
+    }
+    const values = columns.map((k) => obj[k]);
     if (values.some((v2) => v2 === void 0 || v2 === null)) {
       return void 0;
     }
@@ -7943,6 +8435,17 @@ var ResultHydrator = class {
     }
     return parts.join(COMPOSITE_KEY_SEP);
   }
+  extractQueryKeyValue(obj, key) {
+    const columns = toColumnList3(key);
+    if (columns.length === 0) {
+      return void 0;
+    }
+    if (columns.length === 1) {
+      return obj[columns[0]];
+    }
+    const values = columns.map((k) => obj[k]);
+    return values.some((v2) => v2 === void 0 || v2 === null) ? void 0 : values;
+  }
 };
 
 // src/dx/set-operation-builder.ts
@@ -10416,13 +10919,18 @@ function mapRelationType2(kind) {
       return "belongsToMany";
   }
 }
+function isGeneratedTableWithConfig(table) {
+  const columns = table.columns;
+  return typeof columns === "object" && columns !== null && typeof columns.type !== "string";
+}
 function buildTableIRFromDefinition(tableName, genTable, fkAutoIndex) {
   const columns = [];
   const foreignKeys = [];
   const indexes = [];
   const primaryKeys = [];
+  const tableColumns = isGeneratedTableWithConfig(genTable) ? genTable.columns : genTable;
   const indexedColumns = /* @__PURE__ */ new Set();
-  for (const [colName, colDef] of Object.entries(genTable)) {
+  for (const [colName, colDef] of Object.entries(tableColumns)) {
     const col2 = {
       name: colName,
       type: generatedTypeToColumnType(colDef.type),
@@ -10475,7 +10983,7 @@ function buildTableIRFromDefinition(tableName, genTable, fkAutoIndex) {
     const fkColumn = fk.columns[0];
     const targetColumn = fk.references.columns[0];
     if (fk.references.table === tableName && fkColumn !== void 0 && targetColumn !== void 0) {
-      const colDef = genTable[fkColumn];
+      const colDef = tableColumns[fkColumn];
       const inferredName = fkColumn.endsWith("Id") ? fkColumn.slice(0, -2) : "parent";
       const parentRole = colDef?.references?.parentRole ?? inferredName;
       const childRole = colDef?.references?.childRole ?? (parentRole === "parent" ? "children" : `${parentRole}s`);
@@ -10491,7 +10999,10 @@ function buildTableIRFromDefinition(tableName, genTable, fkAutoIndex) {
     }
   }
   let primaryKey;
-  if (primaryKeys.length > 0) {
+  const configuredPrimaryKey = isGeneratedTableWithConfig(genTable) ? genTable.primaryKey : void 0;
+  if (configuredPrimaryKey !== void 0) {
+    primaryKey = configuredPrimaryKey;
+  } else if (primaryKeys.length > 0) {
     primaryKey = primaryKeys.length === 1 ? primaryKeys[0] : primaryKeys;
   } else {
     const fkColumns = foreignKeys.flatMap((fk) => fk.columns);
@@ -10502,6 +11013,27 @@ function buildTableIRFromDefinition(tableName, genTable, fkAutoIndex) {
       primaryKey = hasId ? "id" : void 0;
     }
   }
+  if (isGeneratedTableWithConfig(genTable)) {
+    for (const fk of genTable.foreignKeys ?? []) {
+      const foreignKey = {
+        columns: [...fk.columns],
+        references: {
+          table: fk.references.table,
+          columns: [...fk.references.columns]
+        }
+      };
+      if (fk.onDelete) foreignKey.onDelete = fk.onDelete;
+      if (fk.onUpdate) foreignKey.onUpdate = fk.onUpdate;
+      foreignKeys.push(foreignKey);
+    }
+    for (const index of genTable.indexes ?? []) {
+      indexes.push({
+        columns: [...index.columns],
+        unique: index.unique ?? false,
+        ...index.name !== void 0 && { name: index.name }
+      });
+    }
+  }
   const frozenColumns = Object.freeze(columns);
   return Object.freeze({
     name: tableName,
@@ -10685,6 +11217,7 @@ var ForeignKeyReferenceSchema = v.object({
   parentRole: v.optional(v.string()),
   childRole: v.optional(v.string())
 });
+var StringOrStringArraySchema = v.union([v.string(), v.array(v.string())]);
 var ColumnDefinitionSchema = v.object({
   type: SchemaColumnTypeSchema,
   primaryKey: v.optional(v.boolean()),
@@ -10698,7 +11231,24 @@ var ColumnDefinitionSchema = v.object({
 var FlatTableDefinitionSchema = safeRecord(ColumnDefinitionSchema);
 var TableDefWithConfigSchema = v.object({
   columns: FlatTableDefinitionSchema,
-  primaryKey: v.array(v.string()),
+  primaryKey: v.optional(StringOrStringArraySchema),
+  foreignKeys: v.optional(
+    v.array(
+      v.object({
+        columns: v.array(v.string()),
+        references: v.object({
+          table: v.string(),
+          columns: v.array(v.string())
+        }),
+        onDelete: v.optional(
+          v.picklist(["CASCADE", "SET NULL", "RESTRICT", "NO ACTION"])
+        ),
+        onUpdate: v.optional(
+          v.picklist(["CASCADE", "SET NULL", "RESTRICT", "NO ACTION"])
+        )
+      })
+    )
+  ),
   indexes: v.optional(
     v.array(
       v.object({
@@ -10720,15 +11270,15 @@ var IncludeStrategySchema = v.optional(
 var BelongsToRelationSchema = v.object({
   kind: v.literal("belongsTo"),
   target: v.string(),
-  foreignKey: v.string(),
-  targetKey: v.optional(v.string()),
+  foreignKey: StringOrStringArraySchema,
+  targetKey: v.optional(StringOrStringArraySchema),
   includeStrategy: IncludeStrategySchema
 });
 var HasManyRelationSchema = v.object({
   kind: v.literal("hasMany"),
   target: v.string(),
-  foreignKey: v.string(),
-  sourceKey: v.optional(v.string()),
+  foreignKey: StringOrStringArraySchema,
+  sourceKey: v.optional(StringOrStringArraySchema),
   includeStrategy: IncludeStrategySchema
 });
 var ManyToManyRelationSchema = v.object({