@blamejs/blamejs-shop 0.4.30 → 0.4.32

package/lib/vendor/blamejs/lib/db.js

@@ -57,9 +57,11 @@ var { generateToken, generateBytes, encryptPacked, decryptPacked, sha3Hash } = r
 var cryptoField = require("./crypto-field");
 var dbDeclareRowPolicy = require("./db-declare-row-policy");
 var dbDeclareView = require("./db-declare-view");
-var { Query } = require("./db-query");
+var { Query, _isRawWriteToResidencyTable, _assertRawWriteResidency } = require("./db-query");
 var dbSchema = require("./db-schema");
 var { defineClass } = require("./framework-error");
+var frameworkFiles = require("./framework-files");
+var frameworkSchema = require("./framework-schema");
 var { boot } = require("./log");
 var lazyRequire = require("./lazy-require");
 var observability = require("./observability");
@@ -68,10 +70,18 @@ var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var validateOpts = require("./validate-opts");
 var vault = require("./vault");
 var vaultAad = require("./vault-aad");
 
+// b.sql opts for the local single-node sqlite handle (database.prepare,
+// never clusterStorage): "sqlite" dialect + quoteName so the resolved
+// framework table name quotes by construction. The few DML sites here that
+// target a framework state table resolve its name through
+// frameworkSchema.tableName so a configured table prefix flows through.
+var _SQL_OPTS = { dialect: "sqlite", quoteName: true };
+
 var DbError = defineClass("DbError", { alwaysPermanent: true });
 var WormViolationError = require("./framework-error").WormViolationError;
 var _wormErr = WormViolationError.factory;
@@ -173,27 +183,30 @@ var columnGateMode = "reject";
 // are provisioned by the framework before app schema reconciles. Apps cannot
 // opt out, override, or rename them. An app schema entry colliding with any of
 // these names is refused at init.
+// These are the canonical LOCAL reserved table-name declarations (the
+// guard set an operator schema may not collide with), NOT query SQL — the
+// literal names ARE the contract. allow:hand-rolled-sql markers below.
 var RESERVED_TABLE_NAMES = new Set([
   "audit_log",
   "audit_checkpoints",
   "consent_log",
-  "_blamejs_subject_restrictions",
-  "_blamejs_subject_erasures",
-  "_blamejs_sessions",
-  "_blamejs_jobs",
-  "_blamejs_migrations",
-  "_blamejs_counters",
-  "_blamejs_audit_purge_anchor",
-  "_blamejs_scheduler_ticks",
-  "_blamejs_rate_limit_counters",
-  "_blamejs_pubsub_messages",
-  "_blamejs_api_encrypt_nonces",
-  "_blamejs_api_keys",
-  "_blamejs_cache",
-  "_blamejs_seeders",
-  "_blamejs_seeders_lock",
-  "_blamejs_break_glass_policies",
-  "_blamejs_break_glass_grants",
+  "_blamejs_subject_restrictions",   // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_subject_erasures",       // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_sessions",               // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_jobs",                   // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_migrations",             // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_counters",               // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_audit_purge_anchor",     // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_scheduler_ticks",        // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_rate_limit_counters",    // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_pubsub_messages",        // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_api_encrypt_nonces",     // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_api_keys",               // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_cache",                  // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_seeders",                // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_seeders_lock",           // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_break_glass_policies",   // allow:hand-rolled-sql — canonical reserved local table-name declaration
+  "_blamejs_break_glass_grants",     // allow:hand-rolled-sql — canonical reserved local table-name declaration
 ]);
 
 var FRAMEWORK_SCHEMA = [
@@ -260,7 +273,7 @@ var FRAMEWORK_SCHEMA = [
     },
   },
   {
-    name: "_blamejs_subject_restrictions",
+    name: "_blamejs_subject_restrictions",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       subjectIdHash: "TEXT PRIMARY KEY",
       since:         "INTEGER NOT NULL",
@@ -269,7 +282,7 @@ var FRAMEWORK_SCHEMA = [
     sealedFields: ["reason"],
   },
   {
-    name: "_blamejs_subject_erasures",
+    name: "_blamejs_subject_erasures",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       subjectIdHash: "TEXT PRIMARY KEY",
       erasedAt:      "INTEGER NOT NULL",
@@ -281,7 +294,7 @@ var FRAMEWORK_SCHEMA = [
     // b.retention consult b.legalHold.isHeld(subjectId) before
     // accepting any deletion. Per FRCP Rule 26/37(e), GDPR Art
     // 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2).
-    name: "_blamejs_legal_hold",
+    name: "_blamejs_legal_hold",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       subjectIdHash: "TEXT PRIMARY KEY",
       placedAt:      "INTEGER NOT NULL",
@@ -291,15 +304,29 @@ var FRAMEWORK_SCHEMA = [
       citation:      "TEXT",
       retainUntil:   "INTEGER",
     },
+    // The legal-basis / custodian / ticket-citation free text links a data
+    // subject to a legal matter — PII at rest. Sealed like the DSR ticket store
+    // (b.legalHold seals on write + unseals on read through cryptoField).
+    sealedFields: ["reason", "placedBy", "custodian", "citation"],
     indexes: ["placedAt"],
   },
   {
     // Per-row crypto-erasure key registry — per-row keys.
-    // Each entry holds a sealed wrapped K_row keyed by (table,
-    // rowId). b.subject.eraseHard deletes the entry, leaving WAL /
-    // replica residuals undecryptable.
-    name: "_blamejs_per_row_keys",
+    // Each entry holds the AAD-sealed random row-secret keyed by
+    // (tableName, rowId); the row-scoped K_row is derived from it.
+    // b.subject.eraseHard / b.retention destroy the entry, leaving WAL /
+    // replica residuals undecryptable. wrappedKey is registered as an
+    // AAD-bound sealed field (aad:true, rowIdField:"rowId") so a vault
+    // keypair rotation auto-reseals it old-root -> new-root via
+    // rotate._rotateColumn — without this a rotation would orphan every
+    // wrapped secret and brick every keyed row.
+    name: "_blamejs_per_row_keys",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
+      // _id is the rotation pipeline's keyset-pagination + UPDATE key
+      // (rotate._rotateColumn SELECTs _id and orders by it); the natural
+      // identity stays the composite (tableName, rowId). materialize
+      // populates _id with a fresh token.
+      _id:        "TEXT",
       tableName:  "TEXT NOT NULL",
       rowId:      "TEXT NOT NULL",
       wrappedKey: "BLOB NOT NULL",
@@ -307,6 +334,10 @@ var FRAMEWORK_SCHEMA = [
     },
     primaryKey: ["tableName", "rowId"],
     indexes: [],
+    sealedFields:  ["wrappedKey"],
+    aad:           true,
+    rowIdField:    "rowId",
+    schemaVersion: "1",
   },
   {
     // Operator-declared WORM (write-once-read-many) registry. Each
@@ -314,7 +345,7 @@ var FRAMEWORK_SCHEMA = [
     // demanded the WORM declaration; boot-time assertions iterate
     // this registry to verify triggers are installed under the
     // current b.compliance.current() posture.
-    name: "_blamejs_worm_tables",
+    name: "_blamejs_worm_tables",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       tableName: "TEXT PRIMARY KEY",
       posture:   "TEXT",
@@ -327,7 +358,7 @@ var FRAMEWORK_SCHEMA = [
     // destructive ops; under the named posture the framework refuses
     // execution unless the caller passes a consumed dual-control
     // grant.
-    name: "_blamejs_dual_control_gates",
+    name: "_blamejs_dual_control_gates",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       tableName: "TEXT PRIMARY KEY",
       posture:   "TEXT",
@@ -354,7 +385,7 @@ var FRAMEWORK_SCHEMA = [
     sealedFields: [],
   },
   {
-    name: "_blamejs_audit_purge_anchor",
+    name: "_blamejs_audit_purge_anchor",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       // CHECK constraint: scope is one of the framework's audit-
       // chain anchor scopes (`audit` / `consent`). Pre-v0.8.37 a
@@ -376,7 +407,7 @@ var FRAMEWORK_SCHEMA = [
     // leader's INSERT loses with a constraint violation, and that node
     // skips the tick. Closes the once-globally gap during cluster
     // leader hand-offs where two leaders briefly coexist.
-    name: "_blamejs_scheduler_ticks",
+    name: "_blamejs_scheduler_ticks",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       tickKey:         "TEXT PRIMARY KEY",
       name:            "TEXT NOT NULL",
@@ -392,7 +423,7 @@ var FRAMEWORK_SCHEMA = [
     // the cluster-shared rate-limit backend. One row per (key); the
     // count rolls over atomically when the windowStart advances. Used
     // by lib/middleware/rate-limit.js when scope: 'cluster' is set.
-    name: "_blamejs_rate_limit_counters",
+    name: "_blamejs_rate_limit_counters",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       key:         "TEXT PRIMARY KEY",
       windowStart: "INTEGER NOT NULL",
@@ -408,7 +439,7 @@ var FRAMEWORK_SCHEMA = [
     // publish; other nodes poll for new ids and dispatch to their
     // local subscribers. Rows older than the configured retention
     // window are pruned by the backend on a rate-limited basis.
-    name: "_blamejs_pubsub_messages",
+    name: "_blamejs_pubsub_messages",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       id:          "INTEGER PRIMARY KEY AUTOINCREMENT",
       topic:       "TEXT NOT NULL",
@@ -426,7 +457,7 @@ var FRAMEWORK_SCHEMA = [
     // exposes the original 16-byte client nonces. Hashing is
     // deterministic so the PRIMARY KEY conflict is what catches a
     // replay attempt within the replay window.
-    name: "_blamejs_api_encrypt_nonces",
+    name: "_blamejs_api_encrypt_nonces",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       nonceHash: "TEXT PRIMARY KEY",
       expireAt:  "INTEGER NOT NULL",
@@ -435,7 +466,7 @@ var FRAMEWORK_SCHEMA = [
     sealedFields: [],
   },
   {
-    name: "_blamejs_sessions",
+    name: "_blamejs_sessions",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       sidHash:       "TEXT PRIMARY KEY",
       userId:        "TEXT NOT NULL",
@@ -456,7 +487,7 @@ var FRAMEWORK_SCHEMA = [
     // verify. Same dual-storage pattern as sessions: this row mirrors
     // the cluster-mode DDL in framework-schema.js so cluster-storage
     // can route to either backend transparently.
-    name: "_blamejs_api_keys",
+    name: "_blamejs_api_keys",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       id:                  "TEXT PRIMARY KEY",
       namespace:           "TEXT NOT NULL",
@@ -487,7 +518,7 @@ var FRAMEWORK_SCHEMA = [
     derivedHashes: { ownerIdHash: { from: "ownerId" } },
   },
   {
-    name: "_blamejs_jobs",
+    name: "_blamejs_jobs",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       _id:             "TEXT PRIMARY KEY",
       queueName:       "TEXT NOT NULL",
@@ -532,7 +563,7 @@ var FRAMEWORK_SCHEMA = [
     // JSON-serialized; expiresAt is unix-ms (Number.MAX_SAFE_INTEGER for
     // never-expiring entries). Not sealed: cache values are operator-
     // chosen application data, the operator decides what's worth storing.
-    name: "_blamejs_cache",
+    name: "_blamejs_cache",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       cacheKey:   "TEXT PRIMARY KEY",
       valueJson:  "TEXT NOT NULL",
@@ -548,7 +579,7 @@ var FRAMEWORK_SCHEMA = [
     // PK (cacheKey, tag) lets one cacheKey carry many tags; index on
     // tag makes invalidation a single indexed scan. Cleared together
     // with the matching _blamejs_cache rows on del / clear / sweep.
-    name: "_blamejs_cache_tags",
+    name: "_blamejs_cache_tags",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       cacheKey:   "TEXT NOT NULL",
       tag:        "TEXT NOT NULL",
@@ -564,7 +595,7 @@ var FRAMEWORK_SCHEMA = [
     // collide with prod fixtures by name). rerunnable=1 entries get
     // their appliedAt updated in place on every run; non-rerunnable
     // entries are insert-once.
-    name: "_blamejs_seeders",
+    name: "_blamejs_seeders",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       env:         "TEXT NOT NULL",
       name:        "TEXT NOT NULL",
@@ -582,7 +613,7 @@ var FRAMEWORK_SCHEMA = [
     // on scope='lock' enforces single row). Two processes calling
     // `seed run` against the same DB race on this PK; loser sees a
     // clear "lock held" error.
-    name: "_blamejs_seeders_lock",
+    name: "_blamejs_seeders_lock",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       scope:    "TEXT PRIMARY KEY CHECK (scope = 'lock')",
       lockedAt: "INTEGER NOT NULL",
@@ -596,7 +627,7 @@ var FRAMEWORK_SCHEMA = [
     // glass-locked and what the operator's grant rules are. Sealed
     // columns hold the column-list, factor-list, and bypass config so
     // policy contents aren't browsable in cleartext.
-    name: "_blamejs_break_glass_policies",
+    name: "_blamejs_break_glass_policies",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       tableName:                  "TEXT PRIMARY KEY",
       columnsJson:                "TEXT NOT NULL",
@@ -625,7 +656,7 @@ var FRAMEWORK_SCHEMA = [
     // (each row access = its own grant).
     // Sealed columns hold reason + scopeColumns so audit-readable
     // metadata doesn't leak in cleartext.
-    name: "_blamejs_break_glass_grants",
+    name: "_blamejs_break_glass_grants",   // allow:hand-rolled-sql — canonical local-schema table-name declaration
     columns: {
       _id:                "TEXT PRIMARY KEY",
       issuedToActorId:    "TEXT NOT NULL",
@@ -688,7 +719,7 @@ function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
   // needs to live outside `dataDir` (e.g. a separate volume mounted
   // from a KMS-fronted secret store). Default places it next to the
   // encrypted DB so backup capture is one-tarball.
-  var keyPath = keyPathOverride || nodePath.join(dataDirPath, "db.key.enc");
+  var keyPath = keyPathOverride || nodePath.join(dataDirPath, frameworkFiles.fileName("dbKeyEnc"));
   var aad = _dbKeyAad(dataDirPath, keyPath);
   if (nodeFs.existsSync(keyPath)) {
     var sealed = atomicFile.readSync(keyPath, { encoding: "utf8" }).trim();
@@ -956,6 +987,7 @@ function cleanStaleTmpDbs(tmpDir) {
  *   schema:                  Array,             // required — [{ name, columns, indexes, sealedFields, derivedHashes, foreignKeys, primaryKey, subjectField, personalDataCategories }, ...]
  *   atRest:                  "encrypted"|"plain", // default "encrypted"
  *   tmpDir:                  string,            // override the encrypted-mode tmpfs path (default /dev/shm or BLAMEJS_TMPDIR)
+ *   allowNonTmpfsTmpDir:     boolean,           // default false — encrypted mode THROWS when tmpDir is not a recognized tmpfs mount (plaintext-on-disk leak); pass true to downgrade to a warning when the mount is verified in-memory out-of-band
  *   migrationDir:            string,            // optional — path to ./migrations/ (run-once each)
  *   streamLimit:             number,            // default 1_000_000 — db.stream row ceiling
  *   columnGate:              "reject"|"warn"|"off", // default "reject" — refuse queries on columns not declared in the table schema
@@ -1028,6 +1060,15 @@ async function init(opts) {
       JSON.stringify(opts.columnGate));
   }
   columnGateMode = opts.columnGate || "reject";
+  // Configurable framework-table prefix. Config-time: setTablePrefix
+  // throws a FrameworkSchemaError on a non-identifier prefix so a typo
+  // surfaces at boot rather than as a silently-misnamed table. Applied
+  // BEFORE any schema creation below so framework DDL + the cluster
+  // tableName resolver honor it. Default ("_blamejs_") is byte-identical
+  // to the historical names, so omitting the option is a no-op.
+  if (opts.tablePrefix !== undefined) {
+    frameworkSchema.setTablePrefix(opts.tablePrefix);
+  }
   dataDir = opts.dataDir;
   if (!nodeFs.existsSync(dataDir)) nodeFs.mkdirSync(dataDir, { recursive: true });
 
@@ -1040,21 +1081,42 @@ async function init(opts) {
     }
     if (!nodeFs.existsSync(tmpDir)) nodeFs.mkdirSync(tmpDir, { recursive: true });
 
-    // If the resolved tmpDir is NOT actually tmpfs, the
-    // plaintext DB file lives on persistent storage. We check that tmpDir
-    // resolves under /dev/shm or /run/shm on Linux as a heuristic; on other
-    // platforms we warn that the operator must verify tmpfs binding
-    // out-of-band. (Free-space headroom is enforced separately via
-    // fs.statfsSync in the storage guard below.)
+    // If the resolved tmpDir is NOT actually tmpfs, the plaintext working
+    // copy lives on persistent storage and leaks into backup snapshots,
+    // replication, and forensic disk images — defeating the whole point of
+    // encrypted-at-rest mode. On Linux we verify the resolved path lands
+    // under a known in-memory mount (/dev/shm /run/shm /run/user, plus
+    // /tmp which is tmpfs on systemd-default + most container images).
+    //
+    // Fail-closed default (v0.15.0): a tmpDir that resolves OUTSIDE those
+    // mounts THROWS db/tmpdir-not-tmpfs at boot rather than logging a
+    // warning the operator never reads — the prior warn-only path silently
+    // shipped plaintext to disk under the encrypted-mode default. The
+    // documented opt-out is opts.allowNonTmpfsTmpDir: true, for the operator
+    // who has verified the mount is in-memory out-of-band (e.g. a ramfs /
+    // a tmpfs bind-mounted at a non-standard path the heuristic can't see)
+    // or who has accepted the disk-residency tradeoff. The opt-out downgrades
+    // to the prior warning. (Free-space headroom is enforced separately via
+    // fs.statfsSync in the storage guard below.) The heuristic is Linux-only;
+    // other platforms can't be probed by path and emit the warning unchanged.
     if (process.platform === "linux") {
       var realTmp = "";
       try { realTmp = nodeFs.realpathSync(tmpDir); } catch (_e) { /* stat best-effort */ }
       if (realTmp.indexOf("/dev/shm") !== 0 && realTmp.indexOf("/run/shm") !== 0 &&
           realTmp.indexOf("/run/user/") !== 0 && realTmp.indexOf("/tmp") !== 0) {
-        log.warn("WARNING: db.init: tmpDir '" + tmpDir + "' (real: '" + realTmp +
-          "') does not resolve under /dev/shm /run/shm /run/user /tmp — verify it is " +
-          "actually a tmpfs mount. A persistent-disk tmpDir leaks plaintext into backup " +
-          "snapshots, replication, and forensic disk images.");
+        var tmpfsMsg = "db.init: tmpDir '" + tmpDir + "' (real: '" + realTmp +
+          "') does not resolve under /dev/shm /run/shm /run/user /tmp — it is not a " +
+          "recognized tmpfs mount. A persistent-disk tmpDir leaks the decrypted " +
+          "working copy into backup snapshots, replication, and forensic disk images.";
+        if (opts.allowNonTmpfsTmpDir === true) {
+          log.warn("WARNING: " + tmpfsMsg + " (allowNonTmpfsTmpDir:true — verify the " +
+            "mount is in-memory out-of-band.)");
+        } else {
+          throw _dbErr("db/tmpdir-not-tmpfs", "FATAL: " + tmpfsMsg +
+            " Mount a tmpfs at the path (or set BLAMEJS_TMPDIR / opts.tmpDir to one), " +
+            "or pass opts.allowNonTmpfsTmpDir: true to accept the disk-residency tradeoff, " +
+            "or pass atRest: 'plain' if encryption-at-rest is not required.");
+        }
       }
     }
 
@@ -1063,7 +1125,7 @@ async function init(opts) {
     // just the basename under `dataDir` (default "db.enc"). Helps when
     // multiple framework-shaped instances share a dataDir.
     encPath = opts.encryptedDbPath ||
-              nodePath.join(dataDir, opts.encryptedDbName || "db.enc");
+              nodePath.join(dataDir, opts.encryptedDbName || frameworkFiles.fileName("dbEnc"));
     dbPath  = nodePath.join(tmpDir, "blamejs-" + generateToken(C.BYTES.bytes(16)) + ".db");
     encKey  = loadOrCreateDbKey(dataDir, opts.dbKeyPath);
 
@@ -1624,6 +1686,27 @@ var _prepareCache = new Map();
  *   typeof row.total;
  *   // → "object"
  */
+// Wrap a prepared statement that writes to a per-row-residency table so its
+// execution (run / get / all / iterate) validates the residency tag of the
+// bound row through the same gate the structured builder uses. Only residency
+// writes are wrapped (cheap prepare-time pre-check) so the common path is
+// untouched.
+function _gatedResidencyStmt(stmt, sql) {
+  var EXEC = { run: true, get: true, all: true, iterate: true };
+  return new Proxy(stmt, {
+    get: function (target, prop) {
+      var v = target[prop];
+      if (typeof prop === "string" && EXEC[prop] && typeof v === "function") {
+        return function () {
+          _assertRawWriteResidency(sql, Array.prototype.slice.call(arguments));
+          return v.apply(target, arguments);
+        };
+      }
+      return typeof v === "function" ? v.bind(target) : v;
+    },
+  });
+}
+
 function prepare(sql) {
   _requireInit();
   if (_prepareCache.has(sql)) {
@@ -1634,6 +1717,7 @@ function prepare(sql) {
     return hit;
   }
   var stmt = database.prepare(sql);
+  if (_isRawWriteToResidencyTable(sql)) stmt = _gatedResidencyStmt(stmt, sql);
   _prepareCache.set(sql, stmt);
   if (_prepareCache.size > PREPARE_CACHE_MAX) {
     var oldestKey = _prepareCache.keys().next().value;
@@ -1796,6 +1880,9 @@ function _reportSlowSqlite(durationMs, statement) {
 
 function execRaw(sql) {
   _requireInit();
+  // Raw writes bypass the structured builder's residency gate; validate the
+  // residency tag of an INSERT / UPDATE to a per-row-residency table here too.
+  _assertRawWriteResidency(sql);
   var startedAt = Date.now();
   var auditMod = (function () { try { return require("./audit"); } catch (_e) { return null; } })(); // allow:inline-require — circular-load defense (audit imports db)
   // DDL_RE only matches the leading keyword — bounded by `/\s*(KEYWORD)\b/`
@@ -1926,6 +2013,31 @@ function hashFor(table, field, value) {
   return lookup ? lookup.value : null;
 }
 
+/**
+ * @primitive b.db.hashCandidatesFor
+ * @signature b.db.hashCandidatesFor(table, field, value)
+ * @since     0.15.1
+ * @status    stable
+ * @related   b.db.hashFor, b.db.from
+ *
+ * Dual-read sibling of `hashFor`. Returns `{ field, values }` where `values`
+ * holds the active derived-hash digest AND — across the v0.15.0 keyed-MAC
+ * default flip — the legacy salted-sha3 digest a row written before the flip
+ * carries. A `WHERE <hashColumn> IN (...)` lookup over `values` matches both
+ * keyed-indexed and legacy-indexed rows, so the flip never silently drops an
+ * un-migrated row. Returns `null` when the field has no derived-hash
+ * declaration on the table.
+ *
+ * @example
+ *   var c = b.db.hashCandidatesFor("users", "email", "alice@example.com");
+ *   b.db.from("users").whereIn(c.field, c.values).all();
+ *   // → rows matching either the keyed-MAC or the legacy digest
+ */
+function hashCandidatesFor(table, field, value) {
+  _requireInit();
+  return cryptoField.lookupHashCandidates(table, field, value);
+}
+
 // _ddlToJsonSchemaType — best-effort SQL→JSON Schema type mapping.
 // SQLite is dynamically typed but the framework's DDL syntax pins
 // concrete types; we map them here. Operator-supplied custom types
@@ -2250,21 +2362,24 @@ function _normalizePk(tableSpec) {
 // that RAISE(ABORT) the operation. INSERT remains permitted (that's what
 // audit.record / consent.grant do).
 function _installAppendOnlyTriggers(database) {
+  // b.sql has no CREATE TRIGGER builder — these append-only WORM triggers
+  // are SQLite-specific (RAISE(ABORT) trigger bodies) over framework-
+  // controlled, fixed table names. Identifiers are quoted by construction.
   var tables = ["audit_log", "consent_log", "audit_checkpoints"];
   for (var i = 0; i < tables.length; i++) {
     var t = tables[i];
     runSql(database,
-      'CREATE TRIGGER IF NOT EXISTS "no_delete_' + t + '" ' +
+      'CREATE TRIGGER IF NOT EXISTS "no_delete_' + t + '" ' +     // allow:hand-rolled-sql — b.sql has no CREATE TRIGGER builder; SQLite append-only WORM trigger, fixed framework table
       'BEFORE DELETE ON "' + t + '" ' +
       'BEGIN ' +
-      "  SELECT RAISE(ABORT, '" + t + " is append-only — DELETE prohibited'); " +
+      "  SELECT RAISE(ABORT, '" + t + " is append-only — DELETE prohibited'); " +   // allow:hand-rolled-sql — RAISE(ABORT) trigger body, not a query
       'END'
     );
     runSql(database,
-      'CREATE TRIGGER IF NOT EXISTS "no_update_' + t + '" ' +
+      'CREATE TRIGGER IF NOT EXISTS "no_update_' + t + '" ' +     // allow:hand-rolled-sql — b.sql has no CREATE TRIGGER builder; SQLite append-only WORM trigger, fixed framework table
       'BEFORE UPDATE ON "' + t + '" ' +
       'BEGIN ' +
-      "  SELECT RAISE(ABORT, '" + t + " is append-only — UPDATE prohibited'); " +
+      "  SELECT RAISE(ABORT, '" + t + " is append-only — UPDATE prohibited'); " +   // allow:hand-rolled-sql — RAISE(ABORT) trigger body, not a query
       'END'
     );
   }
@@ -2277,19 +2392,22 @@ function _installAppendOnlyTriggers(database) {
 // boot-time assertion under WORM_POSTURES catches operators who
 // set the posture without declaring tables.
 function _installWormTriggers(database, tableName) {
+  // b.sql has no CREATE TRIGGER builder — operator-table WORM triggers are
+  // SQLite-specific RAISE(ABORT) trigger bodies; tableName is validated
+  // (validateIdentifier) and quoted by construction.
   safeSql.validateIdentifier(tableName);
   runSql(database,
-    'CREATE TRIGGER IF NOT EXISTS "worm_no_delete_' + tableName + '" ' +
+    'CREATE TRIGGER IF NOT EXISTS "worm_no_delete_' + tableName + '" ' +   // allow:hand-rolled-sql — b.sql has no CREATE TRIGGER builder; SQLite WORM trigger over validated operator table
     'BEFORE DELETE ON "' + tableName + '" ' +
     'BEGIN ' +
-    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - DELETE prohibited'); " +
+    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - DELETE prohibited'); " +   // allow:hand-rolled-sql — RAISE(ABORT) trigger body, not a query
     'END'
   );
   runSql(database,
-    'CREATE TRIGGER IF NOT EXISTS "worm_no_update_' + tableName + '" ' +
+    'CREATE TRIGGER IF NOT EXISTS "worm_no_update_' + tableName + '" ' +   // allow:hand-rolled-sql — b.sql has no CREATE TRIGGER builder; SQLite WORM trigger over validated operator table
     'BEFORE UPDATE ON "' + tableName + '" ' +
     'BEGIN ' +
-    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - UPDATE prohibited'); " +
+    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - UPDATE prohibited'); " +   // allow:hand-rolled-sql — RAISE(ABORT) trigger body, not a query
     'END'
   );
 }
@@ -2355,9 +2473,8 @@ function declareWorm(args) {
       "the SQLite trigger primitive is single-node only");
   }
   var nowMs = Date.now();
-  var ins = database.prepare(
-    'INSERT OR REPLACE INTO "_blamejs_worm_tables" (tableName, posture, declaredAt) VALUES (?, ?, ?)'
-  );
+  // allow:hand-rolled-sql — logical name resolved through frameworkSchema.tableName (the prescribed prefix-aware indirection)
+  var wormTable = frameworkSchema.tableName("_blamejs_worm_tables");
   for (var j = 0; j < args.tables.length; j++) {
     var t = args.tables[j];
     if (t === "audit_log" || t === "consent_log" || t === "audit_checkpoints") {
@@ -2366,7 +2483,14 @@ function declareWorm(args) {
         "use audit-tools.purge for sanctioned deletions");
     }
     _installWormTriggers(database, t);
-    ins.run(t, args.posture || null, nowMs);
+    // INSERT-or-replace on the tableName PK: b.sql upsert emits the
+    // portable ON CONFLICT DO UPDATE form (same replace-on-PK semantics
+    // as the prior INSERT OR REPLACE).
+    var wormUp = sql.upsert(wormTable, _SQL_OPTS)
+      .values({ tableName: t, posture: args.posture || null, declaredAt: nowMs })
+      .onConflict(["tableName"]).doUpdateFromExcluded(["posture", "declaredAt"]).toSql();
+    var wormStmt = database.prepare(wormUp.sql);
+    wormStmt.run.apply(wormStmt, wormUp.params);
     audit.safeEmit({
       action:   "db.worm.declared",
       outcome:  "success",
@@ -2383,9 +2507,11 @@ function _assertWormUnderPosture() {
   if (cluster.isClusterMode()) return;
   var rows;
   try {
-    rows = database.prepare(
-      'SELECT tableName FROM "_blamejs_worm_tables"'
-    ).all();
+    // allow:hand-rolled-sql — logical name resolved through frameworkSchema.tableName (prefix-aware), composed via b.sql
+    var wormSel = sql.select(frameworkSchema.tableName("_blamejs_worm_tables"), _SQL_OPTS)
+      .columns(["tableName"]).toSql();
+    var wormSelStmt = database.prepare(wormSel.sql);
+    rows = wormSelStmt.all.apply(wormSelStmt, wormSel.params);
   } catch (_e) { rows = []; }
   if (!rows || rows.length === 0) {
     throw _wormErr("POSTURE_VIOLATION",
@@ -2459,12 +2585,17 @@ function declareRequireDualControl(args) {
       "declareRequireDualControl: args.posture must be a non-empty string or null");
   }
   var nowMs = Date.now();
-  var ins = database.prepare(
-    'INSERT OR REPLACE INTO "_blamejs_dual_control_gates" ' +
-    '(tableName, posture, m, n, declaredAt) VALUES (?, ?, ?, ?, ?)'
-  );
+  // allow:hand-rolled-sql — logical name resolved through frameworkSchema.tableName (the prescribed prefix-aware indirection)
+  var gatesTable = frameworkSchema.tableName("_blamejs_dual_control_gates");
   for (var j = 0; j < args.tables.length; j++) {
-    ins.run(args.tables[j], args.posture || null, m, n, nowMs);
+    // INSERT-or-replace on the tableName PK via b.sql upsert (same
+    // replace-on-PK semantics as the prior INSERT OR REPLACE).
+    var gateUp = sql.upsert(gatesTable, _SQL_OPTS)
+      .values({ tableName: args.tables[j], posture: args.posture || null,
+                m: m, n: n, declaredAt: nowMs })
+      .onConflict(["tableName"]).doUpdateFromExcluded(["posture", "m", "n", "declaredAt"]).toSql();
+    var gateStmt = database.prepare(gateUp.sql);
+    gateStmt.run.apply(gateStmt, gateUp.params);
     audit.safeEmit({
       action:   "db.dual_control.declared",
       outcome:  "success",
@@ -2479,9 +2610,11 @@ function _checkDualControlGate(tableName) {
   if (cluster.isClusterMode()) return null;
   var row;
   try {
-    row = database.prepare(
-      'SELECT tableName, posture, m, n FROM "_blamejs_dual_control_gates" WHERE tableName = ?'
-    ).get(tableName);
+    // allow:hand-rolled-sql — logical name resolved through frameworkSchema.tableName (prefix-aware), composed via b.sql
+    var gateSel = sql.select(frameworkSchema.tableName("_blamejs_dual_control_gates"), _SQL_OPTS)
+      .columns(["tableName", "posture", "m", "n"]).where("tableName", tableName).toSql();
+    var gateSelStmt = database.prepare(gateSel.sql);
+    row = gateSelStmt.get.apply(gateSelStmt, gateSel.params);
   } catch (_e) { return null; }
   return row || null;
 }
@@ -2568,16 +2701,18 @@ function eraseHard(tableName, rowId, opts) {
   var t0 = Date.now();
   var deleted = 0;
   transaction(function () {
-    var row = database.prepare(
-      'SELECT * FROM "' + tableName + '" WHERE _id = ?'
-    ).get(rowId);
+    // tableName is an operator app table (validateIdentifier'd above), not
+    // a framework table, so it is NOT routed through tableName(); b.sql
+    // quotes it by construction (quoteName) on the local sqlite handle.
+    var rowSel = sql.select(tableName, _SQL_OPTS).where("_id", rowId).toSql();
+    var rowSelStmt = database.prepare(rowSel.sql);
+    var row = rowSelStmt.get.apply(rowSelStmt, rowSel.params);
     if (row) {
       try { cryptoField.eraseRow(tableName, row); } catch (_e) { /* table may have no sealed cols */ }
     }
-    var del = database.prepare(
-      'DELETE FROM "' + tableName + '" WHERE _id = ?'
-    );
-    var result = del.run(rowId);
+    var rowDel = sql.delete(tableName, _SQL_OPTS).where("_id", rowId).toSql();
+    var rowDelStmt = database.prepare(rowDel.sql);
+    var result = rowDelStmt.run.apply(rowDelStmt, rowDel.params);
     deleted = (result && result.changes) || 0;
     // REINDEX rebuilds every index on the table from scratch,
     // dropping the B-tree pages that held the deleted row's index
@@ -2603,7 +2738,7 @@ function eraseHard(tableName, rowId, opts) {
 // Read the audit.tip sidecar file in dataDir and compare to the current
 // audit_log MAX(monotonicCounter). Refuse boot on rollback (current < tip).
 function _checkRollback(dataDirPath) {
-  var tipPath = nodePath.join(dataDirPath, "audit.tip");
+  var tipPath = nodePath.join(dataDirPath, frameworkFiles.fileName("auditTip"));
   if (!nodeFs.existsSync(tipPath)) {
     log("no audit.tip sidecar — skipping rollback check (first boot or operator-cleared)");
     return;
@@ -2617,7 +2752,12 @@ function _checkRollback(dataDirPath) {
       ". Either delete it (forfeits rollback protection until next checkpoint) " +
       "or restore from operator backup.");
   }
-  var current = database.prepare("SELECT MAX(monotonicCounter) AS m FROM audit_log").get();
+  // The local-SQLite chain table is named "audit_log" (its external-db
+  // counterpart _blamejs_audit_log is the cluster path, handled elsewhere),
+  // so the local read uses that literal name; b.sql quotes it (quoteName).
+  var maxQ = sql.select("audit_log", _SQL_OPTS).max("monotonicCounter", "m").toSql();
+  var maxStmt = database.prepare(maxQ.sql);
+  var current = maxStmt.get.apply(maxStmt, maxQ.params);
   var currentMax = current && current.m ? current.m : 0;
   if (currentMax < tip.atMonotonicCounter) {
     events.emit(events.EVENTS.AUDIT_ROLLBACK_DETECTED, {
@@ -3168,6 +3308,7 @@ module.exports = {
   ["e" + "xec"]:        execRaw,
   transaction:         transaction,
   hashFor:             hashFor,
+  hashCandidatesFor:   hashCandidatesFor,
   close:               close,
   // flushToDisk — force the live tmpfs SQLite to be re-encrypted to
   // <dataDir>/db.enc immediately. In encrypted-at-rest mode the
@@ -3276,30 +3417,39 @@ module.exports = {
     }
     if (cluster.isClusterMode()) {
       // External-db has no append-only triggers; ordinary DELETE works.
+      // clusterStorage.execute rewrites the BARE logical table name to its
+      // cluster-prefixed form and placeholderizes ?→$N, so b.sql emits the
+      // bare name (no quoteName) here.
       var cs = clusterStorage();
-      var d = await cs.execute(
-        "DELETE FROM audit_log WHERE monotonicCounter <= ?", [lastPurgedCounter]
-      );
-      var dc = await cs.execute(
-        "DELETE FROM audit_checkpoints WHERE atMonotonicCounter <= ?", [lastPurgedCounter]
-      );
+      var clusterLogDel = sql.delete("audit_log")
+        .where("monotonicCounter", "<=", lastPurgedCounter).toSql();
+      var d = await cs.execute(clusterLogDel.sql, clusterLogDel.params);
+      var clusterChkDel = sql.delete("audit_checkpoints")
+        .where("atMonotonicCounter", "<=", lastPurgedCounter).toSql();
+      var dc = await cs.execute(clusterChkDel.sql, clusterChkDel.params);
       return { rowsDeleted: d.rowCount || 0, checkpointsDeleted: dc.rowCount || 0 };
     }
     // Single-node: drop triggers, delete, recreate triggers — all in
     // one transaction so a crash mid-operation doesn't leave the
-    // table writable to general code.
+    // table writable to general code. The local chain tables are named
+    // "audit_log" / "audit_checkpoints" (no _blamejs_ prefix locally);
+    // b.sql quotes them (quoteName) on the local handle.
     var rowsDeleted = 0;
     var checkpointsDeleted = 0;
     transaction(function () {
+      // allow:hand-rolled-sql — b.sql has no DROP TRIGGER builder; framework-controlled trigger name, append-only re-installed below
       runSql(database, 'DROP TRIGGER IF EXISTS "no_delete_audit_log"');
+      // allow:hand-rolled-sql — b.sql has no DROP TRIGGER builder; framework-controlled trigger name, append-only re-installed below
       runSql(database, 'DROP TRIGGER IF EXISTS "no_delete_audit_checkpoints"');
-      var d = database.prepare(
-        "DELETE FROM audit_log WHERE monotonicCounter <= ?"
-      ).run(lastPurgedCounter);
+      var logDel = sql.delete("audit_log", _SQL_OPTS)
+        .where("monotonicCounter", "<=", lastPurgedCounter).toSql();
+      var logDelStmt = database.prepare(logDel.sql);
+      var d = logDelStmt.run.apply(logDelStmt, logDel.params);
       rowsDeleted = (d && d.changes) || 0;
-      var dc = database.prepare(
-        "DELETE FROM audit_checkpoints WHERE atMonotonicCounter <= ?"
-      ).run(lastPurgedCounter);
+      var chkDel = sql.delete("audit_checkpoints", _SQL_OPTS)
+        .where("atMonotonicCounter", "<=", lastPurgedCounter).toSql();
+      var chkDelStmt = database.prepare(chkDel.sql);
+      var dc = chkDelStmt.run.apply(chkDelStmt, chkDel.params);
       checkpointsDeleted = (dc && dc.changes) || 0;
       _installAppendOnlyTriggers(database);
     });
@@ -3401,7 +3551,7 @@ module.exports = {
   // Helper for audit.checkpoint to write the rollback-detection sidecar
   _writeAuditTip: function (tip) {
     if (!dataDir) return;
-    var tipPath = nodePath.join(dataDir, "audit.tip");
+    var tipPath = nodePath.join(dataDir, frameworkFiles.fileName("auditTip"));
     atomicFile.writeSync(tipPath, JSON.stringify(tip, null, 2), { fileMode: 0o600 });
   },
 };