turbine-orm 0.81.0 → 0.90.0

package/dist/query/builder.js

@@ -12,105 +12,75 @@
  */
 import { acquireConnection, openCheckout } from '../checkout.js';
 import { settleEventLoop } from '../connection-guard.js';
+import { resolveDiagnostics } from '../diagnostics.js';
 import { postgresDialect } from '../dialect.js';
-import { explainConnectionLoss, isStaleConnectionError, NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
+import { explainConnectionLoss, INVARIANT_REPORT_HINT, InvariantError, isStaleConnectionError, NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
+import { consoleLogger, logTo } from '../logger.js';
 import { executeNestedCreate, executeNestedUpdate, extractRelationFields, hasRelationFields, } from '../nested-write.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
+import { transactionStateOf, withSavepoint } from '../transaction-state.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, } from './compound-unique.js';
-import { dedupeColumnList, dedupeOrderEntries, isEmptyOrderBy, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
+import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, uniqueKeyNames, whereIdentifiesOneRow, } from './compound-unique.js';
+import { resolveExcludedFromCreate } from './expr.js';
+import { cursorFieldValue, dedupeColumnList, dedupeOrderEntries, isEmptyOrderBy, isJsonPathOrderBy, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, operandColumnKind, orderByEntries, sortedEntries, } from './filters.js';
+import { assertCursorNotEmptied, assertCursorWritten, assertWhereNotEmptiedByPruning, hasCursor, isCursorInclusive, pruneUndefinedArgs, } from './normalize-args.js';
 import { warnUnknownQueryOptions } from './option-surface.js';
-import { applyStableRelationOrderTo, normalizeWithClause } from './relation-names.js';
+import { applyStableRelationOrderTo, normalizeWithClause, normalizeWithPagination } from './relation-names.js';
 import * as relationsMod from './relations.js';
+import { lockOnStreamMessage, lockOutsideTransactionMessage, lockWithDistinctMessage, resolveRowLock, } from './row-lock.js';
+import { resolveSqlComment } from './sql-comment.js';
+import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, newStreamIdleState, resolveStreamIdleTimeout, StreamIdleGuard, streamBackstopStatement, streamIdleExpiredError, watchStreamConnection, } from './stream-idle.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { availableClause, isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
-import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
+import { assertMiddlewareArgsKept, availableClause, boundedPreparedName, canCancelBackend, isNodePostgresPool, isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, readJsonFloat, readJsonFloatArray, readOnlyMiddlewareParams, readTextArray, resolveColumnName, resolveRelation, resolveRelationDef, sendCancelRequest, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
+import { resetWarnOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
 /**
- * SQL-cache lockstep cross-check gate.
+ * SQL-cache lockstep cross-check.
  *
  * The SQL template cache requires three code paths to enumerate where-clause
  * keys identically: `fingerprintWhere` (builds the cache key),
  * `buildWhereClause` (builds SQL + `$N` params on a MISS), and
  * `collectWhereParams` (re-collects params on a HIT without rebuilding). Since
  * 0.36 all three consume ONE shared where-key walk (see `where-compile.ts`), so
- * enumeration drift is structurally eliminated; this check remains as a
+ * enumeration drift is structurally eliminated; these checks remain as a
  * tripwire in case a future leaf builder or its collect mirror falls out of
- * step. It rebuilds the SQL + params fresh on a cache HIT and compares them
- * against what the cache-hit path produced.
+ * step. Every failure is an {@link InvariantError} (E020), thrown before the
+ * statement is sent.
  *
- * Modes (decided per HIT; env read inline, not captured once, so tests and
- * perf-sensitive traffic can toggle per process):
- * - `'dev'`: `NODE_ENV !== 'production'` and `TURBINE_DISABLE_CACHE_CHECK !== '1'`
- *   (always checks; the historical default, the whole unit suite runs under it).
- * - `'off'`: dev with `TURBINE_DISABLE_CACHE_CHECK=1`, OR production with no
- *   sampling configured (the hot path is untouched).
- * - `'sampled'`: production with `TURBINE_CACHE_CHECK_SAMPLE` set to a float in
- *   `(0,1]`, re-verify that fraction of cache hits (per-hit `Math.random()`;
- *   `>= 1` checks every hit). A mismatch logs once per distinct fingerprint AND
- *   throws, same as dev. `0`, unset, or an unparseable value means never check.
- */
-function cacheCrossCheckMode() {
-    const env = crossCheckEnv ?? readCrossCheckEnv();
-    if (env.mode !== 'sampled')
-        return env.mode;
-    // The SAMPLING decision, and only it, is genuinely per hit.
-    return env.rate >= 1 || Math.random() < env.rate ? 'sampled' : 'off';
-}
-/**
- * The env-derived half of {@link cacheCrossCheckMode}, resolved ONCE per
- * process and memoized.
- *
- * `process.env` is not a plain object: every property read crosses a C++
- * interceptor. Measured at 112.7 ns per read against 3.6 ns for a module-level
- * constant, and this function ran TWO reads on every cache hit, which put it
- * at the top of the SQL-build CPU profile (12.53% self time, with a further
- * ~12% inside the interceptor) for a value that does not change.
- *
- * It is memoized rather than hoisted to a `const` because the toggle IS
- * observed at runtime, contrary to what a quick look suggests: the
- * cross-check and sampling suites flip `NODE_ENV` /
- * `TURBINE_DISABLE_CACHE_CHECK` / `TURBINE_CACHE_CHECK_SAMPLE` around a
- * synchronous block in-process, not at spawn. So the read is deferred to first
- * use and {@link resetCacheCrossCheckEnv} re-arms it; that is the entire
- * contract, and the only thing lost versus reading every time is that a
- * process which mutates these variables mid-run must say so.
- */
-let crossCheckEnv;
-function readCrossCheckEnv() {
-    let resolved;
-    if (process.env.NODE_ENV !== 'production') {
-        resolved = { mode: process.env.TURBINE_DISABLE_CACHE_CHECK === '1' ? 'off' : 'dev' };
-    }
-    else {
-        const raw = process.env.TURBINE_CACHE_CHECK_SAMPLE;
-        const rate = raw === undefined ? Number.NaN : Number.parseFloat(raw);
-        resolved = !Number.isFinite(rate) || rate <= 0 ? { mode: 'off' } : { mode: 'sampled', rate };
-    }
-    crossCheckEnv = resolved;
-    return resolved;
-}
-/**
- * Discard the memoized cross-check environment so the next cache hit re-reads
- * `process.env`.
+ * Two checks always run, whatever the diagnostics mode, because each costs one
+ * array compare and the alternative is executing parameters known to be wrong:
+ * - On a MISS, the params the build closure pushed are compared with the params
+ *   the collect path produced (`sql-cache-lockstep`). The miss already paid
+ *   for both walks, and a shape run once per instance is otherwise never
+ *   compared at all.
+ * - On a HIT, the collected param count must equal the count the entry was
+ *   built with (`sql-cache-param-count`). Otherwise the server would reject
+ *   the statement with a bind error that reads like a connection problem.
  *
- * @internal Exposed for the tests that toggle these variables in-process (see
- * {@link crossCheckEnv}). Production code sets them before the first query and
- * never again.
+ * The full rebuild-and-compare on a HIT follows the client's
+ * `diagnostics.cacheCheck`, resolved once at construction (see diagnostics.ts;
+ * the legacy `TURBINE_DISABLE_CACHE_CHECK` / `TURBINE_CACHE_CHECK_SAMPLE`
+ * variables are read there and nowhere else):
+ * - `'every-hit'` (the development default): every hit is compared, and a
+ *   mismatch throws.
+ * - `{ sample }`: that fraction of hits is compared (per-hit `Math.random()`;
+ *   a sample of 1 compares every hit). A mismatch is logged at `error` once
+ *   per distinct fingerprint, then throws.
+ * - `'off'` (the production default): never rebuilt on a hit.
  */
-export function resetCacheCrossCheckEnv() {
-    crossCheckEnv = undefined;
-}
 /**
- * Distinct cache-mismatch fingerprints already logged by the sampled production
- * cross-check, so a hot mismatch logs `console.error` exactly once per shape
- * instead of flooding the log. Dev mode does not log (it throws immediately),
- * so this set is only ever touched on the `'sampled'` path.
+ * Warn-once namespace for the sampled cross-check's mismatch log, so a hot
+ * mismatch logs exactly once per table and shape instead of flooding the log.
+ * `'every-hit'` does not log (it throws immediately), so only the sampled path
+ * records here. Keyed on the TABLE as well as the fingerprint: the fingerprint
+ * alone carries no table, so a mismatch on one table used to silence the same
+ * shape's mismatch on every other table. The shared registry also bounds the
+ * set (`WARN_ONCE_CAP`) and is what `resetWarnOnce` clears.
  */
-const loggedCacheMismatchFingerprints = new Set();
+const CACHE_MISMATCH_WARN_NS = 'cacheMismatch';
 /**
  * Marginal cost of keeping a to-one relation on the JOIN plan, per parent row.
  *
@@ -268,6 +238,29 @@ const ROW_PLAN_CACHE_SIZE = 128;
  * probe's own limit.
  */
 const STREAM_SPECULATION_MAX_BATCH = 1000;
+/** Per-cell decode work in a {@link RowDecodePlan}. */
+const CELL_PLAIN = 0;
+const CELL_TEMPORAL = 1;
+const CELL_FLOAT = 2;
+const CELL_FLOAT_ARRAY = 3;
+const CELL_TEXT_ARRAY = 4;
+/** The dialect's own decode for a type whose storage differs (see `Dialect.decodeColumnValue`). */
+const CELL_DIALECT = 5;
+const FLOAT_TYPES = new Set(['float4', 'float8', 'real', 'double precision']);
+const FLOAT_ARRAY_TYPES = new Set(['_float4', '_float8', 'float4[]', 'float8[]', 'real[]', 'double precision[]']);
+/**
+ * The decode a column of `pgType` needs beyond the driver's, other than
+ * temporal: a float can arrive from JSON as "NaN" / "Infinity", and an enum
+ * array, which the driver has no parser for, as array text.
+ */
+function cellKindOf(pgType, enums) {
+    if (FLOAT_TYPES.has(pgType))
+        return CELL_FLOAT;
+    if (FLOAT_ARRAY_TYPES.has(pgType))
+        return CELL_FLOAT_ARRAY;
+    const element = pgType.startsWith('_') ? pgType.slice(1) : pgType.endsWith('[]') ? pgType.slice(0, -2) : undefined;
+    return element !== undefined && enums !== undefined && Object.hasOwn(enums, element) ? CELL_TEXT_ARRAY : CELL_PLAIN;
+}
 /**
  * Strict structural equality for a single SQL parameter value. Handles the
  * value shapes Turbine binds: primitives (incl. `NaN` and `bigint`), `null`/
@@ -410,35 +403,95 @@ export function unlockNestedWriteTx(tx) {
  */
 // Moved to ./filters.ts in 0.74.0 so PowqlInterface consumes the SAME
 // predicate rather than a second copy of it. See applyStableRelationOrderTo.
+/**
+ * Marks `findMany` args built for a `findFirst`: one row, not a page, so
+ * {@link QueryInterface.completePageOrder} leaves its order as written. A
+ * symbol, so it survives the spreads at the args seam and no JSON body can
+ * set it. Set through {@link firstRowOnly} only.
+ */
+const FIRST_ROW_ONLY = Symbol('turbine.firstRowOnly');
+/**
+ * The {@link FIRST_ROW_ONLY} mark for a read the caller bounded with neither
+ * `limit` nor `offset`. An `offset` makes the row depend on which tied rows it
+ * skipped, so `findFirst({ orderBy, offset })` is a page of one and gets the
+ * page tiebreaker like any other page.
+ */
+function firstRowOnly(args) {
+    return args?.limit === undefined && args?.offset === undefined ? { [FIRST_ROW_ONLY]: true } : {};
+}
+/** The largest delay `setTimeout` honours; Node fires anything larger after 1 ms. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** The accepted `relationLoadStrategy` values. */
+const RELATION_LOAD_STRATEGIES = Object.freeze([
+    'join',
+    'batched',
+    'auto',
+    'flatten',
+]);
+/** A per-query `timeout`: milliseconds up to {@link MAX_TIMEOUT_MS}, or 0 for none (the same rule as `$transaction`). */
+function isValidTimeout(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= MAX_TIMEOUT_MS;
+}
+/** A short, value-safe rendering of a rejected option value. */
+function describeOptionValue(value) {
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'string')
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}...` : value);
+    return value === null ? 'null' : `a value of type ${typeof value}`;
+}
+function relationLoadStrategyMessage(value) {
+    return (`\`relationLoadStrategy\` must be one of ${RELATION_LOAD_STRATEGIES.map((v) => `'${v}'`).join(', ')} ` +
+        `(received ${describeOptionValue(value)}).`);
+}
+/** A value the findUnique simple path may bind as it is: a primitive, Date or Buffer. */
+function isFastPathScalar(value) {
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+            return true;
+        case 'object':
+            return value instanceof Date || (value !== null && ArrayBuffer.isView(value));
+        default:
+            return false;
+    }
+}
+/** Resolves a race when a deadline passes first. */
+const TIMED_OUT = Symbol('timedOut');
+/**
+ * How long a statement that outlived its `timeout` gets, after the cancel
+ * request is sent, to answer before its connection is destroyed instead of
+ * reused. A cancel normally lands within a round trip or two.
+ */
+const CANCEL_GRACE_MS = 2000;
+/** Whether `err` is PostgreSQL's query_canceled (57014), as the driver raised it or as Turbine wrapped it. */
+function isQueryCanceled(err) {
+    const e = err;
+    return e?.code === '57014' || e?.cause?.code === '57014';
+}
+/** The {@link DeferredQuery.rowLock} marker for a locking read, or nothing. */
+function rowLockMarker(rowLock) {
+    return rowLock ? { rowLock: true } : {};
+}
 /** The two accepted {@link JsonEncoding} values, frozen so the check is total. */
 const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
 /**
  * The relation JSON encoding a client on `dialect` gets when it names none.
  *
- * `'positional'` (`json_build_array`) on PostgreSQL, `'object'`
- * (`json_build_object`) everywhere else. The positional form drops the repeated
- * key names from every relation row: measured on a 50-parent / ~10-child read
- * against local PostgreSQL 17, server time 0.685 ms → 0.350 ms and 152 KB →
- * 100 KB on the wire, returning byte-identical parsed rows.
- *
- * ## Why the test is `dialect.name`, not "does the dialect have buildJsonArray"
- *
- * Because a presence test does not distinguish engines HERE. `buildJsonArray`
- * is declared on `postgresDialect`, and sqlite.ts / mysql.ts / mssql.ts /
- * powdb.ts each build their dialect by SPREADING it, so every engine inherits
- * the hook and an "is it absent" fallback never fires. That is the documented
- * inheritance trap (see `buildPartitionLimit` in {@link
- * QueryInterface.batchedContext} and the `distinct` gate in
- * {@link QueryInterface.buildFindMany}), and it is exactly the shape that
- * silently turned the partition-limit window on for SQLite.
+ * `'positional'` (`json_build_array`) where the engine has it (PostgreSQL),
+ * `'object'` (`json_build_object`) everywhere else. The positional form drops
+ * the repeated key names from every relation row: measured on a 50-parent /
+ * ~10-child read against local PostgreSQL 17, server time 0.685 ms → 0.350 ms
+ * and 152 KB → 100 KB on the wire, returning byte-identical parsed rows.
  *
- * A new capability flag would work, but only if every engine set it
- * explicitly, and it would be a SECOND authority on the same question:
- * `buildSelectWithRelations` (relations.ts) already refuses `'positional'` with
- * E017 on `dialect.name !== 'postgresql'`. Deriving the default from the
- * identical predicate is what makes it impossible for the default to select an
- * encoding the builder then refuses. A flag could drift from that refusal; this
- * cannot.
+ * Read from `capabilities.positionalJson`, never from whether the dialect has
+ * `buildJsonArray`: that hook is on `postgresDialect` and every engine inherits
+ * it by spreading, so a presence test would hand every engine the positional
+ * default. `buildSelectWithRelations` (relations.ts) refuses `'positional'` on
+ * the SAME flag, so the default can never select an encoding the builder then
+ * refuses: one authority, not two.
  *
  * A wire-compatible engine that reaches this on `postgresDialect` itself
  * (CockroachDB, YugabyteDB, AlloyDB, Timescale, all of which are ADAPTERS over
@@ -446,9 +499,8 @@ const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
  * which is correct: they speak `json_build_array`.
  */
 function defaultJsonEncoding(dialect) {
-    return dialect.name === 'postgresql' ? 'positional' : 'object';
+    return dialect.capabilities.positionalJson ? 'positional' : 'object';
 }
-// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known", intentional for untyped table access
 export class QueryInterface {
     pool;
     table;
@@ -469,6 +521,13 @@ export class QueryInterface {
      * inline, not through the top-level cache).
      */
     lastCacheHit = false;
+    /**
+     * The params the build closure pushed on the most recent MISS, held until
+     * {@link crossCheckCache} compares them with the collected params and clears
+     * them. `undefined` after a hit. Same single-flag reasoning as
+     * {@link lastCacheHit}.
+     */
+    lastMissParams;
     /**
      * Set while a build closure runs when the statement's WHERE (or HAVING)
      * carries a caller-written `AND`/`OR` combinator array, i.e. when its SQL text
@@ -480,6 +539,21 @@ export class QueryInterface {
      */
     variableArityShape = false;
     middlewares;
+    /** The client's resolved `diagnostics` (see diagnostics.ts), fixed for this instance's life. */
+    diagnostics;
+    /** `streamIdleTimeoutMs`: how long a cursor stream may wait for its consumer. `0` disables. */
+    streamIdleTimeoutMs;
+    /** `sqlComment`, resolved; `undefined` when statements carry no comment (one falsy check per send). */
+    sqlCommenter;
+    /** Where this instance's log lines go: the client's `logger`, else the console logger. */
+    logger;
+    /**
+     * {@link logger} when `diagnostics.advice` is on, else `undefined`. Every
+     * per-query advice site starts with `const log = this.advice; if (!log)
+     * return;`, so with advice off a site costs one property read and builds no
+     * message.
+     */
+    advice;
     defaultLimit;
     warnOnUnlimited;
     scopedConnect;
@@ -581,7 +655,6 @@ export class QueryInterface {
      * the audit's "Set<string>" guidance and leaves room for future
      * cross-table sharing.
      */
-    warnedTables = new Set();
     /** Cache hit/miss counters for diagnostics */
     cacheHits = 0;
     cacheMisses = 0;
@@ -602,6 +675,10 @@ export class QueryInterface {
      * to Date as well (otherwise nested dates leak through as strings).
      */
     camelDateFieldCache = new Map();
+    /** Per-table memo of {@link cellKindOf}, keyed by column name and field name. */
+    cellKindCache = new Map();
+    /** The dialect decode of each {@link CELL_DIALECT} column, by table, then by column and field name. */
+    dialectDecodeCache = new Map();
     /**
      * Per-table memo of `Object.entries(meta.relations)`, consumed by the nested
      * row parser (see `getRelationEntries` in relations.ts). Same rationale and
@@ -675,7 +752,14 @@ export class QueryInterface {
         }
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];
+        // Resolved by the client once; a QueryInterface built directly (tests,
+        // tooling) resolves here, at construction, never per call.
+        this.diagnostics = resolveDiagnostics(options?.diagnostics);
+        this.logger = options?.logger ?? consoleLogger;
+        this.advice = this.diagnostics.advice ? this.logger : undefined;
         this.defaultLimit = options?.defaultLimit;
+        this.streamIdleTimeoutMs =
+            resolveStreamIdleTimeout(options?.streamIdleTimeoutMs, 'streamIdleTimeoutMs') ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
         // Default to ON: surfacing accidental full-table scans is more valuable
         // than the (small) risk of noisy logs. Callers opt out globally with
         // `warnOnUnlimited: false`, per table with `warnOnUnlimited: { users:
@@ -712,6 +796,17 @@ export class QueryInterface {
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
         this.sqlTemplateCache = new LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? postgresDialect;
+        this.sqlCommenter =
+            options?._sqlCommenter ??
+                resolveSqlComment(options?.sqlComment, this.logger, {
+                    dialect: this.dialect.name,
+                    preparesEveryStatement: this.dialect.capabilities.preparesEveryStatement,
+                    buildsSql: true,
+                });
+        if (options?.relationLoadStrategy !== undefined &&
+            !RELATION_LOAD_STRATEGIES.includes(options.relationLoadStrategy)) {
+            throw new ValidationError(relationLoadStrategyMessage(options.relationLoadStrategy));
+        }
         this.relationLoadStrategy = options?.relationLoadStrategy ?? 'auto';
         this.stableRelationOrder = options?.stableRelationOrder === true;
         this.implicitPkOrdering = options?.implicitPkOrdering === true;
@@ -778,6 +873,8 @@ export class QueryInterface {
         // per `build*` call, so it is exposed as a LIVE getter (not a copied value).
         const self = this;
         this.ctx = {
+            diagnostics: this.diagnostics,
+            logger: this.logger,
             dialect: this.dialect,
             table: this.table,
             schema: this.schema,
@@ -844,7 +941,7 @@ export class QueryInterface {
         };
     }
     /**
-     * Dev-only, once per table: the columns whose database type is absent from
+     * Advice (`diagnostics.advice`), once per table: the columns whose database type is absent from
      * BOTH the column entry and the table-level type maps, the residual case
      * after the two-source resolution above.
      *
@@ -869,23 +966,24 @@ export class QueryInterface {
      *     Postgres rejects with `22007 invalid input syntax for type time`.
      *   - `timestamptz` and every non-temporal type: unaffected.
      *
-     * PostgreSQL only: the UTC bind rewrite is Postgres-gated (see
-     * `utcDateTimeWrites` in writes.ts), so on the other engines a missing type
-     * changes nothing about how a `Date` is bound. Suppressed under
-     * `NODE_ENV=production` like the other dev diagnostics and deduped through
-     * the shared registry, so a hot table logs one line for the process.
+     * PostgreSQL only: the zone-less `timestamp` rewrite is Postgres-gated (see
+     * `utcDateTimeRewrite` in where.ts), so on the other engines a missing type
+     * costs only the `date` rewrite. Silent when `diagnostics.advice` is off
+     * (the production default) like the other advice, and deduped through the
+     * shared registry, so a hot table logs one line for the process.
      *
      * Cannot throw on odd metadata: it walks `tableMeta.columns`, the array the
      * constructor loop above has already iterated (and that client.ts validates
      * as an array), never `dateColumns`, which is a `Set` in every first-party
      * metadata path but arrives as a plain object from JSON-round-tripped
-     * metadata. A dev-only diagnostic that crashes a shape production would serve
+     * metadata. An advisory diagnostic that crashes a shape production would serve
      * is worse than the bug it reports.
      */
     warnUntypedColumns() {
-        if (process.env.NODE_ENV === 'production')
+        const log = this.advice;
+        if (!log)
             return;
-        if (this.dialect.name !== 'postgresql')
+        if (!this.dialect.capabilities.utcTimestampRewrite)
             return;
         const untyped = [];
         for (const col of this.tableMeta.columns) {
@@ -901,14 +999,14 @@ export class QueryInterface {
         const MAX_NAMED = 12;
         const named = untyped.slice(0, MAX_NAMED).join(', ');
         const rest = untyped.length > MAX_NAMED ? ` (+${untyped.length - MAX_NAMED} more)` : '';
-        console.warn(`[turbine] table "${this.table}": no database type in metadata for column(s) ${named}${rest} (neither the ` +
+        logTo(log, 'warn', `table "${this.table}": no database type in metadata for column(s) ${named}${rest} (neither the ` +
             "column entry's `dialectType`/`pgType` nor the table-level `dialectTypes`/`pgTypes` map). Turbine cannot " +
             'tell which of them are zone-less, so it skips the UTC bind rewrite and a `Date` goes to the driver ' +
             "as-is: right for `timestamptz`, but a zone-less `date`/`timestamp` then stores the PROCESS's local " +
             'calendar fields rather than UTC (silently, since the read path shifts back by the same offset), and a ' +
             '`time`/`timetz` column rejects the value outright (`22007 invalid input syntax for type time`). ' +
             'Columns whose type IS resolved, every `timestamptz` among them, are unaffected. Fix: regenerate with ' +
-            '`npx turbine generate`, or set the column types in `defineSchema`.');
+            '`npx turbine generate`, or set the column types in `defineSchema`.', { code: 'untyped-columns', table: this.table, columns: untyped });
     }
     /** Quote an identifier through the active SQL dialect. */
     q(name) {
@@ -1075,24 +1173,63 @@ export class QueryInterface {
      * query/relation-names.ts.
      */
     withDeclaredRelationNames(args) {
-        if (!args?.with)
+        const withClause = args?.with;
+        if (!withClause)
+            return args;
+        const normalized = normalizeWithClause(this.schema, this.table, withClause);
+        return normalized === withClause ? args : { ...args, with: normalized };
+    }
+    /**
+     * `args` with `take` / `skip` folded into `limit` / `offset` at every `with`
+     * level (see `normalizeWithPagination` in query/relation-names.ts). Runs after
+     * the relation-name pass, so it resolves the declared spelling.
+     */
+    withRelationPagination(args) {
+        const withClause = args?.with;
+        if (!withClause)
             return args;
-        const normalized = normalizeWithClause(this.schema, this.table, args.with);
-        return normalized === args.with ? args : { ...args, with: normalized };
+        const normalized = normalizeWithPagination(this.schema, this.table, withClause);
+        return normalized === withClause ? args : { ...args, with: normalized };
     }
     /**
-     * Caller args in canonical form: declared relation spellings, and the Prisma
-     * pagination aliases folded into `limit` / `offset`.
+     * Caller args in canonical form: `undefined` pruned (query/normalize-args.ts),
+     * declared relation spellings, and the Prisma pagination aliases folded into
+     * `limit` / `offset`, with `take` / `skip` folded inside every `with` level too.
      *
-     * ONE method rather than two calls at each seam, because the two
-     * normalizations have the same requirement and the same failure mode: both
-     * must happen before `withFingerprint` / the cache key, and a seam that
-     * applies one but not the other is a seam where the alias survives into a
-     * fingerprint. Both return their input by reference when there was nothing to
-     * change, so the common path still allocates nothing.
+     * Called at the seam of EVERY public operation and its `build*` twin, so the
+     * guards, the fingerprint, the build and the collect all read one shape. Each
+     * step returns its input by reference when there was nothing to change, so a
+     * second call on already-normalized args is free and the common path
+     * allocates nothing.
+     *
+     * `refuseEmptiedWhere` names the single-row read (`findFirst`,
+     * `findFirstOrThrow`) that refuses a `where` whose every key was `undefined`.
+     */
+    normalizeArgs(args, refuseEmptiedWhere) {
+        const pruned = pruneUndefinedArgs(this.schema, this.table, args);
+        if (pruned !== args) {
+            if (refuseEmptiedWhere)
+                assertWhereNotEmptiedByPruning(this.table, refuseEmptiedWhere, args, pruned);
+            assertCursorNotEmptied(this.table, args, pruned);
+        }
+        if (pruned)
+            this.assertQueryOptions(pruned);
+        return normalizePagination(this.withRelationPagination(this.withDeclaredRelationNames(pruned)));
+    }
+    /**
+     * Validate the per-query options whose bad values used to be ignored or
+     * misread: `timeout` (Node clamps a non-positive, non-finite or oversized
+     * delay to 1 ms) and `relationLoadStrategy`.
      */
-    normalizeArgs(args) {
-        return normalizePagination(this.withDeclaredRelationNames(args));
+    assertQueryOptions(args) {
+        const { timeout, relationLoadStrategy } = args;
+        if (timeout !== undefined && !isValidTimeout(timeout)) {
+            throw new ValidationError(`\`timeout\` on ${this.table} must be a positive number of milliseconds up to ${MAX_TIMEOUT_MS}, or 0 for ` +
+                `no timeout (received ${describeOptionValue(timeout)}). Leave it out for no timeout.`);
+        }
+        if (relationLoadStrategy !== undefined && !RELATION_LOAD_STRATEGIES.includes(relationLoadStrategy)) {
+            throw new ValidationError(relationLoadStrategyMessage(relationLoadStrategy));
+        }
     }
     /**
      * Refuse a `findUnique` whose `where` names no unique key. The rule and the
@@ -1102,6 +1239,30 @@ export class QueryInterface {
     assertFindUniqueKey(where) {
         assertWhereIdentifiesOneRow(this.tableMeta, this.table, where);
     }
+    /**
+     * Refuse a locking read that is not inside a transaction, at the execute
+     * entry of each find method and before any strategy runs. The `build*`
+     * methods accept `lock` (the SQL is right wherever it runs); executing it
+     * in autocommit releases the lock before the caller sees the rows.
+     *
+     * The value is validated first, so an engine with no row locks answers
+     * E017 rather than asking for a transaction it would also refuse.
+     * "Inside a transaction" is `_txScoped`: the accessors a TransactionClient
+     * hands out, at any nesting depth.
+     */
+    assertLockInTransaction(args, operation) {
+        if (args?.lock === undefined)
+            return;
+        resolveRowLock(args.lock, this.dialect, this.table);
+        if (!this.txScoped)
+            throw new ValidationError(lockOutsideTransactionMessage(this.table, operation));
+    }
+    /** Refuse `lock` on a streaming read (a cursor is not a locking read). */
+    assertNoStreamLock(args, operation) {
+        if (args?.lock !== undefined) {
+            throw new ValidationError(lockOnStreamMessage(this.table, operation));
+        }
+    }
     /**
      * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
      * explicit one, recursing into nested `with`. Returns a CLONED clause (user
@@ -1134,146 +1295,325 @@ export class QueryInterface {
         const fields = pk.map((c) => this.tableMeta.reverseColumnMap[c] ?? c);
         return fields.length === 1 ? { [fields[0]]: 'asc' } : fields.map((f) => ({ [f]: 'asc' }));
     }
+    /** Memo for {@link totalOrderKeys}; table metadata is immutable. */
+    totalOrderKeysMemo;
     /**
-     * The field names a `cursor` actually seeks on (its own keys with a defined
-     * value), in canonical sorted order. This is the diagnostic / implicit-
-     * ordering view; the seek itself orders the fields by their `orderBy`
-     * precedence (see {@link cursorSeekEntries}). Empty for a missing cursor or
-     * one whose every value is `undefined` (which emits no seek condition at
-     * all, so it does not paginate).
+     * The unique keys whose columns are all NOT NULL, primary key first: the
+     * column sets that make an order total (no two rows can tie on them).
      */
-    cursorFields(cursor) {
-        if (!cursor || typeof cursor !== 'object')
+    totalOrderKeys() {
+        if (this.totalOrderKeysMemo)
+            return this.totalOrderKeysMemo;
+        const meta = this.tableMeta;
+        const nullable = (column) => !meta.primaryKey.includes(column) && meta.columns.find((c) => c.name === column)?.nullable === true;
+        this.totalOrderKeysMemo = uniqueKeyNames(meta).filter((cols) => cols.every((c) => !nullable(c)));
+        return this.totalOrderKeysMemo;
+    }
+    /**
+     * THE tiebreaker rule, shared by cursor pages ({@link planCursor}) and the
+     * pages before them ({@link completePageOrder}), so every page of one walk
+     * is cut from the same total order: the columns to append to an order over
+     * `ordered` so that no two rows tie. `[]` when the order already contains a
+     * unique NOT NULL key; the first such key's missing columns otherwise;
+     * `undefined` when the table has none.
+     */
+    tiebreakColumns(ordered) {
+        const keys = this.totalOrderKeys();
+        if (keys.some((cols) => cols.every((c) => ordered.has(c))))
             return [];
-        return Object.entries(cursor)
-            .filter(([, v]) => v !== undefined)
-            .map(([k]) => k)
-            .sort();
+        return keys[0]?.filter((c) => !ordered.has(c));
     }
     /**
-     * The ascending ordering implied by a `cursor`, or `undefined` when the shape
-     * is too ambiguous to order safely.
-     *
-     * A cursor seek compares against the cursor's own field(s) (`col > $n`, `<`
-     * when the orderBy says desc), so the ONLY ordering coherent with it is on
-     * those fields: ordering a seek on column X by column Y walks the table in an
-     * order the seek does not follow, which skips and repeats rows just as badly
-     * as no order at all. That is why this orders on the cursor field rather than
-     * blindly on the primary key when the two differ.
+     * A paginated `findMany` (`limit` / `offset`) whose `orderBy` can tie gets
+     * the tiebreaker appended, in the last term's direction, so a page boundary
+     * cannot fall between tied rows in a different order on each page (skipping
+     * or repeating one), and the first page of a cursor walk uses the order its
+     * cursor pages use. Returns `args` itself when the order is already total,
+     * the query is not paginated, or it pages by `cursor` or `distinct`, which
+     * order themselves. A `findFirst` with no `offset` is one row, not a page,
+     * and is left alone.
      *
-     * Returns `undefined` (warn, inject nothing) for two shapes:
-     *  - a MULTI-field cursor. The seek is a proper keyset predicate, but its
-     *    column PRECEDENCE comes from the `orderBy` ({@link cursorSeekEntries}),
-     *    and with no orderBy there is nothing to derive it from: the cursor
-     *    object's key order is canonicalized away, so `(a asc, b asc)` would be a
-     *    guess at which key the caller meant to lead. The caller must state the
-     *    order, and the unordered-page warning says so.
-     *  - a field that does not resolve to a real column. Column validation belongs
-     *    to the normal build path, which raises a precise error; synthesizing an
-     *    ORDER BY on it here would only change which error the caller sees.
+     * An order containing a vector distance gets no tiebreaker: a KNN index
+     * serves only `ORDER BY <distance> LIMIT k`, a compound order turns that
+     * into a scan and sort of the whole table, and two equal distances are
+     * rare. A `cursor` still refuses such an order (see {@link planCursor}).
      */
-    cursorOrderBy(cursor) {
-        const fields = this.cursorFields(cursor);
-        if (fields.length !== 1)
-            return undefined;
-        const field = fields[0];
-        try {
-            this.toColumn(field);
-        }
-        catch {
-            return undefined;
+    completePageOrder(args) {
+        if (args.orderBy === undefined || (args.limit === undefined && args.offset === undefined))
+            return args;
+        if (hasCursor(args.cursor) || (args.distinct && args.distinct.length > 0))
+            return args;
+        if (args[FIRST_ROW_ONLY])
+            return args;
+        const entries = orderByEntries(args.orderBy).filter(([, d]) => d !== undefined);
+        if (entries.some(([, d]) => isVectorOrderBy(d)))
+            return args;
+        const ordered = new Set();
+        let lastDesc = false;
+        for (const [key, dir] of entries) {
+            lastDesc = false;
+            if (isVectorOrderBy(dir) || isJsonPathOrderBy(dir) || this.isRelationOrderByValue(dir))
+                continue;
+            const column = resolveColumnName(this.tableMeta, key);
+            if (column === undefined)
+                continue;
+            ordered.add(column);
+            lastDesc = normalizeOrderBy(dir).dir === 'DESC';
         }
-        return { [field]: 'asc' };
+        const missing = this.tiebreakColumns(ordered);
+        if (!missing || missing.length === 0)
+            return args;
+        const dir = lastDesc ? 'desc' : 'asc';
+        const field = (column) => this.tableMeta.reverseColumnMap[column] ?? column;
+        return {
+            ...args,
+            orderBy: [...entries.map(([k, v]) => ({ [k]: v })), ...missing.map((c) => ({ [field(c)]: dir }))],
+        };
     }
     /**
-     * The fields a `cursor` seeks on, in KEYSET order with their seek direction.
-     * THE single authority the cache fingerprint (`cur=`), the SQL build and the
-     * cache-hit param collect all consume, so the three cannot disagree about
-     * which value binds to which `$n`.
+     * Plan a `cursor` page: THE single authority the cache key, the SQL build and
+     * the cache-hit param collect all read, so the three cannot disagree.
      *
-     * Keyset order is the `orderBy` precedence: the predicate for
-     * `orderBy: [{ viewCount }, { id }]` must test `view_count` first and `id`
-     * only within equal `view_count`, whatever order the caller wrote the cursor
-     * object in (its keys are canonicalized for the cache anyway). A cursor field
-     * the orderBy does not name trails the named ones in sorted key order and
-     * seeks ascending, the same default a single-field cursor with no orderBy has
-     * always had.
+     * The page is ordered by the EFFECTIVE order: the caller's `orderBy` plus a
+     * tiebreaker (the primary key, else a unique key on NOT NULL columns) when
+     * the orderBy does not already end in one, in the last term's direction. A
+     * cursor query is always ordered, because a seek over rows the engine may
+     * return in any order skips and repeats rows. `args.orderBy` is rewritten to
+     * that order (by reference when nothing changes).
      *
-     * Directions are indexed by the RESOLVED COLUMN, never the caller's key: both
-     * `cursor` and `orderBy` take either spelling, so a cursor written
-     * `{ created_at }` against `orderBy: { createdAt: 'desc' }` used to miss the
-     * lookup, default to ascending, and seek the wrong side of the page. The
-     * `{ sort, nulls }` spec form is normalized for the same reason. A relation /
-     * JSON-path / vector orderBy key resolves to no column and is skipped.
+     * Two ways to place the page, picked from what the cursor carries:
+     *  - VALUES: the cursor has a value for every column of the effective order,
+     *    so the seek compares against them directly (`col > $1`, expanded to a
+     *    keyset across several columns). Extra cursor fields are ignored.
+     *  - ROW: otherwise the cursor must identify one row by a unique key (the
+     *    findUnique rule), and the seek reads that row's ordered values in
+     *    scalar subqueries, guarded by `EXISTS` so a deleted cursor row gives an
+     *    empty page rather than a wrong one.
+     * Anything else is refused (E003) naming the missing fields.
      *
-     * An unknown cursor field throws the same E003 here that the build path
-     * threw before this helper existed; the fingerprint simply meets it first.
+     * NULL sort keys are placed where the engine sorts them (PostgreSQL: last
+     * ascending, first descending; SQLite / MySQL / SQL Server: NULL is smallest)
+     * or where an explicit `nulls` puts them, and each row is visited exactly
+     * once. On PostgreSQL a nullable ordered column has its placement written
+     * out, so a Postgres-compatible engine with a different default reads the
+     * same order the seek assumes.
      */
-    cursorSeekEntries(cursor, orderBy) {
-        const orderPos = new Map();
-        const orderDesc = new Map();
-        for (const [ok, od] of orderByEntries(orderBy)) {
-            const ocol = resolveColumnName(this.tableMeta, ok);
-            if (ocol === undefined)
+    planCursor(args) {
+        const raw = args.cursor;
+        if (!hasCursor(raw))
+            return { args, plan: undefined };
+        const meta = this.tableMeta;
+        const field = (column) => meta.reverseColumnMap[column] ?? column;
+        const nullableColumn = (column) => !meta.primaryKey.includes(column) && meta.columns.find((c) => c.name === column)?.nullable === true;
+        // The cursor's own values, by resolved column (either spelling, or a
+        // compound-unique selector, is accepted). Each is a row's value, checked
+        // by the rule every engine shares (cursorFieldValue).
+        const flat = expandCompoundUniqueWhere(meta, raw);
+        const cursorValues = new Map();
+        for (const [key, written] of sortedEntries(flat)) {
+            if (written === undefined)
                 continue;
-            if (!orderPos.has(ocol))
-                orderPos.set(ocol, orderPos.size);
-            // Last wins, matching object-key semantics (duplicates are refused
-            // upstream anyway, so in practice there is exactly one).
-            orderDesc.set(ocol, isOrderBySpec(od) ? od.sort === 'desc' : od === 'desc');
-        }
-        const entries = sortedEntries(cursor)
-            .filter(([, v]) => v !== undefined)
-            .map(([k, value]) => {
-            const column = this.toColumn(k);
-            return { column, value, desc: orderDesc.get(column) === true };
-        });
-        // Stable sort over the canonical (sorted-key) list: orderBy precedence
-        // first, unnamed fields after it in their sorted order.
-        return entries.sort((a, b) => (orderPos.get(a.column) ?? Number.MAX_SAFE_INTEGER) - (orderPos.get(b.column) ?? Number.MAX_SAFE_INTEGER));
+            const column = this.toColumn(key);
+            const value = cursorFieldValue(key, written, {
+                column,
+                table: this.table,
+                kind: operandColumnKind(this.getColumnPgType(column)),
+                nullable: nullableColumn(column),
+            });
+            cursorValues.set(column, value);
+        }
+        if (cursorValues.size === 0)
+            return { args, plan: undefined };
+        // The caller's order, plain columns only: a relation, JSON-path or vector
+        // ordering has no value a seek can compare against.
+        const terms = [];
+        const orderEntries = orderByEntries(args.orderBy).filter(([, d]) => d !== undefined);
+        for (const [key, dir] of orderEntries) {
+            if (isVectorOrderBy(dir) || isJsonPathOrderBy(dir) || this.isRelationOrderByValue(dir)) {
+                throw new ValidationError(`findMany on "${this.table}" refused: \`cursor\` cannot page past the orderBy entry "${key}", which ` +
+                    'orders by a relation, a JSON path or a vector distance rather than a column. Order the cursor ' +
+                    'query by columns only, or page it with `offset`.');
+            }
+            const column = this.toColumn(key);
+            if (terms.some((t) => t.column === column))
+                continue;
+            const { dir: d, nulls } = normalizeOrderBy(dir);
+            terms.push({ column, key, desc: d === 'DESC', nulls, nullable: nullableColumn(column) });
+        }
+        // Tiebreaker, the same one a first page gets (see tiebreakColumns).
+        const tiebreak = this.tiebreakColumns(new Set(terms.map((t) => t.column)));
+        if (!tiebreak) {
+            throw new ValidationError(`findMany on "${this.table}" refused: a \`cursor\` page needs an order with no ties, and "${this.table}" ` +
+                'has no primary key or unique key on NOT NULL columns to break them. Add a primary key, or page ' +
+                'this table with `offset`.');
+        }
+        const desc = terms.length > 0 ? terms[terms.length - 1].desc : false;
+        for (const column of tiebreak) {
+            terms.push({ column, key: field(column), desc, nulls: undefined, nullable: false });
+        }
+        const appended = tiebreak.length > 0;
+        // Where NULLs sort, per term. Where the engine sorts them high (PostgreSQL)
+        // a nullable column's placement is written out, so a Postgres-compatible
+        // engine with a different default reads the order the seek assumes.
+        const { nullsSortHigh, nullsOrderingClause } = this.dialect.capabilities;
+        const pinNulls = nullsSortHigh && nullsOrderingClause;
+        let pinned = false;
+        for (const t of terms) {
+            if (t.nulls === undefined && t.nullable && pinNulls) {
+                t.nulls = t.desc ? 'first' : 'last';
+                t.pin = true;
+                pinned = true;
+            }
+        }
+        const nullsFirst = (t) => t.nulls !== undefined ? t.nulls === 'first' : nullsSortHigh ? t.desc : !t.desc;
+        let nextArgs = args;
+        if (appended || pinned) {
+            const orderBy = terms.map((t) => {
+                const dir = t.desc ? 'desc' : 'asc';
+                const original = orderEntries.find(([k]) => k === t.key)?.[1];
+                return { [t.key]: t.pin ? { sort: dir, nulls: t.nulls } : (original ?? dir) };
+            });
+            nextArgs = { ...args, orderBy };
+        }
+        const inclusive = isCursorInclusive(args);
+        const coerce = (column, value) => whereMod.coerceWhereOperand(this.ctx, meta, column, value);
+        const keysetTerms = terms.map((t) => ({
+            column: t.column,
+            desc: t.desc,
+            nullsFirst: nullsFirst(t),
+            nullable: t.nullable,
+        }));
+        // An inclusive cursor (prisma-compat) names a ROW, as Prisma's does, so it
+        // always reads that row: a deleted cursor row gives an empty page, never a
+        // page placed where the row used to be.
+        const namesRow = inclusive && whereIdentifiesOneRow(meta, flat);
+        if (!namesRow && terms.every((t) => cursorValues.has(t.column))) {
+            const values = terms.map((t) => {
+                const v = cursorValues.get(t.column);
+                return v === null ? null : coerce(t.column, v);
+            });
+            const fp = `v:${keysetTerms.map((t, i) => `${t.column}:${t.desc ? 'd' : 'a'}${t.nullable ? (t.nullsFirst ? 'f' : 'l') : ''}${values[i] === null ? '0' : ''}`).join(',')}` +
+                (inclusive ? ':i' : '');
+            return {
+                args: nextArgs,
+                plan: { mode: 'values', terms: keysetTerms, values, lookup: [], inclusive, fingerprint: fp },
+            };
+        }
+        if (!whereIdentifiesOneRow(meta, flat)) {
+            const missing = terms.filter((t) => !cursorValues.has(t.column)).map((t) => `"${field(t.column)}"`);
+            const order = terms.map((t) => `${field(t.column)} ${t.desc ? 'desc' : 'asc'}`).join(', ');
+            const keys = uniqueKeyNames(meta).map((cols) => cols.length === 1 ? `{ ${field(cols[0])} }` : `{ ${cols.map(field).join(', ')} }`);
+            throw new ValidationError(`findMany on "${this.table}" refused: the \`cursor\` has no value for ${missing.join(', ')}, which the ` +
+                `page order (${order}) needs, and it does not name one row by a unique key. Give the cursor a value ` +
+                `for every ordered field, or name the cursor row by ${keys.length > 0 ? keys.join(' or ') : 'a unique key'}.`);
+        }
+        const lookup = [...cursorValues].map(([column, v]) => ({ column, value: v === null ? null : coerce(column, v) }));
+        const fp = `r:${keysetTerms.map((t) => `${t.column}:${t.desc ? 'd' : 'a'}${t.nullable ? (t.nullsFirst ? 'f' : 'l') : ''}`).join(',')}` +
+            `|k=${lookup.map((l) => `${l.column}${l.value === null ? '0' : ''}`).join(',')}` +
+            (inclusive ? ':i' : '');
+        return {
+            args: nextArgs,
+            plan: { mode: 'row', terms: keysetTerms, values: [], lookup, inclusive, fingerprint: fp },
+        };
     }
     /**
-     * The keyset predicate for cursor terms in keyset order.
-     *
-     * One field is the plain `col > $1` (byte-identical to every single-field
-     * cursor ever emitted). Two or more expand to
-     * `(c1 > $1 OR (c1 = $1 AND c2 > $2) OR (c1 = $1 AND c2 = $2 AND c3 > $3))`,
-     * with `<` for a `desc` field: the row-value form `(c1, c2) > ($1, $2)` is
-     * shorter, but it cannot express a MIXED direction at all and SQL Server has
-     * no row-value comparison, so the expanded form is the one path every engine
-     * and every direction set share. Each value is bound ONCE and its `$n` is
-     * referenced by every branch that needs it (legal on every supported
-     * placeholder syntax), which is what keeps the param count equal to the field
-     * count on both the build and the collect side.
+     * Render a {@link CursorPlan}'s seek predicate, pushing its params. Run by
+     * the build AND by the cache-hit collect (which discards the SQL), so the two
+     * cannot bind different params.
      *
-     * The former `c1 > $1 AND c2 > $2` was a conjunction, not a seek: it skipped
-     * every row whose leading key EQUALED the cursor's, so a table with few
-     * distinct leading values lost most of its rows across a page walk, silently.
+     * Each value is bound once and referenced by every branch that needs it. One
+     * non-null column is the plain `col > $1`; several expand to
+     * `(c1 > $1 OR (c1 = $1 AND c2 > $2) OR ...)`, with `<` for a descending
+     * column (a row-value comparison cannot mix directions, and SQL Server has
+     * none). A nullable column gets NULL-aware equality and "after" terms.
      */
-    keysetPredicate(terms) {
-        const compare = (t) => `${t.column} ${t.desc ? '<' : '>'} ${t.placeholder}`;
-        if (terms.length === 1)
-            return compare(terms[0]);
-        const branches = terms.map((term, i) => {
+    renderCursorPredicate(plan, params) {
+        const qt = this.q(this.table);
+        const col = (t) => `${qt}.${this.q(t.column)}`;
+        let ref;
+        let guard = '';
+        if (plan.mode === 'values') {
+            const refs = plan.values.map((v) => {
+                if (v === null)
+                    return null;
+                params.push(v);
+                return this.p(params.length);
+            });
+            ref = (i) => refs[i] ?? null;
+        }
+        else {
+            const alias = 'cursor_row';
+            const conds = plan.lookup.map((l) => {
+                if (l.value === null)
+                    return `${alias}.${this.q(l.column)} IS NULL`;
+                params.push(l.value);
+                return `${alias}.${this.q(l.column)} = ${this.p(params.length)}`;
+            });
+            const gf = whereMod.targetGlobalFilterAlias(this.ctx, this.table, alias, params);
+            if (gf)
+                conds.push(gf);
+            const from = `FROM ${qt} ${alias} WHERE ${conds.join(' AND ')}`;
+            ref = (i) => `(SELECT ${alias}.${this.q(plan.terms[i].column)} ${from})`;
+            guard = `EXISTS (SELECT 1 ${from})`;
+        }
+        // Value mode knows each value; row mode knows only whether the column can
+        // hold NULL, so its comparisons stay NULL-aware for nullable columns.
+        const rowMode = plan.mode === 'row';
+        const eq = (i) => {
+            const t = plan.terms[i];
+            const r = ref(i);
+            if (r === null)
+                return `${col(t)} IS NULL`;
+            if (rowMode && t.nullable)
+                return `(${col(t)} = ${r} OR (${col(t)} IS NULL AND ${r} IS NULL))`;
+            return `${col(t)} = ${r}`;
+        };
+        const after = (i, orEqual) => {
+            const t = plan.terms[i];
+            const r = ref(i);
+            const op = `${t.desc ? '<' : '>'}${orEqual ? '=' : ''}`;
+            if (r === null)
+                return t.nullsFirst ? `${col(t)} IS NOT NULL` : null;
+            if (!t.nullable)
+                return `${col(t)} ${op} ${r}`;
+            if (rowMode) {
+                return t.nullsFirst
+                    ? `((${r} IS NULL AND ${col(t)} IS NOT NULL) OR ${col(t)} ${op} ${r})`
+                    : `(${r} IS NOT NULL AND (${col(t)} ${op} ${r} OR ${col(t)} IS NULL))`;
+            }
+            return t.nullsFirst ? `${col(t)} ${op} ${r}` : `(${col(t)} ${op} ${r} OR ${col(t)} IS NULL)`;
+        };
+        const n = plan.terms.length;
+        const last = n - 1;
+        // An inclusive page folds "equal on every column" into the last branch when
+        // that column is NOT NULL and its value known non-null (`>=`); otherwise it
+        // is its own branch.
+        const foldEqual = plan.inclusive && !plan.terms[last].nullable && ref(last) !== null;
+        const branches = [];
+        for (let i = 0; i < n; i++) {
+            const a = after(i, foldEqual && i === last);
+            if (a === null)
+                continue;
             if (i === 0)
-                return compare(term);
-            const prefix = terms.slice(0, i).map((t) => `${t.column} = ${t.placeholder}`);
-            return `(${[...prefix, compare(term)].join(' AND ')})`;
-        });
-        return `(${branches.join(' OR ')})`;
+                branches.push(a);
+            else
+                branches.push(`(${[...plan.terms.slice(0, i).map((_, j) => eq(j)), a].join(' AND ')})`);
+        }
+        if (plan.inclusive && !foldEqual) {
+            branches.push(n === 1 ? eq(0) : `(${plan.terms.map((_, j) => eq(j)).join(' AND ')})`);
+        }
+        const keyset = branches.length === 0 ? '1 = 0' : branches.length === 1 ? branches[0] : `(${branches.join(' OR ')})`;
+        return guard ? `(${guard} AND ${keyset})` : keyset;
     }
     /**
-     * Whether a findMany paginates (`limit` / `take` / `offset` / `cursor`) but
-     * declares no ordering, which makes the returned page NON-DETERMINISTIC:
-     * Postgres is free to return different rows for the same unordered `LIMIT`
-     * once the heap changes underneath it, so a row can appear on two pages or on
-     * none.
+     * Whether a findMany paginates (`limit` / `take` / `offset`) but declares no
+     * ordering, which makes the returned page NON-DETERMINISTIC: Postgres is
+     * free to return different rows for the same unordered `LIMIT` once the heap
+     * changes underneath it, so a row can appear on two pages or on none.
      *
-     * `cursor` counts, and is the worst case rather than an exception: a keyset
-     * seek with no ORDER BY is exactly this bug (`WHERE id > $1 LIMIT $2` walks
-     * the heap in whatever order the plan happens to produce). An empty orderBy
-     * (`[]`, or an object whose every value is `undefined`) counts as absent,
-     * because it emits no ordering.
+     * A `cursor` page never counts: it is always ordered by its effective order
+     * (see {@link planCursor}). An empty orderBy (`[]`, or an object whose every
+     * value is `undefined`) counts as absent, because it emits no ordering.
      *
      * `distinct` is still excluded: that path re-orders in an outer wrapper around
      * a `DISTINCT ON` whose ordering picks the representative row, so an implicit
@@ -1284,11 +1624,11 @@ export class QueryInterface {
             return false;
         if (args.distinct !== undefined)
             return false;
+        if (hasCursor(args.cursor))
+            return false;
         if (!isEmptyOrderBy(args.orderBy))
             return false;
-        if (args.limit !== undefined || args.offset !== undefined)
-            return true;
-        return this.cursorFields(args.cursor).length > 0;
+        return args.limit !== undefined || args.offset !== undefined;
     }
     /**
      * Opt-in (`implicitPkOrdering`) primary-key ascending ordering for a paginating
@@ -1296,47 +1636,42 @@ export class QueryInterface {
      *
      * OFF by default in CORE, deliberately: turning it on would add an `ORDER BY`
      * to SQL that existing applications already emit, changing both the rows a
-     * given page returns and the plan the engine picks. That is a breaking change
-     * in everything but the type signature, so it waits for a major. The
+     * given page returns and the plan the engine picks. The
      * `turbine-orm/prisma-compat` layer defaults it ON instead, because reproducing
      * Prisma's semantics is that layer's whole contract.
      *
      * An explicit `orderBy` always wins, a PK-less table is left alone (nothing
      * stable to order by), and a composite PK orders on every column in
-     * declaration order. A `cursor` query orders on the CURSOR's field instead
-     * (see {@link cursorOrderBy}), and is left alone when that shape is ambiguous.
+     * declaration order. A `cursor` page is ordered by its own plan, not here, and
      * `distinct` shapes are skipped (see {@link isUnorderedPage}). With the flag
-     * off this returns `undefined` before touching anything, so the emitted SQL is
-     * byte-identical to before.
+     * off this returns `undefined` before touching anything.
      */
     implicitPkOrderBy(args) {
         if (!this.implicitPkOrdering)
             return undefined;
         if (!this.isUnorderedPage(args))
             return undefined;
-        if (this.cursorFields(args?.cursor).length > 0)
-            return this.cursorOrderBy(args?.cursor);
         return this.pkOrderBy();
     }
     /**
-     * Dev-only, once per query shape: an unordered paginating findMany returns a
+     * Advice (`diagnostics.advice`), once per query shape: an unordered paginating findMany returns a
      * non-deterministic page (see {@link isUnorderedPage}), and on real data it is
      * also usually the slower plan (an unordered `LIMIT` can discard tens of
      * thousands of heap rows that an index scan on the key would have skipped).
      *
-     * Gated exactly like the other dev diagnostics (silent under
-     * `NODE_ENV=production`) and consistent with `warnOnUnlimited`: a per-call
+     * Gated exactly like the other advice (silent when `diagnostics.advice` is
+     * off) and consistent with `warnOnUnlimited`: a per-call
      * `warnOnUnlimited: false` silences it, `true` forces it past a config-level
      * opt-out, and a config/per-table `warnOnUnlimited: false` silences it. Deduped
      * process-wide through the shared warn registry, so it can never spam.
      *
      * Suppressed only when `implicitPkOrdering` will ACTUALLY order this query.
-     * The flag being on is not enough: a PK-less table and an ambiguous
-     * multi-field cursor both get no injected ordering, and those are precisely
-     * the shapes that still need saying out loud.
+     * The flag being on is not enough: a PK-less table gets no injected
+     * ordering, and that is precisely the shape that still needs saying out loud.
      */
     maybeWarnUnorderedPage(args) {
-        if (process.env.NODE_ENV === 'production')
+        const log = this.advice;
+        if (!log)
             return;
         if (this.implicitPkOrdering && this.implicitPkOrderBy(args) !== undefined)
             return;
@@ -1347,30 +1682,18 @@ export class QueryInterface {
             return;
         if (!this.isUnorderedPage(args))
             return;
-        const cursorFields = this.cursorFields(args?.cursor);
-        const shape = [
-            cursorFields.length > 0 ? 'cursor' : '',
-            args?.limit !== undefined ? 'limit' : '',
-            args?.offset !== undefined ? 'offset' : '',
-        ]
+        const shape = [args?.limit !== undefined ? 'limit' : '', args?.offset !== undefined ? 'offset' : '']
             .filter(Boolean)
             .join('+');
         if (!shouldWarnOnce(WARN_NS.unorderedPage, `${this.table}|${shape}`))
             return;
-        const asOrderBy = (fields) => fields.length === 1 ? `{ ${fields[0]}: 'asc' }` : `[${fields.map((f) => `{ ${f}: 'asc' }`).join(', ')}]`;
         const pk = (this.tableMeta.primaryKey ?? []).map((c) => this.tableMeta.reverseColumnMap[c] ?? c);
-        // A cursor seeks on its own field, so that is the ordering to recommend:
-        // the primary key would be the wrong advice whenever the two differ.
-        const orderFields = cursorFields.length > 0 ? cursorFields : pk;
-        const suggestion = orderFields.length > 0 ? `Add \`orderBy: ${asOrderBy(orderFields)}\`` : 'Add an `orderBy` on a unique column';
-        const seek = cursorFields.length > 0
-            ? 'a `cursor` seek with no orderBy compares against rows the engine is free to return in any order, so ' +
-                'paging with it skips and repeats rows: '
-            : '';
-        console.warn(`[turbine] findMany on "${this.table}" paginates (${shape}) with no orderBy: ${seek}the page is NOT ` +
+        const asOrderBy = pk.length === 1 ? `{ ${pk[0]}: 'asc' }` : `[${pk.map((f) => `{ ${f}: 'asc' }`).join(', ')}]`;
+        const suggestion = pk.length > 0 ? `Add \`orderBy: ${asOrderBy}\`` : 'Add an `orderBy` on a unique column';
+        logTo(log, 'warn', `findMany on "${this.table}" paginates (${shape}) with no orderBy: the page is NOT ` +
             'deterministic (the same query can return different rows as the table changes, so a row may appear ' +
             `on two pages or on none). ${suggestion}, or set \`implicitPkOrdering: true\` in the client config ` +
-            'to order paginated queries automatically (by the cursor field, or by the primary key).');
+            'to order paginated queries by the primary key automatically.', { code: 'unordered-page', table: this.table, operation: 'findMany', paging: shape });
     }
     // -------------------------------------------------------------------------
     // relationLoadStrategy: 'auto', per-relation batched fallback when the
@@ -1597,7 +1920,7 @@ export class QueryInterface {
         return split;
     }
     /**
-     * Dev-only once-per-relation note that `'auto'` engaged the batched fallback.
+     * Advice, once per relation: `'auto'` engaged the batched fallback.
      *
      * Both lines follow the same four parts: the CONDITION that tripped the rule,
      * the MECHANISM (which plan shape was replaced by which, and what that costs),
@@ -1606,20 +1929,21 @@ export class QueryInterface {
      * as a bug, so the mechanism sentence is not optional.
      */
     emitAutoNotes(engaged) {
-        if (process.env.NODE_ENV === 'production')
+        const log = this.advice;
+        if (!log)
             return;
         for (const e of engaged) {
             if (!shouldWarnOnce(WARN_NS.autoStrategy, `${this.table}.${e.relation}`))
                 continue;
             if (e.reason === 'to-one-cardinality') {
-                console.warn(`[turbine] auto strategy: to-one relation "${e.relation}" on "${this.table}" loads batched ` +
+                logTo(log, 'warn', `auto strategy: to-one relation "${e.relation}" on "${this.table}" loads batched ` +
                     `(the query is unbounded or its limit exceeds ${this.autoToOneThreshold()} rows). On the join plan ` +
                     'a to-one relation is a correlated subquery the engine re-evaluates once per parent row, a per-row ' +
                     'cost that stands even on a unique index; batched replaces it with ONE follow-up statement ' +
                     '(`key = ANY(...)` for the whole page), so it trades that per-row cost for a single extra round ' +
                     'trip. Bound the query with a smaller `limit`, tune `autoToOneJoinMaxRows` (the break-even is ' +
                     "round-trip time / per-row cost), or set `relationLoadStrategy: 'join'` to force the " +
-                    'single-statement plan.');
+                    'single-statement plan.', { code: 'auto-strategy', table: this.table, relation: e.relation, reason: e.reason });
                 continue;
             }
             const probe = e.miss
@@ -1637,9 +1961,9 @@ export class QueryInterface {
                 : ' On the join plan that relation is a correlated subquery re-evaluated once per parent row, so an ' +
                     `unindexed probe is one full scan of "${child}" per parent row; the batched follow-up scans it ` +
                     'once for the whole page.';
-            console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}).${why} ` +
+            logTo(log, 'warn', `auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}).${why} ` +
                 "Create the covering index (or set `relationLoadStrategy: 'join'` to force the single-statement " +
-                'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.');
+                'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.', { code: 'auto-strategy', table: this.table, relation: e.relation, reason: e.reason });
         }
     }
     /**
@@ -1730,16 +2054,15 @@ export class QueryInterface {
             // a closure rather than passing `this.dialect` so the loader keeps
             // needing nothing else from the dialect.
             //
-            // The `dialect.name` test is NOT redundant with the hook's presence, and
-            // this is the same trap the `distinct` gate documents: every engine
-            // dialect is built by SPREADING `postgresDialect`, so an optional hook
-            // added there is INHERITED by sqlite / mysql / mssql, whose "absent"
-            // fallback would then never be taken. The wrapper is not portable as
-            // written either (T-SQL rejects an ORDER BY inside a derived table
-            // without TOP/OFFSET, and the compiled child query carries one), so the
-            // pushdown stays with the dialect that owns the implementation until
-            // another engine ships its own and asserts it.
-            buildPartitionLimit: this.dialect.name === 'postgresql' && this.dialect.buildPartitionLimit
+            // The capability is NOT redundant with the hook's presence: every engine
+            // dialect is built by SPREADING `postgresDialect`, so the hook is
+            // INHERITED by sqlite / mysql / mssql, whose "absent" fallback would then
+            // never be taken. The wrapper is not portable as written either (T-SQL
+            // rejects an ORDER BY inside a derived table without TOP/OFFSET, and the
+            // compiled child query carries one), so the pushdown stays with the
+            // dialect that owns the implementation until another engine ships its own
+            // and asserts it.
+            buildPartitionLimit: this.dialect.capabilities.partitionLimitPushdown && this.dialect.buildPartitionLimit
                 ? (input) => this.dialect.buildPartitionLimit(input)
                 : undefined,
             skipGlobalFilters: skip,
@@ -1878,15 +2201,14 @@ export class QueryInterface {
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
      *
-     * `build` receives a fresh `$N` param scratch array. On a miss those params
-     * are discarded (the returned params come from each call site's dedicated
-     * collect path); the array exists so the build path can number placeholders
-     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
-     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
-     * verify the collect path stayed in lockstep with the build path.
+     * `build` receives a fresh `$N` param scratch array. The executed params
+     * always come from each call site's dedicated collect path; on a miss the
+     * scratch params are kept in {@link lastMissParams} so `crossCheckCache` can
+     * compare the two. On a HIT, `build` is skipped here and re-run by
+     * {@link crossCheckCache} only when `diagnostics.cacheCheck` asks for it.
      *
-     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
-     * cross-check is warranted.
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows which
+     * comparison applies.
      */
     acquireSql(cacheKey, build) {
         if (!this.sqlCacheEnabled) {
@@ -1897,6 +2219,7 @@ export class QueryInterface {
         if (cached) {
             this.cacheHits++;
             this.lastCacheHit = true;
+            this.lastMissParams = undefined;
             return cached;
         }
         this.lastCacheHit = false;
@@ -1926,40 +2249,68 @@ export class QueryInterface {
      */
     buildCacheEntry(build) {
         this.variableArityShape = false;
-        const sql = build([]);
+        this.lastMissParams = undefined;
+        const built = [];
+        const sql = build(built);
         const variableArity = this.variableArityShape;
         this.variableArityShape = false;
         this.cacheMisses++;
-        return { sql, name: variableArity ? '' : sqlToPreparedName(sql) };
+        this.lastMissParams = built;
+        // With `sqlComment` putting a comment on every statement, the template's own
+        // name is never sent (the execute seam sends a `c_` name derived from it),
+        // so it is not claimed from the budget: only names that reach the wire do.
+        const name = variableArity
+            ? ''
+            : this.sqlCommenter?.alwaysComments
+                ? sqlToPreparedName(sql)
+                : boundedPreparedName(sql);
+        return { sql, name, paramCount: built.length };
     }
     /**
-     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     * The SQL-cache lockstep checks (see the comment above `CACHE_MISMATCH_WARN_NS`).
      *
-     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
-     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
-     * closure the caller passed to `acquireSql`, then compares:
+     * On a MISS: the collected params must equal the params the build pushed.
+     * On a HIT: the collected param count must equal the entry's, always; then,
+     * when `diagnostics.cacheCheck` selects this hit, the SQL and params are
+     * rebuilt fresh through the same closure and compared:
      *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
-     *   (b) the params the cache-hit collect path produced against the fresh
-     *       build-path params (length and element-wise strict deep-equal).
+     *   (b) the collected params against the fresh build-path params (length
+     *       and element-wise strict deep-equal).
      *
      * A mismatch means the fingerprint / build / collect paths have drifted out
      * of lockstep (the exact class of bug that has silently corrupted results
-     * before), so it throws a {@link ValidationError} (E003) naming the
-     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
-     * in dev/test is the point. Production never reaches the comparison.
+     * before), so it throws an {@link InvariantError} (E020) naming the
+     * fingerprint, the operation, and both SQL strings (truncated), never a
+     * parameter value.
      *
      * @param op human label of the calling build method (for the error message).
-     * @param cacheKey the cache fingerprint that HIT.
-     * @param entry the cached SQL entry that will be executed.
+     * @param cacheKey the cache fingerprint.
+     * @param entry the SQL entry that will be executed.
      * @param build the same closure passed to `acquireSql`; re-run here to
      *   capture the fresh build-path SQL + params.
      * @param collectedParams the params the caller's collect path produced.
      */
     crossCheckCache(op, cacheKey, entry, build, collectedParams) {
-        if (!this.lastCacheHit)
+        if (!this.lastCacheHit) {
+            const built = this.lastMissParams;
+            this.lastMissParams = undefined;
+            if (built === undefined || cacheParamsEqual(collectedParams, built))
+                return;
+            throw this.lockstepError(op, cacheKey, [
+                `built params and collected params diverge on a cache miss (collected ${collectedParams.length}, built ${built.length})`,
+            ], false);
+        }
+        if (entry.paramCount !== undefined && collectedParams.length !== entry.paramCount) {
+            throw new InvariantError('sql-cache-param-count', `SQL cache param count mismatch on ${op} (fingerprint "${cacheKey}"): the cached statement has ` +
+                `${entry.paramCount} placeholders but the cache hit collected ${collectedParams.length} params, so ` +
+                'the statement was not sent.');
+        }
+        const check = this.diagnostics.cacheCheck;
+        if (check === 'off')
             return;
-        const mode = cacheCrossCheckMode();
-        if (mode === 'off')
+        const sampled = typeof check === 'object';
+        // The sampling decision, and only it, is per hit.
+        if (sampled && check.sample < 1 && Math.random() >= check.sample)
             return;
         const freshParams = [];
         const freshSql = build(freshParams);
@@ -1975,34 +2326,39 @@ export class QueryInterface {
         if (!paramsOk) {
             details.push(`cache-hit params and freshly-built params diverge (collected ${collectedParams.length}, built ${freshParams.length})`);
         }
-        const message = `SQL cache lockstep violation on ${op} (fingerprint "${cacheKey}"). ` +
-            `This is a Turbine internal invariant violation, please report it at ` +
-            `https://github.com/zvndev/turbine-orm/issues. The fingerprint, SQL-build, and ` +
-            `param-collect paths must enumerate where-clause keys identically.\n${details.join('\n')}`;
-        // Sampled production path: log once per distinct fingerprint so the failure
-        // is durably recorded in the server log before the throw unwinds the query.
-        // (Dev mode throws straight away; its behavior is unchanged.)
-        if (mode === 'sampled' && !loggedCacheMismatchFingerprints.has(cacheKey)) {
-            loggedCacheMismatchFingerprints.add(cacheKey);
-            console.error(message);
+        throw this.lockstepError(op, cacheKey, details, sampled);
+    }
+    /**
+     * The `sql-cache-lockstep` {@link InvariantError}. When `log` is set (the
+     * sampled hit path) the failure is also logged once per table and shape, so
+     * it is durably recorded in the server log before the throw unwinds the
+     * query; the other paths throw straight away.
+     */
+    lockstepError(op, cacheKey, details, log) {
+        const err = new InvariantError('sql-cache-lockstep', `SQL cache lockstep violation on ${op} (fingerprint "${cacheKey}"). The fingerprint, SQL-build, and ` +
+            `param-collect paths must enumerate where-clause keys identically. ${INVARIANT_REPORT_HINT}\n` +
+            details.join('\n'));
+        if (log && shouldWarnOnce(CACHE_MISMATCH_WARN_NS, `${this.table}|${cacheKey}`)) {
+            logTo(this.logger, 'error', err.message, { code: 'cache-mismatch', table: this.table, operation: op });
         }
-        throw new ValidationError(message);
+        return err;
     }
     /**
-     * Reset the per-instance unlimited-query warning dedupe set.
-     * Exposed for tests so a single test process can verify the warning fires
-     * exactly once per table without bleeding state between assertions.
+     * Reset the unlimited-query warning dedupe, which is process-wide (see
+     * {@link maybeWarnUnlimited}). Exposed for tests so a single test process can
+     * verify the warning fires once per table without bleeding state between
+     * assertions.
      */
     resetUnlimitedWarnings() {
-        this.warnedTables.clear();
+        resetWarnOnce(WARN_NS.unlimitedFindMany);
     }
-    emitQueryEvent(sql, params, duration, action, rows, error, retried) {
+    emitQueryEvent(out, params, duration, action, rows, error, retried) {
         const onQuery = this.options?._onQuery;
         if (!onQuery)
             return;
         try {
             onQuery({
-                sql,
+                sql: out.sql,
                 params,
                 duration,
                 model: this.table,
@@ -2012,12 +2368,28 @@ export class QueryInterface {
                 error,
                 strategy: this.currentStrategyTag,
                 ...(retried ? { retried: true } : {}),
+                ...(out.comment === undefined ? {} : { comment: out.comment }),
             });
         }
         catch {
             // Listener errors must never crash a query
         }
     }
+    /**
+     * The statement `sql` as it goes out under `preparedName`: with the
+     * `sqlComment` appended, and under the name that comment calls for (see
+     * query/sql-comment.ts). This is the one place a comment is added, at the
+     * execute seam and after the SQL-template cache, so the cache, its keys and
+     * its lockstep checks only ever see commentless text. Without `sqlComment`
+     * it is the statement unchanged.
+     */
+    outgoing(sql, preparedName, action) {
+        const commenter = this.sqlCommenter;
+        const c = commenter?.commentFor(this.table, action);
+        if (commenter === undefined || c === undefined)
+            return { sql, text: sql, name: preparedName, comment: undefined };
+        return { sql, text: `${sql} ${c.comment}`, name: commenter.preparedName(preparedName, c), comment: c.comment };
+    }
     /**
      * Resolve the prepared-statement name a read should execute under, honouring
      * the per-query {@link FindManyArgs.forceCustomPlan} opt-in.
@@ -2108,13 +2480,31 @@ export class QueryInterface {
     }
     /**
      * Execute a pool.query with an optional timeout.
-     * If timeout is set, races the query against a timer and rejects on expiry.
+     *
+     * On a node-postgres pool outside a transaction the timeout is enforced on
+     * the SERVER ({@link queryCancellable}). Anywhere else (a transaction's
+     * connection, an engine shim, an HTTP pool) it races the query against a
+     * timer: the call rejects on time but the statement keeps running, so the
+     * error's `outcome` is `'unknown'`.
+     *
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
      * `retryIfStale` is {@link readWithTimeout}'s; nothing else sets it.
      */
-    async queryWithTimeout(sql, params, timeout, preparedName, retryIfStale = false) {
-        let start = performance.now();
+    async queryWithTimeout(sql, params, requestedTimeout, preparedName, retryIfStale = false, pool = this.pool) {
         const action = this.currentAction;
+        const out = this.outgoing(sql, preparedName, action);
+        // 0 is no timeout, as it is for `$transaction`'s option and the server's statement_timeout.
+        const timeout = requestedTimeout === 0 ? undefined : requestedTimeout;
+        if (timeout !== undefined && pool === this.pool && this.cancelsOnTimeout()) {
+            return this.queryCancellable(out, params, timeout, retryIfStale, action);
+        }
+        if (timeout !== undefined && pool === this.pool && this.txScoped && this.dialect.capabilities.backendCancel) {
+            const state = transactionStateOf(this.pool);
+            if (state !== undefined && canCancelBackend(state.client)) {
+                return this.queryCancellableInTransaction(out, params, timeout, state, action);
+            }
+        }
+        let start = performance.now();
         // Build the query argument, use object form with `name` for prepared
         // statements, or the plain (text, values) form otherwise.
         //
@@ -2122,19 +2512,19 @@ export class QueryInterface {
         // pool shims only speak `(text, values)`), so it is reached through a
         // cast. Guarded at runtime by `preparedStatementsEnabled`, which only the
         // drivers that accept it turn on.
-        const usePrepared = preparedName && this.preparedStatementsEnabled;
+        const usePrepared = out.name && this.preparedStatementsEnabled;
         const send = () => usePrepared
-            ? this.pool.query({
-                name: preparedName,
-                text: sql,
+            ? pool.query({
+                name: out.name,
+                text: out.text,
                 values: params,
             })
-            : this.pool.query(sql, params);
+            : pool.query(out.text, params);
         let exec = send();
         // Set when the caller's timeout has already answered, so a first attempt
         // that fails AFTER that does not send a retry nobody is waiting for.
         let abandoned = false;
-        if (retryIfStale && !this.txScoped) {
+        if (retryIfStale && !this.txScoped && pool === this.pool) {
             exec = exec.catch(async (err) => {
                 if (abandoned || !isStaleConnectionError(err))
                     throw err;
@@ -2142,7 +2532,7 @@ export class QueryInterface {
                 // so a listener counting errors sees it and one alerting on failed
                 // CALLS can skip it. The final event below times the retry alone.
                 const wrapped = wrapPgError(err);
-                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined, true);
+                this.emitQueryEvent(out, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined, true);
                 await settleEventLoop();
                 if (abandoned)
                     throw err;
@@ -2153,12 +2543,12 @@ export class QueryInterface {
         if (!timeout) {
             try {
                 const result = await exec;
-                this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+                this.emitQueryEvent(out, params, performance.now() - start, action, result.rowCount ?? 0);
                 return result;
             }
             catch (err) {
                 const wrapped = wrapPgError(err);
-                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+                this.emitQueryEvent(out, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
                 throw wrapped;
             }
         }
@@ -2166,23 +2556,240 @@ export class QueryInterface {
         const timeoutPromise = new Promise((_, reject) => {
             timer = setTimeout(() => {
                 abandoned = true;
-                reject(new TimeoutError(timeout));
+                reject(new TimeoutError(timeout, 'Query', {
+                    outcome: 'unknown',
+                    message: `Query timed out after ${timeout}ms. It could not be cancelled on the server and may still ` +
+                        'complete, so a write may have been applied: check before retrying it.',
+                }));
             }, timeout);
         });
         try {
             const result = await Promise.race([exec, timeoutPromise]);
-            this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+            this.emitQueryEvent(out, params, performance.now() - start, action, result.rowCount ?? 0);
             return result;
         }
         catch (err) {
             const wrapped = wrapPgError(err);
-            this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+            this.emitQueryEvent(out, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
             throw wrapped;
         }
         finally {
             clearTimeout(timer);
         }
     }
+    /**
+     * Whether a timed statement can be stopped on the server: an engine with a
+     * protocol cancel (PostgreSQL) on a node-postgres pool, outside a transaction
+     * (inside one, the connection belongs to the transaction and is not this
+     * method's to cancel or destroy).
+     */
+    cancelsOnTimeout() {
+        return !this.txScoped && this.dialect.capabilities.backendCancel && isNodePostgresPool(this.pool);
+    }
+    /**
+     * {@link queryWithTimeout} with a timeout the server enforces. The statement
+     * runs on a connection checked out for it, so when the deadline passes the
+     * backend running it is known and gets a protocol cancel request.
+     *
+     * The call then waits, at most {@link CANCEL_GRACE_MS}, for the statement to
+     * answer, and the answer decides the result:
+     *   - cancelled (57014): TimeoutError, `outcome: 'not-executed'`;
+     *   - finished first: the result, returned late, because reporting a write
+     *     that committed as a timeout invites a retry that applies it twice;
+     *   - failed: that error;
+     *   - no answer: TimeoutError, `outcome: 'unknown'`, and the connection is
+     *     destroyed rather than handed to the next caller still busy.
+     * A deadline that passes while still waiting for a connection sends nothing
+     * (`'not-executed'`). Either way the connection goes back to the pool only
+     * once its backend is idle, so timed-out statements cannot hold the pool.
+     */
+    async queryCancellable(out, params, timeout, retryIfStale, action) {
+        let start = performance.now();
+        const config = out.name && this.preparedStatementsEnabled ? { name: out.name, text: out.text, values: params } : null;
+        const report = (err, retried) => {
+            const wrapped = err instanceof TimeoutError ? err : wrapPgError(err);
+            const error = wrapped instanceof Error ? wrapped : undefined;
+            this.emitQueryEvent(out, params, performance.now() - start, action, 0, error, retried);
+            return wrapped;
+        };
+        let expired = false;
+        let expire = () => { };
+        const deadline = new Promise((resolve) => {
+            expire = resolve;
+        });
+        const timer = setTimeout(() => {
+            expired = true;
+            expire(TIMED_OUT);
+        }, timeout);
+        const neverSent = () => new TimeoutError(timeout, 'Query', {
+            outcome: 'not-executed',
+            message: `Query timed out after ${timeout}ms before it reached the server. It made no change.`,
+        });
+        try {
+            for (let attempt = 0;; attempt++) {
+                const checkingOut = acquireConnection(this.pool);
+                let held;
+                try {
+                    held = await Promise.race([checkingOut, deadline]);
+                }
+                catch (err) {
+                    throw report(err);
+                }
+                if (held === TIMED_OUT) {
+                    checkingOut.then((late) => late.checkout.release(), () => { });
+                    throw report(neverSent());
+                }
+                const { client, checkout } = held;
+                const running = (config
+                    ? client.query(config)
+                    : client.query(out.text, params)).then((result) => ({ result }), (error) => ({ error }));
+                const first = await Promise.race([running, deadline]);
+                const settled = first === TIMED_OUT ? await this.cancelTimedOut(held, running, timeout) : first;
+                if ('result' in settled) {
+                    if (first !== TIMED_OUT)
+                        checkout.release();
+                    this.emitQueryEvent(out, params, performance.now() - start, action, settled.result.rowCount ?? 0);
+                    return settled.result;
+                }
+                if ('timeout' in settled)
+                    throw report(settled.timeout);
+                const err = settled.error;
+                if (first === TIMED_OUT)
+                    throw report(err);
+                checkout.release(err instanceof Error ? err : true);
+                if (!(retryIfStale && attempt === 0 && isStaleConnectionError(err)))
+                    throw report(err);
+                report(err, true);
+                await settleEventLoop();
+                if (expired)
+                    throw report(neverSent());
+                start = performance.now();
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * A timed statement inside a transaction, cancelled on the server when the
+     * deadline passes, on the transaction's own connection.
+     *
+     * A cancelled statement made no change, but PostgreSQL aborts the
+     * transaction it ran in, so the timeout ends the transaction too: it is
+     * marked to roll back ({@link TransactionState.abort}), which also covers a
+     * cancel that arrived after the statement finished. The error is
+     * `outcome: 'not-executed'` either way, because nothing it did can commit.
+     * A statement that finishes before the deadline is returned as usual.
+     */
+    async queryCancellableInTransaction(out, params, timeout, state, action) {
+        const start = performance.now();
+        const running = (out.name && this.preparedStatementsEnabled
+            ? this.pool.query({
+                name: out.name,
+                text: out.text,
+                values: params,
+            })
+            : this.pool.query(out.text, params)).then((result) => ({ result }), (error) => ({ error }));
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMED_OUT), timeout);
+        });
+        let settled;
+        try {
+            const first = await Promise.race([running, deadline]);
+            settled = first === TIMED_OUT ? await this.cancelInTransaction(state, running, timeout) : first;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if ('result' in settled) {
+            this.emitQueryEvent(out, params, performance.now() - start, action, settled.result.rowCount ?? 0);
+            return settled.result;
+        }
+        const err = 'timeout' in settled ? settled.timeout : wrapPgError(settled.error);
+        this.emitQueryEvent(out, params, performance.now() - start, action, 0, err instanceof Error ? err : undefined);
+        throw err;
+    }
+    /** Cancel a timed-out statement in a transaction and end the transaction. See {@link queryCancellableInTransaction}. */
+    async cancelInTransaction(state, running, timeout) {
+        let graceTimer;
+        const graceOver = new Promise((resolve) => {
+            graceTimer = setTimeout(() => resolve(TIMED_OUT), CANCEL_GRACE_MS);
+        });
+        try {
+            await Promise.race([sendCancelRequest(state.client, CANCEL_GRACE_MS), graceOver]);
+            const answer = await Promise.race([running, graceOver]);
+            if (answer !== TIMED_OUT && 'result' in answer)
+                return answer;
+            const cancelled = answer !== TIMED_OUT && isQueryCanceled(answer.error);
+            if (answer !== TIMED_OUT && !cancelled)
+                return answer;
+            const error = new TimeoutError(timeout, 'Query', {
+                outcome: 'not-executed',
+                ...(cancelled ? { cause: answer.error } : {}),
+                message: (cancelled
+                    ? `Query timed out after ${timeout}ms and was cancelled on the server, so it made no change. `
+                    : `Query timed out after ${timeout}ms, and the server did not confirm its cancellation within ` +
+                        `${CANCEL_GRACE_MS}ms. `) +
+                    'The transaction it ran in is over: it rolls back instead of committing, and no statement in it is ' +
+                    'kept. Let this error leave the transaction callback and retry the whole transaction, or run a ' +
+                    'statement that may time out in a nested `tx.$transaction(...)`, which rolls back only that block.',
+            });
+            state.abort(error);
+            return { timeout: error };
+        }
+        finally {
+            clearTimeout(graceTimer);
+        }
+    }
+    /**
+     * Cancel a statement that outlived its timeout, wait for it to answer, and
+     * release its connection accordingly. See {@link queryCancellable}.
+     */
+    async cancelTimedOut(held, running, timeout) {
+        let graceTimer;
+        const graceOver = new Promise((resolve) => {
+            graceTimer = setTimeout(() => resolve(TIMED_OUT), CANCEL_GRACE_MS);
+        });
+        try {
+            const delivered = await Promise.race([sendCancelRequest(held.client, CANCEL_GRACE_MS), graceOver]);
+            const answer = await Promise.race([running, graceOver]);
+            if (answer === TIMED_OUT) {
+                held.checkout.release(new Error('the statement did not stop after a cancel request'));
+                return {
+                    timeout: new TimeoutError(timeout, 'Query', {
+                        outcome: 'unknown',
+                        message: `Query timed out after ${timeout}ms and the server did not confirm its cancellation within ` +
+                            `${CANCEL_GRACE_MS}ms, so it may still complete and a write may have been applied: check before ` +
+                            'retrying it. The connection was closed.',
+                    }),
+                };
+            }
+            // A cancel that was sent but not confirmed could still land on the NEXT
+            // statement this connection runs, so such a connection is not reused.
+            const reusable = delivered === true;
+            if ('result' in answer) {
+                held.checkout.release(reusable ? undefined : true);
+                return answer;
+            }
+            const err = answer.error;
+            if (reusable && err?.code === '57014') {
+                held.checkout.release();
+                return {
+                    timeout: new TimeoutError(timeout, 'Query', {
+                        outcome: 'not-executed',
+                        cause: err,
+                        message: `Query timed out after ${timeout}ms and was cancelled on the server. It made no change.`,
+                    }),
+                };
+            }
+            held.checkout.release(err instanceof Error ? err : true);
+            return answer;
+        }
+        finally {
+            clearTimeout(graceTimer);
+        }
+    }
     /**
      * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
      * the active dialect's {@link Dialect.resultStrategy}, then apply its
@@ -2197,18 +2804,104 @@ export class QueryInterface {
      *     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 reselect = deferred.reselect;
+        if (this.dialect.resultStrategy === 'reselect' && reselect) {
+            // One transaction, so the row returned is the row this call wrote, and
+            // the transform runs before COMMIT so a refusal it raises writes nothing.
+            return this.inOneTransaction(async (exec) => deferred.transform(await reselect(exec)), timeout, `A ${this.dialect.name} write`, 'Pass a pool that can check out a connection.');
         }
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, timeout, deferred.preparedName);
         return deferred.transform(result);
     }
+    /**
+     * The executor for a write's statements, sharing one deadline: each one gets
+     * what is left of `timeout`, so a chunked `createMany` or a lock, write and
+     * re-read cannot run for N times the timeout. A statement due past the
+     * deadline is not sent. `onClient` routes them to a held connection.
+     */
+    deadlineExec(timeout, onClient) {
+        const deadline = timeout ? performance.now() + timeout : undefined;
+        return async (sql, params, preparedName) => {
+            let left = timeout;
+            if (deadline !== undefined) {
+                left = Math.ceil(deadline - performance.now());
+                if (left <= 0) {
+                    throw new TimeoutError(timeout, 'Query', {
+                        outcome: 'not-executed',
+                        message: `Query timed out after ${timeout}ms: the write's statements share one deadline, and it passed ` +
+                            'before the next one was sent. Its earlier statements are rolled back, so it makes no change.',
+                    });
+                }
+            }
+            return onClient
+                ? this.queryWithTimeout(sql, params, left, preparedName, false, onClient)
+                : this.queryWithTimeout(sql, params, left, preparedName);
+        };
+    }
+    /**
+     * Run a write that takes several statements as one transaction on one
+     * connection: the caller's transaction when there is one, else one opened
+     * here. A statement that times out is cancelled where the engine allows it,
+     * and its connection is closed rather than rolled back (a ROLLBACK would wait
+     * behind it); the transaction never commits, so the write made no change.
+     * `timeout` is one deadline for every statement (see {@link deadlineExec}).
+     */
+    async inOneTransaction(work, timeout, operation, alternative) {
+        if (this.txScoped) {
+            // In the caller's transaction, a savepoint keeps the write whole: a later
+            // statement that fails and is caught cannot leave the earlier ones behind.
+            return withSavepoint(this.pool, () => work(this.deadlineExec(timeout)));
+        }
+        if (typeof this.pool.connect !== 'function') {
+            throw new UnsupportedFeatureError(`${operation} on a pool without connect()`, this.dialect.name, `${operation} runs several statements in one transaction, which needs a connection of its own, and ` +
+                `this pool cannot check one out (a stateless HTTP driver). ${alternative}`);
+        }
+        const { client, checkout } = await openCheckout(this.pool, (c) => c.query(this.dialect.beginStatement()));
+        const onClient = {
+            query: (text, values) => typeof text === 'string'
+                ? client.query(text, values)
+                : client.query(text),
+        };
+        try {
+            const value = await work(this.deadlineExec(timeout, onClient));
+            await client.query(this.dialect.commitStatement());
+            checkout.release();
+            return value;
+        }
+        catch (err) {
+            if (err instanceof TimeoutError) {
+                if (await sendCancelRequest(client, CANCEL_GRACE_MS)) {
+                    checkout.release(err);
+                }
+                else {
+                    // No cancel reached the server (or the engine has none), so the
+                    // statement may still be running. The ROLLBACK queues behind it on
+                    // this connection, and the connection goes back to the pool only
+                    // after it: never with the transaction still open.
+                    client.query(this.dialect.rollbackStatement()).then(() => checkout.release(), (e) => checkout.release(e instanceof Error ? e : true));
+                }
+                throw new TimeoutError(err.timeoutMs, 'Query', {
+                    outcome: 'not-executed',
+                    cause: err,
+                    message: `Query timed out after ${err.timeoutMs}ms. Its transaction is rolled back rather than committed, ` +
+                        'so it makes no change.',
+                });
+            }
+            try {
+                await client.query(this.dialect.rollbackStatement());
+            }
+            catch {
+                // Best effort: the connection may be gone.
+            }
+            checkout.release();
+            throw explainConnectionLoss(wrapPgError(err), checkout.lostWith);
+        }
+    }
     // ---------------------------------------------------------------------------
     // Write compilation (extracted to writes.ts).
     // ---------------------------------------------------------------------------
     buildCreate(args) {
+        args = this.normalizeArgs(args);
         return writesMod.buildCreate(this.ctx, args, this.resolveWriteProjection(args));
     }
     /**
@@ -2230,22 +2923,26 @@ export class QueryInterface {
         return { columns };
     }
     buildCreateMany(args) {
-        return writesMod.buildCreateMany(this.ctx, args);
+        args = this.normalizeArgs(args);
+        return writesMod.buildCreateMany(this.ctx, args, 'refuse', this.resolveWriteProjection(args));
     }
     buildUpdate(args) {
+        args = this.normalizeArgs(args);
         return writesMod.buildUpdate(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildDelete(args) {
+        args = this.normalizeArgs(args);
         return writesMod.buildDelete(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildUpsert(args) {
+        args = this.normalizeArgs(args);
         return writesMod.buildUpsert(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildUpdateMany(args) {
-        return writesMod.buildUpdateMany(this.ctx, args);
+        return writesMod.buildUpdateMany(this.ctx, this.normalizeArgs(args));
     }
     buildDeleteMany(args) {
-        return writesMod.buildDeleteMany(this.ctx, args);
+        return writesMod.buildDeleteMany(this.ctx, this.normalizeArgs(args));
     }
     /**
      * Best-effort extraction of an auto-generated primary key from a write
@@ -2261,11 +2958,10 @@ export class QueryInterface {
      * If no middlewares are registered, executes directly.
      *
      * 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.
+     * transform the result returned by `next()`. `params.args` is a plain copy
+     * (see `readOnlyMiddlewareParams`): the query is compiled from the caller's
+     * args, so `next()` throws a TypeError when the copy was changed. Cross-cutting
+     * filters (e.g. soft deletes) belong in the query itself, or in `globalFilters`.
      */
     async executeWithMiddleware(action, args, executor) {
         this.currentAction = action;
@@ -2274,14 +2970,17 @@ export class QueryInterface {
         // can be complete. Putting it in each method instead would mean fifteen
         // sites and a new one every time an operation is added, which is precisely
         // how the surface it checks came to need checking.
-        warnUnknownQueryOptions(this.table, action, args);
+        warnUnknownQueryOptions(this.table, action, args, this.advice ?? null);
         if (this.middlewares.length === 0) {
             return executor();
         }
-        const params = { model: this.table, action, args: { ...args } };
+        // A copy: the query is compiled from `args`, not from what middleware
+        // sees, so `next()` throws on a changed copy rather than doing nothing.
+        const params = readOnlyMiddlewareParams(this.table, action, args);
         // Build middleware chain
         let index = 0;
         const next = async (p) => {
+            assertMiddlewareArgsKept(params, p);
             if (index < this.middlewares.length) {
                 const mw = this.middlewares[index++];
                 return mw(p, next);
@@ -2304,6 +3003,7 @@ export class QueryInterface {
         // nothing else). It is here so the invariant holds at the seam rather than
         // depending on every consumer to re-establish it.
         args = this.normalizeArgs(args);
+        this.assertLockInTransaction(args, 'findUnique');
         return this.executeWithMiddleware('findUnique', args, async () => {
             if (args.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
@@ -2356,6 +3056,9 @@ export class QueryInterface {
         return entity;
     }
     buildFindUnique(args) {
+        // Canonical args FIRST: the empty-where guard and the unique-key rule below
+        // must read the pruned `where`, never one still carrying `undefined` keys.
+        args = this.normalizeArgs(args);
         this.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
         // Pinned before the cache key, which carries it (see buildFindMany).
         const jsonEncoding = this.resolveJsonEncoding(args.jsonEncoding);
@@ -2377,9 +3080,10 @@ export class QueryInterface {
         // deliberately so: a tenant filter is not a unique selector, and letting it
         // satisfy this would still hand back an arbitrary row from inside the tenant.
         //
-        // `findFirst` is intentionally NOT guarded. "The first row matching an
-        // optional filter" is its whole contract and Prisma's `findFirst` behaves
-        // the same way; ask for one row by identity with `findUnique`.
+        // `findFirst` takes no such guard: "the first row matching an optional
+        // filter" is its contract, and `where: {}` or no `where` asks for any row.
+        // It refuses only a `where` that was emptied by `undefined` values (see
+        // normalizeArgs), which never meant "any row".
         if (whereMod.userPredicateIsEmpty(this.ctx, (args.where ?? {}))) {
             throw new ValidationError(`findUnique on "${this.table}" refused: the \`where\` clause has no predicate, ` +
                 'so this would return an arbitrary row rather than a specific one. ' +
@@ -2399,9 +3103,9 @@ export class QueryInterface {
         // a global filter is not an identity, and letting one satisfy this would
         // hand back an arbitrary row from inside the tenant.
         this.assertFindUniqueKey(args.where);
-        // Declared relation spellings first, before stable-order and the
-        // fingerprint (see buildFindMany).
-        args = this.normalizeArgs(args);
+        // The locking clause, read by the cache key and all three SQL paths below.
+        const rowLock = resolveRowLock(args.lock, this.dialect, this.table);
+        const lockSql = rowLock?.sql ?? '';
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {
@@ -2431,7 +3135,9 @@ export class QueryInterface {
         // `|je=`: same rule and same hazard as in buildFindMany. findUnique is never
         // flatten-planned, so this is the only plan-shape segment it needs.
         const encodingFp = `|je=${jsonEncoding === 'positional' ? 'p' : 'o'}`;
-        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}|pii=${includePii ? 1 : 0}${encodingFp}${this.globalFilterCacheSegment()}`;
+        // Empty without a lock, so every unlocked key is unchanged.
+        const lockFp = rowLock ? `|lk=${rowLock.fp}` : '';
+        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}|pii=${includePii ? 1 : 0}${encodingFp}${lockFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         // Check if all where values are simple (plain equality, no operators/null/OR).
         // Keys are sorted to match fingerprintWhere, insertion order here would let
@@ -2439,14 +3145,19 @@ export class QueryInterface {
         const whereKeys = Object.keys(whereObj)
             .filter((k) => whereObj[k] !== undefined)
             .sort();
+        // Only a scalar the general path would accept as it is (a primitive, Date
+        // or Buffer) on a non-JSON column takes the simple path, so no operand
+        // reaches SQL without the general path's validation. Resolved, not looked
+        // up: a relation filter spelled the snake_case way must not read as a
+        // plain equality.
         const isSimpleWhere = !whereObj.OR &&
             !whereObj.AND &&
             !whereObj.NOT &&
             whereKeys.every((k) => {
-                const v = whereObj[k];
-                // Resolved, not looked up: a relation filter spelled the snake_case
-                // way must not read as a plain equality and take the simple path.
-                return v !== null && !isWhereOperator(v) && !resolveRelationDef(this.tableMeta.relations, k);
+                if (!isFastPathScalar(whereObj[k]) || resolveRelationDef(this.tableMeta.relations, k))
+                    return false;
+                const column = resolveColumnName(this.tableMeta, k);
+                return column !== undefined && !this.isJsonColumnType(this.getColumnPgType(column));
             });
         // Simple path: plain equality, no operators/null/OR.
         //
@@ -2467,7 +3178,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}.*`;
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}${lockSql}`;
             };
             const entry = this.acquireSql(ck, buildSql);
             // Collect params (same order and same coercion as build)
@@ -2484,6 +3195,7 @@ export class QueryInterface {
                 },
                 tag: `${this.table}.findUnique`,
                 preparedName: entry.name,
+                ...rowLockMarker(rowLock),
             };
         }
         // General path (with operators, null, OR, with clause)
@@ -2493,7 +3205,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}${this.limitOneClause()}`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}${lockSql}`;
             };
             const entry = this.acquireSql(ck, buildSql);
             // Collect params
@@ -2508,6 +3220,7 @@ export class QueryInterface {
                 },
                 tag: `${this.table}.findUnique`,
                 preparedName: entry.name,
+                ...rowLockMarker(rowLock),
             };
         }
         // Nested queries with `with` clause.
@@ -2519,7 +3232,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, undefined, undefined, includePii);
-            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
+            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}${lockSql}`;
         };
         const entry = this.acquireSql(ck, buildSql);
         // Collect params in exact build order: where first, then with-clause relations
@@ -2536,6 +3249,7 @@ export class QueryInterface {
             },
             tag: `${this.table}.findUnique`,
             preparedName: entry.name,
+            ...rowLockMarker(rowLock),
         };
     }
     // -------------------------------------------------------------------------
@@ -2551,19 +3265,20 @@ export class QueryInterface {
         // nothing else). It is here so the invariant holds at the seam rather than
         // depending on every consumer to re-establish it.
         args = this.normalizeArgs(args);
+        this.assertLockInTransaction(args, 'findMany');
         this.maybeWarnUnlimited(args);
         this.maybeWarnUnorderedPage(args);
-        // Dev-only: warn on deeply nested with clauses
-        if (process.env.NODE_ENV !== 'production') {
-            if (args?.with) {
-                const depth = this.measureWithDepth(args.with);
-                if (depth > 5 && shouldWarnOnce(WARN_NS.deepWith, this.table)) {
-                    console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}": every level is a ` +
-                        'correlated subquery the engine re-evaluates once per row of the level above, so the work ' +
-                        'multiplies down the tree and the whole subtree is built as JSON inside each parent row. Split ' +
-                        "into separate queries, or use `relationLoadStrategy: 'batched'` (one flat statement per " +
-                        'relation, no per-parent re-evaluation). Dev-only: silent under `NODE_ENV=production`.');
-                }
+        // Advice: warn on deeply nested with clauses.
+        const advice = this.advice;
+        if (advice && args?.with) {
+            const depth = this.measureWithDepth(args.with);
+            if (depth > 5 && shouldWarnOnce(WARN_NS.deepWith, this.table)) {
+                logTo(advice, 'warn', `Deep with clause (depth ${depth}) on "${this.tableMeta.name}": every level is a ` +
+                    'correlated subquery the engine re-evaluates once per row of the level above, so the work ' +
+                    'multiplies down the tree and the whole subtree is built as JSON inside each parent row. Split ' +
+                    "into separate queries, or use `relationLoadStrategy: 'batched'` (one flat statement per " +
+                    'relation, no per-parent re-evaluation). Advice: silent when `diagnostics.advice` is off, as it ' +
+                    'is by default in production.', { code: 'deep-with', table: this.table, operation: 'findMany', depth });
             }
         }
         return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
@@ -2638,11 +3353,13 @@ export class QueryInterface {
         }
     }
     /**
-     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * Emit a one-time warning when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
      *
-     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
-     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Said once per table per process (`WARN_NS.unlimitedFindMany`), so a busy
+     * loop calling `db.users.findMany()` thousands of times logs once, and so
+     * does the same call inside every `$transaction`, which builds its own
+     * query interfaces.
      * 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`. A per-call `warnOnUnlimited` overrides the
@@ -2658,19 +3375,18 @@ export class QueryInterface {
             return;
         if (this.defaultLimit !== undefined)
             return;
-        const hasExplicitLimit = args?.limit !== undefined || args?.cursor !== undefined;
+        const hasExplicitLimit = args?.limit !== undefined || hasCursor(args?.cursor);
         if (hasExplicitLimit)
             return;
         if (this.whereMatchesAtMostOneRow(args?.where))
             return;
-        if (this.warnedTables.has(this.table))
+        if (!shouldWarnOnce(WARN_NS.unlimitedFindMany, this.table))
             return;
-        this.warnedTables.add(this.table);
-        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit: the statement is emitted with no row limit, ` +
+        logTo(this.logger, 'warn', `warning: findMany on "${this.table}" has no limit: the statement is emitted with no row limit, ` +
             'so the engine returns every matching row and the driver materializes all of them as objects before ' +
             'this call resolves (the cost grows with the table, not with the rows you use). Pass `limit`/`take`, ' +
             'or set `defaultLimit` in the client config; silence with `warnOnUnlimited: false` (per call, per ' +
-            'table, or in config).');
+            'table, or in config).', { code: 'unlimited-find-many', table: this.table, operation: 'findMany' });
     }
     /**
      * Whether `where` can match at most one row, because it pins every column of
@@ -2717,7 +3433,7 @@ export class QueryInterface {
     }
     /**
      * Recursively measure the maximum depth of a `with` clause tree.
-     * Used by the dev-only deep-with warning guard.
+     * Used by the deep-with advice.
      */
     measureWithDepth(withClause) {
         let maxDepth = 1;
@@ -2768,7 +3484,7 @@ export class QueryInterface {
         if (args?.orderBy !== undefined) {
             const deduped = dedupeOrderEntries(this.tableMeta, orderByEntries(args.orderBy), this.table);
             if (deduped) {
-                warnRedundantSortTerm(this.table, 'orderBy', deduped.dropped);
+                warnRedundantSortTerm(this.advice, this.table, 'orderBy', deduped.dropped);
                 args = {
                     ...args,
                     orderBy: deduped.entries.map(([k, v]) => ({ [k]: v })),
@@ -2778,7 +3494,7 @@ export class QueryInterface {
         if (args?.distinct && args.distinct.length > 0) {
             const deduped = dedupeColumnList(this.tableMeta, args.distinct);
             if (deduped) {
-                warnRedundantSortTerm(this.table, 'distinct', deduped.dropped);
+                warnRedundantSortTerm(this.advice, this.table, 'distinct', deduped.dropped);
                 args = { ...args, distinct: deduped.columns };
             }
         }
@@ -2789,29 +3505,40 @@ export class QueryInterface {
         const implicitOrder = this.implicitPkOrderBy(args);
         if (implicitOrder)
             args = { ...args, orderBy: implicitOrder };
+        // A `cursor` that names no row (`null`, `{}`) is refused before either
+        // reader below asks whether there is one.
+        assertCursorWritten(this.table, 'findMany', args?.cursor);
+        // A page whose order can tie gets the cursor tiebreaker (completePageOrder),
+        // before fingerprinting, so the cache key carries it.
+        if (args)
+            args = this.completePageOrder(args);
+        // A cursor page is planned (and its orderBy completed to the effective
+        // order) BEFORE fingerprinting, so the key, the SQL and the param collect
+        // all read one plan. See planCursor.
+        let cursorPlan;
+        if (hasCursor(args?.cursor))
+            ({ args, plan: cursorPlan } = this.planCursor(args));
         // `distinct` compiles to `SELECT DISTINCT ON (...)`, which is PostgreSQL
         // syntax and nothing else's. Every other engine parsed it as far as the
         // word `ON` and answered with a RAW driver error carrying no TURBINE_ code
         // (SQLite: `near "ON": syntax error`; MySQL: ER_PARSE_ERROR), i.e. the one
         // shape the typed-error surface exists to prevent. Refused with the same
-        // E017 the OTHER spelling of this feature already used, `groupBy({
-        // distinctOn })` in aggregates.ts, which was gated correctly all along.
-        //
-        // `dialect.name` rather than a new capability flag, deliberately, and this
-        // is the exception to the "capability flags, not engine names" rule the
-        // rest of the dialect follows: every engine dialect is built by SPREADING
-        // `postgresDialect`, so a flag defaulting to `true` would be inherited by
-        // all of them (which is the bug) and one defaulting to `false` would have
-        // to be re-declared on Postgres-compatible dialects that already work.
-        // The established precedent for exactly this feature is the `dialect.name`
-        // test in `buildDistinctOnSource`.
+        // E017, on the same `distinctOn` capability, as the OTHER spelling of this
+        // feature, `groupBy({ distinctOn })` in aggregates.ts.
         //
         // Before the cache, like the two guards below, so a warmed template cannot
         // serve the query the cold path refuses.
-        if (args?.distinct && args.distinct.length > 0 && this.dialect.name !== 'postgresql') {
+        if (args?.distinct && args.distinct.length > 0 && !this.dialect.capabilities.distinctOn) {
             throw new UnsupportedFeatureError('DISTINCT ON (findMany distinct)', this.dialect.name, 'findMany({ distinct }) requires PostgreSQL: SELECT DISTINCT ON is not portable. Group in ' +
                 'application code, or use groupBy({ by }) for one row per combination.');
         }
+        // The locking clause, validated and rendered once: the cache key and the
+        // SQL both read this value. PostgreSQL refuses a lock on a DISTINCT query
+        // (0A000), so that pair is refused here, before the cache.
+        const rowLock = resolveRowLock(args?.lock, this.dialect, this.table);
+        if (rowLock && args?.distinct && args.distinct.length > 0) {
+            throw new ValidationError(lockWithDistinctMessage(this.table));
+        }
         // `distinct` + relation orderBy is refused up front (E003): the distinct
         // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
         // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
@@ -2858,14 +3585,9 @@ export class QueryInterface {
             })
                 .join(',')
             : '';
-        // Keyset order AND per-field direction: a multi-field cursor's predicate
-        // is one OR-branch per field in orderBy precedence, and `<` / `>` are SQL
-        // text, so `asc` and `desc` (or two precedences) can never share a template.
-        const cursorFp = args?.cursor
-            ? this.cursorSeekEntries(args.cursor, args.orderBy)
-                .map((e) => `${e.column}:${e.desc ? 'd' : 'a'}`)
-                .join(',')
-            : '';
+        // Mode, keyset order, directions, NULL placement and which values are
+        // NULL all change the predicate's SQL text (see planCursor).
+        const cursorFp = cursorPlan?.fingerprint ?? '';
         // distinct must fingerprint in USER order: the SQL emits `DISTINCT ON` in
         // the caller's column order, so a permuted array rebuilds different SQL and
         // must not collapse onto the same cache entry (would trip the cross-check).
@@ -2906,7 +3628,9 @@ export class QueryInterface {
         // non-default one, so the key never depends on what the client default
         // happens to be.
         const encodingFp = `|je=${jsonEncoding === 'positional' ? 'p' : 'o'}`;
-        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}|pii=${includePii ? 1 : 0}${flattenFp}${encodingFp}${this.globalFilterCacheSegment()}`;
+        // Empty without a lock, so every unlocked key is unchanged.
+        const lockFp = rowLock ? `|lk=${rowLock.fp}` : '';
+        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}|pii=${includePii ? 1 : 0}${flattenFp}${encodingFp}${lockFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const buildSql = (freshParams) => {
             // Fresh build: generates SQL and populates freshParams
@@ -2972,18 +3696,9 @@ export class QueryInterface {
             // WHERE + cursor conditions accumulate into `tail`, pushing params in
             // where → cursor order (the collect path mirrors this exactly).
             let tail = freshWhereSql;
-            if (args?.cursor) {
-                // Keyset order (orderBy precedence), MUST match cursorFp and the
-                // cache-hit collect below: both go through cursorSeekEntries.
-                const seek = this.cursorSeekEntries(args.cursor, args.orderBy);
-                if (seek.length > 0) {
-                    const terms = seek.map((e) => {
-                        freshParams.push(e.value);
-                        return { column: `${qt}.${this.q(e.column)}`, placeholder: this.p(freshParams.length), desc: e.desc };
-                    });
-                    const predicate = this.keysetPredicate(terms);
-                    tail += freshWhereSql ? ` AND ${predicate}` : ` WHERE ${predicate}`;
-                }
+            if (cursorPlan) {
+                const predicate = this.renderCursorPredicate(cursorPlan, freshParams);
+                tail += freshWhereSql ? ` AND ${predicate}` : ` WHERE ${predicate}`;
             }
             // ORDER BY is built AFTER the cursor pushes (param order
             // where → with → cursor → orderBy → limit → offset) and BEFORE final
@@ -3057,6 +3772,9 @@ export class QueryInterface {
                 offsetPh = this.paginationRef(args.offset, freshParams, 'skip/offset');
             }
             sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
+            // The locking clause follows pagination and binds nothing.
+            if (rowLock)
+                sql += rowLock.sql;
             return sql;
         };
         const entry = this.acquireSql(ck, buildSql);
@@ -3069,13 +3787,9 @@ export class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params, undefined, flattenPlan);
         }
-        // 3. Cursor params, keyset order, matching cursorFp and the build path
-        //    (each value binds ONCE; the expanded predicate re-references its `$n`).
-        if (args?.cursor) {
-            for (const e of this.cursorSeekEntries(args.cursor, args.orderBy)) {
-                params.push(e.value);
-            }
-        }
+        // 3. Cursor params: the build's own renderer, SQL discarded.
+        if (cursorPlan)
+            this.renderCursorPredicate(cursorPlan, params);
         // 4. ORDER BY params (vector KNN ordering binds a `$n::vector` query vector).
         //    Mirrors buildOrderBy's push order, between cursor and LIMIT.
         if (args?.orderBy) {
@@ -3102,6 +3816,7 @@ export class QueryInterface {
             transform: (result) => result.rows.map((row) => (parseWith ? parseWith(row) : this.parseRow(row, this.table))),
             tag: `${this.table}.findMany`,
             preparedName: entry.name,
+            ...rowLockMarker(rowLock),
         };
     }
     // -------------------------------------------------------------------------
@@ -3162,20 +3877,21 @@ export class QueryInterface {
      * the result set is empty. Callers may therefore treat a yielded batch as
      * non-empty.
      */
-    async *streamRaw(args, action) {
-        // Pagination aliases folded BEFORE the speculative build below, which
-        // spreads `args` and overrides `limit`. A surviving `take` would reach that
-        // spread alongside the override and be read as two different values for one
-        // bound. Relation names are left to `buildFindMany`, which both branches go
-        // through.
-        args = normalizePagination(args);
+    async *streamRaw(args, action, idle, unit) {
+        // Canonical args BEFORE the speculative build below, which spreads `args`
+        // and sets its own `limit`: a surviving `take` would reach that spread
+        // beside it and be read as a second value for one bound.
+        args = this.normalizeArgs(args);
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
+        // Validated on every path, so a bad value is refused whether or not this
+        // stream turns out to need a cursor.
+        const idleTimeoutMs = resolveStreamIdleTimeout(args?.idleTimeoutMs, 'idleTimeoutMs') ?? this.streamIdleTimeoutMs;
         this.currentAction = action;
         // The two streaming methods do NOT go through `executeWithMiddleware`, so
         // the unknown-key diagnostic has to be hung here as well or a stream would
         // be the one read that silently drops an `include`. Both public methods
         // reach this, and each passes its own name.
-        warnUnknownQueryOptions(this.table, action, args);
+        warnUnknownQueryOptions(this.table, action, args, this.advice ?? null);
         // Streaming is ALREADY immune to the generic-plan cliff: the speculative
         // fetch has never passed a prepared name, and the cursor path runs through
         // DECLARE, so neither statement enters the plan cache. `preparedNameFor` is
@@ -3212,9 +3928,18 @@ export class QueryInterface {
         // four round trips on a drain that would have fit, never any transferred
         // rows.
         if (batchSize <= STREAM_SPECULATION_MAX_BATCH) {
+            // The caller's bound (or the client's `defaultLimit`, exactly as findMany
+            // applies it) caps the speculative fetch. When the bound fits in a batch
+            // the speculative fetch IS the whole answer; otherwise `rows <= batchSize`
+            // still means fewer rows exist than either bound, and an overflow goes to
+            // the cursor, whose statement carries the caller's own LIMIT.
+            const callerLimit = args?.limit ?? this.defaultLimit;
+            const bound = callerLimit === undefined ? undefined : this.paginationValue(callerLimit, 'limit');
             const speculativeDeferred = this.buildFindMany({
                 ...args,
-                limit: batchSize + 1,
+                limit: bound !== undefined && bound <= batchSize ? bound : batchSize + 1,
+                // Only the caller's own bound makes this a page (completePageOrder).
+                ...firstRowOnly(args),
             });
             const speculativeResult = await this.readWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout, streamPreparedName);
             if (speculativeResult.rows.length <= batchSize) {
@@ -3238,22 +3963,100 @@ export class QueryInterface {
         // transaction control of its own (`ambientTransaction`).
         const held = this.txScoped ? null : await this.acquireConnection();
         const client = held?.client ?? null;
-        const conn = client ?? {
+        const base = client ?? {
             query: async (text, values) => (await this.pool.query(text, values)),
         };
+        // The idle guard watches only a stream that holds a connection of its own
+        // between pulls. Inside a caller's transaction the connection is theirs and
+        // their transaction's timeout bounds it. On PostgreSQL the stream's BEGIN
+        // also carries the server-side limit (see streamBackstopStatement), and the
+        // guard keeps a live consumer's transaction from looking idle to it.
+        const watched = held !== null && idleTimeoutMs > 0;
+        const backstop = watched && this.dialect.capabilities.idleTransactionTimeout;
+        let guard;
+        const conn = watched
+            ? watchStreamConnection(base, () => guard, backstop
+                ? { begin: this.dialect.beginStatement(), statement: streamBackstopStatement(idleTimeoutMs) }
+                : undefined)
+            : base;
+        // The cursor's statement carries the `sqlComment` like any other (the
+        // speculative fetch above got it at the execute seam). Never named: a
+        // cursor is declared by text.
+        const streamSql = this.outgoing(deferred.sql, undefined, action).text;
+        const stream = this.dialect.openStream(conn, streamSql, deferred.params, batchSize, {
+            ambientTransaction: this.txScoped,
+        });
+        if (watched) {
+            guard = new StreamIdleGuard(idle, idleTimeoutMs, () => streamIdleExpiredError(action, this.table, idleTimeoutMs, unit), () => this.expireIdleStream(stream, held, action, idleTimeoutMs, idle, unit), backstop ? () => base.query('SELECT 1') : undefined);
+        }
         try {
-            yield* this.dialect.openStream(conn, deferred.sql, deferred.params, batchSize, {
-                ambientTransaction: this.txScoped,
-            });
+            // Driven by hand rather than `yield*`, so an expired stream's cleanup can
+            // run from the timer while this generator is suspended.
+            while (true) {
+                const step = await stream.next();
+                if (step.done)
+                    break;
+                yield step.value;
+                if (idle.expired)
+                    throw idle.expired;
+            }
         }
         catch (err) {
+            if (err === idle.expired)
+                throw err;
             // Wrap pg constraint errors so streaming surfaces typed errors like the rest of the API
             throw explainConnectionLoss(wrapPgError(err), held?.checkout.lostWith);
         }
         finally {
-            held?.checkout.release();
+            guard?.stop();
+            if (guard?.expiry) {
+                // The timer already closed the stream and released the connection;
+                // wait for that so the connection is never handed back mid-cleanup.
+                await guard.expiry;
+            }
+            else {
+                try {
+                    // An early exit (`break`) closes the cursor here; after a full drain
+                    // or an error the dialect's generator has finished and this is a no-op.
+                    await stream.return(undefined);
+                }
+                catch (err) {
+                    // Only an early exit can reach this throw: after an error or a full
+                    // drain the dialect's generator has finished and return() resolves.
+                    // A failed CLOSE / COMMIT on an early exit must reach the caller, as
+                    // it did when this loop was a `yield*`.
+                    // biome-ignore lint/correctness/noUnsafeFinally: it replaces only an early-exit return, see above
+                    throw explainConnectionLoss(wrapPgError(err), held?.checkout.lostWith);
+                }
+                finally {
+                    held?.checkout.release();
+                }
+            }
         }
     }
+    /**
+     * Close a stream whose consumer asked for nothing within its idle timeout:
+     * run the dialect's own cleanup (PostgreSQL: CLOSE, COMMIT), release the
+     * connection (with the cleanup's error, if any, so the pool discards it), and
+     * log `stream-idle-timeout`. The log line matters: an abandoned consumer
+     * never pulls again, so it never sees the E002 waiting for it.
+     */
+    async expireIdleStream(stream, held, action, timeoutMs, idle, unit) {
+        let failure;
+        try {
+            await stream.return(undefined);
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            held.checkout.release(failure === undefined ? undefined : failure instanceof Error ? failure : true);
+        }
+        logTo(this.logger, 'warn', `${action} on "${this.table}" had no ${unit} requested for ${timeoutMs} ms, so Turbine closed its cursor ` +
+            `and released its connection (${idle.rows} ${idle.rows === 1 ? 'row' : 'rows'} handed out before that). ` +
+            'An iterator that is kept and never finished, or a response stream torn down without calling return(), ' +
+            'leaves a stream like this. The next request on it throws TimeoutError (E002).', { code: 'stream-idle-timeout', table: this.table, operation: action, timeoutMs, rows: idle.rows });
+    }
     /**
      * Stream rows from a findMany query using PostgreSQL cursors, one BATCH of
      * rows at a time.
@@ -3289,13 +4092,24 @@ export class QueryInterface {
      * ```
      */
     async *findManyStreamBatches(args) {
+        args = this.normalizeArgs(args);
+        this.assertNoStreamLock(args, 'findManyStreamBatches');
         const parse = this.makeStreamRowParser(args);
-        for await (const batch of this.streamRaw(args, 'findManyStreamBatches')) {
+        const idle = newStreamIdleState();
+        for await (const batch of this.streamRaw(args, 'findManyStreamBatches', idle, 'batch')) {
             const parsed = new Array(batch.length);
             for (let i = 0; i < batch.length; i++) {
                 parsed[i] = parse(batch[i]);
             }
+            idle.rows += parsed.length;
+            // `suspended` and `pulls` are the idle guard's whole view of the
+            // consumer: two writes per yield, no timer work.
+            idle.suspended = true;
             yield parsed;
+            idle.suspended = false;
+            idle.pulls++;
+            if (idle.expired)
+                throw idle.expired;
         }
     }
     /**
@@ -3334,14 +4148,25 @@ export class QueryInterface {
      * ```
      */
     async *findManyStream(args) {
+        args = this.normalizeArgs(args);
+        this.assertNoStreamLock(args, 'findManyStream');
         const parse = this.makeStreamRowParser(args);
         // Parsed one row at a time, INSIDE the yield loop rather than a batch ahead
         // of it, so a consumer that breaks early still pays only for the rows it
         // took. That laziness is the reason this loop is not written over
         // `findManyStreamBatches`.
-        for await (const batch of this.streamRaw(args, 'findManyStream')) {
+        const idle = newStreamIdleState();
+        for await (const batch of this.streamRaw(args, 'findManyStream', idle, 'row')) {
             for (let i = 0; i < batch.length; i++) {
-                yield parse(batch[i]);
+                const row = parse(batch[i]);
+                idle.rows++;
+                // See findManyStreamBatches: the idle guard's view of the consumer.
+                idle.suspended = true;
+                yield row;
+                idle.suspended = false;
+                idle.pulls++;
+                if (idle.expired)
+                    throw idle.expired;
             }
         }
     }
@@ -3349,28 +4174,28 @@ export class QueryInterface {
     // findFirst, like findMany but returns a single row or null
     // -------------------------------------------------------------------------
     async findFirst(args) {
-        // BEFORE the strategy branch, not only inside the builders, so the
-        // join-vs-batched decision and its dev warning see the same declared name
-        // every other stage does. `planAuto` splits `with` on the caller's keys and
-        // `runAutoSplit` carries them onward; each downstream consumer normalizes
-        // too, so this is not load-bearing for correctness (measured: removing it
-        // changes the warning text from the declared name back to the caller's and
-        // nothing else). It is here so the invariant holds at the seam rather than
-        // depending on every consumer to re-establish it.
-        args = this.normalizeArgs(args);
+        // BEFORE the strategy branch, so the batched and auto paths below read the
+        // same canonical args the builders do, and so an all-undefined `where` is
+        // refused before anything runs (see normalizeArgs).
+        args = this.normalizeArgs(args, 'findFirst');
+        this.assertLockInTransaction(args, 'findFirst');
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             if (args?.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
                 // findFirst is findMany + LIMIT 1: batch the single base row, then load.
                 if (strategy === 'batched') {
-                    const rows = await this.runFindManyBatched({ ...args, limit: 1 });
+                    const rows = await this.runFindManyBatched({
+                        ...args,
+                        limit: 1,
+                        ...firstRowOnly(args),
+                    });
                     return (rows[0] ?? null);
                 }
                 if (strategy === 'auto') {
                     // findFirst is findMany + LIMIT 1: a one-row parent set.
                     const split = this.planAuto(args.with, args.stableRelationOrder, false, 1);
                     if (split) {
-                        const rows = (await this.runAutoSplit({ ...args, limit: 1 }, split, false));
+                        const rows = (await this.runAutoSplit({ ...args, limit: 1, ...firstRowOnly(args) }, split, false));
                         return (rows[0] ?? null);
                     }
                 }
@@ -3381,8 +4206,16 @@ export class QueryInterface {
         });
     }
     buildFindFirst(args) {
+        return this.buildFindFirstAs(args, 'findFirst');
+    }
+    /**
+     * findFirst / findFirstOrThrow over findMany's builder with `LIMIT 1`.
+     * `operation` names the method in the refusal of an all-undefined `where`.
+     */
+    buildFindFirstAs(args, operation) {
+        args = this.normalizeArgs(args, operation);
         // Reuse findMany's SQL builder but force LIMIT 1
-        const findManyArgs = { ...args, limit: 1 };
+        const findManyArgs = { ...args, limit: 1, ...firstRowOnly(args) };
         const deferred = this.buildFindMany(findManyArgs);
         return {
             sql: deferred.sql,
@@ -3392,12 +4225,15 @@ export class QueryInterface {
                 return rows.length > 0 ? rows[0] : null;
             },
             tag: `${this.table}.findFirst`,
+            ...(deferred.rowLock ? { rowLock: true } : {}),
         };
     }
     // -------------------------------------------------------------------------
     // findFirstOrThrow, like findFirst but throws if no record found
     // -------------------------------------------------------------------------
     async findFirstOrThrow(args) {
+        args = this.normalizeArgs(args, 'findFirstOrThrow');
+        this.assertLockInTransaction(args, 'findFirstOrThrow');
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
             const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -3405,7 +4241,8 @@ export class QueryInterface {
         });
     }
     buildFindFirstOrThrow(args) {
-        const inner = this.buildFindFirst(args);
+        args = this.normalizeArgs(args, 'findFirstOrThrow');
+        const inner = this.buildFindFirstAs(args, 'findFirstOrThrow');
         return {
             sql: inner.sql,
             params: inner.params,
@@ -3421,12 +4258,15 @@ export class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findFirstOrThrow`,
+            ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
     // -------------------------------------------------------------------------
     // findUniqueOrThrow, like findUnique but throws if no record found
     // -------------------------------------------------------------------------
     async findUniqueOrThrow(args) {
+        args = this.normalizeArgs(args);
+        this.assertLockInTransaction(args, 'findUniqueOrThrow');
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
             const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -3434,6 +4274,7 @@ export class QueryInterface {
         });
     }
     buildFindUniqueOrThrow(args) {
+        args = this.normalizeArgs(args);
         const inner = this.buildFindUnique(args);
         return {
             sql: inner.sql,
@@ -3450,12 +4291,14 @@ export class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findUniqueOrThrow`,
+            ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
     // -------------------------------------------------------------------------
     // create
     // -------------------------------------------------------------------------
     async create(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('create', args, async () => {
             if (hasRelationFields(args.data, this.tableMeta)) {
                 return this.nestedCreate(args);
@@ -3468,16 +4311,55 @@ export class QueryInterface {
     // createMany, uses UNNEST for performance
     // -------------------------------------------------------------------------
     async createMany(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('createMany', args, async () => {
-            const deferred = this.buildCreateMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            const projection = this.resolveWriteProjection(args);
+            const base = args;
+            // One statement when the rows fit the engine's per-statement limits,
+            // else chunks that do, all in one transaction so the rows land together
+            // or not at all. (`buildCreateMany`, one statement for a pipeline,
+            // refuses instead.)
+            const { chunks, rowsPerChunk } = writesMod.planCreateMany(this.ctx, base, projection);
+            const run = async () => {
+                // An engine that applies two rows whose onConflict keys are equal only
+                // under the column's collation (SQLite's NOCASE) as an insert and an
+                // update of one row, in one statement, is caught by the transform (the
+                // row comes back twice), so the statement runs in a transaction that
+                // refusal rolls back. A reselect write already runs in one.
+                const appliesRepeatedKeys = base.onConflict !== undefined &&
+                    this.dialect.capabilities.bulkUpsertAppliesRepeatedKeys &&
+                    this.dialect.resultStrategy !== 'reselect';
+                if (chunks.length === 1 && !appliesRepeatedKeys) {
+                    return this.executeMutation(chunks[0], args.timeout);
+                }
+                const reselects = this.dialect.resultStrategy === 'reselect';
+                return this.inOneTransaction(async (exec) => {
+                    const rows = [];
+                    for (const chunk of chunks) {
+                        const result = reselects && chunk.reselect
+                            ? await chunk.reselect(exec)
+                            : await exec(chunk.sql, chunk.params, chunk.preparedName);
+                        rows.push(...chunk.transform(result));
+                    }
+                    return rows;
+                }, args.timeout, `createMany of ${base.data.length} rows`, `Insert at most ${rowsPerChunk} rows per call, which fits one statement, or pass a pool that can check ` +
+                    'out a connection.');
+            };
+            if (base.onConflict === undefined)
+                return run();
+            try {
+                return await run();
+            }
+            catch (err) {
+                throw writesMod.explainConflictKeyCollision(this.ctx, base, err);
+            }
         });
     }
     // -------------------------------------------------------------------------
     // update
     // -------------------------------------------------------------------------
     async update(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('update', args, async () => {
             if (hasRelationFields(args.data, this.tableMeta)) {
                 return this.nestedUpdate(args);
@@ -3590,6 +4472,7 @@ export class QueryInterface {
     // delete
     // -------------------------------------------------------------------------
     async delete(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('delete', args, async () => {
             const deferred = this.buildDelete(args);
             return this.executeMutation(deferred, args.timeout);
@@ -3599,7 +4482,11 @@ export class QueryInterface {
     // upsert, INSERT ... ON CONFLICT ... DO UPDATE
     // -------------------------------------------------------------------------
     async upsert(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('upsert', args, async () => {
+            // First: the nested-write branch below decides before upsertLookupReason
+            // would have refused it.
+            writesMod.assertNoOptimisticLock(this.ctx, args, 'upsert');
             if (this.upsertNeedsLookup(args)) {
                 return this.upsertLookupFirst(args);
             }
@@ -3614,6 +4501,7 @@ export class QueryInterface {
      * an upsert or has to run the array inside a transaction.
      */
     upsertNeedsLookup(args) {
+        args = this.normalizeArgs(args);
         return (hasRelationFields((args.create ?? {}), this.tableMeta) ||
             hasRelationFields((args.update ?? {}), this.tableMeta) ||
             writesMod.upsertLookupReason(this.ctx, args) !== null);
@@ -3642,7 +4530,11 @@ export class QueryInterface {
     async upsertLookupFirst(args) {
         const where = (args.where ?? {});
         const create = (args.create ?? {});
-        const update = (args.update ?? {});
+        // `expr.excluded(field)` in `update` reads the incoming row, which here is
+        // `create`: resolved to create's value before the update compiles, as the
+        // single-statement path does.
+        const update = (resolveExcludedFromCreate(this.ctx, (args.update ?? {}), create) ??
+            {});
         assertMutationWhereIdentifiesOneRow(this.tableMeta, this.table, expandCompoundUniqueWhere(this.tableMeta, where), 'upsert');
         this.resolveWriteProjection(args);
         // An undefined option is an absent one on every call below.
@@ -3676,6 +4568,7 @@ export class QueryInterface {
     // updateMany, UPDATE ... WHERE ... returning count
     // -------------------------------------------------------------------------
     async updateMany(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('updateMany', args, async () => {
             const deferred = this.buildUpdateMany(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
@@ -3686,6 +4579,7 @@ export class QueryInterface {
     // deleteMany, DELETE ... WHERE ... returning count
     // -------------------------------------------------------------------------
     async deleteMany(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('deleteMany', args, async () => {
             const deferred = this.buildDeleteMany(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
@@ -3696,6 +4590,7 @@ export class QueryInterface {
     // count
     // -------------------------------------------------------------------------
     async count(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('count', (args ?? {}), async () => {
             const deferred = this.buildCount(args);
             const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -3703,6 +4598,7 @@ export class QueryInterface {
         });
     }
     buildCount(args) {
+        args = this.normalizeArgs(args);
         this.currentSkip = resolveSkipGlobalFilters(args?.skipGlobalFilters);
         const effWhere = this.mergeGlobalFilter(args?.where);
         const hasWhere = effWhere !== undefined;
@@ -3740,6 +4636,7 @@ export class QueryInterface {
      * that cannot be typed, so those columns are not projected onto the row type.
      */
     async groupBy(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
             const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -3750,15 +4647,16 @@ export class QueryInterface {
     // Aggregate / groupBy compilation (extracted to aggregates.ts).
     // ---------------------------------------------------------------------------
     buildGroupBy(args) {
-        return aggMod.buildGroupBy(this.ctx, args);
+        return aggMod.buildGroupBy(this.ctx, this.normalizeArgs(args));
     }
     buildAggregate(args) {
-        return aggMod.buildAggregate(this.ctx, args);
+        return aggMod.buildAggregate(this.ctx, this.normalizeArgs(args));
     }
     // -------------------------------------------------------------------------
     // aggregate, standalone aggregation without groupBy
     // -------------------------------------------------------------------------
     async aggregate(args) {
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('aggregate', args, async () => {
             const deferred = this.buildAggregate(args);
             const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
@@ -3876,14 +4774,15 @@ export class QueryInterface {
         }
         return relationsMod.planFlattenWith(this.ctx, this.table, withClause, includePii);
     }
-    /** Dev-only once-only note that `'flatten'` was refused for the whole query. */
+    /** Advice, once per reason: `'flatten'` was refused for the whole query. */
     warnFlattenBlocked(reason) {
-        if (process.env.NODE_ENV === 'production')
+        const log = this.advice;
+        if (!log)
             return;
         if (!shouldWarnOnce(WARN_NS.flattenFallback, `${this.table}|query|${reason}`))
             return;
-        console.warn(`[turbine] relationLoadStrategy: 'flatten' did not engage on "${this.table}": ${reason}. ` +
-            'Every relation loads via the correlated subquery instead (same rows, same values, different plan).');
+        logTo(log, 'warn', `relationLoadStrategy: 'flatten' did not engage on "${this.table}": ${reason}. ` +
+            'Every relation loads via the correlated subquery instead (same rows, same values, different plan).', { code: 'flatten-blocked', table: this.table, reason });
     }
     /**
      * Convert a field name to its snake_case column name (unquoted, for non-SQL
@@ -4018,8 +4917,8 @@ export class QueryInterface {
             // To-many relation orderBy (`{ posts: { _count } }`) uses the same count
             // subquery as `_count`: mirror its global-filter params. Pick-row
             // ordering mirrors its full param chain (by-path / global filter /
-            // pick.where / pick.orderBy paths). To-one relation orderBy carries the
-            // target's global filter once per ordered column.
+            // pick.where / pick.orderBy paths). To-one relation orderBy is mirrored
+            // by running its build (see collectToOneRelationOrderParams).
             if (this.isRelationOrderByValue(dir)) {
                 // Mirrors the build path's resolution, so a cache HIT binds params for
                 // the same relation the cached SQL was built from.
@@ -4032,9 +4931,7 @@ export class QueryInterface {
                     this.collectRelationCountParams(relDef, params);
                 }
                 else if (relDef) {
-                    for (const _col of Object.keys(dir)) {
-                        this.collectTargetGlobalFilterAlias(relDef.to, params);
-                    }
+                    relationsMod.collectToOneRelationOrderParams(this.ctx, key, dir, params);
                 }
             }
         }
@@ -4106,10 +5003,10 @@ export class QueryInterface {
      * one, is the acknowledgement, and the warning exists to surface an
      * unacknowledged trade rather than to nag.
      *
-     * NOT DEV-ONLY, unlike every other warning in this codebase, and deliberately
-     * so. Production is exactly where a destructive write commits and where the
-     * row cannot be recovered afterwards, so a warning that goes quiet under
-     * `NODE_ENV=production` is silent in the only place it matters. The cost is
+     * NOT ADVICE: it fires whatever `diagnostics` says, deliberately. Production
+     * is exactly where a destructive write commits and where the row cannot be
+     * recovered afterwards, so a warning that goes quiet in production mode is
+     * silent in the only place it matters. The cost is
      * bounded to the point of irrelevance: once per process per field, and only
      * on a row that actually held an infinity.
      *
@@ -4122,7 +5019,7 @@ export class QueryInterface {
             return;
         if (!shouldWarnOnce(WARN_NS.temporalInfinity, `${table}.${field}`))
             return;
-        console.warn(`[turbine] ${table}.${field} holds the Postgres value \`infinity\` (or \`-infinity\`). JavaScript has ` +
+        logTo(this.logger, 'warn', `${table}.${field} holds the Postgres value \`infinity\` (or \`-infinity\`). JavaScript has ` +
             'no Date for it, so it reads as the JS number `Infinity` / `-Infinity` on a field the generated ' +
             'types declare as `Date`: `.toISOString()` and `.getTime()` throw a TypeError on these rows, and ' +
             '`JSON.stringify` still renders them null because JSON has no infinity literal. The number is the ' +
@@ -4132,7 +5029,7 @@ export class QueryInterface {
             "cannot tell infinity, -infinity and NULL apart. Set `temporalInfinity: 'preserve'` to confirm this " +
             "reading and silence the warning, or `'null'` to read null instead, accepting that a stored " +
             'infinity then looks exactly like a stored NULL and a read-modify-write over a nullable column ' +
-            'stores SQL NULL, destroying the value with no error.');
+            'stores SQL NULL, destroying the value with no error.', { code: 'temporal-infinity', table, field });
     }
     /**
      * Apply the configured reading to the infinity elements of a temporal ARRAY
@@ -4212,6 +5109,64 @@ export class QueryInterface {
         // UTC so results don't depend on the server's time zone.
         return this.utcTimestamps ? parseDbDate(String(value)) : new Date(value);
     }
+    /** The non-temporal decode kinds of `table`'s columns, by column and by field name. */
+    getCellKinds(table, meta) {
+        let kinds = this.cellKindCache.get(table);
+        if (!kinds) {
+            kinds = new Map();
+            for (const column of meta.columns) {
+                // Metadata may carry the type on the column or only in the table map.
+                const pgType = column.pgType ?? meta.pgTypes?.[column.name];
+                if (typeof pgType !== 'string')
+                    continue;
+                let kind = cellKindOf(pgType, this.schema.enums);
+                const decode = kind === CELL_PLAIN ? this.dialect.decodeColumnValue?.(pgType) : undefined;
+                if (decode !== undefined) {
+                    kind = CELL_DIALECT;
+                    let decoders = this.dialectDecodeCache.get(table);
+                    if (!decoders) {
+                        decoders = new Map();
+                        this.dialectDecodeCache.set(table, decoders);
+                    }
+                    decoders.set(column.name, decode);
+                    decoders.set(column.field, decode);
+                }
+                if (kind === CELL_PLAIN)
+                    continue;
+                kinds.set(column.name, kind);
+                kinds.set(column.field, kind);
+            }
+            this.cellKindCache.set(table, kinds);
+        }
+        return kinds;
+    }
+    /** One cell's decode, for every kind but {@link CELL_PLAIN}. */
+    decodeCell(kind, value, table, field) {
+        switch (kind) {
+            case CELL_TEMPORAL:
+                return this.decodeTemporalCell(value, table, field);
+            case CELL_FLOAT:
+                return readJsonFloat(value);
+            case CELL_FLOAT_ARRAY:
+                return readJsonFloatArray(value);
+            case CELL_TEXT_ARRAY:
+                return readTextArray(value);
+            case CELL_DIALECT:
+                return this.decodeDialectCell(value, table, field);
+            default:
+                return value;
+        }
+    }
+    /**
+     * A {@link CELL_DIALECT} cell: the dialect's decode for the column's declared
+     * type, recorded by {@link getCellKinds} when it classified the column.
+     */
+    decodeDialectCell(value, table, field) {
+        if (value === null || value === undefined)
+            return value;
+        const decode = this.dialectDecodeCache.get(table)?.get(field);
+        return decode ? decode(value) : value;
+    }
     /**
      * Build the decode plan for one exact column list, and remember it as this
      * table's most recent shape so the next row of the same result set hits the
@@ -4235,16 +5190,19 @@ export class QueryInterface {
             // camelCase-keyed date fields, so nested json_build_object rows (whose
             // keys are already camelCase) get the same Date coercion as top-level rows.
             const camelDateFields = this.getCamelDateFields(table, meta);
+            const cellKinds = this.getCellKinds(table, meta);
             const cols = keys.slice();
             const fields = [];
-            const dates = [];
+            const kinds = [];
             for (const col of cols) {
                 const field = reverseMap[col] ?? col; // fall back to raw col name, not regex
                 fields.push(field);
                 // Top-level rows are snake_case (dateCols); nested rows are camelCase.
-                dates.push(dateCols.has(col) || camelDateFields.has(field));
+                kinds.push(dateCols.has(col) || camelDateFields.has(field)
+                    ? CELL_TEMPORAL
+                    : (cellKinds.get(col) ?? cellKinds.get(field) ?? CELL_PLAIN));
             }
-            plan = { cols, fields, dates };
+            plan = { cols, fields, kinds };
             this.rowPlanCache.set(shapeKey, plan);
         }
         this.rowPlanLast.set(table, plan);
@@ -4288,11 +5246,16 @@ export class QueryInterface {
             const plan = last !== undefined && QueryInterface.rowPlanMatches(last, keys)
                 ? last
                 : this.buildRowDecodePlan(table, meta, keys);
-            const { cols, fields, dates } = plan;
+            const { cols, fields, kinds } = plan;
             for (let i = 0; i < cols.length; i++) {
                 const field = fields[i];
                 const value = row[cols[i]];
-                parsed[field] = dates[i] ? this.decodeTemporalCell(value, table, field) : value;
+                const kind = kinds[i];
+                // A float from the driver is already a number; only JSON's strings need reading.
+                parsed[field] =
+                    kind === CELL_PLAIN || (kind === CELL_FLOAT && typeof value !== 'string')
+                        ? value
+                        : this.decodeCell(kind, value, table, field);
             }
         }
         else {