turbine-orm 0.19.1 → 0.21.0

package/dist/query/builder.js

@@ -11,7 +11,7 @@
  * metadata — nothing is hardcoded.
  */
 import { postgresDialect } from '../dialect.js';
-import { CircularRelationError, NotFoundError, OptimisticLockError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
+import { CircularRelationError, NotFoundError, OptimisticLockError, RelationError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, sqlToPreparedName } from './utils.js';
@@ -44,6 +44,53 @@ function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ */
+function fingerprintOperatorShape(value) {
+    const obj = value;
+    const opKeys = Object.keys(obj)
+        .filter((k) => k !== 'mode')
+        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .sort();
+    const modeStr = value.mode === 'insensitive' ? ':i' : '';
+    return `op(${opKeys.join(',')}${modeStr})`;
+}
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+function assertBindableEqualsOperand(value, column) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    throw new ValidationError(`[turbine] Plain-object value for operator 'equals' on ${column}: ` +
+        `objects are only valid 'equals' values on JSON (json/jsonb) columns, ` +
+        `where 'equals' is the JSONB containment filter.`);
+}
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+function sortedKeys(obj) {
+    return Object.keys(obj).sort();
+}
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+function sortedEntries(obj) {
+    return Object.entries(obj).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
 /** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
@@ -53,9 +100,11 @@ const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
  * appear in any other where-filter shape, so the presence of one of these is
  * an unambiguous signal that the user meant a JSON filter. Used by the
  * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
- * `WhereOperator` for LIKE) is not misclassified.
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
  */
-const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
+const JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
 /** Check if a value is a JSONB filter object */
 function isJsonFilter(value) {
     if (value === null ||
@@ -252,6 +301,89 @@ export class QueryInterface {
     p(index) {
         return this.dialect.paramPlaceholder(index);
     }
+    /**
+     * Cast an aggregate expression to an integer/float result type through the
+     * active dialect. PostgreSQL keeps the historical postfix cast (`expr::int` /
+     * `expr::float`); SQLite (no `::` operator) maps to `CAST(expr AS INTEGER/REAL)`.
+     * Falls back to the Postgres postfix cast for dialects without the hook.
+     */
+    castAgg(expr, target) {
+        return this.dialect.castAggregate?.(expr, target) ?? `${expr}::${target}`;
+    }
+    /**
+     * Build the trailing pagination clause for an OUTER SELECT. PostgreSQL/MySQL/
+     * SQLite use ` LIMIT <ph>` and/or ` OFFSET <ph>`. SQL Server has no `LIMIT`, so
+     * its dialect implements {@link Dialect.buildLimitOffset} to emit
+     * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
+     * Param-push order (limit before offset) is owned by the caller and unchanged —
+     * this only varies the SQL text, so PG output stays byte-identical.
+     */
+    buildPagination(limitPh, offsetPh, hasOrderBy) {
+        if (this.dialect.buildLimitOffset) {
+            return this.dialect.buildLimitOffset({ limitPlaceholder: limitPh, offsetPlaceholder: offsetPh, hasOrderBy });
+        }
+        let s = '';
+        if (limitPh !== undefined)
+            s += ` LIMIT ${limitPh}`;
+        if (offsetPh !== undefined)
+            s += ` OFFSET ${offsetPh}`;
+        return s;
+    }
+    /**
+     * The single-row limit appended to findUnique / findFirst-style lookups. ` LIMIT 1`
+     * for PG/MySQL/SQLite; SQL Server routes through {@link Dialect.buildLimitOffset}
+     * (literal `1`, no params) → ` ORDER BY (SELECT NULL) OFFSET 0 ROWS FETCH NEXT 1
+     * ROWS ONLY`. No params are pushed, so the collect path is unaffected.
+     */
+    limitOneClause() {
+        if (this.dialect.buildLimitOffset) {
+            return this.dialect.buildLimitOffset({ limitPlaceholder: '1', offsetPlaceholder: undefined, hasOrderBy: false });
+        }
+        return ' LIMIT 1';
+    }
+    /**
+     * Validate a LIMIT/OFFSET value as a non-negative integer and return it as an
+     * inline SQL literal. Used only on `dialect.inlineLimitOffset` engines (MySQL).
+     * The input is always a Turbine-controlled pagination value, never a raw user
+     * string — and this guard guarantees the output is `String` of a validated
+     * integer, so inlining cannot inject SQL.
+     */
+    limitOffsetLiteral(value) {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+            throw new ValidationError(`LIMIT/OFFSET must be a non-negative integer, received: ${String(value)}`);
+        }
+        return String(n);
+    }
+    /**
+     * Resolve a LIMIT/OFFSET value to either an inline literal (no param pushed, on
+     * `dialect.inlineLimitOffset` engines) or a bound placeholder (the value is
+     * pushed to `params`). Build and collect paths both gate on the same flag so
+     * the param order stays mirrored; PG/SQLite/SQL Server keep parameterizing and
+     * stay byte-identical.
+     */
+    paginationRef(value, params) {
+        if (this.dialect.inlineLimitOffset) {
+            return this.limitOffsetLiteral(value);
+        }
+        params.push(Number(value));
+        return this.p(params.length);
+    }
+    /**
+     * Build an `IN` / `NOT IN` predicate through the active dialect. PostgreSQL
+     * keeps the array-param form (`expr = ANY($n)` / `expr != ALL($n)`); other
+     * engines (SQLite) use a length-independent single-placeholder form. Paired
+     * with {@link inParam}, which supplies the single bound value.
+     */
+    inClause(expr, paramRef, negated) {
+        if (this.dialect.buildInClause)
+            return this.dialect.buildInClause(expr, paramRef, negated);
+        return negated ? `${expr} != ALL(${paramRef})` : `${expr} = ANY(${paramRef})`;
+    }
+    /** The single bound parameter for an `IN` list (PG: the array; SQLite: a JSON string). */
+    inParam(values) {
+        return this.dialect.inClauseParam ? this.dialect.inClauseParam(values) : values;
+    }
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -352,14 +484,59 @@ export class QueryInterface {
             clearTimeout(timer);
         }
     }
+    /**
+     * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
+     * the active dialect's {@link Dialect.resultStrategy}, then apply its
+     * transform.
+     *
+     *   - `'returning'` / `'output'`: the statement returns its own affected rows
+     *     (`RETURNING *` / `OUTPUT INSERTED.*`). Byte-identical to the historical
+     *     single `queryWithTimeout` + `transform(result)` path — the PostgreSQL
+     *     route is unchanged.
+     *   - `'reselect'`: the engine cannot return rows from a write, so the build
+     *     method attached a {@link DeferredQuery.reselect} plan that runs the
+     *     write and a follow-up SELECT; the SELECT's rows feed the transform.
+     */
+    async executeMutation(deferred, timeout) {
+        if (this.dialect.resultStrategy === 'reselect' && deferred.reselect) {
+            const exec = (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, preparedName);
+            const result = await deferred.reselect(exec);
+            return deferred.transform(result);
+        }
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, timeout, deferred.preparedName);
+        return deferred.transform(result);
+    }
+    /**
+     * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
+     * by a write's `where` clause. Used by the `'reselect'` result strategy to
+     * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
+     * builder as reads, so no user value is interpolated.
+     */
+    buildReselectByWhere(whereObj) {
+        const params = [];
+        const clause = this.buildWhereClause(whereObj, params);
+        const where = clause ? ` WHERE ${clause}` : '';
+        return { sql: `SELECT * FROM ${this.q(this.table)}${where}`, params };
+    }
+    /**
+     * Best-effort extraction of an auto-generated primary key from a write
+     * result for `'reselect'` engines (e.g. mysql2's `insertId`). Returns
+     * `undefined` when the driver exposes no such field.
+     */
+    mutationInsertId(result) {
+        const r = result;
+        return r.insertId ?? r.lastID;
+    }
     /**
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      */
     async executeWithMiddleware(action, args, executor) {
         this.currentAction = action;
@@ -398,8 +575,12 @@ export class QueryInterface {
         const withFp = args.with ? this.withFingerprint(args.with) : '';
         const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
         const params = [];
-        // Check if all where values are simple (plain equality, no operators/null/OR)
-        const whereKeys = Object.keys(whereObj).filter((k) => whereObj[k] !== undefined);
+        // Check if all where values are simple (plain equality, no operators/null/OR).
+        // Keys are sorted to match fingerprintWhere — insertion order here would let
+        // permuted where literals share a cache entry with misaligned params.
+        const whereKeys = Object.keys(whereObj)
+            .filter((k) => whereObj[k] !== undefined)
+            .sort();
         const isSimpleWhere = !whereObj.OR &&
             !whereObj.AND &&
             !whereObj.NOT &&
@@ -416,7 +597,7 @@ export class QueryInterface {
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 void tempParams; // params are positional, SQL is value-invariant
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
             });
             // Collect params (same order as build)
             for (const k of whereKeys) {
@@ -441,7 +622,7 @@ export class QueryInterface {
                 const whereSql = clause ? ` WHERE ${clause}` : '';
                 const qt = this.q(this.table);
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
             });
             // Collect params
             this.collectWhereParams(whereObj, params);
@@ -466,7 +647,7 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
-            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql} LIMIT 1`;
+            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
         });
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
@@ -603,7 +784,8 @@ export class QueryInterface {
             }
             let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
             if (args?.cursor) {
-                const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+                // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
+                const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
@@ -625,14 +807,18 @@ export class QueryInterface {
                 // vector at the correct position (after cursor params, before LIMIT).
                 sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
             }
+            // Pagination — push params in the same order the collect path mirrors
+            // (limit before offset); the SQL TEXT shape is dialect-owned via
+            // buildPagination (PG: ` LIMIT $n`/` OFFSET $n`; SQL Server: OFFSET/FETCH).
+            let limitPh;
+            let offsetPh;
             if (effectiveLimit !== undefined) {
-                freshParams.push(Number(effectiveLimit));
-                sql += ` LIMIT ${this.p(freshParams.length)}`;
+                limitPh = this.paginationRef(effectiveLimit, freshParams);
             }
             if (args?.offset !== undefined) {
-                freshParams.push(Number(args.offset));
-                sql += ` OFFSET ${this.p(freshParams.length)}`;
+                offsetPh = this.paginationRef(args.offset, freshParams);
             }
+            sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
             return sql;
         });
         // Collect params in exact build order:
@@ -644,9 +830,9 @@ export class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params);
         }
-        // 3. Cursor params
+        // 3. Cursor params — sorted (canonical) order, matching cursorFp and the build path.
         if (args?.cursor) {
-            const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+            const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
             for (const [, v] of cursorEntries) {
                 params.push(v);
             }
@@ -656,12 +842,13 @@ export class QueryInterface {
         if (args?.orderBy) {
             this.collectOrderByParams(args.orderBy, params);
         }
-        // 5. LIMIT param
-        if (effectiveLimit !== undefined) {
+        // 5. LIMIT param — skipped when the dialect inlines pagination (build path
+        //    mirrors via paginationRef → no placeholder, no param).
+        if (effectiveLimit !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(effectiveLimit));
         }
-        // 6. OFFSET param
-        if (args?.offset !== undefined) {
+        // 6. OFFSET param — same inline gate as LIMIT above.
+        if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(args.offset));
         }
         return {
@@ -721,34 +908,19 @@ export class QueryInterface {
         }
         // --- Overflow: fall back to cursor path from scratch ---
         const deferred = this.buildFindMany(args);
-        // Acquire a dedicated connection — cursors require a single connection in a transaction
+        // Acquire a dedicated connection — cursors require a single connection in a
+        // transaction. The dialect owns the streaming SQL (Postgres: BEGIN → DECLARE
+        // … NO SCROLL CURSOR FOR → FETCH n → CLOSE → COMMIT, ROLLBACK on error); we
+        // just parse + yield the row batches it produces.
         const client = await this.pool.connect();
-        const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        const quotedCursor = this.q(cursorName);
         try {
-            await client.query('BEGIN');
-            await client.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${deferred.sql}`, deferred.params);
-            while (true) {
-                const batch = await client.query(`FETCH ${batchSize} FROM ${quotedCursor}`);
-                if (batch.rows.length === 0)
-                    break;
-                for (const row of batch.rows) {
+            for await (const batch of this.dialect.openStream(client, deferred.sql, deferred.params, batchSize)) {
+                for (const row of batch) {
                     yield (hasRelations ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table));
                 }
-                if (batch.rows.length < batchSize)
-                    break;
             }
-            await client.query(`CLOSE ${quotedCursor}`);
-            await client.query('COMMIT');
         }
         catch (err) {
-            // Rollback on error (also closes cursor implicitly)
-            try {
-                await client.query('ROLLBACK');
-            }
-            catch {
-                // Connection may already be broken — ignore rollback error
-            }
             // Wrap pg constraint errors so streaming surfaces typed errors like the rest of the API
             throw wrapPgError(err);
         }
@@ -850,8 +1022,7 @@ export class QueryInterface {
                 return this.nestedCreate(args);
             }
             const deferred = this.buildCreate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildCreate(args) {
@@ -880,6 +1051,33 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.create`,
+            // Non-RETURNING engines: INSERT, then re-fetch the new row by primary key
+            // (provided value, else the driver's generated insert id).
+            reselect: this.makeCreateReselect(sql, params, args.data),
+        };
+    }
+    /**
+     * Build the `'reselect'` plan for {@link buildCreate}: run the INSERT, then
+     * `SELECT * WHERE pk = ?`. Returns `undefined` (skipped) unless the active
+     * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
+     * pays nothing. Not yet wired to a real non-RETURNING engine.
+     */
+    makeCreateReselect(insertSql, insertParams, data) {
+        if (this.dialect.resultStrategy !== 'reselect')
+            return undefined;
+        return async (exec) => {
+            const writeResult = await exec(insertSql, insertParams);
+            const insertId = this.mutationInsertId(writeResult);
+            const conds = [];
+            const selParams = [];
+            let idx = 1;
+            for (const pk of this.tableMeta.primaryKey) {
+                const field = this.tableMeta.reverseColumnMap[pk] ?? snakeToCamel(pk);
+                selParams.push(data[field] ?? data[pk] ?? insertId);
+                conds.push(`${this.q(pk)} = ${this.p(idx++)}`);
+            }
+            const where = conds.length > 0 ? ` WHERE ${conds.join(' AND ')}` : '';
+            return exec(`SELECT * FROM ${this.q(this.table)}${where}`, selParams);
         };
     }
     // -------------------------------------------------------------------------
@@ -935,8 +1133,7 @@ export class QueryInterface {
                 return this.nestedUpdate(args);
             }
             const deferred = this.buildUpdate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildUpdate(args) {
@@ -964,7 +1161,12 @@ export class QueryInterface {
                 whereSql = whereSql ? `${whereSql} AND ${versionCheck}` : ` WHERE ${versionCheck}`;
             }
             this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
-            return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}${this.dialect.buildReturningClause('*')}`;
+            // Engines that inject their returning shape MID-statement (SQL Server
+            // `OUTPUT INSERTED.*` between SET and WHERE) override buildUpdateStatement;
+            // absent → the trailing-clause PG/SQLite/MySQL form (byte-identical).
+            return this.dialect.buildUpdateStatement
+                ? this.dialect.buildUpdateStatement({ table: this.q(this.table), setClauses, whereSql, returning: '*' })
+                : `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}${this.dialect.buildReturningClause('*')}`;
         };
         let sql;
         let preparedName;
