@blamejs/core 0.14.27 → 0.15.0

package/lib/mail-store.js

@@ -63,6 +63,7 @@ var cryptoField = require("./crypto-field");
 var vault = require("./vault");
 var safeMime = require("./safe-mime");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var guardMessageId = require("./guard-message-id");
 var mailStoreFts = require("./mail-store-fts");
 var { defineClass } = require("./framework-error");
@@ -133,13 +134,28 @@ function create(opts) {
     throw new MailStoreError("mail-store/bad-table-prefix",
       "mailStore.create: tablePrefix is not a valid SQL identifier: " + e.message);
   }
-  var qMsgs    = safeSql.quoteIdentifier(prefix + "_messages",  "sqlite");
-  var qFolders = safeSql.quoteIdentifier(prefix + "_folders",   "sqlite");
-  var qFlags   = safeSql.quoteIdentifier(prefix + "_flags",     "sqlite");
-  var qQuota   = safeSql.quoteIdentifier(prefix + "_quota",     "sqlite");
-  var qFts     = safeSql.quoteIdentifier(prefix + "_messages_fts", "sqlite");
-  var qMeta    = safeSql.quoteIdentifier(prefix + "_meta",      "sqlite");
+  // Bare logical table names. The store targets a CONCRETE sqlite handle
+  // (the operator's backend), never b.clusterStorage, so every b.sql
+  // builder is constructed with { dialect: "sqlite", quoteName: true } so
+  // the prefixed name emits as a quoted `"..."` identifier (the same
+  // quote-by-construction the prior hand-rolled safeSql.quoteIdentifier
+  // produced). The few quoted tokens kept below feed the two spots a verb
+  // builder cannot reach: the FTS5 virtual-table self-reference in a MATCH
+  // sub-query and the existing-row self-reference inside the quota upsert's
+  // `col = col + EXCLUDED.col` expression.
   var messagesTable = prefix + "_messages";
+  var foldersTable  = prefix + "_folders";
+  var flagsTable    = prefix + "_flags";
+  var quotaTable    = prefix + "_quota";
+  var ftsTable      = prefix + "_messages_fts";
+  var metaTable     = prefix + "_meta";
+  var SQL = { dialect: "sqlite", quoteName: true };
+  // The only quoted table token kept as a literal: the quota table's
+  // existing-row self-reference inside the `col = col +/- ...` SET
+  // expressions (the decrement update + the accumulate-on-conflict upsert),
+  // which a structured set()/value cell cannot express. Every other table
+  // identifier emits through the b.sql builders above with quoteName.
+  var qQuota = safeSql.quoteIdentifier(quotaTable, "sqlite");
 
   var maxMessageBytes = opts.maxMessageBytes !== undefined ? opts.maxMessageBytes : DEFAULT_MAX_MESSAGE_BYTES;
   var maxBodyBytes    = opts.maxBodyBytes    !== undefined ? opts.maxBodyBytes    : DEFAULT_MAX_BODY_BYTES;
@@ -160,62 +176,138 @@ function create(opts) {
   });
 
   if (doInit) {
-    _ensureSchema(db, qMsgs, qFolders, qFlags, qQuota, qFts, qMeta);
-    _ensureDefaultFolders(db, qFolders);
+    _ensureSchema(db, {
+      messagesTable: messagesTable, foldersTable: foldersTable,
+      flagsTable: flagsTable, quotaTable: quotaTable,
+      ftsTable: ftsTable, metaTable: metaTable,
+    });
+    _ensureDefaultFolders(db, foldersTable);
   }
 
