turbine-orm 0.32.0 → 0.32.2

package/dist/query/builder.js

@@ -20,6 +20,105 @@ import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fin
 import { escapeLike, LRUCache, OPERATOR_KEYS, parseDbDate, sqlToPreparedName } from './utils.js';
 /** Relations already warned about missing FK indexes (once per process, dev only). */
 const unindexedRelationWarned = new Set();
+/**
+ * Dev-mode SQL-cache lockstep cross-check gate.
+ *
+ * The SQL template cache requires three code paths to enumerate where-clause
+ * keys identically: `fingerprintWhere` (builds the cache key),
+ * `buildWhereClause` (builds SQL + `$N` params on a MISS), and
+ * `collectWhereParams` (re-collects params on a HIT without rebuilding). They
+ * are synchronized only by convention, and drift has shipped silent
+ * wrong-results bugs before (permuted where-key order; an orderBy fingerprint
+ * collision). This check catches such drift loudly the moment a cache HIT
+ * happens by rebuilding the SQL + params fresh and comparing them against what
+ * the cache-hit path produced.
+ *
+ * Enabled only when `NODE_ENV !== 'production'` (same convention as the other
+ * dev-only guards in this file) AND `TURBINE_DISABLE_CACHE_CHECK !== '1'`. The
+ * env vars are read inline (not captured once) so tests and perf-sensitive dev
+ * traffic can toggle them per process. In production the check never runs, so
+ * the hot path is unchanged.
+ */
+function cacheCrossCheckEnabled() {
+    return process.env.NODE_ENV !== 'production' && process.env.TURBINE_DISABLE_CACHE_CHECK !== '1';
+}
+/**
+ * Strict structural equality for a single SQL parameter value. Handles the
+ * value shapes Turbine binds: primitives (incl. `NaN` and `bigint`), `null`/
+ * `undefined`, `Date` (by time), `Buffer`/typed arrays (by bytes), arrays
+ * (`in` lists, pgvector arrays), and plain objects (JSON filter payloads).
+ */
+function cacheParamValueEqual(a, b) {
+    if (a === b)
+        return true; // identical ref or equal primitive (covers matching null/undefined)
+    if (a === null || b === null || a === undefined || b === undefined)
+        return false;
+    const ta = typeof a;
+    if (ta !== typeof b)
+        return false;
+    if (ta !== 'object') {
+        // Primitives that failed `===`: only NaN is legitimately "equal" to itself.
+        return typeof a === 'number' && Number.isNaN(a) && Number.isNaN(b);
+    }
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    const aView = ArrayBuffer.isView(a);
+    const bView = ArrayBuffer.isView(b);
+    if (aView || bView) {
+        if (!aView || !bView)
+            return false;
+        const ua = a;
+        const ub = b;
+        if (ua.byteLength !== ub.byteLength)
+            return false;
+        const va = new Uint8Array(ua.buffer, ua.byteOffset, ua.byteLength);
+        const vb = new Uint8Array(ub.buffer, ub.byteOffset, ub.byteLength);
+        for (let i = 0; i < va.length; i++) {
+            if (va[i] !== vb[i])
+                return false;
+        }
+        return true;
+    }
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr || bArr) {
+        if (!aArr || !bArr)
+            return false;
+        const arrA = a;
+        const arrB = b;
+        if (arrA.length !== arrB.length)
+            return false;
+        for (let i = 0; i < arrA.length; i++) {
+            if (!cacheParamValueEqual(arrA[i], arrB[i]))
+                return false;
+        }
+        return true;
+    }
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const k of keysA) {
+        if (!Object.hasOwn(objB, k))
+            return false;
+        if (!cacheParamValueEqual(objA[k], objB[k]))
+            return false;
+    }
+    return true;
+}
+/** Element-wise strict equality of two SQL parameter arrays. */
+function cacheParamsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!cacheParamValueEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
@@ -28,6 +127,15 @@ export class QueryInterface {
     tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     sqlTemplateCache = new LRUCache(1000);
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    lastCacheHit = false;
     middlewares;
     defaultLimit;
     warnOnUnlimited;
@@ -346,24 +454,84 @@ export class QueryInterface {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     acquireSql(cacheKey, build) {
         if (!this.sqlCacheEnabled) {
-            const sql = build();
+            this.lastCacheHit = false;
+            const sql = build([]);
             this.cacheMisses++;
             return { sql, name: sqlToPreparedName(sql) };
         }
         const cached = this.sqlTemplateCache.get(cacheKey);
         if (cached) {
             this.cacheHits++;
+            this.lastCacheHit = true;
             return cached;
         }
-        const sql = build();
+        this.lastCacheHit = false;
+        const sql = build([]);
         const entry = { sql, name: sqlToPreparedName(sql) };
         this.sqlTemplateCache.set(cacheKey, entry);
         this.cacheMisses++;
         return entry;
     }
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    crossCheckCache(op, cacheKey, entry, build, collectedParams) {
+        if (!this.lastCacheHit)
+            return;
+        if (!cacheCrossCheckEnabled())
+            return;
+        const freshParams = [];
+        const freshSql = build(freshParams);
+        const sqlOk = freshSql === entry.sql;
+        const paramsOk = cacheParamsEqual(collectedParams, freshParams);
+        if (sqlOk && paramsOk)
+            return;
+        const truncate = (s) => (s.length > 300 ? `${s.slice(0, 300)}… (${s.length} chars total)` : s);
+        const details = [];
+        if (!sqlOk) {
+            details.push(`cached SQL and freshly-built SQL diverge:\n  cached = <${truncate(entry.sql)}>\n  fresh  = <${truncate(freshSql)}>`);
+        }
+        if (!paramsOk) {
+            details.push(`cache-hit params and freshly-built params diverge (collected ${collectedParams.length}, built ${freshParams.length})`);
+        }
+        throw new ValidationError(`[turbine] SQL cache lockstep violation on ${op} (fingerprint "${cacheKey}"). ` +
+            `This is a Turbine internal invariant violation, please report it at ` +
+            `https://github.com/zvndev/turbine-orm/issues. The fingerprint, SQL-build, and ` +
+            `param-collect paths must enumerate where-clause keys identically.\n${details.join('\n')}`);
+    }
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -562,19 +730,22 @@ export class QueryInterface {
             });
         // Simple path: plain equality, no operators/null/OR
         if (!args.with && isSimpleWhere) {
-            const entry = this.acquireSql(ck, () => {
+            const buildSql = (freshParams) => {
                 const qt = this.q(this.table);
-                const tempParams = whereKeys.map((k) => whereObj[k]);
-                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = ${this.p(i + 1)}`);
+                const whereClauses = whereKeys.map((k, i) => {
+                    freshParams.push(whereObj[k]);
+                    return `${this.toSqlColumn(k)} = ${this.p(i + 1)}`;
+                });
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
-                void tempParams; // params are positional, SQL is value-invariant
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params (same order as build)
             for (const k of whereKeys) {
                 params.push(whereObj[k]);
             }
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -588,16 +759,17 @@ export class QueryInterface {
         }
         // General path (with operators, null, OR, with clause)
         if (!args.with) {
-            const entry = this.acquireSql(ck, () => {
-                const freshParams = [];
+            const buildSql = (freshParams) => {
                 const clause = this.buildWhereClause(whereObj, freshParams);
                 const whereSql = clause ? ` WHERE ${clause}` : '';
                 const qt = this.q(this.table);
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
-            });
+            };
+            const entry = this.acquireSql(ck, buildSql);
             // Collect params
             this.collectWhereParams(whereObj, params);
+            this.crossCheckCache('findUnique', ck, entry, buildSql, params);
             return {
                 sql: entry.sql,
                 params,
@@ -614,16 +786,17 @@ export class QueryInterface {
         //   1. buildWhere pushes where params
         //   2. buildSelectWithRelations pushes relation params to same array
         // We must preserve this exact order.
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
             return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
         this.collectWithParams(args.with, params);
+        this.crossCheckCache('findUnique', ck, entry, buildSql, params);
         const parseWith = this.makeNestedParser(args.with);
         return {
             sql: entry.sql,
@@ -688,7 +861,7 @@ export class QueryInterface {
         if (this.warnedTables.has(this.table))
             return;
         this.warnedTables.add(this.table);
-        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit: this will fetch every row. ` +
             'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
     /**
@@ -745,15 +918,24 @@ export class QueryInterface {
                 .sort()
                 .join(',')
             : '';
-        const distinctFp = args?.distinct ? args.distinct.slice().sort().join(',') : '';
+        // distinct must fingerprint in USER order: the SQL emits `DISTINCT ON` in
+        // the caller's column order, so a permuted array rebuilds different SQL and
+        // must not collapse onto the same cache entry (would trip the cross-check).
+        const distinctFp = args?.distinct ? args.distinct.join(',') : '';
         const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
-        const limitFp = effectiveLimit !== undefined ? '1' : '0';
-        const offsetFp = args?.offset !== undefined ? '1' : '0';
+        // On engines that inline the literal LIMIT/OFFSET into the SQL text
+        // (dialect.inlineLimitOffset, MySQL), the value is part of the SQL, not the
+        // params, so it MUST be part of the fingerprint or two different limits share
+        // one cached statement (silent wrong row counts). Parameterized engines
+        // (PG/SQLite/SQL Server, whose buildLimitOffset uses placeholders) keep the
+        // presence-only fingerprint so the cache is not needlessly fragmented.
+        const inlinePagination = this.dialect.inlineLimitOffset === true;
+        const limitFp = effectiveLimit !== undefined ? (inlinePagination ? `v${effectiveLimit}` : '1') : '0';
+        const offsetFp = args?.offset !== undefined ? (inlinePagination ? `v${args.offset}` : '1') : '0';
         const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            // Fresh build — generates SQL and populates freshParams
-            const freshParams = [];
+        const buildSql = (freshParams) => {
+            // Fresh build: generates SQL and populates freshParams
             const { sql: freshWhereSql } = hasWhere
                 ? (() => {
                     const clause = this.buildWhereClause(whereObj, freshParams);
@@ -833,7 +1015,8 @@ export class QueryInterface {
             }
             sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
             return sql;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order:
         // 1. WHERE params (includes the AND-merged global filter, if any)
         if (hasWhere) {
@@ -864,6 +1047,7 @@ export class QueryInterface {
         if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(args.offset));
         }
+        this.crossCheckCache('findMany', ck, entry, buildSql, params);
         // Build the row parser once (positional shapes are computed here, not per row).
         const parseWith = args?.with ? this.makeNestedParser(args.with) : null;
         return {
@@ -1189,8 +1373,7 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = lock ? null : `u:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const buildSql = () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             if (lock) {
@@ -1214,13 +1397,15 @@ export class QueryInterface {
         };
         let sql;
         let preparedName;
+        let cacheEntry;
         if (ck) {
-            const entry = this.acquireSql(ck, buildSql);
-            sql = entry.sql;
-            preparedName = entry.name;
+            cacheEntry = this.acquireSql(ck, buildSql);
+            sql = cacheEntry.sql;
+            preparedName = cacheEntry.name;
         }
         else {
-            sql = buildSql();
+            // optimisticLock path: value-variant version check → uncacheable, no cross-check.
+            sql = buildSql([]);
         }
         // Collect params: SET first, then WHERE, then version check (same order as fresh build)
         this.collectSetParams(dataObj, params);
@@ -1228,6 +1413,9 @@ export class QueryInterface {
         if (lock) {
             params.push(lock.expected);
         }
+        if (ck && cacheEntry) {
+            this.crossCheckCache('update', ck, cacheEntry, buildSql, params);
+        }
         return {
             sql,
             params,
@@ -1359,8 +1547,7 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `d:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
@@ -1368,8 +1555,10 @@ export class QueryInterface {
             return this.dialect.buildDeleteStatement
                 ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
                 : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('delete', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1497,16 +1686,17 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `um:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
             return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectSetParams(dataObj, params);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('updateMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1533,13 +1723,14 @@ export class QueryInterface {
         const whereFp = this.fingerprintWhere(whereObj);
         const ck = `dm:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `DELETE FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         this.collectWhereParams(whereObj, params);
+        this.crossCheckCache('deleteMany', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1566,15 +1757,16 @@ export class QueryInterface {
         const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const ck = `cnt:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
+        const buildSql = (freshParams) => {
             const clause = hasWhere ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
-        });
+        };
+        const entry = this.acquireSql(ck, buildSql);
         if (hasWhere) {
             this.collectWhereParams(whereObj, params);
         }
+        this.crossCheckCache('count', ck, entry, buildSql, params);
         return {
             sql: entry.sql,
             params,
@@ -1626,6 +1818,15 @@ export class QueryInterface {
         const selectExprs = [];
         /** by entries in order: how to read each group key off the result row. */
         const byReaders = [];
+        // ORDER BY registries: map each key the groupBy RESULT actually contains to
+        // the exact SELECT expression that produced it, so `orderBy` re-emits that
+        // expression (never a SELECT alias, since not every dialect accepts alias
+        // references in ORDER BY, and re-emitting mirrors HAVING's `jsonAggExprs`).
+        // `byOrderExprs`: plain by-field name / JSON group-key alias → column or
+        // extract expression. `aggOrderExprs`: `${aggKey}:${field}` → aggregate
+        // expression (including any already-bound JSON-path placeholder, reused
+        // exactly like HAVING since ORDER BY is appended after all other params).
+        const byOrderExprs = new Map();
         const usedResultKeys = new Set();
         const claimResultKey = (key, what) => {
             if (key === '_count' || usedResultKeys.has(key)) {
@@ -1646,6 +1847,7 @@ export class QueryInterface {
                 groupExprs.push(this.q(col));
                 selectExprs.push(this.q(col));
                 byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+                byOrderExprs.set(entry, this.q(col));
             }
             else {
                 const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
@@ -1657,13 +1859,24 @@ export class QueryInterface {
                 selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
                 groupExprs.push(extract);
                 byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+                // ORDER BY by this JSON alias re-emits the extract expression (with its
+                // already-bound $n): the same reuse HAVING does for JSON aggregates.
+                byOrderExprs.set(alias, extract);
             }
         }
         // _count
-        if (args._count === true || args._count === undefined) {
+        const countSelected = args._count === true || args._count === undefined;
+        if (countSelected) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
+        // ORDER BY aggregate expressions, keyed `${aggKey}:${field}` (plus a bare
+        // `_count`). Populated alongside the SELECT list below so `orderBy` can only
+        // reference an aggregate that is actually requested. `COUNT(*)` (uncast) is
+        // the ordering expression (the SELECT cast is only for the returned value).
+        const aggOrderExprs = new Map();
+        if (countSelected)
+            aggOrderExprs.set('_count', 'COUNT(*)');
         // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
         // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
         // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
@@ -1686,6 +1899,7 @@ export class QueryInterface {
                     const inner = `${sqlFn}(${this.q(col)})`;
                     const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
                     selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    aggOrderExprs.set(`${aggKey}:${key}`, expr);
                     continue;
                 }
                 const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
@@ -1703,6 +1917,7 @@ export class QueryInterface {
                 selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
                 jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
                 jsonAggExprs.set(`${key}:${aggKey}`, expr);
+                aggOrderExprs.set(`${aggKey}:${key}`, expr);
             }
         };
         buildAggregates('_sum', 'SUM', args._sum);
@@ -1719,9 +1934,12 @@ export class QueryInterface {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
         }
-        // ORDER BY
+        // ORDER BY, over the groupBy RESULT columns (by-fields, JSON aliases, and
+        // requested aggregates), not the table's physical columns.
         if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            const orderSql = this.buildGroupByOrderBy(args.orderBy, byOrderExprs, aggOrderExprs);
+            if (orderSql)
+                sql += ` ORDER BY ${orderSql}`;
         }
         return {
             sql,
@@ -1786,6 +2004,74 @@ export class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * 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.
+     */
+    buildGroupByOrderBy(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). */
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys()) {
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            }
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            // Aggregate ordering blocks.
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(value);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                    continue;
+                }
+                // `_sum` / `_avg` / `_min` / `_max`: an object of field → direction/spec.
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${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()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(dirSpec);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                }
+                continue;
+            }
+            // Plain by-field name or JSON group-key alias.
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". ` +
+                    `Orderable keys: ${validKeys()}.`);
+            }
+            const { dir, nulls } = normalizeOrderBy(value);
+            parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a
@@ -2903,9 +3189,11 @@ export class QueryInterface {
                 const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, targetRels?.[k]?.to)}`);
                 subParts.push(`o=${oEntries.join(',')}`);
             }
-            // limit presence
+            // limit presence, but on inline-pagination engines (MySQL) the literal
+            // value is baked into the subquery SQL, so fingerprint the value there or
+            // `{limit:3}` and `{limit:5}` would share one cached statement.
             if (opts.limit !== undefined) {
-                subParts.push('l=1');
+                subParts.push(this.dialect.inlineLimitOffset ? `l=${opts.limit}` : 'l=1');
             }
             // nested with (recurse)
             if (opts.with) {

package/dist/query/deferred.d.ts

@@ -85,10 +85,19 @@ export interface QueryInterfaceOptions {
     preparedStatements?: boolean;
     /**
      * Enable the SQL template cache. When true, repeated queries with the
-     * same shape (same keys, operators, relations — different values) reuse
+     * same shape (same keys, operators, relations, different values) reuse
      * cached SQL text instead of rebuilding from scratch.
      *
      * Default: `true`. Set to `false` as a nuclear kill switch.
+     *
+     * Dev-mode safety net: when `NODE_ENV !== 'production'`, every cache HIT is
+     * cross-checked by rebuilding the SQL + params fresh and comparing them
+     * against the cache-hit result, catching any drift between the fingerprint,
+     * SQL-build, and param-collect paths (which has silently corrupted results
+     * before). A mismatch throws a `ValidationError` (E003). This runs only
+     * outside production, so it never touches the production hot path. Set the
+     * env var `TURBINE_DISABLE_CACHE_CHECK=1` to opt out when dev traffic is
+     * perf-sensitive.
      */
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */