turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/builder.d.ts

@@ -12,16 +12,7 @@
  */
 import type { PgCompatPool } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
-/**
- * Discard the memoized cross-check environment so the next cache hit re-reads
- * `process.env`.
- *
- * @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.
- */
-export declare function resetCacheCrossCheckEnv(): void;
+import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, DefaultInputTypes, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TableInputTypes, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 /**
  * Marginal cost of keeping a to-one relation on the JOIN plan, per parent row.
  *
@@ -188,7 +179,7 @@ export declare function unlockNestedWriteTx<X extends {
 }>(tx: X): X;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
-export declare class QueryInterface<T extends object, R extends object = {}> {
+export declare class QueryInterface<T extends object, R extends object = {}, M extends TableInputTypes = DefaultInputTypes<T, R>> {
     private readonly pool;
     private readonly table;
     private readonly schema;
@@ -208,6 +199,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * inline, not through the top-level cache).
      */
     private lastCacheHit;
+    /**
+     * 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}.
+     */
+    private 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
@@ -219,6 +217,21 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private variableArityShape;
     private readonly middlewares;
+    /** The client's resolved `diagnostics` (see diagnostics.ts), fixed for this instance's life. */
+    private readonly diagnostics;
+    /** `streamIdleTimeoutMs`: how long a cursor stream may wait for its consumer. `0` disables. */
+    private readonly streamIdleTimeoutMs;
+    /** `sqlComment`, resolved; `undefined` when statements carry no comment (one falsy check per send). */
+    private readonly sqlCommenter;
+    /** Where this instance's log lines go: the client's `logger`, else the console logger. */
+    private readonly 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.
+     */
+    private readonly advice;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
     private readonly scopedConnect;
@@ -320,7 +333,6 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * the audit's "Set<string>" guidance and leaves room for future
      * cross-table sharing.
      */
-    private readonly warnedTables;
     /** Cache hit/miss counters for diagnostics */
     private cacheHits;
     private cacheMisses;
@@ -341,6 +353,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * to Date as well (otherwise nested dates leak through as strings).
      */
     private readonly camelDateFieldCache;
+    /** Per-table memo of {@link cellKindOf}, keyed by column name and field name. */
+    private readonly cellKindCache;
+    /** The dialect decode of each {@link CELL_DIALECT} column, by table, then by column and field name. */
+    private readonly dialectDecodeCache;
     /**
      * Per-table memo of `Object.entries(meta.relations)`, consumed by the nested
      * row parser (see `getRelationEntries` in relations.ts). Same rationale and
@@ -406,7 +422,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly ctx;
     constructor(pool: PgCompatPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /**
-     * 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.
      *
@@ -431,17 +447,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *     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.
      */
     private warnUntypedColumns;
@@ -552,23 +568,52 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private withDeclaredRelationNames;
     /**
-     * Caller args in canonical form: declared relation spellings, and the Prisma
-     * pagination aliases folded into `limit` / `offset`.
+     * `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.
+     */
+    private withRelationPagination;
+    /**
+     * 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.
+     *
+     * 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.
      *
-     * 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.
+     * `refuseEmptiedWhere` names the single-row read (`findFirst`,
+     * `findFirstOrThrow`) that refuses a `where` whose every key was `undefined`.
      */
     private normalizeArgs;
+    /**
+     * 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`.
+     */
+    private assertQueryOptions;
     /**
      * Refuse a `findUnique` whose `where` names no unique key. The rule and the
      * message live in query/compound-unique.ts, beside the definition of what
      * counts as unique and shared with the PowDB engine.
      */
     private assertFindUniqueKey;
+    /**
+     * 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.
+     */
+    private assertLockInTransaction;
+    /** Refuse `lock` on a streaming read (a cursor is not a locking read). */
+    private assertNoStreamLock;
     /**
      * 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
@@ -587,94 +632,88 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * through the normal column mapping.
      */
     private pkOrderBy;
