@vibeorm/runtime 1.3.0 → 2.0.0-alpha.2

package/src/query-builder.ts

@@ -1,1832 +0,0 @@
-/**
- * SQL Query Builder
- *
- * Takes an operation descriptor (model, operation, args) and produces
- * parameterized SQL queries for PostgreSQL.
- */
-
-import type {
-  ModelMeta,
-  ModelMetaMap,
-  SqlQuery,
-  Operation,
-  ScalarFieldMeta,
-} from "./types.ts";
-import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
-import { buildWhereClause } from "./where-builder.ts";
-
-// ─── Scalar List Helpers ──────────────────────────────────────────
-
-/**
- * Wrap a value in PgArray if the corresponding field is a scalar list (e.g. String[], Int[]).
- * This ensures adapters serialize the JS array as a PostgreSQL array literal
- * rather than passing it as a raw array or JSON string.
- */
-function wrapListValue(params: { value: unknown; field: ScalarFieldMeta }): unknown {
-  if (params.field.isList && Array.isArray(params.value)) {
-    return new PgArray(params.value);
-  }
-  return params.value;
-}
-
-// ─── SQL Direction Sanitizer ──────────────────────────────────────
-
-const VALID_DIRECTIONS = new Set(["ASC", "DESC"]);
-
-/** Sanitize an ORDER BY direction to prevent SQL injection via untrusted input. */
-export function sanitizeDirection(params: { direction: string }): string {
-  const upper = params.direction.toUpperCase();
-  return VALID_DIRECTIONS.has(upper) ? upper : "ASC";
-}
-
-function reverseDirection(params: { direction: string }): string {
-  const normalized = sanitizeDirection({ direction: params.direction });
-  return normalized === "ASC" ? "DESC" : "ASC";
-}
-
-function getScalarFieldOrThrow(params: {
-  sfMap: ReadonlyMap<string, ScalarFieldMeta>;
-  field: string;
-  modelName: string;
-  context: string;
-}): ScalarFieldMeta {
-  const scalarField = params.sfMap.get(params.field);
-  if (!scalarField) {
-    throw new Error(
-      `Unknown field "${params.field}" in ${params.context} for model "${params.modelName}"`
-    );
-  }
-  return scalarField;
-}
-
-function getTakeValue(params: { args: Record<string, unknown> }): number | undefined {
-  const take = params.args.take;
-  return typeof take === "number" ? take : undefined;
-}
-
-const AGGREGATE_SQL_FN_BY_KEY = new Map<string, string>([
-  ["_count", "COUNT"],
-  ["_avg", "AVG"],
-  ["_sum", "SUM"],
-  ["_min", "MIN"],
-  ["_max", "MAX"],
-]);
-
-function getAggregateSqlFnOrThrow(params: { aggregateKey: string }): string {
-  const sqlFn = AGGREGATE_SQL_FN_BY_KEY.get(params.aggregateKey);
-  if (!sqlFn) {
-    throw new Error(`Unsupported aggregate function "${params.aggregateKey}"`);
-  }
-  return sqlFn;
-}
-
-// ─── SELECT Builder ───────────────────────────────────────────────
-
-export function buildSelectQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  defaultOrderByPk?: boolean;
-  distinctOrderByPk?: boolean;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, args, defaultOrderByPk = false, distinctOrderByPk = true } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-  const take = getTakeValue({ args });
-
-  // Negative take is only valid with cursor-based pagination (backward page)
-  if (take !== undefined && take < 0 && args.cursor === undefined) {
-    throw new Error(
-      `Negative \`take\` (${take}) is only supported with cursor-based pagination on model "${modelMeta.name}". Provide a \`cursor\` argument or use a positive \`take\` value.`
-    );
-  }
-
-  const isBackwardCursor = args.cursor !== undefined && take !== undefined && take < 0;
-
-  // Determine which columns to select
-  const columns = resolveSelectColumns({ modelMeta, args });
-  const columnsSql = columns
-    .map((c) => `${table}."${c.dbName}" AS "${c.name}"`)
-    .join(", ");
-
-  // DISTINCT ON support (PostgreSQL)
-  let distinctSql = "";
-  if (args.distinct) {
-    const distinctFields = args.distinct as string[];
-    if (distinctFields.length > 0) {
-      const distinctCols = distinctFields.map((field) => {
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: "distinct",
-        });
-        return `${table}."${sf.dbName}"`;
-      });
-      distinctSql = `DISTINCT ON (${distinctCols.join(", ")}) `;
-    }
-  }
-
-  // Build WHERE — start with explicit where, then add cursor condition
-  let where = args.where as Record<string, unknown> | undefined;
-
-  // Cursor-based pagination: inject cursor condition into WHERE
-  // For composite cursors we need lexicographic ordering:
-  //   (a > $1) OR (a = $1 AND b > $2) OR (a = $1 AND b = $2 AND c > $3) ...
-  if (args.cursor) {
-    const cursorInput = args.cursor as Record<string, unknown>;
-    const cursorEntries = Object.entries(cursorInput).filter(
-      ([, v]) => v !== undefined
-    );
-
-    // Determine the default comparison direction from take sign
-    const isBackward = isBackwardCursor;
-
-    // Resolve per-field ORDER BY directions so the cursor comparator aligns
-    // with the sort direction. For DESC ordering, forward pagination uses `lt`
-    // instead of `gt` so that the cursor skips to the next descending page.
-    const orderByDirMap = new Map<string, string>();
-    if (args.orderBy) {
-      const orderByItems = Array.isArray(args.orderBy)
-        ? (args.orderBy as Record<string, unknown>[])
-        : [args.orderBy as Record<string, unknown>];
-      for (const item of orderByItems) {
-        for (const [field, dir] of Object.entries(item)) {
-          if (typeof dir === "string") {
-            orderByDirMap.set(field, dir.toUpperCase());
-          } else if (typeof dir === "object" && dir !== null) {
-            const dirObj = dir as Record<string, unknown>;
-            if (typeof dirObj.sort === "string") {
-              orderByDirMap.set(field, (dirObj.sort as string).toUpperCase());
-            }
-          }
-        }
-      }
-    }
-
-    /**
-     * Resolve the cursor comparison operator for a given field.
-     * - Forward (take >= 0) + ASC  → gt  (skip rows below cursor)
-     * - Forward (take >= 0) + DESC → lt  (skip rows above cursor)
-     * - Backward (take < 0) + ASC  → lt  (reverse direction)
-     * - Backward (take < 0) + DESC → gt  (reverse direction)
-     */
-    const cmpOpForField = (field: string): string => {
-      const dir = orderByDirMap.get(field) ?? "ASC";
-      const isDesc = dir === "DESC";
-      // Forward + ASC = gt, Forward + DESC = lt, Backward flips
-      return (isDesc !== isBackward) ? "lt" : "gt";
-    };
-
-    let cursorWhere: Record<string, unknown> | undefined;
-
-    if (cursorEntries.length === 1) {
-      // Single-field cursor: simple gt/lt (most common case)
-      const [field, value] = cursorEntries[0]!;
-      cursorWhere = { [field]: { [cmpOpForField(field)]: value } };
-    } else if (cursorEntries.length > 1) {
-      // Composite cursor: build lexicographic OR conditions
-      // For fields [a, b, c] with forward:
-      //   (a > v1) OR (a = v1 AND b > v2) OR (a = v1 AND b = v2 AND c > v3)
-      const orBranches: Record<string, unknown>[] = [];
-      for (let i = 0; i < cursorEntries.length; i++) {
-        const branch: Record<string, unknown> = {};
-        // All preceding fields must equal their cursor values
-        for (let j = 0; j < i; j++) {
-          const [eqField, eqValue] = cursorEntries[j]!;
-          branch[eqField] = { equals: eqValue };
-        }
-        // The i-th field uses the field-specific comparison operator
-        const [cmpField, cmpValue] = cursorEntries[i]!;
-        branch[cmpField] = { [cmpOpForField(cmpField)]: cmpValue };
-        orBranches.push(branch);
-      }
-      cursorWhere = { OR: orBranches };
-    }
-
-    // Merge cursor conditions with existing where via AND
-    if (cursorWhere) {
-      where = where
-        ? { AND: [where, cursorWhere] }
-        : cursorWhere;
-    }
-  }
-
-  const whereResult = buildWhereClause({
-    where,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: 0,
-  });
-
-  let paramIdx = whereResult.values.length;
-  const allValues = [...whereResult.values];
-
-  // Build ORDER BY
-  let orderBySql = "";
-  const orderByJoins: string[] = [];
-  // Track joined relation aliases to avoid duplicate LEFT JOINs when the
-  // same relation appears multiple times in orderBy (e.g., { author: { name: "asc" } }, { author: { email: "desc" } })
-  const joinedRelationAliases = new Set<string>();
-
-  if (args.orderBy) {
-    const orderByItems = Array.isArray(args.orderBy)
-      ? (args.orderBy as Record<string, unknown>[])
-      : [args.orderBy as Record<string, unknown>];
-
-    const orderClauses = orderByItems.flatMap((item) =>
-      Object.entries(item).map(([field, direction]) => {
-        // Null ordering: { sort: "desc", nulls: "last" }
-        if (typeof direction === "object" && direction !== null) {
-          const dirObj = direction as Record<string, unknown>;
-
-          // SortOrderWithNulls: { sort: "asc", nulls: "last" }
-          if (dirObj.sort && typeof dirObj.sort === "string") {
-            const scalarField = getScalarFieldOrThrow({
-              sfMap,
-              field,
-              modelName: modelMeta.name,
-              context: "orderBy",
-            });
-            const direction = isBackwardCursor
-              ? reverseDirection({ direction: dirObj.sort as string })
-              : (dirObj.sort as string);
-            let clause = `${table}."${scalarField.dbName}" ${sanitizeDirection({ direction })}`;
-            if (dirObj.nulls === "first") clause += " NULLS FIRST";
-            else if (dirObj.nulls === "last") clause += " NULLS LAST";
-            return clause;
-          }
-
-          // Relation count ordering: { posts: { _count: "desc" } }
-          // NOTE: Uses a correlated subquery per row. PostgreSQL's planner typically
-          // converts this to a hash/merge join internally. An explicit LEFT JOIN on a
-          // pre-aggregated subquery would be an alternative, but adds complexity and
-          // risk for marginal gain on typical result sets (<10k rows).
-          if (dirObj._count && typeof dirObj._count === "string") {
-            const relField = modelMeta.relationFields.find((r) => r.name === field);
-            if (relField) {
-              const modelMap = getModelByNameMap({ allModelsMeta });
-              const relatedMeta = modelMap.get(relField.relatedModel);
-              if (relatedMeta) {
-                const reverseRel = relatedMeta.relationFields.find(
-                  (r: { relatedModel: string; isForeignKey: boolean; fields: readonly string[] }) =>
-                    r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
-                );
-                if (reverseRel) {
-                  const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
-                  const fkScalar = relatedSfMap.get(reverseRel.fields[0]!);
-                  const fkDbName = fkScalar?.dbName ?? reverseRel.fields[0]!;
-                  const parentPk = modelMeta.primaryKey[0]!;
-                  const parentSf = sfMap.get(parentPk);
-                  const parentPkDb = parentSf?.dbName ?? parentPk;
-                  const direction = isBackwardCursor
-                    ? reverseDirection({ direction: dirObj._count as string })
-                    : (dirObj._count as string);
-                  return `(SELECT COUNT(*) FROM "${relatedMeta.dbName}" WHERE "${relatedMeta.dbName}"."${fkDbName}" = ${table}."${parentPkDb}") ${sanitizeDirection({ direction })}`;
-                }
-              }
-            }
-            throw new Error(
-              `Unknown relation field "${field}" in orderBy._count for model "${modelMeta.name}"`
-            );
-          }
-
-          // Relation field ordering: { author: { name: "asc" } }
-          const relField = modelMeta.relationFields.find((r) => r.name === field);
-          if (relField && !relField.isList) {
-            const modelMap = getModelByNameMap({ allModelsMeta });
-            const relatedMeta = modelMap.get(relField.relatedModel);
-            if (relatedMeta) {
-              const relatedAlias = `"__orderby_${field}"`;
-
-              // Only emit the LEFT JOIN once per relation alias
-              if (!joinedRelationAliases.has(field)) {
-                joinedRelationAliases.add(field);
-                // Determine join condition
-                let joinCond: string;
-                if (relField.isForeignKey && relField.fields.length > 0) {
-                  const fkScalar = sfMap.get(relField.fields[0]!);
-                  const fkDbName = fkScalar?.dbName ?? relField.fields[0]!;
-                  const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
-                  const refScalar = relatedSfMap.get(relField.references[0]!);
-                  const refDbName = refScalar?.dbName ?? relField.references[0]!;
-                  joinCond = `${relatedAlias}."${refDbName}" = ${table}."${fkDbName}"`;
-                } else {
-                  const reverseRel = relatedMeta.relationFields.find(
-                    (r: { relatedModel: string; isForeignKey: boolean; fields: readonly string[] }) =>
-                      r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
-                  );
-                  if (reverseRel) {
-                    const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
-                    const fkScalar = relatedSfMap.get(reverseRel.fields[0]!);
-                    const fkDbName = fkScalar?.dbName ?? reverseRel.fields[0]!;
-                    const refScalar = sfMap.get(reverseRel.references[0]!);
-                    const refDbName = refScalar?.dbName ?? reverseRel.references[0]!;
-                    joinCond = `${relatedAlias}."${fkDbName}" = ${table}."${refDbName}"`;
-                  } else {
-                    joinCond = "TRUE";
-                  }
-                }
-                orderByJoins.push(`LEFT JOIN "${relatedMeta.dbName}" ${relatedAlias} ON ${joinCond}`);
-              }
-
-              // Get the ordering field from the relation object
-              const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
-              return Object.entries(dirObj).map(([relField2, relDir]) => {
-                if (typeof relDir !== "string") {
-                  throw new Error(
-                    `Unsupported orderBy direction for relation field "${field}.${relField2}" on model "${modelMeta.name}"`
-                  );
-                }
-                const relSf = getScalarFieldOrThrow({
-                  sfMap: relatedSfMap,
-                  field: relField2,
-                  modelName: relatedMeta.name,
-                  context: `orderBy.${field}`,
-                });
-                const direction = isBackwardCursor
-                  ? reverseDirection({ direction: relDir })
-                  : relDir;
-                return `${relatedAlias}."${relSf.dbName}" ${sanitizeDirection({ direction })}`;
-              }).join(", ");
-            }
-          }
-        }
-
-        // Simple scalar ordering — only allow known scalar fields
-        if (typeof direction !== "string") {
-          throw new Error(
-            `Unsupported orderBy direction for field "${field}" on model "${modelMeta.name}"`
-          );
-        }
-        const scalarField = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: "orderBy",
-        });
-        const resolvedDirection = isBackwardCursor
-          ? reverseDirection({ direction })
-          : direction;
-        return `${table}."${scalarField.dbName}" ${sanitizeDirection({ direction: resolvedDirection })}`;
-      })
-    );
-
-    const validOrderClauses = orderClauses;
-
-    if (validOrderClauses.length > 0) {
-      // When DISTINCT ON is used with explicit orderBy, PostgreSQL requires
-      // the DISTINCT ON expressions to match the leftmost ORDER BY terms.
-      // Prepend distinct columns that aren't already leading the ORDER BY.
-      if (args.distinct) {
-        const distinctFields = args.distinct as string[];
-        const distinctPrefixClauses = distinctFields.map((field) => {
-          const sf = getScalarFieldOrThrow({
-            sfMap,
-            field,
-            modelName: modelMeta.name,
-            context: "distinct",
-          });
-          return `${table}."${sf.dbName}"`;
-        });
-        // Build a set of column refs that are already leading ORDER BY terms
-        const existingLeadCols = new Set(
-          validOrderClauses.slice(0, distinctFields.length).map((clause) => {
-            // Extract the column ref (everything before the direction keyword)
-            const match = clause.match(/^(.+?)\s+(ASC|DESC)/i);
-            return match ? match[1]!.trim() : clause.trim();
-          })
-        );
-        // Prepend any distinct columns not already at the front
-        const missingPrefixes = distinctPrefixClauses.filter((col) => !existingLeadCols.has(col));
-        let combinedClauses: string[];
-        if (missingPrefixes.length > 0) {
-          const prefixOrderClauses = missingPrefixes.map((col) => `${col} ASC`);
-          combinedClauses = [...prefixOrderClauses, ...validOrderClauses];
-        } else {
-          combinedClauses = [...validOrderClauses];
-        }
-        // Add PK tie-breaker for deterministic row selection per distinct group
-        if (distinctOrderByPk) {
-          const allOrderColRefs = new Set(
-            combinedClauses.map((clause) => {
-              const match = clause.match(/^(.+?)\s+(ASC|DESC)/i);
-              return match ? match[1]!.trim() : clause.trim();
-            })
-          );
-          for (const pkName of modelMeta.primaryKey) {
-            const pkSf = sfMap.get(pkName);
-            if (pkSf) {
-              const pkRef = `${table}."${pkSf.dbName}"`;
-              if (!allOrderColRefs.has(pkRef)) {
-                combinedClauses.push(`${pkRef} ASC`);
-              }
-            }
-          }
-        }
-        orderBySql = ` ORDER BY ${combinedClauses.join(", ")}`;
-      } else {
-        orderBySql = ` ORDER BY ${validOrderClauses.join(", ")}`;
-      }
-    }
-  } else if (args.distinct) {
-    // DISTINCT ON requires ORDER BY on the same columns first
-    const distinctFields = args.distinct as string[];
-    if (distinctFields.length > 0) {
-      const distinctOrderClauses = distinctFields.map((field) => {
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: "distinct",
-        });
-        return `${table}."${sf.dbName}" ASC`;
-      });
-      // Add PK tie-breaker for deterministic row selection per distinct group
-      if (distinctOrderByPk) {
-        const distinctFieldSet = new Set(distinctFields);
-        for (const pkName of modelMeta.primaryKey) {
-          if (!distinctFieldSet.has(pkName)) {
-            const pkSf = sfMap.get(pkName);
-            if (pkSf) {
-              distinctOrderClauses.push(`${table}."${pkSf.dbName}" ASC`);
-            }
-          }
-        }
-      }
-      orderBySql = ` ORDER BY ${distinctOrderClauses.join(", ")}`;
-    }
-  } else if (args.cursor) {
-    // Cursor pagination without explicit orderBy: default to ordering by cursor
-    // fields to ensure deterministic results and proper index utilization.
-    const cursorInput = args.cursor as Record<string, unknown>;
-    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
-    const take = args.take as number | undefined;
-    const isBackward = take !== undefined && take < 0;
-    const defaultDir = isBackward ? "DESC" : "ASC";
-    const cursorOrderClauses = cursorEntries.map(([field]) => {
-      const sf = getScalarFieldOrThrow({
-        sfMap,
-        field,
-        modelName: modelMeta.name,
-        context: "cursor",
-      });
-      return `${table}."${sf.dbName}" ${defaultDir}`;
-    });
-    if (cursorOrderClauses.length > 0) {
-      orderBySql = ` ORDER BY ${cursorOrderClauses.join(", ")}`;
-    }
-  } else if (defaultOrderByPk) {
-    // Default ORDER BY primary key for deterministic results
-    const pkOrderClauses: string[] = [];
-    for (const pkName of modelMeta.primaryKey) {
-      const pkSf = sfMap.get(pkName);
-      if (pkSf) {
-        pkOrderClauses.push(`${table}."${pkSf.dbName}" ASC`);
-      }
-    }
-    if (pkOrderClauses.length > 0) {
-      orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
-    }
-  }
-
-  // Build LIMIT / OFFSET
-  let limitSql = "";
-  if (take !== undefined) {
-    paramIdx++;
-    // take can be negative for backward cursor pagination; use absolute value
-    const takeValue = Math.abs(take);
-    limitSql = ` LIMIT $${paramIdx}`;
-    allValues.push(takeValue);
-  }
-
-  let offsetSql = "";
-  if (args.skip !== undefined) {
-    paramIdx++;
-    offsetSql = ` OFFSET $${paramIdx}`;
-    allValues.push(args.skip);
-  }
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-  const joinsPart = orderByJoins.length > 0 ? ` ${orderByJoins.join(" ")}` : "";
-  const text = `SELECT ${distinctSql}${columnsSql} FROM ${table}${joinsPart}${wherePart}${orderBySql}${limitSql}${offsetSql}`;
-
-  return { text, values: allValues };
-}
-
-// ─── INSERT Builder ───────────────────────────────────────────────
-
-export function buildInsertQuery(params: {
-  modelMeta: ModelMeta;
-  data: Record<string, unknown>;
-  args?: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, data, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  // Filter to only scalar fields that are present in data
-  const entries: Array<{ dbName: string; value: unknown }> = [];
-
-  for (const [key, value] of Object.entries(data)) {
-    if (value === undefined) continue;
-    const scalarField = sfMap.get(key);
-    if (scalarField) {
-      entries.push({ dbName: scalarField.dbName, value: wrapListValue({ value, field: scalarField }) });
-    }
-  }
-
-  if (entries.length === 0) {
-    // Insert with default values only
-    const returningCols = resolveMutationReturningColumns({ modelMeta, args });
-    return {
-      text: `INSERT INTO ${table} DEFAULT VALUES RETURNING ${returningCols}`,
-      values: [],
-    };
-  }
-
-  const columns = entries.map((e) => `"${e.dbName}"`).join(", ");
-  const placeholders = entries.map((_, i) => `$${i + 1}`).join(", ");
-  const values = entries.map((e) => e.value);
-
-  const returningCols = resolveMutationReturningColumns({ modelMeta, args });
-
-  const text = `INSERT INTO ${table} (${columns}) VALUES (${placeholders}) RETURNING ${returningCols}`;
-
-  return { text, values };
-}
-
-// ─── UPDATE Builder ───────────────────────────────────────────────
-
-export function buildUpdateQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  where: Record<string, unknown>;
-  data: Record<string, unknown>;
-  args?: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, where, data, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  let paramIdx = 0;
-  const allValues: unknown[] = [];
-  const setClauses: string[] = [];
-
-  for (const [key, value] of Object.entries(data)) {
-    if (value === undefined) continue;
-    const scalarField = sfMap.get(key);
-    if (!scalarField) continue;
-
-    const setResult = buildSetClause({
-      dbName: scalarField.dbName,
-      value,
-      paramIdx,
-      field: scalarField,
-    });
-    setClauses.push(setResult.sql);
-    allValues.push(...setResult.values);
-    paramIdx += setResult.values.length;
-  }
-
-  // Build WHERE
-  const whereResult = buildWhereClause({
-    where,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: paramIdx,
-  });
-  allValues.push(...whereResult.values);
-
-  const returningCols = resolveMutationReturningColumns({ modelMeta, args });
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-
-  // No scalar updates to apply. Avoid a no-op write and return the matched row
-  // using a read query so callers still get update-style payload semantics.
-  if (setClauses.length === 0) {
-    const text = `SELECT ${returningCols} FROM ${table}${wherePart} LIMIT 1`;
-    return { text, values: allValues };
-  }
-
-  const text = `UPDATE ${table} SET ${setClauses.join(", ")}${wherePart} RETURNING ${returningCols}`;
-
-  return { text, values: allValues };
-}
-
-// ─── DELETE Builder ───────────────────────────────────────────────
-
-export function buildDeleteQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  where: Record<string, unknown>;
-  args?: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, where, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-
-  const whereResult = buildWhereClause({
-    where,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: 0,
-  });
-
-  const returningCols = resolveMutationReturningColumns({ modelMeta, args });
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-  const text = `DELETE FROM ${table}${wherePart} RETURNING ${returningCols}`;
-
-  return { text, values: whereResult.values };
-}
-
-// ─── COUNT Builder ────────────────────────────────────────────────
-
-export function buildCountQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  countStrategy?: "direct" | "subquery";
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, args, countStrategy = "direct" } = params;
-  const table = `"${modelMeta.dbName}"`;
-
-  const operationCountStrategy = args.countStrategy;
-  const resolvedCountStrategy =
-    operationCountStrategy === "direct" || operationCountStrategy === "subquery"
-      ? operationCountStrategy
-      : countStrategy;
-
-  const whereResult = buildWhereClause({
-    where: args.where as Record<string, unknown> | undefined,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: 0,
-  });
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-
-  if (resolvedCountStrategy === "subquery") {
-    // Wrap in a subquery with OFFSET 0. This can produce better query plans
-    // on serverless/proxy PostgreSQL providers where the standard COUNT(*)
-    // path chooses a suboptimal plan. The OFFSET 0 is a no-op but prevents
-    // PostgreSQL from flattening the subquery, which can change plan choice.
-    const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-    const pkFieldName = modelMeta.primaryKey[0]!;
-    const pkScalar = sfMap.get(pkFieldName);
-    const pkDbName = pkScalar?.dbName ?? pkFieldName;
-    const pkCol = `${table}."${pkDbName}"`;
-    const text = `SELECT COUNT(*) AS "count" FROM (SELECT ${pkCol} FROM ${table}${wherePart} OFFSET 0) AS "sub"`;
-    return { text, values: whereResult.values };
-  }
-
-  const text = `SELECT COUNT(*) AS "count" FROM ${table}${wherePart}`;
-  return { text, values: whereResult.values };
-}
-
-// ─── Relation Query Builder ───────────────────────────────────────
-
-/**
- * Build a query to load related records for a batch of parent IDs.
- * Used for to-many relations (hybrid strategy: separate batched query).
- */
-export type RelationSqlQuery = SqlQuery & {
-  /** When the FK column is already in the selected columns, this holds
-   *  its application-level field name so callers can use it for stitching
-   *  instead of the __vibeorm_fk alias. undefined means __vibeorm_fk is present. */
-  fkFieldName?: string;
-};
-
-export function buildRelationQuery(params: {
-  parentModelMeta: ModelMeta;
-  relationMeta: {
-    readonly relatedModel: string;
-    readonly type: string;
-    readonly fields: readonly string[];
-    readonly references: readonly string[];
-    readonly isList: boolean;
-    readonly isForeignKey?: boolean;
-    readonly relationName?: string;
-  };
-  relatedModelMeta: ModelMeta;
-  parentIds: unknown[];
-  args?: Record<string, unknown>;
-  allModelsMeta: ModelMetaMap;
-  defaultOrderByPk?: boolean;
-}): RelationSqlQuery {
-  const {
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    parentIds,
-    args = {},
-    allModelsMeta,
-    defaultOrderByPk = false,
-  } = params;
-
-  const table = `"${relatedModelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-
-  // Determine which columns to select
-  const columns = resolveSelectColumns({
-    modelMeta: relatedModelMeta,
-    args,
-  });
-  const columnsSql = columns
-    .map((c) => `${table}."${c.dbName}" AS "${c.name}"`)
-    .join(", ");
-
-  const allValues: unknown[] = [];
-  let paramIdx = 0;
-
-  // The FK column on the related model that references the parent
-  let fkDbName: string;
-  let fkFieldName: string | undefined;
-
-  // Access relationName for disambiguation (multi-FK scenarios like Follow)
-  const parentRelationName = (relationMeta as { relationName?: string }).relationName;
-
-  if (relationMeta.fields.length > 0) {
-    const reverseRelation = relatedModelMeta.relationFields.find(
-      (r) =>
-        r.relatedModel === parentModelMeta.name &&
-        r.isForeignKey &&
-        r.references.length > 0 &&
-        (!parentRelationName || r.relationName === parentRelationName)
-    );
-    if (reverseRelation) {
-      fkFieldName = reverseRelation.fields[0]!;
-      const fkField = sfMap.get(fkFieldName);
-      fkDbName = fkField?.dbName ?? fkFieldName;
-    } else if (relationMeta.isForeignKey && !relationMeta.isList && relationMeta.references.length > 0) {
-      // Parent holds the FK (many-to-one/to-one), so we query the related table
-      // by the referenced column (typically PK) using parent FK values.
-      fkFieldName = relationMeta.references[0]!;
-      const refField = sfMap.get(fkFieldName);
-      fkDbName = refField?.dbName ?? fkFieldName;
-    } else {
-      fkFieldName = relationMeta.fields[0]!;
-      const localField = sfMap.get(fkFieldName);
-      fkDbName = localField?.dbName ?? fkFieldName;
-    }
-  } else {
-    const reverseRelation = relatedModelMeta.relationFields.find(
-      (r) =>
-        r.relatedModel === parentModelMeta.name &&
-        r.isForeignKey &&
-        (!parentRelationName || r.relationName === parentRelationName)
-    );
-    if (reverseRelation) {
-      fkFieldName = reverseRelation.fields[0]!;
-      const fkField = sfMap.get(fkFieldName);
-      fkDbName = fkField?.dbName ?? fkFieldName;
-    } else {
-      fkDbName = `${parentModelMeta.name.toLowerCase()}Id`;
-    }
-  }
-
-  // Only add __vibeorm_fk alias if the FK column isn't already in the selected columns.
-  // This avoids transferring the same column value twice per row.
-  const fkAlreadySelected = columns.some((c) => c.dbName === fkDbName);
-  const fkSelectSql = fkAlreadySelected
-    ? ""
-    : `, ${table}."${fkDbName}" AS "__vibeorm_fk"`;
-
-  paramIdx++;
-  allValues.push(new PgArray(parentIds));
-
-  let whereSql = `${table}."${fkDbName}" = ANY($${paramIdx})`;
-
-  // Add any additional where from nested args
-  if (args.where) {
-    const subWhere = buildWhereClause({
-      where: args.where as Record<string, unknown>,
-      modelMeta: relatedModelMeta,
-      allModelsMeta,
-      paramOffset: paramIdx,
-    });
-    if (subWhere.sql) {
-      whereSql += ` AND (${subWhere.sql})`;
-      allValues.push(...subWhere.values);
-      paramIdx += subWhere.values.length;
-    }
-  }
-
-  // Build order clauses once (shared between ORDER BY and ROW_NUMBER window)
-  const orderClauses = buildSimpleOrderClauses({
-    orderBy: args.orderBy,
-    sfMap,
-    tableRef: table,
-    modelName: relatedModelMeta.name,
-  });
-
-  // Per-parent LIMIT/OFFSET using ROW_NUMBER() window function
-  if (args.take !== undefined || args.skip !== undefined) {
-    let windowOrderBy = orderClauses.length > 0 ? orderClauses.join(", ") : "";
-    if (!windowOrderBy) {
-      const pk = relatedModelMeta.primaryKey[0];
-      if (pk) {
-        const pkScalar = sfMap.get(pk);
-        windowOrderBy = `${table}."${pkScalar?.dbName ?? pk}" ASC`;
-      } else {
-        windowOrderBy = "1";
-      }
-    }
-
-    const fkSelectInner = fkAlreadySelected
-      ? ""
-      : `, ${table}."${fkDbName}" AS "__vibeorm_fk"`;
-    // ORDER BY is already captured in the ROW_NUMBER() OVER clause; omit the
-    // redundant trailing ORDER BY to avoid an extra sort node in the plan.
-    const innerSql = `SELECT ${columnsSql}${fkSelectInner}, ROW_NUMBER() OVER (PARTITION BY ${table}."${fkDbName}" ORDER BY ${windowOrderBy}) AS "__vibeorm_rn" FROM ${table} WHERE ${whereSql}`;
-
-    // Normalize negative take (Prisma allows negative for backward pagination)
-    const normalizedTake = args.take !== undefined ? Math.abs(args.take as number) : undefined;
-    const normalizedSkip = args.skip !== undefined ? Math.max(0, args.skip as number) : undefined;
-
-    // Build compound WHERE condition on __vibeorm_rn
-    const rnConditions: string[] = [];
-    if (normalizedSkip !== undefined) {
-      paramIdx++;
-      allValues.push(normalizedSkip);
-      rnConditions.push(`__ranked."__vibeorm_rn" > $${paramIdx}`);
-    }
-    if (normalizedTake !== undefined) {
-      paramIdx++;
-      if (normalizedSkip !== undefined) {
-        // upper bound = skip + take
-        allValues.push(normalizedSkip + normalizedTake);
-      } else {
-        allValues.push(normalizedTake);
-      }
-      rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
-    }
-
-    const fkOrderExpr = fkAlreadySelected && fkFieldName
-      ? `__ranked."${fkFieldName}"`
-      : `__ranked."__vibeorm_fk"`;
-    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")} ORDER BY ${fkOrderExpr} ASC, __ranked."__vibeorm_rn" ASC`;
-
-    return { text, values: allValues, fkFieldName: fkAlreadySelected ? fkFieldName : undefined };
-  }
-
-  // Add PK fallback ORDER BY when defaultOrderByPk is enabled and no explicit orderBy
-  let finalOrderClauses = orderClauses;
-  if (finalOrderClauses.length === 0 && defaultOrderByPk) {
-    const pkOrderClauses: string[] = [];
-    for (const pkName of relatedModelMeta.primaryKey) {
-      const pkSf = sfMap.get(pkName);
-      if (pkSf) {
-        pkOrderClauses.push(`${table}."${pkSf.dbName}" ASC`);
-      }
-    }
-    finalOrderClauses = pkOrderClauses;
-  }
-  const orderBySql = finalOrderClauses.length > 0 ? ` ORDER BY ${finalOrderClauses.join(", ")}` : "";
-  const text = `SELECT ${columnsSql}${fkSelectSql} FROM ${table} WHERE ${whereSql}${orderBySql}`;
-
-  return { text, values: allValues, fkFieldName: fkAlreadySelected ? fkFieldName : undefined };
-}
-
-// ─── Many-to-Many Relation Query Builder ──────────────────────────
-
-/**
- * Build a query to load M:N related records via an implicit join table.
- * E.g., Post.tags via "_PostToTag" join table.
- */
-export function buildManyToManyQuery(params: {
-  parentModelMeta: ModelMeta;
-  relationMeta: {
-    readonly relatedModel: string;
-    readonly type: string;
-    readonly isList: boolean;
-    readonly joinTable?: string;
-    readonly relationName?: string;
-  };
-  relatedModelMeta: ModelMeta;
-  parentIds: unknown[];
-  args?: Record<string, unknown>;
-  allModelsMeta: ModelMetaMap;
-  defaultOrderByPk?: boolean;
-}): RelationSqlQuery {
-  const {
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    parentIds,
-    args = {},
-    allModelsMeta,
-    defaultOrderByPk = false,
-  } = params;
-
-  const joinTable = `"${(relationMeta as { joinTable?: string }).joinTable}"`;
-  const relatedTable = `"${relatedModelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-
-  // Determine A vs B: alphabetical model name order
-  const sorted = [parentModelMeta.name, relatedModelMeta.name].sort();
-  const parentIsA = parentModelMeta.name === sorted[0];
-  const parentCol = parentIsA ? "A" : "B";
-  const relatedCol = parentIsA ? "B" : "A";
-
-  // Determine which columns to select from the related model
-  const columns = resolveSelectColumns({
-    modelMeta: relatedModelMeta,
-    args,
-  });
-  const columnsSql = columns
-    .map((c) => `${relatedTable}."${c.dbName}" AS "${c.name}"`)
-    .join(", ");
-
-  const allValues: unknown[] = [];
-  let paramIdx = 0;
-
-  // Build = ANY clause for parent IDs (stable SQL shape for prepared statement caching)
-  paramIdx++;
-  allValues.push(new PgArray(parentIds));
-
-  // Related model PK (typically "id")
-  const relatedPk = relatedModelMeta.primaryKey[0];
-  const relatedPkSf = relatedPk ? sfMap.get(relatedPk) : undefined;
-  const relatedPkDb = relatedPkSf?.dbName ?? relatedPk ?? "id";
-
-  let whereSql = `${joinTable}."${parentCol}" = ANY($${paramIdx})`;
-
-  // Add any additional where from nested args
-  if (args.where) {
-    const subWhere = buildWhereClause({
-      where: args.where as Record<string, unknown>,
-      modelMeta: relatedModelMeta,
-      allModelsMeta,
-      paramOffset: paramIdx,
-    });
-    if (subWhere.sql) {
-      whereSql += ` AND (${subWhere.sql})`;
-      allValues.push(...subWhere.values);
-      paramIdx += subWhere.values.length;
-    }
-  }
-
-  // Build order clauses once (shared between ORDER BY and ROW_NUMBER window)
-  const m2mOrderClauses = buildSimpleOrderClauses({
-    orderBy: args.orderBy,
-    sfMap,
-    tableRef: relatedTable,
-    modelName: relatedModelMeta.name,
-  });
-
-  // LIMIT / take + skip support via ROW_NUMBER
-  if (args.take !== undefined || args.skip !== undefined) {
-    let windowOrderBy = m2mOrderClauses.length > 0 ? m2mOrderClauses.join(", ") : "";
-    if (!windowOrderBy) {
-      windowOrderBy = `${relatedTable}."${relatedPkDb}" ASC`;
-    }
-
-    // ORDER BY is already captured in the ROW_NUMBER() OVER clause; omit the
-    // redundant trailing ORDER BY to avoid an extra sort node in the plan.
-    const innerSql = `SELECT ${columnsSql}, ${joinTable}."${parentCol}" AS "__vibeorm_fk", ROW_NUMBER() OVER (PARTITION BY ${joinTable}."${parentCol}" ORDER BY ${windowOrderBy}) AS "__vibeorm_rn" FROM ${relatedTable} INNER JOIN ${joinTable} ON ${joinTable}."${relatedCol}" = ${relatedTable}."${relatedPkDb}" WHERE ${whereSql}`;
-
-    // Normalize negative take (Prisma allows negative for backward pagination)
-    const normalizedTake = args.take !== undefined ? Math.abs(args.take as number) : undefined;
-    const normalizedSkip = args.skip !== undefined ? Math.max(0, args.skip as number) : undefined;
-
-    const rnConditions: string[] = [];
-    if (normalizedSkip !== undefined) {
-      paramIdx++;
-      allValues.push(normalizedSkip);
-      rnConditions.push(`__ranked."__vibeorm_rn" > $${paramIdx}`);
-    }
-    if (normalizedTake !== undefined) {
-      paramIdx++;
-      if (normalizedSkip !== undefined) {
-        allValues.push(normalizedSkip + normalizedTake);
-      } else {
-        allValues.push(normalizedTake);
-      }
-      rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
-    }
-
-    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")} ORDER BY __ranked."__vibeorm_fk" ASC, __ranked."__vibeorm_rn" ASC`;
-    return { text, values: allValues };
-  }
-
-  // Add PK fallback ORDER BY when defaultOrderByPk is enabled and no explicit orderBy
-  let finalM2mOrderClauses = m2mOrderClauses;
-  if (finalM2mOrderClauses.length === 0 && defaultOrderByPk) {
-    finalM2mOrderClauses = [`${relatedTable}."${relatedPkDb}" ASC`];
-  }
-  const m2mOrderBySql = finalM2mOrderClauses.length > 0 ? ` ORDER BY ${finalM2mOrderClauses.join(", ")}` : "";
-  const text = `SELECT ${columnsSql}, ${joinTable}."${parentCol}" AS "__vibeorm_fk" FROM ${relatedTable} INNER JOIN ${joinTable} ON ${joinTable}."${relatedCol}" = ${relatedTable}."${relatedPkDb}" WHERE ${whereSql}${m2mOrderBySql}`;
-
-  return { text, values: allValues };
-}
-
-// ─── Shared ORDER BY Helper ───────────────────────────────────────
-
-/**
- * Build ORDER BY clauses from a Prisma-style orderBy arg for a single table.
- * Returns an array of SQL clause strings like `"Table"."col" ASC`.
- */
-function buildSimpleOrderClauses(params: {
-  orderBy: unknown;
-  sfMap: ReadonlyMap<string, ScalarFieldMeta>;
-  tableRef: string;
-  modelName: string;
-}): string[] {
-  const { orderBy, sfMap, tableRef, modelName } = params;
-  if (!orderBy) return [];
-
-  const orderByItems = Array.isArray(orderBy)
-    ? (orderBy as Record<string, string>[])
-    : [orderBy as Record<string, string>];
-
-  return orderByItems.flatMap((item) =>
-    Object.entries(item).map(([field, direction]) => {
-      if (typeof direction !== "string") {
-        throw new Error(
-          `Unsupported orderBy direction for field "${field}" on model "${modelName}"`
-        );
-      }
-      const scalarField = getScalarFieldOrThrow({
-        sfMap,
-        field,
-        modelName,
-        context: "orderBy",
-      });
-      return `${tableRef}."${scalarField.dbName}" ${sanitizeDirection({ direction })}`;
-    })
-  );
-}
-
-// ─── INSERT MANY Builder ──────────────────────────────────────────
-
-/**
- * Build a multi-row INSERT query.
- * Produces: INSERT INTO "Table" ("col1", "col2") VALUES ($1, $2), ($3, $4), ...
- *
- * Handles varying keys across records by computing the union of all keys
- * and using DEFAULT for missing ones.
- */
-export function buildInsertManyQuery(params: {
-  modelMeta: ModelMeta;
-  data: Record<string, unknown>[];
-  skipDuplicates?: boolean;
-  returning?: boolean;
-  selectFields?: string[];
-}): SqlQuery {
-  const { modelMeta, data, skipDuplicates = false, returning = false, selectFields } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  if (data.length === 0) {
-    // Empty data — return a no-op that returns count 0
-    return { text: `SELECT 0 AS "count"`, values: [] };
-  }
-
-  // Compute the union of all keys across all records, filtered to scalar fields
-  const allKeys = new Set<string>();
-  for (const record of data) {
-    for (const key of Object.keys(record)) {
-      if (record[key] === undefined) continue;
-      if (sfMap.has(key)) {
-        allKeys.add(key);
-      }
-    }
-  }
-
-  // Sort keys alphabetically to produce stable SQL text regardless of object
-  // key insertion order. This improves prepared statement cache hit rates.
-  const orderedKeys = [...allKeys].sort();
-
-  if (orderedKeys.length === 0) {
-    // All records have empty data — insert defaults for each row
-    // PostgreSQL doesn't support multi-row DEFAULT VALUES, so use a union
-    const unionParts = data.map(() => `SELECT`);
-    // Actually just use single inserts... or use a CTE
-    // Simpler: use VALUES with explicit DEFAULT keywords
-    // PostgreSQL supports: INSERT INTO t DEFAULT VALUES (but only one row)
-    // For multiple: INSERT INTO t (col) VALUES (DEFAULT), (DEFAULT), ...
-    // We need at least one column. Use the PK column.
-    const pkField = modelMeta.scalarFields[0]!;
-    const col = `"${pkField.dbName}"`;
-    const valueRows = data.map(() => `(DEFAULT)`).join(", ");
-    const returningClause = returning
-      ? ` RETURNING ${resolveReturningColumns({ modelMeta, selectFields })}`
-      : "";
-    const conflictClause = skipDuplicates ? ` ON CONFLICT DO NOTHING` : "";
-    return {
-      text: `INSERT INTO ${table} (${col}) VALUES ${valueRows}${conflictClause}${returningClause}`,
-      values: [],
-    };
-  }
-
-  // Map keys to DB column names (keep field ref for isList wrapping)
-  const columnMap = orderedKeys.map((key) => {
-    const scalarField = sfMap.get(key)!;
-    return { key, dbName: scalarField.dbName, field: scalarField };
-  });
-
-  const columns = columnMap.map((c) => `"${c.dbName}"`).join(", ");
-
-  // Build VALUES rows
-  const allValues: unknown[] = [];
-  let paramIdx = 0;
-  const valueRows: string[] = [];
-
-  for (const record of data) {
-    const placeholders: string[] = [];
-    for (const { key, field } of columnMap) {
-      const value = record[key];
-      if (value === undefined) {
-        placeholders.push("DEFAULT");
-      } else {
-        paramIdx++;
-        placeholders.push(`$${paramIdx}`);
-        allValues.push(wrapListValue({ value, field }));
-      }
-    }
-    valueRows.push(`(${placeholders.join(", ")})`);
-  }
-
-  const conflictClause = skipDuplicates ? ` ON CONFLICT DO NOTHING` : "";
-  const returningClause = returning
-    ? ` RETURNING ${resolveReturningColumns({ modelMeta, selectFields })}`
-    : "";
-
-  const text = `INSERT INTO ${table} (${columns}) VALUES ${valueRows.join(", ")}${conflictClause}${returningClause}`;
-
-  return { text, values: allValues };
-}
-
-/**
- * Resolve RETURNING columns for insert many queries.
- */
-function resolveReturningColumns(params: {
-  modelMeta: ModelMeta;
-  selectFields?: string[];
-}): string {
-  const { modelMeta, selectFields } = params;
-
-  if (selectFields && selectFields.length > 0) {
-    const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-    return selectFields
-      .map((name) => {
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field: name,
-          modelName: modelMeta.name,
-          context: "createMany.select",
-        });
-        return `"${sf.dbName}" AS "${sf.name}"`;
-      })
-      .join(", ");
-  }
-
-  return modelMeta.scalarFields
-    .map((f) => `"${f.dbName}" AS "${f.name}"`)
-    .join(", ");
-}
-
-// ─── UPDATE MANY Builder ──────────────────────────────────────────
-
-/**
- * Build an UPDATE query without RETURNING (for updateMany).
- * Uses a subquery COUNT trick to return the affected row count.
- */
-export function buildUpdateManyQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  where: Record<string, unknown>;
-  data: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, where, data } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  let paramIdx = 0;
-  const allValues: unknown[] = [];
-  const setClauses: string[] = [];
-
-  for (const [key, value] of Object.entries(data)) {
-    if (value === undefined) continue;
-    const scalarField = sfMap.get(key);
-    if (!scalarField) continue;
-
-    const setResult = buildSetClause({
-      dbName: scalarField.dbName,
-      value,
-      paramIdx,
-      field: scalarField,
-    });
-    setClauses.push(setResult.sql);
-    allValues.push(...setResult.values);
-    paramIdx += setResult.values.length;
-  }
-
-  if (setClauses.length === 0) {
-    return { text: `SELECT 0 AS "count"`, values: [] };
-  }
-
-  // Build WHERE
-  const whereResult = buildWhereClause({
-    where,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: paramIdx,
-  });
-  allValues.push(...whereResult.values);
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-  const text = `UPDATE ${table} SET ${setClauses.join(", ")}${wherePart}`;
-
-  return { text, values: allValues };
-}
-
-// ─── AGGREGATE Builder ────────────────────────────────────────────
-
-/**
- * Build an aggregate query with _count, _avg, _sum, _min, _max.
- */
-export function buildAggregateQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  const selectParts: string[] = [];
-
-  // _count
-  const countArg = args._count;
-  if (countArg === true) {
-    selectParts.push(`COUNT(*) AS "_count__all"`);
-  } else if (typeof countArg === "object" && countArg !== null) {
-    const countFields = countArg as Record<string, boolean>;
-    if (countFields._all) {
-      selectParts.push(`COUNT(*) AS "_count__all"`);
-    }
-    for (const [field, enabled] of Object.entries(countFields)) {
-      if (field === "_all" || !enabled) continue;
-      const sf = getScalarFieldOrThrow({
-        sfMap,
-        field,
-        modelName: modelMeta.name,
-        context: "aggregate._count",
-      });
-      const col = sf.dbName;
-      selectParts.push(`COUNT("${col}") AS "_count__${field}"`);
-    }
-  }
-
-  // _avg, _sum, _min, _max
-  for (const aggFn of ["_avg", "_sum", "_min", "_max"] as const) {
-    const aggArg = args[aggFn];
-    if (typeof aggArg === "object" && aggArg !== null) {
-      const sqlFn = getAggregateSqlFnOrThrow({ aggregateKey: aggFn });
-      const fields = aggArg as Record<string, boolean>;
-      for (const [field, enabled] of Object.entries(fields)) {
-        if (!enabled) continue;
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: aggFn,
-        });
-        const col = sf.dbName;
-        selectParts.push(`${sqlFn}("${col}") AS "${aggFn}__${field}"`);
-      }
-    }
-  }
-
-  if (selectParts.length === 0) {
-    // No aggregation requested — just count all
-    selectParts.push(`COUNT(*) AS "_count__all"`);
-  }
-
-  // Build WHERE
-  const whereResult = buildWhereClause({
-    where: args.where as Record<string, unknown> | undefined,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: 0,
-  });
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-  const text = `SELECT ${selectParts.join(", ")} FROM ${table}${wherePart}`;
-
-  return { text, values: whereResult.values };
-}
-
-// ─── GROUP BY Builder ─────────────────────────────────────────────
-
-/**
- * Build a GROUP BY query with aggregate functions and HAVING clause.
- */
-export function buildGroupByQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, allModelsMeta, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  const by = args.by as string[];
-  if (!by || by.length === 0) {
-    throw new Error("groupBy requires a non-empty 'by' array");
-  }
-
-  // Group-by columns
-  const groupColumns = by.map((field) => {
-    const sf = getScalarFieldOrThrow({
-      sfMap,
-      field,
-      modelName: modelMeta.name,
-      context: "groupBy.by",
-    });
-    const col = sf.dbName;
-    return { field, col, dbName: col };
-  });
-
-  const selectParts: string[] = groupColumns.map(
-    (g) => `${table}."${g.col}" AS "${g.field}"`
-  );
-
-  // Aggregate functions
-  const countArg = args._count;
-  if (countArg === true) {
-    selectParts.push(`COUNT(*) AS "_count__all"`);
-  } else if (typeof countArg === "object" && countArg !== null) {
-    const countFields = countArg as Record<string, boolean>;
-    if (countFields._all) {
-      selectParts.push(`COUNT(*) AS "_count__all"`);
-    }
-    for (const [field, enabled] of Object.entries(countFields)) {
-      if (field === "_all" || !enabled) continue;
-      const sf = getScalarFieldOrThrow({
-        sfMap,
-        field,
-        modelName: modelMeta.name,
-        context: "groupBy._count",
-      });
-      const col = sf.dbName;
-      selectParts.push(`COUNT("${col}") AS "_count__${field}"`);
-    }
-  }
-
-  for (const aggFn of ["_avg", "_sum", "_min", "_max"] as const) {
-    const aggArg = args[aggFn];
-    if (typeof aggArg === "object" && aggArg !== null) {
-      const sqlFn = getAggregateSqlFnOrThrow({ aggregateKey: aggFn });
-      const fields = aggArg as Record<string, boolean>;
-      for (const [field, enabled] of Object.entries(fields)) {
-        if (!enabled) continue;
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: aggFn,
-        });
-        const col = sf.dbName;
-        selectParts.push(`${sqlFn}("${col}") AS "${aggFn}__${field}"`);
-      }
-    }
-  }
-
-  // Build WHERE
-  const whereResult = buildWhereClause({
-    where: args.where as Record<string, unknown> | undefined,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: 0,
-  });
-  let paramIdx = whereResult.values.length;
-  const allValues = [...whereResult.values];
-
-  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-
-  // GROUP BY
-  const groupBySql = groupColumns
-    .map((g) => `${table}."${g.col}"`)
-    .join(", ");
-
-  // HAVING
-  let havingSql = "";
-  if (args.having) {
-    const havingResult = buildHavingClause({
-      having: args.having as Record<string, unknown>,
-      modelMeta,
-      paramOffset: paramIdx,
-    });
-    if (havingResult.sql) {
-      havingSql = ` HAVING ${havingResult.sql}`;
-      allValues.push(...havingResult.values);
-      paramIdx += havingResult.values.length;
-    }
-  }
-
-  // ORDER BY
-  let orderBySql = "";
-  if (args.orderBy) {
-    const orderByItems = Array.isArray(args.orderBy)
-      ? (args.orderBy as Record<string, string>[])
-      : [args.orderBy as Record<string, string>];
-
-    const orderClauses = orderByItems.flatMap((item) =>
-      Object.entries(item).map(([field, direction]) => {
-        // Support ordering by aggregate: { _count: { id: "asc" } }
-        if (field.startsWith("_") && typeof direction === "object" && direction !== null) {
-          const sqlFn = getAggregateSqlFnOrThrow({ aggregateKey: field });
-          const aggEntries = Object.entries(direction as Record<string, string>);
-          return aggEntries.map(([aggField, aggDir]) => {
-            if (typeof aggDir !== "string") {
-              throw new Error(
-                `Unsupported orderBy direction for aggregate field "${field}.${aggField}" on model "${modelMeta.name}"`
-              );
-            }
-            if (field === "_count" && aggField === "_all") {
-              return `COUNT(*) ${sanitizeDirection({ direction: aggDir })}`;
-            }
-            const sf = getScalarFieldOrThrow({
-              sfMap,
-              field: aggField,
-              modelName: modelMeta.name,
-              context: `${field}.orderBy`,
-            });
-            const col = sf.dbName;
-            return `${sqlFn}("${col}") ${sanitizeDirection({ direction: aggDir })}`;
-          }).join(", ");
-        }
-        if (typeof direction !== "string") {
-          throw new Error(
-            `Unsupported orderBy direction for field "${field}" on model "${modelMeta.name}"`
-          );
-        }
-        const sf = getScalarFieldOrThrow({
-          sfMap,
-          field,
-          modelName: modelMeta.name,
-          context: "groupBy.orderBy",
-        });
-        const col = sf.dbName;
-        return `${table}."${col}" ${sanitizeDirection({ direction })}`;
-      })
-    );
-
-    if (orderClauses.length > 0) {
-      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
-    }
-  }
-
-  // LIMIT / OFFSET
-  let limitSql = "";
-  if (args.take !== undefined) {
-    paramIdx++;
-    limitSql = ` LIMIT $${paramIdx}`;
-    allValues.push(args.take);
-  }
-
-  let offsetSql = "";
-  if (args.skip !== undefined) {
-    paramIdx++;
-    offsetSql = ` OFFSET $${paramIdx}`;
-    allValues.push(args.skip);
-  }
-
-  const text = `SELECT ${selectParts.join(", ")} FROM ${table}${wherePart} GROUP BY ${groupBySql}${havingSql}${orderBySql}${limitSql}${offsetSql}`;
-
-  return { text, values: allValues };
-}
-
-// ─── HAVING Clause Builder ────────────────────────────────────────
-
-/**
- * Build a HAVING clause from Prisma-style having input.
- * Supports: { field: { _avg: { gt: 10 }, _count: { gte: 5 } } }
- */
-function buildHavingClause(params: {
-  having: Record<string, unknown>;
-  modelMeta: ModelMeta;
-  paramOffset: number;
-}): { sql: string; values: unknown[] } {
-  const { having, modelMeta, paramOffset } = params;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-  const conditions: string[] = [];
-  const values: unknown[] = [];
-  let paramIdx = paramOffset;
-
-  for (const [field, filter] of Object.entries(having)) {
-    if (filter === undefined) continue;
-    if (typeof filter !== "object" || filter === null) continue;
-
-    const filterObj = filter as Record<string, unknown>;
-
-    for (const [aggFn, comparison] of Object.entries(filterObj)) {
-      if (!aggFn.startsWith("_") || typeof comparison !== "object" || comparison === null) continue;
-
-      const sqlFn = getAggregateSqlFnOrThrow({ aggregateKey: aggFn });
-      const sf = getScalarFieldOrThrow({
-        sfMap,
-        field,
-        modelName: modelMeta.name,
-        context: "having",
-      });
-      const col = sf.dbName;
-
-      const compObj = comparison as Record<string, unknown>;
-      for (const [op, val] of Object.entries(compObj)) {
-        if (val === undefined) continue;
-        paramIdx++;
-        values.push(val);
-
-        let sqlOp: string;
-        switch (op) {
-          case "equals": sqlOp = "="; break;
-          case "not": sqlOp = "!="; break;
-          case "lt": sqlOp = "<"; break;
-          case "lte": sqlOp = "<="; break;
-          case "gt": sqlOp = ">"; break;
-          case "gte": sqlOp = ">="; break;
-          default: continue;
-        }
-
-        conditions.push(`${sqlFn}("${col}") ${sqlOp} $${paramIdx}`);
-      }
-    }
-  }
-
-  return {
-    sql: conditions.join(" AND "),
-    values,
-  };
-}
-
-// ─── SET Clause Builder (atomic ops + list ops) ──────────────────
-
-/**
- * Build a single SET clause for an UPDATE statement.
- * Handles:
- * - Plain values: "col" = $N
- * - Atomic number ops: { increment: N } → "col" = "col" + $N
- * - Scalar list ops: { set: [...] } → "col" = $N, { push: v } → "col" = array_append("col", $N)
- */
-function buildSetClause(params: {
-  dbName: string;
-  value: unknown;
-  paramIdx: number;
-  field: ScalarFieldMeta;
-  /** Optional table prefix for qualifying column self-references (e.g. in ON CONFLICT DO UPDATE SET) */
-  tablePrefix?: string;
-}): { sql: string; values: unknown[] } {
-  const { dbName, value, paramIdx, field, tablePrefix } = params;
-  let idx = paramIdx;
-  // Qualified column reference for the RHS (e.g. "Product"."price" in upsert context)
-  const colRef = tablePrefix ? `${tablePrefix}."${dbName}"` : `"${dbName}"`;
-
-  // Check for atomic number operations: { increment, decrement, multiply, divide, set }
-  if (typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
-    const ops = value as Record<string, unknown>;
-
-    if (ops.increment !== undefined) {
-      idx++;
-      return { sql: `"${dbName}" = ${colRef} + $${idx}`, values: [ops.increment] };
-    }
-    if (ops.decrement !== undefined) {
-      idx++;
-      return { sql: `"${dbName}" = ${colRef} - $${idx}`, values: [ops.decrement] };
-    }
-    if (ops.multiply !== undefined) {
-      idx++;
-      return { sql: `"${dbName}" = ${colRef} * $${idx}`, values: [ops.multiply] };
-    }
-    if (ops.divide !== undefined) {
-      idx++;
-      return { sql: `"${dbName}" = ${colRef} / $${idx}`, values: [ops.divide] };
-    }
-
-    // Scalar list operations: { set: [...] } or { push: value }
-    if ("push" in ops) {
-      const pushVal = ops.push;
-      if (Array.isArray(pushVal)) {
-        // Push multiple: "col" = "col" || $N
-        idx++;
-        return { sql: `"${dbName}" = ${colRef} || $${idx}`, values: [wrapListValue({ value: pushVal, field })] };
-      } else {
-        // Push single: "col" = array_append("col", $N)
-        idx++;
-        return { sql: `"${dbName}" = array_append(${colRef}, $${idx})`, values: [pushVal] };
-      }
-    }
-
-    if ("set" in ops) {
-      idx++;
-      return { sql: `"${dbName}" = $${idx}`, values: [wrapListValue({ value: ops.set, field })] };
-    }
-  }
-
-  // Plain value (wrap if scalar list)
-  idx++;
-  return { sql: `"${dbName}" = $${idx}`, values: [wrapListValue({ value, field })] };
-}
-
-// ─── UPSERT Builder (INSERT ... ON CONFLICT) ─────────────────────
-
-/**
- * Build an atomic upsert query using INSERT ... ON CONFLICT DO UPDATE SET.
- * This is race-condition-free unlike the findUnique + create/update approach.
- */
-export function buildUpsertQuery(params: {
-  modelMeta: ModelMeta;
-  where: Record<string, unknown>;
-  create: Record<string, unknown>;
-  update: Record<string, unknown>;
-  args?: Record<string, unknown>;
-}): SqlQuery {
-  const { modelMeta, where, create, update, args } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-  // Determine conflict columns from where clause (unique fields)
-  const conflictCols: string[] = [];
-  for (const key of Object.keys(where)) {
-    const sf = sfMap.get(key);
-    if (sf) {
-      conflictCols.push(`"${sf.dbName}"`);
-    }
-  }
-
-  // If no conflict columns, fallback to primary key
-  if (conflictCols.length === 0) {
-    for (const pk of modelMeta.primaryKey) {
-      const sf = sfMap.get(pk);
-      conflictCols.push(`"${sf?.dbName ?? pk}"`);
-    }
-  }
-
-  // Merge where unique values into create data so the conflict target column
-  // is always present in the INSERT. Without this, upsert({ where: { email: "x" },
-  // create: { name: "Y" }, ... }) would omit `email` from the INSERT row.
-  const mergedCreate = { ...create };
-  for (const [key, value] of Object.entries(where)) {
-    if (value === undefined || value === null) continue;
-    // Only merge scalar (non-object) values — skip nested where objects like { equals: ... }
-    if (typeof value !== "object" && mergedCreate[key] === undefined) {
-      mergedCreate[key] = value;
-    }
-  }
-
-  // Build INSERT part from merged create data
-  const insertEntries: Array<{ dbName: string; value: unknown }> = [];
-  for (const [key, value] of Object.entries(mergedCreate)) {
-    if (value === undefined) continue;
-    const sf = sfMap.get(key);
-    if (sf) {
-      insertEntries.push({ dbName: sf.dbName, value: wrapListValue({ value, field: sf }) });
-    }
-  }
-
-  let paramIdx = 0;
-  const allValues: unknown[] = [];
-
-  const insertColumns = insertEntries.map((e) => `"${e.dbName}"`).join(", ");
-  const insertPlaceholders = insertEntries.map((e) => {
-    paramIdx++;
-    allValues.push(e.value);
-    return `$${paramIdx}`;
-  }).join(", ");
-
-  // Build UPDATE SET part from update data (using atomic operations)
-  // In ON CONFLICT DO UPDATE SET context, column self-references must be table-qualified
-  // to avoid ambiguity (e.g. "Product"."price" instead of just "price").
-  const updateClauses: string[] = [];
-  for (const [key, value] of Object.entries(update)) {
-    if (value === undefined) continue;
-    const sf = sfMap.get(key);
-    if (!sf) continue;
-
-    const setResult = buildSetClause({
-      dbName: sf.dbName,
-      value,
-      paramIdx,
-      field: sf,
-      tablePrefix: table,
-    });
-    updateClauses.push(setResult.sql);
-    allValues.push(...setResult.values);
-    paramIdx += setResult.values.length;
-  }
-
-  const returningCols = resolveMutationReturningColumns({ modelMeta, args });
-
-  let text: string;
-  if (updateClauses.length > 0) {
-    text = `INSERT INTO ${table} (${insertColumns}) VALUES (${insertPlaceholders}) ON CONFLICT (${conflictCols.join(", ")}) DO UPDATE SET ${updateClauses.join(", ")} RETURNING ${returningCols}`;
-  } else {
-    text = `INSERT INTO ${table} (${insertColumns}) VALUES (${insertPlaceholders}) ON CONFLICT (${conflictCols.join(", ")}) DO NOTHING RETURNING ${returningCols}`;
-  }
-
-  return { text, values: allValues };
-}
-
-// ─── Column Resolution ────────────────────────────────────────────
-
-function resolveSelectColumns(params: {
-  modelMeta: ModelMeta;
-  args: Record<string, unknown>;
-}): readonly ScalarFieldMeta[] {
-  const { modelMeta, args } = params;
-  const select = args.select as Record<string, boolean | object> | undefined;
-  const omit = args.omit as Record<string, boolean> | undefined;
-
-  if (select) {
-    const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-
-    // With select → return only selected scalar fields
-    const columns = modelMeta.scalarFields.filter((f) => {
-      const val = select[f.name];
-      return val === true || (typeof val === "object" && val !== null);
-    });
-
-    // Build a set of relation names for O(1) lookups
-    const relationNameSet = new Set(modelMeta.relationFields.map((r) => r.name));
-
-    // Auto-include PK if select has nested relations (needed for Phase 2 relation loading)
-    const hasNested = Object.entries(select).some(([key, val]) => {
-      if (typeof val !== "object" || val === null) return false;
-      return relationNameSet.has(key);
-    });
-
-    if (hasNested) {
-      // Track already-selected column names for O(1) dedup checks
-      const selectedNames = new Set(columns.map((c) => c.name));
-
-      // Auto-include PK columns (needed for all relation loading strategies)
-      for (const pkName of modelMeta.primaryKey) {
-        if (!selectedNames.has(pkName)) {
-          const sf = sfMap.get(pkName);
-          if (sf) {
-            columns.push(sf);
-            selectedNames.add(pkName);
-          }
-        }
-      }
-
-      // Build a map of relation name → RelationFieldMeta for O(1) lookups
-      const relationByName = new Map(modelMeta.relationFields.map((r) => [r.name, r]));
-
-      // Auto-include FK fields for selected to-one relations where parent holds the FK
-      // (needed for Phase 2 relation loading to query related records by FK value)
-      for (const [key, val] of Object.entries(select)) {
-        if (typeof val !== "object" || val === null) continue;
-        const rel = relationByName.get(key);
-        if (rel && rel.isForeignKey && !rel.isList) {
-          for (const fkFieldName of rel.fields) {
-            if (!selectedNames.has(fkFieldName)) {
-              const sf = sfMap.get(fkFieldName);
-              if (sf) {
-                columns.push(sf);
-                selectedNames.add(fkFieldName);
-              }
-            }
-          }
-        }
-      }
-    }
-
-    return columns;
-  }
-
-  if (omit) {
-    // With omit → return all scalar fields except omitted ones
-    return modelMeta.scalarFields.filter((f) => !omit[f.name]);
-  }
-
-  // No select/omit → return all scalar fields (default selection)
-  return modelMeta.scalarFields;
-}
-
-function resolveMutationReturningColumns(params: {
-  modelMeta: ModelMeta;
-  args?: Record<string, unknown>;
-}): string {
-  const { modelMeta, args } = params;
-  const shouldForceFullReturning = args?.returning === true;
-
-  if (!shouldForceFullReturning && (args?.select || args?.omit)) {
-    const columns = resolveSelectColumns({
-      modelMeta,
-      args,
-    });
-    if (columns.length > 0) {
-      return columns
-        .map((f) => `"${f.dbName}" AS "${f.name}"`)
-        .join(", ");
-    }
-  }
-
-  return modelMeta.scalarFields
-    .map((f) => `"${f.dbName}" AS "${f.name}"`)
-    .join(", ");
-}