@blamejs/blamejs-shop 0.4.31 → 0.4.32

package/lib/vendor/blamejs/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,7 +47,124 @@ 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");
+
+// Circular load — db.js requires db-query at module scope, so the
+// residency gate reaches back for getDataResidency() lazily.
+var db = lazyRequire(function () { return require("./db"); });
+
+// Cross-border regulated postures live on b.compliance
+// (CROSS_BORDER_REGULATED_POSTURES — one vocabulary shared with
+// external-db's gate): under these, a residency mismatch REFUSES the
+// write; under anything else the gates emit an advisory audit and
+// pass (backward-compatible).
+function _postureState() {
+  try {
+    var compliance = require("./compliance");                                     // allow:inline-require — defensive against optional load
+    var posture = compliance.current();
+    return { posture: posture, regulated: compliance.isCrossBorderRegulated(posture) };
+  } catch (_e) { return { posture: null, regulated: false }; }
+}
+
+// Local-SQLite write-residency gate (GDPR Art 44-46 / PIPL Art 38 /
+// DPDP §16 cross-border transfer restrictions). Runs on the PLAINTEXT
+// row before sealRow so the tag column is readable even when other
+// columns seal. Two layers:
+//
+//   1. Per-ROW tag (declarePerRowResidency): on INSERT the declared
+//      column must be present and within allowedTags; under a
+//      regulated posture a tag outside the deployment's region set
+//      ({ region } + allowedStorageRegions from db.init's
+//      dataResidency) refuses the write. UPDATEs gate only when the
+//      change set touches the residency column (an update that does
+//      not move residency is not a transfer).
+//   2. Per-COLUMN tags (declareColumnResidency): the long-advertised
+//      assertColumnResidency gate, enforced here against the
+//      deployment region. Operators tag columns with the region
+//      value their dataResidency declares.
+//
+// Unregulated postures audit (drop-silent) and pass; tables with no
+// declaration are untouched.
+function _assertLocalResidency(table, plaintextRow, op) {
+  var spec = cryptoField.getPerRowResidency(table);
+  var colMap = cryptoField.getColumnResidency(table);
+  if (!spec && !colMap) return;
+
+  var residency = null;
+  try { residency = db().getDataResidency(); } catch (_e) { residency = null; }
+  var region = residency && residency.region ? residency.region : null;
+  var allowedRegions = region
+    ? [region].concat(Array.isArray(residency.allowedStorageRegions)
+        ? residency.allowedStorageRegions : [])
+    : null;
+  var state = _postureState();
+  var posture = state.posture;
+  var regulated = state.regulated;
+
+  if (spec) {
+    var tag = plaintextRow[spec.residencyColumn];
+    var tagPresent = tag !== undefined && tag !== null;
+    var colInChangeSet = Object.prototype.hasOwnProperty.call(plaintextRow, spec.residencyColumn);
+    if (op === "insert" && !tagPresent) {
+      throw new DbQueryError("db-query/row-residency-tag-missing",
+        op + ": table '" + table + "' declares per-row residency on column '" +
+        spec.residencyColumn + "' — every inserted row must carry a tag from [" +
+        spec.allowedTags.join(", ") + "]", true);
+    }
+    // An UPDATE that explicitly sets the residency column to null /
+    // undefined would clear the row's region binding (INSERT refuses a
+    // missing tag; the same row must not be nullable into an untagged
+    // state on update). UPDATEs that don't touch the column pass.
+    if (op === "update" && colInChangeSet && !tagPresent) {
+      throw new DbQueryError("db-query/row-residency-tag-missing",
+        op + ": table '" + table + "' residency column '" + spec.residencyColumn +
+        "' cannot be cleared — set a tag from [" + spec.allowedTags.join(", ") + "]", true);
+    }
+    if (tagPresent) {
+      if (typeof tag !== "string" || spec.allowedTags.indexOf(tag) === -1) {
+        throw new DbQueryError("db-query/row-residency-tag-invalid",
+          op + ": table '" + table + "' residency tag '" + tag +
+          "' is not in allowedTags [" + spec.allowedTags.join(", ") + "]", true);
+      }
+      if (tag !== "global" && tag !== "unrestricted" && allowedRegions &&
+          allowedRegions.indexOf(tag) === -1) {
+        if (regulated) {
+          audit.safeEmit({ action: "db.residency.gate.rejected", outcome: "denied",
+            metadata: { table: table, rowTag: tag, region: region, posture: posture,
+                        operation: op, scope: "local" } });
+          throw new DbQueryError("db-query/row-residency-local-mismatch",
+            op + ": row residency tag '" + tag + "' is outside this deployment's " +
+            "region set [" + allowedRegions.join(", ") + "] under '" + posture +
+            "' posture (cross-border transfer refused)", true);
+        }
+        audit.safeEmit({ action: "db.residency.gate.advisory", outcome: "info",
+          metadata: { table: table, rowTag: tag, region: region, posture: posture || null,
+                      operation: op, scope: "local" } });
+      }
+    }
+  }
+
+  if (colMap && region) {
+    var refusal = cryptoField.assertColumnResidency(table, plaintextRow, { backendTag: region });
+    if (refusal) {
+      if (regulated) {
+        audit.safeEmit({ action: "db.column_residency.gate.rejected", outcome: "denied",
+          metadata: { table: refusal.table, column: refusal.column, want: refusal.want,
+                      got: refusal.got, posture: posture, operation: op, scope: "local" } });
+        throw new DbQueryError("db-query/column-residency-mismatch",
+          op + ": column '" + refusal.column + "' on table '" + refusal.table +
+          "' is bound to residency '" + refusal.want + "' but this deployment's " +
+          "region is '" + refusal.got + "' under '" + posture + "' posture", true);
+      }
+      audit.safeEmit({ action: "db.residency.gate.advisory", outcome: "info",
+        metadata: { table: refusal.table, column: refusal.column, want: refusal.want,
+                    got: refusal.got, posture: posture || null, operation: op, scope: "local" } });
+    }
+  }
+}
 
 // "@>" / "?" / "?|" / "?&" are JSONB containment + key-existence
 // operators. Routed through safeJsonPath validation before binding so
