turbine-orm 0.72.0 → 0.73.0

package/README.md

@@ -20,7 +20,7 @@ Six reasons, each with the mechanism that makes it true:
 2. **Written from scratch.** Turbine is not a layer over Knex or a query-builder library. Query compilation is plain string building with an FNV-1a shape fingerprint into a bounded LRU of SQL templates, so there is no plan cache to size and no compiler running on your event loop.
 3. **Nested relations in one statement.** A `with` clause compiles to correlated `json_agg` subqueries, so users with posts with comments is one round trip, typed end to end: `users[0].posts[0].comments[0].author.name` autocompletes with no annotation.
 4. **Close to raw SQL.** In the last published run, Turbine's overhead over a hand-written `pg` control was 1.08x by geometric mean. The table is below; the losses are stated with the wins.
-5. **Agents get typed tools, not a SQL prompt.** `npx turbine mcp` exposes eleven read-only MCP tools, including a relation graph and a join-path finder that returns the `with` clause to write. Every tool runs inside `BEGIN READ ONLY`, and PII-tagged columns are redacted before rows reach a model.
+5. **Agents get a skill and typed tools, not a SQL prompt.** `npx turbine skill` installs a query-writing skill whose every claim is executed against a live database before release; `npx turbine mcp` exposes eleven read-only MCP tools, including a relation graph and a join-path finder that returns the `with` clause to write. Every tool runs inside `BEGIN READ ONLY`, and PII-tagged columns are redacted before rows reach a model.
 6. **The dangerous operations ask first.** Destructive migration statements refuse to run without typed consent. `update`/`delete` with an empty `where` throws. Columns tagged `pii: true` are excluded from the emitted SQL's projections. `turbine doctor` reports missing FK indexes offline, no account, no telemetry.
 
 ## Benchmarks
