turbine-orm 0.71.0 → 0.72.0

package/dist/connection-url.d.ts

@@ -158,3 +158,33 @@ export interface ConnectionOptionsConfig {
  * a value that can carry a space can carry a second `-c`.
  */
 export declare function withStatementTimeoutOption(config: ConnectionOptionsConfig, statementTimeoutMs: number): ConnectionOptionsConfig;
+/**
+ * `connectionString` with `setting` appended to an existing `options` query
+ * parameter, or `null` when it carries none (in which case the caller uses the
+ * `options` config field, which the connection string does not override).
+ *
+ * Only the query string is rewritten, never the userinfo or host, so a
+ * percent-encoded password cannot be mangled by a round trip through `URL`. The
+ * split is on the first `?`, which is also where pg's own parser puts the
+ * query-string boundary: a connection string with an unencoded `?` inside the
+ * password is not parseable by pg either, so there is no shape this handles
+ * differently from the driver.
+ *
+ * Shared with `client.ts`, which needs the identical merge for
+ * `plan_cache_mode`. It was duplicated there until 2026-08-16, and the reason
+ * is worth keeping because it was wrong in an instructive way: importing it
+ * from `client.ts` adds an import edge from a module ~100 test processes load,
+ * and this file's merged coverage read 40% while measuring 100% in isolation,
+ * which moved the aggregate gate 75.48% -> 75.03% against a 75% floor. The
+ * conclusion drawn was that the refactor cost the gate's headroom.
+ *
+ * The 40% was a c8 merge defect, not an import cost: c8's V8-level merge is not
+ * monotonic, and once the report merges at the istanbul level instead this file
+ * reads 100% with the edge in place (see `//merge-bug` in .c8rc.json). So the
+ * duplication was paying for an artifact, and the two copies are now one.
+ *
+ * Keep this module import-free regardless. That part was never about coverage:
+ * `query/` and `cli/` both reach it, and an edge back to `client.ts` would be
+ * the cycle `scripts/check-import-cycles.mjs` exists to refuse.
+ */
+export declare function mergeConnectionStringOptions(connectionString: string, setting: string): string | null;

package/dist/connection-url.js

@@ -256,27 +256,24 @@ export function withStatementTimeoutOption(config, statementTimeoutMs) {
  * password is not parseable by pg either, so there is no shape this handles
  * differently from the driver.
  *
- * DELIBERATELY DUPLICATED with `TurbineClient.mergeConnectionStringOptions`,
- * which needs the identical merge for `plan_cache_mode`. Collapsing the two
- * onto this copy is the obviously correct refactor and it was tried; it is
- * reverted, and the reason is worth writing down because the next person will
- * try it too.
+ * Shared with `client.ts`, which needs the identical merge for
+ * `plan_cache_mode`. It was duplicated there until 2026-08-16, and the reason
+ * is worth keeping because it was wrong in an instructive way: importing it
+ * from `client.ts` adds an import edge from a module ~100 test processes load,
+ * and this file's merged coverage read 40% while measuring 100% in isolation,
+ * which moved the aggregate gate 75.48% -> 75.03% against a 75% floor. The
+ * conclusion drawn was that the refactor cost the gate's headroom.
  *
- * Exporting it and importing it from `client.ts` adds an import edge from a
- * module that ~100 test processes load. In each of those processes this file's
- * top level runs and its functions do not, so c8 merges ~100 top-level-only
- * entries against the one full entry from `pooler-guard.test.ts`, and the file
- * reports 40% in the merged report while measuring 100% in isolation. Real
- * coverage is unchanged either way, but the aggregate gate moved 75.48% ->
- * 75.03% against a 75% floor, i.e. the refactor spent almost all the headroom
- * on a reporting artifact.
+ * The 40% was a c8 merge defect, not an import cost: c8's V8-level merge is not
+ * monotonic, and once the report merges at the istanbul level instead this file
+ * reads 100% with the edge in place (see `//merge-bug` in .c8rc.json). So the
+ * duplication was paying for an artifact, and the two copies are now one.
  *
- * So: two copies, both small, both pure, neither reachable from the other. If
- * you unify them, re-measure `npm run test:coverage` as a whole and not just
- * this file, and raise the floor's headroom first. Keep this module
- * import-free regardless.
+ * Keep this module import-free regardless. That part was never about coverage:
+ * `query/` and `cli/` both reach it, and an edge back to `client.ts` would be
+ * the cycle `scripts/check-import-cycles.mjs` exists to refuse.
  */
-function mergeConnectionStringOptions(connectionString, setting) {
+export function mergeConnectionStringOptions(connectionString, setting) {
     const q = connectionString.indexOf('?');
     if (q === -1)
         return null;

package/dist/powql.d.ts

@@ -67,8 +67,34 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private readonly onQuery?;
     private warnedUnlimited;
     constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
-    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    /**
+     * Resolve a camelCase field name (or raw snake) to its column metadata.
+     *
+     * THE single key→column decision on this engine: every PowQL surface
+     * reaches a column through here, which is why PowDB never grew the
+     * per-argument asymmetry the SQL builders did. It resolves through the
+     * shared {@link resolveColumnName} so both engines answer alike; the direct
+     * name/field match stays as a fallback, since a PowDB schema may carry names
+     * outside the snake_case↔camelCase round trip and narrowing that would be a
+     * silent break rather than a fix.
+     */
     private column;
+    /**
+     * {@link lookupGroupKey} for the `${aggKey}:${field}` composite the aggregate
+     * ordering registry is keyed by: only the FIELD half needs canonicalizing.
+     */
+    private aggOrderExpr;
+    /**
+     * Read a caller-supplied groupBy result key out of a registry keyed by the
+     * canonical FIELD name.
+     *
+     * `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 others
+     * may name. Try the key as written (which is what carries a JSON group-key
+     * ALIAS, not a column), then its canonical field. Mirrors `lookupGroupKey` in
+     * query/aggregates.ts.
+     */
+    private lookupGroupKey;
     /**
      * PowQL column reference for a field: a dotted field reference
      * (`.snake_name`), or `alias.snake_name` when an `alias` is supplied (the F2
@@ -149,6 +175,17 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * which is precisely the "reports a guarantee that was never made" failure the
      * option's refusal exists to prevent.
      */
+    /**
+     * `args` with every `with` relation key replaced by the relation's DECLARED
+     * spelling, so PowDB accepts a snake_case relation name exactly as the SQL
+     * engines do. Returns `args` by reference when nothing needed rewriting.
+     *
+     * PowqlInterface is a parallel implementation rather than a subclass, so
+     * nothing makes this happen here automatically: a rule adopted only on the
+     * SQL side becomes an engine that disagrees about which queries are valid,
+     * which is the divergence class the projection resolver already cost.
+     */
+    private withDeclaredRelationNames;
     private assertNoForceCustomPlan;
     private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */

package/dist/powql.js

@@ -41,11 +41,12 @@ import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isPowdbDatetim
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
+import { normalizeWithClause } from './query/relation-names.js';
 // The privilege sentinel and its resolver: `includePii` / `allowFullTableScan`
 // are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
 // engines, so a spread request body cannot turn either on here either.
 import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
-import { escapeLike, ownLookup, relationInProjectionMessage, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
+import { escapeLike, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -195,9 +196,20 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // Column / value helpers
     // -------------------------------------------------------------------------
-    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    /**
+     * Resolve a camelCase field name (or raw snake) to its column metadata.
+     *
+     * THE single key→column decision on this engine: every PowQL surface
+     * reaches a column through here, which is why PowDB never grew the
+     * per-argument asymmetry the SQL builders did. It resolves through the
+     * shared {@link resolveColumnName} so both engines answer alike; the direct
+     * name/field match stays as a fallback, since a PowDB schema may carry names
+     * outside the snake_case↔camelCase round trip and narrowing that would be a
+     * silent break rather than a fix.
+     */
     column(field) {
-        const snake = this.meta.columnMap[field] ?? field;
+        const resolved = resolveColumnName(this.meta, field);
+        const snake = resolved ?? ownLookup(this.meta.columnMap, field) ?? field;
         const col = this.meta.columns.find((c) => c.name === snake || c.field === field);
         if (!col) {
             throw new ValidationError(`[turbine] Unknown column "${field}" on table "${this.table}". Known: ${this.meta.columns
@@ -206,6 +218,41 @@ export class PowqlInterface {
         }
         return col;
     }
+    /**
+     * {@link lookupGroupKey} for the `${aggKey}:${field}` composite the aggregate
+     * ordering registry is keyed by: only the FIELD half needs canonicalizing.
+     */
+    aggOrderExpr(registry, aggKey, field) {
+        try {
+            return registry.get(`${aggKey}:${this.column(field).field}`);
+        }
+        catch {
+            return undefined; // not a column: the caller's own E003 is the right error
+        }
+    }
+    /**
+     * Read a caller-supplied groupBy result key out of a registry keyed by the
+     * canonical FIELD name.
+     *
+     * `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 others
+     * may name. Try the key as written (which is what carries a JSON group-key
+     * ALIAS, not a column), then its canonical field. Mirrors `lookupGroupKey` in
+     * query/aggregates.ts.
+     */
+    lookupGroupKey(registry, key) {
+        const direct = registry.get(key);
+        if (direct !== undefined)
+            return direct;
+        let field;
+        try {
+            field = this.column(key).field;
+        }
+        catch {
+            return undefined; // not a column: the caller's own E003 below is the right error
+        }
+        return registry.get(field);
+    }
     /**
      * PowQL column reference for a field: a dotted field reference
      * (`.snake_name`), or `alias.snake_name` when an `alias` is supplied (the F2
@@ -320,6 +367,22 @@ export class PowqlInterface {
      * which is precisely the "reports a guarantee that was never made" failure the
      * option's refusal exists to prevent.
      */
+    /**
+     * `args` with every `with` relation key replaced by the relation's DECLARED
+     * spelling, so PowDB accepts a snake_case relation name exactly as the SQL
+     * engines do. Returns `args` by reference when nothing needed rewriting.
+     *
+     * PowqlInterface is a parallel implementation rather than a subclass, so
+     * nothing makes this happen here automatically: a rule adopted only on the
+     * SQL side becomes an engine that disagrees about which queries are valid,
+     * which is the divergence class the projection resolver already cost.
+     */
+    withDeclaredRelationNames(args) {
+        if (!args?.with)
+            return args;
+        const normalized = normalizeWithClause(this.schema, this.table, args.with);
+        return normalized === args.with ? args : { ...args, with: normalized };
+    }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
             return;
@@ -760,8 +823,8 @@ export class PowqlInterface {
             else if (key === 'NOT') {
                 scalar[key] = await this.resolveRelationFilters(value, timeout);
             }
-            else if (this.meta.relations[key]) {
-                relConds.push(await this.resolveRelationCondition(this.meta.relations[key], value, timeout));
+            else if (resolveRelationDef(this.meta.relations, key)) {
+                relConds.push(await this.resolveRelationCondition(resolveRelationDef(this.meta.relations, key), value, timeout));
             }
             else {
                 scalar[key] = value;
@@ -896,7 +959,7 @@ export class PowqlInterface {
      * for a misspelling that is not there. Same message as the SQL engines.
      */
     projectionColumn(field, clause) {
-        if (ownLookup(this.meta.relations, field)) {
+        if (resolveRelationDef(this.meta.relations, field)) {
             throw new ValidationError(relationInProjectionMessage(this.table, field, clause));
         }
         return this.column(field).name;
@@ -1264,6 +1327,7 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         this.assertNoForceCustomPlan(args);
+        args = this.withDeclaredRelationNames(args);
         return this.withMiddleware('findMany', args, async () => {
             // `limit: 0` means "no rows" (SQL `LIMIT 0`), and answering it client-side
             // is correct on every engine version: PowDB's projection fast path returned
@@ -1345,6 +1409,12 @@ export class PowqlInterface {
         const nest = nestedPlans.length > 0 || linkPlans.length > 0;
         const alias = nest ? 't0' : undefined;
         const where = this.buildWhere(resolvedWhere, params, alias);
+        // PowQL's `distinct` is row-wide, so these names never reach the emitted
+        // statement. They are still caller-supplied names, and a name resolves or
+        // throws: reading the array for its LENGTH alone let `distinct: ['nope']`
+        // succeed here while every SQL engine refuses it. Validation only.
+        for (const key of args.distinct ?? [])
+            this.column(key);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
         const order = this.buildOrder(args.orderBy, params, alias);
@@ -1409,6 +1479,7 @@ export class PowqlInterface {
     }
     async findUnique(args) {
         this.assertNoForceCustomPlan(args);
+        args = this.withDeclaredRelationNames(args);
         // Prisma compound-unique selector → column conjunction (engine parity with
         // the SQL findUnique family; pure metadata, so this is a one-line adoption).
         if (args.where) {
@@ -1433,6 +1504,7 @@ export class PowqlInterface {
         });
     }
     async findFirst(args = {}) {
+        args = this.withDeclaredRelationNames(args);
         this.assertNoForceCustomPlan(args);
         return this.withMiddleware('findFirst', args, async () => {
             const { rows, native, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
@@ -2364,7 +2436,7 @@ export class PowqlInterface {
         for (const [field, value] of Object.entries(data)) {
             if (value === undefined)
                 continue;
-            if (this.meta.relations[field]) {
+            if (resolveRelationDef(this.meta.relations, field)) {
                 throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not createMany()/upsert()`);
             }
             out.push({ col: this.column(field), value });
@@ -2382,7 +2454,11 @@ export class PowqlInterface {
         for (const pk of this.meta.primaryKey) {
             const field = this.meta.reverseColumnMap[pk] ?? pk;
             const col = this.meta.columns.find((c) => c.name === pk);
+            // "Supplied" means under EITHER spelling: `create` resolves both, so
+            // testing the camelCase field alone made `{ user_id: 'x' }` look absent,
+            // generated a UUID under `userId`, and wrote the column twice.
             if (out[field] == null &&
+                (field === pk || out[pk] == null) &&
                 col?.hasDefault &&
                 !col.isGenerated &&
                 col.tsType.replace(/\s*\|\s*null$/, '').trim() === 'string') {
@@ -2521,7 +2597,7 @@ export class PowqlInterface {
         for (const [field, value] of Object.entries(data)) {
             if (value === undefined)
                 continue;
-            if (this.meta.relations[field]) {
+            if (resolveRelationDef(this.meta.relations, field)) {
                 throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not updateMany()/upsert()`);
             }
             const colMeta = this.column(field);
@@ -2684,7 +2760,10 @@ export class PowqlInterface {
             // reselect-by-PK fetch; create/update/delete all use `returning`.
             await this.exec(`upsert ${this.qt} on ${this.colRefName(pkCol)} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout, 'upsert');
             const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
-            const row = await this.reselectByPk(createData[pkField], args.timeout);
+            // Either spelling, as `upsertComposite` already does below: reading the
+            // camelCase field alone reselected `undefined` for a snake-spelled PK and
+            // reported a write that had SUCCEEDED as a NotFoundError.
+            const row = await this.reselectByPk(createData[pkField] ?? createData[pkCol], args.timeout);
             if (!row)
                 throw new NotFoundError({ table: this.table, where: createData });
             return row;
@@ -2852,13 +2931,18 @@ export class PowqlInterface {
                 if (typeof entry === 'string') {
                     const col = this.column(entry);
                     assertAggregatePiiOptIn(this.table, this.meta, entry, col.name, 'groupBy `by` key', resolveUnsafeFlag(args.includePii, 'includePii'));
-                    claim(entry, `column "${col.name}"`);
-                    if (col.name !== entry)
+                    // Keyed by the canonical FIELD, never by whichever of the column's
+                    // two legal spellings the caller wrote (`column` accepts both), so
+                    // neither the result shape nor the keys `orderBy` accepts depends on
+                    // that choice; `lookupGroupKey` reconciles the other spelling. Same
+                    // rule and same result shape as the SQL groupBy (query/aggregates.ts).
+                    claim(col.field, `column "${col.name}"`);
+                    if (col.name !== col.field)
                         claim(col.name, `column "${col.name}"`);
                     groupExprs.push(this.colRefName(col.name));
                     proj.push(this.colRefName(col.name));
-                    byOrderExprs.set(entry, this.colRefName(col.name));
-                    byReaders.push({ kind: 'plain', resultKey: entry, rowKey: col.name, col });
+                    byOrderExprs.set(col.field, this.colRefName(col.name));
+                    byReaders.push({ kind: 'plain', resultKey: col.field, rowKey: col.name, col });
                 }
                 else {
                     const col = this.column(entry.field);
@@ -2921,9 +3005,11 @@ export class PowqlInterface {
                         claim(`${fn}_${col.name}`, `${fn} of column "${col.name}"`);
                         const inner = this.colRefName(col.name);
                         proj.push(`${alias}: ${powfn}(${inner})`);
-                        aggReaders.push({ alias, outKey: `${fn}:${key}`, numeric: true });
-                        aggOrderExprs.set(`${fn}:${key}`, `.${alias}`);
-                        aggInner.set(key, inner);
+                        // Canonical field, so the result bucket and the keys `orderBy` /
+                        // `having` accept are the same whichever spelling was requested.
+                        aggReaders.push({ alias, outKey: `${fn}:${col.field}`, numeric: true });
+                        aggOrderExprs.set(`${fn}:${col.field}`, `.${alias}`);
+                        aggInner.set(col.field, inner);
                     }
                     else {
                         const col = this.column(target.field);
@@ -3059,7 +3145,7 @@ export class PowqlInterface {
                         throw new ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${this.table}". ` +
                             `Supported: ${[...POWQL_HAVING_AGG_FNS.keys()].join(', ')}.`);
                     }
-                    const inner = aggInner.get(key) ?? this.ref(key);
+                    const inner = this.lookupGroupKey(aggInner, key) ?? this.ref(key);
                     conds.push(cmp(`${fn}(${inner})`, filter));
                 }
             }
@@ -3107,7 +3193,9 @@ export class PowqlInterface {
                 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 expr = aggOrderExprs.get(`${key}:${field}`) ?? this.aggOrderExpr(aggOrderExprs, key, field);
                     if (!expr) {
                         throw new ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
                             `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
@@ -3116,7 +3204,7 @@ export class PowqlInterface {
                 }
                 continue;
             }
-            const expr = byOrderExprs.get(key);
+            const expr = this.lookupGroupKey(byOrderExprs, key);
             if (!expr) {
                 throw new ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". Orderable keys: ${validKeys()}.`);
             }

package/dist/query/aggregates.d.ts

@@ -30,19 +30,6 @@ import type { BuilderCtx } from './where.js';
  */
 export declare function assertAggregatePiiOptIn(table: string, meta: TableMetadata | undefined, field: string, column: string, usage: string, includePii: boolean | undefined): void;
 export declare function buildGroupBy<T extends object>(qi: BuilderCtx, args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
-/**
- * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
- * ({@link buildOrderBy}, which validates keys against the table's physical
- * columns), groupBy ordering targets the columns the RESULT actually
- * contains: plain by-fields, JSON group-key aliases, and requested aggregates
- * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
- * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
- * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
- * to accept a SELECT-alias reference in ORDER BY, and any already-bound
- * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
- * no `$n` renumbering). An aggregate key that was not requested, or an unknown
- * by-key, throws {@link ValidationError} E003 listing the valid keys.
- */
 export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy | GroupByOrderBy[], byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
 /**
  * Validate a JSON-path target (group key or aggregate target) in groupBy:

package/dist/query/aggregates.js

@@ -12,7 +12,7 @@ import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
 import { dedupeColumnList, isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, } from './filters.js';
 import { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
-import { isTemporalInfinity, ownLookup, parseDbDate, unknownFieldMessage, warnRedundantSortTerm } from './utils.js';
+import { isTemporalInfinity, ownLookup, parseDbDate, resolveColumnName, warnRedundantSortTerm } from './utils.js';
 import * as whereMod from './where.js';
 import { assertWhereDepth } from './where-compile.js';
 /**
@@ -46,12 +46,14 @@ export function assertAggregatePiiOptIn(table, meta, field, column, usage, inclu
 }
 export 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 ValidationError(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 = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Resolve the PII opt-in ONCE, here, so the sentinel check runs on every
@@ -107,18 +109,30 @@ export 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] ?? 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);
@@ -199,7 +213,9 @@ export 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] ?? snakeToCamel(col)}`, expr);
                 continue;
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
@@ -354,6 +370,37 @@ export 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 = resolveColumnName(qi.tableMeta, key);
+    if (column === undefined)
+        return undefined;
+    return qi.tableMeta.reverseColumnMap[column] ?? snakeToCamel(column);
+}
 export 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). */
@@ -416,7 +463,11 @@ export 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 ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${qi.table}": ` +
                         `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
@@ -427,7 +478,7 @@ export 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 ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${qi.table}". ` +
                 `Orderable keys: ${validKeys()}.`);
@@ -691,7 +742,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 ValidationError(`[turbine] having on "${field}" (table "${qi.table}") filters the grouped value itself, but ` +
@@ -842,25 +893,22 @@ export 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 ValidationError(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 ValidationError(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/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