turbine-orm 0.31.0 → 0.32.1

package/dist/cjs/query/builder.js

@@ -56,6 +56,105 @@ const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./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
 class QueryInterface {
     pool;
@@ -64,6 +163,15 @@ class QueryInterface {
     tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     sqlTemplateCache = new utils_js_1.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;
@@ -327,6 +435,10 @@ class QueryInterface {
      */
     async runFindManyBatched(args) {
         const withClause = args.with;
+        // Scope-rule parity with the join strategy (which throws at SQL build):
+        // reject nested pick-row ordering BEFORE the base query so acceptance
+        // never depends on how many rows come back.
+        (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         // Capture the opt-out from the ARGS before any await: this.currentSkip is
         // instance state on a cached accessor, so a concurrent build during the
         // base-query await would overwrite it (tenant query loading relations with
@@ -378,24 +490,84 @@ 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: (0, utils_js_1.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: (0, utils_js_1.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 errors_js_1.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
@@ -552,6 +724,8 @@ class QueryInterface {
      */
     async runFindUniqueBatched(args) {
         const withClause = args.with;
+        // Same scope-rule parity as runFindManyBatched: reject before querying.
+        (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed);
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
@@ -592,19 +766,22 @@ 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,
@@ -618,16 +795,17 @@ 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,
@@ -644,16 +822,17 @@ 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,
@@ -718,7 +897,7 @@ 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).');
     }
     /**
@@ -738,6 +917,21 @@ class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = args?.skipGlobalFilters;
+        // `distinct` + relation orderBy is refused up front (E003): the distinct
+        // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
+        // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
+        // to-one relation ordering) would reference the parent table name out of
+        // scope — a guaranteed "missing FROM-clause entry" crash on Postgres.
+        // Checked BEFORE the SQL cache so build and warm-cache paths throw
+        // identically (same rule as the vector guard inside the distinct branch).
+        if (args?.distinct && args.distinct.length > 0 && args.orderBy) {
+            for (const d of Object.values(args.orderBy)) {
+                if (this.isRelationOrderByValue(d)) {
+                    throw new errors_js_1.ValidationError('[turbine] `distinct` cannot be combined with relation orderBy (pick-row, `_count`, or ' +
+                        'to-one relation ordering): the outer re-order cannot reference the parent table.');
+                }
+            }
+        }
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const colKey = columnsList ? columnsList.join(',') : '*';
         // AND-merge this table's global filter into the user where; `hasWhere` gates
@@ -751,7 +945,7 @@ class QueryInterface {
         const withFp = args?.with ? this.withFingerprint(args.with) : '';
         const orderFp = args?.orderBy
             ? Object.entries(args.orderBy)
-                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`)
+                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, this.tableMeta.relations[k]?.to)}`)
                 .join(',')
             : '';
         const cursorFp = args?.cursor
@@ -760,15 +954,24 @@ 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);
@@ -848,7 +1051,8 @@ 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) {
@@ -879,6 +1083,7 @@ 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 {
@@ -1204,8 +1409,7 @@ 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) {
@@ -1229,13 +1433,15 @@ 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);
@@ -1243,6 +1449,9 @@ class QueryInterface {
         if (lock) {
             params.push(lock.expected);
         }
+        if (ck && cacheEntry) {
+            this.crossCheckCache('update', ck, cacheEntry, buildSql, params);
+        }
         return {
             sql,
             params,
@@ -1374,8 +1583,7 @@ 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;
@@ -1383,8 +1591,10 @@ 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,
@@ -1512,16 +1722,17 @@ 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,
@@ -1548,13 +1759,14 @@ 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,
@@ -1581,15 +1793,16 @@ 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,
@@ -1612,67 +1825,124 @@ class QueryInterface {
         const meta = this.schema.tables[this.table];
         if (meta) {
             for (const key of args.by) {
-                if (!(key in meta.columnMap)) {
+                if (typeof key === 'string' && !(key in meta.columnMap)) {
                     throw new errors_js_1.ValidationError(`Unknown column "${key}" in groupBy for table "${this.table}"`);
                 }
             }
         }
         this.currentSkip = args.skipGlobalFilters;
-        const groupColsRaw = args.by.map((k) => this.toColumn(k));
-        const groupCols = groupColsRaw.map((c) => this.q(c));
         const gbWhere = this.mergeGlobalFilter(args.where);
         const { sql: whereSql, params } = gbWhere
             ? this.buildWhere(gbWhere)
             : { sql: '', params: [] };
-        // Build SELECT expressions: group-by columns + aggregate functions
-        const selectExprs = [...groupCols];
+        // Row source. Plain: `"table"<WHERE>`. With `distinctOn` (PostgreSQL
+        // only), the groupBy runs over one representative row per column
+        // combination: the wrapper carries args.where INSIDE it (filter before
+        // picking) and is aliased as the table name so every outer expression is
+        // byte-identical either way.
+        const fromSql = args.distinctOn
+            ? this.buildDistinctOnSource(args.distinctOn, whereSql, params)
+            : `${this.q(this.table)}${whereSql}`;
+        // Group keys: plain columns and/or JSON-path keys. Output-name collisions
+        // are rejected up front — and the check runs over the EMITTED SQL output
+        // column names (snake_case column / JSON alias / `_agg_key` aggregate
+        // alias), not just the given arg keys: the driver keeps only the LAST
+        // duplicate field per row object, so a JSON alias equal to another key's
+        // snake_case column (or an aggregate output alias) would silently clobber
+        // that value in the results.
+        const groupExprs = [];
+        const selectExprs = [];
+        /** by entries in order: how to read each group key off the result row. */
+        const byReaders = [];
+        const usedResultKeys = new Set();
+        const claimResultKey = (key, what) => {
+            if (key === '_count' || usedResultKeys.has(key)) {
+                throw new errors_js_1.ValidationError(`[turbine] groupBy output name "${key}" (${what}) collides with another output column on table ` +
+                    `"${this.table}": set an explicit \`alias\` (or rename the aggregate key) to disambiguate.`);
+            }
+            usedResultKeys.add(key);
+        };
+        for (const entry of args.by) {
+            if (typeof entry === 'string') {
+                const col = this.toColumn(entry);
+                claimResultKey(entry, `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)
+                    claimResultKey(col, `column "${col}"`);
+                groupExprs.push(this.q(col));
+                selectExprs.push(this.q(col));
+                byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+            }
+            else {
+                const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
+                params.push(this.jsonPathParam(entry.path));
+                const extract = this.dialect.buildJsonPathExtract(this.q(col), this.p(params.length));
+                const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
+                claimResultKey(alias, `JSON path on "${entry.field}"`);
+                // Same expression (and the same $n placeholder) in SELECT and GROUP BY.
+                selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
+                groupExprs.push(extract);
+                byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+            }
+        }
         // _count
         if (args._count === true || args._count === undefined) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
-        // _sum
-        if (args._sum) {
-            for (const [field, enabled] of Object.entries(args._sum)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${this.q(col)}) AS ${this.q(`_sum_${col}`)}`);
-                }
-            }
-        }
-        // _avg
-        if (args._avg) {
-            for (const [field, enabled] of Object.entries(args._avg)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
-                }
-            }
-        }
-        // _min
-        if (args._min) {
-            for (const [field, enabled] of Object.entries(args._min)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${this.q(col)}) AS ${this.q(`_min_${col}`)}`);
+        // _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
+        // alias (and coercion kind) in the transform; `jsonAggExprs` lets HAVING
+        // reuse the exact aggregate expression (same placeholders) by alias.
+        const jsonAggFields = new Map();
+        const jsonAggExprs = new Map();
+        const buildAggregates = (aggKey, sqlFn, spec) => {
+            if (!spec)
+                return;
+            for (const [key, target] of Object.entries(spec)) {
+                if (!target)
+                    continue;
+                if (target === true) {
+                    const col = this.toColumn(key);
+                    // Aggregate output aliases share the same output-name namespace as
+                    // the group keys: `_sum: { totalPrice: true, total_price: {json} }`
+                    // would emit two "_sum_total_price" columns and silently drop one.
+                    claimResultKey(`${aggKey}_${col}`, `${aggKey} of column "${col}"`);
+                    const inner = `${sqlFn}(${this.q(col)})`;
+                    const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
+                    selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    continue;
                 }
-            }
-        }
-        // _max
-        if (args._max) {
-            for (const [field, enabled] of Object.entries(args._max)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${this.q(col)}) AS ${this.q(`_max_${col}`)}`);
+                const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
+                const alwaysNumeric = aggKey === '_sum' || aggKey === '_avg';
+                if (alwaysNumeric && target.type === 'text') {
+                    throw new errors_js_1.ValidationError(`[turbine] groupBy ${aggKey} target "${key}" on table "${this.table}": ` +
+                        `${aggKey} over a JSON path is always numeric: remove \`type: 'text'\`.`);
                 }
+                const numeric = alwaysNumeric || target.type === 'numeric';
+                claimResultKey(`${aggKey}_${key}`, `${aggKey} JSON target "${key}"`);
+                params.push(this.jsonPathParam(target.path));
+                const extract = this.dialect.buildJsonPathExtract(this.q(col), this.p(params.length));
+                const inner = `${sqlFn}(${numeric ? this.castJsonNumeric(extract) : extract})`;
+                const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
+                selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
+                jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
+                jsonAggExprs.set(`${key}:${aggKey}`, expr);
             }
-        }
-        let sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql} GROUP BY ${groupCols.join(', ')}`;
+        };
+        buildAggregates('_sum', 'SUM', args._sum);
+        buildAggregates('_avg', 'AVG', args._avg);
+        buildAggregates('_min', 'MIN', args._min);
+        buildAggregates('_max', 'MAX', args._max);
+        let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
         // HAVING — filter whole groups by their aggregate values.
         // Appends to the same `params` array, so placeholders continue from the
         // WHERE clause's parameter positions (this.p(params.length) below).
         if (args.having) {
-            const havingClauses = this.buildHavingClauses(args.having, params);
+            const havingClauses = this.buildHavingClauses(args.having, params, jsonAggExprs);
             if (havingClauses.length > 0) {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
@@ -1688,9 +1958,11 @@ class QueryInterface {
                 const parsed = this.parseRow(row, this.table);
                 // Restructure aggregate results into nested objects (Prisma-style)
                 const restructured = {};
-                // Copy group-by fields
-                for (const field of args.by) {
-                    restructured[field] = parsed[field];
+                // Copy group-by fields. JSON-path keys read their alias off the raw
+                // row (the alias is not a table column, so parseRow's snake→camel
+                // mapping must not touch it).
+                for (const reader of byReaders) {
+                    restructured[reader.resultKey] = reader.raw ? row[reader.rowKey] : parsed[reader.resultKey];
                 }
                 // _count
                 if ('_count' in row) {
@@ -1705,29 +1977,27 @@ class QueryInterface {
                 const minObj = {};
                 const maxObj = {};
                 let hasSums = false, hasAvgs = false, hasMins = false, hasMaxs = false;
+                // JSON-path aggregates keep their arg key verbatim; plain-column
+                // aggregates keep the snake→camel field mapping.
+                const jsonAgg = (rawKey) => jsonAggFields.get(rawKey);
+                const fieldFor = (rawKey, col) => jsonAgg(rawKey)?.field ?? this.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
                 for (const [rawKey, rawValue] of Object.entries(row)) {
                     if (rawKey.startsWith('_sum_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                        sumObj[field] = rawValue !== null ? Number(rawValue) : null;
+                        sumObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
                         hasSums = true;
                     }
                     else if (rawKey.startsWith('_avg_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                        avgObj[field] = rawValue !== null ? Number(rawValue) : null;
+                        avgObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
                         hasAvgs = true;
                     }
                     else if (rawKey.startsWith('_min_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                        minObj[field] = rawValue;
+                        const j = jsonAgg(rawKey);
+                        minObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
                         hasMins = true;
                     }
                     else if (rawKey.startsWith('_max_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                        maxObj[field] = rawValue;
+                        const j = jsonAgg(rawKey);
+                        maxObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
                         hasMaxs = true;
                     }
                 }
@@ -1744,6 +2014,75 @@ class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * 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
+     * non-empty array of keys/indexes. Returns the resolved snake_case column.
+     */
+    resolveJsonPathTarget(context, field, path) {
+        if (typeof field !== 'string') {
+            throw new errors_js_1.ValidationError(`[turbine] groupBy ${context} on table "${this.table}" requires a string \`field\`.`);
+        }
+        const col = this.toColumn(field);
+        if (!Array.isArray(path) ||
+            path.length === 0 ||
+            path.some((el) => typeof el !== 'string' && !(typeof el === 'number' && Number.isFinite(el)))) {
+            throw new errors_js_1.ValidationError(`[turbine] groupBy ${context} on "${field}" (table "${this.table}") requires a non-empty \`path\` ` +
+                `array of keys/indexes (e.g. { field: '${field}', path: ['category'] }).`);
+        }
+        const colType = this.pgTypeForColumn(this.tableMeta, col);
+        if (!this.isJsonColumnType(colType)) {
+            throw new errors_js_1.ValidationError(`[turbine] groupBy ${context} on "${field}": column "${col}" on table "${this.table}" is not a JSON ` +
+                `column (actual type: ${colType}).`);
+        }
+        return col;
+    }
+    /**
+     * Build the `distinctOn` row source for groupBy (PostgreSQL only: other
+     * engines throw {@link UnsupportedFeatureError} E017):
+     *
+     * ```sql
+     * (SELECT DISTINCT ON ("c1") * FROM "table"<WHERE> ORDER BY "c1", <orderBy>) AS "table"
+     * ```
+     *
+     * The wrapper is aliased as the table name so every outer expression (group
+     * keys, aggregates, HAVING, ORDER BY) is byte-identical to the plain path.
+     * `distinctOn.orderBy` is required (it decides which row survives) and
+     * supports plain columns, {@link OrderBySpec} nulls, and JSON-path specs;
+     * JSON paths push their text[] param here, after the WHERE params.
+     */
+    buildDistinctOnSource(distinctOn, whereSql, params) {
+        if (this.dialect.name !== 'postgresql') {
+            throw new errors_js_1.UnsupportedFeatureError('DISTINCT ON row source (groupBy distinctOn)', this.dialect.name, 'groupBy({ distinctOn }) requires PostgreSQL: SELECT DISTINCT ON is not portable.');
+        }
+        if (!Array.isArray(distinctOn.columns) || distinctOn.columns.length === 0) {
+            throw new errors_js_1.ValidationError(`[turbine] groupBy distinctOn on table "${this.table}" requires a non-empty \`columns\` array.`);
+        }
+        const orderEntries = Object.entries(distinctOn.orderBy ?? {});
+        if (orderEntries.length === 0) {
+            throw new errors_js_1.ValidationError(`[turbine] groupBy distinctOn on table "${this.table}" requires \`orderBy\` to pick ONE row per ` +
+                "column combination deterministically (e.g. orderBy: { createdAt: 'desc' }).");
+        }
+        const distinctCols = distinctOn.columns.map((c) => this.q(this.toColumn(c)));
+        // DISTINCT ON expressions must lead the ORDER BY; the user's orderBy then
+        // decides which row survives per combination.
+        const orderParts = [...distinctCols];
+        for (const [key, value] of orderEntries) {
+            if ((0, filters_js_1.isJsonPathOrderBy)(value)) {
+                orderParts.push(this.buildJsonPathOrderEntry(this.table, this.tableMeta, key, value, '', params));
+                continue;
+            }
+            if ((0, filters_js_1.isVectorOrderBy)(value) || this.isRelationOrderByValue(value)) {
+                throw new errors_js_1.ValidationError(`[turbine] groupBy distinctOn.orderBy on "${key}" (table "${this.table}") supports plain columns, ` +
+                    'sort specs, and JSON-path orderings only.');
+            }
+            const col = this.resolveOrderByColumn(this.table, this.tableMeta, key);
+            const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
+            orderParts.push(`${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return (`(SELECT DISTINCT ON (${distinctCols.join(', ')}) * FROM ${this.q(this.table)}${whereSql} ` +
+            `ORDER BY ${orderParts.join(', ')}) AS ${this.q(this.table)}`);
+    }
     /**
      * Build the SQL fragments for a {@link HavingClause}.
      *
@@ -1754,8 +2093,14 @@ class QueryInterface {
      * comparison value is pushed onto the shared `params` array and referenced by
      * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
      * interpolation of user values.
+     *
+     * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
+     * exact aggregate expression a JSON-path aggregate emitted in SELECT
+     * (including its already-bound path placeholder), so HAVING on a JSON-path
+     * aggregate alias reuses the same expression instead of resolving the alias
+     * as a column.
      */
-    buildHavingClauses(having, params) {
+    buildHavingClauses(having, params, jsonAggExprs) {
         const clauses = [];
         // Maps the per-field aggregate key to its SQL function name. The set of
         // allowed keys is fixed here — any other key on a field's filter object is
@@ -1782,8 +2127,14 @@ class QueryInterface {
             }
             // toColumn validates the field against schema metadata (throws
             // ValidationError on unknown columns) and q() quotes the identifier — no
-            // unvalidated identifier ever reaches the SQL string.
-            const quotedCol = this.q(this.toColumn(key));
+            // unvalidated identifier ever reaches the SQL string. Resolution is lazy:
+            // a JSON-path aggregate alias is not a column, so it must not hit
+            // toColumn when every aggregate under it resolves via `jsonAggExprs`.
+            let quotedCol = null;
+            const columnExpr = () => {
+                quotedCol ??= this.q(this.toColumn(key));
+                return quotedCol;
+            };
             for (const [aggKey, filter] of Object.entries(value)) {
                 if (filter === undefined)
                     continue;
@@ -1792,7 +2143,7 @@ class QueryInterface {
                     throw new errors_js_1.ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${this.table}". ` +
                         `Supported: ${Object.keys(aggFnByKey).join(', ')}.`);
                 }
-                const expr = `${fn}(${quotedCol})`;
+                const expr = jsonAggExprs?.get(`${key}:${aggKey}`) ?? `${fn}(${columnExpr()})`;
                 clauses.push(...this.buildHavingNumericClauses(expr, filter, params));
             }
         }