@@ -79,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;
@@ -99,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
@@ -143,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 ----
@@ -167,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);
     }
@@ -216,54 +421,101 @@ class Query {
     }
     // Sealed-field translation: rewrite predicate to use derived hash if available
     if (this._isSealedField(field)) {
-      var lookup = cryptoField.lookupHash(this._cryptoFieldKey(), field, value);
-      if (!lookup) {
-        throw new Error(
-          "cannot query sealed column '" + this._cryptoFieldKey() + "." + field +
-          "' without a derived hash. Declare derivedHashes: { <name>: { from: '" + field + "' } } " +
-          "in the table's schema config."
-        );
+      var missingHashMsg =
+        "cannot query sealed column '" + this._cryptoFieldKey() + "." + field +
+        "' without a derived hash. Declare derivedHashes: { <name>: { from: '" + field + "' } } " +
+        "in the table's schema config.";
+      if (op === "IN") {
+        // Membership query on a sealed column: each candidate plaintext maps
+        // to its own derived hash. Hashing the whole array as one value (the
+        // scalar path below) never matches — whereIn/$in on a sealed column
+        // would throw or silently miss. Expand to the per-element hash set,
+        // and for each element ALSO include the legacy salted-sha3 digest so
+        // membership dual-reads across the v0.15.0 keyed-MAC flip exactly as
+        // the "=" path does (un-migrated rows must still be found).
+        if (!Array.isArray(value) || value.length === 0) {
+          throw new Error("where IN on sealed column '" + this._cryptoFieldKey() +
+            "." + field + "' requires a non-empty array of values");
+        }
+        var sealedField = null;
+        var hashedValues = [];
+        for (var inI = 0; inI < value.length; inI++) {
+          var elemLookup = cryptoField.lookupHash(this._cryptoFieldKey(), field, value[inI]);
+          if (!elemLookup) throw new Error(missingHashMsg);
+          sealedField = elemLookup.field;
+          hashedValues.push(elemLookup.value);
+          if (elemLookup.legacyValue != null && elemLookup.legacyValue !== elemLookup.value) {
+            hashedValues.push(elemLookup.legacyValue);
+          }
+        }
+        field = sealedField;
+        value = hashedValues;
+      } else {
+        var lookup = cryptoField.lookupHash(this._cryptoFieldKey(), field, value);
+        if (!lookup) throw new Error(missingHashMsg);
+        field = lookup.field;
+        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;
+        }
       }
-      field = lookup.field;
-      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;
@@ -284,31 +536,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;
   }
 