@@ -216,12 +216,15 @@ Every error extends `TurbineError` with a stable code (`TURBINE_E001` through `E
 
 ## Built for agents
 
-An agent pointed at a database usually gets a connection string and guesses. Turbine gives it typed tools instead:
+An agent pointed at a database usually gets a connection string and guesses. Turbine gives it a skill and typed tools instead:
 
 ```bash
+npx turbine skill  # install the query-writing skill into the project
 npx turbine mcp    # read-only MCP server over JSON-RPC stdio, ships in the package
 ```
 
+The skill covers what an agent gets wrong on a schema it has not seen: `with` versus Prisma's `include`, how relation names are derived, what `select` may name, relation filters, the `having` shape, JSON paths, and which error each mistake produces. **Every factual claim in it is executed against a live database before release**, so it cannot drift from the ORM the way documentation usually does. `--agents` prints a short block for `AGENTS.md` instead.
+
 Eleven tools, every one inside `BEGIN READ ONLY` with a statement timeout, so an agent cannot mutate anything through this server:
 
 | Tool | What it answers |
@@ -238,7 +241,7 @@ Eleven tools, every one inside `BEGIN READ ONLY` with a statement timeout, so an
 | `migrate_status` | Applied vs pending migrations, without applying anything. |
 | `doctor_report` | Missing relation indexes, from the same advisor `turbine doctor` uses. |
 
-The rest of the agent story is structural: query args are fully typed, so a wrong query is a compile error the agent can read; errors carry stable codes it can branch on; and [llms.txt](https://turbineorm.dev/llms.txt) / [llms-full.txt](https://turbineorm.dev/llms-full.txt) give it the docs in fetchable form. Setup for Claude Code and Cursor, plus a drop-in instructions snippet: [turbineorm.dev/ai-agents](https://turbineorm.dev/ai-agents).
+The rest of the agent story is structural: query args are fully typed, so a wrong query is a compile error the agent can read; errors carry stable codes it can branch on; an unrecognized query option warns instead of being silently dropped; and [llms.txt](https://turbineorm.dev/llms.txt) / [llms-full.txt](https://turbineorm.dev/llms-full.txt) give it the docs in fetchable form. Setup for Claude Code and Cursor, plus a drop-in instructions snippet: [turbineorm.dev/ai-agents](https://turbineorm.dev/ai-agents).
 
 ## Safety tooling
 

package/dist/cjs/cli/index.d.ts

@@ -18,6 +18,7 @@
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *   turbine skill                 - Install the agent query skill (--print, --agents, --dir <path>)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -113,6 +114,12 @@ export interface CliArgs {
      * not be turned into a failed install.
      */
     ifDb?: boolean;
+    /** `skill --print`: write the skill to stdout instead of installing it. */
+    print?: boolean;
+    /** `skill --agents`: print the AGENTS.md instructions block instead. */
+    agents?: boolean;
+    /** `skill --dir <path>`: the skills root to install into (default `.claude/skills`). */
+    dir?: string;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
 /**

package/dist/cjs/cli/index.js

@@ -19,6 +19,7 @@
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *   turbine skill                 - Install the agent query skill (--print, --agents, --dir <path>)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -227,6 +228,17 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--allow-pooler':
                 result.allowPooler = true;
                 break;
+            // `turbine skill`
+            case '--print':
+                result.print = true;
+                break;
+            case '--agents':
+                result.agents = true;
+                break;
+            case '--dir':
+                result.dir = next;
+                i++;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -4001,6 +4013,7 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('skill')}              Install the agent query skill ${(0, ui_js_1.dim)('(--print, --agents, --dir <path>)')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
@@ -4051,6 +4064,103 @@ function showHelp() {
     (0, ui_js_1.newline)();
 }
 // ---------------------------------------------------------------------------
+// Agent skill
+// ---------------------------------------------------------------------------
+/**
+ * turbine-orm's own package root, found by walking up from the running script.
+ *
+ * `process.argv[1]` rather than `import.meta.url` so the same source compiles
+ * for both the ESM and CJS builds, and realpath first because `npx turbine`
+ * runs through a `node_modules/.bin` symlink whose dirname is the CONSUMER's
+ * tree, where this package.json does not exist.
+ */
+function ownPackageRoot() {
+    try {
+        let entry = process.argv[1] ?? '';
+        try {
+            entry = (0, node_fs_1.realpathSync)(entry);
+        }
+        catch {
+            // keep the raw path if realpath fails (e.g. deleted cwd)
+        }
+        let dir = (0, node_path_1.dirname)(entry);
+        for (let i = 0; i < 6; i++) {
+            const candidate = (0, node_path_1.resolve)(dir, 'package.json');
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+                if (pkg.name === 'turbine-orm')
+                    return dir;
+            }
+            const parent = (0, node_path_1.dirname)(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+/** The instructions block for a project's AGENTS.md / CLAUDE.md. */
+const AGENTS_SNIPPET = `## Database access (Turbine ORM)
+
+- Queries go through the generated client. Read \`generated/turbine/types.ts\` for
+  the entity and input types before writing one; the names there are the truth.
+- Relations are \`with\`, never Prisma's \`include\`. An unrecognized option is
+  ignored, so an \`include\` returns rows with the relation missing.
+- \`select\` and \`omit\` name columns only. A relation named in \`select\` throws.
+- \`findUnique\` needs a unique key. Use \`findFirst\` for "any row matching a
+  filter", with an \`orderBy\` if which row matters.
+- Re-run \`npx turbine generate\` after any schema change, then \`tsc --noEmit\`:
+  an invalid query is a type error, so the type checker is the fastest reviewer.
+- Never write \`includePii: true\`, \`skipGlobalFilters: true\` or
+  \`allowFullTableScan: true\`. Those options take an imported \`UNSAFE\` symbol and
+  nothing else; any other value throws.
+- Full query reference: https://turbineorm.dev/llms.txt
+`;
+/**
+ * Install the packaged query-writing skill into the project.
+ *
+ * The skill is a file in the published tarball rather than something generated
+ * here, so what an agent reads is exactly what the repository tests: every
+ * factual claim in it is executed against a live database by
+ * `evals/src/verify-skill.ts` on each release.
+ */
+function cmdSkill(args) {
+    if (args.agents === true) {
+        console.log(AGENTS_SNIPPET);
+        return;
+    }
+    const root = ownPackageRoot();
+    const source = root ? (0, node_path_1.resolve)(root, 'skills', 'turbine-orm', 'SKILL.md') : undefined;
+    if (!source || !(0, node_fs_1.existsSync)(source)) {
+        (0, ui_js_1.error)('Could not find the packaged skill inside turbine-orm.');
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Read it online instead:')} ${(0, ui_js_1.cyan)('https://turbineorm.dev/ai-agents')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    const body = (0, node_fs_1.readFileSync)(source, 'utf8');
+    if (args.print === true) {
+        process.stdout.write(body);
+        return;
+    }
+    const skillsDir = args.dir ?? (0, node_path_1.join)('.claude', 'skills');
+    const target = (0, node_path_1.resolve)(process.cwd(), skillsDir, 'turbine-orm', 'SKILL.md');
+    const existed = (0, node_fs_1.existsSync)(target);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+    (0, node_fs_1.writeFileSync)(target, body);
+    (0, ui_js_1.newline)();
+    (0, ui_js_1.success)(`${existed ? 'Updated' : 'Installed'} the Turbine query skill`);
+    console.log(`  ${(0, ui_js_1.dim)((0, node_path_1.relative)(process.cwd(), target))}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('Also worth doing:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('-')} connect the read-only MCP server: ${(0, ui_js_1.cyan)('npx turbine mcp')}`);
+    console.log(`    ${(0, ui_js_1.dim)('-')} add the instructions block to AGENTS.md: ${(0, ui_js_1.cyan)('npx turbine skill --agents')}`);
+    (0, ui_js_1.newline)();
+}
+// ---------------------------------------------------------------------------
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
@@ -4199,6 +4309,9 @@ async function main() {
             case 'observe':
                 await cmdObserve(args);
                 break;
+            case 'skill':
+                cmdSkill(args);
+                break;
             default:
                 (0, ui_js_1.error)(`Unknown command: ${(0, ui_js_1.bold)(args.command)}`);
                 (0, ui_js_1.newline)();

package/dist/cjs/powql.d.ts

@@ -148,10 +148,11 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private get 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.
      */
     private effectiveLimit;
     /**
@@ -186,7 +187,19 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * which is the divergence class the projection resolver already cost.
      */
     private withDeclaredRelationNames;
+    /**
+     * 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.
+     */
+    private normalizeArgs;
     private assertNoForceCustomPlan;
+    /** See query/compound-unique.ts: one rule and one message across engines. */
+    private assertIdentifiesOneRow;
     private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;

package/dist/cjs/powql.js

@@ -77,6 +77,7 @@ const powdb_js_1 = require("./powdb.js");
 const aggregates_js_1 = require("./query/aggregates.js");
 const compound_unique_js_1 = require("./query/compound-unique.js");
 const filters_js_1 = require("./query/filters.js");
+const option_surface_js_1 = require("./query/option-surface.js");
 const relation_names_js_1 = require("./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
@@ -374,13 +375,14 @@ class PowqlInterface {
         return this.pool.capabilities ?? powdb_js_1.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
@@ -419,12 +421,28 @@ class PowqlInterface {
         const normalized = (0, relation_names_js_1.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 (0, utils_js_1.normalizePagination)(this.withDeclaredRelationNames(args));
+    }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
             return;
         throw new errors_js_1.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) {
+        (0, compound_unique_js_1.assertWhereIdentifiesOneRow)(this.meta, this.table, where);
+    }
     assertPagination(limit, offset, context) {
         for (const [name, value] of [
             ['limit', limit],
@@ -1338,6 +1356,11 @@ 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.
+        (0, option_surface_js_1.warnUnknownQueryOptions)(this.table, action, args);
         if (this.middlewares.length === 0)
             return executor();
         let index = 0;
@@ -1363,7 +1386,7 @@ 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
@@ -1503,6 +1526,12 @@ 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');
@@ -1515,7 +1544,7 @@ 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) {
@@ -1523,6 +1552,11 @@ 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)
@@ -1540,7 +1574,7 @@ 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');
@@ -1894,7 +1928,7 @@ 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/cjs/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/cjs/query/builder.js

@@ -57,6 +57,7 @@ const aggMod = __importStar(require("./aggregates.js"));
 const batched_loader_js_1 = require("./batched-loader.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
+const option_surface_js_1 = require("./option-surface.js");
 const relation_names_js_1 = require("./relation-names.js");
 const relationsMod = __importStar(require("./relations.js"));
 const types_js_1 = require("./types.js");
@@ -1121,6 +1122,28 @@ class QueryInterface {
         const normalized = (0, relation_names_js_1.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 (0, utils_js_1.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) {
+        (0, compound_unique_js_1.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
@@ -1260,7 +1283,7 @@ 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;
     }
@@ -1325,7 +1348,6 @@ class QueryInterface {
         const shape = [
             cursorFields.length > 0 ? 'cursor' : '',
             args?.limit !== undefined ? 'limit' : '',
-            args?.take !== undefined ? 'take' : '',
             args?.offset !== undefined ? 'offset' : '',
         ]
             .filter(Boolean)
@@ -1455,7 +1477,7 @@ 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
@@ -1779,7 +1801,7 @@ 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.
@@ -2166,6 +2188,12 @@ 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.
+        (0, option_surface_js_1.warnUnknownQueryOptions)(this.table, action, args);
         if (this.middlewares.length === 0) {
             return executor();
         }
@@ -2194,7 +2222,7 @@ 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);
@@ -2223,7 +2251,7 @@ 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)
@@ -2277,9 +2305,22 @@ 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)) {
@@ -2428,7 +2469,7 @@ 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
@@ -2536,7 +2577,7 @@ 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))
@@ -2615,7 +2656,7 @@ 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.
@@ -2746,7 +2787,7 @@ 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
@@ -3032,8 +3073,19 @@ 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 = (0, utils_js_1.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.
+        (0, option_surface_js_1.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
@@ -3214,7 +3266,7 @@ 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/cjs/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;