@@ -2439,7 +2790,7 @@ class QueryInterface {
             // JSONB filter
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
@@ -2550,7 +2901,7 @@ class QueryInterface {
             // the target column is json/jsonb.
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.pgTypeForColumn(meta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, `${this.q(targetTable)}.${this.q(col)}`);
                     continue;
                 }
@@ -2620,7 +2971,8 @@ class QueryInterface {
         let pathPushed = false;
         const pushPathOnce = () => {
             if (!pathPushed) {
-                params.push(filter.path);
+                // Only reached when a path-requiring clause validated filter.path.
+                params.push(this.jsonPathParam(filter.path, filter.path));
                 pathPushed = true;
             }
         };
@@ -2672,15 +3024,20 @@ class QueryInterface {
             // then the path bound as one text[] param.
             if ((0, filters_js_1.isJsonPathOrderBy)(dir)) {
                 this.validateJsonPathOrderBy(this.table, this.tableMeta, key, dir);
-                params.push(dir.path.map(String));
+                params.push(this.jsonPathParam(dir.path));
                 continue;
             }
             // To-many relation orderBy (`{ posts: { _count } }`) uses the same count
-            // subquery as `_count` — mirror its global-filter params. To-one relation
-            // orderBy carries the target's global filter once per ordered column.
+            // subquery as `_count`: mirror its global-filter params. Pick-row
+            // ordering mirrors its full param chain (by-path / global filter /
+            // pick.where / pick.orderBy paths). To-one relation orderBy carries the
+            // target's global filter once per ordered column.
             if (this.isRelationOrderByValue(dir)) {
                 const relDef = this.tableMeta.relations[key];
-                if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
+                if (relDef && (0, filters_js_1.isRelationPickOrderBy)(dir)) {
+                    this.collectRelationPickOrderParams(key, relDef, dir, params);
+                }
+                else if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);
                 }
                 else if (relDef) {
@@ -2770,12 +3127,15 @@ class QueryInterface {
             }
             // orderBy shape (OrderBySpec nulls placement changes the SQL, so fingerprint it)
             if (opts.orderBy) {
-                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`);
+                const targetRels = this.schema.tables[relDef.to]?.relations;
+                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) {
@@ -3180,7 +3540,7 @@ class QueryInterface {
             // Handle JSONB filter operators (for json/jsonb columns)
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     const jsonClauses = this.buildJsonFilterClauses(column, value, params);
                     andClauses.push(...jsonClauses);
                     continue;
@@ -3395,7 +3755,7 @@ class QueryInterface {
             // jsonb value, silently matching nothing.
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.pgTypeForColumn(meta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     conditions.push(...this.buildJsonFilterClauses(qCol, value, params));
                     continue;
                 }
@@ -3495,7 +3855,7 @@ class QueryInterface {
     assertBindableEqualityValue(rawColumn, value, columnPgType, table) {
         if (!(0, filters_js_1.isUnmatchedPlainObject)(value))
             return;
-        if (columnPgType === 'json' || columnPgType === 'jsonb')
+        if (this.isJsonColumnType(columnPgType))
             return;
         const badKeys = Object.keys(value);
         throw new errors_js_1.ValidationError(badKeys.length === 0
@@ -3566,7 +3926,7 @@ class QueryInterface {
             // bound as a plain equality value.
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.pgTypeForColumn(targetMeta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     clauses.push(...this.buildJsonFilterClauses(qCol, value, params));
                     continue;
                 }
@@ -3639,7 +3999,7 @@ class QueryInterface {
             // JSONB filter — mirrors buildAliasWhere.
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.pgTypeForColumn(targetMeta, col);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, this.q(col));
                     continue;
                 }
@@ -3872,7 +4232,7 @@ class QueryInterface {
      * vs relation-column never collide on one cached SQL string. Captures the
      * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
      */
-    orderByEntryFingerprint(d) {
+    orderByEntryFingerprint(d, targetTable) {
         // Vector KNN ordering changes the emitted operator by metric and adds a
         // `::vector` param, so metric + direction must be part of the cache key.
         if ((0, filters_js_1.isVectorOrderBy)(d)) {
@@ -3883,13 +4243,36 @@ class QueryInterface {
         if ((0, filters_js_1.isJsonPathOrderBy)(d)) {
             return `jp(${d.direction ?? 'asc'},${d.type === 'numeric' ? 'num' : 'text'},${d.nulls ?? ''})`;
         }
+        // Pick-row relation ordering: the by-shape (column vs JSON path vs cast),
+        // direction, nulls, pick.orderBy shape, and pick.where SHAPE are all SQL
+        // text; the JSON paths and pick.where values are bound params and stay OUT
+        // of the key. `targetTable` (the relation's target, resolved by the
+        // caller) lets the pick.where fingerprint distinguish relation-filter
+        // shapes inside it: two pick.wheres that differ only in shape must never
+        // share one cached SQL string.
+        if ((0, filters_js_1.isRelationPickOrderBy)(d)) {
+            const by = typeof d.by === 'string'
+                ? `col=${JSON.stringify(d.by)}`
+                : `jp(${JSON.stringify(d.by?.field)},${d.by?.type === 'numeric' ? 'num' : 'text'})`;
+            const pickOrder = Object.entries(d.pick?.orderBy ?? {})
+                .map(([k, v]) => `${k}:${this.orderByEntryFingerprint(v)}`)
+                .join(',');
+            const pickWhere = d.pick?.where
+                ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
+                : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+        }
         if ((0, filters_js_1.isOrderBySpec)(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
         if (d && typeof d === 'object') {
             // Relation ordering (`{ _count: 'desc' }` or `{ name: 'asc' }`).
+            // INSERTION order, never sorted: the compile side (buildRelationOrderBy)
+            // emits one ORDER BY term per entry in Object.entries order, so entry
+            // order is SQL-shaping precedence. A sorted fingerprint made
+            // `{ name: 'asc', email: 'desc' }` and the swapped literal share one
+            // cached SQL string — silently mis-ordered results on a warm cache.
             return `rel(${Object.entries(d)
                 .map(([k, v]) => `${k}=${this.orderByEntryFingerprint(v)}`)
-                .sort()
                 .join(',')})`;
         }
         return String(d);
@@ -4007,7 +4390,7 @@ class QueryInterface {
                 `of keys/indexes (e.g. { path: ['weight'], direction: 'asc' }).`);
         }
         const colType = this.pgTypeForColumn(meta, col);
-        if (colType !== 'json' && colType !== 'jsonb') {
+        if (!this.isJsonColumnType(colType)) {
             throw new errors_js_1.ValidationError(`[turbine] JSON-path orderBy on "${field}": column "${col}" on table "${table}" is not a JSON column ` +
                 `(actual type: ${colType}).`);
         }
@@ -4027,7 +4410,7 @@ class QueryInterface {
         if (!params) {
             throw new errors_js_1.ValidationError(`[turbine] JSON-path ordering on "${field}" is not supported in this orderBy context.`);
         }
-        params.push(spec.path.map(String));
+        params.push(this.jsonPathParam(spec.path));
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
@@ -4055,12 +4438,21 @@ class QueryInterface {
             throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
                 `Available: ${Object.keys(ownerMeta.relations).join(', ')}`);
         }
+        // Pick-row ordering (`{ pick, by }`): order by a value from ONE related
+        // row: a correlated scalar subquery with its own ORDER BY … LIMIT 1.
+        // Top-level findMany only (`ctx` present means we are inside a relation
+        // subquery's orderBy) and hasMany only: validatePickOrderBy throws the
+        // scope errors, shared with the cache-hit collect mirror.
+        if ((0, filters_js_1.isRelationPickOrderBy)(value)) {
+            this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+        }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
             const keys = Object.keys(value);
             if (keys.length !== 1 || keys[0] !== '_count') {
                 throw new errors_js_1.ValidationError(`[turbine] orderBy on to-many relation "${relName}" only supports "_count" ` +
-                    `(got: ${keys.join(', ') || '(empty)'}).`);
+                    `or a pick-row ordering ({ pick, by }) (got: ${keys.join(', ') || '(empty)'}).`);
             }
             const { dir } = (0, filters_js_1.normalizeOrderBy)(value._count);
             return `${this.buildRelationCountExpr(relDef, parentRef, alias, params)} ${dir}`;
@@ -4101,6 +4493,145 @@ class QueryInterface {
         })
             .join(', ');
     }
+    /**
+     * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
+     * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit
+     * param-collect mirror ({@link collectRelationPickOrderParams}) so both
+     * always throw identically:
+     *
+     *  - `nested` (inside a relation subquery's orderBy or a pick.orderBy):
+     *    top-level findMany only in this release (E003),
+     *  - manyToMany: not supported (E003 naming the limitation),
+     *  - to-one: order by the target column directly instead (E003),
+     *  - `pick.orderBy` is REQUIRED (deterministic row choice),
+     *  - `by` must be a target column name or a `{ field, path }` JSON-path spec.
+     */
+    pickOrderNestedError(relName) {
+        return new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level ` +
+            'findMany orderBy: nested `with` orderBy does not support it.');
+    }
+    validatePickOrderBy(relName, relDef, spec, nested) {
+        if (nested) {
+            throw this.pickOrderNestedError(relName);
+        }
+        if (relDef.type === 'manyToMany') {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering is not supported on manyToMany relation "${relName}": ` +
+                'hasMany relations only.');
+        }
+        if (relDef.type !== 'hasMany') {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering is only for to-many (hasMany) relations; "${relName}" is ${relDef.type}. ` +
+                `Order by the target column directly instead ({ ${relName}: { <column>: 'asc' } }).`);
+        }
+        const pickOrder = spec.pick?.orderBy;
+        if (typeof spec.pick !== 'object' ||
+            spec.pick === null ||
+            typeof pickOrder !== 'object' ||
+            pickOrder === null ||
+            Object.keys(pickOrder).length === 0) {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`pick.orderBy\` to choose ONE ` +
+                "related row deterministically (e.g. pick: { orderBy: { createdAt: 'desc' } }).");
+        }
+        const by = spec.by;
+        const validJsonBy = typeof by === 'object' && by !== null && typeof by.field === 'string' && Array.isArray(by.path);
+        if (typeof by !== 'string' && !validJsonBy) {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
+                "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
+        }
+    }
+    /**
+     * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
+     * that picks ONE related row (`ORDER BY <pick.orderBy> LIMIT 1`, optionally
+     * filtered by `pick.where` and the target's global filter) and surfaces one
+     * value from it (a plain target column or a JSON-path extraction) as the
+     * parent ORDER BY key:
+     *
+     * ```sql
+     * (SELECT ord0."data" #>> $1::text[] FROM "versions" ord0
+     *   WHERE ord0."instance_id" = "instances"."id" AND ord0."is_current" = $2
+     *   ORDER BY ord0."created_at" DESC LIMIT 1) ASC NULLS LAST
+     * ```
+     *
+     * Param-push order (mirrored EXACTLY by
+     * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
+     * target global filter → `pick.where` → `pick.orderBy` JSON paths.
+     */
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+        if (!params) {
+            throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level findMany orderBy.`);
+        }
+        const targetMeta = this.schema.tables[relDef.to];
+        if (!targetMeta)
+            throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        // The value surfaced from the picked row (SELECT list: its param binds first).
+        let byExpr;
+        if (typeof spec.by === 'string') {
+            const col = this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
+            byExpr = `${alias}.${this.q(col)}`;
+        }
+        else {
+            const col = this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, {
+                path: spec.by.path,
+            });
+            params.push(this.jsonPathParam(spec.by.path));
+            const extract = this.dialect.buildJsonPathExtract(`${alias}.${this.q(col)}`, this.p(params.length));
+            byExpr = spec.by.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
+        }
+        // Correlation to the parent row, then the target's global filter (a
+        // soft-deleted / other-tenant row must never be picked: matches the
+        // `with` subquery and to-one relation-orderBy semantics), then pick.where.
+        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+        if (gf)
+            where += ` AND ${gf}`;
+        if (spec.pick.where) {
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            if (pickWhere)
+                where += ` AND ${pickWhere}`;
+        }
+        // pick.orderBy: same surface as a relation `with` orderBy on the target
+        // (plain columns, OrderBySpec nulls, JSON-path specs); a nested pick in
+        // here routes back through buildRelationOrderBy with ctx set and throws
+        // the top-level-only E003.
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, alias, Object.entries(spec.pick.orderBy), params);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows make the correlated subquery
+        // yield NULL. Without a nulls clause, Postgres DESC defaults to NULLS
+        // FIRST — every childless parent would top a "highest first" sort. Default
+        // to NULLS LAST in BOTH directions (deterministic across engines: SQLite's
+        // NULL-is-smallest default diverges from Postgres) unless the caller set
+        // `nulls` explicitly; the grammar gate matches nullsSuffix (PG + SQLite).
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
+     * validation (a warmed cache can never skip it), then pushes in the same
+     * order: `by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths.
+     */
+    collectRelationPickOrderParams(relName, relDef, spec, params) {
+        this.validatePickOrderBy(relName, relDef, spec, false);
+        const targetMeta = this.schema.tables[relDef.to];
+        if (!targetMeta)
+            throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        if (typeof spec.by === 'string') {
+            this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
+        }
+        else {
+            this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, { path: spec.by.path });
+            params.push(this.jsonPathParam(spec.by.path));
+        }
+        this.collectTargetGlobalFilterAlias(relDef.to, params);
+        if (spec.pick.where) {
+            this.collectAliasWhereParams(relDef.to, targetMeta, spec.pick.where, params);
+        }
+        this.collectRelationOrderParams(relDef.to, targetMeta, Object.entries(spec.pick.orderBy), params);
+    }
     /**
      * Compile the ORDER BY terms of a relation `with` clause against the
      * relation's table alias. One unified path for every relation shape
@@ -4151,10 +4682,15 @@ class QueryInterface {
             }
             if ((0, filters_js_1.isJsonPathOrderBy)(dirValue)) {
                 this.validateJsonPathOrderBy(targetTable, targetMeta, key, dirValue);
-                params.push(dirValue.path.map(String));
+                params.push(this.jsonPathParam(dirValue.path));
                 continue;
             }
             if (this.isRelationOrderByValue(dirValue)) {
+                // Pick-row ordering is top-level-only: the build path throws the same
+                // E003 (buildRelationOrderBy with ctx set), so the mirror must too.
+                if ((0, filters_js_1.isRelationPickOrderBy)(dirValue)) {
+                    throw this.pickOrderNestedError(key);
+                }
                 const relDef = targetMeta.relations[key];
                 if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);
@@ -5113,6 +5649,16 @@ class QueryInterface {
      * Used to detect JSONB/array columns for specialized operators.
      * Uses pre-computed Map for O(1) lookup instead of linear scan.
      */
