turbine-orm 0.81.0 → 0.90.0

package/dist/typed-sql.d.ts

@@ -19,7 +19,9 @@
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
- *     get a runtime value into the query is via `${...}`, which we bind.
+ *     get a runtime value into the query is via `${...}`, which we bind. A
+ *     plain array passed where the template belongs is refused at runtime
+ *     ({@link assertTemplateStrings}).
  *
  *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
  *     existing `client.raw()` behavior: a typed raw query is a literal escape
@@ -49,6 +51,7 @@
  */
 import type { PgCompatPool } from './client.js';
 import { type Dialect } from './dialect.js';
+import { type TurbineLogger } from './logger.js';
 import type { QueryEvent } from './query/deferred.js';
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
@@ -61,10 +64,37 @@ import type { QueryEvent } from './query/deferred.js';
  *
  * Exported for unit testing the parameterization invariant without a database.
  */
-export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[], dialect?: Pick<Dialect, 'paramPlaceholder'>): {
+export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[], dialect?: Pick<Dialect, 'paramPlaceholder'>, api?: string): {
     sql: string;
     params: unknown[];
 };
+/**
+ * Refuse a "template" that did not come from a tagged-template call.
+ *
+ * Only the static segments of a template reach the SQL text, and that is safe
+ * because the compiler wrote them. A plain array passed in their place (a
+ * JSON-parsed request field, a string split by hand) puts its text into the
+ * SQL with nothing escaped. A real `TemplateStringsArray` is frozen and carries
+ * a frozen `raw` array of the same length; `JSON.parse` and array literals
+ * produce neither.
+ *
+ * `unsafeApi` names the method that takes statement text instead, for the
+ * error message.
+ */
+export declare function assertTemplateStrings(strings: unknown, api: string, unsafeApi?: string): asserts strings is TemplateStringsArray;
+/**
+ * Raw-statement params with every `Date` (in arrays too) bound as UTC text,
+ * for a client reading zone-less temporal types as UTC (`utcTimestamps`).
+ *
+ * node-postgres renders a Date in the process's zone with its offset. A
+ * `timestamptz` keeps the instant either way, but a `timestamp` or `date`
+ * drops the offset and stores the local wall time, which then reads back
+ * shifted by the process offset. UTC text stores the instant's UTC fields,
+ * which is what a UTC read returns. Returns `params` itself when it holds no
+ * Date. An Invalid Date is refused (E003) instead of reaching the server as
+ * unparseable text.
+ */
+export declare function utcDateParams(params: unknown[], api: string): unknown[];
 /**
  * A pending typed raw SQL query. Implements the thenable contract, so it can be
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
@@ -100,6 +130,8 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * built outside a client, which then emits nothing, as before.
      */
     private readonly onQuery?;
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    private readonly logger;
     constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -120,7 +152,9 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
      * built outside a client, which then emits nothing, as before.
      */
-    onQuery?: ((event: QueryEvent) => void) | undefined);
+    onQuery?: ((event: QueryEvent) => void) | undefined, 
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    logger?: TurbineLogger);
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     private run;
     /**

package/dist/typed-sql.js

@@ -19,7 +19,9 @@
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
- *     get a runtime value into the query is via `${...}`, which we bind.
+ *     get a runtime value into the query is via `${...}`, which we bind. A
+ *     plain array passed where the template belongs is refused at runtime
+ *     ({@link assertTemplateStrings}).
  *
  *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
  *     existing `client.raw()` behavior: a typed raw query is a literal escape
@@ -49,6 +51,7 @@
  */
 import { postgresDialect } from './dialect.js';
 import { ValidationError, wrapPgError } from './errors.js';
+import { consoleLogger, logTo } from './logger.js';
 import { rawIdentity, runReportedStatement } from './query-events.js';
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
@@ -61,11 +64,10 @@ import { rawIdentity, runReportedStatement } from './query-events.js';
  *
  * Exported for unit testing the parameterization invariant without a database.
  */
