turbine-orm 0.65.0 → 0.66.0

package/dist/query/filters.js

@@ -6,7 +6,8 @@
  * and execution rather than filter-shape bookkeeping.
  */
 import { ValidationError } from '../errors.js';
-import { OPERATOR_KEYS } from './utils.js';
+import { assertDirectionToken, assertOrderDirection } from './types.js';
+import { OPERATOR_KEYS, resolveColumnName } from './utils.js';
 // ---------------------------------------------------------------------------
 // Where-operator detection
 // ---------------------------------------------------------------------------
@@ -42,6 +43,47 @@ export function isUnmatchedPlainObject(value) {
  * take values only.
  */
 export const COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * THE relation-filter wrappers: the keys whose body is a clause against the
+ * relation's TARGET table rather than against this one.
+ *
+ * One named list, here, because everything that walks a where clause has to
+ * agree about them and the copies had already spread. It lived inlined in
+ * `where-compile.ts` (`'some' in x || 'every' in x || …`, the SQL compiler's
+ * own answer), again in `normalizeRelationFilter` (where.ts) as the negated
+ * conjunction of the same five, again in `cli/pii-predicate-guard.ts`, and a
+ * fourth time in `prisma-compat.ts` SPLIT across a
+ * `RELATION_QUANTIFIERS` set (`some`/`every`/`none`) plus two inline
+ * `k === 'is' || k === 'isNot'` tests, which is the copy most likely to drift
+ * because half of it does not read as a list and a grep for the list does not
+ * find it.
+ *
+ * The failure mode is not cosmetic: a wrapper the SQL compiler treats as a
+ * relation filter but a WALKER does not is a wrapper whose body reaches the
+ * builder unwalked. That is precisely the operand-position channel this
+ * release closed elsewhere.
+ *
+ * `query/` is the right home rather than `cli/` because the direction of the
+ * dependency is fixed: `cli/` and the prisma-compat shim may import from the
+ * query path, and the query path may never import from `cli/`
+ * (`scripts/check-import-cycles.mjs`).
+ */
+export const RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
+/** {@link RELATION_FILTER_WRAPPERS} as a membership set, for the walkers. */
+export const RELATION_FILTER_WRAPPER_SET = new Set(RELATION_FILTER_WRAPPERS);
+/**
+ * True when a normalized relation-filter body carries at least one cardinality
+ * wrapper. THE predicate the SQL compiler branches on: a key that names a
+ * relation but whose value is not one of these falls through to the scalar
+ * path.
+ */
+export function hasRelationFilterWrapper(filterObj) {
+    for (const wrapper of RELATION_FILTER_WRAPPERS) {
+        if (wrapper in filterObj)
+            return true;
+    }
+    return false;
+}
 /**
  * Check if an operator value is a column reference: a plain object whose ONLY
  * key is `col` with a string value. Anything else (extra keys, non-string
@@ -417,6 +459,209 @@ export function orderByEntries(orderBy) {
     }
     return [];
 }
+// ---------------------------------------------------------------------------
+// ORDER BY key identity and arity
+// ---------------------------------------------------------------------------
+/**
+ * The longest `orderBy` whose statement keeps a NAMED prepared statement.
+ * Past this, the compile paths call `markVariableArity` and the statement is
+ * sent unnamed for the same reason a caller-written `OR` array is.
+ *
+ * WHY 3, and why a threshold at all. Refusing duplicate sort keys
+ * ({@link dedupeOrderEntries}) bounds an `orderBy` to the table's column
+ * count, which sounds like enough and is not: what is left is the PERMUTATION
+ * space. A 20-column table admits 20 one-key sorts, 380 two-key sorts, 6,840
+ * three-key sorts and 116,280 four-key sorts, and every one of those is a
+ * distinct SQL text and therefore a distinct un-reclaimable server-side
+ * prepared statement. The count is dominated by its longest term, so a cap on
+ * LENGTH is what actually bounds the total.
+ *
+ * 3 because that is where real sorts stop and generated ones start. The two
+ * shapes that show up in application code are a single sort key, and a sort key
+ * plus a tiebreaker for stable pagination (`[{createdAt:'desc'},{id:'asc'}]`).
+ * Three covers the widest genuinely hand-written form, a category or priority
+ * followed by recency followed by a primary-key tiebreak. A fourth key is
+ * effectively always a UI that lets the caller stack sort columns, which is
+ * exactly the shape that should not be minting named statements. The asymmetry
+ * of the two errors also points this way: naming a 4-key sort risks the 116,280
+ * above, while NOT naming one costs a single extra server-side parse per
+ * execution on a query that is already rare.
+ */
+export const MAX_NAMED_ORDER_KEYS = 3;
+/**
+ * Canonical identity of ONE order term's sort EXPRESSION, or `null` when this
+ * rule declines to decide for that shape.
+ *
+ * DIRECTION IS DELIBERATELY EXCLUDED. `ORDER BY id ASC, id DESC` sorts exactly
+ * like `ORDER BY id ASC`: the first term already totally orders the rows it
+ * covers, so no later term on the same expression can move anything, whichever
+ * way it points. Including the direction would have missed the very case that
+ * motivated this, a pair of entries spelled differently AND pointing
+ * differently.
+ *
+ * The column is RESOLVED rather than compared as spelled, via the same
+ * `resolveColumnName` every SQL builder resolves keys through, so `userId` and
+ * `user_id` on an introspected schema are recognised as the one column they
+ * both compile to. Falls back to the raw key when the key resolves to nothing
+ * (metadata-less test schemas): the compile path a few lines later is what
+ * reports an unknown field, and this function must not pre-empt that error with
+ * a worse one.
+ *
+ * `null` (not compared) for two shapes:
+ *  - VECTOR KNN ordering. Two distance terms on one column with DIFFERENT
+ *    target vectors are genuinely different expressions and the second is not a
+ *    no-op, so deciding would mean hashing the operand, which is a 1,536-float
+ *    array on a typical embedding column. Not worth the per-build cost for a
+ *    shape that {@link MAX_NAMED_ORDER_KEYS} already bounds.
+ *  - RELATION ordering (`{posts:{_count:'desc'}}`, `{author:{name:'asc'}}`,
+ *    pick-row). Same reason in a different key: the expression is a correlated
+ *    subquery whose identity is its whole nested shape.
+ * Both are bounded by the length cap; neither can be refused wrongly here.
+ */
+export function orderKeyIdentity(meta, key, value) {
+    if (isVectorOrderBy(value))
+        return null;
+    if (isJsonPathOrderBy(value)) {
+        // Same column AND same path AND same cast is one expression; a different
+        // path or a numeric-vs-text cast is a different one, and both are ordinary
+        // in a multi-key sort over a document column.
+        const column = resolvedOrderColumn(meta, key);
+        return `json:${column}:${value.type ?? ''}:${JSON.stringify(value.path)}`;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value) && !isOrderBySpec(value)) {
+        return null;
+    }
+    return `col:${resolvedOrderColumn(meta, key)}`;
+}
+/** {@link resolveColumnName} with the raw key as the unresolvable fallback. */
+function resolvedOrderColumn(meta, key) {
+    return (meta ? resolveColumnName(meta, key) : undefined) ?? key;
+}
+/**
+ * Remove `orderBy` entries that sort by an expression an earlier entry already
+ * sorted by. Returns `null` when nothing is redundant, which is the common case
+ * and the one that must stay allocation-light and byte-identical.
+ *
+ * WHY THIS DROPS RATHER THAN REFUSES, because the reverse was specified and the
+ * premise turned out not to hold. A repeated sort key is a no-op in SQL, and it
+ * is the only way to push an `orderBy` past the table's column count (measured:
+ * `[{id:'asc'}] x n` produced a distinct named prepared statement for every n,
+ * from ONE column, with no ceiling short of the request body size). Both of
+ * those are true. What is NOT true is that it is always a caller bug. The
+ * idiomatic stable-pagination shape is
+ *
+ *     orderBy: [{ [sortField]: sortDir }, { id: 'asc' }]
+ *
+ * appending a primary-key tiebreak unconditionally, which is correct defensive
+ * code, and which produces a duplicate exactly when the caller sorts by the
+ * primary key. That is a column header a user clicks, so refusing would turn a
+ * working table into a 500 on one column and no others. This repo's own
+ * differential fuzz generator writes that pattern, comment included ("a random
+ * key first, the PK as final tiebreaker"), and picks the sort field from a pool
+ * that contains `id`, so a refusal would have failed the suite on 10-35% of
+ * generated cases depending on table width.
+ *
+ * Dropping has no such failure mode: the removed term provably cannot move a
+ * row, so the result set and its order are unchanged, and the caller is told
+ * about the redundancy through a dev-only warn-once instead of an exception.
+ * The security outcome is identical, because what actually bounds the emitted
+ * statement set is the length cap ({@link MAX_NAMED_ORDER_KEYS}), which is
+ * shape-blind and applies to repeats and permutations alike. This function's
+ * job is narrower: keep the ordinary two-key sort under that cap so it keeps
+ * its named statement.
+ *
+ * A DROPPED TERM IS STILL VALIDATED, see {@link assertDroppedDirection}. The
+ * drop is an optimization, and an optimization must not decide whether an input
+ * is legal.
+ *
+ * @param table the table the sort is against, so a refused direction reads
+ *   exactly as it does when the compile path raises it. Defaults to the
+ *   metadata's own name, which is what a caller holding only a `TableMetadata`
+ *   would have passed anyway.
+ */
+export function dedupeOrderEntries(meta, entries, table = meta?.name) {
+    if (entries.length < 2)
+        return null;
+    const seen = new Map();
+    let dropped;
+    const kept = [];
+    for (const entry of entries) {
+        const identity = orderKeyIdentity(meta, entry[0], entry[1]);
+        const first = identity === null ? undefined : seen.get(identity);
+        if (first !== undefined) {
+            assertDroppedDirection(entry[0], entry[1], table);
+            // Resolved only on the dropping branch, so the advisory can name the one
+            // column two different spellings landed on without costing the hot path.
+            if (dropped === undefined)
+                dropped = [];
+            dropped.push({ key: entry[0], first, resolved: resolvedOrderColumn(meta, entry[0]) });
+            continue;
+        }
+        if (identity !== null)
+            seen.set(identity, entry[0]);
+        kept.push(entry);
+    }
+    return dropped ? { entries: kept, dropped } : null;
+}
+/**
+ * Validate the direction of a term this function is about to DROP.
+ *
+ * Without this the drop swallowed the check, because the direction guard lives
+ * on the COMPILE path (`buildOrderBy`) and a dropped term never reaches it:
+ * `orderBy: [{id:'asc'}, {id:'sideways'}]` was silently accepted while
+ * `orderBy: [{id:'sideways'}]` alone raised E003, and `groupBy` (which
+ * validates BEFORE its own dedupe) still refused the identical input, so the
+ * two surfaces disagreed about whether a query was valid. Whether a bad
+ * direction is reported must not depend on whether some earlier term happened
+ * to name the same column.
+ *
+ * Only two shapes can reach here, which is what makes the branch exhaustive:
+ * {@link orderKeyIdentity} returns `null` (never deduped, never dropped) for
+ * the vector and relation shapes, leaving the JSON-path form and the plain
+ * column / OrderBySpec form. Each is checked with exactly the guard
+ * `buildOrderBy` (relations.ts) would have applied to it, message included, so
+ * a dropped term is accepted or refused identically to a kept one.
+ */
+function assertDroppedDirection(key, value, table) {
+    if (isJsonPathOrderBy(value)) {
+        assertDirectionToken(value.direction, `JSON-path orderBy on "${key}"`);
+        return;
+    }
+    assertOrderDirection(value, table === undefined ? `orderBy "${key}"` : `orderBy "${key}" on table "${table}"`);
+}
+/**
+ * The {@link dedupeOrderEntries} rule applied to a `DISTINCT ON` column list,
+ * the other caller-supplied list written into the SQL one term per element.
+ * `DISTINCT ON (a, a)` groups exactly as `DISTINCT ON (a)` does, so a repeat is
+ * a no-op here too, and the same generated-code shape produces it (a grouping
+ * column chosen by the caller, plus a fixed one appended by the code).
+ *
+ * No length cap to go with it, deliberately. Unlike `orderBy`, `DISTINCT ON`
+ * has a meaning that degrades as the list grows (every added column makes the
+ * result strictly less distinct, converging on the plain query), so a long list
+ * is self-limiting in a way a long sort is not.
+ */
+export function dedupeColumnList(meta, columns) {
+    if (columns.length < 2)
+        return null;
+    const seen = new Map();
+    let dropped;
+    const kept = [];
+    for (const key of columns) {
+        const column = typeof key === 'string' ? resolvedOrderColumn(meta, key) : null;
+        const first = column === null ? undefined : seen.get(column);
+        if (first !== undefined && column !== null) {
+            if (dropped === undefined)
+                dropped = [];
+            dropped.push({ key, first, resolved: column });
+            continue;
+        }
+        if (column !== null)
+            seen.set(column, key);
+        kept.push(key);
+    }
+    return dropped ? { columns: kept, dropped } : null;
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/query/relations.d.ts

@@ -269,19 +269,19 @@ export declare function collectManyToManyTargetGlobalFilter(qi: BuilderCtx, relD
  * when a filter applies, no-op otherwise.
  */
 export declare function collectRelationCountParams(qi: BuilderCtx, relDef: RelationDef, params: unknown[]): void;
-export declare function getCamelDateFields(qi: BuilderCtx, table: string, meta: TableMetadata): Set<string>;
 /**
- * Parse a row that may contain JSON nested relation columns.
+ * Per-table memo of `[relationName, relDef]` pairs, alongside the existing
+ * camelCase-date memo and for the same reason.
  *
- * `fromJson` says where THIS row's own scalar columns came from. A root row
- * (join, batched, flatten) is read straight off the driver, so `false`; a row
- * decoded out of a `json_agg`/`json_build_object` column is `true` and gets
- * its divergent scalars decoded back to the driver's representation first (see
- * the JSON-wire section above). Recursion into a relation column is always
- * `true`, which is exactly right on every strategy: `batched` and `flatten`
- * hand this function driver rows, but any relation still nested INSIDE one of
- * those rows arrived as a correlated JSON subquery.
+ * {@link parseNestedRow} walks every relation on the table for EVERY row, and
+ * `Object.entries(meta.relations)` allocates a fresh array of fresh two-element
+ * arrays each time it does. Measured at 227 ns per row on a 12-relation table
+ * against 2 ns for a hoisted list, in the single largest ORM function in the
+ * live CPU profile. The relation map is immutable metadata, so one array per
+ * table is all that is ever needed.
  */
+export declare function getRelationEntries(qi: BuilderCtx, table: string, meta: TableMetadata): [string, RelationDef][];
+export declare function getCamelDateFields(qi: BuilderCtx, table: string, meta: TableMetadata): Set<string>;
 export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unknown>, table: string, fromJson?: boolean): Record<string, unknown>;
 /**
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.

package/dist/query/relations.js

@@ -16,9 +16,9 @@ import { CircularRelationError, RelationError, UnsupportedFeatureError, Validati
 import { missingIndexForRelation } from '../index-advisor.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
-import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
+import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { ownLookup, relationInProjectionMessage, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
+import { canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -114,9 +114,36 @@ export function resolveProjection(qi, table, meta, select, omit, includePii) {
         }
         // Only include columns where value is true. An explicit `select` naming a
         // PII column IS the opt-in: it comes back regardless of `includePii`.
-        return Object.entries(select)
+        //
+        // Emitted in the TABLE's column order, not the caller's key order, which is
+        // the same order the `omit` and default branches below produce. Two reasons,
+        // and the first is a security bound:
+        //
+        // 1. The SELECT list is SQL TEXT, so a caller who reorders their `select`
+        //    keys mints a distinct, permanently-cached, server-side prepared
+        //    statement per permutation (measured: 5,040 statements and 39 MB of
+        //    CachedPlanSource from ONE seven-column table). That is the same
+        //    unbounded-statement failure the `markVariableArity` rule bounds for
+        //    caller-chosen ARITY, reached through caller-chosen ORDER instead, which
+        //    needs no array and no unusual input. `omit` never had it precisely
+        //    because it derives from `allColumns`. See `canonicalColumnOrder`.
+        // 2. It removes a real lockstep hazard. `withFingerprint` already SORTS a
+        //    relation's `select` keys, so the cache key was permutation-invariant
+        //    while the SQL was not: the second permutation was served the first
+        //    one's statement. Harmless for the keyed JSON encoding, NOT harmless for
+        //    `jsonEncoding: 'positional'`, where the emitted array order comes from
+        //    the cached SQL and the decoder (`buildRelationShape`) is rebuilt from
+        //    the current args, so values landed under the wrong keys.
+        //
+        // Order is safe to change here because nothing downstream reads the
+        // projection positionally except through THIS list: the SELECT list, the
+        // relation `json_build_object` pairs and the positional `RelationShape`
+        // keys are all derived from it, so they move together. The one observable
+        // consequence is that a projected row's KEY INSERTION order now follows the
+        // table rather than the `select` literal.
+        return canonicalColumnOrder(meta, Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => projectionColumn(table, meta, k, 'select'));
+            .map(([k]) => projectionColumn(table, meta, k, 'select')));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
@@ -421,8 +448,17 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
     // rules in step, so it is gone. See orderby-unknown-field.test.ts, which pins
     // the refusal itself across that surface.
     const meta = qi.schema.tables[qi.table];
+    const entries = orderByEntries(orderBy);
+    // A long ORDER BY writes one comma-separated term per entry into the SQL
+    // TEXT, so its length is an arity the caller chose and the statement gives up
+    // its server-side name. Marked HERE, on the compile path, because that is the
+    // window `buildCacheEntry` brackets; redundant terms have already been
+    // dropped upstream (buildFindMany), so this counts real ones. See
+    // MAX_NAMED_ORDER_KEYS in filters.ts for why the threshold is where it is.
+    if (entries.length > MAX_NAMED_ORDER_KEYS)
+        qi.markVariableArity();
     let relOrdCounter = 0;
-    return orderByEntries(orderBy)
+    return entries
         .map(([key, value]) => {
         // Vector KNN ordering: { distance: { to, metric, direction? } }
         if (isVectorOrderBy(value)) {
@@ -966,6 +1002,16 @@ export function collectRelationPickOrderParams(qi, relName, relDef, spec, params
  * in the same order, by {@link collectRelationOrderParams}.
  */
 export function buildRelationOrderClause(qi, targetTable, targetMeta, alias, orderEntries, params) {
+    // Same length cap as the top-level `buildOrderBy`. A relation's orderBy comes
+    // from the same request body and its terms are written into the same
+    // statement, so it carries the same exposure. This is the shared choke point
+    // for both to-many shapes (the wrapped hasMany subquery and the m2m junction
+    // subquery). Redundant-term dropping is deliberately NOT mirrored here: it
+    // would have to happen before the `with` fingerprint to stay in lockstep with
+    // the collect path, and a no-op term inside a relation costs only itself
+    // while the cap already bounds what matters.
+    if (orderEntries.length > MAX_NAMED_ORDER_KEYS)
+        qi.markVariableArity();
     let relOrdCounter = 0;
     const orders = orderEntries
         .map(([key, dirValue]) => {
@@ -1113,6 +1159,25 @@ export function collectRelationCountParams(qi, relDef, params) {
         whereMod.collectTargetGlobalFilterAlias(qi, relDef.to, params);
     }
 }
+/**
+ * Per-table memo of `[relationName, relDef]` pairs, alongside the existing
+ * camelCase-date memo and for the same reason.
+ *
+ * {@link parseNestedRow} walks every relation on the table for EVERY row, and
+ * `Object.entries(meta.relations)` allocates a fresh array of fresh two-element
+ * arrays each time it does. Measured at 227 ns per row on a 12-relation table
+ * against 2 ns for a hoisted list, in the single largest ORM function in the
+ * live CPU profile. The relation map is immutable metadata, so one array per
+ * table is all that is ever needed.
+ */
+export function getRelationEntries(qi, table, meta) {
+    let entries = qi.relationEntryCache.get(table);
+    if (!entries) {
+        entries = Object.entries(meta.relations);
+        qi.relationEntryCache.set(table, entries);
+    }
+    return entries;
+}
 export function getCamelDateFields(qi, table, meta) {
     let camel = qi.camelDateFieldCache.get(table);
     if (!camel) {
@@ -1136,6 +1201,9 @@ export function getCamelDateFields(qi, table, meta) {
  * hand this function driver rows, but any relation still nested INSIDE one of
  * those rows arrived as a correlated JSON subquery.
  */
+/** The reserved relation-`_count` column prefix, and its first char code. */
+const COUNT_PREFIX = '_count__';
+const UNDERSCORE_CHAR = 95;
 export function parseNestedRow(qi, row, table, fromJson = false) {
     const meta = qi.schema.tables[table];
     if (!meta)
@@ -1143,18 +1211,30 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
     const parsed = qi.parseRow(fromJson ? decodeJsonWireRow(qi, row, table, meta) : row, table);
     // Assemble reserved `_count__<rel>` scalar columns into a `_count` object.
     // parseRow copies these unknown columns through under their raw key.
+    //
+    // `for…in` with a first-character reject, rather than `Object.keys(...)`
+    // plus `startsWith`: the old form allocated a fresh key array for EVERY row
+    // of every query purely to discover that nothing started with `_count__`,
+    // which is the case for every query that did not ask for a relation `_count`
+    // (almost all of them). `for…in` allocates nothing, and `_` is a rare first
+    // character on a real field, so the common row costs one charCode compare
+    // per key. Deletion is deferred out of the loop so the scan stays on V8's
+    // enum-cache fast path; the resulting key order is unchanged (the same keys
+    // are removed, and `_count` is appended last either way).
     let countObj;
-    for (const key of Object.keys(parsed)) {
-        if (key.startsWith('_count__')) {
-            if (countObj === undefined)
-                countObj = {};
-            countObj[key.slice('_count__'.length)] = Number(parsed[key]);
-            delete parsed[key];
-        }
+    for (const key in parsed) {
+        if (key.charCodeAt(0) !== UNDERSCORE_CHAR || !key.startsWith(COUNT_PREFIX))
+            continue;
+        if (countObj === undefined)
+            countObj = {};
+        countObj[key.slice(COUNT_PREFIX.length)] = Number(parsed[key]);
     }
-    if (countObj)
+    if (countObj) {
+        for (const rel of Object.keys(countObj))
+            delete parsed[`${COUNT_PREFIX}${rel}`];
         parsed._count = countObj;
-    for (const [relName, relDef] of Object.entries(meta.relations)) {
+    }
+    for (const [relName, relDef] of getRelationEntries(qi, table, meta)) {
         const rawValue = row[relName];
         if (rawValue === undefined)
             continue;

package/dist/query/types.d.ts

@@ -405,7 +405,20 @@ export type TypedOrderByClause<T, R extends object> = TypedOrderByObject<T, R> |
 export type WithFieldFlags<NestedT> = [unknown] extends [NestedT] ? Record<string, boolean> : {
     [K in keyof NestedT]?: boolean;
 };
-export interface WithOptions<NestedR extends object = {}, NestedT = unknown> {
+/**
+ * `Record<never, never>` rather than `{}` for the "no nested relations known"
+ * default, and the difference is load-bearing rather than cosmetic: the degrade
+ * branches in {@link TypedWithClause} and {@link TypedOrderByObject} test
+ * `[keyof R] extends [never]`, so the default has to be a type whose `keyof` IS
+ * `never`. `object` (biome's first suggestion) has `keyof object = never` too
+ * but admits any object, and `Record<string, never>` has `keyof = string`,
+ * which would silently flip every untyped `with` clause off the open escape
+ * hatch and onto key checking against no keys at all, i.e. reject everything. A
+ * mapped type over `never` resolves to exactly the empty object type, so this
+ * is the same type `{}` was, spelled in a way that says which property of it
+ * matters.
+ */
+export interface WithOptions<NestedR extends object = Record<never, never>, NestedT = unknown> {
     with?: TypedWithClause<NestedR>;
     /** Filter the related rows. Keys are checked against the relation target when it is known (see {@link WithWhere}). */
     where?: WithWhere<NestedT, NestedR>;