turbine-orm 0.77.1 → 0.78.0

package/dist/query/writes.js

@@ -12,7 +12,7 @@
  */
 import { NotFoundError, OptimisticLockError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
-import { expandCompoundUniqueWhere } from './compound-unique.js';
+import { assertMutationWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './compound-unique.js';
 import { isUnmatchedPlainObject, UPDATE_OPERATOR_KEYS } from './filters.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
 import { canonicalWriteEntries, coerceTemporalValue, resolveColumnName } from './utils.js';
@@ -346,7 +346,15 @@ export function buildUpdate(qi, args) {
     // The empty-`where` guard checks the USER predicate only, a global filter
     // must never turn an unguarded mass update into an allowed one.
     const userHasPredicate = !whereMod.userPredicateIsEmpty(qi, userWhere) || !!lock;
-    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
+    const allowFullTableScan = resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan');
+    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', allowFullTableScan);
+    // `update` returns ONE row, so its where must identify one: the 0.73
+    // `findUnique` rule (query/compound-unique.ts) applied to the write that has
+    // the same shape. On the USER's where, before the global filter is merged
+    // (a filter narrows, it never identifies), and skipped only under the
+    // explicit full-table opt-in, which already means "every row".
+    if (!allowFullTableScan)
+        assertMutationWhereIdentifiesOneRow(qi.tableMeta, qi.table, userWhere, 'update');
     // The SQL is built from the global-filter-merged where (soft-delete keeps an
     // update from touching already-deleted rows).
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
@@ -479,7 +487,12 @@ export function buildDelete(qi, args) {
     // Prisma compound-unique selector → the column conjunction (before the guard).
     const userWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
     // Guard the USER predicate (a global filter must not satisfy the guard).
-    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
+    const allowFullTableScan = resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan');
+    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', allowFullTableScan);
+    // Same identity rule as `update` (see buildUpdate): one returned row means
+    // one addressed row. `deleteMany` is the many-row path.
+    if (!allowFullTableScan)
+        assertMutationWhereIdentifiesOneRow(qi.tableMeta, qi.table, userWhere, 'delete');
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
@@ -533,6 +546,23 @@ export function buildUpsert(qi, args) {
     qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Prisma compound-unique selector on the conflict target → its member columns.
     const upsertWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
+    // An upsert's `where` becomes the CONFLICT TARGET, so it carries the same
+    // one-row contract `update` / `delete` do and is refused by the same rule
+    // (query/compound-unique.ts), with its own sentence because the consequence
+    // differs. Without it a non-unique `where` reached the server as
+    // `ON CONFLICT ("role")` and came back as a bare SQLSTATE 42P10 on
+    // PostgreSQL, and WORSE than an error on the engines that do not read the
+    // conflict target back: MySQL's `ON DUPLICATE KEY UPDATE` ignores it and
+    // keys off whichever unique index the row happens to violate, and SQL
+    // Server's `MERGE ... ON` matches every row the predicate matches and
+    // updates all of them.
+    //
+    // Before any SQL is assembled, and this is the only where-guard `upsert`
+    // runs: `{}` and `{ email: undefined }` are refused here too, and by the
+    // right sentence. The empty-`where` guard's own message points at
+    // `allowFullTableScan: UNSAFE`, which is not an option on `UpsertArgs` at
+    // all, so borrowing it here would name a way out that does not exist.
+    assertMutationWhereIdentifiesOneRow(qi.tableMeta, qi.table, upsertWhere, 'upsert');
     // Build the INSERT part from create data
     const createEntries = writeEntries(qi, args.create);
     const columns = createEntries.map(([k]) => qi.toSqlColumn(k));
@@ -542,25 +572,47 @@ export function buildUpsert(qi, args) {
     // The conflict target comes from `where` keys, must be unique/PK columns
     const conflictKeys = Object.keys(upsertWhere).filter((k) => upsertWhere[k] !== undefined);
     const conflictColumns = conflictKeys.map((k) => qi.toSqlColumn(k));
-    // Build the UPDATE SET part
+    // The conflict-UPDATE SET goes through the SAME operator-aware compiler as
+    // `update()` (buildSetClause), so `set` / `increment` / `decrement` /
+    // `multiply` / `divide` mean here what they mean there and a misspelled
+    // operator gets the same E003. This branch used to bind each value directly,
+    // which stored an operator OBJECT as the JSON text `{"set":"x"}` in a text
+    // column with no error at all. buildSetClause pushes onto `params` as it
+    // goes, so the numbering continues after the create params exactly as the
+    // hand-rolled `paramIdx` did. No SQL cache here (the statement is rebuilt per
+    // call), so the fingerprint / collect mirrors update() keeps are not needed.
     const updateEntries = writeEntries(qi, args.update);
-    let paramIdx = createParams.length + 1;
-    const setClauses = updateEntries.map(([k]) => {
-        const clause = `${qi.toSqlColumn(k)} = ${qi.p(paramIdx)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`;
-        paramIdx++;
-        return clause;
-    });
-    const updateParams = updateEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
-    const params = [...createParams, ...updateParams];
+    const params = [...createParams];
+    const refQualifier = upsertReferenceQualifier(qi);
+    const setClauses = updateEntries.map(([k, v]) => buildSetClause(qi, k, v, params, refQualifier));
     // Global filter → restrict the conflict-UPDATE (soft-delete / tenancy) so an
     // upsert never resurrects a soft-deleted row or writes across tenants. Only
-    // on engines whose upsert can carry a predicate (Postgres); the gf params
-    // continue the placeholder numbering after create+update params.
+    // on engines whose upsert can carry a predicate (Postgres, SQLite); the gf
+    // params continue the placeholder numbering after create+update params.
+    //
+    // Compiled against the TABLE QUALIFIER, not bare: in `ON CONFLICT ... DO
+    // UPDATE ... WHERE` both the target table and `excluded` are in scope, so an
+    // unqualified column is ambiguous and PostgreSQL rejected EVERY upsert on a
+    // globally filtered table at parse time (42702), insert path included.
     let updateWhere;
     if (qi.dialect.supportsUpsertUpdateWhere) {
         const gf = whereMod.resolveGlobalFilter(qi, qi.table);
-        if (gf)
-            updateWhere = whereMod.buildWhereClause(qi, gf, params) ?? undefined;
+        if (gf) {
+            // Compiled through a scope whose FROM-item reference is ALREADY RENDERED
+            // (`"users"`), which is what the target table is inside `ON CONFLICT ...
+            // DO UPDATE`. `aliasWhereScope` is the wrong seam for that: it takes a
+            // BARE alias and quotes it itself for the nested-relation correlation
+            // parent, so handing it `q(table)` produced a triple-quoted reference
+            // inside an EXISTS body and the whole statement failed with 42P01
+            // whenever the configured global filter was a relation filter rather
+            // than a plain column. A bare table name is not the answer either: it
+            // would leave the qualifier unquoted and break every table whose name
+            // needs quoting. `buildRenderedRefWhere` is the rendered-reference seam,
+            // one parameter with one meaning, used for the qualifier and the
+            // correlation parent alike, and shared with the batched `_count`
+            // follow-up, which had the identical bug.
+            updateWhere = whereMod.buildRenderedRefWhere(qi, qi.table, qi.tableMeta, qi.q(qi.table), gf, params) ?? undefined;
+        }
     }
     const sql = qi.dialect.buildUpsertStatement({
         table: qi.q(qi.table),
@@ -577,11 +629,21 @@ export function buildUpsert(qi, args) {
         transform: (result) => {
             const row = result.rows[0];
             if (!row) {
+                // With a conflict-UPDATE predicate in play there IS a way to get no
+                // row: the key conflicts with a row the global filter hides, the
+                // predicate is false for it, the engine skips the update, and the
+                // insert cannot happen either because the key is taken. Nothing was
+                // written and the hidden row is untouched; say so, rather than "this
+                // should never happen".
                 throw new NotFoundError({
                     table: qi.table,
                     where: args.where,
                     operation: 'upsert',
-                    message: `upsert on "${qi.table}" returned no row from RETURNING *; this should never happen.`,
+                    message: updateWhere
+                        ? `upsert on "${qi.table}" wrote nothing: the row that conflicts on the given key is excluded by the ` +
+                            `configured global filter for "${qi.table}", so it was neither updated (the filter hides it) nor ` +
+                            'inserted (the key is taken). Pass `skipGlobalFilters: UNSAFE` to address it anyway.'
+                        : `upsert on "${qi.table}" returned no row from RETURNING *; this should never happen.`,
                 });
             }
             return parseWriteRow(qi, row);
@@ -597,6 +659,29 @@ export function buildUpsert(qi, args) {
             : undefined,
     };
 }
+/**
+ * The qualifier an upsert's arithmetic SET operator reads its column through.
+ *
+ * `INSERT ... ON CONFLICT DO UPDATE SET n = n + 1` is 42702 on PostgreSQL
+ * because `n` could be the target row's or `excluded`'s, so the reference is
+ * qualified with the table name on every engine whose upsert statement names
+ * the table directly (PostgreSQL, SQLite, MySQL all accept `"t"."n"` there).
+ * SQL Server is the exception and keeps the bare reference: its `MERGE`
+ * aliases the target as `T`, so the TABLE NAME does not resolve there at all,
+ * and the alias belongs to that dialect's own `buildUpsertStatement` rather
+ * than to this module. An arithmetic operator in an mssql upsert may therefore
+ * still be refused by the server as an ambiguous column; that shape has never
+ * worked (it previously bound the operator OBJECT as the value), and the sound
+ * fix is for the dialect to publish its target alias, which is a change to
+ * `dialect.ts`. It fails loudly either way, so no wrong answer is possible.
+ * `set` and literal values reference no column and are unaffected everywhere.
+ *
+ * Gated on the dialect NAME, never on hook presence: every engine dialect
+ * spreads `postgresDialect`, so a presence test would say yes for all of them.
+ */
+function upsertReferenceQualifier(qi) {
+    return qi.dialect.name === 'mssql' ? '' : `${qi.q(qi.table)}.`;
+}
 export function buildUpdateMany(qi, args) {
     assertWritable(qi, 'updateMany');
     qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
@@ -859,9 +944,19 @@ export function assertNoGeneratedColumns(qi, data, operation) {
  * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
  * pushes any required params onto the shared params array so that WHERE
  * clause numbering continues correctly afterward.
+ *
+ * `refQualifier` prefixes the column REFERENCE an arithmetic operator reads
+ * from (`"view_count" = <qualifier>"view_count" + $n`). A plain `UPDATE` has
+ * one table in scope and passes nothing; `upsert` passes the table name,
+ * because inside `ON CONFLICT ... DO UPDATE SET` the target table and
+ * `excluded` are BOTH in scope and a bare reference is 42702 on PostgreSQL.
+ * The assignment target on the left stays bare on every engine (it can only
+ * ever be the target table's column), and `set` / literal values reference no
+ * column at all, so their SQL is byte-identical with or without a qualifier.
  */
-export function buildSetClause(qi, key, value, params) {
+export function buildSetClause(qi, key, value, params, refQualifier = '') {
     const col = qi.toSqlColumn(key);
+    const ref = `${refQualifier}${col}`;
     // Enum columns get an explicit `::"EnumName"` cast on their value bind
     // (see enumTypeForColumn); `''` everywhere else. Value-invariant, so the
     // SQL cache and collectSetParams are unaffected.
@@ -888,19 +983,19 @@ export function buildSetClause(qi, key, value, params) {
             }
             if (op === 'increment') {
                 params.push(opValue);
-                return `${col} = ${col} + ${qi.p(params.length)}`;
+                return `${col} = ${ref} + ${qi.p(params.length)}`;
             }
             if (op === 'decrement') {
                 params.push(opValue);
-                return `${col} = ${col} - ${qi.p(params.length)}`;
+                return `${col} = ${ref} - ${qi.p(params.length)}`;
             }
             if (op === 'multiply') {
                 params.push(opValue);
-                return `${col} = ${col} * ${qi.p(params.length)}`;
+                return `${col} = ${ref} * ${qi.p(params.length)}`;
             }
             if (op === 'divide') {
                 params.push(opValue);
-                return `${col} = ${col} / ${qi.p(params.length)}`;
+                return `${col} = ${ref} / ${qi.p(params.length)}`;
             }
         }
         // Fall through: multi-key objects or non-operator single-key objects

package/dist/seed.d.ts

@@ -12,4 +12,20 @@ export type DefinedSeed = () => Promise<void>;
  * Exported for unit testing the frame parser in isolation.
  */
 export declare function parseStackFramePath(line: string): string | null;
+/**
+ * Declare a seed: `fn` receives a connected `TurbineClient` and is awaited.
+ *
+ * The returned function runs the seed on demand. When the module that calls
+ * `defineSeed` is itself the process entry point (`npx tsx seed.ts`, or the
+ * child `turbine seed` spawns), the seed also runs automatically.
+ *
+ * The client connects through `DATABASE_URL`. Under `turbine seed` that value
+ * is the configured connection string with `search_path` PINNED to the
+ * configured `schema` (as the `options=-c search_path` connection parameter,
+ * so it can never leak onto a pooled backend the way a `SET` would). Every
+ * unqualified table name the seed writes therefore lands in the same schema
+ * `push`, `generate` and the generated client use; a seed that must reach
+ * another schema qualifies the name. The default `public` adds nothing, so a
+ * project that never set `schema` connects exactly as before.
+ */
 export declare function defineSeed(fn: SeedFunction): DefinedSeed;

package/dist/seed.js

@@ -139,6 +139,22 @@ async function runSeed(fn) {
         await db.disconnect();
     }
 }
+/**
+ * Declare a seed: `fn` receives a connected `TurbineClient` and is awaited.
+ *
+ * The returned function runs the seed on demand. When the module that calls
+ * `defineSeed` is itself the process entry point (`npx tsx seed.ts`, or the
+ * child `turbine seed` spawns), the seed also runs automatically.
+ *
+ * The client connects through `DATABASE_URL`. Under `turbine seed` that value
+ * is the configured connection string with `search_path` PINNED to the
+ * configured `schema` (as the `options=-c search_path` connection parameter,
+ * so it can never leak onto a pooled backend the way a `SET` would). Every
+ * unqualified table name the seed writes therefore lands in the same schema
+ * `push`, `generate` and the generated client use; a seed that must reach
+ * another schema qualifies the name. The default `public` adds nothing, so a
+ * project that never set `schema` connects exactly as before.
+ */
 export function defineSeed(fn) {
     const run = () => runSeed(fn);
     if (isDirectSeedModule()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.77.1",
+  "version": "0.78.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -132,7 +132,7 @@
     "//coverage:cli": "The CLI coverage gate, split into ONE collection run plus a per-file threshold check for every file in it, and an aggregate. c8 enforces a single threshold set per invocation and its --per-file applies the SAME numbers to every file, neither of which can express 'destructive.ts holds 100 while migrate.ts holds 70'. An aggregate-only floor lets the least-covered file spend the whole slack the best-covered file earned: at the measured 3623/2951 lines, migrate.ts could fall from 70.3% to 66.6% with the aggregate still green. So each file gets its OWN floor, checked by re-reporting the coverage already on disk (c8 report re-reads ./coverage/tmp, so this costs no extra test run). The aggregate check is kept as well: it catches all three sagging together inside their individual margins. Per-file gates run FIRST because their failure names the file. DATABASE_URL is neutralized on the collection run: these test files include live migration tests that create and drop tables, and this script runs from prepublishOnly.",
     "test:coverage:cli": "npm run check:coverage-sync && npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:sql-statements && npm run coverage:cli:gate:pii-guard && npm run coverage:cli:gate:error-catalog && npm run coverage:cli:gate:mcp && npm run coverage:cli:gate:compile-query && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:index && npm run coverage:cli:gate:aggregate",
     "//coverage:cli:collect": "--check-coverage=false is load-bearing, not tidying. c8 reads .c8rc.json for defaults, so this COLLECTION step was silently enforcing the MAIN gate's global thresholds against a src/cli-only file set. That is a gate nobody wrote and nobody wanted, and it went unnoticed only because the main floor was low enough (75) for the CLI aggregate (89.29) to clear it by accident. When the main floors were re-baselined to 93/89/78 (see //merge-bug in .c8rc.json) it started failing here, several steps before the per-file gates that are supposed to decide. Thresholds for these files belong to the coverage:cli:gate:* scripts, which pass their own explicitly.",
-    "coverage:cli:collect": "DATABASE_URL= c8 --all --check-coverage=false --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/compile-query.ts --include src/cli/error-catalog.ts --include src/cli/index.ts tsx --test src/test/studio-write.test.ts src/test/pii-guard-symmetry.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/tracking-table-race.test.ts src/test/destructive-dynamic-assembly.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts src/test/mcp.test.ts src/test/mcp-relations.test.ts src/test/mcp-pii.test.ts src/test/mcp-pii-round2.test.ts src/test/mcp-agent-tools.test.ts src/test/mcp-compile-query.test.ts src/test/mcp-perimeter-bounds.test.ts",
+    "coverage:cli:collect": "DATABASE_URL= c8 --all --check-coverage=false --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/compile-query.ts --include src/cli/error-catalog.ts --include src/cli/index.ts tsx --test src/test/studio-write.test.ts src/test/pii-guard-symmetry.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/tracking-table-race.test.ts src/test/destructive-dynamic-assembly.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts src/test/mcp.test.ts src/test/mcp-relations.test.ts src/test/mcp-pii.test.ts src/test/mcp-pii-round2.test.ts src/test/mcp-agent-tools.test.ts src/test/mcp-compile-query.test.ts src/test/mcp-perimeter-bounds.test.ts src/test/destructive-obfuscation.test.ts src/test/cli-init-schema.test.ts src/test/cli-introspect-options.test.ts src/test/mcp-transport-bounds.test.ts src/test/seed-schema.test.ts src/test/migrate-preview-and-report.test.ts src/test/destructive-quoting-forms.test.ts",
     "coverage:cli:gate": "c8 report --all --exclude 'src/test/**' --reporter text --check-coverage",
     "coverage:cli:gate:destructive": "npm run coverage:cli:gate -- --include src/cli/destructive.ts --lines 98 --statements 98 --branches 84 --functions 98",
     "coverage:cli:gate:sql-statements": "npm run coverage:cli:gate -- --include src/cli/sql-statements.ts --lines 100 --statements 100 --branches 98 --functions 100",
@@ -254,7 +254,7 @@
   },
   "lint-staged": {
     "*.ts": [
-      "biome check --no-errors-on-unmatched"
+      "biome check --error-on-warnings --no-errors-on-unmatched"
     ]
   }
 }

package/skills/turbine-orm/SKILL.md

@@ -171,15 +171,29 @@ where: { tastingNotes: { path: ['panel', 'score'], gte: 9 } }
 where: { credentialBlob: { path: ['tier'], equals: 'master' } }
 ```
 
-A path takes a NARROWER operator set than a plain column: `equals`, `gt`, `gte`,
-`lt`, `lte`, `contains`, `startsWith`, `endsWith`, plus `mode`. `not`, `in` and
-`notIn` are refused with `TURBINE_E003` listing what is accepted; express them
-with `NOT` / `OR` around the path filter instead.
-
-`_count` accepts a JSON path, and `groupBy` accepts one as a grouping key via
-`{ field, path }`. **`_avg`, `_sum`, `_min` and `_max` do not work on a JSON
-path**: they reach the database as `avg(jsonb)` and fail there. Cast the value
-into a real column, or aggregate in application code.
+A path takes a DIFFERENT operator set from a plain column: `equals`, `gt`,
+`gte`, `lt`, `lte`, `hasKey`, `contains`, `stringContains`, `stringStartsWith`,
+`stringEndsWith`, plus `mode` (which applies to the three `string*` operators).
+`contains` on a JSON column is containment (`@>`, a whole sub-document such as
+`{ contains: { panel: { seats: 4 } } }`), NOT a substring test; the substring
+operators on a path are `stringContains`, `stringStartsWith` and
+`stringEndsWith`. `not`, `in`, `notIn`, `startsWith` and `endsWith` are refused
+with `TURBINE_E003` listing the accepted set (the last two point at their
+`string*` spelling); express `not` / `in` with `NOT` / `OR` around the path
+filter instead.
+
+`groupBy` accepts a JSON path as a grouping key via `{ field, path }`, and its
+`_sum`, `_avg`, `_min` and `_max` accept the same `{ field, path }` object under
+an alias key: `_sum: { score: { field: 'tastingNotes', path: ['panel', 'score'] } }`
+comes back as `_sum.score`. `_sum` / `_avg` cast the value to numeric; `_min` /
+`_max` compare as text unless `type: 'numeric'`. **`aggregate()` has no JSON-path
+form**: every key there must be a column (anything else is `TURBINE_E003`) and
+every value `true`; an object value is read as `true`, so the whole column
+reaches the database as `avg(jsonb)` and fails there with a database error, not
+a Turbine code. **`_count` never takes a path**, in `groupBy` or `aggregate()`:
+an object under a `_count` key is read as `true` (a count of that column's
+non-null values) and any path in it is ignored. To count per JSON value, group
+by the path and read `_count`.
 
 ## Aggregates
 
@@ -192,6 +206,11 @@ await db.ripeningChecks.aggregate({
 });
 ```
 
+`_sum` / `_avg` over an `int8` / `bigint` or `numeric` / `decimal` column return
+PostgreSQL's exact text as a **string** (every value, not only large ones; `AVG`
+is not float-cast there); over `int4` / `float` columns and over a JSON path they
+return a number. `_min` / `_max` return the column's own type.
+
 ## groupBy and having
 
 `by` lists the grouping columns. The `having` shape is **column first, aggregate
@@ -219,13 +238,21 @@ where: { guildId_batchRef: { guildId: 4, batchRef: 'WB-0007' } }
 where: { guildId: 4, batchRef: 'WB-0007' }              // equivalent
 ```
 
+## Single-row writes carry the same rule
+
+`update`, `delete` and `upsert` each require a `where` that identifies one row,
+by the same rule as `findUnique`, and anything else is `TURBINE_E003` naming the
+keys that would work. For an upsert the `where` **is** the `ON CONFLICT` target,
+so a non-unique predicate is refused rather than sent. Use `updateMany` and
+`deleteMany` for "every row matching a filter".
+
 ## `distinct`
 
 `distinct: ['status']` de-duplicates on those columns.
 
 ## Errors worth branching on
 
-Every error extends `TurbineError` and carries a stable `code`. The ones a query
+Every error Turbine raises extends `TurbineError` and carries a stable `code`; an unmapped driver SQLSTATE stays the driver's error, with that SQLSTATE on `.code`. The ones a query
 produces:
 
 | code | class | means |