turbine-orm 0.30.0 → 0.32.0

package/dist/query/builder.js

@@ -15,8 +15,8 @@ import { CircularRelationError, NotFoundError, OptimisticLockError, RelationErro
 import { missingIndexForRelation } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
-import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isJsonFilter, isOrderBySpec, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, JSON_RANGE_OPERATORS, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
+import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
+import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isColumnRef, isJsonFilter, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isVectorOrderBy, isWhereOperator, JSON_RANGE_OPERATORS, normalizeOrderBy, sortedEntries, sortedKeys, UPDATE_OPERATOR_KEYS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
 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();
@@ -291,6 +291,10 @@ export 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.
+        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
@@ -516,6 +520,8 @@ export class QueryInterface {
      */
     async runFindUniqueBatched(args) {
         const withClause = args.with;
+        // Same scope-rule parity as runFindManyBatched: reject before querying.
+        rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
         const proj = includeKeysForBatching(args.select, args.omit, needed);
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
@@ -702,6 +708,21 @@ export 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 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
@@ -715,7 +736,7 @@ export 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
@@ -1576,67 +1597,124 @@ export 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 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 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 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 ')}`;
             }
@@ -1652,9 +1730,11 @@ export 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) {
@@ -1669,29 +1749,27 @@ export 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] ?? 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] ?? 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] ?? 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] ?? 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] ?? snakeToCamel(col);
-                        maxObj[field] = rawValue;
+                        const j = jsonAgg(rawKey);
+                        maxObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
                         hasMaxs = true;
                     }
                 }
@@ -1708,6 +1786,75 @@ export 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 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 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 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 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 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 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 (isJsonPathOrderBy(value)) {
+                orderParts.push(this.buildJsonPathOrderEntry(this.table, this.tableMeta, key, value, '', params));
+                continue;
+            }
+            if (isVectorOrderBy(value) || this.isRelationOrderByValue(value)) {
+                throw new 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 } = 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}.
      *
@@ -1718,8 +1865,14 @@ export 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
@@ -1746,8 +1899,14 @@ export 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;
@@ -1756,7 +1915,7 @@ export class QueryInterface {
                     throw new 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));
             }
         }