-    /**
-     * 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).
-     */
-    private cursorFields;
-    /**
-     * 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.
-     *
-     * 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.
-     */
-    private cursorOrderBy;
-    /**
-     * 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`.
-     *
-     * 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.
-     *
-     * 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.
-     *
-     * An unknown cursor field throws the same E003 here that the build path
-     * threw before this helper existed; the fingerprint simply meets it first.
-     */
-    private cursorSeekEntries;
-    /**
-     * 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.
-     *
-     * 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.
-     */
-    private keysetPredicate;
-    /**
-     * 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.
-     *
-     * `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.
+    /** Memo for {@link totalOrderKeys}; table metadata is immutable. */
+    private totalOrderKeysMemo;
+    /**
+     * 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).
+     */
+    private totalOrderKeys;
+    /**
+     * 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.
+     */
+    private tiebreakColumns;
+    /**
+     * 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.
+     *
+     * 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}).
+     */
+    private completePageOrder;
+    /**
+     * 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.
+     *
+     * 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).
+     *
+     * 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.
+     *
+     * 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.
+     */
+    private planCursor;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    private renderCursorPredicate;
+    /**
+     * 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.
+     *
+     * 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
@@ -687,36 +726,32 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * 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.
      */
     private implicitPkOrderBy;
     /**
-     * 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.
      */
     private maybeWarnUnorderedPage;
     /**
@@ -807,7 +842,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private planAuto;
     /**
-     * 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),
@@ -885,15 +920,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * 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.
      */
     private acquireSql;
     /**
@@ -918,36 +952,54 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private buildCacheEntry;
     /**
-     * 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.
      */
     private crossCheckCache;
     /**
-     * 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.
+     * 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.
+     */
+    private lockstepError;
+    /**
+     * 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(): void;
     private emitQueryEvent;
+    /**
+     * 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.
+     */
+    private outgoing;
     /**
      * Resolve the prepared-statement name a read should execute under, honouring
      * the per-query {@link FindManyArgs.forceCustomPlan} opt-in.
@@ -1018,11 +1070,61 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readWithTimeout;
     /**
      * 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.
      */
     private queryWithTimeout;
+    /**
+     * 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).
+     */
+    private cancelsOnTimeout;
+    /**
+     * {@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.
+     */
+    private queryCancellable;
+    /**
+     * 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.
+     */
+    private queryCancellableInTransaction;
+    /** Cancel a timed-out statement in a transaction and end the transaction. See {@link queryCancellableInTransaction}. */
+    private cancelInTransaction;
+    /**
+     * Cancel a statement that outlived its timeout, wait for it to answer, and
+     * release its connection accordingly. See {@link queryCancellable}.
+     */
+    private cancelTimedOut;
     /**
      * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
      * the active dialect's {@link Dialect.resultStrategy}, then apply its
@@ -1037,7 +1139,23 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *     write and a follow-up SELECT; the SELECT's rows feed the transform.
      */
     private executeMutation;
-    buildCreate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
+    /**
+     * 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.
+     */
+    private deadlineExec;
+    /**
+     * 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}).
+     */
+    private inOneTransaction;
+    buildCreate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O, M['create']>): DeferredQuery<FieldResult<T, S, O>>;
     /**
      * A single-row write's `select` / `omit`, resolved through the SAME
      * `resolveProjection` reads use (see WriteProjection in writes.ts), or
@@ -1045,14 +1163,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * writes.ts because relations.ts imports writes.ts.
      */
     private resolveWriteProjection;
-    buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
-    buildUpdate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
+    buildCreateMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O>): DeferredQuery<FieldResult<T, S, O>[]>;
+    buildUpdate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O, M['update']>): DeferredQuery<FieldResult<T, S, O>>;
     buildDelete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
-    buildUpsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
-    buildUpdateMany(args: UpdateManyArgs<T>): DeferredQuery<{
+    buildUpsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O, M['whereUnique'], M['createMany'], M['updateMany']>): DeferredQuery<FieldResult<T, S, O>>;
+    buildUpdateMany(args: UpdateManyArgs<T, R, M['updateMany']>): DeferredQuery<{
         count: number;
     }>;
-    buildDeleteMany(args: DeleteManyArgs<T>): DeferredQuery<{
+    buildDeleteMany(args: DeleteManyArgs<T, R>): DeferredQuery<{
         count: number;
     }>;
     /**
@@ -1066,14 +1184,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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`.
      */
     private executeWithMiddleware;
-    findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): Promise<QueryResult<T, R, W, S, O> | null>;
     /**
      * Batched-strategy findUnique: fetch the single base row without relation
      * subqueries (adding any parent stitch keys the projection excluded), then load
@@ -1081,7 +1198,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * strategy's shape for the one row.
      */
     private runFindUniqueBatched;
