@bakery-framework/orm 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/field.ts

@@ -7,7 +7,7 @@ import type * as SyncTypes from './sync/types'
  *
  * The former `value()` primitive, now private and two arguments shorter.
  * `autoIncrement` and `primary` were positional booleans that only
- * `Field.Primary()` ever set, and it can state them directly — which is the
+ * `Field.Primary()` ever set, and it can state them directly, which is the
  * whole reason `value('integer', undefined, false, true, true)` was worth
  * replacing.
  *
@@ -27,7 +27,7 @@ function column<T, N extends boolean = false, O extends boolean = false>(
   if (nullable === true || d === null) result.nullable = true
   // The runtime object is byte-for-byte what it was before `TableDef` changed
   // shape: `type` holds the dialect name, `optional` is type-level only. That
-  // is the whole safety argument for this change — no adapter, no generated
+  // is the whole safety argument for this change: no adapter, no generated
   // file and no stored ledger payload sees any difference.
   return result as unknown as TableDef<T, N, O>
 }
@@ -52,9 +52,9 @@ const isColumnValue = (v: unknown): v is ColumnValue =>
 /**
  * Resolve either calling convention to `{ table, cols }`.
  *
- * The string form — `Field.Index('posts', ['authorId'])` — cannot catch a typo
- * in either argument until sync time, if then. The column form —
- * `Field.Index(posts.authorId)` — carries its own table, so that argument
+ * The string form: `Field.Index('posts', ['authorId'])`: cannot catch a typo
+ * in either argument until sync time, if then. The column form:
+ * `Field.Index(posts.authorId)`: carries its own table, so that argument
  * disappears and a mistake becomes a compile error.
  */
 function resolveTarget(
@@ -86,8 +86,8 @@ export interface ForeignKeyActions {
 /**
  * The shape `Field.Foreign()` contributes to a row type.
  *
- * Always `integer`, because that is what `Field.Primary()` always is — an
- * `INTEGER PRIMARY KEY AUTOINCREMENT` — and a foreign key exists to point at
+ * Always `integer`, because that is what `Field.Primary()` always is (an
+ * `INTEGER PRIMARY KEY AUTOINCREMENT`), and a foreign key exists to point at
  * one. Nullable adds `| null`, which is the only variation worth having.
  *
  * The runtime object still resolves its type from the referenced column (see
@@ -102,14 +102,14 @@ type ForeignDef<N extends true | undefined> = TableDef<
   N extends true ? true : false
 >
 
-/** What `Field.Index` / `Field.Unique` accept — a column produced by `table()`. */
+/** What `Field.Index` / `Field.Unique` accept: a column produced by `table()`. */
 type ColumnValue = { __table: string; __column: string }
 
 /**
  * What `Field.Enum` accepts: a literal array, or a TypeScript string enum.
  *
  * A string enum is an ordinary object at runtime (`{ Draft: 'draft' }`), so
- * both forms reduce to the same list of members — `Object.values` for the
+ * both forms reduce to the same list of members, `Object.values` for the
  * object, the tuple itself for the array.
  *
  * **String enums only.** A *numeric* enum compiles to an object with a reverse
@@ -127,7 +127,7 @@ type EnumValues<V> = V extends readonly (infer U extends string)[]
   : V[keyof V]
 
 /**
- * `Field` — the column vocabulary, namespaced so it is discoverable.
+ * `Field`: the column vocabulary, namespaced so it is discoverable.
  *
  * This replaced `value('string', null, true, false, false)`, which required
  * remembering a type string *and* the meaning of four positional booleans.
@@ -137,8 +137,8 @@ type EnumValues<V> = V extends readonly (infer U extends string)[]
  * **`Field` is now the whole vocabulary, not sugar over one.** `value`,
  * `primary`, `index`, `unique` and `foreign` are gone; the construction they
  * did lives in `column()` and `resolveTarget()` above, private to this file.
- * What the sync engine and the type inference consume is unchanged — plain
- * descriptor objects — so this moved the API without moving the contract.
+ * What the sync engine and the type inference consume is unchanged (plain
+ * descriptor objects), so this moved the API without moving the contract.
  *
  * The one shape deliberately left unspellable is **nullable *and* defaulted to
  * something other than null**, because a null default is how you say nullable.
@@ -158,7 +158,7 @@ type EnumValues<V> = V extends readonly (infer U extends string)[]
  */
 export const Field = {
   /**
-   * `INTEGER PRIMARY KEY AUTOINCREMENT` — the id column, spelled once.
+   * `INTEGER PRIMARY KEY AUTOINCREMENT`: the id column, spelled once.
    *
    * The single most repeated line in any schema, and the one most likely to be
    * written wrong by hand: `value('integer', undefined, false, true, true)`.
@@ -185,7 +185,7 @@ export const Field = {
     >('integer', d),
 
   /**
-   * A fractional number — `DOUBLE` on MySQL, `DOUBLE PRECISION` on Postgres,
+   * A fractional number: `DOUBLE` on MySQL, `DOUBLE PRECISION` on Postgres,
    * `REAL` on SQLite.
    *
    * Named `Float` rather than mirroring the underlying `'number'` type string,
@@ -208,12 +208,12 @@ export const Field = {
     >('string', d),
 
   /**
-   * Unbounded text — `TEXT` on every dialect.
+   * Unbounded text: `TEXT` on every dialect.
    *
    * **MySQL rejects a literal `DEFAULT` on TEXT**, so this takes no default.
    * That is not an omission: `Field.String('')` emits
    * `TEXT NOT NULL DEFAULT ''`, which MySQL refuses outright with "BLOB, TEXT,
-   * GEOMETRY or JSON column can't have a default value" — the shipped schema
+   * GEOMETRY or JSON column can't have a default value", the shipped schema
    * template could not `db:sync` against MySQL because of exactly this. Use
    * `Varchar` when you need a default.
    */
@@ -227,18 +227,27 @@ export const Field = {
   },
 
   /**
-   * Sized text — `VARCHAR(n)`, and the answer to TEXT's default problem, since
+   * Sized text: `VARCHAR(n)`, and the answer to TEXT's default problem, since
    * every dialect accepts a default on a sized column.
    *
    *     slug: Field.Varchar(255, ''),
    *
-   * SQLite has no real `VARCHAR` — all text is TEXT affinity — but it stores
+   * SQLite has no real `VARCHAR` (all text is TEXT affinity), but it stores
    * the declared type verbatim and reads it back, so one schema round-trips on
    * all three.
    *
-   * `length` is not part of the column diff, so **widening a Varchar does not
-   * migrate on its own**; see `ColumnConstraint.length` for why that is
-   * deliberate rather than missing.
+   * **`length` *is* part of the column diff** (`sync/diff.ts`), so adopting
+   * `Varchar` on an existing table rebuilds it once. That is deliberate and
+   * it converges: all three dialects report a VARCHAR width back exactly, so
+   * after one rebuild the two agree and the table stays synced. A column that
+   * reports no width really is unsized, and a schema that declares no width
+   * asks for nothing.
+   *
+   * This comment claimed the opposite until 2026-09-20, and it is the comment
+   * a schema author reads when deciding whether the change is safe. Measured
+   * on a real app: switching 12 tables' text columns to `Varchar` moved
+   * `db:sync` from "perfectly synced" to a 12-table rebuild, and the second
+   * sync was clean.
    */
   Varchar: <D extends string | null | undefined = undefined>(
     length: number,
@@ -254,7 +263,7 @@ export const Field = {
     ),
 
   /**
-   * A 64-bit integer — `BIGINT` everywhere.
+   * A 64-bit integer: `BIGINT` everywhere.
    *
    * Reads back as a **string** on MySQL and Postgres, which is how they avoid
    * losing precision, and as a **number** on SQLite, which does not: values
@@ -269,11 +278,11 @@ export const Field = {
     >('bigint' as any, d),
 
   /**
-   * A JSON document — `JSON` on MySQL, `JSONB` on Postgres, a `JSON`-declared
+   * A JSON document: `JSON` on MySQL, `JSONB` on Postgres, a `JSON`-declared
    * text column on SQLite.
    *
    * MySQL and Postgres parse it into an object on read; SQLite hands back the
-   * raw string. The row type is therefore `unknown` — narrow it where you use
+   * raw string. The row type is therefore `unknown`: narrow it where you use
    * it rather than trusting a type that would be wrong on one of the three.
    *
    * Takes no default, for the same reason `Text` does not: MySQL refuses a
@@ -286,7 +295,7 @@ export const Field = {
     (nullable: true): TableDef<unknown, true, true>
   },
 
-  /** True/false — `BOOLEAN` on Postgres, `TINYINT(1)` on MySQL. */
+  /** True/false: `BOOLEAN` on Postgres, `TINYINT(1)` on MySQL. */
   Bool: <D extends boolean | null | undefined = undefined>(d?: D) =>
     column<
       Nullable<boolean, D extends null ? true : false>,
@@ -312,8 +321,8 @@ export const Field = {
    *
    * **The column's type is copied from the target, not declared here**, and
    * that is the real reason to prefer this form. MySQL refuses a foreign key
-   * whose column type does not match the referenced key *exactly* — an
-   * `INT` child against a `BIGINT` parent is rejected outright — and that
+   * whose column type does not match the referenced key *exactly* (an
+   * `INT` child against a `BIGINT` parent is rejected outright), and that
    * mismatch is invisible in a schema where the two columns are declared pages
    * apart. Resolution happens in `resolveColumnForeignKeys()`, where the whole
    * schema is in scope, so the two cannot disagree.
@@ -332,11 +341,11 @@ export const Field = {
       } = {},
     ) =>
       ({
-        // `integer` in the row type, always — see `ForeignDef`. At *runtime* the
+        // `integer` in the row type, always. See `ForeignDef`. At *runtime* the
         // type is still overwritten from the referenced column by
         // `resolveColumnForeignKeys()`, because MySQL refuses a key whose column
-        // type does not match the target exactly. For the ordinary case — a key
-        // pointing at a `Field.Primary()` — the two agree and there is nothing to
+        // type does not match the target exactly. For the ordinary case: a key
+        // pointing at a `Field.Primary()`: the two agree and there is nothing to
         // reconcile.
         type: 'integer',
         ...(options.nullable ? { nullable: true, default: null } : {}),
@@ -429,7 +438,7 @@ export const Field = {
    * The column form carries its own table, so there is no separate table
    * argument to get wrong; the string form exists because the `DBInfo`
    * namespace layout has no `table()` values to point at. Several columns make
-   * one composite index, in the order given — which is the order that decides
+   * one composite index, in the order given, which is the order that decides
    * which queries it can serve.
    *
    * A direct alias of `index()` rather than a wrapper, so the two cannot drift
@@ -460,7 +469,7 @@ export const Field = {
   },
 
   /**
-   * A UUID, generated by the database — `CHAR(36)` sized text with a
+   * A UUID, generated by the database: `CHAR(36)` sized text with a
    * per-dialect default expression.
    *
    *     id: Field.Uuid(),
@@ -468,7 +477,7 @@ export const Field = {
    * `gen_random_uuid()` on Postgres, `UUID()` on MySQL, and
    * `lower(hex(randomblob(16)))` shaped into the canonical form on SQLite,
    * which has no UUID function of its own. All three round-trip through the
-   * `%uuid%` marker, the same way `Field.Date.now()` round-trips `%dateNow%` —
+   * `%uuid%` marker, the same way `Field.Date.now()` round-trips `%dateNow%`,
    * without the read-back half the database reports its own expression, the
    * schema says `%uuid%`, and the column rebuilds on every sync forever.
    *
@@ -496,13 +505,19 @@ export const Field = {
    *
    * Enforced in the database too, and **the same way on all three dialects**:
    * a `CHECK (col IN (…))`. MySQL has a native `ENUM` and this deliberately
-   * does not use it — a value rejected by MySQL and accepted by SQLite means
+   * does not use it: a value rejected by MySQL and accepted by SQLite means
    * an app that behaves differently depending on where it runs, which is worse
    * than either choice made consistently.
    *
-   * The members are **not part of the column diff** — see
-   * `ColumnConstraint._enum`. Adding or removing one does not migrate on its
-   * own; the table has to be rebuilt for the CHECK to change.
+   * **The members join the column diff when the current state came from the
+   * ledger**, so changing them migrates rather than silently doing nothing.
+   * Under introspection they stay out of it, because all three dialects
+   * report a CHECK back in a different shape and Postgres re-renders it
+   * entirely: three parsers, three chances to rebuild the table on every sync
+   * forever. `sync/diff.ts` has the measured shapes.
+   *
+   * So adopting `Enum` on an existing ledger-tracked table rebuilds it once.
+   * This comment said the members were never diffed until 2026-09-20.
    */
   Enum: <
     const V extends EnumSource,
@@ -520,7 +535,7 @@ export const Field = {
       throws(
         'Field.Enum() takes a string enum or an array of strings. A numeric ' +
           'enum reverse-maps its members, so its values are half names and ' +
-          'half numbers — use Field.Int() and validate in your code, or give ' +
+          'half numbers. Use Field.Int() and validate in your code, or give ' +
           'the enum string values.',
       )
     }
@@ -555,7 +570,7 @@ export const Field = {
    * **`updatedAt` is not auto-maintained on write, and that is a deliberate
    * limit rather than an oversight.** Doing it silently needs the query layer
    * to know which tables have the column, and the query layer has no runtime
-   * view of the schema at all — `schema.ts` is loaded by the sync engine, not
+   * view of the schema at all: `schema.ts` is loaded by the sync engine, not
    * by the ORM. The alternatives were a `hasCol` probe on every UPDATE, or
    * stamping a column that might not exist. Stamp it yourself:
    *
@@ -570,7 +585,7 @@ export const Field = {
    * The current time as Unix **seconds**, for a value position.
    *
    * A plain number, so it binds as an ordinary parameter and needs no dialect
-   * handling — unlike `%dateNow%`, which is a DDL default marker and means
+   * handling: unlike `%dateNow%`, which is a DDL default marker and means
    * nothing in an INSERT or UPDATE.
    */
   now: () => Math.floor(Date.now() / 1000),

package/src/globals.d.ts

@@ -4,7 +4,7 @@ import type { AppDBOptionals, AppDBSchema } from './schema-registry'
  * Ambient database types.
  *
  * These live with the orm package rather than in core's `global.d.ts`: they are
- * derived from this package's schema registry, and core cannot reference orm —
+ * derived from this package's schema registry, and core cannot reference orm,
  * orm depends on core, so the reverse would be circular.
  *
  * Both are read only inside this package (`orm/query.ts`, `orm/mutation.ts`,

package/src/index.ts

@@ -12,7 +12,7 @@ export type {
  *
  * Re-exported from the root rather than given a `./observe` subpath. The
  * export map is closed and every entry in it is public API from the moment it
- * ships, so a new subpath needs a reason — and there is none here: this is one
+ * ships, so a new subpath needs a reason, and there is none here: this is one
  * function and three types, the observer is process-wide, and an app sets it
  * once at boot next to where it already imports `DB`.
  *
@@ -34,15 +34,15 @@ export type {
  * Schema authoring, from one place.
  *
  * `table`/`alias` live in `define.ts` and the column and constraint helpers in
- * `schema-util.ts`, but that split is an implementation detail — someone
+ * `schema-util.ts`, but that split is an implementation detail: someone
  * writing `orm/schema.ts` should import from `@bakery-framework/orm` without having to
  * know which file a helper happens to sit in.
  */
 export { alias, table, view } from './define'
 export { Field } from './field'
 /**
- * `TableDef` is the **column** descriptor — `TableDef<TYPE, nullable, optional>`
- * — and it now comes from the root barrel, which is where someone writing a
+ * `TableDef` is the **column** descriptor (`TableDef<TYPE, nullable, optional>`
+ *), and it now comes from the root barrel, which is where someone writing a
  * schema would look for it.
  *
  * It did not, and that was a defect rather than an omission: the barrel used to

package/src/orm/index.ts

@@ -8,14 +8,14 @@
  *
  * `./query` first works. `./mutation` first does not: `mutation.ts` pulls in
  * `query.ts`, whose top-level `Mutation.Insert` runs while `Mutation` is still
- * initialising, and the whole ORM dies with
+ * initializing, and the whole ORM dies with
  * `TypeError: undefined is not an object (evaluating 'Mutation.Insert')`.
  *
  * Biome's `organizeImports` sorts these alphabetically and puts `./mutation`
  * first. The compiler cannot see the breakage, because the types are fine
  * either way. Hence the suppression.
  */
-// biome-ignore-all assist/source/organizeImports: cycle — see above
+// biome-ignore-all assist/source/organizeImports: cycle. See above
 import { DB } from './query'
 import { Mutation } from './mutation'
 

package/src/orm/mutation.ts

@@ -7,7 +7,7 @@ import type {
   AppDBOptionals as DBOptionals,
   AppDBSchema as DBSchema,
 } from '../schema-registry'
-import { evalOperands, qId } from '../schema-util'
+import { evalOperands, nullComparison, qId } from '../schema-util'
 import { DB } from './query'
 
 export namespace Mutation {
@@ -16,7 +16,7 @@ export namespace Mutation {
    *
    * There used to be a `| (string & {})` member here, for autocomplete on the
    * literals while still accepting any string. It also made the rest of the
-   * type decorative — `Exclude<…, AppViews>` never rejected anything, so a
+   * type decorative: `Exclude<…, AppViews>` never rejected anything, so a
    * `DB.Insert.into('some_view')` compiled and failed at the database instead,
    * and so did a typo'd table name.
    *
@@ -36,7 +36,7 @@ export namespace Mutation {
   export type Prettify<T> = { [K in keyof T]: T[K] } & {}
 
   /**
-   * `RETURNING` takes an identifier list and is interpolated, not bound — the
+   * `RETURNING` takes an identifier list and is interpolated, not bound: the
    * same position `orderBy` and `groupBy` guard with `safeColumn`. It was the
    * one identifier writer on Insert/Update/Delete with no guard at all, so
    * `.returning('* FROM users; DROP TABLE t --')` was emitted verbatim.
@@ -71,10 +71,10 @@ export namespace Mutation {
     : string
 
   /**
-   * What a write returns — the adapter's own result, not a copy of it.
+   * What a write returns: the adapter's own result, not a copy of it.
    *
    * It *was* a copy: an identical `{lastInsertRowid, changes}` declared here as
-   * well as on `SQLAdapter`. Identical today is the whole problem — that is the
+   * well as on `SQLAdapter`. Identical today is the whole problem: that is the
    * state `SQLAdapter.ColumnConstraint` was in before it fell behind
    * `sync/types.ts` and started erasing fields at the cast.
    */
@@ -87,14 +87,14 @@ export namespace Mutation {
     }
 
     /**
-     * The rows to insert — as a spread, or as one array.
+     * The rows to insert: as a spread, or as one array.
      *
      * Both forms exist because the variadic signature alone made the obvious
      * call wrong in a way nothing announced: `values(rows)` bound the *array*
      * as a single record, and the only symptom was
      * `table big has no column named 0`. An array is never a record, so the two
-     * forms cannot be confused, and anything that is neither — a mixed
-     * `values(rows, extra)`, a primitive — is rejected by name rather than
+     * forms cannot be confused, and anything that is neither (a mixed
+     * `values(rows, extra)`, a primitive) is rejected by name rather than
      * turned into columns called `0` and `1`.
      */
     values(records: InsertSchema<T>[]): InsertExecutable
@@ -115,7 +115,7 @@ export namespace Mutation {
             'values() takes records: values(row), values(rowA, rowB) or ' +
               'values(rows). Got a ' +
               (Array.isArray(record) ? 'nested array' : typeof record) +
-              ' — if you meant to pass an array of rows, pass it as the only ' +
+              ': if you meant to pass an array of rows, pass it as the only ' +
               'argument.',
           )
         }
@@ -142,7 +142,7 @@ export namespace Mutation {
     /**
      * Insert, or update the row that is already there.
      *
-     * `cols` names the unique columns that decide "already there" — a primary
+     * `cols` names the unique columns that decide "already there": a primary
      * key or a unique index. Without an upsert the only way to express this is
      * to check and then branch, which is a **race**: two requests both see no
      * row and both insert.
@@ -150,8 +150,8 @@ export namespace Mutation {
      *     DB.Insert.into('users').values({ email, name }).upsert(['email'])
      *
      * By default every inserted column except the conflict columns is
-     * overwritten. Pass a second argument to narrow that — `upsert(['email'],
-     * ['name'])` leaves everything else as it was — or an empty array for
+     * overwritten. Pass a second argument to narrow that (`upsert(['email'],
+     * ['name'])` leaves everything else as it was), or an empty array for
      * insert-if-absent, which becomes `DO NOTHING`.
      *
      * MySQL ignores `cols` because `ON DUPLICATE KEY UPDATE` fires on *any*
@@ -180,7 +180,7 @@ export namespace Mutation {
      * How many records fit in one statement, under the adapter's ceiling.
      *
      * The ceiling comes from the adapter because only it knows its dialect, but
-     * a statement can be *rendered* without a connection — `parse()` is how the
+     * a statement can be *rendered* without a connection: `parse()` is how the
      * tests read the SQL, and the stub adapter in `orm.test.ts` implements two
      * members. An unreachable or silent adapter falls back to the same default
      * the base class publishes rather than making `parse()` require a database.
@@ -222,7 +222,7 @@ export namespace Mutation {
     }
 
     /**
-     * The insert as one statement per batch — the form the executors run.
+     * The insert as one statement per batch: the form the executors run.
      *
      * A single `INSERT … VALUES (…),(…),…` carries three parameters per row, so
      * it stops being a legal statement somewhere around eleven thousand rows.
@@ -233,15 +233,15 @@ export namespace Mutation {
      * like for an arbitrary `rows`.
      *
      * The column list is computed once, across every record, so every batch
-     * inserts the same columns in the same order — a per-batch union would
+     * inserts the same columns in the same order: a per-batch union would
      * change the shape of the statement halfway through the insert.
      *
      * **`RETURNING` is accumulated, not refused.** Refusing is the
      * safe-looking option and the wrong one: the batches run sequentially
      * inside one transaction, so concatenating each batch's rows in batch order
      * reproduces the sequence a single statement would have produced. Ordering
-     * *within* a batch is whatever the dialect gives — Postgres does not
-     * promise `RETURNING` follows `VALUES` order — but that is equally true
+     * *within* a batch is whatever the dialect gives (Postgres does not
+     * promise `RETURNING` follows `VALUES` order), but that is equally true
      * unchunked, so batching neither adds nor removes a guarantee. Refusing
      * would have cost the main reason to write `.values(rows).returning('id')`
      * at all: getting the generated ids of a bulk import back.
@@ -288,7 +288,7 @@ export namespace Mutation {
      *
      * The transaction is what keeps a batched insert meaning what the unbatched
      * one meant: all rows or none. It is opened only when a batch boundary
-     * exists — one statement is already atomic — and only when the caller is
+     * exists (one statement is already atomic), and only when the caller is
      * not already inside `DB.transaction`, where the outer transaction is
      * already the atomic unit.
      *
@@ -329,7 +329,7 @@ export namespace Mutation {
      * Two shapes, not three: Postgres and SQLite share
      * `ON CONFLICT (…) DO UPDATE SET col = excluded.col`, while MySQL spells it
      * `ON DUPLICATE KEY UPDATE col = VALUES(col)` and takes no conflict target
-     * at all — it fires on whichever unique key was violated.
+     * at all, it fires on whichever unique key was violated.
      *
      * Every identifier goes through `qId`, and no value is interpolated: the
      * new row's values are already bound as the INSERT's parameters, and both
@@ -345,7 +345,7 @@ export namespace Mutation {
       ).filter(k => insertedKeys.includes(k))
 
       // The adapter spells it. This used to branch on `driver === 'mysql'`
-      // here, which put one dialect's syntax in the shared query builder — the
+      // here, which put one dialect's syntax in the shared query builder: the
       // thing every other difference (quote character, placeholder ceiling,
       // date expression, foreign-key clause) is kept out of it for.
       return getActiveDb().upsertClause(cols, targets)
@@ -362,7 +362,7 @@ export namespace Mutation {
     }
 
     async fetch<R = any>(): Promise<R | undefined> {
-      // Every batch still runs — `fetch()` means "insert, and hand me a row
+      // Every batch still runs: `fetch()` means "insert, and hand me a row
       // back", not "insert the first batch". `Executor.get` is defined as
       // `all(…)[0]`, so this is the same row it would have produced.
       const rows = await this.array<R>()
@@ -381,7 +381,7 @@ export namespace Mutation {
       const changes = results.reduce((n, r) => n + Number(r?.changes ?? 0), 0)
       // `changes` sums, because it answers "how many rows did this insert
       // write". `lastInsertRowid` cannot sum, and the dialects do not agree
-      // what it means for a multi-row insert — so the adapter says which end of
+      // what it means for a multi-row insert, so the adapter says which end of
       // the batched run carries its answer, rather than this file knowing.
       const pick =
         getActiveDb().batchInsertIdPosition === 'first'
@@ -475,8 +475,12 @@ export namespace Mutation {
         if (c.operator === '') {
           parts.push(i === 0 ? left : `${c.connector} ${left}`)
         } else {
-          const right = evalOperands(c.right, params, c.isRightColumn)
-          const clauseStr = `${left} ${c.operator} ${right}`
+          // `nullComparison` before `evalOperands`, and the order is the point:
+          // a null that becomes `IS NULL` must not also bind a parameter.
+          const nullOp = nullComparison(c.operator, c.right, c.isRightColumn)
+          const clauseStr = nullOp
+            ? `${left} ${nullOp}`
+            : `${left} ${c.operator} ${evalOperands(c.right, params, c.isRightColumn)}`
           parts.push(i === 0 ? clauseStr : `${c.connector} ${clauseStr}`)
         }
       }
@@ -618,8 +622,8 @@ export namespace Mutation {
       for (let i = 0; i < this._clauses.length; i++) {
         const c = this._clauses[i]!
         const left = evalOperands(c.left, params, true)
-        // `parseWhereArgs` emits `operator: ''` for the one-argument form —
-        // `where(DB.raw`…`)` or `where(<subquery>)` — where the left operand
+        // `parseWhereArgs` emits `operator: ''` for the one-argument form,
+        // `where(DB.raw`…`)` or `where(<subquery>)`, where the left operand
         // is the whole condition and there is no right one. This branch is a
         // copy of `UpdateExecutable.evalWhere` above, which is a copy of
         // `formatClause` in query.ts; it was the copy that never got it. The
@@ -630,8 +634,12 @@ export namespace Mutation {
         if (c.operator === '') {
           parts.push(i === 0 ? left : `${c.connector} ${left}`)
         } else {
-          const right = evalOperands(c.right, params, c.isRightColumn)
-          const clauseStr = `${left} ${c.operator} ${right}`
+          // `nullComparison` before `evalOperands`, and the order is the point:
+          // a null that becomes `IS NULL` must not also bind a parameter.
+          const nullOp = nullComparison(c.operator, c.right, c.isRightColumn)
+          const clauseStr = nullOp
+            ? `${left} ${nullOp}`
+            : `${left} ${c.operator} ${evalOperands(c.right, params, c.isRightColumn)}`
           parts.push(i === 0 ? clauseStr : `${c.connector} ${clauseStr}`)
         }
       }