turbine-orm 0.77.1 → 0.78.0

package/dist/query/builder.js

@@ -1134,9 +1134,11 @@ export class QueryInterface {
     }
     /**
      * 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).
      */
     cursorFields(cursor) {
         if (!cursor || typeof cursor !== 'object')
@@ -1150,18 +1152,20 @@ export class QueryInterface {
      * 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.
@@ -1179,6 +1183,83 @@ export class QueryInterface {
         }
         return { [field]: 'asc' };
     }
+    /**
+     * 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.
+     */
+    cursorSeekEntries(cursor, orderBy) {
+        const orderPos = new Map();
+        const orderDesc = new Map();
+        for (const [ok, od] of orderByEntries(orderBy)) {
+            const ocol = resolveColumnName(this.tableMeta, ok);
+            if (ocol === undefined)
+                continue;
+            if (!orderPos.has(ocol))
+                orderPos.set(ocol, orderPos.size);
+            // Last wins, matching object-key semantics (duplicates are refused
+            // upstream anyway, so in practice there is exactly one).
+            orderDesc.set(ocol, isOrderBySpec(od) ? od.sort === 'desc' : od === 'desc');
+        }
+        const entries = sortedEntries(cursor)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, value]) => {
+            const column = this.toColumn(k);
+            return { column, value, desc: orderDesc.get(column) === true };
+        });
+        // Stable sort over the canonical (sorted-key) list: orderBy precedence
+        // first, unnamed fields after it in their sorted order.
+        return entries.sort((a, b) => (orderPos.get(a.column) ?? Number.MAX_SAFE_INTEGER) - (orderPos.get(b.column) ?? Number.MAX_SAFE_INTEGER));
+    }
+    /**
+     * 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.
+     */
+    keysetPredicate(terms) {
+        const compare = (t) => `${t.column} ${t.desc ? '<' : '>'} ${t.placeholder}`;
+        if (terms.length === 1)
+            return compare(terms[0]);
+        const branches = terms.map((term, i) => {
+            if (i === 0)
+                return compare(term);
+            const prefix = terms.slice(0, i).map((t) => `${t.column} = ${t.placeholder}`);
+            return `(${[...prefix, compare(term)].join(' AND ')})`;
+        });
+        return `(${branches.join(' OR ')})`;
+    }
     /**
      * Whether a findMany paginates (`limit` / `take` / `offset` / `cursor`) but
      * declares no ordering, which makes the returned page NON-DETERMINISTIC:
@@ -1663,17 +1744,27 @@ export class QueryInterface {
             // Query-level opt-in threaded onto every follow-up child `buildFindMany`,
             // so a batched load excludes/includes PII exactly as the join strategy.
             includePii,
-            tableGlobalFilter: (table, alias, precedingParams) => {
+            // `ref` is the follow-up query's FROM-item AS THE SQL REFERS TO IT: the
+            // quoted child table for a hasMany `_count`, the bare junction alias `t`
+            // for the m2m one. Compiled through the rendered-reference scope, which
+            // uses it verbatim for the column qualifier and for a nested relation
+            // filter's correlation parent alike. It went through the BARE-alias scope
+            // before, which quotes what it is given, so a `globalFilters` entry that
+            // was itself a relation filter emitted `"""posts"""` into the EXISTS
+            // body and the count failed 42P01. Reproduced live; the plain batched
+            // relation fetch was never affected, because that one goes through the
+            // child's own buildFindMany and merges the filter unqualified.
+            tableGlobalFilter: (table, ref, precedingParams) => {
                 const gf = this.resolveGlobalFilter(table, resolvedSkip);
                 if (!gf)
                     return null;
                 const meta = this.schema.tables[table];
                 if (!meta)
                     return null;
-                // Seed the param array with `precedingParams` placeholders so
-                // buildAliasWhere numbers the gf params after the already-bound ones.
+                // Seed the param array with `precedingParams` placeholders so the
+                // builder numbers the gf params after the already-bound ones.
                 const seeded = new Array(precedingParams).fill(undefined);
-                const clause = this.buildAliasWhere(table, meta, alias, gf, seeded);
+                const clause = whereMod.buildRenderedRefWhere(this.ctx, table, meta, ref, gf, seeded);
                 if (!clause)
                     return null;
                 return { clause, params: seeded.slice(precedingParams) };
@@ -2697,10 +2788,12 @@ export class QueryInterface {
             })
                 .join(',')
             : '';
+        // Keyset order AND per-field direction: a multi-field cursor's predicate
+        // is one OR-branch per field in orderBy precedence, and `<` / `>` are SQL
+        // text, so `asc` and `desc` (or two precedences) can never share a template.
         const cursorFp = args?.cursor
-            ? Object.keys(args.cursor)
-                .filter((k) => args.cursor[k] !== undefined)
-                .sort()
+            ? this.cursorSeekEntries(args.cursor, args.orderBy)
+                .map((e) => `${e.column}:${e.desc ? 'd' : 'a'}`)
                 .join(',')
             : '';
         // distinct must fingerprint in USER order: the SQL emits `DISTINCT ON` in
@@ -2810,39 +2903,16 @@ export class QueryInterface {
             // where → cursor order (the collect path mirrors this exactly).
             let tail = freshWhereSql;
             if (args?.cursor) {
-                // Sorted (canonical) order, MUST match cursorFp and the cache-hit collect below.
-                const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
-                if (cursorEntries.length > 0) {
-                    // Resolve the seek direction per cursor field from the flattened
-                    // orderBy entries (last wins, matching object-key semantics), so both
-                    // the object and array orderBy forms drive the cursor comparison.
-                    //
-                    // 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' }` missed
-                    // this lookup, defaulted to ascending, and emitted `created_at > $n`
-                    // under `ORDER BY created_at DESC` — the wrong page, silently. Same
-                    // failure the `{ sort, nulls }` normalization below prevents, reached
-                    // through the spelling instead of the value shape. A relation /
-                    // JSON-path / vector key resolves to no column and is skipped.
-                    const orderDirByColumn = new Map();
-                    for (const [ok, od] of orderByEntries(args.orderBy)) {
-                        const ocol = resolveColumnName(this.tableMeta, ok);
-                        if (ocol !== undefined)
-                            orderDirByColumn.set(ocol, od);
-                    }
-                    const cursorConditions = cursorEntries.map(([k, v]) => {
-                        const rawCol = this.toColumn(k);
-                        const col = this.q(rawCol);
-                        // orderBy values can be the { sort, nulls } spec form: normalize
-                        // before comparing, or a desc spec would seek the ascending side.
-                        const dir = orderDirByColumn.get(rawCol);
-                        const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
-                        const op = desc ? '<' : '>';
-                        freshParams.push(v);
-                        return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
+                // Keyset order (orderBy precedence), MUST match cursorFp and the
+                // cache-hit collect below: both go through cursorSeekEntries.
+                const seek = this.cursorSeekEntries(args.cursor, args.orderBy);
+                if (seek.length > 0) {
+                    const terms = seek.map((e) => {
+                        freshParams.push(e.value);
+                        return { column: `${qt}.${this.q(e.column)}`, placeholder: this.p(freshParams.length), desc: e.desc };
                     });
-                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
+                    const predicate = this.keysetPredicate(terms);
+                    tail += freshWhereSql ? ` AND ${predicate}` : ` WHERE ${predicate}`;
                 }
             }
             // ORDER BY is built AFTER the cursor pushes (param order
@@ -2861,10 +2931,40 @@ export class QueryInterface {
                     throw new ValidationError('`distinct` cannot be combined with vector distance ordering.');
                 }
                 const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                // The outer level re-orders by the user's columns, which must therefore
+                // exist in the derived table. A NARROWED projection (`select`, `omit`,
+                // or the PII rule, which narrows with no user projection at all) left
+                // them out, so the statement failed with 42703. Every order column the
+                // projection omits is projected into the INNER query under its own
+                // name, and the outer SELECT then lists the projected columns
+                // explicitly instead of `*`, so the extra column orders the result and
+                // never reaches a row (a PII column never even crosses the wire). The
+                // full projection (`columnsList === null`, `"t".*`) and a projection
+                // that already covers the order keeps the `SELECT *` wrapper byte for
+                // byte. The user's order is rendered ONCE (params pushed once, as the
+                // collect path mirrors) and its text reused at both levels.
+                let innerSelect = selectClause;
+                let outerSelect = '*';
+                if (columnsList) {
+                    const projected = new Set(columnsList);
+                    const extras = [];
+                    for (const [key] of orderByEntries(args.orderBy)) {
+                        // Relation and vector ordering are refused above, so every key
+                        // names a column of this table (a JSON-path entry's key is its
+                        // column); buildOrderBy has already validated it.
+                        const col = this.toColumn(key);
+                        if (!projected.has(col) && !extras.includes(col))
+                            extras.push(col);
+                    }
+                    if (extras.length > 0) {
+                        innerSelect = `${selectClause}, ${extras.map((c) => `${qt}.${this.q(c)}`).join(', ')}`;
+                        outerSelect = this.distinctOuterSelectList(columnsList, args.with).join(', ');
+                    }
+                }
+                const inner = `SELECT ${distinctPrefix}${innerSelect} FROM ${qt}${tail} ORDER BY ${distinctCols
                     .map((c) => `${c} ASC`)
                     .join(', ')}, ${userOrder}`;
-                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+                sql = `SELECT ${outerSelect} FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
             }
             else {
                 // Pass freshParams so vector KNN ordering binds its `$n::vector` query
@@ -2899,11 +2999,11 @@ export class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params, undefined, flattenPlan);
         }
-        // 3. Cursor params, sorted (canonical) order, matching cursorFp and the build path.
+        // 3. Cursor params, keyset order, matching cursorFp and the build path
+        //    (each value binds ONCE; the expanded predicate re-references its `$n`).
         if (args?.cursor) {
-            const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
-            for (const [, v] of cursorEntries) {
-                params.push(v);
+            for (const e of this.cursorSeekEntries(args.cursor, args.orderBy)) {
+                params.push(e.value);
             }
         }
         // 4. ORDER BY params (vector KNN ordering binds a `$n::vector` query vector).
@@ -3682,6 +3782,36 @@ export class QueryInterface {
     toSqlColumn(field) {
         return this.q(this.toColumn(field));
     }
+    /**
+     * 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.
+     */
+    distinctOuterSelectList(columnsList, withClause) {
+        const list = columnsList.map((c) => this.q(c));
+        if (!withClause)
+            return list;
+        for (const [relName] of sortedEntries(withClause)) {
+            if (relName === '_count')
+                continue;
+            list.push(this.q(relName));
+        }
+        const countSpec = withClause._count;
+        if (countSpec !== undefined) {
+            for (const rel of resolveCountRelations(this.tableMeta, countSpec))
+                list.push(this.q(`_count__${rel.name}`));
+        }
+        return list;
+    }
     // =========================================================================
     // Fingerprinting, value-invariant shape keys for SQL cache lookup
     // =========================================================================

