turbine-orm 0.77.1 → 0.78.0

package/dist/powql.d.ts

@@ -218,6 +218,20 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private assertNoForceCustomPlan;
     /** See query/compound-unique.ts: one rule and one message across engines. */
     private assertIdentifiesOneRow;
+    /**
+     * The single-row WRITE rule (`update` / `delete` return one row, so their
+     * `where` must identify one; `upsert`'s `where` names the row it conflicts
+     * on), shared with the SQL engines through query/compound-unique.ts so the
+     * two cannot disagree about which writes are valid. Skipped under the
+     * explicit full-table opt-in, which already means "every row". For `update` /
+     * `delete` it runs AFTER `assertCompiledWhere`, so an empty selector keeps
+     * the empty-where message and this only refuses a non-empty one that names no
+     * key; `upsert` takes no `allowFullTableScan` and has no empty-where guard to
+     * run first, so this is its only where check and it covers `{}` as well.
+     */
+    private assertMutationIdentifiesOneRow;
+    /** A caller `where` with a Prisma compound-unique selector expanded to its member columns. */
+    private expandedWhere;
     private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;

package/dist/powql.js

@@ -39,7 +39,7 @@ import { NotFoundError, OptimisticLockError, ReadOnlyError, TimeoutError, Unsupp
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, baseTsType, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb-shared.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
-import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './query/compound-unique.js';
+import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, } from './query/compound-unique.js';
 import { ARRAY_OPERATOR_KEYS, isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { warnUnknownQueryOptions } from './query/option-surface.js';
 import { applyStableRelationOrderTo, normalizeWithClause } from './query/relation-names.js';
@@ -446,6 +446,28 @@ export class PowqlInterface {
     assertIdentifiesOneRow(where) {
         assertWhereIdentifiesOneRow(this.meta, this.table, where);
     }
+    /**
+     * The single-row WRITE rule (`update` / `delete` return one row, so their
+     * `where` must identify one; `upsert`'s `where` names the row it conflicts
+     * on), shared with the SQL engines through query/compound-unique.ts so the
+     * two cannot disagree about which writes are valid. Skipped under the
+     * explicit full-table opt-in, which already means "every row". For `update` /
+     * `delete` it runs AFTER `assertCompiledWhere`, so an empty selector keeps
+     * the empty-where message and this only refuses a non-empty one that names no
+     * key; `upsert` takes no `allowFullTableScan` and has no empty-where guard to
+     * run first, so this is its only where check and it covers `{}` as well.
+     */
+    assertMutationIdentifiesOneRow(where, allowFullTableScan, operation) {
+        if (allowFullTableScan)
+            return;
+        assertMutationWhereIdentifiesOneRow(this.meta, this.table, where, operation);
+    }
+    /** A caller `where` with a Prisma compound-unique selector expanded to its member columns. */
+    expandedWhere(where) {
+        if (!where)
+            return where;
+        return expandCompoundUniqueWhere(this.meta, where);
+    }
     assertPagination(limit, offset, context) {
         for (const [name, value] of [
             ['limit', limit],
@@ -2665,14 +2687,22 @@ export class PowqlInterface {
     async update(args) {
         return this.withMiddleware('update', args, async () => {
             if (hasRelationFields(args.data, this.meta)) {
+                // The nested engine re-enters `update` / `findUnique` for the parent
+                // row before it writes anything, so the identity rule below still runs
+                // first on this path.
                 return this.nestedUpdate(args);
             }
+            const allowFullTableScan = resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan');
+            // Prisma compound-unique selector → column conjunction, so the selector
+            // counts as the key it is (engine parity with the SQL buildUpdate).
+            const userWhere = this.expandedWhere(args.where);
             const params = [];
-            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const resolvedWhere = await this.resolveRelationFilters(userWhere, args.timeout);
             let where = this.buildWhere(resolvedWhere, params);
             // `false` here refused an empty where even WITH the opt-in, while every
             // SQL engine accepted it: verified by probe on buildUpdate/buildDelete.
-            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'update');
+            this.assertCompiledWhere(where, allowFullTableScan, 'update');
+            this.assertMutationIdentifiesOneRow(userWhere, allowFullTableScan, 'update');
             where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             let setClause = this.buildUpdateAssignments(args.data, params);
             // Optimistic locking, matching the SQL engines exactly: bump the version
@@ -2846,10 +2876,13 @@ export class PowqlInterface {
     }
     async delete(args) {
         return this.withMiddleware('delete', args, async () => {
+            const allowFullTableScan = resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan');
+            const userWhere = this.expandedWhere(args.where);
             const params = [];
-            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const resolvedWhere = await this.resolveRelationFilters(userWhere, args.timeout);
             let where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'delete');
+            this.assertCompiledWhere(where, allowFullTableScan, 'delete');
+            this.assertMutationIdentifiesOneRow(userWhere, allowFullTableScan, 'delete');
             where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             // `returning` hands back the deleted row(s), no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
@@ -2873,6 +2906,13 @@ export class PowqlInterface {
     }
     async upsert(args) {
         return this.withMiddleware('upsert', args, async () => {
+            // The single-row rule for `upsert`, shared with the SQL engines through
+            // query/compound-unique.ts. PowqlInterface is a PARALLEL implementation,
+            // not a subclass, so a rule adopted only on the SQL side is two engines
+            // disagreeing about whether a query is VALID, which is the failure class
+            // 0.64.0 and 0.72.0 were both spent on. Before `applyPkDefault`, so a
+            // refused upsert mints no client-side UUID and sends nothing.
+            this.assertMutationIdentifiesOneRow(this.expandedWhere(args.where), false, 'upsert');
             const createData = this.applyPkDefault(args.create);
             const pkCol = this.meta.primaryKey[0];
             if (this.meta.primaryKey.length !== 1 || !pkCol) {

package/dist/prisma-compat.js

@@ -123,7 +123,7 @@ import { TurbineError, TurbineErrorCode, UnsupportedFeatureError, ValidationErro
 import { createManyShapeRuns } from './nested-write.js';
 import { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
 import { AGGREGATE_OPTIONS, applyNativeOptions, COUNT_OPTIONS, CREATE_MANY_OPTIONS, CREATE_OPTIONS, DELETE_MANY_OPTIONS, DELETE_OPTIONS, FIND_MANY_OPTIONS, FIND_UNIQUE_OPTIONS, GROUP_BY_OPTIONS, optionKeysOfKind, UNSAFE, UPDATE_MANY_OPTIONS, UPDATE_OPTIONS, UPSERT_OPTIONS, } from './query/index.js';
-import { suggestKey } from './query/utils.js';
+import { markInternalCombinator, suggestKey } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { assertWhereDepth, MAX_WHERE_DEPTH } from './query/where-compile.js';
 // ---------------------------------------------------------------------------
@@ -260,6 +260,33 @@ function lookupsFor(ctx, mm) {
     return l;
 }
 /** Resolve a turbine relation's target Prisma model map (for nested translation). */
+/**
+ * A `where` fragment no row satisfies, for Prisma's empty `OR`.
+ *
+ * `{ <key>: { in: [] } }`, which core compiles to `= ANY($n)` with an empty
+ * array: false for every row, NULL-valued ones included, and one ordinary bound
+ * param rather than a literal spliced into the SQL. The column is the first
+ * primary-key column, else the table's first column, so it is always a real
+ * column of this table and the predicate stays a plain scalar comparison the
+ * cache fingerprints like any other.
+ *
+ * A table this layer cannot name a column of THROWS. The fallback used to be
+ * `{}`, an empty `where` fragment - which is not "no rows" but its exact
+ * opposite, EVERY row, and it would have been merged in silently beside the
+ * caller's other predicates. A sentinel builder that cannot build a sentinel
+ * has not succeeded, and the one shape it exists to compile is the one where
+ * answering "all of them" instead of "none of them" is worst.
+ */
+function matchNothing(ctx, mm) {
+    const meta = ctx.schema.tables[mm.table];
+    const column = meta?.primaryKey?.[0] ?? meta?.allColumns?.[0];
+    if (!meta || !column) {
+        throw new ValidationError(`An empty \`OR\` on model ${mm.table} means "no rows", and compiling that needs one real column ` +
+            `of the table, but the schema metadata for "${mm.table}" lists none. Regenerate the client ` +
+            '(`npx turbine generate`) so the table carries its columns, or drop the empty `OR`.');
+    }
+    return { [meta.reverseColumnMap?.[column] ?? column]: { in: [] } };
+}
 function relTargetModel(ctx, mm, turbineRel) {
     const rd = ctx.schema.tables[mm.table]?.relations?.[turbineRel];
     if (!rd)
@@ -600,8 +627,30 @@ function translateWhere(ctx, mm, where, depth = 0) {
     if (!isPlainObject(where))
         return where;
     const out = {};
+    // The empty-`OR` sentinel, held aside rather than merged into `out`. At most
+    // one per level, since `OR` is a single object key.
+    let matchNone;
     for (const [key, val] of Object.entries(where)) {
         if (COMBINATORS.has(key)) {
+            // An EMPTY `OR` is false in Prisma (no branch can match), while an empty
+            // `AND` / `NOT` is true. Core drops an empty combinator entirely, so the
+            // same call returned EVERY row here: the classic trigger is
+            // `OR: ids.map(...)` over a selection that turned out to be empty, i.e.
+            // "none of these" answered with "all of them". Compiled to a predicate
+            // that matches nothing so this layer keeps Prisma's meaning; core's own
+            // semantics are unchanged and documented separately.
+            //
+            // Held aside, NOT `Object.assign`ed onto `out`: the sentinel is keyed on
+            // a real column of the table, so merging it made two predicates on one
+            // key collide and JavaScript's key ORDER decided which survived.
+            // `{ OR: [], id: 5 }` kept the caller's `id = 5` and dropped the
+            // sentinel (returning the row Prisma excludes); `{ id: 5, OR: [] }` kept
+            // the sentinel and dropped the caller's `id = 5`. Same query, same
+            // meaning, opposite predicate.
+            if (key === 'OR' && Array.isArray(val) && val.length === 0) {
+                matchNone = matchNothing(ctx, mm);
+                continue;
+            }
             // An `AND` / `OR` array of N conditions is ONE level, not N: the elements
             // are siblings, so they all translate at the same incremented depth.
             out[key] = Array.isArray(val)
@@ -623,6 +672,17 @@ function translateWhere(ctx, mm, where, depth = 0) {
         // Relation filter.
         const rel = mm.relations[key];
         if (rel) {
+            // Prisma spells "this to-one relation has no related row" as a bare
+            // `null` on the relation key; core spells it `{ is: null }` and answers a
+            // bare null with E003. The generic message then degraded into naming the
+            // key that was just passed ("Did you mean "user" (a relation)?"), because
+            // the adapter had already renamed it. To-many keys are NOT mapped: Prisma
+            // has no bare-null shape there, so core still refuses them by name rather
+            // than this layer inventing a meaning.
+            if (val === null && rel.cardinality === 'one') {
+                out[rel.name] = { is: null };
+                continue;
+            }
             const target = relTargetModel(ctx, mm, rel.name);
             out[rel.name] = translateRelationFilter(ctx, target, val, depth + 1);
             continue;
@@ -631,7 +691,20 @@ function translateWhere(ctx, mm, where, depth = 0) {
         // through unchanged (Prisma operator names match Turbine's).
         out[renameField(mm, key)] = val;
     }
-    return out;
+    if (!matchNone)
+        return out;
+    // Nothing else at this level: the sentinel IS the where, no wrapper needed.
+    if (Object.keys(out).length === 0)
+        return matchNone;
+    // Otherwise conjoin, so neither half can overwrite the other whatever order
+    // the caller wrote the keys in. BRANDED, because an `AND` array is the shape
+    // that makes a statement unnamed (a caller-written combinator has a
+    // caller-sized arity); this one is Turbine's, with a fixed arity of two, and
+    // an unbranded wrapper here would quietly take every compat query carrying an
+    // empty `OR` off named prepared statements. The caller's own combinators sit
+    // INSIDE `out` and are walked at the next level with their own brand check,
+    // so they still count.
+    return markInternalCombinator({ AND: [out, matchNone] });
 }
 function translateRelationFilter(ctx, target, val, depth) {
     if (!isPlainObject(val))
@@ -1161,15 +1234,29 @@ function translateCursor(ctx, mm, prismaArgs, t) {
     const op = desc ? 'lte' : 'gte';
     t.where = mergeKeyset(t.where ?? {}, field, op, value);
 }
-/** Flatten a Turbine orderBy (object or single-object array) into [field, isDesc] pairs. */
+/**
+ * Flatten a Turbine orderBy (object, or an array of them) into [field, isDesc]
+ * pairs.
+ *
+ * EVERY array element is read. Reading only an array of length one returned
+ * `[]` for a two-element array, and `[]` is also what "no orderBy at all"
+ * returns, so {@link translateCursor} took its no-orderBy branch: it found a
+ * bare cursor on the primary key, wrote `orderBy = { id: 'asc' }` over the
+ * caller's array, and returned the rows following the anchor in PK order
+ * instead of in the caller's order. The single-sort-key check downstream is
+ * what refuses a shape a bare (inclusive) cursor cannot express, and it can
+ * only fire if the pairs it counts are all there.
+ */
 function orderByPairs(ob) {
-    const one = Array.isArray(ob) ? (ob.length === 1 ? ob[0] : undefined) : ob;
-    if (!isPlainObject(one))
-        return [];
+    const entries = Array.isArray(ob) ? ob : [ob];
     const out = [];
-    for (const [k, v] of Object.entries(one)) {
-        const dir = isPlainObject(v) ? v.sort : v;
-        out.push([k, dir === 'desc']);
+    for (const entry of entries) {
+        if (!isPlainObject(entry))
+            continue;
+        for (const [k, v] of Object.entries(entry)) {
+            const dir = isPlainObject(v) ? v.sort : v;
+            out.push([k, dir === 'desc']);
+        }
     }
     return out;
 }

package/dist/query/aggregates.js

@@ -211,7 +211,7 @@ export function buildGroupBy(qi, args) {
                 // would emit two "_sum_total_price" columns and silently drop one.
                 claimResultKey(`${aggKey}_${col}`, `${aggKey} of column "${col}"`);
                 const inner = `${sqlFn}(${qi.q(col)})`;
-                const expr = aggKey === '_avg' ? qi.castAgg(inner, 'float') : inner;
+                const expr = aggKey === '_avg' ? plainAvgExpr(qi, col) : inner;
                 selectExprs.push(`${expr} AS ${qi.q(`${aggKey}_${col}`)}`);
                 // Canonical field, matching the result bucket the transform fills;
                 // `orderBy` may spell it either way (see {@link lookupGroupKey}).
@@ -322,13 +322,17 @@ export function buildGroupBy(qi, args) {
             // aggregates keep the snake→camel field mapping.
             const jsonAgg = (rawKey) => jsonAggFields.get(rawKey);
             const fieldFor = (rawKey, col) => jsonAgg(rawKey)?.field ?? qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
+            // A JSON-path `_sum` / `_avg` casts its extracted text to numeric in
+            // SQL and is always a number; a plain column follows its source type
+            // (see {@link isExactNumericType}).
+            const sumAvg = (rawKey, rawValue) => jsonAgg(rawKey) ? (rawValue !== null ? Number(rawValue) : null) : sumAvgValue(qi, rawKey.slice(5), rawValue);
             for (const [rawKey, rawValue] of Object.entries(row)) {
                 if (rawKey.startsWith('_sum_')) {
-                    sumObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
+                    sumObj[fieldFor(rawKey, rawKey.slice(5))] = sumAvg(rawKey, rawValue);
                     hasSums = true;
                 }
                 else if (rawKey.startsWith('_avg_')) {
-                    avgObj[fieldFor(rawKey, rawKey.slice(5))] = rawValue !== null ? Number(rawValue) : null;
+                    avgObj[fieldFor(rawKey, rawKey.slice(5))] = sumAvg(rawKey, rawValue);
                     hasAvgs = true;
                 }
                 else if (rawKey.startsWith('_min_')) {
@@ -883,6 +887,52 @@ function temporalAggValue(qi, col, value) {
         return qi.utcTimestamps !== false ? parseDbDate(value) : new Date(value);
     return value;
 }
+/**
+ * Whether `SUM` / `AVG` over a column of `pgType` is EXACT on the wire and must
+ * not be narrowed to a JS number.
+ *
+ * PostgreSQL widens both past their input: over int8 they are `numeric`, over
+ * numeric they stay `numeric`. (An int2 / int4 sum is int8 and its average
+ * `numeric` too, but those totals fit a double, which is the line this draws.)
+ * The driver delivers `numeric` as its exact text, because no parser is
+ * registered for it, deliberately: the type is arbitrary-precision. `Number()`
+ * over that text rounded a `SUM(int8)` of 461168601842738790350 to
+ * 461168601842738800000 and a numeric(12,2) total of 1020.50 to 1020.5, while
+ * `_min` / `_max` on the very same columns came back exact, because they hand
+ * the driver's value through untouched.
+ *
+ * So for these source types the aggregate is returned as the driver delivered
+ * it (on PostgreSQL the text, a string; an engine whose driver already hands
+ * back a number keeps that number) and `_avg` is not cast to float in SQL,
+ * which would otherwise round on the server before the value reached the
+ * wire. Every other type keeps `Number()` and the cast. Spelled for every
+ * engine's type names: the PostgreSQL `udt_name` (`int8`, `numeric`) and the
+ * SQL names the other dialects report (`bigint`, `decimal`), with case and any
+ * `(precision, scale)` suffix ignored. JSON-path aggregates never reach this:
+ * they cast the extracted text to numeric themselves and stay numbers.
+ */
+function isExactNumericType(pgType) {
+    const paren = pgType.indexOf('(');
+    const base = (paren === -1 ? pgType : pgType.slice(0, paren)).trim().toLowerCase();
+    return base === 'int8' || base === 'bigint' || base === 'numeric' || base === 'decimal';
+}
+/** `AVG(col)`, float-cast unless the source column is exact (see {@link isExactNumericType}). */
+function plainAvgExpr(qi, col) {
+    const inner = `AVG(${qi.q(col)})`;
+    return isExactNumericType(whereMod.getColumnPgType(qi, col)) ? inner : qi.castAgg(inner, 'float');
+}
+/**
+ * A `_sum` / `_avg` value over a plain column: the driver's value verbatim
+ * for an exact source type (see {@link isExactNumericType}), a JS number for
+ * every other, `null` for an aggregate over zero rows.
+ */
+function sumAvgValue(qi, col, value) {
+    if (value === null || value === undefined)
+        return null;
+    if (isExactNumericType(whereMod.getColumnPgType(qi, col)))
+        return value;
+    return Number(value);
+}
 export function buildAggregate(qi, args) {
     qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Resolved once, up front: see buildGroupBy.
@@ -944,7 +994,7 @@ export function buildAggregate(qi, args) {
         for (const [field, enabled] of Object.entries(args._avg)) {
             if (enabled) {
                 const col = qi.toColumn(field);
-                selectExprs.push(`${qi.castAgg(`AVG(${qi.q(col)})`, 'float')} AS ${qi.q(`_avg_${col}`)}`);
+                selectExprs.push(`${plainAvgExpr(qi, col)} AS ${qi.q(`_avg_${col}`)}`);
             }
         }
     }
@@ -1014,13 +1064,13 @@ export function buildAggregate(qi, args) {
                 if (key.startsWith('_sum_')) {
                     const col = key.slice(5);
                     const field = qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                    sumObj[field] = val !== null ? Number(val) : null;
+                    sumObj[field] = sumAvgValue(qi, col, val);
                     hasSums = true;
                 }
                 else if (key.startsWith('_avg_')) {
                     const col = key.slice(5);
                     const field = qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                    avgObj[field] = val !== null ? Number(val) : null;
+                    avgObj[field] = sumAvgValue(qi, col, val);
                     hasAvgs = true;
                 }
                 else if (key.startsWith('_min_')) {

package/dist/query/builder.d.ts

@@ -589,32 +589,80 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private pkOrderBy;
     /**
      * The field names a `cursor` actually seeks on (its own keys with a defined
-     * value), in the canonical sorted order the cursor conditions are built in.
-     * Empty for a missing cursor or one whose every value is `undefined` (which
-     * emits no seek condition at all, so it does not paginate).
+     * 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 emits `col > $n` per field (`<` when the orderBy says desc),
-     * so the ONLY ordering coherent with it is on the cursor's own field: ordering
-     * a seek on column X by column Y walks the table in an order the seek does not
-     * follow, which skips and repeats rows just as badly as no order at all. That
-     * is why this orders on the cursor field rather than blindly on the primary
-     * key when the two differ.
+     * A 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. `a > $1 AND b > $2` is a conjunction, not a proper
-     *    composite keyset seek (`(a, b) > ($1, $2)`), so no single ORDER BY makes
-     *    it correct. Injecting `(a asc, b asc)` would dress a broken seek up as a
-     *    sound one.
+     *  - 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:
@@ -1307,6 +1355,21 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */
     private toSqlColumn;
+    /**
+     * The explicit outer SELECT list of the `distinct` + `orderBy` wrapper, used
+     * only when the inner derived table had to carry ORDER BY columns the
+     * projection leaves out (see the distinct branch of {@link buildFindMany}):
+     * the projected base columns, then one column per `with` relation, then one
+     * per counted relation. These are the aliases `buildSelectWithRelations`
+     * (relations.ts) gives the same columns, `AS "<relName>"` per entry in sorted
+     * order and `AS "_count__<rel>"` per counted relation, over the SAME
+     * `resolveCountRelations` it uses, so the two lists name the same columns.
+     * `flatten` never reaches here (the strategy is gated off under `distinct`),
+     * so no prefixed scalar aliases exist to enumerate. A drift between the two
+     * would fail LOUDLY, as a 42703 on the outer list, never as a silently wrong
+     * row, and the live distinct test pins the `with` + `_count` shape.
+     */
+    private distinctOuterSelectList;
     fingerprintWhere(where: Record<string, unknown>): string;
     collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
     private resolveGlobalFilter;