turbine-orm 0.71.0 → 0.72.0

package/dist/cjs/query/aggregates.js

@@ -89,12 +89,14 @@ function assertAggregatePiiOptIn(table, meta, field, column, usage, includePii)
 }
 function buildGroupBy(qi, args) {
     const meta = qi.schema.tables[qi.table];
-    if (meta) {
-        for (const key of args.by) {
-            if (typeof key === 'string' && !(key in meta.columnMap)) {
-                throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
-            }
-        }
+    // Up-front, so a bad `by` key is reported before anything else in the call,
+    // and through `qi.toColumn` (the ONE `resolveColumnName` rule) rather than
+    // `key in meta.columnMap`, which knows only the FIELD spelling and so
+    // rejected the snake_case COLUMN name that `where` / `select` / `distinct`
+    // accept and that an introspected schema's DDL declares.
+    for (const key of args.by) {
+        if (typeof key === 'string')
+            qi.toColumn(key);
     }
     qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // Resolve the PII opt-in ONCE, here, so the sentinel check runs on every
@@ -150,18 +152,30 @@ function buildGroupBy(qi, args) {
     for (const entry of args.by) {
         if (typeof entry === 'string') {
             const col = qi.toColumn(entry);
+            // The group key's identity is the COLUMN, so everything keyed off it
+            // uses the canonical FIELD name rather than whichever spelling the caller
+            // wrote. The result key above all: rows are read through `parseRow`,
+            // whose keys are field names, so `by: ['created_at']` keyed by the
+            // caller's spelling read `parsed['created_at']` and returned `undefined`
+            // for every group. `_count` / `_sum` / `_min` in the same transform
+            // already map their alias back through `reverseColumnMap`.
+            const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
             assertAggregatePiiOptIn(qi.table, meta, entry, col, 'groupBy `by` key', includePii);
-            claimResultKey(entry, `column "${col}"`);
+            claimResultKey(field, `column "${col}"`);
             // The emitted output column is the snake_case name; claim it too (when
             // it differs from the result key) so a JSON alias like 'created_at'
             // cannot silently shadow the 'createdAt' group key on the wire.
-            if (col !== entry)
+            if (col !== field)
                 claimResultKey(col, `column "${col}"`);
             groupExprs.push(qi.q(col));
             selectExprs.push(qi.q(col));
-            byReaders.push({ resultKey: entry, rowKey: col, raw: false });
-            byOrderExprs.set(entry, qi.q(col));
-            havingGroupKeys.set(entry, { kind: 'column', field: entry });
+            byReaders.push({ resultKey: field, rowKey: col, raw: false });
+            // Registered ONCE, under the canonical field: `orderBy` and `having`
+            // may spell the same group key the other way, and {@link lookupGroupKey}
+            // reconciles that at lookup time rather than doubling every
+            // "orderable keys" list.
+            byOrderExprs.set(field, qi.q(col));
+            havingGroupKeys.set(field, { kind: 'column', field });
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
@@ -242,7 +256,9 @@ function buildGroupBy(qi, args) {
                 const inner = `${sqlFn}(${qi.q(col)})`;
                 const expr = aggKey === '_avg' ? qi.castAgg(inner, 'float') : inner;
                 selectExprs.push(`${expr} AS ${qi.q(`${aggKey}_${col}`)}`);
-                aggOrderExprs.set(`${aggKey}:${key}`, expr);
+                // Canonical field, matching the result bucket the transform fills;
+                // `orderBy` may spell it either way (see {@link lookupGroupKey}).
+                aggOrderExprs.set(`${aggKey}:${qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col)}`, expr);
                 continue;
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
@@ -397,6 +413,37 @@ function buildGroupBy(qi, args) {
  * no `$n` renumbering). An aggregate key that was not requested, or an unknown
  * by-key, throws {@link ValidationError} E003 listing the valid keys.
  */
+/**
+ * Read a caller-supplied groupBy result key out of a registry keyed by the
+ * CANONICAL name (the field for a `by` column / aggregate target, the alias
+ * for a JSON group key).
+ *
+ * `by`, `orderBy` and `having` are three arguments of one call, each free to
+ * spell a column either way, so `by`'s choice must not decide what the other
+ * two may name. Reconciled here rather than by registering both spellings,
+ * which would list every group key twice in the "orderable keys" text: try the
+ * key as written (which is what carries a JSON alias, not a column), then its
+ * canonical field.
+ */
+function lookupGroupKey(qi, registry, key) {
+    const direct = registry.get(key);
+    if (direct !== undefined)
+        return direct;
+    const canonical = canonicalFieldName(qi, key);
+    return canonical === undefined ? undefined : registry.get(canonical);
+}
+/**
+ * The canonical FIELD name for a caller-supplied column name, or `undefined`
+ * when it names no column (a JSON group-key alias, a typo). One hop through
+ * {@link resolveColumnName} and back via `reverseColumnMap`, so both spellings
+ * land on one string.
+ */
+function canonicalFieldName(qi, key) {
+    const column = (0, utils_js_1.resolveColumnName)(qi.tableMeta, key);
+    if (column === undefined)
+        return undefined;
+    return qi.tableMeta.reverseColumnMap[column] ?? (0, schema_js_1.snakeToCamel)(column);
+}
 function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
     const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
     /** Human-readable list of every key this call can order by (for E003). */
@@ -459,7 +506,11 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
             for (const [field, dirSpec] of Object.entries(value)) {
                 if (dirSpec === undefined)
                     continue;
-                const expr = aggOrderExprs.get(`${key}:${field}`);
+                // `field` is the caller's spelling of the aggregate's target column;
+                // the registry is keyed by the canonical one.
+                const canonical = canonicalFieldName(qi, field);
+                const expr = aggOrderExprs.get(`${key}:${field}`) ??
+                    (canonical === undefined ? undefined : aggOrderExprs.get(`${key}:${canonical}`));
                 if (!expr) {
                     throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${qi.table}": ` +
                         `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
@@ -470,7 +521,7 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
             continue;
         }
         // Plain by-field name or JSON group-key alias.
-        const expr = byOrderExprs.get(key);
+        const expr = lookupGroupKey(qi, byOrderExprs, key);
         if (!expr) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${qi.table}". ` +
                 `Orderable keys: ${validKeys()}.`);
@@ -734,7 +785,7 @@ function buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys,
  * its re-emitted extract expression.
  */
 function buildHavingScalarClauses(qi, field, value, params, groupKeys) {
-    const ref = groupKeys?.get(field);
+    const ref = groupKeys ? lookupGroupKey(qi, groupKeys, field) : undefined;
     if (!ref) {
         const known = groupKeys ? [...groupKeys.keys()] : [];
         throw new errors_js_1.ValidationError(`[turbine] having on "${field}" (table "${qi.table}") filters the grouped value itself, but ` +
@@ -885,25 +936,22 @@ function buildAggregate(qi, args) {
         ? whereMod.buildWhere(qi, aggWhere)
         : { sql: '', params: [] };
     const meta = qi.schema.tables[qi.table];
-    if (meta) {
-        for (const group of [args._sum, args._avg, args._min, args._max]) {
-            if (group && typeof group === 'object') {
-                for (const key of Object.keys(group)) {
-                    if (!(key in meta.columnMap)) {
-                        throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
-                    }
-                }
-            }
+    // Every target is validated up front, including one whose falsy value the
+    // builders below skip, and through `qi.toColumn` (the ONE
+    // `resolveColumnName` rule). `key in meta.columnMap` knows only the FIELD
+    // spelling, so the snake_case COLUMN name that `where` / `select` and even
+    // `groupBy`'s own `_min` accepted was rejected here.
+    for (const group of [args._sum, args._avg, args._min, args._max]) {
+        if (group && typeof group === 'object') {
+            for (const key of Object.keys(group))
+                qi.toColumn(key);
         }
-        if (args._count && typeof args._count === 'object') {
-            for (const key of Object.keys(args._count)) {
-                // `_all` is the reserved COUNT(*) selector, not a column.
-                if (key === '_all')
-                    continue;
-                if (!(key in meta.columnMap)) {
-                    throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
-                }
-            }
+    }
+    if (args._count && typeof args._count === 'object') {
+        for (const key of Object.keys(args._count)) {
+            // `_all` is the reserved COUNT(*) selector, not a column.
+            if (key !== '_all')
+                qi.toColumn(key);
         }
     }
     const selectExprs = [];

package/dist/cjs/query/batched-loader.d.ts

@@ -58,6 +58,7 @@ import type { PgCompatQueryResult } from '../pg-types.js';
 import { type RelationDef, type SchemaMetadata, type TableMetadata } from '../schema.js';
 import type { ReselectExecutor } from './builder.js';
 import type { SkipGlobalFilters, Unsafe, WithClause, WithCount } from './types.js';
+import { type ColumnNameSource } from './utils.js';
 /**
  * A DeferredQuery, minimally typed for what the loader consumes. Kept local to
  * avoid a value import of builder.ts (which imports this module).
@@ -166,7 +167,18 @@ export declare function defaultProjectionFields(meta: TableMetadata, includePii:
  * resolver so the two strategies refuse identically, word for word.
  */
 export declare function assertProjectionShape(table: string, select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined): void;
-export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
+export declare 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: ColumnNameSource, select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
 /**
  * The default projection for this table when it is NOT `select`/`omit`-driven:
  * `hidden` are fields the default projection leaves out (today: PII-tagged

package/dist/cjs/query/batched-loader.js

@@ -163,8 +163,12 @@ function partitionOrderBy(meta, orderBy) {
         return null;
     const out = [];
     for (const [key, value] of entries) {
-        const column = (0, utils_js_1.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 = (0, utils_js_1.resolveColumnName)(meta, key);
+        if (column === undefined)
             return null;
         let sort;
         let nulls;
@@ -275,7 +279,18 @@ function assertProjectionShape(table, select, omit) {
         throw new errors_js_1.ValidationError((0, utils_js_1.selectOmitExclusiveMessage)(table));
     }
 }
-function includeKeysForBatching(select, omit, fields, 
+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
@@ -289,23 +304,43 @@ 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 = (0, utils_js_1.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) => (0, utils_js_1.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);
             }
         }
@@ -633,7 +668,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),
@@ -836,7 +871,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/cjs/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/cjs/query/builder.js

@@ -57,6 +57,7 @@ const aggMod = __importStar(require("./aggregates.js"));
 const batched_loader_js_1 = require("./batched-loader.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
+const relation_names_js_1 = require("./relation-names.js");
 const relationsMod = __importStar(require("./relations.js"));
 const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
@@ -1102,6 +1103,24 @@ 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 = (0, relation_names_js_1.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
@@ -1122,7 +1141,7 @@ 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 = (0, utils_js_1.ownLookup)(meta.relations, relName);
+            const rel = (0, utils_js_1.resolveRelationDef)(meta.relations, relName);
             if (!rel)
                 continue; // unknown relation, let the build path surface E005
             const options = spec === true ? {} : spec;
@@ -1509,7 +1528,7 @@ class QueryInterface {
                 }
                 continue;
             }
-            const rel = (0, utils_js_1.ownLookup)(this.tableMeta.relations, key);
+            const rel = (0, utils_js_1.resolveRelationDef)(this.tableMeta.relations, key);
             if (!rel) {
                 joinWith[key] = spec; // unknown relation, let the join path surface E005
                 continue;
@@ -1619,7 +1638,7 @@ class QueryInterface {
         const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, batchedWith);
         (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, includePii));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(this.tableMeta, args.select, args.omit, needed, (0, batched_loader_js_1.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.
@@ -1757,6 +1776,10 @@ 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.
@@ -1791,7 +1814,7 @@ class QueryInterface {
     prepareBatchedBase(args, withClause) {
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
         (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii')));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(this.tableMeta, args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
             with: undefined,
@@ -2163,6 +2186,15 @@ 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);
@@ -2190,6 +2222,8 @@ 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)
@@ -2198,7 +2232,7 @@ class QueryInterface {
         (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
         (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii')));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(this.tableMeta, args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.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));
@@ -2243,6 +2277,9 @@ 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)) {
@@ -2285,7 +2322,9 @@ class QueryInterface {
             !whereObj.NOT &&
             whereKeys.every((k) => {
                 const v = whereObj[k];
-                return v !== null && !(0, filters_js_1.isWhereOperator)(v) && !(0, utils_js_1.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 && !(0, filters_js_1.isWhereOperator)(v) && !(0, utils_js_1.resolveRelationDef)(this.tableMeta.relations, k);
             });
         // Simple path: plain equality, no operators/null/OR.
         //
@@ -2381,6 +2420,15 @@ 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
@@ -2531,8 +2579,12 @@ class QueryInterface {
             const isScalarEquality = value !== null && (typeof value !== 'object' || value instanceof Date) && typeof value !== 'function';
             if (!isScalarEquality)
                 return false;
-            const column = (0, utils_js_1.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 = (0, utils_js_1.resolveColumnName)(this.tableMeta, field);
+            if (column === undefined)
                 return false;
             pinned.add(column);
         }
@@ -2559,6 +2611,11 @@ class QueryInterface {
         this.currentSkip = (0, types_js_1.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.
@@ -2670,7 +2727,13 @@ class QueryInterface {
         // distinct key (correct, it emits a different ORDER BY).
         const orderFp = args?.orderBy
             ? (0, filters_js_1.orderByEntries)(args.orderBy)
-                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, (0, utils_js_1.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 = (0, utils_js_1.resolveRelation)(this.tableMeta.relations, k);
+                return `${rel?.name ?? k}:${this.orderByEntryFingerprint(d, rel?.def.to)}`;
+            })
                 .join(',')
             : '';
         const cursorFp = args?.cursor
@@ -2792,12 +2855,27 @@ 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((0, filters_js_1.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 (0, filters_js_1.orderByEntries)(args.orderBy)) {
+                        const ocol = (0, utils_js_1.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 = (0, filters_js_1.isOrderBySpec)(dir) ? dir.sort === 'desc' : dir === 'desc';
                         const op = desc ? '<' : '>';
                         freshParams.push(v);
@@ -3128,6 +3206,15 @@ 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);
@@ -3705,9 +3792,12 @@ 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 = (0, utils_js_1.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 = (0, utils_js_1.resolveRelation)(this.tableMeta.relations, key);
+                const relDef = resolvedRel?.def;
                 if (relDef && (0, filters_js_1.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/cjs/query/compound-unique.js

@@ -113,7 +113,9 @@ function isRealKey(meta, key) {
     return ((0, utils_js_1.ownLookup)(meta.columnMap, key) !== undefined ||
         (0, utils_js_1.ownLookup)(meta.reverseColumnMap, key) !== undefined ||
         meta.allColumns.includes(key) ||
-        (0, utils_js_1.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.
+        (0, utils_js_1.resolveRelationDef)(meta.relations, key) !== undefined);
 }
 /**
  * A candidate compound-unique selector value: a plain object that is not a
@@ -155,16 +157,38 @@ 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((0, utils_js_1.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 = (0, utils_js_1.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 errors_js_1.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.