+    /**
+     * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
+     * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
+     * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
+     * — build and collect sides alike, keeping the SQL-cache lockstep.
+     */
+    isJsonColumnType(colType) {
+        const t = colType.toLowerCase();
+        return t === 'json' || t === 'jsonb';
+    }
     getColumnPgType(column) {
         return this.columnPgTypeMap.get(column) ?? 'text';
     }
@@ -5182,7 +5728,8 @@ class QueryInterface {
         let pathParamIdx = null;
         const pathExtract = () => {
             if (pathParamIdx === null) {
-                params.push(filter.path);
+                // Only reached when a path-requiring clause validated filter.path.
+                params.push(this.jsonPathParam(filter.path, filter.path));
                 pathParamIdx = params.length;
             }
             return this.dialect.buildJsonPathExtract(column, this.p(pathParamIdx));
@@ -5218,6 +5765,24 @@ class QueryInterface {
         }
         return clauses;
     }
+    /**
+     * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
+     * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+     * caller has a specific native binding, e.g. JsonFilter's raw path array).
+     * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
+     * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
+     * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
+     * params) and fail at runtime with the engine's bad-JSON-path error. The
+     * encoded path stays a bound parameter — never spliced into SQL text — so
+     * the build/collect param mirrors stay in lockstep and injection-safe.
+     */
+    jsonPathParam(path, nativeForm) {
+        if (this.dialect.jsonPathSupport === 'native')
+            return nativeForm ?? path.map(String);
+        return `$${path
+            .map((seg) => typeof seg === 'number' || /^\d+$/.test(String(seg)) ? `[${seg}]` : `."${String(seg).replace(/"/g, '\\"')}"`)
+            .join('')}`;
+    }
     /**
      * Cast an extracted JSON path text value to a numeric type for range
      * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to