turbine-orm 0.72.0 → 0.73.0

package/dist/powql.js

@@ -39,14 +39,15 @@ import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, Va
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
-import { expandCompoundUniqueWhere } from './query/compound-unique.js';
+import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
+import { warnUnknownQueryOptions } from './query/option-surface.js';
 import { normalizeWithClause } from './query/relation-names.js';
 // The privilege sentinel and its resolver: `includePii` / `allowFullTableScan`
 // are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
 // engines, so a spread request body cannot turn either on here either.
 import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
-import { escapeLike, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
+import { escapeLike, normalizePagination, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -338,13 +339,14 @@ export class PowqlInterface {
         return this.pool.capabilities ?? ALL_POWDB_CAPABILITIES;
     }
     /**
-     * The `limit` a query actually emits: the explicit `limit`, Prisma's `take`
-     * alias, then the client-level `defaultLimit`. Shared by {@link buildFind} and
-     * the {@link findMany} zero short-circuit so the two can never disagree about
-     * which limit is in force.
+     * The `limit` a query actually emits: the explicit `limit`, then the
+     * client-level `defaultLimit`. Prisma's `take` alias is already folded into
+     * `limit` by `normalizeArgs`, so there is one spelling by the time this runs.
+     * Shared by {@link buildFind} and the {@link findMany} zero short-circuit so
+     * the two can never disagree about which limit is in force.
      */
     effectiveLimit(args) {
-        return args.limit ?? args.take ?? this.defaultLimit;
+        return args.limit ?? this.defaultLimit;
     }
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
@@ -383,12 +385,28 @@ export class PowqlInterface {
         const normalized = normalizeWithClause(this.schema, this.table, args.with);
         return normalized === args.with ? args : { ...args, with: normalized };
     }
+    /**
+     * Caller args in canonical form: declared relation spellings, and `take` /
+     * `skip` folded into `limit` / `offset`.
+     *
+     * Same composition as `QueryInterface.normalizeArgs` and here for the same
+     * reason the method above is here: nothing about a parallel implementation
+     * makes a core rule arrive on its own, and an engine that reads `take` but
+     * not `skip` pages differently from one that reads both.
+     */
+    normalizeArgs(args) {
+        return normalizePagination(this.withDeclaredRelationNames(args));
+    }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
             return;
         throw new UnsupportedFeatureError('The forceCustomPlan query option', 'powdb', 'Forcing a per-query custom plan means keeping the statement out of the PostgreSQL plan cache, and PowDB ' +
             'has no such cache to keep it out of. Remove the option, or set it only on PostgreSQL queries.');
     }
+    /** See query/compound-unique.ts: one rule and one message across engines. */
+    assertIdentifiesOneRow(where) {
+        assertWhereIdentifiesOneRow(this.meta, this.table, where);
+    }
     assertPagination(limit, offset, context) {
         for (const [name, value] of [
             ['limit', limit],
@@ -1302,6 +1320,11 @@ export class PowqlInterface {
     }
     /** Run a method body through the middleware chain (mirrors QueryInterface). */
     async withMiddleware(action, args, executor) {
+        // The unknown-key diagnostic, at the same seam and for the same reason as
+        // `QueryInterface.executeWithMiddleware`. The option surface is the CORE
+        // one because these args ARE core's args; PowDB reads them, it does not
+        // define them.
+        warnUnknownQueryOptions(this.table, action, args);
         if (this.middlewares.length === 0)
             return executor();
         let index = 0;
@@ -1327,7 +1350,7 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         this.assertNoForceCustomPlan(args);
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         return this.withMiddleware('findMany', args, async () => {
             // `limit: 0` means "no rows" (SQL `LIMIT 0`), and answering it client-side
             // is correct on every engine version: PowDB's projection fast path returned
@@ -1467,6 +1490,12 @@ export class PowqlInterface {
      * too, so both engines agree.
      */
     async explain(args = {}) {
+        // `explain` must compile the statement `findMany` would run, so it
+        // normalizes the same args the same way. Without this, explaining a query
+        // written with `take` / `skip` would report a plan for a DIFFERENT
+        // statement than the one that executes, which is the one thing a
+        // diagnostic must not do.
+        args = this.normalizeArgs(args);
         const params = [];
         const { powql } = await this.buildFind(args, params);
         const { rows } = await this.exec(`explain ${powql}`, params, args.timeout, 'explain');
@@ -1479,7 +1508,7 @@ export class PowqlInterface {
     }
     async findUnique(args) {
         this.assertNoForceCustomPlan(args);
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         // Prisma compound-unique selector → column conjunction (engine parity with
         // the SQL findUnique family; pure metadata, so this is a one-line adoption).
         if (args.where) {
@@ -1487,6 +1516,11 @@ export class PowqlInterface {
             if (expanded !== args.where)
                 args = { ...args, where: expanded };
         }
+        // AFTER the selector expansion, so a compound selector counts as the key it
+        // is. Same rule and same message as the SQL engines: a `where` that matches
+        // many rows plus `limit 1` returns an arbitrary one of them, and PowDB has
+        // no more of an ordering guarantee there than Postgres does.
+        this.assertIdentifiesOneRow(args.where);
         return this.withMiddleware('findUnique', args, async () => {
             const { rows, native, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
@@ -1504,7 +1538,7 @@ export class PowqlInterface {
         });
     }
     async findFirst(args = {}) {
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         this.assertNoForceCustomPlan(args);
         return this.withMiddleware('findFirst', args, async () => {
             const { rows, native, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
@@ -1858,7 +1892,7 @@ export class PowqlInterface {
      *     one loader chunk (the loader limits per chunk, the join once globally).
      */
     joinEligible(rel, opt, args, parentCount) {
-        const effLimit = args.limit ?? args.take ?? this.defaultLimit;
+        const effLimit = args.limit ?? this.defaultLimit;
         if (effLimit !== undefined || args.offset)
             return false;
         const options = (opt === true ? {} : opt);

package/dist/query/builder.d.ts

@@ -551,6 +551,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * query/relation-names.ts.
      */
     private withDeclaredRelationNames;
+    /**
+     * Caller args in canonical form: declared relation spellings, and the Prisma
+     * pagination aliases folded into `limit` / `offset`.
+     *
+     * 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.
+     */
+    private normalizeArgs;
+    /**
+     * 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;
     /**
      * 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

package/dist/query/builder.js

@@ -17,12 +17,13 @@ import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '..
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { expandCompoundUniqueWhere } from './compound-unique.js';
+import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './compound-unique.js';
 import { dedupeColumnList, dedupeOrderEntries, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
+import { warnUnknownQueryOptions } from './option-surface.js';
 import { normalizeWithClause } from './relation-names.js';
 import * as relationsMod from './relations.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
+import { isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -1083,6 +1084,28 @@ export class QueryInterface {
         const normalized = normalizeWithClause(this.schema, this.table, args.with);
         return normalized === args.with ? args : { ...args, with: normalized };
     }
+    /**
+     * Caller args in canonical form: declared relation spellings, and the Prisma
+     * pagination aliases folded into `limit` / `offset`.
+     *
+     * 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.
+     */
+    normalizeArgs(args) {
+        return normalizePagination(this.withDeclaredRelationNames(args));
+    }
+    /**
+     * 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.
+     */
+    assertFindUniqueKey(where) {
+        assertWhereIdentifiesOneRow(this.tableMeta, this.table, where);
+    }
     /**
      * 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
@@ -1222,7 +1245,7 @@ export class QueryInterface {
             return false;
         if (!isEmptyOrderBy(args.orderBy))
             return false;
-        if (args.limit !== undefined || args.take !== undefined || args.offset !== undefined)
+        if (args.limit !== undefined || args.offset !== undefined)
             return true;
         return this.cursorFields(args.cursor).length > 0;
     }
@@ -1287,7 +1310,6 @@ export class QueryInterface {
         const shape = [
             cursorFields.length > 0 ? 'cursor' : '',
             args?.limit !== undefined ? 'limit' : '',
-            args?.take !== undefined ? 'take' : '',
             args?.offset !== undefined ? 'offset' : '',
         ]
             .filter(Boolean)
@@ -1417,7 +1439,7 @@ export class QueryInterface {
      * not an estimate.
      */
     autoParentBound(args) {
-        return args?.take ?? args?.limit ?? this.defaultLimit;
+        return args?.limit ?? this.defaultLimit;
     }
     /**
      * The parent-row count at which `'auto'` stops preferring the single-statement
@@ -1741,7 +1763,7 @@ export class QueryInterface {
         // Declared relation spellings first, exactly as the join path does in
         // buildFindMany: the loader reads `args.with` itself, so without this the
         // two strategies would disagree about which relation names are valid.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         // Stable relation order (opt-in): the batched loader forwards each relation's
         // orderBy into its follow-up query, so filling the synthesized PK order here
         // makes the batched output deterministic exactly like the join path.
@@ -2128,6 +2150,12 @@ export class QueryInterface {
      */
     async executeWithMiddleware(action, args, executor) {
         this.currentAction = action;
+        // Every public operation passes through here with its own name and the
+        // caller's args, which makes this the one place the unknown-key diagnostic
+        // can be complete. Putting it in each method instead would mean fifteen
+        // sites and a new one every time an operation is added, which is precisely
+        // how the surface it checks came to need checking.
+        warnUnknownQueryOptions(this.table, action, args);
         if (this.middlewares.length === 0) {
             return executor();
         }
@@ -2156,7 +2184,7 @@ export class QueryInterface {
         // changes the warning text from the declared name back to the caller's and
         // nothing else). It is here so the invariant holds at the seam rather than
         // depending on every consumer to re-establish it.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('findUnique', args, async () => {
             if (args.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
@@ -2185,7 +2213,7 @@ export class QueryInterface {
      */
     async runFindUniqueBatched(args) {
         // Declared relation spellings first, see runFindManyBatched.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         // Stable relation order (opt-in), see runFindManyBatched.
         const withClause = this.resolveStableOrder(args.stableRelationOrder)
             ? this.applyStableRelationOrder(args.with, this.table)
@@ -2239,9 +2267,22 @@ export class QueryInterface {
                 'A key whose value is `undefined` does not count, check that the value you are looking up is defined. ' +
                 'If you meant "any row matching an optional filter", use `findFirst`.');
         }
+        // ...and a where that HAS a predicate but does not name a unique key is the
+        // same hazard one step along (0.73.0). `findUnique({ where: { status:
+        // 'active' } })` used to emit `WHERE status = $1 LIMIT 1` with no ORDER BY:
+        // one row out of many, chosen by the engine, different between two calls
+        // with the same argument and between two plans for the same call. The
+        // caller who wrote `findUnique` asked for the row, not a row, and the
+        // `null` branch they wrote reads as "no such row" when it means "none
+        // matched this filter".
+        //
+        // Checked against the USER's where for the same reason as the guard above:
+        // a global filter is not an identity, and letting one satisfy this would
+        // hand back an arbitrary row from inside the tenant.
+        this.assertFindUniqueKey(args.where);
         // Declared relation spellings first, before stable-order and the
         // fingerprint (see buildFindMany).
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {
@@ -2390,7 +2431,7 @@ export class QueryInterface {
         // changes the warning text from the declared name back to the caller's and
         // nothing else). It is here so the invariant holds at the seam rather than
         // depending on every consumer to re-establish it.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         this.maybeWarnUnlimited(args);
         this.maybeWarnUnorderedPage(args);
         // Dev-only: warn on deeply nested with clauses
@@ -2498,7 +2539,7 @@ export class QueryInterface {
             return;
         if (this.defaultLimit !== undefined)
             return;
-        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined || args?.cursor !== undefined;
+        const hasExplicitLimit = args?.limit !== undefined || args?.cursor !== undefined;
         if (hasExplicitLimit)
             return;
         if (this.whereMatchesAtMostOneRow(args?.where))
@@ -2577,7 +2618,7 @@ export class QueryInterface {
         // pass and the fingerprint below and before any of the six `with` walkers,
         // so none of them needs to know a relation has two accepted spellings and
         // both spellings share one cache entry. See query/relation-names.ts.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations BEFORE fingerprinting, so the two orderings get distinct cache
         // entries and every downstream path (SQL build, collect, parser) inherits it.
@@ -2708,7 +2749,7 @@ export class QueryInterface {
         // the caller's column order, so a permuted array rebuilds different SQL and
         // must not collapse onto the same cache entry (would trip the cross-check).
         const distinctFp = args?.distinct ? args.distinct.join(',') : '';
-        const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
+        const effectiveLimit = args?.limit ?? this.defaultLimit;
         // On engines that inline the literal LIMIT/OFFSET into the SQL text
         // (dialect.inlineLimitOffset, MySQL), the value is part of the SQL, not the
         // params, so it MUST be part of the fingerprint or two different limits share
@@ -2994,8 +3035,19 @@ export class QueryInterface {
      * non-empty.
      */
     async *streamRaw(args, action) {
+        // Pagination aliases folded BEFORE the speculative build below, which
+        // spreads `args` and overrides `limit`. A surviving `take` would reach that
+        // spread alongside the override and be read as two different values for one
+        // bound. Relation names are left to `buildFindMany`, which both branches go
+        // through.
+        args = normalizePagination(args);
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         this.currentAction = action;
+        // The two streaming methods do NOT go through `executeWithMiddleware`, so
+        // the unknown-key diagnostic has to be hung here as well or a stream would
+        // be the one read that silently drops an `include`. Both public methods
+        // reach this, and each passes its own name.
+        warnUnknownQueryOptions(this.table, action, args);
         // Streaming is ALREADY immune to the generic-plan cliff: the speculative
         // fetch has never passed a prepared name, and the cursor path runs through
         // DECLARE, so neither statement enters the plan cache. `preparedNameFor` is
@@ -3176,7 +3228,7 @@ export class QueryInterface {
         // changes the warning text from the declared name back to the caller's and
         // nothing else). It is here so the invariant holds at the seam rather than
         // depending on every consumer to re-establish it.
-        args = this.withDeclaredRelationNames(args);
+        args = this.normalizeArgs(args);
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             if (args?.with) {
                 const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);

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

@@ -49,3 +49,47 @@ import type { TableMetadata } from '../schema.js';
  * unknown-column error at SQL-build time.
  */
 export declare function expandCompoundUniqueWhere(meta: TableMetadata, where: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Every column set that identifies AT MOST ONE ROW of this table.
+ *
+ * Same sources and the same partial-index rule as {@link syntheticKeyMap}, and
+ * in this module for that reason: "what identifies one row" is one question,
+ * and answering it in two places is how a compound selector comes to be
+ * accepted by the name and refused by its members (0.72.0 fixed exactly that).
+ * The difference is only the arity: a synthetic SELECTOR needs two or more
+ * columns to have a joined name, while a single-column unique identifies a row
+ * perfectly well.
+ */
+/**
+ * Throw unless `where` identifies a single row. The refusal for `findUnique` on
+ * EVERY engine, message included.
+ *
+ * Shared rather than written twice because `PowqlInterface` is a parallel
+ * implementation: two copies of a rule this specific (which sources count as
+ * unique, whether a null identifies, which keys the message lists) is how two
+ * engines come to disagree about whether a query is valid, which is the exact
+ * divergence 0.64.0 and 0.72.0 were both spent on.
+ *
+ * The message lists the keys that WOULD work, because the fix is almost always
+ * one of them and a caller cannot be expected to know which columns the
+ * database considers unique. A table with no unique key at all gets its own
+ * sentence: no `where` satisfies this, and "name a unique key" is advice that
+ * person cannot take.
+ */
+export declare function assertWhereIdentifiesOneRow(meta: TableMetadata, table: string, where: Record<string, unknown> | undefined): void;
+export declare function uniqueKeyNames(meta: TableMetadata): string[][];
+/**
+ * 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.
+ *
+ * Deliberately reads only the TOP LEVEL of the user's where. A unique key
+ * buried inside an `OR` does not identify a row (the other branch matches
+ * whatever it matches), and one inside an `AND` array is a shape nobody writes
+ * for a lookup by identity. Extra predicates alongside the key are fine: they
+ * can only narrow a set that already holds at most one row.
+ *
+ * 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.
+ */
+export declare function whereIdentifiesOneRow(meta: TableMetadata, where: Record<string, unknown>): boolean;

package/dist/query/compound-unique.js

@@ -200,3 +200,119 @@ export function expandCompoundUniqueWhere(meta, where) {
     }
     return result ?? where;
 }
+/**
+ * Every column set that identifies AT MOST ONE ROW of this table.
+ *
+ * Same sources and the same partial-index rule as {@link syntheticKeyMap}, and
+ * in this module for that reason: "what identifies one row" is one question,
+ * and answering it in two places is how a compound selector comes to be
+ * accepted by the name and refused by its members (0.72.0 fixed exactly that).
+ * The difference is only the arity: a synthetic SELECTOR needs two or more
+ * columns to have a joined name, while a single-column unique identifies a row
+ * perfectly well.
+ */
+/**
+ * Throw unless `where` identifies a single row. The refusal for `findUnique` on
+ * EVERY engine, message included.
+ *
+ * Shared rather than written twice because `PowqlInterface` is a parallel
+ * implementation: two copies of a rule this specific (which sources count as
+ * unique, whether a null identifies, which keys the message lists) is how two
+ * engines come to disagree about whether a query is valid, which is the exact
+ * divergence 0.64.0 and 0.72.0 were both spent on.
+ *
+ * The message lists the keys that WOULD work, because the fix is almost always
+ * one of them and a caller cannot be expected to know which columns the
+ * database considers unique. A table with no unique key at all gets its own
+ * sentence: no `where` satisfies this, and "name a unique key" is advice that
+ * person cannot take.
+ */
+export function assertWhereIdentifiesOneRow(meta, table, where) {
+    if (whereIdentifiesOneRow(meta, where ?? {}))
+        return;
+    const field = (c) => meta.reverseColumnMap[c] ?? c;
+    const keys = uniqueKeyNames(meta).map((cols) => cols.length === 1 ? `\`${field(cols[0])}\`` : `\`{ ${cols.map(field).join(', ')} }\``);
+    const advice = keys.length > 0
+        ? `Name a unique key (${keys.join(', ')}), or use \`findFirst\` if you meant "any row matching a filter".`
+        : `Table "${table}" declares no primary key and no unique constraint, so no \`where\` can identify one row ` +
+            'here. Use `findFirst` (add an `orderBy` to make which row it is deterministic).';
+    throw new ValidationError(`[turbine] 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}`);
+}
+export function uniqueKeyNames(meta) {
+    return dedupeColumnSets(uniqueColumnSets(meta));
+}
+/** Distinct column sets, preserving first-seen order (a PK is often also a declared unique). */
+function dedupeColumnSets(sets) {
+    const seen = new Set();
+    const out = [];
+    for (const cols of sets) {
+        const sig = cols.join('\u0000');
+        if (seen.has(sig))
+            continue;
+        seen.add(sig);
+        out.push(cols);
+    }
+    return out;
+}
+function uniqueColumnSets(meta) {
+    const sets = [];
+    if (meta.primaryKey.length > 0)
+        sets.push(meta.primaryKey);
+    for (const uc of meta.uniqueColumns)
+        if (uc.length > 0)
+            sets.push(uc);
+    for (const idx of meta.indexes) {
+        if (idx.unique && !idx.docPath && !idx.partial && idx.columns.length > 0)
+            sets.push(idx.columns);
+    }
+    return sets;
+}
+/**
+ * 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.
+ *
+ * Deliberately reads only the TOP LEVEL of the user's where. A unique key
+ * buried inside an `OR` does not identify a row (the other branch matches
+ * whatever it matches), and one inside an `AND` array is a shape nobody writes
+ * for a lookup by identity. Extra predicates alongside the key are fine: they
+ * can only narrow a set that already holds at most one row.
+ *
+ * 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.
+ */
+export function whereIdentifiesOneRow(meta, where) {
+    const pinned = new Set();
+    for (const [key, value] of Object.entries(where)) {
+        if (!isPinnedToOneValue(value))
+            continue;
+        const column = resolveColumnName(meta, key);
+        if (column !== undefined)
+            pinned.add(column);
+    }
+    if (pinned.size === 0)
+        return false;
+    return uniqueColumnSets(meta).some((cols) => cols.every((c) => pinned.has(c)));
+}
+/** A bare value, or an operator object whose `equals` is a value. */
+function isPinnedToOneValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (isWhereOperator(value)) {
+        const eq = value.equals;
+        return eq !== undefined && eq !== null;
+    }
+    // A JSON / array / vector filter narrows, it does not identify.
+    if (isJsonFilter(value) || isArrayFilter(value) || isVectorFilter(value))
+        return false;
+    // Anything else that is a plain object is a relation filter or a sub-where,
+    // neither of which pins a column. Dates, Buffers and primitives are values.
+    return !isPlainObject(value);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/query/option-surface.d.ts

@@ -108,4 +108,26 @@ export declare const ALL_OPTION_TABLES: Readonly<Record<string, Readonly<Record<
 export declare function applyNativeOptions(table: Readonly<Record<string, OptionKind>>, src: Record<string, unknown>, dst: Record<string, unknown>): void;
 /** The keys of `table` with the given kind, as a set. */
 export declare function optionKeysOfKind(table: Readonly<Record<string, OptionKind>>, ...kinds: OptionKind[]): string[];
+/**
+ * Dev-mode warning for a key that is not part of the operation's option
+ * surface, and is therefore doing nothing.
+ *
+ * The motivating case is `include`. It is Prisma's word for `with`, it is what
+ * a model or a developer coming from Prisma reaches for first, and an
+ * unrecognized key is simply ignored: the query runs, returns rows, and the
+ * relation the caller asked for is absent. No error, no empty array, just a
+ * missing key on every row. A cross-model eval measured this as the single
+ * largest source of confidently-wrong queries against Turbine, and every one of
+ * them looked like a success from inside the process.
+ *
+ * A WARNING and never an error, deliberately. Refusing an unknown key would
+ * break `findMany({ ...someOptionsBag })`, which is ordinary code, and the
+ * option surface grows: a caller pinned to an older minor would have their
+ * working query start throwing. A warning costs a correct program nothing and
+ * tells an incorrect one exactly what happened.
+ *
+ * Dev-only, once per `table.operation.key` per process, and total: the whole
+ * body is wrapped, because a diagnostic must never be the reason a query fails.
+ */
+export declare function warnUnknownQueryOptions(table: string, operation: string, args: unknown): void;
 export {};