turbine-orm 0.71.0 → 0.72.0

package/dist/query/batched-loader.js

@@ -56,7 +56,7 @@
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
 import { dedupeOrderEntries, isOrderBySpec, isRelationPickOrderBy, orderByEntries, sortedEntries } from './filters.js';
-import { markInternalCombinator, ownLookup, selectNamesNothingMessage, selectOmitExclusiveMessage, sqlToPreparedName, } from './utils.js';
+import { markInternalCombinator, ownLookup, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, sqlToPreparedName, } from './utils.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit, it
@@ -153,8 +153,12 @@ function partitionOrderBy(meta, orderBy) {
         return null;
     const out = [];
     for (const [key, value] of entries) {
-        const column = ownLookup(meta.columnMap, key);
-        if (!column || !meta.allColumns.includes(column))
+        // The one key-resolution rule. A bare `columnMap` read knows only the
+        // FIELD spelling, so a snake-spelled orderBy declined the partition
+        // pushdown and silently fell back to fetching every child row and slicing
+        // client-side: two strategies, different bytes over the wire, one query.
+        const column = resolveColumnName(meta, key);
+        if (column === undefined)
             return null;
         let sort;
         let nulls;
@@ -265,7 +269,18 @@ export function assertProjectionShape(table, select, omit) {
         throw new ValidationError(selectOmitExclusiveMessage(table));
     }
 }
-export function includeKeysForBatching(select, omit, fields, 
+export function includeKeysForBatching(
+/**
+ * The table the projection is compiled against. `select` / `omit` keys are
+ * the CALLER's, and a column has two legal spellings there, so matching by
+ * raw key made "is the correlation key already projected?" depend on which
+ * was used: `select: { user_id: true }` with a `userId` key looked
+ * unprojected, so the key was force-added AND marked stitch-only and
+ * `stripFields` deleted the very column the caller asked for, while
+ * `omit: { user_id: true }` failed to un-omit and tripped
+ * `assertCorrelationKeyProjected`'s "bug in turbine" path on a legal query.
+ */
+meta, select, omit, fields, 
 /**
  * The default projection for this table when it is NOT `select`/`omit`-driven:
  * `hidden` are fields the default projection leaves out (today: PII-tagged
@@ -279,23 +294,43 @@ export function includeKeysForBatching(select, omit, fields,
  */
 defaultProjection) {
     const unique = [...new Set(fields)];
+    /**
+     * The caller's projection keys indexed by the column each resolves to, so a
+     * correlation key is recognized under either spelling. A key resolving to no
+     * column is left out: the projection build raises E003, where it belongs.
+     */
+    const keyByColumn = (projection) => {
+        const byColumn = new Map();
+        for (const key of Object.keys(projection)) {
+            const column = resolveColumnName(meta, key);
+            if (column !== undefined)
+                byColumn.set(column, key);
+        }
+        return byColumn;
+    };
+    /** `fields` are canonical field names, but resolve them anyway rather than assume. */
+    const columnOf = (field) => resolveColumnName(meta, field) ?? field;
     if (select) {
         const next = { ...select };
         const strip = [];
+        const selected = keyByColumn(select);
         for (const f of unique) {
-            if (!next[f]) {
-                next[f] = true;
-                strip.push(f); // not requested by the caller, added only to stitch
-            }
+            const existing = selected.get(columnOf(f));
+            if (existing !== undefined && next[existing])
+                continue; // already projected, under either spelling
+            next[f] = true;
+            strip.push(f); // not requested by the caller, added only to stitch
         }
         return { select: next, omit, strip };
     }
     if (omit) {
         const next = { ...omit };
         const strip = [];
+        const omitted = keyByColumn(omit);
         for (const f of unique) {
-            if (next[f]) {
-                delete next[f]; // un-omit so the key is present; the caller wanted it gone
+            const existing = omitted.get(columnOf(f));
+            if (existing !== undefined && next[existing]) {
+                delete next[existing]; // un-omit so the key is present; the caller wanted it gone
                 strip.push(f);
             }
         }
@@ -623,7 +658,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     const orderFields = pushDownLimit
         ? (windowOrder ?? []).map((o) => targetMeta.reverseColumnMap[o.column] ?? o.column)
         : [];
-    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField, ...orderFields, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
+    const proj = includeKeysForBatching(targetMeta, options.select, options.omit, [childKeyField, ...orderFields, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const buildChunk = (chunk) => child.buildFindMany({
         where: mergeChildWhere(options.where, childKeyField, chunk),
@@ -826,7 +861,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     // reason as the to-many loader above: this level's PK is not the only key the
     // recursion below will ask these rows for.
     assertProjectionShape(targetMeta.name, options.select, options.omit);
-    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
+    const proj = includeKeysForBatching(targetMeta, options.select, options.omit, [targetPkField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const buildTargetChunk = (chunk) => child.buildFindMany({
         where: mergeChildWhere(options.where, targetPkField, chunk),

package/dist/query/builder.d.ts

@@ -538,6 +538,19 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * so a warm template can never serve a call the cold path would refuse.
      */
     private resolveJsonEncoding;
+    /**
+     * `args` with every `with` relation key replaced by the relation's DECLARED
+     * spelling, so a snake_case relation name resolves the way a snake_case
+     * column name already does.
+     *
+     * Returns `args` by reference when nothing needed rewriting, which is every
+     * query that already spells its relations the declared way. Runs before the
+     * stable-order pass and before `withFingerprint`, so the whole pipeline, and
+     * the SQL cache key with it, sees one spelling. The rule and the reason it is
+     * applied ONCE here rather than at each of the six `with` walkers are in
+     * query/relation-names.ts.
+     */
+    private withDeclaredRelationNames;
     /**
      * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
      * explicit one, recursing into nested `with`. Returns a CLONED clause (user

package/dist/query/builder.js

@@ -19,9 +19,10 @@ import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { dedupeColumnList, dedupeOrderEntries, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
+import { normalizeWithClause } from './relation-names.js';
 import * as relationsMod from './relations.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
+import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -1064,6 +1065,24 @@ export class QueryInterface {
         this.currentJsonEncoding = argEncoding;
         return argEncoding;
     }
+    /**
+     * `args` with every `with` relation key replaced by the relation's DECLARED
+     * spelling, so a snake_case relation name resolves the way a snake_case
+     * column name already does.
+     *
+     * Returns `args` by reference when nothing needed rewriting, which is every
+     * query that already spells its relations the declared way. Runs before the
+     * stable-order pass and before `withFingerprint`, so the whole pipeline, and
+     * the SQL cache key with it, sees one spelling. The rule and the reason it is
+     * applied ONCE here rather than at each of the six `with` walkers are in
+     * query/relation-names.ts.
+     */
+    withDeclaredRelationNames(args) {
+        if (!args?.with)
+            return args;
+        const normalized = normalizeWithClause(this.schema, this.table, args.with);
+        return normalized === args.with ? args : { ...args, with: normalized };
+    }
     /**
      * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
      * explicit one, recursing into nested `with`. Returns a CLONED clause (user
@@ -1084,7 +1103,7 @@ export class QueryInterface {
         for (const [relName, spec] of Object.entries(withClause)) {
             if (relName === '_count' || !spec)
                 continue; // `_count` is a count, not a row load
-            const rel = ownLookup(meta.relations, relName);
+            const rel = resolveRelationDef(meta.relations, relName);
             if (!rel)
                 continue; // unknown relation, let the build path surface E005
             const options = spec === true ? {} : spec;
@@ -1471,7 +1490,7 @@ export class QueryInterface {
                 }
                 continue;
             }
-            const rel = ownLookup(this.tableMeta.relations, key);
+            const rel = resolveRelationDef(this.tableMeta.relations, key);
             if (!rel) {
                 joinWith[key] = spec; // unknown relation, let the join path surface E005
                 continue;
@@ -1581,7 +1600,7 @@ export class QueryInterface {
         const includePii = resolveUnsafeFlag(args.includePii, 'includePii');
         const needed = neededParentKeyFields(this.tableMeta, batchedWith);
         assertProjectionShape(this.table, args.select, args.omit);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, includePii));
+        const proj = includeKeysForBatching(this.tableMeta, args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, includePii));
         const hasJoin = Object.keys(joinWith).length > 0;
         // Force the residual `with` onto the join plan so the base query never
         // re-enters this auto planning.
@@ -1719,6 +1738,10 @@ export class QueryInterface {
      * from the returned rows, so the shape matches the join strategy exactly.
      */
     async runFindManyBatched(args) {
+        // Declared relation spellings first, exactly as the join path does in
+        // buildFindMany: the loader reads `args.with` itself, so without this the
+        // two strategies would disagree about which relation names are valid.
+        args = this.withDeclaredRelationNames(args);
         // Stable relation order (opt-in): the batched loader forwards each relation's
         // orderBy into its follow-up query, so filling the synthesized PK order here
         // makes the batched output deterministic exactly like the join path.
@@ -1753,7 +1776,7 @@ export class QueryInterface {
     prepareBatchedBase(args, withClause) {
         const needed = neededParentKeyFields(this.tableMeta, withClause);
         assertProjectionShape(this.table, args.select, args.omit);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
+        const proj = includeKeysForBatching(this.tableMeta, args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
             with: undefined,
@@ -2125,6 +2148,15 @@ export class QueryInterface {
     // findUnique
     // -------------------------------------------------------------------------
     async findUnique(args) {
+        // BEFORE the strategy branch, not only inside the builders, so the
+        // join-vs-batched decision and its dev warning see the same declared name
+        // every other stage does. `planAuto` splits `with` on the caller's keys and
+        // `runAutoSplit` carries them onward; each downstream consumer normalizes
+        // too, so this is not load-bearing for correctness (measured: removing it
+        // changes the warning text from the declared name back to the caller's and
+        // nothing else). It is here so the invariant holds at the seam rather than
+        // depending on every consumer to re-establish it.
+        args = this.withDeclaredRelationNames(args);
         return this.executeWithMiddleware('findUnique', args, async () => {
             if (args.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
@@ -2152,6 +2184,8 @@ export class QueryInterface {
      * strategy's shape for the one row.
      */
     async runFindUniqueBatched(args) {
+        // Declared relation spellings first, see runFindManyBatched.
+        args = this.withDeclaredRelationNames(args);
         // Stable relation order (opt-in), see runFindManyBatched.
         const withClause = this.resolveStableOrder(args.stableRelationOrder)
             ? this.applyStableRelationOrder(args.with, this.table)
@@ -2160,7 +2194,7 @@ export class QueryInterface {
         rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
         assertProjectionShape(this.table, args.select, args.omit);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
+        const proj = includeKeysForBatching(this.tableMeta, args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -2205,6 +2239,9 @@ export class QueryInterface {
                 'A key whose value is `undefined` does not count, check that the value you are looking up is defined. ' +
                 'If you meant "any row matching an optional filter", use `findFirst`.');
         }
+        // Declared relation spellings first, before stable-order and the
+        // fingerprint (see buildFindMany).
+        args = this.withDeclaredRelationNames(args);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {
@@ -2247,7 +2284,9 @@ export class QueryInterface {
             !whereObj.NOT &&
             whereKeys.every((k) => {
                 const v = whereObj[k];
-                return v !== null && !isWhereOperator(v) && !ownLookup(this.tableMeta.relations, k);
+                // Resolved, not looked up: a relation filter spelled the snake_case
+                // way must not read as a plain equality and take the simple path.
+                return v !== null && !isWhereOperator(v) && !resolveRelationDef(this.tableMeta.relations, k);
             });
         // Simple path: plain equality, no operators/null/OR.
         //
@@ -2343,6 +2382,15 @@ export class QueryInterface {
     // findMany
     // -------------------------------------------------------------------------
     async findMany(args) {
+        // BEFORE the strategy branch, not only inside the builders, so the
+        // join-vs-batched decision and its dev warning see the same declared name
+        // every other stage does. `planAuto` splits `with` on the caller's keys and
+        // `runAutoSplit` carries them onward; each downstream consumer normalizes
+        // too, so this is not load-bearing for correctness (measured: removing it
+        // changes the warning text from the declared name back to the caller's and
+        // nothing else). It is here so the invariant holds at the seam rather than
+        // depending on every consumer to re-establish it.
+        args = this.withDeclaredRelationNames(args);
         this.maybeWarnUnlimited(args);
         this.maybeWarnUnorderedPage(args);
         // Dev-only: warn on deeply nested with clauses
@@ -2493,8 +2541,12 @@ export class QueryInterface {
             const isScalarEquality = value !== null && (typeof value !== 'object' || value instanceof Date) && typeof value !== 'function';
             if (!isScalarEquality)
                 return false;
-            const column = ownLookup(this.tableMeta.columnMap, field);
-            if (!column)
+            // The one key-resolution rule: a bare `columnMap` read knows only the
+            // FIELD spelling, so `where: { user_id: 1 }` on a unique column did not
+            // count as pinning it and drew a spurious unlimited-read warning the
+            // camelCase spelling of the same query did not.
+            const column = resolveColumnName(this.tableMeta, field);
+            if (column === undefined)
                 return false;
             pinned.add(column);
         }
@@ -2521,6 +2573,11 @@ export class QueryInterface {
         this.currentSkip = resolveSkipGlobalFilters(args?.skipGlobalFilters);
         // Pinned before the flatten plan and the cache key, both of which read it.
         const jsonEncoding = this.resolveJsonEncoding(args?.jsonEncoding);
+        // Relation names to their declared spelling FIRST, before the stable-order
+        // pass and the fingerprint below and before any of the six `with` walkers,
+        // so none of them needs to know a relation has two accepted spellings and
+        // both spellings share one cache entry. See query/relation-names.ts.
+        args = this.withDeclaredRelationNames(args);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations BEFORE fingerprinting, so the two orderings get distinct cache
         // entries and every downstream path (SQL build, collect, parser) inherits it.
@@ -2632,7 +2689,13 @@ export class QueryInterface {
         // distinct key (correct, it emits a different ORDER BY).
         const orderFp = args?.orderBy
             ? orderByEntries(args.orderBy)
-                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, ownLookup(this.tableMeta.relations, k)?.to)}`)
+                // Keyed by the DECLARED relation name (falling back to the key
+                // itself for a column), so the two spellings of one orderBy share a
+                // cache entry instead of minting two templates for one query.
+                .map(([k, d]) => {
+                const rel = resolveRelation(this.tableMeta.relations, k);
+                return `${rel?.name ?? k}:${this.orderByEntryFingerprint(d, rel?.def.to)}`;
+            })
                 .join(',')
             : '';
         const cursorFp = args?.cursor
@@ -2754,12 +2817,27 @@ export class QueryInterface {
                     // Resolve the seek direction per cursor field from the flattened
                     // orderBy entries (last wins, matching object-key semantics), so both
                     // the object and array orderBy forms drive the cursor comparison.
-                    const orderDirByKey = new Map(orderByEntries(args.orderBy));
+                    //
+                    // Indexed by the RESOLVED COLUMN, never the caller's key: both
+                    // `cursor` and `orderBy` take either spelling, so a cursor written
+                    // `{ created_at }` against `orderBy: { createdAt: 'desc' }` missed
+                    // this lookup, defaulted to ascending, and emitted `created_at > $n`
+                    // under `ORDER BY created_at DESC` — the wrong page, silently. Same
+                    // failure the `{ sort, nulls }` normalization below prevents, reached
+                    // through the spelling instead of the value shape. A relation /
+                    // JSON-path / vector key resolves to no column and is skipped.
+                    const orderDirByColumn = new Map();
+                    for (const [ok, od] of orderByEntries(args.orderBy)) {
+                        const ocol = resolveColumnName(this.tableMeta, ok);
+                        if (ocol !== undefined)
+                            orderDirByColumn.set(ocol, od);
+                    }
                     const cursorConditions = cursorEntries.map(([k, v]) => {
-                        const col = this.toSqlColumn(k);
+                        const rawCol = this.toColumn(k);
+                        const col = this.q(rawCol);
                         // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
-                        const dir = orderDirByKey.get(k);
+                        const dir = orderDirByColumn.get(rawCol);
                         const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
                         const op = desc ? '<' : '>';
                         freshParams.push(v);
@@ -3090,6 +3168,15 @@ export class QueryInterface {
     // findFirst, like findMany but returns a single row or null
     // -------------------------------------------------------------------------
     async findFirst(args) {
+        // BEFORE the strategy branch, not only inside the builders, so the
+        // join-vs-batched decision and its dev warning see the same declared name
+        // every other stage does. `planAuto` splits `with` on the caller's keys and
+        // `runAutoSplit` carries them onward; each downstream consumer normalizes
+        // too, so this is not load-bearing for correctness (measured: removing it
+        // changes the warning text from the declared name back to the caller's and
+        // nothing else). It is here so the invariant holds at the seam rather than
+        // depending on every consumer to re-establish it.
+        args = this.withDeclaredRelationNames(args);
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             if (args?.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
@@ -3667,9 +3754,12 @@ export class QueryInterface {
             // pick.where / pick.orderBy paths). To-one relation orderBy carries the
             // target's global filter once per ordered column.
             if (this.isRelationOrderByValue(dir)) {
-                const relDef = ownLookup(this.tableMeta.relations, key);
+                // Mirrors the build path's resolution, so a cache HIT binds params for
+                // the same relation the cached SQL was built from.
+                const resolvedRel = resolveRelation(this.tableMeta.relations, key);
+                const relDef = resolvedRel?.def;
                 if (relDef && isRelationPickOrderBy(dir)) {
-                    this.collectRelationPickOrderParams(key, relDef, dir, params);
+                    this.collectRelationPickOrderParams(resolvedRel.name, relDef, dir, params);
                 }
                 else if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);

package/dist/query/compound-unique.js

@@ -40,7 +40,7 @@
  */
 import { ValidationError } from '../errors.js';
 import { isArrayFilter, isJsonFilter, isVectorFilter, isWhereOperator } from './filters.js';
-import { ownLookup } from './utils.js';
+import { ownLookup, resolveColumnName, resolveRelationDef } from './utils.js';
 const syntheticKeyCache = new WeakMap();
 /**
  * Build (once per table) the map from a synthetic selector name to the ordered
@@ -110,7 +110,9 @@ function isRealKey(meta, key) {
     return (ownLookup(meta.columnMap, key) !== undefined ||
         ownLookup(meta.reverseColumnMap, key) !== undefined ||
         meta.allColumns.includes(key) ||
-        ownLookup(meta.relations, key) !== undefined);
+        // Resolved, so a relation named the snake_case way still reads as a real
+        // key here and is not mistaken for a compound-unique selector.
+        resolveRelationDef(meta.relations, key) !== undefined);
 }
 /**
  * A candidate compound-unique selector value: a plain object that is not a
@@ -152,16 +154,38 @@ export function expandCompoundUniqueWhere(meta, where) {
             continue; // unknown key, falls through to the standard E003
         const selector = value;
         const provided = Object.keys(selector).filter((k) => selector[k] !== undefined);
-        const expected = new Set(fields);
-        const exact = provided.length === expected.size && provided.every((k) => expected.has(k));
+        // Matched by the COLUMN each member name resolves to, not by the literal
+        // key. The selector's own NAME is registered under both spellings (see
+        // `register` above), so `{ org_id_user_id: { org_id, user_id } }` found the
+        // selector and was then refused for its members. Insertion order is
+        // `fields` order, keeping the expansion (and the SQL) stable.
+        const expected = new Map();
+        for (const f of fields)
+            expected.set(resolveColumnName(meta, f) ?? f, f);
+        /** column → the key the caller actually wrote for it. */
+        const providedByColumn = new Map();
+        let ambiguous = false;
+        for (const k of provided) {
+            const column = resolveColumnName(meta, k);
+            // Unresolvable, or two spellings of one column: fall through to the
+            // same refusal an incomplete member set gets.
+            if (column === undefined || providedByColumn.has(column)) {
+                ambiguous = true;
+                break;
+            }
+            providedByColumn.set(column, k);
+        }
+        const exact = !ambiguous &&
+            providedByColumn.size === expected.size &&
+            [...providedByColumn.keys()].every((c) => expected.has(c));
         if (!exact) {
             throw new ValidationError(`[turbine] Compound unique selector "${key}" on table "${meta.name}" must supply exactly ` +
                 `{ ${fields.join(', ')} }, received { ${provided.join(', ') || '(none)'} }.`);
         }
         result ??= { ...where };
         delete result[key];
-        for (const field of fields) {
-            const v = selector[field];
+        for (const [column, field] of expected) {
+            const v = selector[providedByColumn.get(column)];
             if (Object.hasOwn(result, field)) {
                 // A member field is ALSO given directly in the outer where: wrap the
                 // expansion in AND so neither value is clobbered.

package/dist/query/relation-names.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Caller-supplied RELATION names, normalized to their declared spelling once,
+ * before anything reads them.
+ *
+ * ## The rule
+ *
+ * A relation has one declared name (`ripeningChecks`), while the DDL anyone
+ * reads has only the table name (`ripening_checks`). Writing back what the
+ * schema shows therefore failed: E005 in `with`, E003 in a relation filter,
+ * E005 in `orderBy`, on names the error text was already computing correctly
+ * ("Did you mean ...?"). This accepts the snake_case spelling wherever the
+ * declared name is accepted, by the same resolve-then-validate rule
+ * {@link resolveRelation} states, which is the relation-level twin of
+ * `resolveColumnName`. It is not a guess: `snakeToCamel(key)` is accepted ONLY
+ * when it names a real declared relation, so a typo is still a typo, and an
+ * exact declared name always wins first.
+ *
+ * ## Why this is ONE pass up front and not a fix at each lookup
+ *
+ * The `with` tree is walked by SIX independent functions, each of which decides
+ * for itself which keys name relations: `withFingerprint`, `collectWithParams`,
+ * `buildRelationShapes`, `planFlattenWith`, `buildSelectWithRelations` and the
+ * batched loader, plus the positional row parser. Teaching each of them that a
+ * key has two spellings would make seven places that must agree about it, and
+ * disagreement is not a clean failure: the fingerprint is the SQL-cache key, so
+ * a walker that resolved differently from the builder would serve one query's
+ * template to another, silently. That is the drift class this repo has paid for
+ * repeatedly (the where-clause walkers, the two projection resolvers).
+ *
+ * Normalizing before any walker runs makes all seven correct with no knowledge
+ * of the second spelling, and keeps ONE authority for the rule.
+ *
+ * ## Shape
+ *
+ * Returns the SAME object when nothing needed rewriting, which is every query
+ * that already spells its relations the declared way, so the common path
+ * allocates nothing and is reference-identical to its input.
+ *
+ * An UNRESOLVABLE key is left exactly as written, deliberately. Reporting it is
+ * the builder's job, and it already names the offending key and lists the
+ * available relations; rejecting it here would move that error away from its
+ * context and change which error type callers see.
+ */
+import type { SchemaMetadata } from '../schema.js';
+import type { WithClause } from './types.js';
+/**
+ * `withClause` with every relation key replaced by its declared spelling,
+ * recursively, including the relation names inside a `_count`.
+ *
+ * Returns the input by reference when no key changed.
+ */
+export declare function normalizeWithClause(schema: SchemaMetadata, table: string, withClause: WithClause | undefined, depth?: number): WithClause | undefined;

package/dist/query/relation-names.js

@@ -0,0 +1,117 @@
+/**
+ * Caller-supplied RELATION names, normalized to their declared spelling once,
+ * before anything reads them.
+ *
+ * ## The rule
+ *
+ * A relation has one declared name (`ripeningChecks`), while the DDL anyone
+ * reads has only the table name (`ripening_checks`). Writing back what the
+ * schema shows therefore failed: E005 in `with`, E003 in a relation filter,
+ * E005 in `orderBy`, on names the error text was already computing correctly
+ * ("Did you mean ...?"). This accepts the snake_case spelling wherever the
+ * declared name is accepted, by the same resolve-then-validate rule
+ * {@link resolveRelation} states, which is the relation-level twin of
+ * `resolveColumnName`. It is not a guess: `snakeToCamel(key)` is accepted ONLY
+ * when it names a real declared relation, so a typo is still a typo, and an
+ * exact declared name always wins first.
+ *
+ * ## Why this is ONE pass up front and not a fix at each lookup
+ *
+ * The `with` tree is walked by SIX independent functions, each of which decides
+ * for itself which keys name relations: `withFingerprint`, `collectWithParams`,
+ * `buildRelationShapes`, `planFlattenWith`, `buildSelectWithRelations` and the
+ * batched loader, plus the positional row parser. Teaching each of them that a
+ * key has two spellings would make seven places that must agree about it, and
+ * disagreement is not a clean failure: the fingerprint is the SQL-cache key, so
+ * a walker that resolved differently from the builder would serve one query's
+ * template to another, silently. That is the drift class this repo has paid for
+ * repeatedly (the where-clause walkers, the two projection resolvers).
+ *
+ * Normalizing before any walker runs makes all seven correct with no knowledge
+ * of the second spelling, and keeps ONE authority for the rule.
+ *
+ * ## Shape
+ *
+ * Returns the SAME object when nothing needed rewriting, which is every query
+ * that already spells its relations the declared way, so the common path
+ * allocates nothing and is reference-identical to its input.
+ *
+ * An UNRESOLVABLE key is left exactly as written, deliberately. Reporting it is
+ * the builder's job, and it already names the offending key and lists the
+ * available relations; rejecting it here would move that error away from its
+ * context and change which error type callers see.
+ */
+import { resolveRelation } from './utils.js';
+/** Depth cap mirroring the builder's own, so a cyclic `with` cannot spin here. */
+const MAX_DEPTH = 12;
+/**
+ * `withClause` with every relation key replaced by its declared spelling,
+ * recursively, including the relation names inside a `_count`.
+ *
+ * Returns the input by reference when no key changed.
+ */
+export function normalizeWithClause(schema, table, withClause, depth = 0) {
+    if (!withClause || typeof withClause !== 'object' || depth > MAX_DEPTH)
+        return withClause;
+    const meta = schema.tables[table];
+    if (!meta)
+        return withClause;
+    let changed = false;
+    const out = {};
+    for (const [key, spec] of Object.entries(withClause)) {
+        if (key === '_count') {
+            const nextCount = normalizeCount(meta, spec);
+            if (nextCount !== spec)
+                changed = true;
+            out[key] = nextCount;
+            continue;
+        }
+        const resolved = resolveRelation(meta.relations, key);
+        // Unknown key: keep it verbatim and let the builder raise E005 by name.
+        const name = resolved?.name ?? key;
+        if (name !== key)
+            changed = true;
+        const nextSpec = resolved ? normalizeSpec(schema, resolved.def.to, spec, depth) : spec;
+        if (nextSpec !== spec)
+            changed = true;
+        out[name] = nextSpec;
+    }
+    return changed ? out : withClause;
+}
+/** A relation's `with` options, normalizing its nested `with` against the TARGET table. */
+function normalizeSpec(schema, target, spec, depth) {
+    if (spec === true || spec === false || spec === null || typeof spec !== 'object')
+        return spec;
+    const opts = spec;
+    if (!opts.with)
+        return spec;
+    const nested = normalizeWithClause(schema, target, opts.with, depth + 1);
+    return nested === opts.with ? spec : { ...opts, with: nested };
+}
+/**
+ * `_count` names relations too. `true` means every relation and has nothing to
+ * rename; the record form has one key per counted relation.
+ */
+function normalizeCount(meta, count) {
+    if (!count || typeof count !== 'object')
+        return count;
+    let changed = false;
+    const out = {};
+    for (const [key, value] of Object.entries(count)) {
+        const name = resolveRelation(meta.relations, key)?.name ?? key;
+        if (name !== key)
+            changed = true;
+        out[name] = value;
+    }
+    return changed ? out : count;
+}
+/*
+ * NOTE for the next person: there are deliberately no `declaredRelationName` /
+ * `namesRelation` wrappers here. The argument positions where a relation key
+ * sits INTERLEAVED with column keys (`where`'s some/every/none, `orderBy`'s
+ * relation targets, the simple-where fast path) cannot be normalized up front
+ * the way `with` can, so they call `resolveRelation` / `resolveRelationDef`
+ * from query/utils.ts directly at their branch point. Each of those branches is
+ * already a documented single authority; wrapping them here would add a second
+ * name for the same rule without removing a caller.
+ */

package/dist/query/relations.d.ts

@@ -117,12 +117,17 @@ export declare function isRelationOrderByValue(_qi: BuilderCtx, value: unknown):
  */
 export declare function nullsSuffix(qi: BuilderCtx, nulls: 'first' | 'last' | undefined): string;
 /**
- * Resolve an orderBy key to its snake_case column via the table's columnMap
- * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
- * where path uses. Shared by top-level JSON-path ordering and every nested
- * relation orderBy path so nested orderBy accepts exactly what top-level
- * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
- * camelCase-named DB columns like "sortOrder").
+ * Resolve an orderBy key to its snake_case column via {@link resolveColumnName},
+ * throwing the SAME unknown-field E003 the top-level where path uses. Shared by
+ * top-level JSON-path ordering and every nested relation orderBy path so nested
+ * orderBy accepts exactly what top-level accepts (the 0.30.x bug: nested orderBy
+ * skipped the columnMap and rejected camelCase-named DB columns like
+ * "sortOrder").
+ *
+ * The rule is REACHED here, never restated: this used to inline
+ * `columnMap ?? camelToSnake` + an `allColumns` check, which agreed with
+ * `resolveColumnName` while the top-level scalar path a few lines up disagreed
+ * with both.
  */
 export declare function resolveOrderByColumn(_qi: BuilderCtx, table: string, meta: TableMetadata, key: string): string;
 /**