@blamejs/core 0.14.26 → 0.15.0

package/lib/cluster.js

@@ -50,16 +50,88 @@ var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
-var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
 var validateOpts = require("./validate-opts");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
+// The external-DB schema quotes every column identifier, so Postgres
+// stores them case-preserving. The boot-time chain-tip + vault-key-
+// consistency statements compose through b.sql, which quotes every
+// identifier by construction (double-quote on Postgres / SQLite, backtick
+// on MySQL) so an unquoted fold-to-lowercase reference can't miss the
+// column.
+
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
 // loaded before its init has run; both are safe to call once cluster
 // reaches runtime, but eager require here would deadlock the load order.
 var externalDb = lazyRequire(function () { return require("./external-db"); });
 var vault = lazyRequire(function () { return require("./vault"); });
+// b.sql builder + the `?`->`$N` placeholderizer + the framework-table
+// name resolver. clusterStorage requires cluster, so these are lazy to
+// stay clear of the load cycle; resolved at runtime when the boot-time
+// rollback / vault-key-consistency checks run.
+var sql = lazyRequire(function () { return require("./sql"); });
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+var frameworkSchema = lazyRequire(function () { return require("./framework-schema"); });
+
+// b.sql speaks postgres | sqlite | mysql; the cluster's configuredDialect
+// is one of those (validated at init). Used so the boot-time chain-tip /
+// vault-key-consistency statements emit the right identifier quoting.
+function _bDialect() {
+  return configuredDialect === "mysql" ? "mysql"
+       : configuredDialect === "sqlite" ? "sqlite" : "postgres";
+}
+
+// Emit a b.sql builder + run it against the configured external-DB
+// backend. b.sql emits `?` placeholders; the externalDb driver receives
+// the SQL verbatim, so translate to `$N` for Postgres (passthrough for
+// SQLite / MySQL).
+function _runClusterQuery(builder) {
+  var built = builder.toSql();
+  return externalDb().query(
+    clusterStorage().placeholderize(built.sql, configuredDialect),
+    built.params,
+    { backend: configuredExternalDbBackend }
+  );
+}
+
+// "The framework-internal table this check needs does not exist yet" —
+// the signal that a gates-only cluster (leader election wired, but
+// framework state still resident in per-node SQLite without
+// frameworkSchema.ensureSchema) should SKIP the boot-time rollback /
+// vault-key-consistency check instead of FATAL-refusing boot. Each
+// backend phrases the missing-relation fault differently, and not all
+// drivers carry a stable structured code, so this matches BOTH the
+// driver phrasing AND the portable code/SQLSTATE when present:
+//
+//   - SQLite:    "no such table: X"
+//   - Postgres:  "relation "X" does not exist"  (SQLSTATE 42P01)
+//   - MySQL:     "Table 'db.X' doesn't exist"   (errno 1146, SQLSTATE 42S02)
+//
+// The earlier message-only test recognized the SQLite/Postgres phrasing
+// ("no such table" / "does not exist") but NOT MySQL's "doesn't exist"
+// (the apostrophe-contracted form), so a gates-only MySQL cluster boot
+// mis-fired the skip and surfaced ER_NO_SUCH_TABLE instead of completing.
+function _isMissingTableError(e) {
+  if (!e) return false;
+  // Structured code / SQLSTATE first — driver-stable, locale-independent.
+  // mysql2-shape: e.errno === 1146 / e.code === "ER_NO_SUCH_TABLE";
+  // the docker-exec shim + ANSI drivers surface SQLSTATE 42S02 (MySQL) /
+  // 42P01 (Postgres) on e.code / e.sqlState.
+  var code     = (e.code != null) ? String(e.code) : "";
+  var sqlState = (e.sqlState != null) ? String(e.sqlState) : "";
+  if (e.errno === 1146) return true;
+  if (code === "ER_NO_SUCH_TABLE" || code === "42S02" || code === "42P01" ||
+      sqlState === "42S02" || sqlState === "42P01") {
+    return true;
+  }
+  // Driver phrasing fallback. "doesn't exist" (MySQL apostrophe form) is
+  // covered alongside "does not exist" (Postgres) and "no such table"
+  // (SQLite). The MySQL message embeds the table name in quotes, so the
+  // bare "doesn't exist" substring is the portable anchor.
+  var msg = e.message || "";
+  return /no such table|does not exist|doesn't exist|relation .* does not exist/i.test(msg);
+}
 
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
@@ -324,8 +396,16 @@ async function init(opts) {
   // framework state — the operator owns rollback detection in that
   // case.
   if (configuredExternalDbBackend) {
-    await _checkChainTipRollback("audit",   "_blamejs_audit_log",   "_blamejs_audit_tip");
-    await _checkChainTipRollback("consent", "_blamejs_consent_log", "_blamejs_consent_tip");
+    // Resolve the chain + tip table names through frameworkSchema so the
+    // configurable framework-table prefix is honored (the names are
+    // `_blamejs_`-prefixed and self-mapped, so the resolve is a no-op under
+    // the default prefix).
+    await _checkChainTipRollback("audit",
+      frameworkSchema().tableName("audit_log"),                                   // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_audit_tip"));                         // allow:hand-rolled-sql — logical-name reference
+    await _checkChainTipRollback("consent",
+      frameworkSchema().tableName("consent_log"),                                 // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_consent_tip"));                       // allow:hand-rolled-sql — logical-name reference
     // Vault-key consistency: every node in a cluster must hold the
     // SAME vault key. A node booting with a different key would seal
     // new writes under a key the rest of the cluster can't unseal,
@@ -373,26 +453,16 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
-  // Both tables are framework-internal constants from the call sites
-  // (`_blamejs_audit_log`, `_blamejs_consent_log`, etc.). Validate +
-  // quote per the framework's identifier-quoting convention so a
-  // future rename can't silently break the query.
-  safeSql.validateIdentifier(logTable, { allowReserved: true });
-  safeSql.validateIdentifier(tipTable, { allowReserved: true });
-  var qLogTable = safeSql.quoteIdentifier(logTable);
-  var qTipTable = safeSql.quoteIdentifier(tipTable);
-
+  // Both tables are framework-internal constants resolved at the call
+  // sites through frameworkSchema. b.sql quotes every identifier by
+  // construction; the dialect-final SQL is placeholderized to `$N` for
+  // Postgres (passthrough for SQLite).
   var tipRows;
   try {
-    tipRows = await externalDb().query(
-      "SELECT atMonotonicCounter, rowHash FROM " + qTipTable +
-      " WHERE scope = " + (configuredDialect === "postgres" ? "$1" : "?"),
-      [chainName],
-      { backend: configuredExternalDbBackend }
-    );
+    tipRows = await _runClusterQuery(sql().select(tipTable, { dialect: _bDialect() })
+      .columns(["atMonotonicCounter", "rowHash"]).where("scope", chainName));
   } catch (e) {
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log(chainName + "-tip table not present — skipping rollback check (cluster gates-only mode)");
       return;
     }
@@ -406,11 +476,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipCounter = Number(tip.atMonotonicCounter);
   var tipHash = tip.rowHash;
 
-  var currentRows = await externalDb().query(
-    "SELECT MAX(monotonicCounter) AS m FROM " + qLogTable,
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var currentRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+    .max("monotonicCounter", "m"));
   var currentMax = (currentRows.rows && currentRows.rows[0] && currentRows.rows[0].m)
     ? Number(currentRows.rows[0].m)
     : 0;
@@ -426,12 +493,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   }
 
   if (tipHash) {
-    var hashRows = await externalDb().query(
-      "SELECT rowHash FROM " + qLogTable + " WHERE monotonicCounter = " +
-      (configuredDialect === "postgres" ? "$1" : "?"),
-      [tipCounter],
-      { backend: configuredExternalDbBackend }
-    );
+    var hashRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+      .columns(["rowHash"]).where("monotonicCounter", tipCounter));
     if (hashRows.rows && hashRows.rows.length > 0) {
       var rowAtTip = hashRows.rows[0].rowHash;
       if (rowAtTip !== tipHash) {
@@ -492,12 +555,13 @@ function _vaultKeyFingerprint() {
 // non-constant, so the column is nullable and treated as epoch 0 when
 // absent on legacy rows.
 async function _ensureRotationEpochColumn() {
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
   try {
-    await externalDb().query(
-      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var alter = sql().alterTable(stateTable,
+      { addColumn: { name: "rotationEpoch", type: "BIGINT" } },
+      { dialect: _bDialect() }).sql;
+    await externalDb().query(clusterStorage().placeholderize(alter, configuredDialect), [],
+      { backend: configuredExternalDbBackend });
   } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
 }
 
@@ -533,29 +597,23 @@ async function _checkVaultKeyConsistency() {
     return;
   }
   var nowMs = Date.now();
-  var ph = configuredDialect === "postgres";
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
 
   // First boot: try to record THIS node's fingerprint. ON CONFLICT DO
   // NOTHING means the FIRST node to boot wins; subsequent nodes
   // observe whatever's already there. Every node then SELECTs and
   // compares — any mismatch (including ours after a losing race)
-  // surfaces the drift.
+  // surfaces the drift. The scope value binds like any other param; b.sql
+  // folds DO NOTHING to the MySQL `scope = scope` no-op automatically.
   try {
-    await externalDb().query(
-      "INSERT INTO _blamejs_cluster_state " +
-      "  (scope, vaultKeyFp, recordedAt, recordedByNode) " +
-      "VALUES ('state', " +
-      (ph ? "$1, $2, $3" : "?, ?, ?") + ") " +
-      "ON CONFLICT (scope) DO NOTHING",
-      [localFp, nowMs, nodeId],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().upsert(stateTable, { dialect: _bDialect() })
+      .values({ scope: "state", vaultKeyFp: localFp, recordedAt: nowMs, recordedByNode: nodeId })
+      .onConflict(["scope"]).doNothing());
   } catch (e) {
     // Table missing → the cluster-provider-db ensureSchema didn't run
     // (custom provider that doesn't create _blamejs_cluster_state).
     // Skip silently — same defensive posture as the audit-tip check.
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log("cluster-state table not present — skipping vault-key consistency check (custom provider)");
       return;
     }
@@ -569,12 +627,9 @@ async function _checkVaultKeyConsistency() {
 
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
-  var rows = await externalDb().query(
-    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
-    "WHERE scope = 'state'",
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var rows = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+    .columns(["vaultKeyFp", "recordedByNode", "recordedAt", "rotationEpoch"])
+    .where("scope", "state"));
   if (!rows.rows || rows.rows.length === 0) {
     // Should never happen — we just INSERTed. Surface as fatal so the
     // condition isn't silently ignored.
@@ -628,27 +683,20 @@ async function _checkVaultKeyConsistency() {
     var priorEpoch = (canonical.rotationEpoch != null) ? Number(canonical.rotationEpoch) : 0;
     if (!isFinite(priorEpoch) || priorEpoch < 0) priorEpoch = 0;
     var nextEpoch = priorEpoch + 1;
-    await externalDb().query(
-      "UPDATE _blamejs_cluster_state SET " +
-      "  vaultKeyFp = " + (ph ? "$1" : "?") + ", " +
-      "  recordedAt = " + (ph ? "$2" : "?") + ", " +
-      "  recordedByNode = " + (ph ? "$3" : "?") + ", " +
-      "  rotationEpoch = " + (ph ? "$4" : "?") + " " +
-      "WHERE scope = 'state' AND vaultKeyFp = " + (ph ? "$5" : "?"),
-      [localFp, nowMs, nodeId, nextEpoch, canonical.vaultKeyFp],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().update(stateTable, { dialect: _bDialect() })
+      .set({
+        vaultKeyFp: localFp, recordedAt: nowMs,
+        recordedByNode: nodeId, rotationEpoch: nextEpoch,
+      })
+      .where("scope", "state").where("vaultKeyFp", canonical.vaultKeyFp));
     // Re-read so the post-adopt state reflects whoever actually won the
     // advance (this node, or a peer that adopted the SAME rotated key a
     // beat earlier). A surviving mismatch here means the row now carries a
     // fingerprint that is neither the old one nor ours — a real drift that
     // the rotation declaration does not cover, so fail closed.
-    var after = await externalDb().query(
-      "SELECT vaultKeyFp, recordedByNode, rotationEpoch FROM _blamejs_cluster_state " +
-      "WHERE scope = 'state'",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var after = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+      .columns(["vaultKeyFp", "recordedByNode", "rotationEpoch"])
+      .where("scope", "state"));
     var post = (after.rows && after.rows[0]) || canonical;
     if (post.vaultKeyFp !== localFp) {
       throw _err("VAULT_KEY_DRIFT",

package/lib/compliance.js

@@ -50,6 +50,18 @@ var audit         = lazyRequire(function () { return require("./audit"); });
 var retentionMod  = lazyRequire(function () { return require("./retention"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var cryptoField   = lazyRequire(function () { return require("./crypto-field"); });
+var redact        = lazyRequire(function () { return require("./redact"); });
+
+// Postures whose floor implies an outbound-DLP gate (b.redact's
+// classifier presets cover exactly these regimes). Pinning one of these
+// does NOT auto-install outbound DLP — the compliance coordinator holds
+// no httpClient / mail / webhook handles — so set() emits a one-time
+// `compliance.posture.outbound_dlp_unwired` warning when none is wired,
+// so the gap is grep-able in the audit chain instead of a silent paper-
+// compliance hole (CWE-200 / CWE-201 outbound data exposure).
+var OUTBOUND_DLP_FLOOR_POSTURES = Object.freeze([
+  "hipaa", "pci-dss", "gdpr", "soc2", "fapi-2.0", "fapi-2.0-message-signing",
+]);
 
 // Recognised posture names. Aligns with the compliance-posture
 // vocabulary every guard / retention floor / etc. accepts. Operators
@@ -445,6 +457,24 @@ function set(posture) {
         "warning");
     }
   }
+
+  // Outbound-DLP wiring signal. A posture whose floor implies an
+  // outbound-DLP gate is being pinned, but set() cannot install the
+  // interceptors itself (no httpClient / mail / webhook handles). Warn
+  // once when nothing is wired so the gap is visible in the audit chain
+  // rather than a silent paper-compliance hole. Fires at most once per
+  // pin (set() is idempotent for the same posture).
+  if (OUTBOUND_DLP_FLOOR_POSTURES.indexOf(posture) !== -1) {
+    var dlpInstalled = false;
+    try { dlpInstalled = redact().isOutboundDlpInstalled() === true; }
+    catch (_e) { dlpInstalled = false; }
+    if (!dlpInstalled) {
+      _emitAudit("compliance.posture.outbound_dlp_unwired",
+        { posture: posture,
+          recommendation: "compliance.set does not auto-install outbound DLP — it holds no httpClient / mail / webhook handles. Call b.redact.installForPosture('" + posture + "', { httpClient, mail, webhook }) with your primitive instances so outbound payloads are classified (CWE-200 / CWE-201)." },
+        "warning");
+    }
+  }
 }
 
 // _applyPostureCascade — walks every primitive that
@@ -948,6 +978,25 @@ function describe(posture) {
 //                               + DPDP §12 + LGPD-BR Art. 18 + PIPL-CN
 //                               Art. 47 all require effective erasure;
 //                               leftover index residue defeats it.
+//   sealEnvelopeFloor         — minimum field-level seal envelope a
+//                               sealed-column table may declare under
+//                               this posture: "plain" (vault.seal, no
+//                               AAD), "aad" (AEAD-bound to table/row/
+//                               column via b.vault.aad), or "per-row-key"
+//                               (K_row crypto-shred). cryptoField.
+//                               registerTable refuses a table whose
+//                               declared envelope is below the floor when
+//                               this posture is the globally-pinned one.
+//                               PCI-DSS Req. 3.5/3.6 (PAN render
+//                               unreadable, key-management binding) and
+//                               HIPAA 45 CFR 164.312(a)(2)(iv) +
+//                               164.312(e)(2)(ii) (encryption that
+//                               resists ciphertext relocation, CWE-311 /
+//                               CWE-326) need an AAD-bound envelope at
+//                               minimum so a DB-write attacker cannot
+//                               copy a sealed cell between rows. Absent
+//                               on a posture → no floor (back-compat;
+//                               plain envelopes keep registering).
 //
 // This table is the single source-of-truth — duplicating values into
 // per-primitive defaults would drift the moment a regulator updates.
@@ -957,12 +1006,22 @@ var POSTURE_DEFAULTS = Object.freeze({
     auditChainSignedRequired: true,
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  true,
+    // 45 CFR 164.312(a)(2)(iv) + (e)(2)(ii) — ePHI encryption must
+    // resist ciphertext relocation; a plain vault.seal cell can be
+    // copied between rows undetected (CWE-311 / CWE-326). AAD-bound
+    // envelope is the floor.
+    sealEnvelopeFloor:        "aad",
   }),
   "pci-dss": Object.freeze({
     backupEncryptionRequired: true,
     auditChainSignedRequired: true,
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  false,
+    // PCI-DSS v4 Req. 3.5 (PAN unreadable) + Req. 3.6 (key-management
+    // binding) — the seal must bind cardholder data to its storage
+    // location so a relocated ciphertext fails to verify. AAD-bound
+    // envelope is the floor.
+    sealEnvelopeFloor:        "aad",
   }),
   "gdpr": Object.freeze({
     backupEncryptionRequired: false,           // GDPR Art. 32 says "appropriate" — not mandatory floor
@@ -1006,6 +1065,28 @@ var POSTURE_DEFAULTS = Object.freeze({
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  true,
   }),
+  // UK GDPR (DPA 2018 + retained EU GDPR) — Art. 17 right to erasure
+  // applies identically to GDPR, including residual B-tree pages.
+  "uk-gdpr": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Japan APPI — deletion/cessation right with residue-cleanup floor.
+  "appi-jp": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Singapore PDPA — right to erasure with effectiveness floor.
+  "pdpa-sg": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
   // v0.8.70 — 2026 effective deadlines
   "modpa": Object.freeze({
     // Maryland Online Data Privacy Act (effective 2026-10-01) —
@@ -1357,10 +1438,13 @@ var POSTURE_DEFAULTS = Object.freeze({
  * where `set()` would over-pin the process.
  *
  * Recognised keys per posture include `backupEncryptionRequired`,
- * `auditChainSignedRequired`, `tlsMinVersion`, and
- * `requireVacuumAfterErase` — the floors enforced by `b.backup`,
- * `b.audit`, the TLS minimum-version gate, and `b.cryptoField`'s
- * residual-erasure pass.
+ * `auditChainSignedRequired`, `tlsMinVersion`,
+ * `requireVacuumAfterErase`, and `sealEnvelopeFloor` — the floors
+ * enforced by `b.backup`, `b.audit`, the TLS minimum-version gate,
+ * `b.cryptoField`'s residual-erasure pass, and `b.cryptoField`'s
+ * field-level seal-envelope gate. Keys not declared for a posture
+ * return `null` (no floor), so reading `sealEnvelopeFloor` for a
+ * posture that doesn't pin one is the back-compat no-op signal.
  *
  * @example
  *   b.compliance.postureDefault("hipaa", "tlsMinVersion");
@@ -1615,10 +1699,91 @@ function isCrossBorderRegulated(posture) {
   return CROSS_BORDER_REGULATED_POSTURES.indexOf(posture) !== -1;
 }
 
+// Region-tag wildcards. Both spellings mean "no residency constraint"
+// across the framework — the external-db gate uses "unrestricted" as
+// its default + wildcard, while the local db-query / external-db row
+// gates also accept "global" as the region-neutral row tag. Normalizing
+// folds both to "unrestricted" so callers reason about one wildcard.
+var _REGION_WILDCARDS = Object.freeze(["global", "unrestricted", "any", "*"]);
+
+/**
+ * @primitive b.compliance.normalizeRegionTag
+ * @signature b.compliance.normalizeRegionTag(tag)
+ * @since     0.14.27
+ * @compliance gdpr
+ * @related   b.compliance.isRegionCompatible, b.compliance.isCrossBorderRegulated
+ *
+ * Canonicalize an operator-supplied residency region tag so the same
+ * region declared as `"EU"`, `"eu"`, or `" Eu "` compares equal. Lower-
+ * cases and trims the tag; folds the no-constraint wildcards
+ * (`"global"` / `"unrestricted"` / `"any"` / `"*"`) to `"unrestricted"`.
+ * Returns `null` for non-string / empty input.
+ *
+ * This is an ADDITIVE helper composed OVER the residency write gates
+ * (`b.db.from` local, `b.externalDb.query` backend/replica) — it does
+ * not change the gate internals. Callers normalize their tags with it
+ * BEFORE handing them to the gate so case / wildcard drift (`"EU"` vs
+ * `"eu"` vs `"global"`) doesn't read as a region mismatch.
+ *
+ * @example
+ *   b.compliance.normalizeRegionTag("EU");           // → "eu"
+ *   b.compliance.normalizeRegionTag(" eu ");         // → "eu"
+ *   b.compliance.normalizeRegionTag("global");       // → "unrestricted"
+ *   b.compliance.normalizeRegionTag("unrestricted"); // → "unrestricted"
+ *   b.compliance.normalizeRegionTag(null);           // → null
+ */
+function normalizeRegionTag(tag) {
+  if (typeof tag !== "string") return null;
+  var t = tag.trim().toLowerCase();
+  if (t.length === 0) return null;
+  if (_REGION_WILDCARDS.indexOf(t) !== -1) return "unrestricted";
+  return t;
+}
+
+/**
+ * @primitive b.compliance.isRegionCompatible
+ * @signature b.compliance.isRegionCompatible(a, b)
+ * @since     0.14.27
+ * @compliance gdpr
+ * @related   b.compliance.normalizeRegionTag, b.compliance.isCrossBorderRegulated
+ *
+ * Returns `true` when two residency region tags are compatible for a
+ * same-region write/replication after normalization: identical
+ * normalized regions are compatible, and a wildcard (`"global"` /
+ * `"unrestricted"`) on EITHER side is compatible. Different concrete
+ * regions (`"eu"` vs `"us"`) are NOT compatible — a cross-border
+ * transfer the operator must opt into explicitly at the gate.
+ *
+ * Mirrors the residency gate's compatibility rule (identical-or-
+ * wildcard) but over NORMALIZED tags, so it is case- and wildcard-drift
+ * insensitive. ADDITIVE helper composed over the gate — it does not
+ * change `_residencyCompatible` in db-query.js / external-db.js.
+ * Missing/non-string tags on either side normalize to `null`, treated
+ * as "no constraint" → compatible (matches the gate's
+ * `!primaryTag || !replicaTag` short-circuit).
+ *
+ * @example
+ *   b.compliance.isRegionCompatible("EU", "eu");            // → true
+ *   b.compliance.isRegionCompatible("eu", "global");        // → true
+ *   b.compliance.isRegionCompatible("unrestricted", "us");  // → true
+ *   b.compliance.isRegionCompatible("eu", "us");            // → false
+ *   b.compliance.isRegionCompatible("EU", null);            // → true
+ */
+function isRegionCompatible(a, b) {
+  var na = normalizeRegionTag(a);
+  var nb = normalizeRegionTag(b);
+  if (na === null || nb === null) return true;            // no constraint either side
+  if (na === nb) return true;                             // identical region (post-normalize)
+  if (na === "unrestricted" || nb === "unrestricted") return true; // wildcard either side
+  return false;
+}
+
 module.exports = {
   set:                    set,
   current:                current,
   isCrossBorderRegulated: isCrossBorderRegulated,
+  normalizeRegionTag:     normalizeRegionTag,
+  isRegionCompatible:     isRegionCompatible,
   CROSS_BORDER_REGULATED_POSTURES: CROSS_BORDER_REGULATED_POSTURES,
   assert:                 assert,
   clear:                  clear,

package/lib/consent.js

@@ -46,6 +46,8 @@ var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var chainWriter = require("./chain-writer");
 var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var lazyRequire = require("./lazy-require");
 var C = require("./constants");
 var { ClusterError } = require("./framework-error");
@@ -304,10 +306,18 @@ function isGranted(opts) {
   if (!hash) {
     throw new Error("consent_log subjectId is missing a derived hash — schema misconfigured");
   }
-  var row = db().prepare(
-    "SELECT action FROM consent_log WHERE subjectIdHash = ? AND purpose = ? " +
-    "ORDER BY monotonicCounter DESC LIMIT 1"
-  ).get(hash, opts.purpose);
+  // Local db() handle: emit the LOCAL table name (consent_log) quoted so
+  // the camelCase subjectIdHash / monotonicCounter columns resolve, and
+  // run the built { sql, params } against the prepared statement.
+  var isGrantedBuilt = sql.select("consent_log", { dialect: "sqlite", quoteName: true })
+    .columns(["action"])
+    .where("subjectIdHash", hash)
+    .where("purpose", opts.purpose)
+    .orderBy("monotonicCounter", "desc")
+    .limit(1)
+    .toSql();
+  var isGrantedStmt = db().prepare(isGrantedBuilt.sql);
+  var row = isGrantedStmt.get.apply(isGrantedStmt, isGrantedBuilt.params);
   if (!row) return false;
   return row.action === "granted";
 }
@@ -409,30 +419,69 @@ async function _appendConsentRow(fields) {
 }
 
 async function _upsertConsentTip(counter, rowHash, signedAt, fencingToken) {
-  // Single atomic INSERT … ON CONFLICT DO UPDATE … WHERE … RETURNING.
-  // Same canonical fencing-token guard as _blamejs_audit_tip: the
-  // WHERE clause enforces monotonic-non-decreasing fencingToken at
-  // the DB level so a partitioned old leader can't overwrite the tip
-  // even if its application-layer cluster.requireLeader() gate let
-  // the call through.
+  // Single atomic INSERT … ON CONFLICT(scope) DO UPDATE … WHERE … RETURNING
+  // via b.sql. Same canonical fencing-token guard as _blamejs_audit_tip: the
+  // fenced WHERE enforces monotonic-non-decreasing fencingToken at the DB
+  // level so a partitioned old leader can't overwrite the tip even if its
+  // application-layer cluster.requireLeader() gate let the call through. On
+  // rejection RETURNING produces 0 rows.
+  //
+  // The consent-tip is external-only; its LOGICAL name IS the
+  // `_blamejs_`-prefixed name (self-mapped in LOCAL_TO_EXTERNAL), passed
+  // bare to b.sql so clusterStorage rewrites it (and the same bare name
+  // inside the guarded fence) to the configured prefix and placeholderizes.
+  //
+  // Dialect is the ACTIVE backend (clusterStorage.dialect()) so the fence's
+  // identifier quoting + conflict-expression idiom match the server the SQL
+  // dispatches to. The fence text itself is dialect-specific because the
+  // builder folds it verbatim: on Postgres / SQLite the upsert keeps a
+  // `WHERE "<table>"."fencingToken" <= EXCLUDED."fencingToken"` guard (and a
+  // RETURNING row that signals fenced-out via 0 rows); on MySQL there is no
+  // WHERE and no EXCLUDED, so the builder folds the same guard into per-column
+  // `IF(<table>.`fencingToken` <= VALUES(`fencingToken`), VALUES(col), col)`
+  // — the fence must therefore reference `VALUES(...)` with backticks. The
+  // bare table qualifier (no quoteName) lets clusterStorage rewrite the
+  // logical `_blamejs_consent_tip` to the configured prefix inside the fence
+  // exactly as it does for the table name.
+  var d = clusterStorage.dialect();
+  var qFence = safeSql.quoteIdentifier("fencingToken", d);
+  var tipFence = d === "mysql"
+    ? "_blamejs_consent_tip." + qFence + " <= VALUES(" + qFence + ")"     // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    : "_blamejs_consent_tip." + qFence + " <= EXCLUDED." + qFence;        // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+  var tipBuilt = sql.upsert("_blamejs_consent_tip", { dialect: d })   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    .columns(["scope", "atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    .values({
+      scope:              "consent",
+      atMonotonicCounter: counter,
+      rowHash:            rowHash,
+      signedAt:           signedAt,
+      fencingToken:       fencingToken,
+    })
+    .onConflict(["scope"])
+    .doUpdateFromExcluded(["atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    // guardColumn pins fencingToken LAST in the MySQL SET list so every
+    // other column's IF() evaluates the guard against the PRE-UPDATE token
+    // (MySQL evaluates SET left-to-right; a later assignment would otherwise
+    // see fencingToken already overwritten). Ignored on Postgres / SQLite,
+    // which apply the WHERE atomically.
+    .conflictWhere(tipFence, [], { guardColumn: "fencingToken" })
+    .returning(["fencingToken"])
+    .toSql();
   var result = await safeAsync.withTimeout(
-    clusterStorage.execute(
-      "INSERT INTO _blamejs_consent_tip " +
-      "  (scope, atMonotonicCounter, rowHash, signedAt, fencingToken) " +
-      "VALUES ('consent', ?, ?, ?, ?) " +
-      "ON CONFLICT (scope) DO UPDATE SET " +
-      "  atMonotonicCounter = EXCLUDED.atMonotonicCounter, " +
-      "  rowHash            = EXCLUDED.rowHash, " +
-      "  signedAt           = EXCLUDED.signedAt, " +
-      "  fencingToken       = EXCLUDED.fencingToken " +
-      "WHERE _blamejs_consent_tip.fencingToken <= EXCLUDED.fencingToken " +
-      "RETURNING fencingToken",
-      [counter, rowHash, signedAt, fencingToken]
-    ),
+    clusterStorage.execute(tipBuilt.sql, tipBuilt.params),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "consent.upsertConsentTip" }
   );
-  if (!result.rows || result.rows.length === 0) {
+  // MySQL upsert has no RETURNING — the builder emits a readback SELECT
+  // alongside, but a fenced-out lower-token write still SUCCEEDS as a no-op
+  // INSERT…ON DUPLICATE KEY UPDATE (the IF() keeps the stored values), so
+  // there is no 0-rows signal to detect. The DB-level fence still PRESERVES
+  // the tip (the security property); the FENCED_OUT throw is the
+  // Postgres/SQLite RETURNING-0-rows path only. On MySQL clusterStorage is
+  // not a supported framework backend, so the consent-tip never dispatches
+  // there in production — the threaded dialect makes the SAME builders emit
+  // valid MySQL for operators driving these shapes against MySQL directly.
+  if (d !== "mysql" && (!result.rows || result.rows.length === 0)) {
     throw new ClusterError(
       "FENCED_OUT",
       "consent-tip update rejected: incoming fencingToken=" + fencingToken +