@@ -360,51 +616,51 @@ 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);
-    return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row) : null;
+    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;
     for (var i = 0; i < rows.length; i++) {
-      out[i] = cryptoField.unsealRow(key, rows[i]);
+      out[i] = cryptoField.unsealRow(key, rows[i], undefined, dbHandle);
     }
     return out;
   }
@@ -416,8 +672,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.
@@ -431,10 +689,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); });
@@ -454,7 +713,7 @@ class Query {
           var step = iter.next();
           if (step.done) { this.push(null); return; }
           emitted += 1;
-          this.push(cryptoField.unsealRow(key, step.value));
+          this.push(cryptoField.unsealRow(key, step.value, undefined, dbHandle));
         } catch (e) {
           this.destroy(e);
         }
@@ -463,9 +722,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;
   }
 
@@ -477,14 +738,25 @@ class Query {
     if (withId._id === undefined || withId._id === null) {
       withId._id = generateToken(C.BYTES.bytes(16));
     }
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), withId);
-    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);
+    // Residency gates read the PLAINTEXT row (the tag column must be
+    // inspectable even when sibling columns seal below).
+    _assertLocalResidency(this._cryptoFieldKey(), withId, "insert");
+    // Per-row-key tables (declarePerRowKey): materialize a fresh K_row
+    // BEFORE sealRow so sealed columns encrypt under the row-scoped key
+    // (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 the per-row-key store.
+    var sealOpts;
+    var cfKey = this._cryptoFieldKey();
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      var kRow = cryptoField.materializePerRowKey(cfKey, withId._id, this._db);
+      sealOpts = { kRow: kRow, rowId: withId._id };
+    }
+    var sealed = cryptoField.sealRow(cfKey, withId, sealOpts);
+    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);
   }
@@ -511,10 +783,23 @@ 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");
     }
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), changes);
+    // Residency gates on the plaintext change set — an UPDATE that
+    // touches the residency tag (or a region-bound column) is a
+    // transfer and goes through the same refusal matrix as INSERT.
+    _assertLocalResidency(this._cryptoFieldKey(), changes, "update");
+    var cfKey = this._cryptoFieldKey();
+    // Per-row-key tables: sealed columns must re-encrypt under EACH
+    // affected row's own K_row, so a single set-based UPDATE can't seal
+    // one value across rows. Resolve the affected _id set, then seal +
+    // write each row under its row-scoped key. Idempotent materialize
+    // re-derives the existing K_row (created on INSERT).
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      return this._updatePerRowKey(cfKey, changes, single);
+    }
+    var sealed = cryptoField.sealRow(cfKey, changes);
     var setKeys = Object.keys(sealed);
     if (setKeys.length === 0) {
       throw new Error("update changes object is empty");
@@ -522,27 +807,142 @@ 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
+  // ciphertext. Resolve the affected _id set via the WHERE, then for
+  // each row: materialize (idempotent) its K_row, seal the change set
+  // 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 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;
+      if (rowId === undefined || rowId === null) continue;
+      var kRow = cryptoField.materializePerRowKey(cfKey, rowId, this._db);
+      var sealed = cryptoField.sealRow(cfKey, changes, { kRow: kRow, rowId: rowId });
+      var setKeys = Object.keys(sealed);
+      if (setKeys.length === 0) {
+        throw new Error("update changes object is empty");
+      }
+      setKeys.forEach(_validateField);
+      var selfUpd = this;
+      setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
+      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;
+  }
+
   deleteOne() {
     return this._delete(true) > 0;
   }
@@ -554,9 +954,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).
@@ -570,19 +970,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;
   }
 
@@ -602,10 +1005,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;
   }
 
@@ -613,36 +1016,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);
+      // 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);
+      };
     }
-    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]);
+    // 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;
   }
 
@@ -668,22 +1096,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;
   }
 
@@ -724,20 +1154,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;
   }
 }
@@ -751,11 +1202,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;
@@ -766,19 +1219,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); }
@@ -797,56 +1248,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;
@@ -854,12 +1316,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;
     }
@@ -874,40 +1336,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;
   }
