@vibeorm/runtime 1.0.0

package/src/lateral-join-builder.ts

@@ -0,0 +1,759 @@
+/**
+ * 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(json_agg(json_build_object(
+ *     'id', __rel."id", 'title', __rel."title", ...
+ *   )), '[]'::json) AS "__vibeorm_rel_posts"
+ *   FROM "Post" __rel WHERE __rel."authorId" = "User"."id"
+ * ) __lat_0 ON true
+ * LEFT JOIN LATERAL (
+ *   SELECT json_build_object(
+ *     'id', __rel."id", 'bio', __rel."bio", ...
+ *   ) AS "__vibeorm_rel_profile"
+ *   FROM "Profile" __rel WHERE __rel."userId" = "User"."id" LIMIT 1
+ * ) __lat_1 ON true
+ * WHERE "User"."role" = $1
+ * ORDER BY "User"."id" ASC
+ * LIMIT 20
+ */
+
+import type {
+  ModelMeta,
+  ModelMetaMap,
+  RelationFieldMeta,
+  SqlQuery,
+  ProfilingContext,
+} from "./types.ts";
+import { getScalarFieldMap, getModelByNameMap } from "./types.ts";
+import { buildWhereClause } from "./where-builder.ts";
+import { loadRelations } from "./relation-loader.ts";
+
+type SqlExecutor = (params: {
+  text: string;
+  values: unknown[];
+}) => Promise<Record<string, unknown>[]>;
+
+// ─── 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[];
+}): { query: SqlQuery; relationAliases: RelationAlias[] } {
+  const { modelMeta, allModelsMeta, args, relationsToLoad } = 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;
+
+  // 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}`;
+
+    // Find the related model meta
+    const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
+    if (!relatedModelMeta) continue;
+
+    // Determine FK column and join condition
+    const { fkDbName, fkTable } = resolveFkColumn({
+      parentModelMeta: modelMeta,
+      relationMeta,
+      relatedModelMeta,
+    });
+
+    // Build json_build_object fields for the related model.
+    // Respect nested select/omit to avoid serialising columns the caller doesn't need.
+    const relatedScalars = resolveRelatedScalars({
+      relatedModelMeta,
+      nestedArgs,
+    });
+    const jsonFields = relatedScalars
+      .map((f) => `'${f.name}', __rel."${f.dbName}"`)
+      .join(", ");
+
+    let lateralSubquery: string;
+
+    if (relationMeta.isList) {
+      // To-many: use json_agg with COALESCE for empty arrays
+      const subWhere = `__rel."${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
+        const relMetaWithAlias = {
+          ...relatedModelMeta,
+          dbName: "__rel" as string, // temporarily override for SQL generation
+        } as unknown as typeof relatedModelMeta;
+        // We can't easily re-alias, so build with original and replace table ref
+        const nestedWhereResult = buildWhereClause({
+          where: nestedArgs.where as Record<string, unknown>,
+          modelMeta: relatedModelMeta,
+          allModelsMeta,
+          paramOffset: paramIdx,
+        });
+        if (nestedWhereResult.sql) {
+          // Replace "TableName". with __rel. for the subquery alias
+          const aliasedSql = nestedWhereResult.sql.replace(
+            new RegExp(`"${relatedModelMeta.dbName}"\\."`, "g"),
+            `__rel."`
+          );
+          nestedWhereSql = ` AND ${aliasedSql}`;
+          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]) => {
+            const sf = relatedSfMap.get(field);
+            const col = sf ? sf.dbName : field;
+            return `__rel."${col}" ${(dir as string).toUpperCase()}`;
+          })
+        );
+        if (clauses.length > 0) {
+          orderBySql = ` ORDER BY ${clauses.join(", ")}`;
+        }
+      }
+
+      let limitSql = "";
+      if (nestedArgs.take !== undefined) {
+        paramIdx++;
+        limitSql = ` LIMIT $${paramIdx}`;
+        allValues.push(nestedArgs.take);
+      }
+
+      let offsetSql = "";
+      if (nestedArgs.skip !== undefined) {
+        paramIdx++;
+        offsetSql = ` OFFSET $${paramIdx}`;
+        allValues.push(nestedArgs.skip);
+      }
+
+      // When take or skip is specified, use a subquery to apply per-parent LIMIT/OFFSET properly
+      if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
+        lateralSubquery = `LEFT JOIN LATERAL (
+    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})), '[]'::jsonb) AS "${colAlias}"
+    FROM (
+      SELECT * FROM "${relatedModelMeta.dbName}" __rel
+      WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
+    ) __rel
+  ) ${alias} ON true`;
+      } else {
+        lateralSubquery = `LEFT JOIN LATERAL (
+    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
+    FROM "${relatedModelMeta.dbName}" __rel
+    WHERE ${subWhere}${nestedWhereSql}
+  ) ${alias} ON true`;
+      }
+    } else {
+      // To-one: use json_build_object 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 = `__rel."${refDbName}" = ${table}."${parentFkDbName}"`;
+      } else {
+        // Related model holds FK (e.g., User.profile -> Profile.userId)
+        joinCondition = `__rel."${fkDbName}" = ${table}."${pkDbName}"`;
+      }
+
+      lateralSubquery = `LEFT JOIN LATERAL (
+    SELECT json_build_object(${jsonFields}) AS "${colAlias}"
+    FROM "${relatedModelMeta.dbName}" __rel
+    WHERE ${joinCondition}
+    LIMIT 1
+  ) ${alias} ON true`;
+    }
+
+    lateralJoins.push(lateralSubquery);
+    lateralSelects.push(`${alias}."${colAlias}"`);
+    relationAliases.push({ alias: colAlias, relationMeta, nestedArgs });
+  }
+
+  // Build WHERE from args
+  const whereResult = buildWhereClause({
+    where: args.where as Record<string, unknown> | undefined,
+    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]) => {
+        const scalarField = sfMap.get(field);
+        const col = scalarField ? scalarField.dbName : field;
+        return `${table}."${col}" ${direction.toUpperCase()}`;
+      })
+    );
+
+    if (orderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  }
+
+  // Build 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 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: args.where as Record<string, unknown> | undefined,
+    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;
+}): Promise<Record<string, unknown>[]> {
+  const { modelMeta, allModelsMeta, args, executor, profilingCtx } = 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,
+  });
+
+  const t1 = profiling ? performance.now() : 0;
+
+  const rows = await executor(query);
+
+  const t2 = profiling ? performance.now() : 0;
+
+  // Parse JSON relation columns
+  const pkField = modelMeta.primaryKey[0]!;
+  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
+    for (const { alias, relationMeta } of relationAliases) {
+      const jsonValue = row[alias];
+      if (jsonValue === null || jsonValue === undefined) {
+        record[relationMeta.name] = relationMeta.isList ? [] : null;
+      } else if (typeof jsonValue === "string") {
+        try {
+          record[relationMeta.name] = JSON.parse(jsonValue);
+        } catch {
+          record[relationMeta.name] = relationMeta.isList ? [] : null;
+        }
+      } else {
+        // Already parsed by bun:sql (json/jsonb columns auto-parse)
+        record[relationMeta.name] = jsonValue;
+      }
+    }
+
+    results.push(record);
+  }
+
+  const t3 = profiling ? performance.now() : 0;
+
+  // Recursively load nested relations (deeper levels fall back to batched)
+  const nestedModelMap = getModelByNameMap({ allModelsMeta });
+  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,
+          });
+        }
+      })
+  );
+
+  // 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;
+}): 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 } = 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,
+  });
+
+  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 RelationToLoad = {
+  relationMeta: RelationFieldMeta;
+  nestedArgs: Record<string, unknown>;
+};
+
+type RelationAlias = {
+  alias: string;
+  relationMeta: RelationFieldMeta;
+  nestedArgs: Record<string, unknown>;
+};
+
+export function resolveRelationsToLoad(params: {
+  parentModelMeta: ModelMeta;
+  args: Record<string, unknown>;
+}): RelationToLoad[] {
+  const { parentModelMeta, args } = params;
+  const result: RelationToLoad[] = [];
+
+  const select = args.select as Record<string, unknown> | undefined;
+  const include = args.include as Record<string, unknown> | undefined;
+
+  for (const relationMeta of parentModelMeta.relationFields) {
+    let shouldLoad = false;
+    let nestedArgs: Record<string, unknown> = {};
+
+    if (select) {
+      const val = select[relationMeta.name];
+      if (val === true) {
+        shouldLoad = true;
+      } else if (typeof val === "object" && val !== null) {
+        shouldLoad = true;
+        nestedArgs = val as Record<string, unknown>;
+      }
+    }
+
+    if (include) {
+      const val = include[relationMeta.name];
+      if (val === true) {
+        shouldLoad = true;
+      } else if (typeof val === "object" && val !== null) {
+        shouldLoad = true;
+        nestedArgs = val as Record<string, unknown>;
+      }
+    }
+
+    if (shouldLoad) {
+      result.push({ relationMeta, nestedArgs });
+    }
+  }
+
+  return result;
+}
+
+function hasNestedRelations(params: { nestedArgs: Record<string, unknown> }): boolean {
+  const { nestedArgs } = params;
+  return (
+    nestedArgs.include !== undefined ||
+    (typeof nestedArgs.select === "object" && nestedArgs.select !== null)
+  );
+}
+
+/**
+ * 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 json_build_object.
+ * 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 selected = relatedModelMeta.scalarFields.filter((f) => {
+      const val = selectArg[f.name];
+      return val === true || (typeof val === "object" && val !== null);
+    });
+
+    // Always include PK for relation stitching
+    for (const pkName of relatedModelMeta.primaryKey) {
+      if (!selected.some((f) => f.name === pkName)) {
+        const sf = relatedModelMeta.scalarFields.find((f) => f.name === 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",
+  };
+}