-export function buildTypedSql(strings, values, dialect = postgresDialect) {
-    // The tagged-template API guarantees `strings.length === values.length + 1`.
-    // Guard the directly-callable (exported) surface so a mismatched call can't
-    // silently desync placeholders from params (pg would reject it, but fail
-    // loudly here instead).
+export function buildTypedSql(strings, values, dialect = postgresDialect, api = 'sql') {
+    assertTemplateStrings(strings, api);
+    // A tagged template always has `strings.length === values.length + 1`; a
+    // hand-built frozen one may not, and would desync placeholders from params.
     if (strings.length !== values.length + 1) {
         throw new ValidationError(`sql template segment/value count mismatch: ${strings.length} segments, ${values.length} values.`);
     }
@@ -78,6 +80,92 @@ export function buildTypedSql(strings, values, dialect = postgresDialect) {
     }
     return { sql, params: values.slice() };
 }
+/**
+ * Refuse a "template" that did not come from a tagged-template call.
+ *
+ * Only the static segments of a template reach the SQL text, and that is safe
+ * because the compiler wrote them. A plain array passed in their place (a
+ * JSON-parsed request field, a string split by hand) puts its text into the
+ * SQL with nothing escaped. A real `TemplateStringsArray` is frozen and carries
+ * a frozen `raw` array of the same length; `JSON.parse` and array literals
+ * produce neither.
+ *
+ * `unsafeApi` names the method that takes statement text instead, for the
+ * error message.
+ */
+export function assertTemplateStrings(strings, api, unsafeApi = 'rawUnsafe') {
+    if (Array.isArray(strings) && Object.isFrozen(strings)) {
+        const raw = strings.raw;
+        if (Array.isArray(raw) && Object.isFrozen(raw) && raw.length === strings.length) {
+            if (strings.every((s) => typeof s === 'string'))
+                return;
+            throw new ValidationError(`${api}: a segment of the template contains an invalid escape sequence, so it has no text. ` +
+                'Fix the escape (write a literal backslash as `\\\\`).');
+        }
+    }
+    const received = Array.isArray(strings) ? 'a plain array' : strings === null ? 'null' : typeof strings;
+    throw new ValidationError(`${api} must be called as a tagged template, for example ${api}\`SELECT * FROM users WHERE id = \${id}\`, ` +
+        `so that every interpolated value is sent as a bound parameter. It received ${received} instead, whose ` +
+        'text would reach the SQL unescaped. To run statement text built at runtime (DDL, a migration file), use ' +
+        `\`${unsafeApi}(text, ...values)\` and keep untrusted input out of the text.`);
+}
+/**
+ * A `Date` in the form node-postgres sends under `parseInputDatesAsUTC`:
+ * `YYYY-MM-DDTHH:MM:SS.mmm+00:00`, with ` BC` for years before 1.
+ */
+function utcDateText(date) {
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    let year = date.getUTCFullYear();
+    const bc = year < 1;
+    if (bc)
+        year = 1 - year;
+    return (`${pad(year, 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}` +
+        `T${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}` +
+        `.${pad(date.getUTCMilliseconds(), 3)}+00:00${bc ? ' BC' : ''}`);
+}
+function utcDateValue(value, api, position, nested) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new ValidationError(`${api}: parameter $${position} ${nested ? 'contains' : 'is'} an Invalid Date, which has no SQL value. ` +
+                'Pass a valid Date, or null for SQL NULL.');
+        }
+        return utcDateText(value);
+    }
+    if (!Array.isArray(value))
+        return value;
+    let out;
+    for (let i = 0; i < value.length; i++) {
+        const converted = utcDateValue(value[i], api, position, true);
+        if (converted !== value[i]) {
+            out ??= value.slice();
+            out[i] = converted;
+        }
+    }
+    return out ?? value;
+}
+/**
+ * Raw-statement params with every `Date` (in arrays too) bound as UTC text,
+ * for a client reading zone-less temporal types as UTC (`utcTimestamps`).
+ *
+ * node-postgres renders a Date in the process's zone with its offset. A
+ * `timestamptz` keeps the instant either way, but a `timestamp` or `date`
+ * drops the offset and stores the local wall time, which then reads back
+ * shifted by the process offset. UTC text stores the instant's UTC fields,
+ * which is what a UTC read returns. Returns `params` itself when it holds no
+ * Date. An Invalid Date is refused (E003) instead of reaching the server as
+ * unparseable text.
+ */
+export function utcDateParams(params, api) {
+    let out;
+    for (let i = 0; i < params.length; i++) {
+        const converted = utcDateValue(params[i], api, i + 1, false);
+        if (converted !== params[i]) {
+            out ??= params.slice();
+            out[i] = converted;
+        }
+    }
+    return out ?? params;
+}
 /**
  * A pending typed raw SQL query. Implements the thenable contract, so it can be
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
@@ -95,6 +183,7 @@ export class TypedSqlQuery {
     logging;
     runScoped;
     onQuery;
+    logger;
     constructor(pool, sql, params, logging, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -115,19 +204,22 @@ export class TypedSqlQuery {
      * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
      * built outside a client, which then emits nothing, as before.
      */