@@ -2403,7 +2562,7 @@ export class QueryInterface {
             // JSONB filter
             if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
                 const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
+                if (this.isJsonColumnType(colType)) {
                     this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
@@ -2423,7 +2582,11 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(rawColumn, value, params);
+                this.collectOperatorParams(rawColumn, value, params, {
+                    meta: this.tableMeta,
+                    table: this.table,
+                    prefix: '',
+                });
                 continue;
             }
             // Plain equality — same strict validation as the build path, so a
@@ -2510,7 +2673,7 @@ export class QueryInterface {
             // the target column is json/jsonb.
             if (typeof value === 'object' && !Array.isArray(value) && 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;
                 }
@@ -2524,28 +2687,40 @@ export class QueryInterface {
                 }
             }
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(col, value, params);
+                this.collectOperatorParams(col, value, params, { meta, table: targetTable, prefix: '' });
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(column, op, params) {
-        if (op.equals !== undefined && op.equals !== null) {
+    /**
+     * Collect params from operator clauses. Mirrors buildOperatorClauses:
+     * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
+     * but they re-run the same validation (unknown ref / insensitive mode) so a
+     * warmed cache can never skip a check the build path enforces.
+     */
+    collectOperatorParams(column, op, params, refCtx) {
+        const skipRef = (v) => {
+            if (!isColumnRef(v))
+                return false;
+            if (refCtx)
+                this.resolveColumnRef(v, refCtx, op.mode);
+            return true;
+        };
+        if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
             assertBindableEqualsOperand(op.equals, `"${column}"`);
             params.push(op.equals);
         }
-        if (op.gt !== undefined)
+        if (op.gt !== undefined && !skipRef(op.gt))
             params.push(op.gt);
-        if (op.gte !== undefined)
+        if (op.gte !== undefined && !skipRef(op.gte))
             params.push(op.gte);
-        if (op.lt !== undefined)
+        if (op.lt !== undefined && !skipRef(op.lt))
             params.push(op.lt);
-        if (op.lte !== undefined)
+        if (op.lte !== undefined && !skipRef(op.lte))
             params.push(op.lte);
-        if (op.not !== undefined && op.not !== null)
+        if (op.not !== undefined && op.not !== null && !skipRef(op.not))
             params.push(op.not);
         if (op.in !== undefined)
             params.push(this.inParam(op.in));
@@ -2568,7 +2743,8 @@ export 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;
             }
         };
@@ -2601,10 +2777,10 @@ export class QueryInterface {
         // isEmpty has no params (IS NULL / IS NOT NULL)
     }
     /**
-     * Collect params for an orderBy clause. Only vector KNN ordering pushes a
-     * param (the `$n::vector` query vector); plain direction ordering is
-     * parameterless. Mirrors buildOrderBy's push order exactly so the cached-SQL
-     * param re-collection stays in lockstep.
+     * Collect params for an orderBy clause. Vector KNN ordering pushes the
+     * `$n::vector` query vector and JSON-path ordering pushes its text[] path;
+     * plain direction ordering is parameterless. Mirrors buildOrderBy's push
+     * order exactly so the cached-SQL param re-collection stays in lockstep.
      */
     collectOrderByParams(orderBy, params) {
         for (const [key, dir] of Object.entries(orderBy)) {
@@ -2616,12 +2792,24 @@ export class QueryInterface {
                 this.pushVectorParam(key, rawColumn, dir.distance.to, params);
                 continue;
             }
+            // JSON-path ordering: mirrors buildJsonPathOrderEntry: same validation,
+            // then the path bound as one text[] param.
+            if (isJsonPathOrderBy(dir)) {
+                this.validateJsonPathOrderBy(this.table, this.tableMeta, key, dir);
+                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 && isRelationPickOrderBy(dir)) {
+                    this.collectRelationPickOrderParams(key, relDef, dir, params);
+                }
+                else if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                     this.collectRelationCountParams(relDef, params);
                 }
                 else if (relDef) {
@@ -2711,7 +2899,8 @@ export 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
@@ -2762,9 +2951,20 @@ export class QueryInterface {
         const targetMeta = this.schema.tables[targetTable];
         if (!targetMeta)
             return;
+        // A dialect that owns the whole subquery (buildRelationSubquery override,
+        // SQL Server FOR JSON) compiles orderBy through its OWN paging clause -
+        // plain directions only, no order params: so the native order-param
+        // mirrors below must stay off for it (its documented contract remains
+        // where → limit → nested).
+        const nativeOrderPath = !this.dialect.buildRelationSubquery;
         // manyToMany param order mirrors buildManyToManySubquery:
-        //   where params → limit param → nested-with params (always, both paths).
+        //   orderBy params → where params → limit param → nested-with params
+        //   (always, both paths).
         if (relDef.type === 'manyToMany') {
+            const m2mOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+            if (nativeOrderPath && m2mOrderEntries.length > 0) {
+                this.collectRelationOrderParams(targetTable, targetMeta, m2mOrderEntries, params);
+            }
             if (spec.where) {
                 this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
@@ -2783,7 +2983,8 @@ export class QueryInterface {
             return;
         }
         // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
-        const hasOrder = spec.orderBy ? Object.values(spec.orderBy).some((dir) => dir !== undefined) : false;
+        const relOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const hasOrder = relOrderEntries.length > 0;
         const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
@@ -2794,6 +2995,12 @@ export class QueryInterface {
                 this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
             }
         }
+        // orderBy params (JSON paths / relation-order global filters): mirrors
+        // buildRelationSubquery, which builds its ORDER BY terms BEFORE compiling
+        // spec.where (both wrapped and non-wrapped paths).
+        if (nativeOrderPath && hasOrder) {
+            this.collectRelationOrderParams(targetTable, targetMeta, relOrderEntries, params);
+        }
         // where params — mirrors buildAliasWhere push order
         if (spec.where) {
             this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
@@ -3103,7 +3310,7 @@ export class QueryInterface {
             // Handle JSONB filter operators (for json/jsonb columns)
             if (typeof value === 'object' && !Array.isArray(value) && 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;
@@ -3144,7 +3351,11 @@ export class QueryInterface {
             }
             // Handle operator objects
             if (isWhereOperator(value)) {
-                const opClauses = this.buildOperatorClauses(column, value, params);
+                const opClauses = this.buildOperatorClauses(column, value, params, {
+                    meta: this.tableMeta,
+                    table: this.table,
+                    prefix: '',
+                });
                 andClauses.push(...opClauses);
                 continue;
             }
@@ -3314,7 +3525,7 @@ export class QueryInterface {
             // jsonb value, silently matching nothing.
             if (typeof value === 'object' && !Array.isArray(value) && 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;
                 }
@@ -3338,7 +3549,11 @@ export class QueryInterface {
                 }
             }
             if (isWhereOperator(value)) {
-                const opClauses = this.buildOperatorClauses(qCol, value, params);
+                const opClauses = this.buildOperatorClauses(qCol, value, params, {
+                    meta,
+                    table: targetTable,
+                    prefix: `${qt}.`,
+                });
                 conditions.push(...opClauses);
                 continue;
             }
@@ -3410,7 +3625,7 @@ export class QueryInterface {
     assertBindableEqualityValue(rawColumn, value, columnPgType, table) {
         if (!isUnmatchedPlainObject(value))
             return;
-        if (columnPgType === 'json' || columnPgType === 'jsonb')
+        if (this.isJsonColumnType(columnPgType))
             return;
         const badKeys = Object.keys(value);
         throw new ValidationError(badKeys.length === 0
@@ -3481,7 +3696,7 @@ export class QueryInterface {
             // bound as a plain equality value.
             if (typeof value === 'object' && !Array.isArray(value) && 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;
                 }
@@ -3505,7 +3720,11 @@ export class QueryInterface {
                 }
             }
             if (isWhereOperator(value)) {
-                clauses.push(...this.buildOperatorClauses(qCol, value, params));
+                clauses.push(...this.buildOperatorClauses(qCol, value, params, {
+                    meta: targetMeta,
+                    table: targetTable,
+                    prefix: `${alias}.`,
+                }));
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
@@ -3550,7 +3769,7 @@ export class QueryInterface {
             // JSONB filter — mirrors buildAliasWhere.
             if (typeof value === 'object' && !Array.isArray(value) && 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;
                 }
@@ -3564,7 +3783,7 @@ export class QueryInterface {
                 }
             }
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(col, value, params);
+                this.collectOperatorParams(col, value, params, { meta: targetMeta, table: targetTable, prefix: '' });
                 continue;
             }
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
@@ -3641,16 +3860,55 @@ export class QueryInterface {
         }
         return parts.join('&');
     }
+    /**
+     * Validate a `{ col }` column reference against its table and return the
+     * resolved snake_case column name. Shared by the SQL-build path
+     * ({@link buildOperatorClauses}) and the cache-hit param-collect path
+     * (`collectOperatorParams`) so both always throw identically: a warmed
+     * cache can never skip the check.
+     */
+    resolveColumnRef(ref, ctx, mode) {
+        if (mode === 'insensitive') {
+            throw new ValidationError(`[turbine] mode: 'insensitive' cannot be combined with a column reference ({ col: "${ref.col}" }). ` +
+                `Case-insensitive column-to-column comparison is not supported: use client.sql\`...\` ` +
+                `for lower(a) = lower(b).`);
+        }
+        const col = ctx.meta.columnMap[ref.col] ?? camelToSnake(ref.col);
+        if (!ctx.meta.allColumns.includes(col)) {
+            throw new ValidationError(`[turbine] Unknown field "${ref.col}" referenced by { col } in where on table "${ctx.table}". ` +
+                `Known fields: ${Object.keys(ctx.meta.columnMap).join(', ') || '(none)'}.`);
+        }
+        return col;
+    }
+    /**
+     * Compile a `{ col }` reference to its quoted, prefix-matched SQL identifier.
+     * NO param is bound: the referenced column is part of the SQL text (and of
+     * the where fingerprint, see {@link fingerprintOperatorShape}).
+     */
+    columnRefSql(ref, ctx, mode) {
+        if (!ctx) {
+            throw new ValidationError(`[turbine] Column reference { col: "${ref.col}" } is not supported in this filter context.`);
+        }
+        return `${ctx.prefix}${this.q(this.resolveColumnRef(ref, ctx, mode))}`;
+    }
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.
+     *
+     * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
+     * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+     * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
+     * pushing nothing and the referenced name lives in the fingerprint.
      */
-    buildOperatorClauses(column, op, params) {
+    buildOperatorClauses(column, op, params, refCtx) {
         const clauses = [];
         if (op.equals !== undefined) {
             if (op.equals === null) {
                 clauses.push(`${column} IS NULL`);
             }
+            else if (isColumnRef(op.equals)) {
+                clauses.push(`${column} = ${this.columnRefSql(op.equals, refCtx, op.mode)}`);
+            }
             else {
                 assertBindableEqualsOperand(op.equals, column);
                 params.push(op.equals);
@@ -3658,25 +3916,48 @@ export class QueryInterface {
             }
         }
         if (op.gt !== undefined) {
-            params.push(op.gt);
-            clauses.push(`${column} > ${this.p(params.length)}`);
+            if (isColumnRef(op.gt)) {
+                clauses.push(`${column} > ${this.columnRefSql(op.gt, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.gt);
+                clauses.push(`${column} > ${this.p(params.length)}`);
+            }
         }
         if (op.gte !== undefined) {
-            params.push(op.gte);
-            clauses.push(`${column} >= ${this.p(params.length)}`);
+            if (isColumnRef(op.gte)) {
+                clauses.push(`${column} >= ${this.columnRefSql(op.gte, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.gte);
+                clauses.push(`${column} >= ${this.p(params.length)}`);
+            }
         }
         if (op.lt !== undefined) {
-            params.push(op.lt);
-            clauses.push(`${column} < ${this.p(params.length)}`);
+            if (isColumnRef(op.lt)) {
+                clauses.push(`${column} < ${this.columnRefSql(op.lt, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.lt);
+                clauses.push(`${column} < ${this.p(params.length)}`);
+            }
         }
         if (op.lte !== undefined) {
-            params.push(op.lte);
-            clauses.push(`${column} <= ${this.p(params.length)}`);
+            if (isColumnRef(op.lte)) {
+                clauses.push(`${column} <= ${this.columnRefSql(op.lte, refCtx, op.mode)}`);
+            }
+            else {
+                params.push(op.lte);
+                clauses.push(`${column} <= ${this.p(params.length)}`);
+            }
         }
         if (op.not !== undefined) {
             if (op.not === null) {
                 clauses.push(`${column} IS NOT NULL`);
             }
+            else if (isColumnRef(op.not)) {
+                clauses.push(`${column} != ${this.columnRefSql(op.not, refCtx, op.mode)}`);
+            }
             else {
                 params.push(op.not);
                 clauses.push(`${column} != ${this.p(params.length)}`);
@@ -3721,19 +4002,47 @@ export 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 (isVectorOrderBy(d)) {
             return `vec(${d.distance.metric},${d.distance.direction ?? 'asc'})`;
         }
+        // JSON-path ordering: direction, cast kind, and nulls placement change the
+        // SQL text; the path itself is a bound param and stays OUT of the key.
+        if (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 (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 (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);
@@ -3772,6 +4081,11 @@ export class QueryInterface {
                 const safeDir = value.distance.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${this.q(rawColumn)} ${operator} ${placeholder} ${safeDir}`;
             }
+            // JSON-path ordering: { path: [...], direction?, type?, nulls? } on a
+            // json/jsonb column of THIS table. Path is bound as one text[] param.
+            if (isJsonPathOrderBy(value)) {
+                return this.buildJsonPathOrderEntry(this.table, this.tableMeta, key, value, '', params);
+            }
             // Relation ordering: an object value that is not a vector or OrderBySpec,
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
@@ -3798,6 +4112,7 @@ export class QueryInterface {
             value !== null &&
             !Array.isArray(value) &&
             !isVectorOrderBy(value) &&
+            !isJsonPathOrderBy(value) &&
             !isOrderBySpec(value));
     }
     /**
@@ -3814,6 +4129,63 @@ export class QueryInterface {
         }
         return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
     }
+    /**
+     * Resolve an orderBy key to its snake_case column via the table's columnMap
+     * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
+     * where path uses. Shared by top-level JSON-path ordering and every nested
+     * relation orderBy path so nested orderBy accepts exactly what top-level
+     * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
+     * camelCase-named DB columns like "sortOrder").
+     */
+    resolveOrderByColumn(table, meta, key) {
+        const col = meta.columnMap[key] ?? camelToSnake(key);
+        if (!meta.allColumns.includes(col)) {
+            throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${table}". ` +
+                `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+        }
+        return col;
+    }
+    /**
+     * Validate a {@link JsonPathOrderBy} entry: column must exist AND be
+     * json/jsonb, path must be a non-empty array of keys/indexes: and return
+     * the resolved column. Shared by the SQL-build path
+     * ({@link buildJsonPathOrderEntry}) and the cache-hit param-collect mirrors
+     * so both always throw identically.
+     */
+    validateJsonPathOrderBy(table, meta, field, spec) {
+        const col = this.resolveOrderByColumn(table, meta, field);
+        if (spec.path.length === 0 ||
+            spec.path.some((el) => typeof el !== 'string' && !(typeof el === 'number' && Number.isFinite(el)))) {
+            throw new ValidationError(`[turbine] JSON-path orderBy on "${field}" (table "${table}") requires a non-empty \`path\` array ` +
+                `of keys/indexes (e.g. { path: ['weight'], direction: 'asc' }).`);
+        }
+        const colType = this.pgTypeForColumn(meta, col);
+        if (!this.isJsonColumnType(colType)) {
+            throw new ValidationError(`[turbine] JSON-path orderBy on "${field}": column "${col}" on table "${table}" is not a JSON column ` +
+                `(actual type: ${colType}).`);
+        }
+        return col;
+    }
+    /**
+     * Compile one {@link JsonPathOrderBy} entry:
+     * `("col" #>> $n::text[])::numeric ASC`: the numeric cast only with
+     * `type: 'numeric'` (default is text comparison), the extraction routed
+     * through the dialect's JSON hook exactly like the JSON where-filters, the
+     * path bound as ONE text[] param (mirrored by the order-param collectors).
+     * `prefix` scopes the column (`''` top-level, `t0.` inside a relation
+     * subquery).
+     */
+    buildJsonPathOrderEntry(table, meta, field, spec, prefix, params) {
+        const col = this.validateJsonPathOrderBy(table, meta, field, spec);
+        if (!params) {
+            throw new ValidationError(`[turbine] JSON-path ordering on "${field}" is not supported in this orderBy context.`);
+        }
+        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';
+        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+    }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
      * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
@@ -3822,29 +4194,45 @@ export class QueryInterface {
      *
      * Validation: relation must exist (E005); to-many only allows `_count`, and
      * to-one only allows real target columns (E003).
+     *
+     * `ctx` generalizes the term beyond the root table: inside a relation
+     * subquery's orderBy the relations live on the TARGET table's metadata and
+     * the correlation parent is the relation's alias, not `this.table`.
      */
-    buildRelationOrderBy(relName, value, alias, params) {
-        const relDef = this.tableMeta.relations[relName];
+    buildRelationOrderBy(relName, value, alias, params, ctx) {
+        const ownerMeta = ctx?.meta ?? this.tableMeta;
+        const ownerTable = ctx?.table ?? this.table;
+        const parentRef = ctx?.parentRef ?? this.table;
+        const relDef = ownerMeta.relations[relName];
         if (!relDef) {
-            throw new RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${this.table}". ` +
-                `Available: ${Object.keys(this.tableMeta.relations).join(', ')}`);
+            throw new 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 (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 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 } = normalizeOrderBy(value._count);
-            return `${this.buildRelationCountExpr(relDef, this.table, alias, params)} ${dir}`;
+            return `${this.buildRelationCountExpr(relDef, parentRef, alias, params)} ${dir}`;
         }
         // To-one: each entry orders by a correlated scalar subquery on a target column.
         const targetMeta = this.schema.tables[relDef.to];
         if (!targetMeta)
             throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
         const qTarget = this.q(relDef.to);
-        const qParent = this.q(this.table);
+        const qParent = this.q(parentRef);
         // belongsTo: alias.referenceKey = parent.foreignKey; hasOne: reversed.
         const correlation = relDef.type === 'belongsTo'
             ? this.dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey)
@@ -3855,7 +4243,9 @@ export class QueryInterface {
         }
         return entries
             .map(([col, dirValue]) => {
-            const snakeCol = camelToSnake(col);
+            // columnMap-first resolution (camelToSnake fallback): mirrors the
+            // scalar orderBy path so camelCase-named DB columns resolve here too.
+            const snakeCol = targetMeta.columnMap[col] ?? camelToSnake(col);
             if (!targetMeta.allColumns.includes(snakeCol)) {
                 throw new ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").`);
             }
@@ -3873,6 +4263,218 @@ export 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 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 ValidationError(`[turbine] Pick-row ordering is not supported on manyToMany relation "${relName}": ` +
+                'hasMany relations only.');
+        }
+        if (relDef.type !== 'hasMany') {
+            throw new 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 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 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 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 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 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
+     * (hasMany / manyToMany / belongsTo / hasOne) supporting exactly what the
+     * top-level orderBy accepts at this level:
+     *
+     *  - scalar columns via columnMap resolution (camelToSnake fallback) with
+     *    {@link OrderBySpec} nulls placement,
+     *  - {@link JsonPathOrderBy} entries (path bound as one text[] param),
+     *  - relation ordering on the TARGET's relations (`_count` for to-many, a
+     *    target column for to-one), correlated to the relation alias,
+     *  - vector KNN ordering stays top-level-only (E003, same as before).
+     *
+     * Param pushes (JSON paths, relation-order global filters) MUST be mirrored,
+     * in the same order, by {@link collectRelationOrderParams}.
+     */
+    buildRelationOrderClause(targetTable, targetMeta, alias, orderEntries, params) {
+        let relOrdCounter = 0;
+        const orders = orderEntries
+            .map(([key, dirValue]) => {
+            if (isVectorOrderBy(dirValue)) {
+                throw new ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if (isJsonPathOrderBy(dirValue)) {
+                return this.buildJsonPathOrderEntry(targetTable, targetMeta, key, dirValue, `${alias}.`, params);
+            }
+            if (this.isRelationOrderByValue(dirValue)) {
+                return this.buildRelationOrderBy(key, dirValue, `${alias}ord${relOrdCounter++}`, params, { meta: targetMeta, table: targetTable, parentRef: alias });
+            }
+            const col = this.resolveOrderByColumn(targetTable, targetMeta, key);
+            const { dir, nulls } = normalizeOrderBy(dirValue);
+            return `${alias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
+        })
+            .join(', ');
+        return ` ORDER BY ${orders}`;
+    }
+    /**
+     * Param-collect mirror of {@link buildRelationOrderClause}: JSON-path
+     * entries push their path (one text[] param each); relation-order entries
+     * mirror {@link collectOrderByParams}' relation branch (count / to-one
+     * global-filter params); scalar entries push nothing but re-run the same
+     * column validation so a warmed cache can never skip it.
+     */
+    collectRelationOrderParams(targetTable, targetMeta, orderEntries, params) {
+        for (const [key, dirValue] of orderEntries) {
+            if (isVectorOrderBy(dirValue)) {
+                throw new ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if (isJsonPathOrderBy(dirValue)) {
+                this.validateJsonPathOrderBy(targetTable, targetMeta, key, dirValue);
+                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 (isRelationPickOrderBy(dirValue)) {
+                    throw this.pickOrderNestedError(key);
+                }
+                const relDef = targetMeta.relations[key];
+                if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
+                    this.collectRelationCountParams(relDef, params);
+                }
+                else if (relDef) {
+                    for (const _col of Object.keys(dirValue)) {
+                        this.collectTargetGlobalFilterAlias(relDef.to, params);
+                    }
+                }
+                continue;
+            }
+            this.resolveOrderByColumn(targetTable, targetMeta, key);
+        }
+    }
     /**
      * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
      * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
@@ -4592,20 +5194,13 @@ export class QueryInterface {
         // Quote parent ref — can be a table name or auto-generated alias
         const qParent = this.q(parentRef);
         const qTarget = this.q(targetTable);
-        // Build ORDER BY for json_agg
+        // Build ORDER BY for json_agg: unified with the top-level orderBy surface
+        // (columnMap resolution, OrderBySpec nulls, JSON-path, relation ordering).
+        // Param pushes here land BEFORE the spec.where params, mirrored by
+        // collectRelationSubqueryParams.
         let orderClause = '';
         if (relOrderEntries.length > 0) {
-            const orders = relOrderEntries
-                .map(([k, dirValue]) => {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = normalizeOrderBy(dirValue);
-                return `${alias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
-            })
-                .join(', ');
-            orderClause = ` ORDER BY ${orders}`;
+            orderClause = this.buildRelationOrderClause(targetTable, targetMeta, alias, relOrderEntries, params);
         }
         // Build WHERE — correlate to parent via parentRef (alias or table name).
         // For hasMany/hasOne: TARGET has the FK (RelationDef.foreignKey is always
@@ -4679,8 +5274,10 @@ export class QueryInterface {
             const inlineOrder = this.dialect.aggSupportsInlineOrderBy ? orderClause.trim() || undefined : undefined;
             return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, inlineOrder)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
         }
-        // belongsTo / hasOne — return single object
-        return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause} LIMIT 1`;
+        // belongsTo / hasOne: return single object. An orderBy picks WHICH row
+        // the LIMIT 1 keeps (deterministic hasOne over a non-unique FK): matching
+        // the batched strategy, which orders its flat follow-up and takes bucket[0].
+        return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause}${orderClause} LIMIT 1`;
     }
     /**
      * Build the json_agg subquery for a `manyToMany` relation, JOINing the target
@@ -4738,22 +5335,15 @@ export class QueryInterface {
         let whereClause = sourceKeys
             .map((jcol, i) => `${jalias}.${this.q(jcol)} = ${qParent}.${this.q(refKeys[i])}`)
             .join(' AND ');
-        // ORDER BY on the target rows. `orderBy: {}` (no defined entries) is
-        // treated as absent — it must not render a dangling `ORDER BY `.
+        // ORDER BY on the target rows: unified with the top-level orderBy surface
+        // (columnMap resolution, OrderBySpec nulls, JSON-path, relation ordering).
+        // `orderBy: {}` (no defined entries) is treated as absent: it must not
+        // render a dangling `ORDER BY `. Param pushes here land BEFORE the
+        // spec.where params, mirrored by collectRelationSubqueryParams' m2m branch.
         const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         let orderClause = '';
         if (relOrderEntries.length > 0) {
-            const orders = relOrderEntries
-                .map(([k, dirValue]) => {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = normalizeOrderBy(dirValue);
-                return `${talias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
-            })
-                .join(', ');
-            orderClause = ` ORDER BY ${orders}`;
+            orderClause = this.buildRelationOrderClause(targetTable, targetMeta, talias, relOrderEntries, params);
         }
         // Additional WHERE filters on the target — full scalar where surface,
         // properly parameterized against the target alias.
@@ -4829,6 +5419,16 @@ export 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';
     }
@@ -4898,7 +5498,8 @@ export 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));
@@ -4934,6 +5535,24 @@ export 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