package/dist/query/compound-unique.d.ts

@@ -77,7 +77,70 @@ export declare function expandCompoundUniqueWhere(meta: TableMetadata, where: Re
  * person cannot take.
  */
 export declare function assertWhereIdentifiesOneRow(meta: TableMetadata, table: string, where: Record<string, unknown> | undefined): void;
+/**
+ * The same refusal for the single-row WRITE methods, `update` and `delete`, and
+ * for `upsert`, whose `where` carries the same one-row contract by a different
+ * mechanism.
+ *
+ * `update` / `delete` emit `... WHERE <predicate> RETURNING *` and hand back
+ * `rows[0]`, so a `where` that matches many rows mutates EVERY one of them and
+ * reports one: the `findUnique` hazard (an arbitrary one of many) with a write
+ * attached. `upsert`'s `where` is not a predicate at all, it IS the conflict
+ * target, so a non-unique one has no single row to update on conflict and the
+ * emitted `ON CONFLICT (...)` names columns no unique index backs. Same rule,
+ * same sources of uniqueness, same null policy as
+ * {@link assertWhereIdentifiesOneRow}; only the sentence differs, because the
+ * consequence and the fix differ per operation. A reader who meant one row
+ * names a key; a reader who meant every matching row has `updateMany` /
+ * `deleteMany`, which report `{ count }` and never pretend to have touched one
+ * row.
+ *
+ * Called on the CALLER's where, before any global filter is merged in (a
+ * tenancy filter narrows, it does not identify). `update` / `delete` skip it
+ * under `allowFullTableScan: UNSAFE`, which already says "every row" in so many
+ * words, and their message names that hatch: a predicate CAN identify one row
+ * through a constraint this schema's metadata does not carry (a stale generated
+ * `metadata.ts`, a `defineSchema` that declares fewer uniques than the database
+ * has), and a rule with no way past it turns that into an unreachable method.
+ * `upsert` has no such option and its message therefore offers none.
+ */
+export declare function assertMutationWhereIdentifiesOneRow(meta: TableMetadata, table: string, where: Record<string, unknown> | undefined, operation: 'update' | 'delete' | 'upsert'): void;
 export declare function uniqueKeyNames(meta: TableMetadata): string[][];
+/**
+ * Brands a predicate Turbine wrote ENTIRELY itself to address the one row a
+ * DECLARED to-one relation points at, so the single-row write rule accepts it.
+ *
+ * A nested `disconnect: true` / `delete: true` on a `hasOne`, and a nested
+ * `update` on a `belongsTo` (whose argument is `{ data }`, with no `where` at
+ * all), give the caller no selector to write. The engine builds the predicate
+ * from the relation's own correlation key, and the thing that makes it one row
+ * is the relation's declared CARDINALITY, which is not in `primaryKey` /
+ * `uniqueColumns` / `indexes` and so is invisible to
+ * {@link whereIdentifiesOneRow}. Without this the rule refused those writes
+ * with "Name a unique key", advice the caller cannot take because they never
+ * wrote a `where`, on every schema whose `hasOne` FK is not ALSO declared
+ * unique: the `defineSchema` code-first path, the PowDB path, and any FK backed
+ * only by a partial unique index.
+ *
+ * Turbine believes a declared `hasOne` everywhere else (it reads the relation
+ * as an object rather than an array, and emits `LIMIT 1` for it), so believing
+ * it here is consistency, not a hole. The brand is applied at the one place the
+ * predicate is synthesized (`scopeWhereToParent` / the belongsTo correlation in
+ * nested-write.ts) and never to anything a caller supplied.
+ *
+ * A distinct Symbol rather than a second meaning for `markInternalCombinator`:
+ * that brand exists to keep a fixed-arity wrapper on a NAMED prepared
+ * statement, and folding "identifies one row" into it would mean any future
+ * fixed-arity wrapper silently switched this rule off. `Symbol.for` for the
+ * ESM/CJS cross-copy identity reason `INTERNAL_COMBINATOR` documents, and a
+ * SYMBOL so the `Object.keys` every where walker enumerates never sees it and
+ * no emitted SQL can change.
+ */
+export declare const INTERNAL_ROW_SELECTOR: unique symbol;
+/** Tag `where` as an engine-written single-row selector, and return it. */
+export declare function markInternalRowSelector<T extends object>(where: T): T;
+/** Did Turbine itself write this predicate to address one declared related row? */
+export declare function isInternalRowSelector(where: unknown): boolean;
 /**
  * True when `where` pins every column of at least one unique key to a single
  * value, so the row it names is the row it gets.
@@ -91,5 +154,18 @@ export declare function uniqueKeyNames(meta: TableMetadata): string[][];
  * A NULL is not an identity. `WHERE email IS NULL` matches every row whose
  * email is null, which a UNIQUE constraint permits any number of, so a null
  * value satisfies no key here even on a unique column.
+ *
+ * The one combinator it does read through is Turbine's OWN: a nested write
+ * scopes a child selector to its parent by merging the parent correlation in,
+ * and when the two name the same column the merge is `{ AND: [selector,
+ * correlation] }` BRANDED via `markInternalCombinator` (query/utils.ts). That
+ * brand is a Symbol no request body can produce, the arity is fixed at two,
+ * and each branch only narrows the other, so the wrapper identifies a row
+ * exactly when one of its branches does. A caller-written `AND` is not read.
+ *
+ * The other thing it reads is {@link markInternalRowSelector}: a predicate the
+ * ENGINE wrote in full, for which there is no caller `where` this rule could be
+ * about. See that function for why the declaration, not the metadata, is the
+ * uniqueness source there.
  */
 export declare function whereIdentifiesOneRow(meta: TableMetadata, where: Record<string, unknown>): boolean;

package/dist/query/compound-unique.js

@@ -40,7 +40,7 @@
  */
 import { ValidationError } from '../errors.js';
 import { isArrayFilter, isJsonFilter, isVectorFilter, isWhereOperator } from './filters.js';
-import { ownLookup, resolveColumnName, resolveRelationDef } from './utils.js';
+import { isInternalCombinator, ownLookup, resolveColumnName, resolveRelationDef } from './utils.js';
 const syntheticKeyCache = new WeakMap();
 /**
  * Build (once per table) the map from a synthetic selector name to the ordered
@@ -239,6 +239,70 @@ export function assertWhereIdentifiesOneRow(meta, table, where) {
     throw new ValidationError(`findUnique on "${table}" refused: the \`where\` clause does not identify a single row, ` +
         `so this would return an arbitrary one of the rows that match. ${advice}`);
 }
+/**
+ * The escape hatch sentence, on `update` / `delete` only.
+ *
+ * Stated with its cost rather than as an option to reach for: the same flag
+ * turns off the empty-`where` guard, so a predicate that is merely NARROW today
+ * and becomes EMPTY tomorrow (every value `undefined` on a request that omitted
+ * them) writes the whole table instead of being refused.
+ */
+const UNSAFE_ESCAPE = 'If this predicate really does identify one row through a constraint this schema does not describe, ' +
+    '`allowFullTableScan: UNSAFE` writes it anyway, at the cost of the empty-`where` guard as well: an ' +
+    'all-`undefined` `where` then matches every row instead of being refused.';
+/**
+ * The same refusal for the single-row WRITE methods, `update` and `delete`, and
+ * for `upsert`, whose `where` carries the same one-row contract by a different
+ * mechanism.
+ *
+ * `update` / `delete` emit `... WHERE <predicate> RETURNING *` and hand back
+ * `rows[0]`, so a `where` that matches many rows mutates EVERY one of them and
+ * reports one: the `findUnique` hazard (an arbitrary one of many) with a write
+ * attached. `upsert`'s `where` is not a predicate at all, it IS the conflict
+ * target, so a non-unique one has no single row to update on conflict and the
+ * emitted `ON CONFLICT (...)` names columns no unique index backs. Same rule,
+ * same sources of uniqueness, same null policy as
+ * {@link assertWhereIdentifiesOneRow}; only the sentence differs, because the
+ * consequence and the fix differ per operation. A reader who meant one row
+ * names a key; a reader who meant every matching row has `updateMany` /
+ * `deleteMany`, which report `{ count }` and never pretend to have touched one
+ * row.
+ *
+ * Called on the CALLER's where, before any global filter is merged in (a
+ * tenancy filter narrows, it does not identify). `update` / `delete` skip it
+ * under `allowFullTableScan: UNSAFE`, which already says "every row" in so many
+ * words, and their message names that hatch: a predicate CAN identify one row
+ * through a constraint this schema's metadata does not carry (a stale generated
+ * `metadata.ts`, a `defineSchema` that declares fewer uniques than the database
+ * has), and a rule with no way past it turns that into an unreachable method.
+ * `upsert` has no such option and its message therefore offers none.
+ */
+export function assertMutationWhereIdentifiesOneRow(meta, table, where, operation) {
+    if (whereIdentifiesOneRow(meta, where ?? {}))
+        return;
+    const keys = describeUniqueKeys(meta);
+    if (operation === 'upsert') {
+        const advice = keys.length > 0
+            ? `Name a unique key (${keys.join(', ')}).`
+            : `Table "${table}" declares no primary key and no unique constraint, so no \`where\` can identify one row ` +
+                'here and no upsert is possible on it: insert with `create`, or change matching rows with `updateMany`.';
+        throw new ValidationError(`upsert on "${table}" refused: the \`where\` clause does not identify a single row. An upsert's \`where\` IS ` +
+            'its conflict target, so there is no one row to update on conflict, and the `ON CONFLICT` this would emit ' +
+            `names columns no unique constraint backs. ${advice}`);
+    }
+    const many = operation === 'update' ? 'updateMany' : 'deleteMany';
+    const advice = keys.length > 0
+        ? `Name a unique key (${keys.join(', ')}), or use \`${many}\` if you meant "every row matching a filter".`
+        : `Table "${table}" declares no primary key and no unique constraint, so no \`where\` can identify one row ` +
+            `here. Use \`${many}\`, which reports how many rows it touched.`;
+    throw new ValidationError(`${operation} on "${table}" refused: the \`where\` clause does not identify a single row, ` +
+        `so this would ${operation} every row that matches and return only one of them. ${advice} ${UNSAFE_ESCAPE}`);
+}
+/** Each unique key of `meta` rendered in field spelling, for an error message. */
+function describeUniqueKeys(meta) {
+    const field = (c) => meta.reverseColumnMap[c] ?? c;
+    return uniqueKeyNames(meta).map((cols) => cols.length === 1 ? `\`${field(cols[0])}\`` : `\`{ ${cols.map(field).join(', ')} }\``);
+}
 export function uniqueKeyNames(meta) {
     return dedupeColumnSets(uniqueColumnSets(meta));
 }
@@ -268,6 +332,49 @@ function uniqueColumnSets(meta) {
     }
     return sets;
 }
