@blamejs/core 0.14.27 → 0.15.1

package/lib/db-query.js

@@ -17,6 +17,20 @@
  *                   updateOne(changes), updateMany(changes),
  *                   deleteOne(), deleteMany().
  *
+ * SQL construction composes b.sql (lib/sql.js): every terminal builds a
+ * b.sql verb builder ({ dialect: "sqlite" }, the local node:sqlite
+ * backend), replays the recorded structured WHERE conditions onto it, and
+ * calls .toSql() for the { sql, params } pair — which db-query then
+ * prepares + runs on the local sqlite handle. b.sql owns identifier
+ * quoting (through b.safeSql), value binding (every value a `?`
+ * placeholder), IN-list expansion, LIKE auto-escape, and the output
+ * validator (_assertEmittable). db-query keeps everything b.sql cannot
+ * know about: the residency write-gate, sealed-row seal/unseal, _id
+ * auto-generation, per-row-key materialization, the column-membership
+ * gate, sealed-field → derived-hash translation, and the JSONB/JSON-path
+ * value guard — all applied at condition-record / row-build time, before
+ * the structured shape reaches b.sql.
+ *
  * Sealed-field semantics:
  *   - On insert/update, sealed columns are vault.seal()'d and their derived
  *     hashes computed automatically.
@@ -33,6 +47,7 @@ var { generateToken } = require("./crypto");
 var safeJson = require("./safe-json");
 var safeJsonPath = require("./safe-jsonpath");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var audit = require("./audit");
 var lazyRequire = require("./lazy-require");
 var { DbQueryError } = require("./framework-error");
@@ -195,8 +210,15 @@ class Query {
     this._schema        = schema;
     this._table         = table;
     this._qualifiedKey  = schema ? schema + "." + table : table;
-    this._where         = [];
-    this._whereParams   = [];
+    // Recorded WHERE chain — an ordered list of leaves. Each leaf is
+    // { joiner, apply(predicate) } where apply() replays the leaf onto a
+    // b.sql Predicate (or builder) using its where-family methods. The
+    // sealed-field translation, JSONB value guard, and column-membership
+    // gate run at record time (in _addCondition / whereRaw / search /
+    // whereGroup / orWhere), so the recorded shape is already safe; the
+    // terminal just replays it through b.sql, which owns quoting +
+    // binding + the output validator.
+    this._conditions    = [];
     this._select        = null;
     this._orderBy       = null;
     this._limit         = null;
@@ -215,6 +237,16 @@ class Query {
       : (Array.isArray(opts.declaredColumns) ? new Set(opts.declaredColumns) : null);
     this._columnGateMode  = opts.columnGateMode || "reject";
     this._allowedColumns  = null;
+    // PRIMARY KEY column for the dialect-aware single-row write idiom on
+    // non-sqlite handles (sqlite uses the implicit rowid). db.from() tables
+    // key on `_id`; a table with a different PK declares it here. Validated
+    // as an identifier so it can splice into SQL as a quoted column.
+    if (opts.primaryKey !== undefined && opts.primaryKey !== null) {
+      safeSql.validateIdentifier(opts.primaryKey, { allowReserved: true });
+      this._primaryKey = opts.primaryKey;
+    } else {
+      this._primaryKey = null;
+    }
   }
 
   // Restrict the operator-allowable columns to an explicit subset
@@ -259,11 +291,55 @@ class Query {
       ". Use .allowedColumns([...]) or db.init({ columnGate: 'off' }) to bypass.");
   }
 
