turbine-orm 0.29.0 → 0.31.0

package/dist/cjs/query/builder.js

@@ -97,6 +97,12 @@ class QueryInterface {
     /** Pre-computed column type lookups (avoids linear scans per query) */
     columnPgTypeMap;
     columnArrayTypeMap;
+    /**
+     * Columns whose type lives in a DIFFERENT schema than the introspected one
+     * (ColumnMetadata.pgTypeSchema is recorded only in that case) — such columns
+     * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
+     */
+    crossSchemaTypeColumns;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     deepWithWarned = new Set();
     /**
@@ -134,9 +140,19 @@ class QueryInterface {
         this.middlewares = middlewares ?? [];
         this.defaultLimit = options?.defaultLimit;
         // Default to ON: surfacing accidental full-table scans is more valuable
-        // than the (small) risk of noisy logs. Callers explicitly opt out with
-        // `warnOnUnlimited: false`.
-        this.warnOnUnlimited = options?.warnOnUnlimited !== false;
+        // than the (small) risk of noisy logs. Callers opt out globally with
+        // `warnOnUnlimited: false`, per table with `warnOnUnlimited: { users:
+        // false }` (unlisted tables keep the default), or per call via
+        // `findMany({ warnOnUnlimited: false })`.
+        // Per-table maps accept BOTH key forms — the snake_case table name
+        // (`user_profiles`) and the camelCase accessor (`userProfiles`) — since
+        // users naturally key by the accessor they type everywhere else. The
+        // snake_case entry wins when both are present.
+        const warnOpt = options?.warnOnUnlimited;
+        this.warnOnUnlimited =
+            typeof warnOpt === 'object' && warnOpt !== null
+                ? (warnOpt[table] ?? warnOpt[(0, schema_js_1.snakeToCamel)(table)]) !== false
+                : warnOpt !== false;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
@@ -152,9 +168,12 @@ class QueryInterface {
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
+        this.crossSchemaTypeColumns = new Set();
         for (const col of this.tableMeta.columns) {
             this.columnPgTypeMap.set(col.name, col.dialectType ?? col.pgType);
             this.columnArrayTypeMap.set(col.name, col.arrayType ?? col.pgArrayType);
+            if (col.pgTypeSchema !== undefined)
+                this.crossSchemaTypeColumns.add(col.name);
         }
     }
     /** Quote an identifier through the active SQL dialect. */
@@ -680,10 +699,16 @@ class QueryInterface {
      * loop calling `db.users.findMany()` thousands of times only logs once.
      * Suppressed when `defaultLimit` is configured (the caller has already
      * opted in to a bounded query) and when the user passed an explicit
-     * `limit`, `take`, or `cursor`.
+     * `limit`, `take`, or `cursor`. A per-call `warnOnUnlimited` overrides the
+     * config-level setting in either direction (`false` silences a call that
+     * intentionally reads the full set; `true` forces the warning even when
+     * disabled in config).
      */
     maybeWarnUnlimited(args) {
-        if (!this.warnOnUnlimited)
+        const perCall = args?.warnOnUnlimited;
+        if (perCall === false)
+            return;
+        if (perCall === undefined && !this.warnOnUnlimited)
             return;
         if (this.defaultLimit !== undefined)
             return;
@@ -694,7 +719,7 @@ class QueryInterface {
             return;
         this.warnedTables.add(this.table);
         console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
-            'Pass `limit` or set `warnOnUnlimited: false` in config to silence.');
+            'Pass `limit`, or silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
     /**
      * Recursively measure the maximum depth of a `with` clause tree.
@@ -1043,7 +1068,8 @@ class QueryInterface {
         const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
         const columns = entries.map(([k]) => this.toSqlColumn(k));
         const params = entries.map(([, v]) => v);
-        const placeholders = entries.map((_, i) => `${this.p(i + 1)}`);
+        // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
+        const placeholders = entries.map(([k], i) => `${this.p(i + 1)}${this.enumCastSuffix(this.toColumn(k))}`);
         const sql = this.dialect.buildInsertStatement({
             table: this.q(this.table),
             columns,
@@ -1125,7 +1151,13 @@ class QueryInterface {
             return keys.map((key) => record[key]);
         });
         // Use actual Postgres types for array casts in the default PostgreSQL dialect.
-        const typeCasts = columns.map((col) => this.getColumnArrayType(col));
+        // Enum columns cast to `"EnumName"[]` — the generic text[] fallback would
+        // type the UNNEST output as text, which Postgres refuses to coerce to the
+        // enum ("column X is of type Y but expression is of type text").
+        const typeCasts = columns.map((col) => {
+            const enumType = this.enumTypeForColumn(col);
+            return enumType ? `${this.q(enumType)}[]` : this.getColumnArrayType(col);
+        });
         const quotedColumns = columns.map((c) => this.q(c));
         const built = this.dialect.buildBulkInsertStatement({
             table: qt,
@@ -1399,7 +1431,8 @@ class QueryInterface {
         const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
         const columns = createEntries.map(([k]) => this.toSqlColumn(k));
         const createParams = createEntries.map(([, v]) => v);
-        const placeholders = createEntries.map((_, i) => `${this.p(i + 1)}`);
+        // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
+        const placeholders = createEntries.map(([k], i) => `${this.p(i + 1)}${this.enumCastSuffix(this.toColumn(k))}`);
         // The conflict target comes from `where` keys — must be unique/PK columns
         const conflictKeys = Object.keys(args.where).filter((k) => args.where[k] !== undefined);
         const conflictColumns = conflictKeys.map((k) => this.toSqlColumn(k));
@@ -1407,7 +1440,7 @@ class QueryInterface {
         const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
         let paramIdx = createParams.length + 1;
         const setClauses = updateEntries.map(([k]) => {
-            const clause = `${this.toSqlColumn(k)} = ${this.p(paramIdx)}`;
+            const clause = `${this.toSqlColumn(k)} = ${this.p(paramIdx)}${this.enumCastSuffix(this.toColumn(k))}`;
             paramIdx++;
             return clause;
         });
@@ -2087,6 +2120,10 @@ class QueryInterface {
      */
     buildSetClause(key, value, params) {
         const col = this.toSqlColumn(key);
+        // Enum columns get an explicit `::"EnumName"` cast on their value bind
+        // (see enumTypeForColumn); `''` everywhere else. Value-invariant, so the
+        // SQL cache and collectSetParams are unaffected.
+        const cast = this.enumCastSuffix(this.toColumn(key));
         // Detect atomic-operator object: plain object (not null, not array, not
         // Date, not Buffer) with EXACTLY one key matching an operator name.
         if (value !== null &&
@@ -2101,7 +2138,7 @@ class QueryInterface {
                 const opValue = v[op];
                 if (op === 'set') {
                     params.push(opValue);
-                    return `${col} = ${this.p(params.length)}`;
+                    return `${col} = ${this.p(params.length)}${cast}`;
                 }
                 // Arithmetic operators: must be finite numbers
                 if (typeof opValue !== 'number' || !Number.isFinite(opValue)) {
@@ -2129,7 +2166,7 @@ class QueryInterface {
         }
         // Plain value (including null, Date, Buffer, arrays, JSON objects)
         params.push(value);
-        return `${col} = ${this.p(params.length)}`;
+        return `${col} = ${this.p(params.length)}${cast}`;
     }
     // =========================================================================
     // Fingerprinting — value-invariant shape keys for SQL cache lookup
@@ -2228,10 +2265,10 @@ class QueryInterface {
                 parts.push(`${key}:vec(${dist.metric},${cmps})`);
                 continue;
             }
-            // JSON filter
+            // JSON filter — range ops carry a numeric/string annotation because the
+            // numeric compile emits a cast (different SQL shape).
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
-                const jKeys = Object.keys(value).sort();
-                parts.push(`${key}:json(${jKeys.join(',')})`);
+                parts.push(`${key}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
                 continue;
             }
             // Array filter
@@ -2317,6 +2354,15 @@ class QueryInterface {
             else if ((0, filters_js_1.isWhereOperator)(value)) {
                 parts.push(`${key}:${(0, filters_js_1.fingerprintOperatorShape)(value)}`);
             }
+            else if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
+                // Mirrors fingerprintWhere: JSON filters inside relation sub-wheres
+                // build real JSON clauses (buildSubWhereForRelation), so their shape
+                // must be cache-distinct from plain equality.
+                parts.push(`${key}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
+            }
+            else if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+            }
             else if ((0, filters_js_1.isUnmatchedPlainObject)(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -2394,7 +2440,7 @@ class QueryInterface {
             if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
                 const colType = this.getColumnPgType(rawColumn);
                 if (colType === 'json' || colType === 'jsonb') {
-                    this.collectJsonFilterParams(value, params);
+                    this.collectJsonFilterParams(value, params, this.q(rawColumn));
                     continue;
                 }
             }
@@ -2413,7 +2459,11 @@ class QueryInterface {
             }
             // Operator objects
             if ((0, filters_js_1.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
@@ -2495,29 +2545,59 @@ class QueryInterface {
                 }
             }
             const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
+            // JSONB filter — mirrors buildSubWhereForRelation (which mirrors the
+            // top-level buildWhereClause): route to the JSON param collector when
+            // 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') {
+                    this.collectJsonFilterParams(value, params, `${this.q(targetTable)}.${this.q(col)}`);
+                    continue;
+                }
+            }
+            // Array filter — mirrors buildSubWhereForRelation.
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if ((0, filters_js_1.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 (!(0, filters_js_1.isColumnRef)(v))
+                return false;
+            if (refCtx)
+                this.resolveColumnRef(v, refCtx, op.mode);
+            return true;
+        };
+        if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
             (0, filters_js_1.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));
@@ -2530,10 +2610,22 @@ class QueryInterface {
         if (op.endsWith !== undefined)
             params.push(`%${(0, utils_js_1.escapeLike)(op.endsWith)}`);
     }
-    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
-    collectJsonFilterParams(filter, params) {
+    /**
+     * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
+     * the `path` is bound at most once (its placeholder is shared by every
+     * extraction clause), then equals/contains/hasKey values, then the range
+     * comparison values in {@link JSON_RANGE_OPERATORS} order.
+     */
+    collectJsonFilterParams(filter, params, column) {
+        let pathPushed = false;
+        const pushPathOnce = () => {
+            if (!pathPushed) {
+                params.push(filter.path);
+                pathPushed = true;
+            }
+        };
         if (filter.path !== undefined && filter.equals !== undefined) {
-            params.push(filter.path);
+            pushPathOnce();
             params.push(String(filter.equals));
         }
         else if (filter.equals !== undefined) {
@@ -2545,6 +2637,10 @@ class QueryInterface {
         if (filter.hasKey !== undefined) {
             params.push(filter.hasKey);
         }
+        for (const { value } of this.jsonRangeEntries(filter, column)) {
+            pushPathOnce();
+            params.push(value);
+        }
     }
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     collectArrayFilterParams(filter, params) {
@@ -2557,10 +2653,10 @@ 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)) {
@@ -2572,6 +2668,13 @@ 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 ((0, filters_js_1.isJsonPathOrderBy)(dir)) {
+                this.validateJsonPathOrderBy(this.table, this.tableMeta, key, dir);
+                params.push(dir.path.map(String));
+                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.
@@ -2718,9 +2821,20 @@ 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);
             }
@@ -2739,7 +2853,8 @@ 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) {
@@ -2750,6 +2865,12 @@ 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);
@@ -3100,7 +3221,11 @@ class QueryInterface {
             }
             // Handle operator objects
             if ((0, filters_js_1.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;
             }
@@ -3264,8 +3389,41 @@ class QueryInterface {
                 conditions.push(`${qCol} IS NULL`);
                 continue;
             }
+            // JSONB filter on a json/jsonb column of the relation target — mirrors
+            // the top-level WHERE path (buildWhereClause). Without this branch the
+            // filter object used to fall through to plain equality and bind as a
+            // 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') {
+                    conditions.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = (0, filters_js_1.findJsonUniqueKey)(value);
+                if (jsonKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
+            }
+            // Array filter on an array column of the relation target — same mirror.
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(meta, col);
+                if (colType.startsWith('_')) {
+                    conditions.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = (0, filters_js_1.findArrayUniqueKey)(value);
+                if (arrayKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if ((0, filters_js_1.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;
             }
@@ -3282,6 +3440,49 @@ class QueryInterface {
     pgTypeForColumn(meta, column) {
         return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
     }
+    /**
+     * The Postgres enum type name for a column, when the schema knows one.
+     *
+     * Introspection stores each column's `udt_name` in `pgTypes` and every
+     * database enum in `schema.enums` (typname → labels); a column whose type
+     * matches an enum key needs an explicit `::"EnumName"` cast on its write
+     * binds — bulk-insert forms like `UNNEST($1::text[])` otherwise type the
+     * value as text and Postgres refuses the implicit text→enum coercion
+     * ("column X is of type Y but expression is of type text").
+     *
+     * Postgres-only by construction: gated on the active dialect being
+     * `postgresql` AND on `schema.enums` having entries (only PG introspection
+     * produces them — `defineSchema` and the other engines leave it empty), so
+     * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
+     */
+    enumTypeForColumn(column) {
+        if (this.dialect.name !== 'postgresql')
+            return null;
+        const enums = this.schema.enums;
+        if (!enums)
+            return null;
+        // Cross-schema guard (N-5): introspection records pgTypeSchema ONLY when
+        // the column's type lives OUTSIDE the introspected schema. A same-named
+        // enum in another schema must not get this schema's cast — search_path
+        // would resolve `::"status"` to the wrong type. Skipping the cast restores
+        // the pre-cast behavior for such columns. Columns without pgTypeSchema
+        // (same-schema types, defineSchema/legacy metadata) keep the cast.
+        if (this.crossSchemaTypeColumns.has(column))
+            return null;
+        const pgType = this.columnPgTypeMap.get(column) ?? this.tableMeta.pgTypes?.[column];
+        if (!pgType || pgType.startsWith('_'))
+            return null;
+        return Object.hasOwn(enums, pgType) ? pgType : null;
+    }
+    /**
+     * `::"EnumName"` cast suffix for a write-bind placeholder on an enum
+     * column; `''` for every other column, so non-enum SQL stays byte-identical.
+     * The type name is an introspected identifier and is quoted via the dialect.
+     */
+    enumCastSuffix(column) {
+        const enumType = this.enumTypeForColumn(column);
+        return enumType ? `::${this.q(enumType)}` : '';
+    }
     /**
      * Equality-fallthrough guard shared by every SQL-build path AND every
      * cache-hit param-collect path. A plain object literal that matched no known
@@ -3360,8 +3561,40 @@ class QueryInterface {
                 clauses.push(`${qCol} IS NULL`);
                 continue;
             }
+            // JSONB filter on a json/jsonb column — mirrors the top-level WHERE path
+            // (buildWhereClause) so a `with.where` JSON filter is never silently
+            // 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') {
+                    clauses.push(...this.buildJsonFilterClauses(qCol, value, params));
+                    continue;
+                }
+                const jsonKey = (0, filters_js_1.findJsonUniqueKey)(value);
+                if (jsonKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
+            }
+            // Array filter on an array column — same mirror.
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    clauses.push(...this.buildArrayFilterClauses(qCol, value, params, colType));
+                    continue;
+                }
+                const arrayKey = (0, filters_js_1.findArrayUniqueKey)(value);
+                if (arrayKey) {
+                    throw new errors_js_1.ValidationError(`[turbine] Column "${col}" on table "${targetTable}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
+            }
             if ((0, filters_js_1.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);
@@ -3403,8 +3636,24 @@ class QueryInterface {
                 }
             }
             const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
+            // 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') {
+                    this.collectJsonFilterParams(value, params, this.q(col));
+                    continue;
+                }
+            }
+            // Array filter — mirrors buildAliasWhere.
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                const colType = this.pgTypeForColumn(targetMeta, col);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
             if ((0, filters_js_1.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);
@@ -3461,6 +3710,16 @@ class QueryInterface {
                 parts.push(`${key}:${(0, filters_js_1.fingerprintOperatorShape)(value)}`);
                 continue;
             }
+            // JSON / array filters build real clauses in buildAliasWhere, so their
+            // shape must be cache-distinct from plain equality (mirrors fingerprintWhere).
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
+                parts.push(`${key}:${(0, filters_js_1.fingerprintJsonFilterShape)(value)}`);
+                continue;
+            }
+            if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isArrayFilter)(value)) {
+                parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
+                continue;
+            }
             if ((0, filters_js_1.isUnmatchedPlainObject)(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
                     .sort()
@@ -3471,16 +3730,55 @@ 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 errors_js_1.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] ?? (0, schema_js_1.camelToSnake)(ref.col);
+        if (!ctx.meta.allColumns.includes(col)) {
+            throw new errors_js_1.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 errors_js_1.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 ((0, filters_js_1.isColumnRef)(op.equals)) {
+                clauses.push(`${column} = ${this.columnRefSql(op.equals, refCtx, op.mode)}`);
+            }
             else {
                 (0, filters_js_1.assertBindableEqualsOperand)(op.equals, column);
                 params.push(op.equals);
@@ -3488,25 +3786,48 @@ class QueryInterface {
             }
         }
         if (op.gt !== undefined) {
-            params.push(op.gt);
-            clauses.push(`${column} > ${this.p(params.length)}`);
+            if ((0, filters_js_1.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 ((0, filters_js_1.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 ((0, filters_js_1.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 ((0, filters_js_1.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 ((0, filters_js_1.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)}`);
@@ -3557,6 +3878,11 @@ class QueryInterface {
         if ((0, filters_js_1.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 ((0, filters_js_1.isJsonPathOrderBy)(d)) {
+            return `jp(${d.direction ?? 'asc'},${d.type === 'numeric' ? 'num' : 'text'},${d.nulls ?? ''})`;
+        }
         if ((0, filters_js_1.isOrderBySpec)(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
         if (d && typeof d === 'object') {
@@ -3602,6 +3928,11 @@ 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 ((0, filters_js_1.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' } }`).
@@ -3628,6 +3959,7 @@ class QueryInterface {
             value !== null &&
             !Array.isArray(value) &&
             !(0, filters_js_1.isVectorOrderBy)(value) &&
+            !(0, filters_js_1.isJsonPathOrderBy)(value) &&
             !(0, filters_js_1.isOrderBySpec)(value));
     }
     /**
@@ -3644,6 +3976,63 @@ 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] ?? (0, schema_js_1.camelToSnake)(key);
+        if (!meta.allColumns.includes(col)) {
+            throw new errors_js_1.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 errors_js_1.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 (colType !== 'json' && colType !== 'jsonb') {
+            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}).`);
+        }
+        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 errors_js_1.ValidationError(`[turbine] JSON-path ordering on "${field}" is not supported in this orderBy context.`);
+        }
+        params.push(spec.path.map(String));
+        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
@@ -3652,12 +4041,19 @@ 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 errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${this.table}". ` +
-                `Available: ${Object.keys(this.tableMeta.relations).join(', ')}`);
+            throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
+                `Available: ${Object.keys(ownerMeta.relations).join(', ')}`);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -3667,14 +4063,14 @@ class QueryInterface {
                     `(got: ${keys.join(', ') || '(empty)'}).`);
             }
             const { dir } = (0, filters_js_1.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 errors_js_1.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)
@@ -3685,7 +4081,9 @@ class QueryInterface {
         }
         return entries
             .map(([col, dirValue]) => {
-            const snakeCol = (0, schema_js_1.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] ?? (0, schema_js_1.camelToSnake)(col);
             if (!targetMeta.allColumns.includes(snakeCol)) {
                 throw new errors_js_1.ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").`);
             }
@@ -3703,6 +4101,74 @@ class QueryInterface {
         })
             .join(', ');
     }
+    /**
+     * 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 ((0, filters_js_1.isVectorOrderBy)(dirValue)) {
+                throw new errors_js_1.ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if ((0, filters_js_1.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 } = (0, filters_js_1.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 ((0, filters_js_1.isVectorOrderBy)(dirValue)) {
+                throw new errors_js_1.ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
+            }
+            if ((0, filters_js_1.isJsonPathOrderBy)(dirValue)) {
+                this.validateJsonPathOrderBy(targetTable, targetMeta, key, dirValue);
+                params.push(dirValue.path.map(String));
+                continue;
+            }
+            if (this.isRelationOrderByValue(dirValue)) {
+                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;
@@ -4422,20 +4888,13 @@ 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 = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = (0, filters_js_1.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
@@ -4509,8 +4968,10 @@ 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
@@ -4568,22 +5029,15 @@ 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 = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const { dir, nulls } = (0, filters_js_1.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.
@@ -4685,18 +5139,59 @@ class QueryInterface {
         };
         return typeMap[baseType] ?? 'text';
     }
+    /**
+     * Validate and enumerate the range comparisons (`gt`/`gte`/`lt`/`lte`) on a
+     * JSON filter, in the fixed {@link JSON_RANGE_OPERATORS} order. Shared by
+     * the SQL-build path ({@link buildJsonFilterClauses}) and the cache-hit
+     * param-collect path ({@link collectJsonFilterParams}) so both always agree
+     * on which params are pushed — and both throw identically for invalid
+     * shapes, so a warmed cache can never skip validation.
+     */
+    jsonRangeEntries(filter, column) {
+        const entries = [];
+        for (const [op, sqlOp] of Object.entries(filters_js_1.JSON_RANGE_OPERATORS)) {
+            const value = filter[op];
+            if (value === undefined)
+                continue;
+            if (filter.path === undefined) {
+                throw new errors_js_1.ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a \`path\` ` +
+                    `(e.g. { path: ['meta', 'score'], ${op}: ${JSON.stringify(value)} }).`);
+            }
+            if (typeof value !== 'number' && typeof value !== 'string') {
+                throw new errors_js_1.ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a number or string, ` +
+                    `got ${JSON.stringify(value)}.`);
+            }
+            if (typeof value === 'number' && !Number.isFinite(value)) {
+                throw new errors_js_1.ValidationError(`[turbine] JSON range operator '${op}' on ${column} requires a finite number.`);
+            }
+            entries.push({ sqlOp, value });
+        }
+        return entries;
+    }
     /**
      * Build SQL clauses for JSONB filter operators on a column.
-     * Supports: path, equals, contains, hasKey.
+     * Supports: path, equals, contains, hasKey, gt, gte, lt, lte.
+     *
+     * The `path` param is bound at most once and its placeholder is shared by
+     * every clause that extracts it (equals + range ops), so the param list
+     * stays byte-identical to {@link collectJsonFilterParams}.
      */
     buildJsonFilterClauses(column, filter, params) {
         const clauses = [];
+        // Lazily bind the path once; reuse the same $N in every extraction clause.
+        let pathParamIdx = null;
+        const pathExtract = () => {
+            if (pathParamIdx === null) {
+                params.push(filter.path);
+                pathParamIdx = params.length;
+            }
+            return this.dialect.buildJsonPathExtract(column, this.p(pathParamIdx));
+        };
         if (filter.path !== undefined && filter.equals !== undefined) {
             // Path access + equals: column #>> $N::text[] = $M
-            params.push(filter.path);
-            const pathParam = params.length;
+            const extract = pathExtract();
             params.push(String(filter.equals));
-            clauses.push(`${this.dialect.buildJsonPathExtract(column, this.p(pathParam))} = ${this.p(params.length)}`);
+            clauses.push(`${extract} = ${this.p(params.length)}`);
         }
         else if (filter.equals !== undefined) {
             // Containment equality: column @> $N::jsonb
@@ -4713,8 +5208,28 @@ class QueryInterface {
             params.push(filter.hasKey);
             clauses.push(`${column} ? ${this.p(params.length)}`);
         }
+        // Range comparisons on the extracted path: numbers compare numerically
+        // (cast through the dialect), strings compare as text.
+        for (const { sqlOp, value } of this.jsonRangeEntries(filter, column)) {
+            const extract = pathExtract();
+            params.push(value);
+            const lhs = typeof value === 'number' ? this.castJsonNumeric(extract) : extract;
+            clauses.push(`${lhs} ${sqlOp} ${this.p(params.length)}`);
+        }
         return clauses;
     }
+    /**
+     * Cast an extracted JSON path text value to a numeric type for range
+     * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to
+     * compare JSON numbers, and `::float` would lose precision on big ints);
+     * other dialects route through {@link Dialect.castAggregate} (SQLite/MySQL/
+     * SQL Server have no `::` operator) as a float cast.
+     */
+    castJsonNumeric(extract) {
+        if (this.dialect.name === 'postgresql')
+            return `(${extract})::numeric`;
+        return this.dialect.castAggregate ? this.dialect.castAggregate(`(${extract})`, 'float') : `(${extract})::numeric`;
+    }
     /**
      * Build SQL clauses for Array filter operators on a column.
      * Supports: has, hasEvery, hasSome, isEmpty.