-  // Prepared statements — cached across the store lifetime.
-  var stmtInsertMsg = db.prepare(
-    "INSERT INTO " + qMsgs + " (" +
-    "objectid, folder_id, modseq, internal_date, received_at, size_bytes, " +
-    "message_id, message_id_hash, in_reply_to, references_csv, " +
-    "thread_root_id, subject, from_addr, from_hash, to_addrs, " +
-    "body_text, body_html, legal_hold) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)"
-  );
-  var stmtBumpFolderModseq = db.prepare("UPDATE " + qFolders + " SET modseq_max = ? WHERE name = ?");
-  var stmtGetFolderByName  = db.prepare("SELECT id, name, role, parent_id, modseq_max, uidvalidity FROM " + qFolders + " WHERE name = ?");
-  var stmtFetchMsg         = db.prepare("SELECT * FROM " + qMsgs + " WHERE objectid = ? AND folder_id = ?");
-  var stmtQueryByModseq    = db.prepare(
-    "SELECT objectid, modseq, size_bytes, internal_date, legal_hold FROM " + qMsgs +
-    " WHERE folder_id = ? AND modseq > ? ORDER BY modseq ASC LIMIT ?");
-  var stmtFlagsForMsg      = db.prepare("SELECT flag FROM " + qFlags + " WHERE objectid = ?");
-  var stmtSetFlag          = db.prepare("INSERT OR IGNORE INTO " + qFlags + " (objectid, flag, set_at) VALUES (?, ?, ?)");
-  var stmtUnsetFlag        = db.prepare("DELETE FROM " + qFlags + " WHERE objectid = ? AND flag = ?");
-  var stmtLegalHold        = db.prepare("UPDATE " + qMsgs + " SET legal_hold = ? WHERE objectid = ?");
-  var stmtMoveByObjectId   = db.prepare(
-    "UPDATE " + qMsgs + " SET folder_id = ?, modseq = ? WHERE objectid = ? AND folder_id = ?");
-  var stmtSizeByObjectId   = db.prepare(
-    "SELECT size_bytes FROM " + qMsgs + " WHERE objectid = ? AND folder_id = ?");
-  var stmtDecrementQuota   = db.prepare(
-    "UPDATE " + qQuota + " SET used_bytes = used_bytes - ?, used_count = used_count - ? WHERE folder_id = ?");
-  var stmtThreadFor        = db.prepare("SELECT objectid FROM " + qMsgs + " WHERE thread_root_id = ? ORDER BY received_at ASC");
-  var stmtFindThreadByMsgId = db.prepare(
-    "SELECT objectid, thread_root_id FROM " + qMsgs + " WHERE message_id_hash = ? LIMIT 1");
-  var stmtInsertFolder     = db.prepare(
-    "INSERT INTO " + qFolders + " (name, role, parent_id, modseq_max, uidvalidity) VALUES (?, ?, ?, 0, ?)");
-  var stmtListFolders      = db.prepare("SELECT id, name, role, parent_id, modseq_max FROM " + qFolders);
-  var stmtQuotaForFolder   = db.prepare("SELECT used_bytes, used_count, cap_bytes, cap_count FROM " + qQuota + " WHERE folder_id = ?");
-  var stmtBumpQuota        = db.prepare(
-    "INSERT INTO " + qQuota + " (folder_id, used_bytes, used_count, cap_bytes, cap_count) VALUES (?, ?, ?, NULL, NULL) " +
-    "ON CONFLICT(folder_id) DO UPDATE SET used_bytes = used_bytes + excluded.used_bytes, used_count = used_count + excluded.used_count");
+  // Prepared statements — cached across the store lifetime. Every
+  // statement text is composed through b.sql (sqlite dialect, quoteName so
+  // the prefixed table name emits as a quoted identifier against the
+  // concrete handle) and then prepared once; the node:sqlite handle binds
+  // the `?` placeholders positionally at run() / get() / all() time. Every
+  // VALUES / SET cell is a `"?"` placeholder string so the builder emits a
+  // `?` per column (only the SQL TEXT is kept; the throwaway params array
+  // of literal "?" strings is discarded) — the caller binds the real values
+  // at run() time, including the leading 0 the INSERT seeds `legal_hold` to.
+  var stmtInsertMsg = db.prepare(sql.insert(messagesTable, SQL)
+    .columns([
+      "objectid", "folder_id", "modseq", "internal_date", "received_at",
+      "size_bytes", "message_id", "message_id_hash", "in_reply_to",
+      "references_csv", "thread_root_id", "subject", "from_addr", "from_hash",
+      "to_addrs", "body_text", "body_html", "legal_hold",
+    ])
+    .values([
+      "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?", "?",
+    ]).toSql().sql);
+  var stmtBumpFolderModseq = db.prepare(sql.update(foldersTable, SQL)
+    .set("modseq_max", "?").where("name", "?").toSql().sql);
+  var stmtGetFolderByName  = db.prepare(sql.select(foldersTable, SQL)
+    .columns(["id", "name", "role", "parent_id", "modseq_max", "uidvalidity"])
+    .where("name", "?").toSql().sql);
+  var stmtFetchMsg         = db.prepare(sql.select(messagesTable, SQL)
+    .where("objectid", "?").where("folder_id", "?").toSql().sql);
+  // The modseq-cursor read carries a per-call row LIMIT. b.sql's limit()
+  // takes a concrete integer (a bound LIMIT placeholder is not a builder
+  // shape), and the limit is a server-controlled, hard-capped integer — so
+  // the statement is composed per call with the integer baked in (the
+  // folder_id + sinceModseq still bind as `?`). Cached prepared statements
+  // are reserved for the fixed-shape reads above.
+  function _queryByModseqStmt(limit) {
+    // Coerce the per-call limit to a non-negative integer before it reaches
+    // b.sql's limit() (which THROWS on a non-integer). The limit is an
+    // operator-supplied query opt, so this is the defensive-reader tier: a
+    // garbage value floors to a sane page size rather than crashing the read.
+    var n = Math.floor(Number(limit));
+    if (!isFinite(n) || n < 0) n = 1000;
+    return db.prepare(sql.select(messagesTable, SQL)
+      .columns(["objectid", "modseq", "size_bytes", "internal_date", "legal_hold"])
+      .where("folder_id", "?").whereOp("modseq", ">", "?")
+      .orderBy("modseq", "asc").limit(n).toSql().sql);
+  }
+  function _queryByModseqRows(folderId, sinceModseq, limit) {
+    return _queryByModseqStmt(limit).all(folderId, sinceModseq);
+  }
+  var stmtFlagsForMsg      = db.prepare(sql.select(flagsTable, SQL)
+    .columns(["flag"]).where("objectid", "?").toSql().sql);
+  // INSERT OR IGNORE — composed as ON CONFLICT(objectid, flag) DO NOTHING
+  // (the flags PK), the sqlite-final upsert form b.sql emits for the
+  // idempotent flag set.
+  var stmtSetFlag          = db.prepare(sql.upsert(flagsTable, SQL)
+    .columns(["objectid", "flag", "set_at"]).values({ objectid: "?", flag: "?", set_at: "?" })
+    .onConflict(["objectid", "flag"]).doNothing().toSql().sql);
+  var stmtUnsetFlag        = db.prepare(sql.delete(flagsTable, SQL)
+    .where("objectid", "?").where("flag", "?").toSql().sql);
+  var stmtLegalHold        = db.prepare(sql.update(messagesTable, SQL)
+    .set("legal_hold", "?").where("objectid", "?").toSql().sql);
+  var stmtMoveByObjectId   = db.prepare(sql.update(messagesTable, SQL)
+    .set("folder_id", "?").set("modseq", "?")
+    .where("objectid", "?").where("folder_id", "?").toSql().sql);
+  var stmtSizeByObjectId   = db.prepare(sql.select(messagesTable, SQL)
+    .columns(["size_bytes"]).where("objectid", "?").where("folder_id", "?").toSql().sql);
+  // `used_bytes = used_bytes - ?` — a guarded setRaw expression (the
+  // decrement amount binds as the leading `?`; the column self-reference
+  // is quoted by construction).
+  var stmtDecrementQuota   = db.prepare(sql.update(quotaTable, SQL)
+    .setRaw("used_bytes", qQuota + ".\"used_bytes\" - ?", ["?"])
+    .setRaw("used_count", qQuota + ".\"used_count\" - ?", ["?"])
+    .where("folder_id", "?").toSql().sql);
+  var stmtThreadFor        = db.prepare(sql.select(messagesTable, SQL)
+    .columns(["objectid"]).where("thread_root_id", "?")
+    .orderBy("received_at", "asc").toSql().sql);
+  var stmtFindThreadByMsgId = db.prepare(sql.select(messagesTable, SQL)
+    .columns(["objectid", "thread_root_id"]).where("message_id_hash", "?")
+    .limit(1).toSql().sql);
+  var stmtInsertFolder     = db.prepare(sql.insert(foldersTable, SQL)
+    .columns(["name", "role", "parent_id", "modseq_max", "uidvalidity"])
+    .values(["?", "?", "?", "?", "?"]).toSql().sql);
+  var stmtListFolders      = db.prepare(sql.select(foldersTable, SQL)
+    .columns(["id", "name", "role", "parent_id", "modseq_max"]).toSql().sql);
+  var stmtQuotaForFolder   = db.prepare(sql.select(quotaTable, SQL)
+    .columns(["used_bytes", "used_count", "cap_bytes", "cap_count"])
+    .where("folder_id", "?").toSql().sql);
+  // INSERT ... ON CONFLICT(folder_id) DO UPDATE SET col = col + EXCLUDED.col
+  // — the atomic per-folder quota accumulator. The existing-row and
+  // proposed-row (EXCLUDED) self-references are quoted by construction off
+  // the resolved table name so the prefix stays consistent across the
+  // INSERT target and the SET expression (the same shape b.rateLimit's
+  // window accumulator composes).
+  var stmtBumpQuota        = db.prepare(sql.upsert(quotaTable, SQL)
+    .columns(["folder_id", "used_bytes", "used_count", "cap_bytes", "cap_count"])
+    .values({ folder_id: "?", used_bytes: "?", used_count: "?", cap_bytes: "?", cap_count: "?" })
+    .onConflict(["folder_id"])
+    .doUpdate({
+      used_bytes: qQuota + ".\"used_bytes\" + EXCLUDED.\"used_bytes\"",
+      used_count: qQuota + ".\"used_count\" + EXCLUDED.\"used_count\"",
+    }).toSql().sql);
   // Hard-expunge prepared statements — used by `hardExpunge` to delete
   // a message permanently after retention-floor + legal-hold gates
   // pass. The SELECT is the gate-input source (legal_hold flag + age);
   // the DELETE + flag-cleanup + quota-decrement run inside a backend