+// ---------------------------------------------------------------------------
+// Engine-addressed row selectors
+// ---------------------------------------------------------------------------
+/**
+ * Brands a predicate Turbine wrote ENTIRELY itself to address the one row a
+ * DECLARED to-one relation points at, so the single-row write rule accepts it.
+ *
+ * A nested `disconnect: true` / `delete: true` on a `hasOne`, and a nested
+ * `update` on a `belongsTo` (whose argument is `{ data }`, with no `where` at
+ * all), give the caller no selector to write. The engine builds the predicate
+ * from the relation's own correlation key, and the thing that makes it one row
+ * is the relation's declared CARDINALITY, which is not in `primaryKey` /
+ * `uniqueColumns` / `indexes` and so is invisible to
+ * {@link whereIdentifiesOneRow}. Without this the rule refused those writes
+ * with "Name a unique key", advice the caller cannot take because they never
+ * wrote a `where`, on every schema whose `hasOne` FK is not ALSO declared
+ * unique: the `defineSchema` code-first path, the PowDB path, and any FK backed
+ * only by a partial unique index.
+ *
+ * Turbine believes a declared `hasOne` everywhere else (it reads the relation
+ * as an object rather than an array, and emits `LIMIT 1` for it), so believing
+ * it here is consistency, not a hole. The brand is applied at the one place the
+ * predicate is synthesized (`scopeWhereToParent` / the belongsTo correlation in
+ * nested-write.ts) and never to anything a caller supplied.
+ *
+ * A distinct Symbol rather than a second meaning for `markInternalCombinator`:
+ * that brand exists to keep a fixed-arity wrapper on a NAMED prepared
+ * statement, and folding "identifies one row" into it would mean any future
+ * fixed-arity wrapper silently switched this rule off. `Symbol.for` for the
+ * ESM/CJS cross-copy identity reason `INTERNAL_COMBINATOR` documents, and a
+ * SYMBOL so the `Object.keys` every where walker enumerates never sees it and
+ * no emitted SQL can change.
+ */
+export const INTERNAL_ROW_SELECTOR = Symbol.for('turbine.internalRowSelector');
+/** Tag `where` as an engine-written single-row selector, and return it. */
+export function markInternalRowSelector(where) {
+    Object.defineProperty(where, INTERNAL_ROW_SELECTOR, { value: true, enumerable: false, configurable: true });
+    return where;
+}
+/** Did Turbine itself write this predicate to address one declared related row? */
+export function isInternalRowSelector(where) {
+    return (typeof where === 'object' && where !== null && where[INTERNAL_ROW_SELECTOR] === true);
+}
 /**
  * True when `where` pins every column of at least one unique key to a single
  * value, so the row it names is the row it gets.
@@ -281,8 +388,26 @@ function uniqueColumnSets(meta) {
  * A NULL is not an identity. `WHERE email IS NULL` matches every row whose
  * email is null, which a UNIQUE constraint permits any number of, so a null
  * value satisfies no key here even on a unique column.
+ *
+ * The one combinator it does read through is Turbine's OWN: a nested write
+ * scopes a child selector to its parent by merging the parent correlation in,
+ * and when the two name the same column the merge is `{ AND: [selector,
+ * correlation] }` BRANDED via `markInternalCombinator` (query/utils.ts). That
+ * brand is a Symbol no request body can produce, the arity is fixed at two,
+ * and each branch only narrows the other, so the wrapper identifies a row
+ * exactly when one of its branches does. A caller-written `AND` is not read.
+ *
+ * The other thing it reads is {@link markInternalRowSelector}: a predicate the
+ * ENGINE wrote in full, for which there is no caller `where` this rule could be
+ * about. See that function for why the declaration, not the metadata, is the
+ * uniqueness source there.
  */
 export function whereIdentifiesOneRow(meta, where) {
+    if (isInternalRowSelector(where))
+        return true;
+    if (isInternalCombinator(where) && Array.isArray(where.AND)) {
+        return where.AND.some((branch) => typeof branch === 'object' && branch !== null && whereIdentifiesOneRow(meta, branch));
+    }
     const pinned = new Set();
     for (const [key, value] of Object.entries(where)) {
         if (!isPinnedToOneValue(value))

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonEncoding, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationPickBy, RelationPickOrderBy, ResolvedSkipGlobalFilters, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonEncoding, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderBySpec, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationOrderBy, RelationOrderByChain, RelationPickBy, RelationPickOrderBy, ResolvedSkipGlobalFilters, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { OptionKind, OptionTable } from './option-surface.js';