@@ -1008,6 +1210,26 @@ export class QueryInterface {
             },
             tag: `${this.table}.update`,
             preparedName,
+            // Non-RETURNING engines: UPDATE, then re-fetch the row by the same where.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    const writeResult = await exec(sql, params, preparedName);
+                    // Optimistic-lock conflict: the version-checked UPDATE matched no
+                    // row. The re-fetch below uses `where` WITHOUT the version
+                    // predicate, so it would return the stale row and silently mask
+                    // the conflict — detect it from affected-rows here instead, to
+                    // match the OptimisticLockError thrown on RETURNING/OUTPUT engines.
+                    if (lock && (writeResult.rowCount ?? 0) === 0) {
+                        throw new OptimisticLockError({
+                            table: this.table,
+                            versionField: lock.field,
+                            expectedVersion: lock.expected,
+                        });
+                    }
+                    const sel = this.buildReselectByWhere(whereObj);
+                    return exec(sel.sql, sel.params);
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1039,19 +1261,19 @@ export class QueryInterface {
     async runInImplicitTx(fn) {
         const client = await this.pool.connect();
         try {
-            await client.query('BEGIN');
+            await client.query(this.dialect.beginStatement());
             const { TransactionClient } = await import('../client.js');
             // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
             // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
             const ctx = { schema: this.schema, tx: tx };
             const result = await fn(ctx);
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
             try {
-                await client.query('ROLLBACK');
+                await client.query(this.dialect.rollbackStatement());
             }
             catch {
                 // Best-effort rollback — connection may have died.
@@ -1084,8 +1306,7 @@ export class QueryInterface {
     async delete(args) {
         return this.executeWithMiddleware('delete', args, async () => {
             const deferred = this.buildDelete(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildDelete(args) {
@@ -1100,7 +1321,11 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
+            // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
+            // absent override → the trailing-clause PG/SQLite/MySQL form (byte-identical).
+            return this.dialect.buildDeleteStatement
+                ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
+                : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
         });
         // On cache hit, still validate the predicate
         if (whereFp === '') {
@@ -1123,6 +1348,16 @@ export class QueryInterface {
             },
             tag: `${this.table}.delete`,
             preparedName: entry.name,
+            // Non-RETURNING engines: the row is gone after DELETE, so pre-SELECT it
+            // by the same where, then run the DELETE, returning the captured row.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    const sel = this.buildReselectByWhere(whereObj);
+                    const pre = await exec(sel.sql, sel.params);
+                    await exec(entry.sql, params, entry.name);
+                    return pre;
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1131,8 +1366,7 @@ export class QueryInterface {
     async upsert(args) {
         return this.executeWithMiddleware('upsert', args, async () => {
             const deferred = this.buildUpsert(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildUpsert(args) {
@@ -1178,6 +1412,14 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.upsert`,
+            // Non-RETURNING engines: run the upsert, then re-fetch by the where keys.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    await exec(sql, params);
+                    const sel = this.buildReselectByWhere(args.where);
+                    return exec(sel.sql, sel.params);
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1272,7 +1514,7 @@ export class QueryInterface {
             const freshParams = [];
             const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
-            return `SELECT COUNT(*)::int AS count FROM ${this.q(this.table)}${whereSql}`;
+            return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
         });
         if (args?.where) {
             this.collectWhereParams(whereObj, params);
@@ -1312,7 +1554,7 @@ export class QueryInterface {
         // _count
         if (args._count === true || args._count === undefined) {
             // default: always include count
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         // _sum
         if (args._sum) {
@@ -1328,7 +1570,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1529,12 +1771,12 @@ export class QueryInterface {
             clauses.push(`${expr} <= ${this.p(params.length)}`);
         }
         if (op.in !== undefined) {
-            params.push(op.in);
-            clauses.push(`${expr} = ANY(${this.p(params.length)})`);
+            params.push(this.inParam(op.in));
+            clauses.push(this.inClause(expr, this.p(params.length), false));
         }
         if (op.notIn !== undefined) {
-            params.push(op.notIn);
-            clauses.push(`${expr} != ALL(${this.p(params.length)})`);
+            params.push(this.inParam(op.notIn));
+            clauses.push(this.inClause(expr, this.p(params.length), true));
         }
         return clauses;
     }
@@ -1572,13 +1814,13 @@ export class QueryInterface {
         const selectExprs = [];
         // _count
         if (args._count === true) {
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         else if (args._count && typeof args._count === 'object') {
             for (const [field, enabled] of Object.entries(args._count)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`COUNT(${this.q(col)})::int AS ${this.q(`_count_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`COUNT(${this.q(col)})`, 'int')} AS ${this.q(`_count_${col}`)}`);
                 }
             }
         }
@@ -1596,7 +1838,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1619,7 +1861,7 @@ export class QueryInterface {
             }
         }
         if (selectExprs.length === 0) {
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         const sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql}`;
         return {
@@ -1886,12 +2128,7 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             // Vector distance filter — metric (operator) and present comparators
@@ -1964,12 +2201,7 @@ export class QueryInterface {
                 parts.push(`${key}:null`);
             }
             else if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
             }
             else if (isUnmatchedPlainObject(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
@@ -1990,7 +2222,8 @@ export class QueryInterface {
      * @internal Exposed as package-private for testing.
      */
     collectWhereParams(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and buildWhereClause.
+        const keys = sortedKeys(where);
         for (const key of keys) {
             const value = where[key];
             if (value === undefined)
@@ -2075,7 +2308,7 @@ export class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(rawColumn, value, params);
                 continue;
             }
             // Plain equality — same strict validation as the build path, so a
@@ -2089,22 +2322,28 @@ export class QueryInterface {
         const meta = this.schema.tables[targetTable];
         if (!meta)
             return;
-        for (const [field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and buildSubWhereForRelation.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             if (value === null)
                 continue;
+            const col = meta.columnMap[field] ?? camelToSnake(field);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
-            const col = meta.columnMap[field] ?? camelToSnake(field);
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
     /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(op, params) {
+    collectOperatorParams(column, op, params) {
+        if (op.equals !== undefined && op.equals !== null) {
+            assertBindableEqualsOperand(op.equals, `"${column}"`);
+            params.push(op.equals);
+        }
         if (op.gt !== undefined)
             params.push(op.gt);
         if (op.gte !== undefined)
@@ -2116,9 +2355,9 @@ export class QueryInterface {
         if (op.not !== undefined && op.not !== null)
             params.push(op.not);
         if (op.in !== undefined)
-            params.push(op.in);
+            params.push(this.inParam(op.in));
         if (op.notIn !== undefined)
-            params.push(op.notIn);
+            params.push(this.inParam(op.notIn));
         if (op.contains !== undefined)
             params.push(`%${escapeLike(op.contains)}%`);
         if (op.startsWith !== undefined)
@@ -2260,7 +2499,7 @@ export class QueryInterface {
         const meta = this.schema.tables[table ?? this.table];
         if (!meta)
             return;
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef)
                 continue;
@@ -2283,11 +2522,11 @@ export class QueryInterface {
             if (spec.where) {
                 this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
-            if (spec.limit !== undefined) {
+            if (spec.limit !== undefined && !this.dialect.inlineLimitOffset) {
                 params.push(Number(spec.limit));
             }
             if (spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef)
                         continue;
@@ -2301,7 +2540,7 @@ export class QueryInterface {
         const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
@@ -2316,12 +2555,12 @@ export class QueryInterface {
         // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
         // pushing one here would orphan a param and desync the collect path.
         // `limit: 0` pushes (LIMIT 0 is honored), so check !== undefined.
-        if (relDef.type === 'hasMany' && spec.limit !== undefined) {
+        if (relDef.type === 'hasMany' && spec.limit !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(spec.limit));
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
         if (willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
@@ -2403,7 +2642,8 @@ export class QueryInterface {
      * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
      */
     buildWhereClause(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and collectWhereParams.
+        const keys = sortedKeys(where);
         if (keys.length === 0)
             return null;
         const andClauses = [];
@@ -2610,7 +2850,9 @@ export class QueryInterface {
             return null;
         const qt = this.q(targetTable);
         const conditions = [];
-        for (const [field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and collectRelFilterParams.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? camelToSnake(field);
@@ -2675,7 +2917,9 @@ export class QueryInterface {
      */
     buildAliasWhere(targetTable, targetMeta, alias, where, params) {
         const clauses = [];
-        for (const [key, value] of Object.entries(where)) {
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and collectAliasWhereParams.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
             if (value === undefined)
                 continue;
             if (key === 'OR' || key === 'AND') {
@@ -2717,7 +2961,9 @@ export class QueryInterface {
     }
     /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
     collectAliasWhereParams(targetTable, targetMeta, where, params) {
-        for (const [key, value] of Object.entries(where)) {
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and buildAliasWhere.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
             if (value === undefined)
                 continue;
             if (key === 'OR' || key === 'AND') {
@@ -2735,11 +2981,11 @@ export class QueryInterface {
             }
             if (value === null)
                 continue;
+            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
-            const col = targetMeta.columnMap[key] ?? camelToSnake(key);
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
             params.push(value);
         }
@@ -2773,11 +3019,7 @@ export class QueryInterface {
                 continue;
             }
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                parts.push(`${key}:op(${opKeys.join(',')}${mode === 'insensitive' ? ':i' : ''})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             if (isUnmatchedPlainObject(value)) {
@@ -2796,6 +3038,16 @@ export class QueryInterface {
      */
     buildOperatorClauses(column, op, params) {
         const clauses = [];
+        if (op.equals !== undefined) {
+            if (op.equals === null) {
+                clauses.push(`${column} IS NULL`);
+            }
+            else {
+                assertBindableEqualsOperand(op.equals, column);
+                params.push(op.equals);
+                clauses.push(`${column} = ${this.p(params.length)}`);
+            }
+        }
         if (op.gt !== undefined) {
             params.push(op.gt);
             clauses.push(`${column} > ${this.p(params.length)}`);
@@ -2822,12 +3074,12 @@ export class QueryInterface {
             }
         }
         if (op.in !== undefined) {
-            params.push(op.in);
-            clauses.push(`${column} = ANY(${this.p(params.length)})`);
+            params.push(this.inParam(op.in));
+            clauses.push(this.inClause(column, this.p(params.length), false));
         }
         if (op.notIn !== undefined) {
-            params.push(op.notIn);
-            clauses.push(`${column} != ALL(${this.p(params.length)})`);
+            params.push(this.inParam(op.notIn));
+            clauses.push(this.inClause(column, this.p(params.length), true));
         }
         const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? this.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
         if (op.contains !== undefined) {
@@ -2898,6 +3150,9 @@ export class QueryInterface {
      * non-vector column — a user-supplied string can never become a SQL operator.
      */
     vectorOperator(field, rawColumn, metric) {
+        if (!this.dialect.supportsVector) {
+            throw new UnsupportedFeatureError('pgvector distance operations', this.dialect.name, 'Vector search requires PostgreSQL with the pgvector extension.');
+        }
         const colType = this.getColumnPgType(rawColumn);
         if (colType !== 'vector') {
             throw new ValidationError(`[turbine] Column "${field}" on table "${this.table}" is not a vector column ` +
@@ -2918,6 +3173,9 @@ export class QueryInterface {
      * placeholder string.
      */
     pushVectorParam(field, _rawColumn, to, params) {
+        if (!this.dialect.supportsVector) {
+            throw new UnsupportedFeatureError('pgvector distance operations', this.dialect.name, 'Vector search requires PostgreSQL with the pgvector extension.');
+        }
         if (!Array.isArray(to) || to.length === 0) {
             throw new ValidationError(`[turbine] Vector distance on "${field}" requires a non-empty array of numbers for "to".`);
         }
@@ -3094,7 +3352,7 @@ export class QueryInterface {
         const baseCols = cols.map((col) => `${qtbl}.${this.q(col)}`).join(', ');
         const relationSelects = [];
         const aliasCounter = { n: 0 };
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef) {
                 throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
@@ -3228,6 +3486,32 @@ export class QueryInterface {
                 .map(([k]) => targetMeta.columnMap[k] ?? camelToSnake(k)));
             targetColumns = targetMeta.allColumns.filter((col) => !omittedFields.has(col));
         }
+        // Engine override seam (additive): a dialect whose JSON-aggregation shape does
+        // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
+        // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs
+        // unchanged (byte-identical output, all their tests stay green). The override
+        // pushes params per the documented RelationSubqueryContext ordering contract,
+        // which mirrors collectRelationSubqueryParams so the SQL cache / pipeline stay
+        // in sync.
+        if (this.dialect.buildRelationSubquery) {
+            return this.dialect.buildRelationSubquery({
+                relDef,
+                spec,
+                params,
+                parentRef,
+                alias,
+                targetTable,
+                targetMeta,
+                targetColumns,
+                depth: currentDepth,
+                path: currentPath,
+                quote: (name) => this.q(name),
+                buildWhere: (whereAlias) => (spec !== true && spec.where
+                    ? this.buildAliasWhere(targetTable, targetMeta, whereAlias, spec.where, params)
+                    : '') ?? '',
+                recurse: (nRelDef, nSpec, nParent, nDepth, nPath) => this.buildRelationSubquery(nRelDef, nSpec, params, nParent, aliasCounter, nDepth, nPath),
+            });
+        }
         // Build JSON object pairs for resolved columns
         const jsonPairs = targetColumns.map((col) => [
             targetMeta.reverseColumnMap[col] ?? snakeToCamel(col),
@@ -3249,7 +3533,7 @@ export class QueryInterface {
         }
         // Nested relations — only in the non-wrapped path (wrapped path builds them separately)
         if (!willWrap && spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3259,7 +3543,7 @@ export class QueryInterface {
                 const nestedSubquery = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, alias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
                 // Use '[]'::json for hasMany (empty array), NULL for belongsTo/hasOne (no object)
                 const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
-                jsonPairs.push([nestedRelName, `COALESCE((${nestedSubquery}), ${fallback})`]);
+                jsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSubquery, fallback)]);
             }
         }
         const jsonObj = this.dialect.buildJsonObject(jsonPairs);
@@ -3307,8 +3591,7 @@ export class QueryInterface {
         // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
         let limitClause = '';
         if (relDef.type === 'hasMany' && spec !== true && spec.limit !== undefined) {
-            params.push(Number(spec.limit));
-            limitClause = ` LIMIT ${this.p(params.length)}`;
+            limitClause = ` LIMIT ${this.paginationRef(spec.limit, params)}`;
         }
         if (relDef.type === 'hasMany') {
             // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
@@ -3325,7 +3608,7 @@ export class QueryInterface {
                 ]);
                 // Build nested relation subqueries referencing innerAlias
                 if (spec !== true && spec.with) {
-                    for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                    for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                         const nestedRelDef = targetMeta.relations[nestedRelName];
                         if (!nestedRelDef) {
                             throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3333,13 +3616,17 @@ export class QueryInterface {
                         }
                         const nestedSub = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
                         const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
-                        innerJsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                        innerJsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
                     }
                 }
                 const innerJsonObj = this.dialect.buildJsonObject(innerJsonPairs);
                 return `SELECT ${this.dialect.buildJsonArrayAgg(innerJsonObj)} FROM (${innerSql}) ${innerAlias}`;
             }
-            return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, orderClause.trim() || undefined)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
+            // Inline ORDER BY only when the dialect's array-agg supports it (PG). For
+            // hasMany this path is reached only when there is no orderClause, so the
+            // argument is `undefined` either way — keeping PG output byte-identical.
+            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`;
@@ -3427,8 +3714,7 @@ export class QueryInterface {
         // LIMIT — `limit: 0` is honored (LIMIT 0 → empty array)
         let limitClause = '';
         if (spec !== true && spec.limit !== undefined) {
-            params.push(Number(spec.limit));
-            limitClause = ` LIMIT ${this.p(params.length)}`;
+            limitClause = ` LIMIT ${this.paginationRef(spec.limit, params)}`;
         }
         const fromJoin = `FROM ${qTarget} ${talias} JOIN ${qJunction} ${jalias} ON ${joinOn}`;
         // When LIMIT or ORDER BY is present, wrap the joined rows in an inner subquery
@@ -3443,7 +3729,7 @@ export class QueryInterface {
             ]);
             // Nested relations reference the inner alias.
             if (spec !== true && spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef) {
                         throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3453,7 +3739,7 @@ export class QueryInterface {
                     const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'
                         ? this.dialect.nullJsonLiteral
                         : this.dialect.emptyJsonArrayLiteral;
-                    innerJsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                    innerJsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
                 }
             }
             const innerJsonObj = this.dialect.buildJsonObject(innerJsonPairs);
@@ -3466,7 +3752,7 @@ export class QueryInterface {
             `${talias}.${this.q(col)}`,
         ]);
         if (spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3476,7 +3762,7 @@ export class QueryInterface {
                 const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'
                     ? this.dialect.nullJsonLiteral
                     : this.dialect.emptyJsonArrayLiteral;
-                jsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                jsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
             }
         }
         const jsonObj = this.dialect.buildJsonObject(jsonPairs);