turbine-orm 0.7.0 → 0.8.0

package/dist/query.js

@@ -71,6 +71,14 @@ function isWhereOperator(value) {
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * appear in any other where-filter shape, so the presence of one of these is
+ * an unambiguous signal that the user meant a JSON filter. Used by the
+ * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
+ * `WhereOperator` for LIKE) is not misclassified.
+ */
+const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
 /** Check if a value is a JSONB filter object */
 function isJsonFilter(value) {
     if (value === null ||
@@ -83,8 +91,27 @@ function isJsonFilter(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.some((k) => JSONB_OPERATOR_KEYS.has(k));
 }
+/**
+ * Returns the first JSON-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findJsonUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (JSONB_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
 /** Known Array operator keys */
 const ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/**
+ * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
+ * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
+ * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
+ * constant so a future overlap (e.g. a `contains` for arrays) is easy to
+ * carve out.
+ */
+const ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
 /** Check if a value is an Array filter object */
 function isArrayFilter(value) {
     if (value === null ||
@@ -97,6 +124,17 @@ function isArrayFilter(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.some((k) => ARRAY_OPERATOR_KEYS.has(k));
 }
+/**
+ * Returns the first array-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findArrayUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (ARRAY_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // LRU cache — bounded SQL template cache to prevent memory leaks
 // ---------------------------------------------------------------------------
@@ -136,16 +174,56 @@ class LRUCache {
         return this.cache.size;
     }
 }
+/**
+ * FNV-1a 64-bit hash returning 16 lowercase hex chars.
+ * Single-loop string iteration. Uses BigInt for 64-bit math.
+ *
+ * @internal Exported for testing only.
+ */
+export function fnv1a64Hex(s) {
+    // FNV-1a offset basis and prime for 64-bit
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn; // 64-bit mask
+    for (let i = 0; i < s.length; i++) {
+        hash ^= BigInt(s.charCodeAt(i));
+        hash = (hash * prime) & mask;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/**
+ * Derive a prepared-statement name from a SQL string.
+ * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
+ *
+ * @internal Exported for testing only.
+ */
+export function sqlToPreparedName(sql) {
+    return `t_${fnv1a64Hex(sql)}`;
+}
 export class QueryInterface {
     pool;
     table;
     schema;
     tableMeta;
-    /** SQL template cache: cacheKey → sql string (params are always positional $1,$2,...) */
-    sqlCache = new LRUCache(1000);
+    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
+    sqlTemplateCache = new LRUCache(1000);
     middlewares;
     defaultLimit;
     warnOnUnlimited;
+    preparedStatementsEnabled;
+    sqlCacheEnabled;
+    /**
+     * Tracks tables that have already triggered an unlimited-query warning so
+     * the user is not spammed once per row. Per-instance state — each
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * 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;
     /** Pre-computed column type lookups (avoids linear scans per query) */
     columnPgTypeMap;
     columnArrayTypeMap;
@@ -160,7 +238,12 @@ export class QueryInterface {
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];
         this.defaultLimit = options?.defaultLimit;
-        this.warnOnUnlimited = options?.warnOnUnlimited ?? false;
+        // Default to ON: surfacing accidental full-table scans is more valuable
+        // than the (small) risk of noisy logs. Callers explicitly opt out with
+        // `warnOnUnlimited: false`.
+        this.warnOnUnlimited = options?.warnOnUnlimited !== false;
+        this.preparedStatementsEnabled = options?.preparedStatements ?? true;
+        this.sqlCacheEnabled = options?.sqlCache !== false;
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
@@ -169,15 +252,66 @@ export class QueryInterface {
             this.columnArrayTypeMap.set(col.name, col.pgArrayType);
         }
     }
+    /**
+     * Return cache hit/miss statistics for this QueryInterface instance.
+     * Useful for monitoring and benchmarking.
+     */
+    cacheStats() {
+        const total = this.cacheHits + this.cacheMisses;
+        return {
+            hits: this.cacheHits,
+            misses: this.cacheMisses,
+            hitRate: total > 0 ? this.cacheHits / total : 0,
+            size: this.sqlTemplateCache.size,
+        };
+    }
+    /**
+     * Look up or build a SQL template in the cache.
+     * On miss, calls `build()` to generate the SQL, stores the entry, and returns it.
+     * On hit, increments counters and returns the cached entry.
+     *
+     * When `sqlCache` is disabled, always calls `build()` without caching.
+     */
+    acquireSql(cacheKey, build) {
+        if (!this.sqlCacheEnabled) {
+            const sql = build();
+            this.cacheMisses++;
+            return { sql, name: sqlToPreparedName(sql) };
+        }
+        const cached = this.sqlTemplateCache.get(cacheKey);
+        if (cached) {
+            this.cacheHits++;
+            return cached;
+        }
+        const sql = build();
+        const entry = { sql, name: sqlToPreparedName(sql) };
+        this.sqlTemplateCache.set(cacheKey, entry);
+        this.cacheMisses++;
+        return entry;
+    }
+    /**
+     * 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.
+     */
+    resetUnlimitedWarnings() {
+        this.warnedTables.clear();
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
-    async queryWithTimeout(sql, params, timeout) {
+    async queryWithTimeout(sql, params, timeout, preparedName) {
+        // Build the query argument — use object form with `name` for prepared
+        // statements, or the plain (text, values) form otherwise.
+        const usePrepared = preparedName && this.preparedStatementsEnabled;
+        const exec = usePrepared
+            ? this.pool.query({ name: preparedName, text: sql, values: params })
+            : this.pool.query(sql, params);
         if (!timeout) {
             try {
-                return await this.pool.query(sql, params);
+                return await exec;
             }
             catch (err) {
                 throw wrapPgError(err);
@@ -188,7 +322,7 @@ export class QueryInterface {
             timer = setTimeout(() => reject(new TimeoutError(timeout)), timeout);
         });
         try {
-            return await Promise.race([this.pool.query(sql, params), timeoutPromise]);
+            return await Promise.race([exec, timeoutPromise]);
         }
         catch (err) {
             throw wrapPgError(err);
@@ -229,148 +363,248 @@ export class QueryInterface {
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
             const deferred = this.buildFindUnique(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildFindUnique(args) {
         const columnsList = this.resolveColumns(args.select, args.omit);
         const whereObj = args.where;
+        const colKey = columnsList ? columnsList.join(',') : '*';
+        const whereFingerprint = this.fingerprintWhere(whereObj);
+        const withFp = args.with ? this.withFingerprint(args.with) : '';
+        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
+        const params = [];
         // Check if all where values are simple (plain equality, no operators/null/OR)
         const whereKeys = Object.keys(whereObj).filter((k) => whereObj[k] !== undefined);
         const isSimpleWhere = !whereObj.OR &&
+            !whereObj.AND &&
+            !whereObj.NOT &&
             whereKeys.every((k) => {
                 const v = whereObj[k];
-                return v !== null && !isWhereOperator(v);
+                return v !== null && !isWhereOperator(v) && !this.tableMeta.relations[k];
             });
-        // For simple queries (no nested with, no operators), use cached SQL template
+        // Simple path: plain equality, no operators/null/OR
         if (!args.with && isSimpleWhere) {
-            const colKey = columnsList ? columnsList.join(',') : '*';
-            const ck = `fu:${whereKeys.sort().join(',')}:c=${colKey}`;
-            let sql = this.sqlCache.get(ck);
-            const params = whereKeys.map((k) => whereObj[k]);
-            if (!sql) {
+            const entry = this.acquireSql(ck, () => {
                 const qt = quoteIdent(this.table);
+                const tempParams = whereKeys.map((k) => whereObj[k]);
                 const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = $${i + 1}`);
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
-                sql = `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
-                this.sqlCache.set(ck, sql);
+                void tempParams; // params are positional, SQL is value-invariant
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+            });
+            // Collect params (same order as build)
+            for (const k of whereKeys) {
+                params.push(whereObj[k]);
             }
             return {
-                sql,
+                sql: entry.sql,
                 params,
                 transform: (result) => {
                     const row = result.rows[0];
                     return row ? this.parseRow(row, this.table) : null;
                 },
                 tag: `${this.table}.findUnique`,
+                preparedName: entry.name,
             };
         }
-        // General path: supports operators, null, OR, nested with
-        const { sql: whereSql, params } = this.buildWhere(args.where);
+        // General path (with operators, null, OR, with clause)
         if (!args.with) {
-            const qt = quoteIdent(this.table);
-            const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
-            const sql = `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+            const entry = this.acquireSql(ck, () => {
+                const freshParams = [];
+                const clause = this.buildWhereClause(whereObj, freshParams);
+                const whereSql = clause ? ` WHERE ${clause}` : '';
+                const qt = quoteIdent(this.table);
+                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+            });
+            // Collect params
+            this.collectWhereParams(whereObj, params);
             return {
-                sql,
+                sql: entry.sql,
                 params,
                 transform: (result) => {
                     const row = result.rows[0];
                     return row ? this.parseRow(row, this.table) : null;
                 },
                 tag: `${this.table}.findUnique`,
+                preparedName: entry.name,
             };
         }
-        // Nested queries: build fresh each time (with clause affects params)
-        const selectClause = this.buildSelectWithRelations(this.table, args.with, params, columnsList);
-        const sql = `SELECT ${selectClause} FROM ${quoteIdent(this.table)}${whereSql} LIMIT 1`;
+        // Nested queries with `with` clause.
+        // The param order in the original code is:
+        //   1. buildWhere pushes where params
+        //   2. buildSelectWithRelations pushes relation params to same array
+        // We must preserve this exact order.
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const clause = this.buildWhereClause(whereObj, freshParams);
+            const whereSql = clause ? ` WHERE ${clause}` : '';
+            const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
+            return `SELECT ${selectClause} FROM ${quoteIdent(this.table)}${whereSql} LIMIT 1`;
+        });
+        // Collect params in exact build order: where first, then with-clause relations
+        this.collectWhereParams(whereObj, params);
+        this.collectWithParams(args.with, params);
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
                 return row ? this.parseNestedRow(row, this.table) : null;
             },
             tag: `${this.table}.findUnique`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
     // findMany
     // -------------------------------------------------------------------------
     async findMany(args) {
-        // Warn if no limit specified and warnOnUnlimited is enabled
-        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined;
-        if (this.warnOnUnlimited && !hasExplicitLimit) {
-            console.warn(`[turbine] findMany() called without limit on table "${this.table}". Set defaultLimit in config to prevent unbounded queries.`);
-        }
+        this.maybeWarnUnlimited(args);
         return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
             const deferred = this.buildFindMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
+    /**
+     * Emit a one-time `console.warn` 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.
+     * 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`.
+     */
+    maybeWarnUnlimited(args) {
+        if (!this.warnOnUnlimited)
+            return;
+        if (this.defaultLimit !== undefined)
+            return;
+        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined || args?.cursor !== undefined;
+        if (hasExplicitLimit)
+            return;
+        if (this.warnedTables.has(this.table))
+            return;
+        this.warnedTables.add(this.table);
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
+            'Pass `limit` or set `warnOnUnlimited: false` in config to silence.');
+    }
     buildFindMany(args) {
-        const { sql: whereSql, params } = args?.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         const columnsList = this.resolveColumns(args?.select, args?.omit);
-        const qt = quoteIdent(this.table);
-        // Distinct support
-        let distinctPrefix = '';
-        if (args?.distinct && args.distinct.length > 0) {
-            const distinctCols = args.distinct.map((k) => this.toSqlColumn(k));
-            distinctPrefix = `DISTINCT ON (${distinctCols.join(', ')}) `;
+        const colKey = columnsList ? columnsList.join(',') : '*';
+        const whereObj = (args?.where ?? {});
+        // Build fingerprint for cache lookup
+        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
+        const withFp = args?.with ? this.withFingerprint(args.with) : '';
+        const orderFp = args?.orderBy
+            ? Object.entries(args.orderBy)
+                .map(([k, d]) => `${k}:${d}`)
+                .join(',')
+            : '';
+        const cursorFp = args?.cursor
+            ? Object.keys(args.cursor)
+                .filter((k) => args.cursor[k] !== undefined)
+                .sort()
+                .join(',')
+            : '';
+        const distinctFp = args?.distinct ? args.distinct.slice().sort().join(',') : '';
+        const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
+        const limitFp = effectiveLimit !== undefined ? '1' : '0';
+        const offsetFp = args?.offset !== undefined ? '1' : '0';
+        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}`;
+        const params = [];
+        const entry = this.acquireSql(ck, () => {
+            // Fresh build — generates SQL and populates freshParams
+            const freshParams = [];
+            const { sql: freshWhereSql } = args?.where
+                ? (() => {
+                    const clause = this.buildWhereClause(whereObj, freshParams);
+                    return { sql: clause ? ` WHERE ${clause}` : '' };
+                })()
+                : { sql: '' };
+            const qt = quoteIdent(this.table);
+            let distinctPrefix = '';
+            if (args?.distinct && args.distinct.length > 0) {
+                const distinctCols = args.distinct.map((k) => this.toSqlColumn(k));
+                distinctPrefix = `DISTINCT ON (${distinctCols.join(', ')}) `;
+            }
+            let selectClause;
+            if (args?.with) {
+                selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
+            }
+            else if (columnsList) {
+                selectClause = columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ');
+            }
+            else {
+                selectClause = `${qt}.*`;
+            }
+            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            if (args?.cursor) {
+                const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+                if (cursorEntries.length > 0) {
+                    const cursorConditions = cursorEntries.map(([k, v]) => {
+                        const col = this.toSqlColumn(k);
+                        const dir = args.orderBy?.[k] ?? 'asc';
+                        const op = dir === 'desc' ? '<' : '>';
+                        freshParams.push(v);
+                        return `${qt}.${col} ${op} $${freshParams.length}`;
+                    });
+                    if (freshWhereSql) {
+                        sql += ` AND ${cursorConditions.join(' AND ')}`;
+                    }
+                    else {
+                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
+                    }
+                }
+            }
+            if (args?.orderBy) {
+                sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            }
+            if (effectiveLimit !== undefined) {
+                freshParams.push(Number(effectiveLimit));
+                sql += ` LIMIT $${freshParams.length}`;
+            }
+            if (args?.offset !== undefined) {
+                freshParams.push(Number(args.offset));
+                sql += ` OFFSET $${freshParams.length}`;
+            }
+            return sql;
+        });
+        // Collect params in exact build order:
+        // 1. WHERE params
+        if (args?.where) {
+            this.collectWhereParams(whereObj, params);
         }
-        let selectClause;
+        // 2. WITH relation params
         if (args?.with) {
-            selectClause = this.buildSelectWithRelations(this.table, args.with, params, columnsList);
-        }
-        else if (columnsList) {
-            selectClause = columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ');
+            this.collectWithParams(args.with, params);
         }
-        else {
-            selectClause = `${qt}.*`;
-        }
-        let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${whereSql}`;
-        // Cursor-based pagination: add WHERE condition for cursor
+        // 3. Cursor params
         if (args?.cursor) {
             const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
-            if (cursorEntries.length > 0) {
-                // Determine direction from orderBy (default 'asc')
-                const cursorConditions = cursorEntries.map(([k, v]) => {
-                    const col = this.toSqlColumn(k);
-                    const dir = args.orderBy?.[k] ?? 'asc';
-                    const op = dir === 'desc' ? '<' : '>';
-                    params.push(v);
-                    return `${qt}.${col} ${op} $${params.length}`;
-                });
-                // Append to existing WHERE or create new one
-                if (whereSql) {
-                    sql += ` AND ${cursorConditions.join(' AND ')}`;
-                }
-                else {
-                    sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                }
+            for (const [, v] of cursorEntries) {
+                params.push(v);
             }
         }
-        if (args?.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
-        }
-        // take overrides limit when cursor pagination is used; fall back to defaultLimit
-        const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
+        // 4. LIMIT param
         if (effectiveLimit !== undefined) {
             params.push(Number(effectiveLimit));
-            sql += ` LIMIT $${params.length}`;
         }
+        // 5. OFFSET param
         if (args?.offset !== undefined) {
             params.push(Number(args.offset));
-            sql += ` OFFSET $${params.length}`;
         }
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => result.rows.map((row) => args?.with ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table)),
             tag: `${this.table}.findMany`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -380,9 +614,21 @@ export class QueryInterface {
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
      *
-     * Uses DECLARE CURSOR within a dedicated transaction on a single pooled connection.
-     * The cursor is automatically closed and the connection released when iteration
-     * completes or is terminated early (e.g. `break` from `for await`).
+     * **Speculative fast-path:** Before opening a cursor, issues a single
+     * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
+     * all rows are yielded immediately with zero cursor overhead (no BEGIN /
+     * DECLARE / CLOSE / COMMIT). Only when the result overflows does the
+     * method fall back to the full cursor path.
+     *
+     * **Cursor path:** Uses DECLARE CURSOR within a dedicated transaction on a
+     * single pooled connection. The cursor is automatically closed and the
+     * connection released when iteration completes or is terminated early
+     * (e.g. `break` from `for await`).
+     *
+     * **Snapshot semantics note:** The speculative fast-path runs outside a
+     * transaction. If the result overflows and the cursor path is opened, the
+     * cursor runs in its own transaction — spanning two separate snapshots.
+     * For strict single-snapshot semantics, wrap the call in `$transaction`.
      *
      * @example
      * ```ts
@@ -392,9 +638,23 @@ export class QueryInterface {
      * ```
      */
     async *findManyStream(args) {
-        const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 100)));
-        const deferred = this.buildFindMany(args);
+        const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         const hasRelations = !!args?.with;
+        // --- Speculative first fetch: try to satisfy the entire drain in one RTT ---
+        const speculativeDeferred = this.buildFindMany({
+            ...args,
+            limit: batchSize + 1,
+        });
+        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
+        if (speculativeResult.rows.length <= batchSize) {
+            // Small drain — yield all rows and return, no cursor needed
+            for (const row of speculativeResult.rows) {
+                yield (hasRelations ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table));
+            }
+            return;
+        }
+        // --- Overflow: fall back to cursor path from scratch ---
+        const deferred = this.buildFindMany(args);
         // Acquire a dedicated connection — cursors require a single connection in a transaction
         const client = await this.pool.connect();
         const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -436,7 +696,7 @@ export class QueryInterface {
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             const deferred = this.buildFindFirst(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -460,7 +720,7 @@ export class QueryInterface {
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -489,7 +749,7 @@ export class QueryInterface {
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -518,7 +778,7 @@ export class QueryInterface {
     async create(args) {
         return this.executeWithMiddleware('create', args, async () => {
             const deferred = this.buildCreate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -551,7 +811,7 @@ export class QueryInterface {
     async createMany(args) {
         return this.executeWithMiddleware('createMany', args, async () => {
             const deferred = this.buildCreateMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -598,22 +858,35 @@ export class QueryInterface {
     async update(args) {
         return this.executeWithMiddleware('update', args, async () => {
             const deferred = this.buildUpdate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildUpdate(args) {
-        const setEntries = Object.entries(args.data).filter(([, v]) => v !== undefined);
-        // Build SET params first (supports atomic operators: set/increment/decrement/multiply/divide)
+        const dataObj = args.data;
+        const whereObj = args.where;
+        const setFp = this.fingerprintSet(dataObj);
+        const whereFp = this.fingerprintWhere(whereObj);
+        const ck = `u:${setFp}|${whereFp}`;
         const params = [];
-        const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, params));
-        // Build WHERE using the shared params array (continues numbering after SET params)
-        const whereClause = this.buildWhereClause(args.where, params);
-        const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
-        this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
-        const sql = `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
+            const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
+            const whereClause = this.buildWhereClause(whereObj, freshParams);
+            const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+            this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
+            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
+        });
+        // On cache hit, validate predicate
+        if (whereFp === '') {
+            this.assertMutationHasPredicate('update', '', args.allowFullTableScan);
+        }
+        // Collect params: SET first, then WHERE (same order as fresh build)
+        this.collectSetParams(dataObj, params);
+        this.collectWhereParams(whereObj, params);
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
@@ -627,6 +900,7 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.update`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -635,16 +909,31 @@ export class QueryInterface {
     async delete(args) {
         return this.executeWithMiddleware('delete', args, async () => {
             const deferred = this.buildDelete(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildDelete(args) {
-        const { sql: whereSql, params } = this.buildWhere(args.where);
-        this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
-        const sql = `DELETE FROM ${quoteIdent(this.table)}${whereSql} RETURNING *`;
+        const whereObj = args.where;
+        const whereFp = this.fingerprintWhere(whereObj);
+        const ck = `d:${whereFp}`;
+        const params = [];
+        // We need to check the mutation predicate. Build the whereSql to test it.
+        // On cache hit we still need to validate (the shape may be empty).
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const clause = this.buildWhereClause(whereObj, freshParams);
+            const whereSql = clause ? ` WHERE ${clause}` : '';
+            this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
+            return `DELETE FROM ${quoteIdent(this.table)}${whereSql} RETURNING *`;
+        });
+        // On cache hit, still validate the predicate
+        if (whereFp === '') {
+            this.assertMutationHasPredicate('delete', '', args.allowFullTableScan);
+        }
+        this.collectWhereParams(whereObj, params);
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
@@ -658,6 +947,7 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.delete`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -666,7 +956,7 @@ export class QueryInterface {
     async upsert(args) {
         return this.executeWithMiddleware('upsert', args, async () => {
             const deferred = this.buildUpsert(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -716,25 +1006,37 @@ export class QueryInterface {
     async updateMany(args) {
         return this.executeWithMiddleware('updateMany', args, async () => {
             const deferred = this.buildUpdateMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildUpdateMany(args) {
-        const setEntries = Object.entries(args.data).filter(([, v]) => v !== undefined);
-        // Build SET params first (supports atomic operators: set/increment/decrement/multiply/divide)
+        const dataObj = args.data;
+        const whereObj = args.where;
+        const setFp = this.fingerprintSet(dataObj);
+        const whereFp = this.fingerprintWhere(whereObj);
+        const ck = `um:${setFp}|${whereFp}`;
         const params = [];
-        const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, params));
-        // Build WHERE using the shared params array (continues numbering after SET params)
-        const whereClause = this.buildWhereClause(args.where, params);
-        const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
-        this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
-        const sql = `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
+            const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
+            const whereClause = this.buildWhereClause(whereObj, freshParams);
+            const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+            this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
+            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
+        });
+        if (whereFp === '') {
+            this.assertMutationHasPredicate('updateMany', '', args.allowFullTableScan);
+        }
+        this.collectSetParams(dataObj, params);
+        this.collectWhereParams(whereObj, params);
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => ({ count: result.rowCount ?? 0 }),
             tag: `${this.table}.updateMany`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -743,19 +1045,32 @@ export class QueryInterface {
     async deleteMany(args) {
         return this.executeWithMiddleware('deleteMany', args, async () => {
             const deferred = this.buildDeleteMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildDeleteMany(args) {
-        const { sql: whereSql, params } = this.buildWhere(args.where);
-        this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
-        const sql = `DELETE FROM ${quoteIdent(this.table)}${whereSql}`;
+        const whereObj = args.where;
+        const whereFp = this.fingerprintWhere(whereObj);
+        const ck = `dm:${whereFp}`;
+        const params = [];
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const clause = this.buildWhereClause(whereObj, freshParams);
+            const whereSql = clause ? ` WHERE ${clause}` : '';
+            this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
+            return `DELETE FROM ${quoteIdent(this.table)}${whereSql}`;
+        });
+        if (whereFp === '') {
+            this.assertMutationHasPredicate('deleteMany', '', args.allowFullTableScan);
+        }
+        this.collectWhereParams(whereObj, params);
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => ({ count: result.rowCount ?? 0 }),
             tag: `${this.table}.deleteMany`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -764,18 +1079,30 @@ export class QueryInterface {
     async count(args) {
         return this.executeWithMiddleware('count', (args ?? {}), async () => {
             const deferred = this.buildCount(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
     buildCount(args) {
-        const { sql: whereSql, params } = args?.where ? this.buildWhere(args.where) : { sql: '', params: [] };
-        const sql = `SELECT COUNT(*)::int AS count FROM ${quoteIdent(this.table)}${whereSql}`;
+        const whereObj = (args?.where ?? {});
+        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
+        const ck = `cnt:${whereFp}`;
+        const params = [];
+        const entry = this.acquireSql(ck, () => {
+            const freshParams = [];
+            const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
+            const whereSql = clause ? ` WHERE ${clause}` : '';
+            return `SELECT COUNT(*)::int AS count FROM ${quoteIdent(this.table)}${whereSql}`;
+        });
+        if (args?.where) {
+            this.collectWhereParams(whereObj, params);
+        }
         return {
-            sql,
+            sql: entry.sql,
             params,
             transform: (result) => result.rows[0].count,
             tag: `${this.table}.count`,
+            preparedName: entry.name,
         };
     }
     // -------------------------------------------------------------------------
@@ -784,7 +1111,7 @@ export class QueryInterface {
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -917,7 +1244,7 @@ export class QueryInterface {
     async aggregate(args) {
         return this.executeWithMiddleware('aggregate', args, async () => {
             const deferred = this.buildAggregate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
         });
     }
@@ -1160,6 +1487,440 @@ export class QueryInterface {
         params.push(value);
         return `${col} = $${params.length}`;
     }
+    // =========================================================================
+    // Fingerprinting — value-invariant shape keys for SQL cache lookup
+    // =========================================================================
+    /**
+     * Produce a value-invariant fingerprint of a where clause.
+     * Same keys + same operator shapes + same combinator structure => same string.
+     * Different values (e.g. id=1 vs id=999) => identical fingerprint.
+     *
+     * @internal Exposed as package-private for testing via class access.
+     */
+    fingerprintWhere(where) {
+        const keys = Object.keys(where)
+            .filter((k) => where[k] !== undefined)
+            .sort();
+        if (keys.length === 0)
+            return '';
+        const parts = [];
+        for (const key of keys) {
+            const value = where[key];
+            if (value === undefined)
+                continue;
+            if (key === 'OR') {
+                const orArr = value;
+                if (!Array.isArray(orArr) || orArr.length === 0)
+                    continue;
+                const orParts = orArr.map((cond) => this.fingerprintWhere(cond));
+                parts.push(`OR[${orParts.join(',')}]`);
+                continue;
+            }
+            if (key === 'AND') {
+                const andArr = value;
+                if (!Array.isArray(andArr) || andArr.length === 0)
+                    continue;
+                const andParts = andArr.map((cond) => this.fingerprintWhere(cond));
+                parts.push(`AND[${andParts.join(',')}]`);
+                continue;
+            }
+            if (key === 'NOT') {
+                const notCond = value;
+                parts.push(`NOT(${this.fingerprintWhere(notCond)})`);
+                continue;
+            }
+            // Relation filters: { posts: { some: { published: true } } }
+            const relDef = this.tableMeta.relations[key];
+            if (relDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                const filterObj = value;
+                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                    const relParts = [];
+                    if (filterObj.some !== undefined)
+                        relParts.push(`some(${this.fingerprintRelFilter(relDef.to, filterObj.some)})`);
+                    if (filterObj.every !== undefined)
+                        relParts.push(`every(${this.fingerprintRelFilter(relDef.to, filterObj.every)})`);
+                    if (filterObj.none !== undefined)
+                        relParts.push(`none(${this.fingerprintRelFilter(relDef.to, filterObj.none)})`);
+                    parts.push(`${key}:{${relParts.join(',')}}`);
+                    continue;
+                }
+            }
+            // null → distinct from value
+            if (value === null) {
+                parts.push(`${key}:null`);
+                continue;
+            }
+            // Operator objects
+            if (isWhereOperator(value)) {
+                const opKeys = Object.keys(value)
+                    .filter((k) => k !== 'mode')
+                    .sort();
+                const mode = value.mode;
+                const modeStr = mode === 'insensitive' ? ':i' : '';
+                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                continue;
+            }
+            // JSON filter
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const jKeys = Object.keys(value).sort();
+                parts.push(`${key}:json(${jKeys.join(',')})`);
+                continue;
+            }
+            // Array filter
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const aKeys = Object.keys(value).sort();
+                parts.push(`${key}:arr(${aKeys.join(',')})`);
+                continue;
+            }
+            // Plain equality
+            parts.push(`${key}:eq`);
+        }
+        return parts.join('&');
+    }
+    /**
+     * Fingerprint a relation filter sub-where for some/every/none.
+     */
+    fingerprintRelFilter(targetTable, subWhere) {
+        const keys = Object.keys(subWhere)
+            .filter((k) => subWhere[k] !== undefined)
+            .sort();
+        if (keys.length === 0)
+            return '';
+        const parts = [];
+        for (const key of keys) {
+            const value = subWhere[key];
+            if (value === undefined)
+                continue;
+            if (value === null) {
+                parts.push(`${key}:null`);
+            }
+            else if (isWhereOperator(value)) {
+                const opKeys = Object.keys(value)
+                    .filter((k) => k !== 'mode')
+                    .sort();
+                const mode = value.mode;
+                const modeStr = mode === 'insensitive' ? ':i' : '';
+                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+            }
+            else {
+                parts.push(`${key}:eq`);
+            }
+        }
+        return parts.join('&');
+    }
+    /**
+     * Walk a where clause and push ONLY values into `params`, in the EXACT same
+     * order that `buildWhereClause` pushes them. Used on cache hit to fill params
+     * without rebuilding SQL.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    collectWhereParams(where, params) {
+        const keys = Object.keys(where);
+        for (const key of keys) {
+            const value = where[key];
+            if (value === undefined)
+                continue;
+            if (key === 'OR') {
+                const orConditions = value;
+                if (!Array.isArray(orConditions) || orConditions.length === 0)
+                    continue;
+                for (const orCond of orConditions) {
+                    this.collectWhereParams(orCond, params);
+                }
+                continue;
+            }
+            if (key === 'AND') {
+                const andConditions = value;
+                if (!Array.isArray(andConditions) || andConditions.length === 0)
+                    continue;
+                for (const andCond of andConditions) {
+                    this.collectWhereParams(andCond, params);
+                }
+                continue;
+            }
+            if (key === 'NOT') {
+                const notCond = value;
+                this.collectWhereParams(notCond, params);
+                continue;
+            }
+            // Relation filters
+            const relationDef = this.tableMeta.relations[key];
+            if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                const filterObj = value;
+                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                    if (filterObj.some !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.some, params);
+                    if (filterObj.none !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.none, params);
+                    if (filterObj.every !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.every, params);
+                    continue;
+                }
+            }
+            // null → no param pushed (IS NULL is parameterless)
+            if (value === null)
+                continue;
+            const rawColumn = this.toColumn(key);
+            // JSONB filter
+            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
+                const colType = this.getColumnPgType(rawColumn);
+                if (colType === 'json' || colType === 'jsonb') {
+                    this.collectJsonFilterParams(value, params);
+                    continue;
+                }
+            }
+            // Array filter
+            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
+                const colType = this.getColumnPgType(rawColumn);
+                if (colType.startsWith('_')) {
+                    this.collectArrayFilterParams(value, params);
+                    continue;
+                }
+            }
+            // Operator objects
+            if (isWhereOperator(value)) {
+                this.collectOperatorParams(value, params);
+                continue;
+            }
+            // Plain equality
+            params.push(value);
+        }
+    }
+    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
+    collectRelFilterParams(targetTable, subWhere, params) {
+        const meta = this.schema.tables[targetTable];
+        if (!meta)
+            return;
+        for (const [field, value] of Object.entries(subWhere)) {
+            if (value === undefined)
+                continue;
+            if (value === null)
+                continue;
+            if (isWhereOperator(value)) {
+                this.collectOperatorParams(value, params);
+                continue;
+            }
+            params.push(value);
+        }
+    }
+    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
+    collectOperatorParams(op, params) {
+        if (op.gt !== undefined)
+            params.push(op.gt);
+        if (op.gte !== undefined)
+            params.push(op.gte);
+        if (op.lt !== undefined)
+            params.push(op.lt);
+        if (op.lte !== undefined)
+            params.push(op.lte);
+        if (op.not !== undefined && op.not !== null)
+            params.push(op.not);
+        if (op.in !== undefined)
+            params.push(op.in);
+        if (op.notIn !== undefined)
+            params.push(op.notIn);
+        if (op.contains !== undefined)
+            params.push(`%${escapeLike(op.contains)}%`);
+        if (op.startsWith !== undefined)
+            params.push(`${escapeLike(op.startsWith)}%`);
+        if (op.endsWith !== undefined)
+            params.push(`%${escapeLike(op.endsWith)}`);
+    }
+    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
+    collectJsonFilterParams(filter, params) {
+        if (filter.path !== undefined && filter.equals !== undefined) {
+            params.push(filter.path);
+            params.push(String(filter.equals));
+        }
+        else if (filter.equals !== undefined) {
+            params.push(JSON.stringify(filter.equals));
+        }
+        if (filter.contains !== undefined) {
+            params.push(JSON.stringify(filter.contains));
+        }
+        if (filter.hasKey !== undefined) {
+            params.push(filter.hasKey);
+        }
+    }
+    /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
+    collectArrayFilterParams(filter, params) {
+        if (filter.has !== undefined)
+            params.push(filter.has);
+        if (filter.hasEvery !== undefined)
+            params.push(filter.hasEvery);
+        if (filter.hasSome !== undefined)
+            params.push(filter.hasSome);
+        // isEmpty has no params (IS NULL / IS NOT NULL)
+    }
+    /**
+     * Produce a fingerprint for a `with` clause tree. Recursion mirrors
+     * buildSelectWithRelations / buildRelationSubquery.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    withFingerprint(withClause, table, depth = 0) {
+        if (!withClause)
+            return '';
+        const meta = this.schema.tables[table ?? this.table];
+        if (!meta)
+            return '';
+        const relNames = Object.keys(withClause).sort();
+        const parts = [];
+        for (const relName of relNames) {
+            const spec = withClause[relName];
+            if (!spec)
+                continue;
+            const relDef = meta.relations[relName];
+            if (!relDef)
+                continue;
+            if (spec === true) {
+                parts.push(relName);
+                continue;
+            }
+            const opts = spec;
+            const subParts = [];
+            // select/omit shape
+            if (opts.select) {
+                const selKeys = Object.entries(opts.select)
+                    .filter(([, v]) => v)
+                    .map(([k]) => k)
+                    .sort();
+                subParts.push(`sl=${selKeys.join(',')}`);
+            }
+            if (opts.omit) {
+                const omKeys = Object.entries(opts.omit)
+                    .filter(([, v]) => v)
+                    .map(([k]) => k)
+                    .sort();
+                subParts.push(`om=${omKeys.join(',')}`);
+            }
+            // where shape (value-invariant)
+            if (opts.where) {
+                // Use a target-table QI if possible, or a simplified fingerprint
+                const wKeys = Object.keys(opts.where)
+                    .filter((k) => opts.where[k] !== undefined)
+                    .sort();
+                subParts.push(`w=${wKeys.join(',')}`);
+            }
+            // orderBy shape
+            if (opts.orderBy) {
+                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${d}`);
+                subParts.push(`o=${oEntries.join(',')}`);
+            }
+            // limit presence
+            if (opts.limit !== undefined) {
+                subParts.push('l=1');
+            }
+            // nested with (recurse)
+            if (opts.with) {
+                const nested = this.withFingerprint(opts.with, relDef.to, depth + 1);
+                if (nested)
+                    subParts.push(`W=(${nested})`);
+            }
+            parts.push(subParts.length > 0 ? `${relName}/{${subParts.join('/')}}` : relName);
+        }
+        return parts.join('|');
+    }
+    /**
+     * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
+     * buildRelationSubquery param-push order.
+     */
+    collectWithParams(withClause, params, table) {
+        const meta = this.schema.tables[table ?? this.table];
+        if (!meta)
+            return;
+        for (const [relName, relSpec] of Object.entries(withClause)) {
+            const relDef = meta.relations[relName];
+            if (!relDef)
+                continue;
+            this.collectRelationSubqueryParams(relDef, relSpec, params, table ?? this.table);
+        }
+    }
+    /**
+     * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
+     */
+    collectRelationSubqueryParams(relDef, spec, params, _parentRef, depth = 0) {
+        if (spec === true)
+            return; // No params for default include
+        const targetTable = relDef.to;
+        const targetMeta = this.schema.tables[targetTable];
+        if (!targetMeta)
+            return;
+        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || spec.orderBy !== undefined);
+        // Non-wrapped path: nested relations BEFORE where/limit
+        if (!willWrap && spec.with) {
+            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                const nestedRelDef = targetMeta.relations[nestedRelName];
+                if (!nestedRelDef)
+                    continue;
+                this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
+            }
+        }
+        // where params
+        if (spec.where) {
+            for (const [, v] of Object.entries(spec.where)) {
+                params.push(v);
+            }
+        }
+        // limit param
+        if (spec.limit) {
+            params.push(Number(spec.limit));
+        }
+        // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
+        if (willWrap && spec.with) {
+            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                const nestedRelDef = targetMeta.relations[nestedRelName];
+                if (!nestedRelDef)
+                    continue;
+                this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'innerAlias', depth + 1);
+            }
+        }
+    }
+    /**
+     * Fingerprint SET clauses for update/updateMany.
+     * Captures key names + operator types (set/increment/etc) but not values.
+     */
+    fingerprintSet(data) {
+        const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+        const parts = [];
+        for (const [k, v] of entries) {
+            if (v !== null &&
+                typeof v === 'object' &&
+                !Array.isArray(v) &&
+                !(v instanceof Date) &&
+                !(typeof Buffer !== 'undefined' && Buffer.isBuffer(v))) {
+                const keys = Object.keys(v);
+                if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
+                    parts.push(`${k}:${keys[0]}`);
+                    continue;
+                }
+            }
+            parts.push(`${k}:eq`);
+        }
+        return parts.join(',');
+    }
+    /**
+     * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
+     */
+    collectSetParams(data, params) {
+        const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+        for (const [, v] of entries) {
+            if (v !== null &&
+                typeof v === 'object' &&
+                !Array.isArray(v) &&
+                !(v instanceof Date) &&
+                !(typeof Buffer !== 'undefined' && Buffer.isBuffer(v))) {
+                const obj = v;
+                const keys = Object.keys(obj);
+                if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
+                    params.push(obj[keys[0]]);
+                    continue;
+                }
+            }
+            params.push(v);
+        }
+    }
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     buildWhere(where) {
         const params = [];
@@ -1261,6 +2022,16 @@ export class QueryInterface {
                     andClauses.push(...jsonClauses);
                     continue;
                 }
+                // Strict validation: a JSON-only operator on a non-JSON column was almost
+                // certainly a typo or schema mismatch. Silently falling through to plain
+                // equality (the previous behaviour) wasted hours of debugging time. Only
+                // throw when the operator is unambiguously JSON-specific — `contains` is
+                // shared with WhereOperator's LIKE so it must continue to fall through.
+                const jsonKey = findJsonUniqueKey(value);
+                if (jsonKey) {
+                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
             }
             // Handle Array filter operators (for array columns)
             if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
@@ -1270,6 +2041,14 @@ export class QueryInterface {
                     andClauses.push(...arrayClauses);
                     continue;
                 }
+                // Strict validation: array operators (`has`, `hasEvery`, ...) on a
+                // non-array column always indicate a mistake. None of these keys
+                // overlap with other filter shapes so we can throw unconditionally.
+                const arrayKey = findArrayUniqueKey(value);
+                if (arrayKey) {
+                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
             }
             // Handle operator objects
             if (isWhereOperator(value)) {
@@ -1468,28 +2247,53 @@ export class QueryInterface {
             return parsed;
         for (const [relName, relDef] of Object.entries(meta.relations)) {
             const rawValue = row[relName];
-            if (rawValue !== undefined) {
-                if (typeof rawValue === 'string') {
-                    try {
-                        parsed[relName] = JSON.parse(rawValue);
+            if (rawValue === undefined)
+                continue;
+            // --- Short-circuit: skip JSON.parse for common empty/null cases ---
+            // hasMany returns '[]' (from COALESCE(..., '[]'::json)); belongsTo/hasOne returns null
+            if (rawValue === null || rawValue === 'null') {
+                parsed[relName] = null;
+                continue;
+            }
+            if (rawValue === '[]') {
+                parsed[relName] = [];
+                continue;
+            }
+            if (Array.isArray(rawValue) && rawValue.length === 0) {
+                parsed[relName] = [];
+                continue;
+            }
+            // --- Non-empty values: full parse path ---
+            if (typeof rawValue === 'string') {
+                try {
+                    const jsonVal = JSON.parse(rawValue);
+                    // After parsing, apply parseRow to each item for snake→camel + date coercion
+                    if (Array.isArray(jsonVal)) {
+                        parsed[relName] = jsonVal.map((item) => typeof item === 'object' && item !== null
+                            ? this.parseRow(item, relDef.to)
+                            : item);
                     }
-                    catch {
-                        console.warn(`[turbine] Warning: Failed to parse JSON for relation "${relName}" on table "${this.table}". Using raw value.`);
-                        parsed[relName] = rawValue;
+                    else if (typeof jsonVal === 'object' && jsonVal !== null) {
+                        parsed[relName] = this.parseRow(jsonVal, relDef.to);
+                    }
+                    else {
+                        parsed[relName] = jsonVal;
                     }
                 }
-                else if (Array.isArray(rawValue)) {
-                    parsed[relName] = rawValue.map((item) => typeof item === 'object' && item !== null
-                        ? this.parseRow(item, relDef.to)
-                        : item);
-                }
-                else if (typeof rawValue === 'object' && rawValue !== null) {
-                    parsed[relName] = this.parseRow(rawValue, relDef.to);
-                }
-                else {
+                catch {
+                    console.warn(`[turbine] Warning: Failed to parse JSON for relation "${relName}" on table "${this.table}". Using raw value.`);
                     parsed[relName] = rawValue;
                 }
             }
+            else if (Array.isArray(rawValue)) {
+                parsed[relName] = rawValue.map((item) => typeof item === 'object' && item !== null ? this.parseRow(item, relDef.to) : item);
+            }
+            else if (typeof rawValue === 'object' && rawValue !== null) {
+                parsed[relName] = this.parseRow(rawValue, relDef.to);
+            }
+            else {
+                parsed[relName] = rawValue;
+            }
         }
         return parsed;
     }