turbine-orm 0.71.0 → 0.72.0

package/README.md

@@ -43,8 +43,8 @@ Measured **2026-08-15 against turbine-orm 0.71.0**, versus **Prisma 7.9.1** (`@p
 What that run says:
 
 - **Turbine ran at 1.08x hand-written `pg`**, where Drizzle ran at 1.47x and Prisma at 1.81x (geometric mean over the eight scenarios with a raw control). That 1.08x is the conservative reading: the raw L2 control statement still uses the `json_build_object` encoding Turbine has moved off, which is worth 1.83x on its own, so the figure the harness records unadjusted is 1.00x. The adjusted one is published instead.
-- Across all ten scenarios Turbine was **2.02x faster than Prisma 7.9** and **1.46x faster than Drizzle 0.45** by geometric mean. Turbine takes nine scenarios, Drizzle one, Prisma none.
-- **Drizzle wins streaming, by 22%** (39.49 ms vs 50.39 ms). Turbine's cursor carries about 19% overhead over hand-written keyset pagination on a full-table drain; it buys arbitrary `orderBy`, early break, and nested `with` per batch, but on this shape it is a loss. `findManyStreamBatches`, which yields a batch at a time instead of a row, cuts that to 6% above the control and narrows the loss to 1.16x without closing it.
+- Across all ten scenarios Turbine was **2.02x faster than Prisma 7.9** and **1.46x faster than Drizzle 0.45** by geometric mean. Turbine took nine scenarios, Drizzle one, Prisma none. The one Drizzle took was streaming, and 0.72.0 takes it back (below).
+- **Streaming was Drizzle's one win, by 22%** (39.49 ms vs 50.39 ms) on 0.71.0. **0.72.0 closes it**: the remaining gap was temporal decoding rather than the cursor, and a direct scan for the canonical ISO wire shape (declining anything else back to `pg`'s own parser) takes `findManyStream` from 52.44 ms to **37.06 ms** against Drizzle's 42.09 ms re-measured in the same rotation, and `findManyStreamBatches` to **31.65 ms**. Scope, because it matters: that is a targeted re-measurement of one scenario on a paired one-process harness, not a re-run of the ten above, so the table's stream row still shows 0.71.0 and the absolute values are not comparable. Method and controls in [`benchmarks/RESULTS-0.72.0.md`](benchmarks/RESULTS-0.72.0.md).
 - **Pipelining is Turbine's clearest win**: one TCP flush for 5 queries runs 2.04x faster than Prisma and 2.07x faster than Drizzle, level with raw `pg`.
 - Three scenarios (L2, L3, atomic increment) are marked *contested*: the contiguous cross-check harness disagrees with itself across runs of the same configuration there, so neither side claims them. Both nested reads were losses in the previous run and the improvement behind them reproduces on both harnesses; whether it is enough to pass Drizzle is what is unsettled.
 - The sub-0.15 ms scenarios carry roughly one third uncertainty in their absolute values. Orderings held across runs; margins should not be quoted, and that includes L2's 2.5%.

package/dist/cjs/client.d.ts

@@ -800,24 +800,6 @@ export declare class TurbineClient {
      * (`ALTER ROLE ... SET plan_cache_mode = ...`).
      */
     private static withPlanCacheMode;
-    /**
-     * `connectionString` with `setting` appended to its existing `options` query
-     * parameter, or `null` when it carries no `options` (in which case the caller
-     * should use the `options` pool field, which is not overridden).
-     *
-     * 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.
-     *
-     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
-     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
-     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
-     * all of the coverage gate's headroom) is written up over there.
-     */
-    private static mergeConnectionStringOptions;
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
      * in this process settled the zone-less temporal read parsers (OIDs 1114,

package/dist/cjs/client.js

@@ -29,6 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TurbineClient = exports.TransactionClient = exports.READ_OPERATIONS = void 0;
 exports.withRetry = withRetry;
 const pg_1 = __importDefault(require("pg"));
+const connection_url_js_1 = require("./connection-url.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const observe_js_1 = require("./observe.js");
@@ -1146,7 +1147,7 @@ class TurbineClient {
         // cannot be a bind parameter.
         const setting = `-c plan_cache_mode=${mode}`;
         const merged = poolConfig.connectionString
-            ? TurbineClient.mergeConnectionStringOptions(poolConfig.connectionString, setting)
+            ? (0, connection_url_js_1.mergeConnectionStringOptions)(poolConfig.connectionString, setting)
             : null;
         if (merged)
             return { ...poolConfig, connectionString: merged };
@@ -1156,34 +1157,6 @@ class TurbineClient {
         const existing = poolConfig.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
         return { ...poolConfig, options: existing ? `${existing} ${setting}` : setting };
     }
-    /**
-     * `connectionString` with `setting` appended to its existing `options` query
-     * parameter, or `null` when it carries no `options` (in which case the caller
-     * should use the `options` pool field, which is not overridden).
-     *
-     * 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.
-     *
-     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
-     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
-     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
-     * all of the coverage gate's headroom) is written up over there.
-     */
-    static mergeConnectionStringOptions(connectionString, setting) {
-        const q = connectionString.indexOf('?');
-        if (q === -1)
-            return null;
-        const params = new URLSearchParams(connectionString.slice(q + 1));
-        const existing = params.get('options');
-        if (existing === null)
-            return null;
-        params.set('options', `${existing} ${setting}`);
-        return connectionString.slice(0, q + 1) + params.toString();
-    }
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
      * in this process settled the zone-less temporal read parsers (OIDs 1114,

package/dist/cjs/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/cjs/connection-url.js

@@ -39,6 +39,7 @@ exports.parseConnectionTarget = parseConnectionTarget;
 exports.detectPooler = detectPooler;
 exports.poolerRefusalMessage = poolerRefusalMessage;
 exports.withStatementTimeoutOption = withStatementTimeoutOption;
+exports.mergeConnectionStringOptions = mergeConnectionStringOptions;
 /**
  * Host and port from a connection string, in either shape libpq accepts.
  *
@@ -263,25 +264,22 @@ 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) {
     const q = connectionString.indexOf('?');

package/dist/cjs/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/cjs/powql.js

@@ -77,6 +77,7 @@ const powdb_js_1 = require("./powdb.js");
 const aggregates_js_1 = require("./query/aggregates.js");
 const compound_unique_js_1 = require("./query/compound-unique.js");
 const filters_js_1 = require("./query/filters.js");
+const relation_names_js_1 = require("./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.
@@ -231,9 +232,20 @@ 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 = (0, utils_js_1.resolveColumnName)(this.meta, field);
+        const snake = resolved ?? (0, utils_js_1.ownLookup)(this.meta.columnMap, field) ?? field;
         const col = this.meta.columns.find((c) => c.name === snake || c.field === field);
         if (!col) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown column "${field}" on table "${this.table}". Known: ${this.meta.columns
@@ -242,6 +254,41 @@ 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
@@ -356,6 +403,22 @@ 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 = (0, relation_names_js_1.normalizeWithClause)(this.schema, this.table, args.with);
+        return normalized === args.with ? args : { ...args, with: normalized };
+    }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
             return;
@@ -796,8 +859,8 @@ 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 ((0, utils_js_1.resolveRelationDef)(this.meta.relations, key)) {
+                relConds.push(await this.resolveRelationCondition((0, utils_js_1.resolveRelationDef)(this.meta.relations, key), value, timeout));
             }
             else {
                 scalar[key] = value;
@@ -932,7 +995,7 @@ class PowqlInterface {
      * for a misspelling that is not there. Same message as the SQL engines.
      */
     projectionColumn(field, clause) {
-        if ((0, utils_js_1.ownLookup)(this.meta.relations, field)) {
+        if ((0, utils_js_1.resolveRelationDef)(this.meta.relations, field)) {
             throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(this.table, field, clause));
         }
         return this.column(field).name;
@@ -1300,6 +1363,7 @@ 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
@@ -1381,6 +1445,12 @@ 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);
@@ -1445,6 +1515,7 @@ 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) {
@@ -1469,6 +1540,7 @@ 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');
@@ -2400,7 +2472,7 @@ class PowqlInterface {
         for (const [field, value] of Object.entries(data)) {
             if (value === undefined)
                 continue;
-            if (this.meta.relations[field]) {
+            if ((0, utils_js_1.resolveRelationDef)(this.meta.relations, field)) {
                 throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not createMany()/upsert()`);
             }
             out.push({ col: this.column(field), value });