-  return count;
+  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;
+  }
+  if (or) pred.orWhereOp(part.field, part.op, part.value);
+  else pred.whereOp(part.field, part.op, part.value);
 }
 
 function _validateField(field) {
@@ -921,4 +1390,157 @@ function _validateField(field) {
   }
 }
 
-module.exports = { Query: Query };
+// ---- raw-write residency gate (execRaw / prepared-statement execution) ----
+// The structured builder runs every insert/update through _assertLocalResidency.
+// The raw paths (b.db.runSql / execRaw, b.db.prepare(sql).run(...)) bypass it, so
+// a cross-border row could land straight on disk under a regulated posture. These
+// helpers extract the residency-column value from a raw INSERT / UPDATE / REPLACE
+// and run it through the SAME gate; a write to a residency table the framework
+// cannot parse fails CLOSED (refused) - a raw write never skips the check.
+var _RAW_WRITE_KEYWORD_RE = /^\s*(?:INSERT|REPLACE|UPDATE)\b/i;
+var _RAW_INSERT_RE = /^\s*(?:INSERT|REPLACE)\s+(?:OR\s+[A-Za-z]+\s+)?INTO\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?\s*\(([^)]+)\)\s*VALUES\s*\(([\s\S]+)\)\s*;?\s*$/i;
+var _RAW_UPDATE_RE = /^\s*UPDATE\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?\s+SET\s+([\s\S]+?)\s*;?\s*$/i;
+var _RAW_TABLE_RE = /^\s*(?:INSERT|REPLACE)\s+(?:OR\s+[A-Za-z]+\s+)?INTO\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?|^\s*UPDATE\s+(?:[\x22\x27\x60]?[A-Za-z_]\w*[\x22\x27\x60]?\s*\.\s*){0,3}[\x22\x27\x60]?([A-Za-z_]\w*)[\x22\x27\x60]?/i;
+
+function _unquoteIdent(s) {
+  s = String(s).trim();
+  if (s.length >= 2 &&
+      (s.charAt(0) === '"' || s.charAt(0) === "'" || s.charAt(0) === "`") &&
+      s.charAt(s.length - 1) === s.charAt(0)) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function _rawWriteTable(sql) {
+  // Both regexes are ^-anchored (leading write keyword + table head): they scan
+  // only the statement head, so they are constant-time regardless of SQL length.
+  if (typeof sql !== "string" || !_RAW_WRITE_KEYWORD_RE.test(sql)) return null;  // allow:regex-no-length-cap
+  var m = _RAW_TABLE_RE.exec(sql);  // allow:regex-no-length-cap
+  return m ? _unquoteIdent(m[1] || m[2]) : null;
+}
+
+// Cheap prepare-time pre-check so only writes to a residency table get wrapped.
+function _isRawWriteToResidencyTable(sql) {
+  var table = _rawWriteTable(sql);
+  if (!table) return false;
+  return !!(cryptoField.getPerRowResidency(table) || cryptoField.getColumnResidency(table));
+}
+
+function _splitTopLevelCommas(s) {
+  var out = [], depth = 0, cur = "", q = null;
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charAt(i);
+    if (q) {
+      cur += c;
+      if (c === q) { if (s.charAt(i + 1) === q) { cur += s.charAt(++i); } else { q = null; } }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") { q = c; cur += c; continue; }
+    if (c === "(") { depth += 1; cur += c; continue; }
+    if (c === ")") { depth -= 1; cur += c; continue; }
+    if (c === "," && depth === 0) { out.push(cur); cur = ""; continue; }
+    cur += c;
+  }
+  if (cur.trim() !== "") out.push(cur);
+  return out.map(function (x) { return x.trim(); });
+}
+
+// Quote/paren-aware: return the SET-clause text up to the first top-level
+// WHERE keyword that is NOT inside a string literal or parenthesised
+// subexpression. A WHERE embedded in a quoted value (SET note='x WHERE
+// y', ...) is skipped, so a residency-column assignment after it is still
+// parsed and gated. Linear scan; fixed 5-char keyword peek, no per-char slice.
+function _setClauseBeforeWhere(s) {
+  var depth = 0, q = null, n = s.length;
+  for (var i = 0; i < n; i++) {
+    var c = s.charAt(i);
+    if (q) {
+      if (c === q) { if (s.charAt(i + 1) === q) { i++; } else { q = null; } }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "\x60") { q = c; continue; }
+    if (c === "(") { depth += 1; continue; }
+    if (c === ")") { depth -= 1; continue; }
+    if (depth === 0 && (c === " " || c === "\t" || c === "\n" || c === "\r")) {
+      var j = i;
+      while (j < n && /\s/.test(s.charAt(j))) j += 1;
+      if (s.substr(j, 5).toLowerCase() === "where" && !/\w/.test(s.charAt(j + 5) || "")) {
+        return s.slice(0, i);
+      }
+    }
+  }
+  return s;
+}
+
+function _rawValue(tok, boundParams, pc) {
+  tok = tok.trim();
+  if (tok === "?") { return boundParams[pc.i++]; }
+  if (tok.length >= 2 && (tok.charAt(0) === "'" || tok.charAt(0) === '"')) {
+    var qc = tok.charAt(0);
+    return tok.slice(1, -1).split(qc + qc).join(qc);
+  }
+  if (/^null$/i.test(tok)) return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(tok)) return Number(tok);
+  return tok;  // bare expression / named param: opaque -> fails the allowedTags check -> refused
+}
+
+function _flattenRunParams(argsLike) {
+  var a = Array.prototype.slice.call(argsLike || []);
+  if (a.length === 1 && Array.isArray(a[0])) return a[0];
+  return a;
+}
+
+function _assertRawWriteResidency(sql, boundParams) {
+  var table = _rawWriteTable(sql);
+  if (!table) return;
+  if (!cryptoField.getPerRowResidency(table) && !cryptoField.getColumnResidency(table)) return;
+  boundParams = _flattenRunParams(boundParams);
+
+  // The INSERT/UPDATE body regexes below scan with [\s\S]+; bound the input
+  // first and fail CLOSED on an over-long statement - a residency write the
+  // framework cannot safely parse must be refused, never let past the gate.
+  if (sql.length > 100000) {
+    throw new DbQueryError("db-query/row-residency-raw-unparseable",
+      "raw write to residency table '" + table + "' exceeds the parse limit (" +
+      sql.length + " chars) - use b.db.from(\"" + table + "\") so residency is validated", true);
+  }
+
+  var mi = _RAW_INSERT_RE.exec(sql);  // allow:regex-no-length-cap — input length-capped above
+  var mu = mi ? null : _RAW_UPDATE_RE.exec(sql);  // allow:regex-no-length-cap — input length-capped above
+  if (!mi && !mu) {
+    throw new DbQueryError("db-query/row-residency-raw-unparseable",
+      "raw write to residency table '" + table + "' cannot be parsed to validate its " +
+      "residency tag - use b.db.from(\"" + table + "\").insertOne / .updateOne so the tag is checked", true);
+  }
+
+  var plaintextRow = {};
+  var pc = { i: 0 };
+  if (mi) {
+    var cols = _splitTopLevelCommas(mi[2]).map(_unquoteIdent);
+    var vals = _splitTopLevelCommas(mi[3]);
+    if (cols.length !== vals.length) {
+      throw new DbQueryError("db-query/row-residency-raw-unparseable",
+        "raw insert to residency table '" + table + "' has an unmodelled VALUES shape " +
+        "(multi-row / expression) - use the structured builder so residency is validated", true);
+    }
+    for (var ci = 0; ci < cols.length; ci++) {
+      plaintextRow[cols[ci]] = _rawValue(vals[ci], boundParams, pc);
+    }
+    _assertLocalResidency(table, plaintextRow, "insert");
+  } else {
+    var assigns = _splitTopLevelCommas(_setClauseBeforeWhere(mu[2]));
+    for (var ai = 0; ai < assigns.length; ai++) {
+      var eq = assigns[ai].indexOf("=");
+      if (eq === -1) continue;
+      plaintextRow[_unquoteIdent(assigns[ai].slice(0, eq))] = _rawValue(assigns[ai].slice(eq + 1), boundParams, pc);
+    }
+    _assertLocalResidency(table, plaintextRow, "update");
+  }
+}
+
+module.exports = {
+  Query: Query,
+  _isRawWriteToResidencyTable: _isRawWriteToResidencyTable,
+  _assertRawWriteResidency:    _assertRawWriteResidency,
+};