@vibeorm/runtime 1.3.0 → 2.0.0-alpha.2

package/src/lateral-join-builder.ts

@@ -1,1053 +0,0 @@
-/**
- * Lateral JOIN Relation Loading Strategy
- *
- * Builds a SINGLE query that fetches parent records + all first-level
- * relations using PostgreSQL LATERAL JOINs. This replaces both the
- * initial SELECT and the relation loading in one round-trip.
- *
- * Produces SQL like:
- *
- * SELECT "User"."id" AS "id", "User"."email" AS "email",
- *   __lat_0."__vibeorm_rel_posts",
- *   __lat_1."__vibeorm_rel_profile"
- * FROM "User"
- * LEFT JOIN LATERAL (
- *   SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb)
- *     AS "__vibeorm_rel_posts"
- *   FROM (
- *     SELECT __rel."id" AS "id", __rel."title" AS "title", ...
- *     FROM "Post" __rel WHERE __rel."authorId" = "User"."id"
- *   ) "__sub"
- * ) __lat_0 ON true
- * LEFT JOIN LATERAL (
- *   SELECT to_jsonb("__sub".*) AS "__vibeorm_rel_profile"
- *   FROM (
- *     SELECT __rel."id" AS "id", __rel."bio" AS "bio", ...
- *     FROM "Profile" __rel WHERE __rel."userId" = "User"."id"
- *     LIMIT 1
- *   ) "__sub"
- * ) __lat_1 ON true
- * WHERE "User"."role" = $1
- * ORDER BY "User"."id" ASC
- * LIMIT 20
- *
- * Uses to_jsonb() on a subselect instead of json_build_object() to avoid
- * PostgreSQL's 100-argument function limit (models with >50 scalar fields
- * would exceed this). Column aliases in the inner SELECT handle the
- * dbName→tsName remapping at zero cost.
- */
-
-import type {
-  ModelMeta,
-  ModelMetaMap,
-  RelationFieldMeta,
-  SqlQuery,
-  ProfilingContext,
-} from "./types.ts";
-import { getScalarFieldMap, getModelByNameMap } from "./types.ts";
-import { buildWhereClause } from "./where-builder.ts";
-import { sanitizeDirection } from "./query-builder.ts";
-import { loadRelations, resolveRelationsToLoad, hasNestedRelations } from "./relation-loader.ts";
-import type { RelationToLoad } from "./relation-loader.ts";
-import { coerceFieldTypes, modelNeedsCoercion } from "./coerce.ts";
-import { resolveCountSpec, loadRelationCounts } from "./count-loader.ts";
-
-type SqlExecutor = (params: {
-  text: string;
-  values: unknown[];
-}) => Promise<Record<string, unknown>[]>;
-
-function reverseDirection(params: { direction: string }): string {
-  const normalized = sanitizeDirection({ direction: params.direction });
-  return normalized === "ASC" ? "DESC" : "ASC";
-}
-
-// ─── Query Builder ────────────────────────────────────────────────
-
-/**
- * Build a complete SELECT query with lateral joins for relations.
- * This replaces both buildSelectQuery + loadRelations in a single SQL statement.
- */
-export function buildLateralJoinQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  relationsToLoad: RelationToLoad[];
-  defaultOrderByPk?: boolean;
-}): { query: SqlQuery; relationAliases: RelationAlias[] } {
-  const { modelMeta, allModelsMeta, args, relationsToLoad, defaultOrderByPk = false } = params;
-  const table = `"${modelMeta.dbName}"`;
-  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-  const modelMap = getModelByNameMap({ allModelsMeta });
-
-  const pkField = modelMeta.primaryKey[0]!;
-  const pkScalar = sfMap.get(pkField);
-  const pkDbName = pkScalar?.dbName ?? pkField;
-
-  // Resolve which scalar columns to select on parent
-  const selectArg = args.select as Record<string, boolean | object> | undefined;
-  const parentScalars = selectArg
-    ? modelMeta.scalarFields.filter((f) => {
-        const val = selectArg[f.name];
-        return val === true || (typeof val === "object" && val !== null);
-      })
-    : modelMeta.scalarFields;
-
-  // Always include the PK so we can stitch results
-  const hasPk = parentScalars.some((f) => f.name === pkField);
-  const columnsToSelect = hasPk
-    ? parentScalars
-    : [pkScalar!, ...parentScalars];
-
-  const parentColumns = columnsToSelect
-    .map((f) => `${table}."${f.dbName}" AS "${f.name}"`)
-    .join(", ");
-
-  const allValues: unknown[] = [];
-  let paramIdx = 0;
-
-  const take = typeof args.take === "number" ? (args.take as number) : undefined;
-
-  // 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;
-
-  // Build WHERE — start with explicit where, then merge cursor conditions.
-  let where = args.where as Record<string, unknown> | undefined;
-  if (args.cursor) {
-    const cursorInput = args.cursor as Record<string, unknown>;
-    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
-
-    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 (!sfMap.has(field)) continue;
-          if (typeof dir === "string") {
-            orderByDirMap.set(field, dir.toUpperCase());
-          }
-        }
-      }
-    }
-
-    const cmpOpForField = (field: string): string => {
-      const dir = orderByDirMap.get(field) ?? "ASC";
-      const isDesc = dir === "DESC";
-      return (isDesc !== isBackwardCursor) ? "lt" : "gt";
-    };
-
-    let cursorWhere: Record<string, unknown> | undefined;
-    if (cursorEntries.length === 1) {
-      const [field, value] = cursorEntries[0]!;
-      if (!sfMap.has(field)) {
-        throw new Error(`Unknown field "${field}" in cursor for model "${modelMeta.name}"`);
-      }
-      cursorWhere = { [field]: { [cmpOpForField(field)]: value } };
-    } else if (cursorEntries.length > 1) {
-      const orBranches: Record<string, unknown>[] = [];
-      for (let i = 0; i < cursorEntries.length; i++) {
-        const branch: Record<string, unknown> = {};
-        for (let j = 0; j < i; j++) {
-          const [eqField, eqValue] = cursorEntries[j]!;
-          if (!sfMap.has(eqField)) {
-            throw new Error(`Unknown field "${eqField}" in cursor for model "${modelMeta.name}"`);
-          }
-          branch[eqField] = { equals: eqValue };
-        }
-        const [cmpField, cmpValue] = cursorEntries[i]!;
-        if (!sfMap.has(cmpField)) {
-          throw new Error(`Unknown field "${cmpField}" in cursor for model "${modelMeta.name}"`);
-        }
-        branch[cmpField] = { [cmpOpForField(cmpField)]: cmpValue };
-        orBranches.push(branch);
-      }
-      cursorWhere = { OR: orBranches };
-    }
-
-    if (cursorWhere) {
-      where = where
-        ? { AND: [where, cursorWhere] }
-        : cursorWhere;
-    }
-  }
-
-  // Build LATERAL JOINs for each relation
-  const lateralJoins: string[] = [];
-  const lateralSelects: string[] = [];
-  const relationAliases: RelationAlias[] = [];
-
-  for (let i = 0; i < relationsToLoad.length; i++) {
-    const { relationMeta, nestedArgs } = relationsToLoad[i]!;
-    const alias = `__lat_${i}`;
-    const colAlias = `__vibeorm_rel_${relationMeta.name}`;
-    const relatedAlias = `"__rel"`;
-
-    // Find the related model meta
-    const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
-    if (!relatedModelMeta) continue;
-
-    // Build aliased column list for the inner subquery.
-    // Uses to_jsonb("__sub".*) instead of json_build_object() to avoid
-    // PostgreSQL's 100-argument function limit on wide models.
-    // Respect nested select/omit to avoid serialising columns the caller doesn't need.
-    const relatedScalars = resolveRelatedScalars({
-      relatedModelMeta,
-      nestedArgs,
-    });
-    const columnAliases = relatedScalars
-      .map((f) => `${relatedAlias}."${f.dbName}" AS "${f.name}"`)
-      .join(", ");
-
-    let lateralSubquery: string;
-
-    // ─── M:N relations via junction table ─────────────────────────
-    const isM2M = relationMeta.type === "manyToMany" && (relationMeta as { joinTable?: string }).joinTable;
-
-    if (isM2M) {
-      const jtName = (relationMeta as { joinTable: string }).joinTable;
-      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-
-      // Determine A vs B column: Prisma implicit junction tables use alphabetical model name order
-      const sorted = [modelMeta.name, relatedModelMeta.name].sort();
-      const parentIsA = modelMeta.name === sorted[0];
-      const parentCol = parentIsA ? "A" : "B";
-      const relatedCol = parentIsA ? "B" : "A";
-
-      // Related model PK for junction join condition
-      const relatedPk = relatedModelMeta.primaryKey[0]!;
-      const relatedPkSf = relatedSfMap.get(relatedPk);
-      const relatedPkDb = relatedPkSf?.dbName ?? relatedPk;
-
-      // Junction join: __jt."B" = __rel."id" WHERE __jt."A" = parent."id"
-      const junctionJoin = `INNER JOIN "${jtName}" __jt ON __jt."${relatedCol}" = ${relatedAlias}."${relatedPkDb}"`;
-      const subWhere = `__jt."${parentCol}" = ${table}."${pkDbName}"`;
-
-      // Nested where filter from include/select args
-      let nestedWhereSql = "";
-      if (nestedArgs.where) {
-        const relMetaWithAlias = {
-          ...relatedModelMeta,
-          dbName: "__rel",
-        } as typeof relatedModelMeta;
-        const nestedWhereResult = buildWhereClause({
-          where: nestedArgs.where as Record<string, unknown>,
-          modelMeta: relMetaWithAlias,
-          allModelsMeta,
-          paramOffset: paramIdx,
-        });
-        if (nestedWhereResult.sql) {
-          nestedWhereSql = ` AND ${nestedWhereResult.sql}`;
-          paramIdx += nestedWhereResult.values.length;
-          allValues.push(...nestedWhereResult.values);
-        }
-      }
-
-      let orderBySql = "";
-      if (nestedArgs.orderBy) {
-        const orderByItems = Array.isArray(nestedArgs.orderBy)
-          ? (nestedArgs.orderBy as Record<string, string>[])
-          : [nestedArgs.orderBy as Record<string, string>];
-        const clauses = orderByItems.flatMap((item) =>
-          Object.entries(item).map(([field, dir]) => {
-            if (typeof dir !== "string") {
-              throw new Error(
-                `Unsupported nested orderBy direction for field "${field}" on relation "${relationMeta.name}"`
-              );
-            }
-            const sf = relatedSfMap.get(field);
-            if (!sf) {
-              throw new Error(
-                `Unknown nested orderBy field "${field}" on relation "${relationMeta.name}"`
-              );
-            }
-            return `${relatedAlias}."${sf.dbName}" ${sanitizeDirection({ direction: dir })}`;
-          })
-        );
-        if (clauses.length > 0) {
-          orderBySql = ` ORDER BY ${clauses.join(", ")}`;
-        }
-      } else if (defaultOrderByPk || nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
-        const pkOrderClauses: string[] = [];
-        for (const rpkName of relatedModelMeta.primaryKey) {
-          const rpkSf = relatedSfMap.get(rpkName);
-          if (rpkSf) {
-            pkOrderClauses.push(`${relatedAlias}."${rpkSf.dbName}" ASC`);
-          }
-        }
-        if (pkOrderClauses.length > 0) {
-          orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
-        }
-      }
-
-      let limitSql = "";
-      if (nestedArgs.take !== undefined) {
-        paramIdx++;
-        limitSql = ` LIMIT $${paramIdx}`;
-        allValues.push(Math.abs(nestedArgs.take as number));
-      }
-
-      let offsetSql = "";
-      if (nestedArgs.skip !== undefined) {
-        paramIdx++;
-        offsetSql = ` OFFSET $${paramIdx}`;
-        allValues.push(nestedArgs.skip);
-      }
-
-      // Wrap in inner subquery with column aliases + to_jsonb to avoid
-      // PostgreSQL's 100-argument limit on json_build_object.
-      if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
-        lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
-    FROM (
-      SELECT ${columnAliases}
-      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      ${junctionJoin}
-      WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
-    ) "__sub"
-  ) ${alias} ON true`;
-      } else {
-        lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
-    FROM (
-      SELECT ${columnAliases}
-      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      ${junctionJoin}
-      WHERE ${subWhere}${nestedWhereSql}${orderBySql}
-    ) "__sub"
-  ) ${alias} ON true`;
-      }
-
-    // ─── Direct FK relations (1:N, 1:1) ──────────────────────────
-    } else {
-      // Determine FK column and join condition
-      const { fkDbName, fkTable } = resolveFkColumn({
-        parentModelMeta: modelMeta,
-        relationMeta,
-        relatedModelMeta,
-      });
-
-      if (relationMeta.isList) {
-        // To-many: use json_agg with COALESCE for empty arrays
-        const subWhere = `${relatedAlias}."${fkDbName}" = ${table}."${pkDbName}"`;
-
-        // Nested where filter from include/select args
-        let nestedWhereSql = "";
-        if (nestedArgs.where) {
-          // Build nested where using __rel alias for the related model.
-          // This avoids brittle regex rewrites of generated SQL table refs.
-          const relMetaWithAlias = {
-            ...relatedModelMeta,
-            dbName: "__rel",
-          } as typeof relatedModelMeta;
-          const nestedWhereResult = buildWhereClause({
-            where: nestedArgs.where as Record<string, unknown>,
-            modelMeta: relMetaWithAlias,
-            allModelsMeta,
-            paramOffset: paramIdx,
-          });
-          if (nestedWhereResult.sql) {
-            nestedWhereSql = ` AND ${nestedWhereResult.sql}`;
-            paramIdx += nestedWhereResult.values.length;
-            allValues.push(...nestedWhereResult.values);
-          }
-        }
-
-        const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-
-        let orderBySql = "";
-        if (nestedArgs.orderBy) {
-          const orderByItems = Array.isArray(nestedArgs.orderBy)
-            ? (nestedArgs.orderBy as Record<string, string>[])
-            : [nestedArgs.orderBy as Record<string, string>];
-          const clauses = orderByItems.flatMap((item) =>
-            Object.entries(item).map(([field, dir]) => {
-              if (typeof dir !== "string") {
-                throw new Error(
-                  `Unsupported nested orderBy direction for field "${field}" on relation "${relationMeta.name}"`
-                );
-              }
-              const sf = relatedSfMap.get(field);
-              if (!sf) {
-                throw new Error(
-                  `Unknown nested orderBy field "${field}" on relation "${relationMeta.name}"`
-                );
-              }
-              return `${relatedAlias}."${sf.dbName}" ${sanitizeDirection({ direction: dir })}`;
-            })
-          );
-          if (clauses.length > 0) {
-            orderBySql = ` ORDER BY ${clauses.join(", ")}`;
-          }
-        } else if (defaultOrderByPk || nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
-          // Default ORDER BY PK for deterministic array ordering in jsonb_agg
-          const pkOrderClauses: string[] = [];
-          for (const rpkName of relatedModelMeta.primaryKey) {
-            const rpkSf = relatedSfMap.get(rpkName);
-            if (rpkSf) {
-              pkOrderClauses.push(`${relatedAlias}."${rpkSf.dbName}" ASC`);
-            }
-          }
-          if (pkOrderClauses.length > 0) {
-            orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
-          }
-        }
-
-        let limitSql = "";
-        if (nestedArgs.take !== undefined) {
-          paramIdx++;
-          limitSql = ` LIMIT $${paramIdx}`;
-          allValues.push(Math.abs(nestedArgs.take as number));
-        }
-
-        let offsetSql = "";
-        if (nestedArgs.skip !== undefined) {
-          paramIdx++;
-          offsetSql = ` OFFSET $${paramIdx}`;
-          allValues.push(nestedArgs.skip);
-        }
-
-        // Wrap in inner subquery with column aliases + to_jsonb to avoid
-        // PostgreSQL's 100-argument limit on json_build_object.
-        if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
-          lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
-    FROM (
-      SELECT ${columnAliases}
-      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
-    ) "__sub"
-  ) ${alias} ON true`;
-        } else {
-          lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
-    FROM (
-      SELECT ${columnAliases}
-      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      WHERE ${subWhere}${nestedWhereSql}${orderBySql}
-    ) "__sub"
-  ) ${alias} ON true`;
-        }
-      } else {
-        // To-one: use to_jsonb on subselect with LIMIT 1
-        let joinCondition: string;
-
-        if (fkTable === "parent") {
-          // Parent holds FK (e.g., Post.authorId -> User.id)
-          const parentFkField = relationMeta.fields[0]!;
-          const parentFkScalar = sfMap.get(parentFkField);
-          const parentFkDbName = parentFkScalar?.dbName ?? parentFkField;
-          const refField = relationMeta.references[0]!;
-          const relatedSfMapForOne = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-          const refScalar = relatedSfMapForOne.get(refField);
-          const refDbName = refScalar?.dbName ?? refField;
-          joinCondition = `${relatedAlias}."${refDbName}" = ${table}."${parentFkDbName}"`;
-        } else {
-          // Related model holds FK (e.g., User.profile -> Profile.userId)
-          joinCondition = `${relatedAlias}."${fkDbName}" = ${table}."${pkDbName}"`;
-        }
-
-        // Nested where filter from include/select args — mirrors the to-many branch.
-        // Without this the join silently ignored `include: { author: { where: {...} } }`.
-        let nestedWhereSql = "";
-        if (nestedArgs.where) {
-          const relMetaWithAlias = {
-            ...relatedModelMeta,
-            dbName: "__rel",
-          } as typeof relatedModelMeta;
-          const nestedWhereResult = buildWhereClause({
-            where: nestedArgs.where as Record<string, unknown>,
-            modelMeta: relMetaWithAlias,
-            allModelsMeta,
-            paramOffset: paramIdx,
-          });
-          if (nestedWhereResult.sql) {
-            nestedWhereSql = ` AND ${nestedWhereResult.sql}`;
-            paramIdx += nestedWhereResult.values.length;
-            allValues.push(...nestedWhereResult.values);
-          }
-        }
-
-        lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT to_jsonb("__sub".*) AS "${colAlias}"
-    FROM (
-      SELECT ${columnAliases}
-      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      WHERE ${joinCondition}${nestedWhereSql}
-      LIMIT 1
-    ) "__sub"
-  ) ${alias} ON true`;
-      }
-    }
-
-    lateralJoins.push(lateralSubquery);
-    lateralSelects.push(`${alias}."${colAlias}"`);
-    relationAliases.push({ alias: colAlias, relationMeta, nestedArgs });
-  }
-
-  // Build WHERE from args
-  const whereResult = buildWhereClause({
-    where,
-    modelMeta,
-    allModelsMeta,
-    paramOffset: paramIdx,
-  });
-  paramIdx += whereResult.values.length;
-  allValues.push(...whereResult.values);
-
-  // Build 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]) => {
-        if (typeof direction !== "string") {
-          throw new Error(
-            `Unsupported orderBy direction for field "${field}" on model "${modelMeta.name}"`
-          );
-        }
-        const scalarField = sfMap.get(field);
-        if (!scalarField) {
-          throw new Error(`Unknown orderBy field "${field}" on model "${modelMeta.name}"`);
-        }
-        const resolvedDirection = isBackwardCursor
-          ? reverseDirection({ direction })
-          : direction;
-        return `${table}."${scalarField.dbName}" ${sanitizeDirection({ direction: resolvedDirection })}`;
-      })
-    );
-
-    if (orderClauses.length > 0) {
-      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
-    }
-  } else if (args.cursor) {
-    const cursorInput = args.cursor as Record<string, unknown>;
-    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
-    const defaultDir = isBackwardCursor ? "DESC" : "ASC";
-    const cursorOrderClauses = cursorEntries.map(([field]) => {
-      const sf = sfMap.get(field);
-      if (!sf) {
-        throw new Error(`Unknown field "${field}" in cursor for model "${modelMeta.name}"`);
-      }
-      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 pn of modelMeta.primaryKey) {
-      const pSf = sfMap.get(pn);
-      if (pSf) {
-        pkOrderClauses.push(`${table}."${pSf.dbName}" ASC`);
-      }
-    }
-    if (pkOrderClauses.length > 0) {
-      orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
-    }
-  }
-
-  // Build LIMIT / OFFSET
-  let limitSql = "";
-  if (take !== undefined) {
-    paramIdx++;
-    limitSql = ` LIMIT $${paramIdx}`;
-    allValues.push(Math.abs(take));
-  }
-
-  let offsetSql = "";
-  if (args.skip !== undefined) {
-    paramIdx++;
-    offsetSql = ` OFFSET $${paramIdx}`;
-    allValues.push(args.skip);
-  }
-
-  const selectSql = [parentColumns, ...lateralSelects].join(", ");
-  const joinsPart = lateralJoins.length > 0
-    ? `\n${lateralJoins.join("\n")}`
-    : "";
-
-  // ── CTE optimisation ────────────────────────────────────────────
-  // When the WHERE clause contains relation-based filters (some/every/
-  // none/is/isNot), the where-builder emits EXISTS / NOT EXISTS
-  // sub-queries. If we put that WHERE after the LATERAL JOINs the
-  // planner may execute every lateral join for every parent row before
-  // filtering. Wrapping the base set in a CTE with LIMIT/OFFSET
-  // guarantees PostgreSQL resolves the matching PKs first, then runs
-  // the lateral joins only against the matched rows.
-  //
-  // We also enable the CTE when LIMIT is present and there are 3+
-  // lateral joins. Without it Postgres may evaluate every lateral for
-  // every candidate row before the LIMIT prunes the result set.
-  const hasRelFilter = whereHasRelationFilter({
-    where,
-    modelMeta,
-  });
-  const hasHeavyIncludes =
-    args.take !== undefined && relationsToLoad.length >= 3;
-  const useCte = hasRelFilter || hasHeavyIncludes;
-
-  let text: string;
-
-  if (useCte) {
-    // CTE selects only the PK, applying WHERE + ORDER + LIMIT + OFFSET
-    const cteWherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-    const cteSql =
-      `WITH __vibeorm_base AS (` +
-      `SELECT ${table}."${pkDbName}" FROM ${table}` +
-      `${cteWherePart}${orderBySql}${limitSql}${offsetSql}` +
-      `)`;
-
-    // Outer query joins the CTE to the parent table, then lateral joins
-    text =
-      `${cteSql} SELECT ${selectSql} FROM ${table}` +
-      ` INNER JOIN __vibeorm_base ON __vibeorm_base."${pkDbName}" = ${table}."${pkDbName}"` +
-      `${joinsPart}${orderBySql}`;
-  } else {
-    // No relation filter — standard flat query (existing behaviour)
-    const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
-    text = `SELECT ${selectSql} FROM ${table}${joinsPart}${wherePart}${orderBySql}${limitSql}${offsetSql}`;
-  }
-
-  return {
-    query: { text, values: allValues },
-    relationAliases,
-  };
-}
-
-// ─── Executor (single-query path) ─────────────────────────────────
-
-/**
- * Execute a findMany/findFirst/findUnique with lateral joins.
- * Returns fully-hydrated records in a single DB round-trip.
- */
-export async function executeLateralJoinQuery(params: {
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  executor: SqlExecutor;
-  profilingCtx?: ProfilingContext;
-  defaultOrderByPk?: boolean;
-}): Promise<Record<string, unknown>[]> {
-  const { modelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } = params;
-  const profiling = !!profilingCtx;
-
-  const t0 = profiling ? performance.now() : 0;
-
-  const relationsToLoad = resolveRelationsToLoad({ parentModelMeta: modelMeta, args });
-
-  // If no relations to load, this shouldn't have been called, but handle gracefully
-  if (relationsToLoad.length === 0) {
-    // Fall through — the caller should use buildSelectQuery instead
-    // But just in case, import the builder dynamically wouldn't work, so just build a simple query
-    const { buildSelectQuery } = await import("./query-builder.ts");
-    const query = buildSelectQuery({ modelMeta, allModelsMeta, args });
-    return executor(query);
-  }
-
-  const { query, relationAliases } = buildLateralJoinQuery({
-    modelMeta,
-    allModelsMeta,
-    args,
-    relationsToLoad,
-    defaultOrderByPk,
-  });
-
-  const t1 = profiling ? performance.now() : 0;
-
-  const rows = await executor(query);
-
-  const t2 = profiling ? performance.now() : 0;
-
-  // Parse JSON relation columns + apply BigInt coercion in a single pass.
-  //
-  // The "query" strategy coerces both parents (via `loadRelationsForStrategy`)
-  // and children (via the per-loader calls in `relation-loader.ts`). The
-  // lateral-join strategy bypasses both, so we do the equivalent work here
-  // (Bug #6).
-  //
-  // Performance: pre-compute which relation aliases actually need coercion
-  // (BigInt or enum-array — see `modelNeedsCoercion`). Wide schemas with
-  // many includes thus pay nothing extra for relations whose child model
-  // has neither.
-  const nestedModelMap = getModelByNameMap({ allModelsMeta });
-  const relationCoerceMeta = relationAliases.map(({ relationMeta }) => {
-    const relatedModelMeta = nestedModelMap.get(relationMeta.relatedModel);
-    if (!relatedModelMeta) return null;
-    return modelNeedsCoercion(relatedModelMeta) ? relatedModelMeta : null;
-  });
-
-  const results: Record<string, unknown>[] = [];
-
-  for (const row of rows) {
-    const record: Record<string, unknown> = {};
-
-    // Copy scalar fields
-    for (const sf of modelMeta.scalarFields) {
-      if (row[sf.name] !== undefined) {
-        record[sf.name] = row[sf.name];
-      }
-    }
-
-    // Parse relation columns from JSON (and coerce inline if needed)
-    for (let i = 0; i < relationAliases.length; i++) {
-      const { alias, relationMeta } = relationAliases[i]!;
-      const jsonValue = row[alias];
-      let parsed: unknown;
-      if (jsonValue === null || jsonValue === undefined) {
-        parsed = relationMeta.isList ? [] : null;
-      } else if (typeof jsonValue === "string") {
-        try {
-          parsed = JSON.parse(jsonValue);
-        } catch {
-          parsed = relationMeta.isList ? [] : null;
-        }
-      } else {
-        // Already parsed by bun:sql (json/jsonb columns auto-parse)
-        parsed = jsonValue;
-      }
-      record[relationMeta.name] = parsed;
-
-      const coerceMeta = relationCoerceMeta[i];
-      if (coerceMeta) {
-        if (Array.isArray(parsed)) {
-          coerceFieldTypes({ records: parsed as Record<string, unknown>[], modelMeta: coerceMeta });
-        } else if (parsed && typeof parsed === "object") {
-          coerceFieldTypes({ records: [parsed as Record<string, unknown>], modelMeta: coerceMeta });
-        }
-      }
-    }
-
-    results.push(record);
-  }
-
-  // Coerce parent records once (whole batch) after the parse loop.
-  coerceFieldTypes({ records: results, modelMeta });
-
-  const t3 = profiling ? performance.now() : 0;
-
-  // Recursively load nested relations (deeper levels fall back to batched)
-  await Promise.all(
-    relationAliases
-      .filter(({ nestedArgs }) => hasNestedRelations({ nestedArgs }))
-      .map(async ({ relationMeta, nestedArgs }) => {
-        const relatedModelMeta = nestedModelMap.get(relationMeta.relatedModel);
-        if (!relatedModelMeta) return;
-
-        const allRelated = results
-          .flatMap((r) => {
-            const val = r[relationMeta.name];
-            if (Array.isArray(val)) return val;
-            if (val && typeof val === "object") return [val];
-            return [];
-          })
-          .filter((r): r is Record<string, unknown> => r !== null);
-
-        if (allRelated.length > 0) {
-          await loadRelations({
-            parentRecords: allRelated,
-            parentModelMeta: relatedModelMeta,
-            allModelsMeta,
-            args: nestedArgs,
-            executor,
-          });
-        }
-      })
-  );
-
-  // ─── _count support (Bug #5) ─────────────────────────────────────
-  // The "query" strategy resolves `_count` after `loadRelations` (see
-  // `loadRelationsForStrategy` in client.ts). The lateral-join strategy
-  // historically returned BEFORE `_count` ran, silently dropping it whenever
-  // the user combined `include: { posts: true, _count: { … } }` with the
-  // join strategy. We mirror the query-strategy behaviour here.
-  const countSpec = resolveCountSpec({ args });
-  if (countSpec && results.length > 0) {
-    await loadRelationCounts({
-      records: results,
-      modelMeta,
-      allModelsMeta,
-      countSpec,
-      executor,
-    });
-  }
-
-  // Populate profiling context with per-phase timings
-  if (profilingCtx) {
-    profilingCtx.queryBuildMs = t1 - t0;
-    profilingCtx.sqlExecMs = t2 - t1;
-    profilingCtx.resultMapMs = t3 - t2;
-    profilingCtx.sql = query.text;
-    profilingCtx.sqlValues = query.values;
-    profilingCtx.rowCount = rows.length;
-  }
-
-  return results;
-}
-
-// ─── Legacy entry point (kept for backward compat) ────────────────
-
-/**
- * @deprecated Use executeLateralJoinQuery instead. This function exists
- * for backward compatibility and performs 2 queries instead of 1.
- */
-export async function loadRelationsWithLateralJoin(params: {
-  parentRecords: Record<string, unknown>[];
-  parentModelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  executor: SqlExecutor;
-  profilingCtx?: ProfilingContext;
-  defaultOrderByPk?: boolean;
-}): Promise<Record<string, unknown>[]> {
-  // For the post-processing path (create, update, etc.), we still need
-  // the 2-query approach since the parent records are already fetched.
-  // But we can use the lateral join to load relations in 1 query instead of N.
-  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } = params;
-
-  if (parentRecords.length === 0) return parentRecords;
-
-  const relationsToLoad = resolveRelationsToLoad({ parentModelMeta, args });
-  if (relationsToLoad.length === 0) return parentRecords;
-
-  const pkField = parentModelMeta.primaryKey[0]!;
-  const parentIds = [
-    ...new Set(
-      parentRecords
-        .map((r) => r[pkField])
-        .filter((id) => id !== undefined && id !== null)
-    ),
-  ];
-
-  if (parentIds.length === 0) return parentRecords;
-
-  // Build a lateral join query scoped to these parent PKs
-  const parentSfMap = getScalarFieldMap({ scalarFields: parentModelMeta.scalarFields });
-  const pkScalar = parentSfMap.get(pkField);
-  const pkDbName = pkScalar?.dbName ?? pkField;
-  const table = `"${parentModelMeta.dbName}"`;
-
-  // Use the lateral join builder with a synthetic WHERE IN for the PKs
-  const syntheticArgs = {
-    ...args,
-    where: {
-      [pkField]: { in: parentIds },
-    },
-  };
-
-  const { query, relationAliases } = buildLateralJoinQuery({
-    modelMeta: parentModelMeta,
-    allModelsMeta,
-    args: syntheticArgs,
-    relationsToLoad,
-    defaultOrderByPk,
-  });
-
-  const rows = await executor(query);
-
-  // Index by PK
-  const relMap = new Map<unknown, Record<string, unknown>>();
-  for (const row of rows) {
-    const pk = row[pkField];
-    const parsed: Record<string, unknown> = {};
-    for (const { alias, relationMeta } of relationAliases) {
-      const jsonValue = row[alias];
-      if (jsonValue === null || jsonValue === undefined) {
-        parsed[relationMeta.name] = relationMeta.isList ? [] : null;
-      } else if (typeof jsonValue === "string") {
-        try {
-          parsed[relationMeta.name] = JSON.parse(jsonValue);
-        } catch {
-          parsed[relationMeta.name] = relationMeta.isList ? [] : null;
-        }
-      } else {
-        parsed[relationMeta.name] = jsonValue;
-      }
-    }
-    relMap.set(pk, parsed);
-  }
-
-  // Stitch relations onto the original parent records
-  for (const parent of parentRecords) {
-    const pk = parent[pkField];
-    const rels = relMap.get(pk);
-    if (rels) {
-      for (const [key, value] of Object.entries(rels)) {
-        parent[key] = value;
-      }
-    } else {
-      for (const { relationMeta } of relationAliases) {
-        parent[relationMeta.name] = relationMeta.isList ? [] : null;
-      }
-    }
-  }
-
-  // Recursively load nested relations in parallel
-  const legacyModelMap = getModelByNameMap({ allModelsMeta });
-  await Promise.all(
-    relationAliases
-      .filter(({ nestedArgs }) => hasNestedRelations({ nestedArgs }))
-      .map(async ({ relationMeta, nestedArgs }) => {
-        const relatedModelMeta = legacyModelMap.get(relationMeta.relatedModel);
-        if (!relatedModelMeta) return;
-
-        const allRelated = parentRecords
-          .flatMap((r) => {
-            const val = r[relationMeta.name];
-            if (Array.isArray(val)) return val;
-            if (val && typeof val === "object") return [val];
-            return [];
-          })
-          .filter((r): r is Record<string, unknown> => r !== null);
-
-        if (allRelated.length > 0) {
-          await loadRelations({
-            parentRecords: allRelated,
-            parentModelMeta: relatedModelMeta,
-            allModelsMeta,
-            args: nestedArgs,
-            executor,
-          });
-        }
-      })
-  );
-
-  return parentRecords;
-}
-
-// ─── Helpers ──────────────────────────────────────────────────────
-
-type RelationAlias = {
-  alias: string;
-  relationMeta: RelationFieldMeta;
-  nestedArgs: Record<string, unknown>;
-};
-
-/**
- * Check whether a Prisma-style where object references any relation field
- * on the given model. Walks AND / OR / NOT combinators recursively.
- * Returns true if any key in the where tree corresponds to a relation field,
- * which means the where-builder will emit EXISTS / NOT EXISTS sub-queries.
- */
-export function whereHasRelationFilter(params: {
-  where: Record<string, unknown> | undefined;
-  modelMeta: ModelMeta;
-}): boolean {
-  const { where, modelMeta } = params;
-  if (!where || typeof where !== "object") return false;
-
-  const relationNames = new Set(
-    (modelMeta.relationFields ?? []).map((r) => r.name)
-  );
-
-  for (const [key, value] of Object.entries(where)) {
-    if (value === undefined) continue;
-
-    // Logical combinators — recurse
-    if (key === "AND" || key === "OR" || key === "NOT") {
-      const items = Array.isArray(value) ? value : [value];
-      for (const item of items) {
-        if (
-          whereHasRelationFilter({
-            where: item as Record<string, unknown>,
-            modelMeta,
-          })
-        ) {
-          return true;
-        }
-      }
-      continue;
-    }
-
-    // Direct relation filter key (some/every/none/is/isNot or shorthand)
-    if (relationNames.has(key)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Resolve which scalar columns to include in a lateral join's inner subquery.
- * Respects nested select/omit so we don't serialise unnecessary columns.
- * Always includes the PK so nested relation loading can stitch correctly.
- */
-function resolveRelatedScalars(params: {
-  relatedModelMeta: ModelMeta;
-  nestedArgs: Record<string, unknown>;
-}): readonly { readonly name: string; readonly dbName: string }[] {
-  const { relatedModelMeta, nestedArgs } = params;
-  const selectArg = nestedArgs.select as Record<string, boolean | object> | undefined;
-  const omitArg = nestedArgs.omit as Record<string, boolean> | undefined;
-
-  if (selectArg) {
-    const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-    const selected = relatedModelMeta.scalarFields.filter((f) => {
-      const val = selectArg[f.name];
-      return val === true || (typeof val === "object" && val !== null);
-    });
-
-    // Always include PK for relation stitching
-    const selectedNames = new Set(selected.map((f) => f.name));
-    for (const pkName of relatedModelMeta.primaryKey) {
-      if (!selectedNames.has(pkName)) {
-        const sf = sfMap.get(pkName);
-        if (sf) selected.push(sf);
-      }
-    }
-
-    return selected;
-  }
-
-  if (omitArg) {
-    return relatedModelMeta.scalarFields.filter((f) => !omitArg[f.name]);
-  }
-
-  // Default: all scalars
-  return relatedModelMeta.scalarFields;
-}
-
-function resolveFkColumn(params: {
-  parentModelMeta: ModelMeta;
-  relationMeta: RelationFieldMeta;
-  relatedModelMeta: ModelMeta;
-}): { fkDbName: string; fkTable: "parent" | "related" } {
-  const { parentModelMeta, relationMeta, relatedModelMeta } = params;
-
-  if (relationMeta.isForeignKey) {
-    // This side (parent) holds the FK
-    return { fkDbName: "", fkTable: "parent" };
-  }
-
-  // The related model holds the FK -- find it (with relationName disambiguation)
-  const parentRelationName = (relationMeta as { relationName?: string }).relationName;
-  const reverseRelation = relatedModelMeta.relationFields.find(
-    (r) => r.relatedModel === parentModelMeta.name && r.isForeignKey &&
-      (!parentRelationName || r.relationName === parentRelationName)
-  );
-
-  if (reverseRelation) {
-    const fkFieldName = reverseRelation.fields[0]!;
-    const fkSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-    const fkField = fkSfMap.get(fkFieldName);
-    return { fkDbName: fkField?.dbName ?? fkFieldName, fkTable: "related" };
-  }
-
-  // Fallback convention
-  return {
-    fkDbName: `${parentModelMeta.name.toLowerCase()}Id`,
-    fkTable: "related",
-  };
-}