-  // Quoted SQL form: `"schema"."table"` if schema-qualified, else `"table"`.
-  _quotedTable() {
+  // Resolve the SQL dialect for the handle this Query runs against.
+  // db.from() drives the framework's local node:sqlite handle (dialect
+  // "sqlite", the default). An operator who constructs `new Query(handle,
+  // table)` over their OWN Postgres / MySQL handle declares the dialect on
+  // the handle via `handle.dialect` ("postgres" | "mysql"), so b.sql emits
+  // the matching identifier quoting + single-row-write idiom. An unknown /
+  // absent value falls back to "sqlite" — the historical default — so every
+  // existing caller is byte-identical.
+  _dialect() {
+    var d = this._db && this._db.dialect;
+    if (d === "postgres" || d === "mysql" || d === "sqlite") return d;
+    return "sqlite";
+  }
+
+  // The b.sql opts for every terminal's verb builder. The dialect is
+  // resolved from the handle (sqlite by default; the operator's external
+  // handle can declare postgres / mysql). quoteName forces b.sql to QUOTE
+  // the resolved table name: db-query does NO clusterStorage prefix rewrite,
+  // so it never needs the bare-unquoted form — and quoting preserves
+  // db-query's reserved-word / case-sensitive table-name support (`"name"`
+  // is the safe identifier form). The schema qualifier (when present) makes
+  // b.sql emit the quoted `"schema"."table"` form. db-query owns the column
+  // gate (sealed-field rewrite happens before b.sql sees a column), so the
+  // builder's own gate stays off.
+  _sqlOpts() {
     return this._schema
-      ? '"' + this._schema + '"."' + this._table + '"'
-      : '"' + this._table + '"';
+      ? { dialect: this._dialect(), schema: this._schema, quoteName: true }
+      : { dialect: this._dialect(), quoteName: true };
+  }
+
+  // Whether any WHERE condition has been recorded — drives the
+  // unconditional-update / -delete / -increment refusals.
+  _hasConditions() {
+    return this._conditions.length > 0;
+  }
+
+  // Replay the recorded WHERE chain onto a b.sql verb builder. The whole
+  // chain is wrapped in one b.sql whereGroup so the leaves' AND/OR
+  // joiners compose at a single precedence level (and a no-condition
+  // chain leaves the builder's where untouched). Returns the builder.
+  _applyConditions(builder) {
+    if (this._conditions.length === 0) return builder;
+    var conds = this._conditions;
+    builder.whereGroup(function (pred) {
+      for (var i = 0; i < conds.length; i++) {
+        conds[i].apply(pred);
+      }
+    });
+    return builder;
   }
 
   // ---- Chainable filters ----
@@ -283,7 +359,20 @@ class Query {
     return this._addCondition(fieldOrObj, op, value);
   }
 
-  _addCondition(field, op, value) {
+  // whereIn(field, values) — AND an `IN (...)` membership predicate. Facade
+  // over where(field, "IN", values) symmetric with b.sql's whereIn, so a
+  // caller can match a column against a value list (e.g. the dual-read
+  // derived-hash candidate set) without spelling the "IN" operator.
+  whereIn(field, values) {
+    return this.where(field, "IN", values);
+  }
+
+  // Resolve a (field, op, value) predicate through the framework gates
+  // (JSONB value guard, sealed-field → derived-hash rewrite, column
+  // membership) and return the post-rewrite { field, op, value } that
+  // b.sql will emit. Shared by _addCondition and the WhereBuilder so the
+  // gates run identically whether the leaf is top-level or grouped.
+  _resolvePredicate(field, op, value) {
     if (!ALLOWED_OPS.has(op)) {
       throw new Error("invalid where operator: " + op);
     }
@@ -341,45 +430,67 @@ class Query {
         );
       }
       field = lookup.field;
-      value = lookup.value;
+      if (op === "=" && lookup.legacyValue != null && lookup.legacyValue !== lookup.value) {
+        // Dual-read across the v0.15.0 keyed-MAC default flip: a row written
+        // before the flip carries the legacy salted-sha3 digest, so an
+        // equality lookup on a sealed field must match BOTH the active
+        // keyed-MAC digest and the legacy one — otherwise the flip silently
+        // drops every un-migrated row from the result. b.sql expands the
+        // IN-list to (?, ?) and binds each digest.
+        op = "IN";
+        value = [lookup.value, lookup.legacyValue];
+      } else {
+        value = lookup.value;
+      }
     }
-    cryptoField && _validateField(field);
+    _validateField(field);
     // Gate the post-sealed-rewrite physical column (derived-hash
     // columns are declared physical columns, so the rewrite target
     // passes membership).
     this._assertColumnMember(field, "where");
     if (op === "IN") {
-      // node:sqlite ? does not support array-binding. Pre-v0.8.18
-      // `where(field, "IN", [1,2,3])` silently bound the entire
-      // array to a single placeholder and matched zero rows.
-      // Expand to (?, ?, ?) and push each value separately.
+      // node:sqlite ? does not support array-binding; b.sql expands the
+      // IN-list to (?, ?, ?) and binds each element. Validate the shape
+      // here so the failure is db-query's clear message, not a builder
+      // error deeper in the stack.
       if (!Array.isArray(value) || value.length === 0) {
         throw new Error("where IN requires a non-empty array of values");
       }
-      var placeholders = value.map(function () { return "?"; }).join(", ");
-      this._where.push('"' + field + '" IN (' + placeholders + ")");
-      for (var i = 0; i < value.length; i += 1) this._whereParams.push(value[i]);
-      return this;
     }
-    if (op === "LIKE" && typeof value === "string") {
-      // Escape SQL LIKE metacharacters %  and _ in operator-supplied
-      // input. Without this, a single `%` in untrusted input becomes
-      // a wildcard that matches everything — a column-disclosure
-      // class (`q=%@%` enumerates entire table). Use a backslash as
-      // the escape character (uniform across SQLite + Postgres) and
-      // emit the corresponding ESCAPE clause so the engine treats it
-      // as the escape token. Operators who deliberately want LIKE
-      // wildcards in their value bypass via whereRaw().
-      var escaped = value.replace(/[\\%_]/g, "\\$&");
-      this._where.push('"' + field + '" LIKE ? ESCAPE ' + "'\\\\'");
-      this._whereParams.push(escaped);
-      return this;
+    return { field: field, op: op, value: value };
+  }
+
+  // Apply a resolved predicate onto a b.sql Predicate using the given
+  // joiner ("AND" via where* / "OR" via orWhere*). LIKE auto-escape,
+  // IN-list expansion, IS NULL, and JSONB emission are all owned by
+  // b.sql's _cmp from here.
+  _emitPredicate(pred, joiner, field, op, value) {
+    if (op === "IN") {
+      if (joiner === "OR") pred.orWhereIn(field, value);
+      else pred.whereIn(field, value);
+      return;
     }
-    this._where.push('"' + field + '" ' + op + " ?");
-    this._whereParams.push(value);
+    if (joiner === "OR") pred.orWhereOp(field, op, value);
+    else pred.whereOp(field, op, value);
+  }
+
+  _addCondition(field, op, value) {
+    var resolved = this._resolvePredicate(field, op, value);
+    var self = this;
+    this._pushLeaf("AND", function (pred) {
+      self._emitPredicate(pred, "AND", resolved.field, resolved.op, resolved.value);
+    });
     return this;
   }
 
+  // Append a WHERE leaf. `apply(pred)` replays it onto a b.sql Predicate
+  // (AND-joined at the chain level — the leaf's own apply decides AND vs
+  // OR internally). orWhere() rewrites the last leaf rather than
+  // appending, to preserve `(prev OR new)` grouping precedence.
+  _pushLeaf(joiner, apply) {
+    this._conditions.push({ joiner: joiner, apply: apply });
+  }
+
   _isSealedField(field) {
     var sealed = cryptoField.getSealedFields(this._cryptoFieldKey());
     return sealed.indexOf(field) !== -1;
@@ -400,31 +511,35 @@ class Query {
 
   // whereRaw — append a parenthesized raw SQL fragment with positional
   // placeholders and the parameter values that fill them. Composes with
-  // .where() (AND-joined via the same `_where` array). The fragment
-  // must NOT contain operator-supplied SQL — it's caller-controlled
-  // text used to build expressions the chainable .where() can't express
-  // (compound OR, row-value comparison for cursor pagination, etc.).
-  // Placeholder count must match params.length.
-  whereRaw(sql, params, opts) {
-    if (typeof sql !== "string" || sql.length === 0) {
+  // .where() (AND-joined). The fragment must NOT contain operator-
+  // supplied SQL — it's caller-controlled text used to build expressions
+  // the chainable .where() can't express (compound OR, row-value
+  // comparison for cursor pagination, etc.). b.sql's whereRaw guards the
+  // fragment (b.guardSql + embedded-literal + placeholder-count); the
+  // count + literal validation that db-query historically did inline now
+  // lives in that one choke-point.
+  whereRaw(sql_, params, opts) {
+    if (typeof sql_ !== "string" || sql_.length === 0) {
       throw new Error("whereRaw: sql must be a non-empty string");
     }
-    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql, "whereRaw");
-    var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
-    // Count `?` placeholders, but skip occurrences inside string
-    // literals ('...'  or "..."), line comments (-- to EOL), and
-    // block comments (/* ... */). Pre-v0.8.18 the naive regex
-    // counted `?` inside literals (e.g. `WHERE name = 'a?b' AND id
-    // = ?`) which caused mismatched-count errors OR — worse — let
-    // through fragments where the literal-`?` placebo masked a
-    // missed real placeholder.
-    var holders = _countPlaceholders(sql);
+    var p = Array.isArray(params) ? params.slice() : (params == null ? [] : [params]);
+    // Fail-fast at the chain-build boundary (matching the pre-b.sql
+    // contract — the operator catches a bad fragment at the whereRaw call,
+    // not deep inside a terminal). The embedded-literal + placeholder-count
+    // refusals keep db-query's stable SafeSqlError `sql/raw-literal` /
+    // explicit count-mismatch contract; b.sql's whereRaw (applied at the
+    // terminal) is the additional emission-time guard (b.guardSql, stacked-
+    // statement, encoding). allowLiterals opts the operator out of the
+    // literal refusal for a static, operator-controlled literal.
+    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql_, "whereRaw");
+    var holders = safeSql.countPlaceholders(sql_);
     if (holders !== p.length) {
       throw new Error("whereRaw: " + holders + " placeholder(s) in sql but " +
         p.length + " param(s) supplied");
     }
-    this._where.push("(" + sql + ")");
-    for (var i = 0; i < p.length; i++) this._whereParams.push(p[i]);
+    this._pushLeaf("AND", function (pred) {
+      pred.whereRaw(sql_, p, opts);
+    });
     return this;
   }
 
@@ -476,49 +591,46 @@ class Query {
     return this;
   }
 
-  // ---- Build SELECT components ----
-
-  _whereClause() {
-    return this._where.length === 0 ? "" : " WHERE " + this._where.join(" AND ");
-  }
+  // ---- Build SELECT components on a b.sql builder ----
 
-  _orderLimitOffset() {
-    var s = "";
+  // Apply the recorded projection / order / limit / offset onto a b.sql
+  // SELECT builder. Projection columns + orderBy fields already passed
+  // _validateField + the column gate at record time.
+  _applySelectClauses(qb) {
+    if (this._select) qb.columns(this._select);
     if (this._orderBy) {
       var entries = Array.isArray(this._orderBy) ? this._orderBy : [this._orderBy];
-      var fragments = [];
       for (var i = 0; i < entries.length; i++) {
-        fragments.push('"' + entries[i].field + '" ' + entries[i].direction);
+        qb.orderBy(entries[i].field, entries[i].direction === "DESC" ? "desc" : "asc");
       }
-      s += " ORDER BY " + fragments.join(", ");
     }
-    if (this._limit !== null)  s += " LIMIT "  + this._limit;
-    if (this._offset !== null) s += " OFFSET " + this._offset;
-    return s;
-  }
-
-  _projection() {
-    if (!this._select) return "*";
-    return this._select.map(function (c) { return '"' + c + '"'; }).join(", ");
+    if (this._limit !== null)  qb.limit(this._limit);
+    if (this._offset !== null) qb.offset(this._offset);
+    return qb;
   }
 
   // ---- Terminal methods (sync) ----
 
   first() {
-    var sql = "SELECT " + this._projection() + " FROM " + this._quotedTable() +
-              this._whereClause() + this._orderLimitOffset() + " LIMIT 1";
-    var stmt = this._db.prepare(sql);
-    var row = stmt.get.apply(stmt, this._whereParams);
+    var qb = sql.select(this._table, this._sqlOpts());
+    this._applyConditions(qb);
+    this._applySelectClauses(qb);
+    qb.limit(1);
+    var built = qb.toSql();
+    var stmt = this._db.prepare(built.sql);
+    var row = stmt.get.apply(stmt, built.params);
     // 4th arg (dbHandle) lets unsealRow fetch + unwrap the row-scoped
     // K_row for vault.row: cells (declarePerRowKey tables).
     return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row, undefined, this._db) : null;
   }
 
   all() {
-    var sql = "SELECT " + this._projection() + " FROM " + this._quotedTable() +
-              this._whereClause() + this._orderLimitOffset();
-    var stmt = this._db.prepare(sql);
-    var rows = stmt.all.apply(stmt, this._whereParams);
+    var qb = sql.select(this._table, this._sqlOpts());
+    this._applyConditions(qb);
+    this._applySelectClauses(qb);
+    var built = qb.toSql();
+    var stmt = this._db.prepare(built.sql);
+    var rows = stmt.all.apply(stmt, built.params);
     var out = new Array(rows.length);
     var key = this._cryptoFieldKey();
     var dbHandle = this._db;
@@ -535,8 +647,10 @@ class Query {
   // StreamLimit ceiling enforced from the module-level db
   // config; per-call opts.streamLimit overrides for one-off bumps.
   stream(opts) {
-    var sql = "SELECT " + this._projection() + " FROM " + this._quotedTable() +
-              this._whereClause() + this._orderLimitOffset();
+    var qb = sql.select(this._table, this._sqlOpts());
+    this._applyConditions(qb);
+    this._applySelectClauses(qb);
+    var built = qb.toSql();
     var perCallLimit;
     // db.js exports getStreamLimit so this module reads the live
     // ceiling without bouncing through the lib's circular load.
@@ -550,11 +664,11 @@ class Query {
       }
       perCallLimit = opts.streamLimit;
     }
-    var stmt = this._db.prepare(sql);
+    var stmt = this._db.prepare(built.sql);
     var key = this._cryptoFieldKey();
     var dbHandle = this._db;
     var iter;
-    try { iter = stmt.iterate.apply(stmt, this._whereParams); }
+    try { iter = stmt.iterate.apply(stmt, built.params); }
     catch (e) {
       var r = new Readable({ objectMode: true, read: function () {} });
       setImmediate(function () { r.destroy(e); });
@@ -583,9 +697,11 @@ class Query {
   }
 
   count() {
-    var sql = "SELECT COUNT(*) AS n FROM " + this._quotedTable() + this._whereClause();
-    var stmt = this._db.prepare(sql);
-    var row = stmt.get.apply(stmt, this._whereParams);
+    var qb = sql.select(this._table, this._sqlOpts()).count("*", "n");
+    this._applyConditions(qb);
+    var built = qb.toSql();
+    var stmt = this._db.prepare(built.sql);
+    var row = stmt.get.apply(stmt, built.params);
     return row ? row.n : 0;
   }
 
@@ -605,7 +721,7 @@ class Query {
     // (vault.row: cells). rowId MUST be withId._id — the same value
     // b.subject.eraseHard / b.retention destroy on, so a later shred
     // makes these cells undecryptable. Materialize stores the random
-    // row-secret AAD-sealed in _blamejs_per_row_keys.
+    // row-secret AAD-sealed in the per-row-key store.
     var sealOpts;
     var cfKey = this._cryptoFieldKey();
     if (cryptoField.hasPerRowKey(cfKey)) {
@@ -613,13 +729,9 @@ class Query {
       sealOpts = { kRow: kRow, rowId: withId._id };
     }
     var sealed = cryptoField.sealRow(cfKey, withId, sealOpts);
-    var cols = Object.keys(sealed);
-    var placeholders = cols.map(function () { return "?"; }).join(", ");
-    var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
-    var values = cols.map(function (c) { return sealed[c]; });
-    var sql = "INSERT INTO " + this._quotedTable() + " (" + quotedCols + ") VALUES (" + placeholders + ")";
-    var insertStmt = this._db.prepare(sql);
-    insertStmt.run.apply(insertStmt, values);
+    var built = sql.insert(this._table, this._sqlOpts()).values(sealed).toSql();
+    var insertStmt = this._db.prepare(built.sql);
+    insertStmt.run.apply(insertStmt, built.params);
     // Return the original row with _id filled in (plaintext, never sealed)
     return Object.assign({}, withId);
   }
@@ -646,7 +758,7 @@ class Query {
     if (!changes || typeof changes !== "object") {
       throw new Error("update requires a changes object");
     }
-    if (this._where.length === 0) {
+    if (!this._hasConditions()) {
       throw new Error("refusing unconditional update — call where(...) first");
     }
     // Residency gates on the plaintext change set — an UPDATE that
@@ -670,27 +782,106 @@ class Query {
     setKeys.forEach(_validateField);
     var selfUpd = this;
     setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
-    var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
-    var setValues = setKeys.map(function (k) { return sealed[k]; });
 
-    var whereSql = this._where.join(" AND ");
-    var limit = single ? " LIMIT 1" : "";
-    // SQLite supports LIMIT on UPDATE only when compiled with SQLITE_ENABLE_UPDATE_DELETE_LIMIT.
-    // node:sqlite ships without that flag — emulate single-row with a sub-select on rowid.
-    var sql;
-    var qt = this._quotedTable();
+    // No engine ships a portable UPDATE ... LIMIT, so a single-row update
+    // resolves exactly one row then writes it. The shape is dialect-aware
+    // (sqlite rowid sub-select / postgres PK sub-select / mysql
+    // resolve-then-write — _buildSingleRowWrite). A null result means the
+    // WHERE matched no row, so there is nothing to update (0 changes).
+    var built;
     if (single) {
-      sql = "UPDATE " + qt + " SET " + setClause +
-            " WHERE rowid = (SELECT rowid FROM " + qt + " WHERE " + whereSql + " LIMIT 1)";
+      built = this._buildSingleRowWrite(sealed);
+      if (built === null) return 0;
     } else {
-      sql = "UPDATE " + qt + " SET " + setClause + " WHERE " + whereSql + limit;
+      var qb = sql.update(this._table, this._sqlOpts()).set(sealed);
+      this._applyConditions(qb);
+      built = qb.toSql();
     }
-    var allParams = setValues.concat(this._whereParams);
-    var updStmt = this._db.prepare(sql);
-    var info = updStmt.run.apply(updStmt, allParams);
+    var updStmt = this._db.prepare(built.sql);
+    var info = updStmt.run.apply(updStmt, built.params);
     return info.changes;
   }
 
+  // The single-row-write row locator, by dialect. No engine ships
+  // UPDATE ... LIMIT portably (node:sqlite is built without
+  // SQLITE_ENABLE_UPDATE_DELETE_LIMIT), so the single-row idiom is a
+  // sub-SELECT that resolves exactly one row then matches it:
+  //
+  //   sqlite   — the implicit `rowid` system column (every non-WITHOUT-
+  //              ROWID table has one); `WHERE "rowid" = (SELECT "rowid"
+  //              FROM t WHERE ... LIMIT 1)`.
+  //   postgres — the table's PRIMARY KEY (`_id`, the db.from() convention).
+  //              Postgres accepts LIMIT in a scalar subquery, so the same
+  //              `= (SELECT "_id" ... LIMIT 1)` shape works — and using the
+  //              real, UNIQUE `_id` column keeps b.sql's quote-by-
+  //              construction intact (ctid is an unquotable system column
+  //              that would force a raw-identifier escape and is unstable
+  //              across VACUUM).
+  //   mysql    — also the PRIMARY KEY, but MySQL refuses LIMIT in a
+  //              subquery that directly references the same table in an
+  //              `IN`/`=` predicate; wrapping the inner SELECT in a derived
+  //              table (`... IN (SELECT "_id" FROM (SELECT "_id" ... LIMIT
+  //              1) AS _s)`) is the standard work-around.
+  //
+  // The inner SELECT is composed through b.sql (same table + conditions)
+  // and spliced via whereSub — passing the inner BUILDER (not concatenated
+  // SQL) so b.sql concatenates the sub-query's sql + params itself and the
+  // final statement still runs through b.sql's output validator.
+  _rowLocatorColumn(dialect) {
+    return dialect === "sqlite" ? "rowid" : this._pkColumn();
+  }
+
+  // The PRIMARY KEY column for single-row writes on non-sqlite dialects.
+  // db.from() tables key on `_id` (auto-generated when absent on insert);
+  // an operator running a table with a different PK overrides it via the
+  // `primaryKey` construction opt.
+  _pkColumn() {
+    return this._primaryKey || "_id";
+  }
+
+  _buildSingleRowWrite(sealed) {
+    if (this._dialect() === "mysql") {
+      // MySQL forbids referencing the UPDATE/DELETE target table in a
+      // subquery (error 1093), so the single-statement sub-SELECT idiom
+      // the other dialects use is unavailable. Resolve the one row's PK in
+      // a prior SELECT, then write `WHERE pk = ?` with the resolved value
+      // bound — every value still binds, the identifier still quotes by
+      // construction, and the write is a single validated statement with no
+      // self-referential subquery. Returns null when no row matched.
+      var pkVal = this._resolveSinglePk();
+      if (pkVal === null) return null;
+      return sql.update(this._table, this._sqlOpts())
+        .set(sealed)
+        .where(this._pkColumn(), pkVal)
+        .toSql();
+    }
+    var col = this._rowLocatorColumn(this._dialect());
+    var inner = sql.select(this._table, this._sqlOpts()).columns([col]);
+    this._applyConditions(inner);
+    inner.limit(1);
+    return sql.update(this._table, this._sqlOpts())
+      .set(sealed)
+      .whereSub(col, "=", inner)
+      .toSql();
+  }
+
+  // Resolve the PK of exactly one row matching the recorded WHERE (LIMIT
+  // 1). Used by the MySQL single-row write path, where a self-referential
+  // subquery is rejected by the engine. The SELECT is a clean, fully-bound
+  // b.sql statement; returns the PK value, or null when nothing matched.
+  _resolveSinglePk() {
+    var pk = this._pkColumn();
+    var pick = sql.select(this._table, this._sqlOpts()).columns([pk]);
+    this._applyConditions(pick);
+    pick.limit(1);
+    var built = pick.toSql();
+    var stmt = this._db.prepare(built.sql);
+    var row = stmt.get.apply(stmt, built.params);
+    if (!row) return null;
+    var v = row[pk];
+    return (v === undefined || v === null) ? null : v;
+  }
+
   // Per-row-key UPDATE. Sealed columns on a declarePerRowKey table are
   // K_row cells (vault.row:), so each affected row must be re-sealed
   // under its OWN K_row — a single set-based UPDATE can't carry per-row
@@ -699,11 +890,12 @@ class Query {
   // under it (derived hashes computed from plaintext as usual), and
   // UPDATE that single row by _id. `single` stops after the first row.
   _updatePerRowKey(cfKey, changes, single) {
-    var whereSql = this._where.join(" AND ");
-    var qt = this._quotedTable();
-    var idStmt = this._db.prepare(
-      "SELECT _id FROM " + qt + " WHERE " + whereSql + (single ? " LIMIT 1" : ""));
-    var idRows = idStmt.all.apply(idStmt, this._whereParams);
+    var idSelect = sql.select(this._table, this._sqlOpts()).columns(["_id"]);
+    this._applyConditions(idSelect);
+    if (single) idSelect.limit(1);
+    var idBuilt = idSelect.toSql();
+    var idStmt = this._db.prepare(idBuilt.sql);
+    var idRows = idStmt.all.apply(idStmt, idBuilt.params);
     var changed = 0;
     for (var r = 0; r < idRows.length; r++) {
       var rowId = idRows[r]._id;
@@ -717,10 +909,10 @@ class Query {
       setKeys.forEach(_validateField);
       var selfUpd = this;
       setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
-      var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
-      var setValues = setKeys.map(function (k) { return sealed[k]; });
-      var updStmt = this._db.prepare("UPDATE " + qt + " SET " + setClause + " WHERE _id = ?");
-      var info = updStmt.run.apply(updStmt, setValues.concat([rowId]));
+      var built = sql.update(this._table, this._sqlOpts())
+        .set(sealed).where("_id", rowId).toSql();
+      var updStmt = this._db.prepare(built.sql);
+      var info = updStmt.run.apply(updStmt, built.params);
       changed += (info && info.changes) || 0;
     }
     return changed;
@@ -737,9 +929,9 @@ class Query {
   // Atomic counter increment.
   //
   // `from(table).where(filter).increment("col", 1)` emits
-  // `UPDATE table SET col = col + ? WHERE ...` so concurrent writers
-  // can't collide on a fetch/mutate/store sequence (which would lose
-  // increments under racing transactions). Pass a negative delta to
+  // `UPDATE table SET col = COALESCE(col, 0) + ? WHERE ...` so concurrent
+  // writers can't collide on a fetch/mutate/store sequence (which would
+  // lose increments under racing transactions). Pass a negative delta to
   // decrement.
   //
   // Returns the number of rows changed (matches updateMany shape).
@@ -753,19 +945,22 @@ class Query {
     if (typeof delta !== "number" || !Number.isFinite(delta) || !Number.isInteger(delta)) {
       throw new Error("increment(column, delta): delta must be a finite integer (default 1)");
     }
-    if (this._where.length === 0) {
+    if (!this._hasConditions()) {
       throw new Error("refusing unconditional increment — call where(...) first");
     }
-    var whereSql = this._where.join(" AND ");
-    var qt = this._quotedTable();
-    var qc = '"' + column + '"';
     // Use COALESCE so a NULL counter starts at 0 instead of producing
     // NULL + delta = NULL silently (which would silently drop the
-    // operation under SQLite's NULL-arithmetic rules).
-    var sql = "UPDATE " + qt + " SET " + qc + " = COALESCE(" + qc + ", 0) + ? WHERE " + whereSql;
-    var allParams = [delta].concat(this._whereParams);
-    var stmt = this._db.prepare(sql);
-    var info = stmt.run.apply(stmt, allParams);
+    // operation under SQLite's NULL-arithmetic rules). The quoted column
+    // expression is built by b.safeSql under the active dialect so the
+    // increment RHS references the same quoted identifier b.sql's set
+    // target uses (double-quote on sqlite/postgres, backtick on mysql).
+    var qc = safeSql.quoteIdentifier(column, this._dialect(), { allowReserved: true });
+    var qb = sql.update(this._table, this._sqlOpts())
+      .setRaw(column, "COALESCE(" + qc + ", 0) + ?", [delta]);
+    this._applyConditions(qb);
+    var built = qb.toSql();
+    var stmt = this._db.prepare(built.sql);
+    var info = stmt.run.apply(stmt, built.params);
     return info.changes;
   }
 
@@ -785,10 +980,10 @@ class Query {
     }
     var sub = new WhereBuilder(this);
     closure(sub);
-    var built = sub.build();
-    if (!built.sql) return this;
-    this._where.push("(" + built.sql + ")");
-    for (var i = 0; i < built.params.length; i++) this._whereParams.push(built.params[i]);
+    if (sub._parts.length === 0) return this;
+    this._pushLeaf("AND", function (pred) {
+      pred.whereGroup(function (g) { sub.replay(g); });
+    });
     return this;
   }
 
@@ -796,36 +991,61 @@ class Query {
   // `.where(a).orWhere(b)` produces `WHERE (a) OR (b)` rather than
   // `WHERE (a) AND (b)`. Accepts the same arg shapes as `.where`:
   // object-literal map, `(field, value)`, `(field, op, value)`, or a
-  // `(qb) => ...` closure.
+  // `(qb) => ...` closure. Replays as `(prevLeaf OR newLeaf)` so the
+  // grouping precedence matches the pre-b.sql `( prev OR ( new ) )` form.
   orWhere(fieldOrObjOrFn, op, value) {
-    if (this._where.length === 0) {
+    if (this._conditions.length === 0) {
       throw new Error("orWhere(...): no prior where(...) — start the chain with where(...)");
     }
+    var argc = arguments.length;
+    var prevLeaf = this._conditions.pop();
+    var orApply;
     if (typeof fieldOrObjOrFn === "function") {
       var sub = new WhereBuilder(this);
       fieldOrObjOrFn(sub);
-      var built = sub.build();
-      if (!built.sql) return this;
-      var prev = this._where.pop();
-      this._where.push("(" + prev + " OR (" + built.sql + "))");
-      for (var i = 0; i < built.params.length; i++) this._whereParams.push(built.params[i]);
-      return this;
-    }
-    // For non-closure shapes, build a transient single-leaf Query and
-    // splice it. We compile to a `WhereBuilder` for symmetry.
-    var sub2 = new WhereBuilder(this);
-    if (fieldOrObjOrFn !== null && typeof fieldOrObjOrFn === "object" && !Array.isArray(fieldOrObjOrFn)) {
-      Object.keys(fieldOrObjOrFn).forEach(function (k) { sub2.eq(k, fieldOrObjOrFn[k]); });
-    } else if (op === undefined) {
-      sub2.eq(fieldOrObjOrFn, /* value */ arguments[1]);
+      if (sub._parts.length === 0) {
+        // Empty OR closure — restore the prior leaf untouched.
+        this._conditions.push(prevLeaf);
+        return this;
+      }
+      orApply = function (pred) {
+        pred.orWhereGroup(function (g) { sub.replay(g); });
+      };
+    } else if (fieldOrObjOrFn !== null && typeof fieldOrObjOrFn === "object" &&
+               !Array.isArray(fieldOrObjOrFn)) {
+      // Object map — all equalities OR'd as one group leaf.
+      var self = this;
+      var resolvedList = Object.keys(fieldOrObjOrFn).map(function (k) {
+        return self._resolvePredicate(k, "=", fieldOrObjOrFn[k]);
+      });
+      orApply = function (pred) {
+        pred.orWhereGroup(function (g) {
+          for (var i = 0; i < resolvedList.length; i++) {
+            self._emitPredicate(g, "AND", resolvedList[i].field, resolvedList[i].op,
+              resolvedList[i].value);
+          }
+        });
+      };
     } else {
-      sub2._push("AND", fieldOrObjOrFn, op, value);
-    }
-    var built2 = sub2.build();
-    if (!built2.sql) return this;
-    var prev2 = this._where.pop();
-    this._where.push("(" + prev2 + " OR (" + built2.sql + "))");
-    for (var j = 0; j < built2.params.length; j++) this._whereParams.push(built2.params[j]);
+      // 2-arg orWhere(field, value) is the equality shorthand; 3-arg
+      // orWhere(field, op, value) carries an explicit operator. Mirror
+      // .where()'s arguments.length discrimination so a 2-arg value of
+      // (e.g.) the number 5 is never mistaken for an operator.
+      var resolved = (argc === 2)
+        ? this._resolvePredicate(fieldOrObjOrFn, "=", op)
+        : this._resolvePredicate(fieldOrObjOrFn, op, value);
+      var selfP = this;
+      orApply = function (pred) {
+        selfP._emitPredicate(pred, "OR", resolved.field, resolved.op, resolved.value);
+      };
+    }
+    // Re-push a single leaf that emits ( prevLeaf OR newLeaf ).
+    this._pushLeaf("AND", function (pred) {
+      pred.whereGroup(function (g) {
+        prevLeaf.apply(g);
+        orApply(g);
+      });
+    });
     return this;
   }
 
@@ -851,22 +1071,24 @@ class Query {
     }
     if (term.length === 0) return this;
     var match = (opts && opts.match) || "substring";
-    // Escape the operator's term so SQL LIKE wildcards in user input
-    // don't widen the match. Use `~` as the ESCAPE char (SQLite's
-    // ESCAPE clause requires a single character — picking `~` rather
-    // than `\` avoids JS-string-literal escaping headaches; `~` rarely
-    // appears in user-supplied search terms).
-    var escaped = String(term).replace(/[~%_]/g, function (c) { return "~" + c; });
-    var pattern;
-    if (match === "exact")        pattern = escaped;
-    else if (match === "prefix")  pattern = escaped + "%";
-    else if (match === "substring") pattern = "%" + escaped + "%";
-    else throw new Error("search: opts.match must be 'substring' | 'prefix' | 'exact'");
-    var clauses = fields.map(function (f) { return '"' + f + '" LIKE ? ESCAPE \'~\''; });
-    var sql = "(" + clauses.join(" OR ") + ")";
-    var params = fields.map(function () { return pattern; });
-    this._where.push(sql);
-    for (var i = 0; i < params.length; i++) this._whereParams.push(params[i]);
+    if (match !== "exact" && match !== "prefix" && match !== "substring") {
+      throw new Error("search: opts.match must be 'substring' | 'prefix' | 'exact'");
+    }
+    // b.sql's whereLike owns the wildcard handling end-to-end: it escapes
+    // the user's `%` / `_` metacharacters with `~`, adds the LIVE wrapping
+    // wildcard per mode, and emits `"field" LIKE ? ESCAPE '~'` (a
+    // builder-emitted ESCAPE clause, so no raw-fragment guard refusal). An
+    // OR group across every search field; the first leaf leads, the rest
+    // OR-join.
+    var fieldList = fields.slice();
+    this._pushLeaf("AND", function (pred) {
+      pred.whereGroup(function (g) {
+        for (var i = 0; i < fieldList.length; i++) {
+          if (i === 0) g.whereLike(fieldList[i], term, match);
+          else g.orWhereLike(fieldList[i], term, match);
+        }
+      });
+    });
     return this;
   }
 
@@ -907,20 +1129,41 @@ class Query {
   }
 
   _delete(single) {
-    if (this._where.length === 0) {
+    if (!this._hasConditions()) {
       throw new Error("refusing unconditional delete — call where(...) first");
     }
-    var whereSql = this._where.join(" AND ");
-    var sql;
-    var qt = this._quotedTable();
+    var built;
     if (single) {
-      sql = "DELETE FROM " + qt +
-            " WHERE rowid = (SELECT rowid FROM " + qt + " WHERE " + whereSql + " LIMIT 1)";
+      // No engine ships a portable DELETE ... LIMIT, so single-row delete
+      // mirrors the single-row update idiom: sqlite splices a rowid
+      // sub-select, postgres a PK sub-select (both via b.sql whereSub, the
+      // inner builder object — b.sql concatenates the sub-query's sql +
+      // params, no hand-rolled string), and mysql resolves the one PK in a
+      // prior SELECT then deletes `WHERE pk = ?` (the engine forbids a
+      // subquery referencing the DELETE target table). A null PK means the
+      // WHERE matched nothing — 0 rows deleted.
+      if (this._dialect() === "mysql") {
+        var pkVal = this._resolveSinglePk();
+        if (pkVal === null) return 0;
+        built = sql.delete(this._table, this._sqlOpts())
+          .where(this._pkColumn(), pkVal)
+          .toSql();
+      } else {
+        var col = this._rowLocatorColumn(this._dialect());
+        var inner = sql.select(this._table, this._sqlOpts()).columns([col]);
+        this._applyConditions(inner);
+        inner.limit(1);
+        built = sql.delete(this._table, this._sqlOpts())
+          .whereSub(col, "=", inner)
+          .toSql();
+      }
     } else {
-      sql = "DELETE FROM " + qt + " WHERE " + whereSql;
+      var dqb = sql.delete(this._table, this._sqlOpts());
+      this._applyConditions(dqb);
+      built = dqb.toSql();
     }
-    var delStmt = this._db.prepare(sql);
-    var info = delStmt.run.apply(delStmt, this._whereParams);
+    var delStmt = this._db.prepare(built.sql);
+    var info = delStmt.run.apply(delStmt, built.params);
     return info.changes;
   }
 }
@@ -934,11 +1177,13 @@ class Query {
 // `.orGte` / `.orLt` / `.orLte` / `.orIn` / `.orLike` ORs an
 // expression. `.raw(sql, params)` AND's an arbitrary fragment.
 //
-// `.build()` returns `{ sql, params }`. Empty builder → `{ sql: "",
-// params: [] }`.
+// Each part is recorded structurally ({ joiner, kind, ... }) and replayed
+// onto a b.sql Predicate via replay(pred) — b.sql owns the quoting +
+// binding + LIKE escape + IN-list expansion. The owning Query runs the
+// column-membership gate as each part is recorded.
 class WhereBuilder {
   constructor(gate) {
-    this._parts = [];   // [{ joiner: "AND"|"OR", sql: "...", params: [...] }]
+    this._parts = [];   // [{ joiner, kind: "cmp"|"raw", ... }]
     // The owning Query, so grouped/OR sub-expressions enforce the
     // same column-membership gate as the top-level chain.
     this._gate = gate || null;
@@ -949,19 +1194,17 @@ class WhereBuilder {
     }
     _validateField(field);
     if (this._gate) this._gate._assertColumnMember(field, "whereGroup");
-    var qf = '"' + field + '"';
     if (op === "IN" || op === "NOT IN") {
       if (!Array.isArray(value) || value.length === 0) {
         throw new Error("WhereBuilder: " + op + " requires a non-empty array of values");
       }
-      var placeholders = value.map(function () { return "?"; }).join(", ");
-      this._parts.push({ joiner: joiner, sql: qf + " " + op + " (" + placeholders + ")", params: value.slice() });
+      this._parts.push({ joiner: joiner, kind: "cmp", field: field, op: op, value: value.slice() });
       return this;
     }
-    if (!ALLOWED_OPS.has(op)) {
+    if (!ALLOWED_OPS.has(op) && op !== "NOT IN") {
       throw new Error("WhereBuilder: invalid operator '" + op + "'");
     }
-    this._parts.push({ joiner: joiner, sql: qf + " " + op + " ?", params: [value] });
+    this._parts.push({ joiner: joiner, kind: "cmp", field: field, op: op, value: value });
     return this;
   }
   eq(f, v)   { return this._push("AND", f, "=",  v); }
@@ -980,56 +1223,67 @@ class WhereBuilder {
   orLte(f, v)  { return this._push("OR", f, "<=", v); }
   orIn(f, vs)  { return this._push("OR", f, "IN", vs); }
   orLike(f, v) { return this._push("OR", f, "LIKE", v); }
-  raw(sql, params, opts) {
-    if (typeof sql !== "string" || sql.length === 0) {
+  raw(sql_, params, opts) {
+    if (typeof sql_ !== "string" || sql_.length === 0) {
       throw new Error("WhereBuilder.raw: sql must be a non-empty string");
     }
-    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql, "WhereBuilder.raw");
-    var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
-    if (_countPlaceholders(sql) !== p.length) {
+    var p = Array.isArray(params) ? params.slice() : (params == null ? [] : [params]);
+    // Same fail-fast literal + placeholder-count contract as Query.whereRaw
+    // (stable SafeSqlError code); b.sql re-guards at the terminal.
+    if (!(opts && opts.allowLiterals === true)) _assertRawNoStringLiteral(sql_, "WhereBuilder.raw");
+    if (safeSql.countPlaceholders(sql_) !== p.length) {
       throw new Error("WhereBuilder.raw: placeholder count mismatch");
     }
-    this._parts.push({ joiner: "AND", sql: "(" + sql + ")", params: p });
+    this._parts.push({ joiner: "AND", kind: "raw", sql: sql_, params: p, opts: opts });
     return this;
   }
+  // Replay the recorded parts onto a b.sql Predicate. The first part
+  // leads the group (its joiner is the group's first leaf); each later
+  // part AND/OR-joins per its recorded joiner. b.sql performs identifier
+  // quoting, value binding, and IN-list expansion.
+  replay(pred) {
+    for (var i = 0; i < this._parts.length; i++) {
+      _replayPart(pred, this._parts[i], this._parts[i].joiner === "OR" && i > 0);
+    }
+  }
   build() {
+    // Back-compat shim for any external reader that called build() to get
+    // a { sql, params } pair. Replay onto a transient b.sql SELECT's
+    // predicate and extract. Returns { sql: "", params: [] } when empty.
     if (this._parts.length === 0) return { sql: "", params: [] };
-    var sql = this._parts[0].sql;
-    var params = this._parts[0].params.slice();
-    for (var i = 1; i < this._parts.length; i += 1) {
-      sql = sql + " " + this._parts[i].joiner + " " + this._parts[i].sql;
-      for (var j = 0; j < this._parts[i].params.length; j += 1) {
-        params.push(this._parts[i].params[j]);
-      }
-    }
-    return { sql: sql, params: params };
+    var self = this;
+    var built = sql.select("t", { dialect: "sqlite" })
+      .whereGroup(function (g) { self.replay(g); })
+      .toSql();
+    // Strip the "SELECT * FROM t WHERE (" prefix + trailing ")".
+    var m = /WHERE \((.*)\)$/.exec(built.sql);
+    return { sql: m ? m[1] : "", params: built.params };
   }
 }
 
-// Count `?` placeholders outside string literals + comments.
-// Tracks SQL single-quoted, double-quoted, line-comment, and block-
-// comment state to avoid counting `?` characters that are part of
-// literal text the SQL engine never interprets as a binding marker.
-// Refuse raw SQL fragments that embed a single-quoted string
-// literal. A whereRaw / WhereBuilder.raw fragment is meant to be a
-// STATIC template whose every value is bound through a `?` placeholder;
-// an embedded `'...'` literal is the signature of operator input
-// concatenated into the query (CWE-89 / CWE-564 — concat into a
-// query builder). Double-quoted identifiers (`"col"`), line comments,
+// Refuse a raw SQL fragment that embeds a single-quoted string literal.
+// A whereRaw / WhereBuilder.raw fragment is a STATIC template whose every
+// value binds through a `?` placeholder; an embedded `'...'` literal is
+// the signature of operator input concatenated into the query builder
+// (CWE-89 / CWE-564). Double-quoted identifiers (`"col"`), line comments,
 // and block comments are skipped. Operators with a deliberate static
-// literal pass `{ allowLiterals: true }`. Shares the quote/comment
-// scanning shape with _countPlaceholders.
-function _assertRawNoStringLiteral(sql, where) {
+// literal pass `{ allowLiterals: true }`. db-query runs this eagerly at
+// the chain-build boundary so the operator-facing `sql/raw-literal`
+// SafeSqlError contract is stable; b.sql's whereRaw re-guards the same
+// fragment at the terminal (b.guardSql + the emission-time validator).
+// Single linear pass, no backtracking regex; shares the scan shape with
+// b.safeSql.countPlaceholders.
+function _assertRawNoStringLiteral(rawSql, where) {
   var i = 0;
-  var len = sql.length;
+  var len = rawSql.length;
   while (i < len) {
-    var ch = sql.charAt(i);
-    var next = i + 1 < len ? sql.charAt(i + 1) : "";
+    var ch = rawSql.charAt(i);
+    var next = i + 1 < len ? rawSql.charAt(i + 1) : "";
     if (ch === '"') {
       i += 1;
       while (i < len) {
-        if (sql.charAt(i) === '"') {
-          if (sql.charAt(i + 1) === '"') { i += 2; continue; }
+        if (rawSql.charAt(i) === '"') {
+          if (rawSql.charAt(i + 1) === '"') { i += 2; continue; }
           i += 1; break;
         }
         i += 1;
@@ -1037,12 +1291,12 @@ function _assertRawNoStringLiteral(sql, where) {
       continue;
     }
     if (ch === "-" && next === "-") {
-      while (i < len && sql.charAt(i) !== "\n") i += 1;
+      while (i < len && rawSql.charAt(i) !== "\n") i += 1;
       continue;
     }
     if (ch === "/" && next === "*") {
       i += 2;
-      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
+      while (i < len && !(rawSql.charAt(i) === "*" && rawSql.charAt(i + 1) === "/")) i += 1;
       i += 2;
       continue;
     }
@@ -1057,40 +1311,47 @@ function _assertRawNoStringLiteral(sql, where) {
   }
 }
 
-function _countPlaceholders(sql) {
-  var count = 0;
-  var i = 0;
-  var len = sql.length;
-  while (i < len) {
-    var ch = sql.charAt(i);
-    var next = i + 1 < len ? sql.charAt(i + 1) : "";
-    if (ch === "'" || ch === '"') {
-      var quote = ch;
-      i += 1;
-      while (i < len) {
-        if (sql.charAt(i) === quote) {
-          // SQL doubles the quote char to escape it within a literal.
-          if (sql.charAt(i + 1) === quote) { i += 2; continue; }
-          i += 1; break;
-        }
-        i += 1;
-      }
-      continue;
-    }
-    if (ch === "-" && next === "-") {
-      while (i < len && sql.charAt(i) !== "\n") i += 1;
-      continue;
-    }
-    if (ch === "/" && next === "*") {
-      i += 2;
-      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
-      i += 2;
-      continue;
-    }
-    if (ch === "?") count += 1;
-    i += 1;
+// Apply one recorded WhereBuilder part onto a b.sql Predicate. `or`
+// selects the OR-joining method (after the first leaf in a group); the
+// first leaf ignores its joiner (it leads the group). NOT IN and LIKE
+// are the two ops with a behavior the bare structured Predicate does not
+// expose 1:1: NOT IN has no orWhere* form, and the WhereBuilder LIKE is a
+// caller-controlled-wildcard LIKE (the value binds verbatim — no
+// auto-escape, matching the pre-b.sql WhereBuilder semantics, distinct
+// from .search() which escapes). Both compose through the guarded raw /
+// group surface without weakening anything.
+function _replayPart(pred, part, or) {
+  if (part.kind === "raw") {
+    if (or) pred.orWhereRaw(part.sql, part.params, part.opts);
+    else pred.whereRaw(part.sql, part.params, part.opts);
+    return;
+  }
+  if (part.op === "LIKE") {
+    // Verbatim LIKE — caller controls the wildcards (no escape clause),
+    // exactly as the pre-migration WhereBuilder emitted `"f" LIKE ?`. The
+    // identifier quoting follows the predicate's OWN dialect (the builder
+    // it replays onto), so the LIKE column matches the surrounding query's
+    // quoting on mysql (backtick) as well as sqlite/postgres (double-quote).
+    var likeDialect = (pred && typeof pred._dialect === "function") ? pred._dialect() : "sqlite";
+    var likeSql = safeSql.quoteIdentifier(part.field, likeDialect, { allowReserved: true }) + " LIKE ?";
+    if (or) pred.orWhereRaw(likeSql, [part.value]);
+    else pred.whereRaw(likeSql, [part.value]);
+    return;
+  }
+  if (part.op === "IN") {
+    if (or) pred.orWhereIn(part.field, part.value);
+    else pred.whereIn(part.field, part.value);
+    return;
+  }
+  if (part.op === "NOT IN") {
+    // b.sql exposes no orWhereNotIn; emit an OR NOT-IN leaf as a
+    // single-member OR group so the join precedence is preserved.
+    if (or) pred.orWhereGroup(function (g) { g.whereNotIn(part.field, part.value); });
+    else pred.whereNotIn(part.field, part.value);
+    return;
   }
-  return count;
+  if (or) pred.orWhereOp(part.field, part.op, part.value);
+  else pred.whereOp(part.field, part.op, part.value);
 }
 
 function _validateField(field) {