-  // transaction so partial state can't survive a crash.
-  var stmtSelectForExpunge = db.prepare(
-    "SELECT objectid, folder_id, size_bytes, received_at, legal_hold FROM " + qMsgs +
-    " WHERE folder_id = ? AND objectid IN (SELECT value FROM json_each(?))");
-  var stmtDeleteMsg        = db.prepare("DELETE FROM " + qMsgs + " WHERE objectid = ?");
-  var stmtDeleteFlags      = db.prepare("DELETE FROM " + qFlags + " WHERE objectid = ?");
+  // transaction so partial state can't survive a crash. The objectid set
+  // arrives as a JSON array string and is unrolled through the sqlite
+  // json_each table-valued function (whereInJsonEach) so the candidate
+  // list binds as a single `?` rather than a variable placeholder count.
+  var stmtSelectForExpunge = db.prepare(sql.select(messagesTable, SQL)
+    .columns(["objectid", "folder_id", "size_bytes", "received_at", "legal_hold"])
+    .where("folder_id", "?").whereInJsonEach("objectid", "?").toSql().sql);
+  var stmtDeleteMsg        = db.prepare(sql.delete(messagesTable, SQL)
+    .where("objectid", "?").toSql().sql);
+  var stmtDeleteFlags      = db.prepare(sql.delete(flagsTable, SQL)
+    .where("objectid", "?").toSql().sql);
   // Sealed-token FTS5 prepared statements — index sync runs in the
   // same transaction window as the canonical row mutation so a crash
   // between the two cannot leave the FTS index out of step with the
   // messages table. See lib/mail-store-fts.js for the tokenize +
   // vault-salted-hash transform applied here.