-    buildFindUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O> | null>;
+    buildFindUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): DeferredQuery<QueryResult<T, R, W, S, O> | null>;
     findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
     /**
      * Return the engine's query plan for a {@link findMany}-shaped query as plain
@@ -1114,11 +1231,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private withSqlCacheDisabled;
     /**
-     * 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
@@ -1146,7 +1265,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private whereMatchesAtMostOneRow;
     /**
      * 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.
      */
     private measureWithDepth;
     buildFindMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>[]>;
@@ -1189,6 +1308,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * non-empty.
      */
     private streamRaw;
+    /**
+     * 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.
+     */
+    private expireIdleStream;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors, one BATCH of
      * rows at a time.
@@ -1262,13 +1389,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     findManyStream<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>, void, undefined>;
     findFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
     buildFindFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O> | null>;
+    /**
+     * findFirst / findFirstOrThrow over findMany's builder with `LIMIT 1`.
+     * `operation` names the method in the refusal of an all-undefined `where`.
+     */
+    private buildFindFirstAs;
     findFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
     buildFindFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
-    findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
-    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
-    create<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
-    createMany(args: CreateManyArgs<T>): Promise<T[]>;
-    update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): DeferredQuery<QueryResult<T, R, W, S, O>>;
+    create<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O, M['create']>): Promise<FieldResult<T, S, O>>;
+    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O>): Promise<FieldResult<T, S, O>[]>;
+    update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O, M['update']>): Promise<FieldResult<T, S, O>>;
     private nestedCreate;
     private nestedUpdate;
     /**
@@ -1282,7 +1414,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private buildNestedCtx;
     private makeTxProxy;
     delete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
-    upsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
+    upsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O, M['whereUnique'], M['createMany'], M['updateMany']>): Promise<FieldResult<T, S, O>>;
     /**
      * @internal Whether `upsert()` looks the row up rather than running one
      * statement, which is also exactly when `buildUpsert` refuses these args.
@@ -1312,14 +1444,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * never writes two rows over one key the database enforces.
      */
     private upsertLookupFirst;
-    updateMany(args: UpdateManyArgs<T, R>): Promise<{
+    updateMany(args: UpdateManyArgs<T, R, M['updateMany']>): Promise<{
         count: number;
     }>;
     deleteMany(args: DeleteManyArgs<T, R>): Promise<{
         count: number;
     }>;
     count(args?: CountArgs<T, R>): Promise<number>;
-    buildCount(args?: CountArgs<T>): DeferredQuery<number>;
+    buildCount(args?: CountArgs<T, R>): DeferredQuery<number>;
     /**
      * Group rows and compute per-group aggregates (Prisma-style). The result row
      * type is INFERRED from the args: each `by` field carries its entity field
@@ -1329,9 +1461,9 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * that cannot be typed, so those columns are not projected onto the row type.
      */
     groupBy<A extends GroupByArgs<T, R>>(args: A): Promise<GroupByResult<T, A>[]>;
-    buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
-    buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
-    aggregate(args: AggregateArgs<T, R>): Promise<AggregateResult<T>>;
+    buildGroupBy<A extends GroupByArgs<T, R>>(args: A): DeferredQuery<GroupByResult<T, A>[]>;
+    buildAggregate<A extends AggregateArgs<T, R>>(args: A): DeferredQuery<AggregateResultOf<T, A>>;
+    aggregate<A extends AggregateArgs<T, R>>(args: A): Promise<AggregateResultOf<T, A>>;
     private resolveColumns;
     withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
     private collectWithParams;
@@ -1385,7 +1517,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * the default path.
      */
     private planFlatten;
-    /** Dev-only once-only note that `'flatten'` was refused for the whole query. */
+    /** Advice, once per reason: `'flatten'` was refused for the whole query. */
     private warnFlattenBlocked;
     /**
      * Convert a field name to its snake_case column name (unquoted, for non-SQL
@@ -1482,10 +1614,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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.
      *
@@ -1516,6 +1648,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * pre-plan code spelled inline.
      */
     private decodeTemporalCell;
+    /** The non-temporal decode kinds of `table`'s columns, by column and by field name. */
+    private getCellKinds;
+    /** One cell's decode, for every kind but {@link CELL_PLAIN}. */
+    private decodeCell;
+    /**
+     * A {@link CELL_DIALECT} cell: the dialect's decode for the column's declared
+     * type, recorded by {@link getCellKinds} when it classified the column.
+     */
+    private decodeDialectCell;
     /**
      * 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