-    onQuery) {
+    onQuery, 
+    /** Where the `logging` preview line goes. Defaults to the console logger. */
+    logger = consoleLogger) {
         this.pool = pool;
         this.sql = sql;
         this.params = params;
         this.logging = logging;
         this.runScoped = runScoped;
         this.onQuery = onQuery;
+        this.logger = logger;
     }
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     run() {
         return this.runScoped(async () => {
             if (this.logging) {
-                console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
+                logTo(this.logger, 'debug', `Typed SQL: ${this.sql.trim().substring(0, 120)}...`, { code: 'typed-sql' });
             }
             const result = await runReportedStatement(this.onQuery, rawIdentity('sql'), this.sql, this.params, () => this.pool.query(this.sql, this.params), wrapPgError);
             return result.rows;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.81.0",
+  "version": "0.90.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).",
@@ -139,9 +139,9 @@
     "//check:coverage-sync": "The three-way coupling between a coverage collection and the floors that hold it. A file can be added to coverage:cli:collect and then be held by NOTHING, which is not a missing gate but a slower lane enforcing a floor of zero, and it has happened twice (mcp.ts and error-catalog.ts each spent a release that way). The invariant is that every file in the collection is named by a per-file gate OR by the aggregate, NOT that the collection and the aggregate are equal: cli/index.ts is deliberately outside the aggregate, see //coverage:cli:gate:aggregate. It also refuses a gate that names a file nobody collects, which measures nothing and passes, and it fails closed on an empty parse. It runs FIRST in test:coverage:cli, ahead of the collection, because it needs no coverage data and its failure names the missing wiring instead of a number.",
     "check:coverage-sync": "node scripts/check-coverage-gate-sync.mjs",
     "//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",
+    "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:local-server-guard && npm run coverage:cli:gate:observe && 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 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: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 --include src/cli/local-server-guard.ts --include src/cli/observe.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/migrations-pure.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 src/test/codegen-cli-destructive.test.ts src/test/codegen-cli-config.test.ts src/test/security-perimeter-local-servers.test.ts src/test/security-perimeter-mcp-secret-names.test.ts src/test/observe-cli.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",
@@ -153,6 +153,9 @@
     "coverage:cli:gate:error-catalog": "npm run coverage:cli:gate -- --include src/cli/error-catalog.ts --lines 100 --statements 100 --branches 90 --functions 100",
     "//coverage:cli:gate:index": "cli/index.ts is the largest file in the repo (5,945 lines) and was in no coverage gate at all. The .c8rc.json //cli-gate argument for the other CLI files applies verbatim: coverage could fall to zero without anything noticing. The floors are LOW on purpose and are not a target: this file is argument parsing and command dispatch whose `process.exit` paths dominate any figure set over it, and the point of the gate is that the number cannot fall silently, not that it is high. MEASURED 2026-08-23 by `npm run coverage:cli:collect` (no database), read from the json-summary reporter rather than the text table, per the //cli-gate-measurements note: 32.62 lines / 32.62 statements / 75.62 branches / 20 functions, identical in isolation and in the nine-file collection. Floors sit about two points under. Raise as coverage improves; never lower one without recording why. It is deliberately NOT in coverage:cli:gate:aggregate, see that key's note.",
     "coverage:cli:gate:index": "npm run coverage:cli:gate -- --include src/cli/index.ts --lines 30 --statements 30 --branches 73 --functions 18",
+    "coverage:cli:gate:local-server-guard": "npm run coverage:cli:gate -- --include src/cli/local-server-guard.ts --lines 100 --statements 100 --branches 96 --functions 100",
+    "//coverage:cli:gate:observe": "cli/observe.ts is the read-only metrics dashboard behind `turbine observe`: a loopback HTTP server with its own session token, one-time login ticket, Host allowlist, Origin check, rate limit and CSP, in front of two queries that run in read-only transactions. It was in no coverage gate at all (about 48 percent of lines were executed by the suites that happened to touch it), while Studio, which shares its perimeter, was. Floors MEASURED 2026-10-13 by `npm run coverage:cli:collect`, read from the json-summary reporter: 100 lines / 100 statements / 99.13 branches / 100 functions. THE COLLECTION BLANKS DATABASE_URL, so the figures are the no-database ones: the live-Postgres tests in observe-cli.test.ts skip here and are not counted, and with a database the figure is 99.14 branches and otherwise identical. That is by design: the fake pool and the fake Postgres wire server in that file reach every line without a database. The one uncovered branch is the non-Error arm of the server's 500 handler (`String(err)`), which a real pg pool never produces. Floors sit 2 points under. Held by this per-file gate only and NOT listed in coverage:cli:gate:aggregate, the same arrangement as local-server-guard.ts: that aggregate was baselined over the larger files and adding a 100 percent file would only move it. Raise as coverage improves; never lower one without recording why.",
+    "coverage:cli:gate:observe": "npm run coverage:cli:gate -- --include src/cli/observe.ts --lines 98 --statements 98 --branches 97 --functions 98",
     "coverage:cli:gate:studio": "npm run coverage:cli:gate -- --include src/cli/studio.ts --lines 82 --statements 82 --branches 81 --functions 86",
     "coverage:cli:gate:migrate": "npm run coverage:cli:gate -- --include src/cli/migrate.ts --lines 69 --statements 69 --branches 91 --functions 73",
     "//coverage:cli:gate:aggregate": "Re-baselined 2026-08-15 when compile-query.ts joined the --include list: measured 89.28 lines / 89.28 statements / 86.77 branches / 89.18 functions, up from a 87/87/85/86 floor set over seven files (itself up from 78/78/84/82 over five). Raise as coverage improves, never lower one without recording why. WHY cli/index.ts IS NOT HERE, although it is in coverage:cli:collect and has its own per-file gate: it is 5,945 lines at 32.62%, so folding it in drops this aggregate from a measured 89.63 lines / 87.15 branches / 89.18 functions to 66.32 / 85.76 / 63.38, which would mean LOWERING two floors by about 25 points. That is the rule above broken, and it also empties the aggregate of its purpose. This check exists only as the backstop that catches every file sagging together inside its individual margin; with one 5,945-line file at 32% dominating the denominator, the other eight could collectively shed well over a thousand covered lines with this still green. The invariant the collection actually needs is that every collected file is held by SOME floor, and index.ts is held by coverage:cli:gate:index. That is what check:coverage-sync asserts.",
@@ -209,7 +212,7 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@swc/core": "1.16.2",
-    "@types/node": "^26.1.0",
+    "@types/node": "^22.20.4",
     "@types/pg": "^8.11.11",
     "@zvndev/powdb-client": "^0.20.0",
     "@zvndev/powdb-embedded": "^0.20.0",

package/skills/turbine-orm/SKILL.md

@@ -101,6 +101,16 @@ Operators: `equals`, `not`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`,
 `startsWith`, `endsWith`, plus `mode: 'insensitive'`. `AND`, `OR` and `NOT` nest
 at any depth; `AND` and `OR` take arrays.
 
+`not` also takes an operator object: `givenName: { not: { contains: 'Roux' } }`.
+To compare two columns, wrap the other one in `col()`, imported from
+`turbine-orm`: `rindScore: { gt: col('aromaScore') }`. A plain `{ col: 'x' }`
+object is refused with `TURBINE_E003`, and so is an operand that does not fit
+its operator, such as an array for `equals` or `null` for `gt`.
+
+A key whose value is `undefined` is left out, as in Prisma. When that empties
+the whole `where`, `findFirst` throws `TURBINE_E003` instead of returning an
+arbitrary row.
+
 Values are always bound as parameters, and `contains` / `startsWith` /
 `endsWith` escape LIKE wildcards for you. There is no code path in the typed API
 that concatenates a value into SQL.
@@ -160,7 +170,10 @@ them. Passing both spellings of one bound with different values throws.
 { take: 20, skip: 40 }
 ```
 
-For deep pages, prefer a `cursor` over a large `offset`.
+For deep pages, prefer a `cursor` over a large `offset`. A cursor names the
+last row you have by a unique key, `cursor: { id: 41 }`; the page excludes that
+row and continues in the query's `orderBy`, with the primary key added as a
+tiebreaker.
 
 ## JSON columns
 
@@ -174,8 +187,11 @@ where: { credentialBlob: { path: ['tier'], equals: 'master' } }
 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
+`equals` at a path compares JSON values, so `equals: null` matches a JSON
+`null` and not the string `"null"`. Without a `path`, `equals` compares the
+whole document exactly. `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
@@ -189,8 +205,9 @@ 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()`:
+reaches the database as `avg(jsonb)`, which the database refuses. That surfaces
+as `TURBINE_E003` with `sqlstate` `42883`, not as a Turbine check naming the
+path. **`_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`.
@@ -211,6 +228,11 @@ 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.
 
+`_percentile: { aromaScore: { p: 0.9 } }` returns the 90th percentile, on
+PostgreSQL only. `p` may be an array of fractions, and the result is then an
+array in the same order. The default `method: 'cont'` interpolates and is
+refused on a date column with `TURBINE_E003`; use `method: 'disc'` there.
+
 ## groupBy and having
 
 `by` lists the grouping columns. The `having` shape is **column first, aggregate
@@ -247,7 +269,35 @@ the `ON CONFLICT` target when `create` carries the same values, so a non-unique
 predicate is refused rather than sent. When `create` does not carry them (a
 `create` that leaves `id` to its sequence, say), `upsert` looks the row up by
 `where` first, inside a transaction. Use `updateMany` and `deleteMany` for
-"every row matching a filter".
+"every row matching a filter". They take no `limit`, `take`, `offset` or `skip`
+(`TURBINE_E003`): to write a bounded batch, `findMany` the ids first, then pass
+`where: { id: { in: ids } }`.
+
+## Computed updates and bulk upserts
+
+To set a column from the row's own values, build the value with `expr` and
+`col()`, both imported from `turbine-orm`:
+
+```ts
+await db.cheeseWheels.update({
+  where: { id: 7 },
+  data: { wheelCount: expr.add(col('wheelCount'), 1) },
+});
+```
+
+A plain object shaped like an expression (`{ kind: 'add', args: [1, 2] }`) is
+refused with `TURBINE_E003`, and so is an expression in `create` data.
+
+`createMany` with `onConflict: { target: ['guildId', 'batchRef'], update:
+['status'] }` inserts the new keys and updates the rows that already exist. The
+target must be the primary key or one whole unique key; any other column list
+is refused with `TURBINE_E003`.
+
+## Locking rows
+
+`lock: 'update'` on `findMany`, `findFirst` or `findUnique` locks the rows it
+returns until the transaction ends. It must run on the `tx` inside
+`db.$transaction(async (tx) => ...)`; on `db` it throws `TURBINE_E003`.
 
 ## `distinct`