-  var stmtInsertFts        = db.prepare(
-    "INSERT INTO " + qFts + " (objectid, subject_toks, addr_toks, body_toks) VALUES (?, ?, ?, ?)");
-  var stmtDeleteFts        = db.prepare("DELETE FROM " + qFts + " WHERE objectid = ?");
+  var stmtInsertFts        = db.prepare(sql.insert(ftsTable, SQL)
+    .columns(["objectid", "subject_toks", "addr_toks", "body_toks"])
+    .values(["?", "?", "?", "?"]).toSql().sql);
+  var stmtDeleteFts        = db.prepare(sql.delete(ftsTable, SQL)
+    .where("objectid", "?").toSql().sql);
 
   // `<prefix>_meta` marker read — used by the reindex gate at create()
   // AND by every FTS query path (search) to refuse a half-built index.
@@ -224,7 +316,8 @@ function create(opts) {
   // instead of throwing.
   function _readFtsMarker() {
     try {
-      var row = db.prepare("SELECT value FROM " + qMeta + " WHERE key = ?")
+      var row = db.prepare(sql.select(metaTable, SQL)
+        .columns(["value"]).where("key", "?").toSql().sql)
         .get(FTS_FORMAT_META_KEY);
       return row ? row.value : null;
     } catch (_e) {
@@ -271,9 +364,9 @@ function create(opts) {
 
     // Count existing FTS rows AFTER the early-return so the common
     // already-current path pays nothing for the scan.
-    var ftsCountRow = db.prepare("SELECT COUNT(*) AS n FROM " + qFts).get();
+    var ftsCountRow = db.prepare(sql.select(ftsTable, SQL).count("*", "n").toSql().sql).get();
     var ftsCount = (ftsCountRow && ftsCountRow.n) || 0;
-    var msgCountRow = db.prepare("SELECT COUNT(*) AS n FROM " + qMsgs).get();
+    var msgCountRow = db.prepare(sql.select(messagesTable, SQL).count("*", "n").toSql().sql).get();
     var msgCount = (msgCountRow && msgCountRow.n) || 0;
 
     // Fresh store — no marker AND nothing indexed AND no messages to
@@ -310,8 +403,8 @@ function create(opts) {
     var allRows;
     db.prepare("BEGIN IMMEDIATE").run();
     try {
-      allRows = db.prepare("SELECT * FROM " + qMsgs).all();
-      db.prepare("DELETE FROM " + qFts).run();
+      allRows = db.prepare(sql.select(messagesTable, SQL).toSql().sql).all();
+      db.prepare(sql.delete(ftsTable, SQL).allowNoWhere().toSql().sql).run();
       for (var i = 0; i < allRows.length; i += 1) {
         // unsealRow returns the DB column names (subject / from_addr /
         // to_addrs / body_text); map them into the FTS param shape
@@ -348,10 +441,10 @@ function create(opts) {
   }
 
   function _writeFtsMarker(value) {
-    db.prepare(
-      "INSERT INTO " + qMeta + " (key, value) VALUES (?, ?) " +
-      "ON CONFLICT(key) DO UPDATE SET value = excluded.value"
-    ).run(FTS_FORMAT_META_KEY, value);
+    db.prepare(sql.upsert(metaTable, SQL)
+      .columns(["key", "value"]).values({ key: "?", value: "?" })
+      .onConflict(["key"]).doUpdateFromExcluded(["value"]).toSql().sql)
+      .run(FTS_FORMAT_META_KEY, value);
   }
 
   // Wire the reindex into create() AFTER schema bootstrap. A fresh store
@@ -370,7 +463,7 @@ function create(opts) {
       // transactions fall back to per-statement (the FTS insert is the
       // last write, so partial state == still consistent to the reader).
       var args = {
-        db: db, qMsgs: qMsgs, qFlags: qFlags, messagesTable: messagesTable,
+        db: db, messagesTable: messagesTable,
         stmtInsertMsg: stmtInsertMsg,
         stmtInsertFts: stmtInsertFts,
         stmtBumpFolderModseq: stmtBumpFolderModseq,
@@ -391,7 +484,7 @@ function create(opts) {
     },
     fetchByObjectId:  function (folderName, objectid) {
       return _fetchByObjectId({
-        db: db, qMsgs: qMsgs, qFolders: qFolders, qFlags: qFlags, messagesTable: messagesTable,
+        db: db, messagesTable: messagesTable,
         stmtGetFolderByName: stmtGetFolderByName,
         stmtFetchMsg: stmtFetchMsg,
         stmtFlagsForMsg: stmtFlagsForMsg,
@@ -428,7 +521,12 @@ function create(opts) {
       }
       var f = filter || {};
       var sinceModseq = f.sinceModseq || 0;
-      var limit = f.limit || 100;
+      // Normalize the row cap to a non-negative integer (default 100, hard
+      // cap 1000) before it reaches b.sql's limit() on the FTS path, which
+      // THROWS on a non-integer. Defensive-reader tier: a garbage operator
+      // value floors to the default page size.
+      var limit = Math.floor(Number(f.limit));
+      if (!isFinite(limit) || limit < 0) limit = 100;
       if (limit > 1000) limit = 1000;                                                                  // query row cap, not bytes
 
       // The FTS index is queryable only when the on-disk format marker
@@ -439,7 +537,7 @@ function create(opts) {
       // matches as if it were complete is the corruption hazard the
       // reindex sentinel exists to prevent.
       if (!_ftsIndexUsable()) {
-        var nonFinal = stmtQueryByModseq.all(folder.id, sinceModseq, limit);
+        var nonFinal = _queryByModseqRows(folder.id, sinceModseq, limit);
         return {
           rows: nonFinal.map(function (r) {
             return {
@@ -476,7 +574,7 @@ function create(opts) {
       }
 
       if (matchClauses.length === 0) {
-        var fallback = stmtQueryByModseq.all(folder.id, sinceModseq, limit);
+        var fallback = _queryByModseqRows(folder.id, sinceModseq, limit);
         return {
           rows: fallback.map(function (r) {
             return {
@@ -491,14 +589,21 @@ function create(opts) {
       var matchExpr = matchClauses.join(" AND ");
       // FTS5 MATCH binds to the virtual-table name — aliases / joined-
       // table refs are parsed as ordinary column refs and fail. The
-      // IN-subquery shape sidesteps that.
-      var sql =
-        "SELECT objectid, modseq, size_bytes, internal_date, legal_hold " +
-        "FROM " + qMsgs + " " +
-        "WHERE folder_id = ? AND modseq > ? " +
-        "AND objectid IN (SELECT objectid FROM " + qFts + " WHERE " + qFts + " MATCH ?) " +
-        "ORDER BY modseq ASC LIMIT ?";
-      var rows = db.prepare(sql).all(folder.id, sinceModseq, matchExpr, limit);
+      // IN-subquery shape (whereIn(col, subBuilder)) sidesteps that: the
+      // sub selects objectid from the FTS5 table with `<fts> MATCH ?`
+      // (whereMatch, which targets the virtual-table identifier and
+      // bypasses the column gate). The MATCH operand stays a bound `?`, so
+      // the operator's tokenized-hashed query expression never reshapes the
+      // statement. Param bind order: folder_id, sinceModseq, then the
+      // sub-query's MATCH operand.
+      var ftsSub = sql.select(ftsTable, SQL)
+        .columns(["objectid"]).whereMatch(ftsTable, "?");
+      var matchStmt = db.prepare(sql.select(messagesTable, SQL)
+        .columns(["objectid", "modseq", "size_bytes", "internal_date", "legal_hold"])
+        .where("folder_id", "?").whereOp("modseq", ">", "?")
+        .whereIn("objectid", ftsSub)
+        .orderBy("modseq", "asc").limit(limit).toSql().sql);
+      var rows = matchStmt.all(folder.id, sinceModseq, matchExpr);
       return {
         rows: rows.map(function (r) {
           return {
@@ -518,7 +623,7 @@ function create(opts) {
       }
       var sinceModseq = (queryOpts && queryOpts.sinceModseq) || 0;
       var limit = (queryOpts && queryOpts.limit) || 1000;                                          // query row cap, not bytes
-      var rows = stmtQueryByModseq.all(folder.id, sinceModseq, limit);
+      var rows = _queryByModseqRows(folder.id, sinceModseq, limit);
       return rows.map(function (r) {
         return {
           objectid: r.objectid, modseq: r.modseq, sizeBytes: r.size_bytes,
@@ -528,7 +633,7 @@ function create(opts) {
     },
     setFlags:         function (folderName, objectids, flagOpts) {
       return _setFlags({
-        db: db, qMsgs: qMsgs,
+        db: db, messagesTable: messagesTable,
         stmtGetFolderByName: stmtGetFolderByName,
         stmtBumpFolderModseq: stmtBumpFolderModseq,
         stmtSetFlag: stmtSetFlag,
@@ -549,12 +654,13 @@ function create(opts) {
       var role = fo.role || null;
       var parentId = fo.parentId || null;
       var uidvalidity = Math.floor(Date.now() / 1000);                                              // Unix timestamp, not bytes
-      stmtInsertFolder.run(name, role, parentId, uidvalidity);
+      stmtInsertFolder.run(name, role, parentId, 0, uidvalidity);                                  // modseq_max seeds to 0
       return stmtGetFolderByName.get(name);
     },
     listFolders:      function () { return stmtListFolders.all(); },
     threadFor:        function (objectid) {
-      var msg = db.prepare("SELECT thread_root_id FROM " + qMsgs + " WHERE objectid = ?").get(objectid);
+      var msg = db.prepare(sql.select(messagesTable, SQL)
+        .columns(["thread_root_id"]).where("objectid", "?").toSql().sql).get(objectid);
       if (!msg) return [];
       return stmtThreadFor.all(msg.thread_root_id).map(function (r) { return r.objectid; });
     },
@@ -798,10 +904,10 @@ function _appendMessage(args) {
     sealed.received_at, sealed.size_bytes, sealed.message_id, sealed.message_id_hash,
     sealed.in_reply_to, sealed.references_csv, sealed.thread_root_id,
     sealed.subject, sealed.from_addr, sealed.from_hash, sealed.to_addrs,
-    sealed.body_text, sealed.body_html
+    sealed.body_text, sealed.body_html, 0                                                          // legal_hold seeds to 0
   );
   args.stmtBumpFolderModseq.run(modseq, args.folderName);
-  args.stmtBumpQuota.run(folder.id, buf.length, 1);
+  args.stmtBumpQuota.run(folder.id, buf.length, 1, null, null);                                    // cap_bytes / cap_count seed NULL on first insert
 
   // FTS index update — tokenize the PRE-seal plaintext, hash each
   // token with the per-deployment vault salt, insert into the FTS5
@@ -896,7 +1002,7 @@ function _moveMessages(args) {
   // on append; move must keep both sides accurate.
   if (changed > 0) {
     args.stmtDecrementQuota.run(movedBytes, changed, fromFolder.id);
-    args.stmtBumpQuota.run(toFolder.id, movedBytes, changed);
+    args.stmtBumpQuota.run(toFolder.id, movedBytes, changed, null, null);                          // cap_bytes / cap_count seed NULL on first insert
   }
   args.stmtBumpFolderModseq.run(srcModseq, args.fromFolderName);
   args.stmtBumpFolderModseq.run(dstModseq, args.toFolderName);
@@ -941,9 +1047,15 @@ function _setFlags(args) {
     var CHUNK = 500;                                                                               // IN-clause chunk size, not bytes
     for (var i = 0; i < args.objectids.length; i += CHUNK) {
       var chunk = args.objectids.slice(i, i + CHUNK);
-      var placeholders = chunk.map(function () { return "?"; }).join(",");
-      var sql = "UPDATE " + args.qMsgs + " SET modseq = ? WHERE objectid IN (" + placeholders + ")";
-      var stmt = args.db.prepare(sql);
+      // b.sql.update(...).whereIn(objectid, chunk) emits the per-chunk
+      // `SET "modseq" = ? WHERE "objectid" IN (?, ?, ...)` text (the chunk
+      // entries are `?` placeholders, bound positionally at run()); the
+      // modseq `?` leads, so the bind list is [newModseq].concat(chunk).
+      var stmtText = sql.update(args.messagesTable, { dialect: "sqlite", quoteName: true })
+        .set("modseq", "?")
+        .whereIn("objectid", chunk.map(function () { return "?"; }))
+        .toSql().sql;
+      var stmt = args.db.prepare(stmtText);
       stmt.run.apply(stmt, [newModseq].concat(chunk));
     }
   }
@@ -1009,100 +1121,121 @@ function _normalizeMsgId(s) {
 
 // ---- Schema bootstrap ----------------------------------------------------
 
-function _ensureSchema(db, qMsgs, qFolders, qFlags, qQuota, qFts, qMeta) {
+function _ensureSchema(db, tables) {
+  // Every DDL statement is composed through b.sql with quoteName so the
+  // prefixed table name emits as a quoted identifier against the concrete
+  // sqlite handle (no clusterStorage rewrite — the store owns its backend).
+  // The DDL builders return { sql } (DDL binds no values).
+  var DDL = { dialect: "sqlite", quoteName: true };
+  var foldersTable  = tables.foldersTable;
+  var messagesTable = tables.messagesTable;
+  var flagsTable    = tables.flagsTable;
+  var quotaTable    = tables.quotaTable;
+  var ftsTable      = tables.ftsTable;
+  var metaTable     = tables.metaTable;
+
+  function _ddl(built) { db.prepare(built.sql).run(); }
+
   // Folders table — created first since messages reference folder_id.
-  db.prepare(
-    "CREATE TABLE IF NOT EXISTS " + qFolders + " (" +
-    "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
-    "name TEXT UNIQUE NOT NULL, " +
-    "role TEXT, " +
-    "parent_id INTEGER, " +
-    "modseq_max INTEGER NOT NULL DEFAULT 0, " +
-    "uidvalidity INTEGER NOT NULL)"
-  ).run();
-  db.prepare(
-    "CREATE INDEX IF NOT EXISTS " + safeSql.quoteIdentifier(qFolders.slice(1, -1) + "_role_idx", "sqlite") +
-    " ON " + qFolders + "(role)"
-  ).run();
-
-  // Messages table — sealed-by-default subject / from / to / body.
-  db.prepare(
-    "CREATE TABLE IF NOT EXISTS " + qMsgs + " (" +
-    "objectid TEXT PRIMARY KEY, " +
-    "folder_id INTEGER NOT NULL, " +
-    "modseq INTEGER NOT NULL, " +
-    "internal_date INTEGER NOT NULL, " +
-    "received_at INTEGER NOT NULL, " +
-    "size_bytes INTEGER NOT NULL, " +
-    "message_id TEXT, " +
-    "message_id_hash TEXT, " +
-    "in_reply_to TEXT, " +
-    "references_csv TEXT, " +
-    "thread_root_id TEXT NOT NULL, " +
-    "subject TEXT, " +
-    "from_addr TEXT, " +
-    "from_hash TEXT, " +
-    "to_addrs TEXT, " +
-    "body_text TEXT, " +
-    "body_html TEXT, " +
-    "legal_hold INTEGER NOT NULL DEFAULT 0, " +
-    "FOREIGN KEY(folder_id) REFERENCES " + qFolders + "(id))"
-  ).run();
+  // `id` is an auto-increment PK (sqlite emits INTEGER PRIMARY KEY
+  // AUTOINCREMENT, the rowid-backed identity column).
+  _ddl(sql.createTable(foldersTable, [
+    { name: "id",          autoIncrement: true },
+    { name: "name",        type: "text", notNull: true, unique: true },
+    { name: "role",        type: "text" },
+    { name: "parent_id",   type: "int" },
+    { name: "modseq_max",  type: "int", notNull: true, default: 0 },
+    { name: "uidvalidity", type: "int", notNull: true },
+  ], DDL));
+  _ddl(sql.createIndex(foldersTable + "_role_idx", foldersTable, ["role"], DDL));
+
+  // Messages table — sealed-by-default subject / from / to / body. The
+  // folder_id FK inherits the quoteName so the referenced table resolves
+  // to the same concrete identifier.
+  _ddl(sql.createTable(messagesTable, [
+    { name: "objectid",        type: "text", primaryKey: true },
+    { name: "folder_id",       type: "int",  notNull: true,
+      references: { table: foldersTable, column: "id" } },
+    { name: "modseq",          type: "int",  notNull: true },
+    { name: "internal_date",   type: "int",  notNull: true },
+    { name: "received_at",     type: "int",  notNull: true },
+    { name: "size_bytes",      type: "int",  notNull: true },
+    { name: "message_id",      type: "text" },
+    { name: "message_id_hash", type: "text" },
+    { name: "in_reply_to",     type: "text" },
+    { name: "references_csv",  type: "text" },
+    { name: "thread_root_id",  type: "text", notNull: true },
+    { name: "subject",         type: "text" },
+    { name: "from_addr",       type: "text" },
+    { name: "from_hash",       type: "text" },
+    { name: "to_addrs",        type: "text" },
+    { name: "body_text",       type: "text" },
+    { name: "body_html",       type: "text" },
+    { name: "legal_hold",      type: "int",  notNull: true, default: 0 },
+  ], DDL));
   // Indexes — modseq for CONDSTORE, thread_root_id for thread fetch,
   // message_id_hash for threading lookup, from_hash for sender search.
   ["modseq", "thread_root_id", "message_id_hash", "from_hash", "received_at", "legal_hold"]
     .forEach(function (col) {
-      db.prepare(
-        "CREATE INDEX IF NOT EXISTS " + safeSql.quoteIdentifier(qMsgs.slice(1, -1) + "_" + col + "_idx", "sqlite") +
-        " ON " + qMsgs + "(" + safeSql.quoteIdentifier(col, "sqlite") + ")"
-      ).run();
+      _ddl(sql.createIndex(messagesTable + "_" + col + "_idx", messagesTable, [col], DDL));
     });
 
-  // Flags table — many-to-one with messages.
-  db.prepare(
-    "CREATE TABLE IF NOT EXISTS " + qFlags + " (" +
-    "objectid TEXT NOT NULL, " +
-    "flag TEXT NOT NULL, " +
-    "set_at INTEGER NOT NULL, " +
-    "PRIMARY KEY (objectid, flag), " +
-    "FOREIGN KEY(objectid) REFERENCES " + qMsgs + "(objectid) ON DELETE CASCADE)"
-  ).run();
+  // Flags table — many-to-one with messages. Composite (objectid, flag) PK
+  // + ON DELETE CASCADE FK back to the messages table.
+  _ddl(sql.createTable(flagsTable, [
+    { name: "objectid", type: "text", notNull: true,
+      references: { table: messagesTable, column: "objectid", onDelete: "CASCADE" } },
+    { name: "flag",     type: "text", notNull: true },
+    { name: "set_at",   type: "int",  notNull: true },
+  ], Object.assign({ primaryKey: ["objectid", "flag"] }, DDL)));
 
   // Quota table — per-folder counters bumped atomically with append/delete.
-  db.prepare(
-    "CREATE TABLE IF NOT EXISTS " + qQuota + " (" +
-    "folder_id INTEGER PRIMARY KEY, " +
-    "used_bytes INTEGER NOT NULL DEFAULT 0, " +
-    "used_count INTEGER NOT NULL DEFAULT 0, " +
-    "cap_bytes INTEGER, " +
-    "cap_count INTEGER, " +
-    "FOREIGN KEY(folder_id) REFERENCES " + qFolders + "(id))"
-  ).run();
+  _ddl(sql.createTable(quotaTable, [
+    { name: "folder_id",  type: "int", primaryKey: true,
+      references: { table: foldersTable, column: "id" } },
+    { name: "used_bytes", type: "int", notNull: true, default: 0 },
+    { name: "used_count", type: "int", notNull: true, default: 0 },
+    { name: "cap_bytes",  type: "int" },
+    { name: "cap_count",  type: "int" },
+  ], DDL));
 
   // Sealed-token FTS5 virtual table. The token-hash transform lives in
   // `lib/mail-store-fts.js`; this is the storage layer. Tokenizer is
   // `unicode61 remove_diacritics 2` so FTS5's segmenter splits hash-
   // tokens on whitespace exactly — hashes are ASCII-hex-only, so no
-  // Unicode case-fold runs at MATCH time.
-  db.prepare(mailStoreFts.createSql(qFts)).run();
+  // Unicode case-fold runs at MATCH time. objectid is UNINDEXED (the join
+  // key, stored but not searched).
+  _ddl(sql.createVirtualTable(ftsTable, {
+    columns: [
+      { name: "objectid", unindexed: true },
+      "subject_toks", "addr_toks", "body_toks",
+    ],
+    tokenize: "unicode61 remove_diacritics 2",
+  }));
 
   // Per-prefix key/value metadata table. Holds the FTS on-disk format
   // marker (`fts_format`) so the reindex path can detect a stale index
   // and rebuild it. Scoped per table-prefix (NOT PRAGMA user_version,
   // which is db-global and would collide across stores sharing one
   // sqlite file).
-  db.prepare(
-    "CREATE TABLE IF NOT EXISTS " + qMeta + " (" +
-    "key TEXT PRIMARY KEY, " +
-    "value TEXT)"
-  ).run();
+  _ddl(sql.createTable(metaTable, [
+    { name: "key",   type: "text", primaryKey: true },
+    { name: "value", type: "text" },
+  ], DDL));
 }
 
-function _ensureDefaultFolders(db, qFolders) {
-  var stmt = db.prepare("INSERT OR IGNORE INTO " + qFolders +
-    " (name, role, parent_id, modseq_max, uidvalidity) VALUES (?, ?, NULL, 0, ?)");
+function _ensureDefaultFolders(db, foldersTable) {
+  // INSERT OR IGNORE — composed as ON CONFLICT(name) DO NOTHING (the
+  // folders UNIQUE name) so re-bootstrapping an existing store is a no-op.
+  // Every column is a `?` placeholder bound positionally at run() (the
+  // builder emits one `?` per value; parent_id binds NULL, modseq_max 0).
+  var stmtText = sql.upsert(foldersTable, { dialect: "sqlite", quoteName: true })
+    .columns(["name", "role", "parent_id", "modseq_max", "uidvalidity"])
+    .values({ name: "?", role: "?", parent_id: "?", modseq_max: "?", uidvalidity: "?" })
+    .onConflict(["name"]).doNothing().toSql().sql;
+  var stmt = db.prepare(stmtText);
   var uv = Math.floor(Date.now() / 1000);                                                          // Unix timestamp, not bytes
-  DEFAULT_FOLDERS.forEach(function (f) { stmt.run(f.name, f.role, uv); });
+  DEFAULT_FOLDERS.forEach(function (f) { stmt.run(f.name, f.role, null, 0, uv); });
 }
 
 module.exports = {