@@ -2418,7 +2490,11 @@ 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') {
@@ -2557,7 +2633,7 @@ class PowqlInterface {
         for (const [field, value] of Object.entries(data)) {
             if (value === undefined)
                 continue;
-            if (this.meta.relations[field]) {
+            if ((0, utils_js_1.resolveRelationDef)(this.meta.relations, field)) {
                 throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not updateMany()/upsert()`);
             }
             const colMeta = this.column(field);
@@ -2720,7 +2796,10 @@ 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 errors_js_1.NotFoundError({ table: this.table, where: createData });
             return row;
@@ -2888,13 +2967,18 @@ class PowqlInterface {
                 if (typeof entry === 'string') {
                     const col = this.column(entry);
                     (0, aggregates_js_1.assertAggregatePiiOptIn)(this.table, this.meta, entry, col.name, 'groupBy `by` key', (0, types_js_1.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);
@@ -2957,9 +3041,11 @@ 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);
@@ -3095,7 +3181,7 @@ class PowqlInterface {
                         throw new errors_js_1.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));
                 }
             }
@@ -3143,7 +3229,9 @@ 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 errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
                             `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
@@ -3152,7 +3240,7 @@ class PowqlInterface {
                 }
                 continue;
             }
-            const expr = byOrderExprs.get(key);
+            const expr = this.lookupGroupKey(byOrderExprs, key);
             if (!expr) {
                 throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". Orderable keys: ${validKeys()}.`);
             }

package/dist/cjs/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: