@blamejs/core 0.14.22 → 0.14.25

package/lib/external-db.js

@@ -58,38 +58,293 @@ function _emitMetric(name, value, labels) {
   catch (_e) { /* hot-path observability sink — drop silent by design */ }
 }
 
-// Statement-class classifier for auth-failure forensics. Inspects
-// the leading keyword only so an attacker-controlled trailing fragment
-// can't smuggle a false classification. Skips leading whitespace plus
-// SQL line / block comments before reading the keyword.
-// Linear (non-backtracking) comment/whitespace skip: each iteration of
-// the outer group consumes exactly one whitespace char, one complete
-// block comment (matched with the star-not-slash form, never a lazy
-// `[\s\S]*?`), or one complete line comment — disjoint by first char,
-// so there is no ambiguous repetition for a crafted SQL string of
-// nested `/**/` or `*/--` runs to backtrack on (CWE-1333 ReDoS).
+// Statement-class classifier for auth-failure forensics AND the
+// residency write gate. Reads the leading keyword — but a leading
+// keyword is not the whole story: `WITH ... INSERT`, `EXPLAIN ANALYZE
+// INSERT`, `CALL`/`EXECUTE`/`DO`, `COPY ... FROM`, and `REPLACE` all
+// place rows while their leading (or only) keyword reads as harmless.
+// _classifyStatement unwraps WITH (CTE) and EXPLAIN [ANALYZE] prefixes
+// to the effective verb so the gate sees the real statement class; an
+// attacker-controlled trailing fragment still can't smuggle a false
+// class because the multi-statement form is refused upstream
+// (_hasTrailingStatement) and an unresolvable prefix classifies
+// UNKNOWN (fail-closed on the gate's enforced path).
+//
+// Skips leading whitespace plus SQL line / block comments before
+// reading the keyword. Linear (non-backtracking) comment/whitespace
+// skip: each iteration of the outer group consumes exactly one
+// whitespace char, one complete block comment (star-not-slash form,
+// never a lazy `[\s\S]*?`), or one complete line comment — disjoint by
+// first char, so a crafted SQL string of nested `/**/` or `*/--` runs
+// cannot backtrack polynomially (CWE-1333 ReDoS).
 var _STATEMENT_CLASS_RE = /^(?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/|--[^\n]*\n)*([A-Za-z]+)/;
 var _STATEMENT_CLASS_MAP = Object.freeze({
-  SELECT: "SELECT", WITH: "SELECT", VALUES: "SELECT", TABLE: "SELECT",
-  INSERT: "DML", UPDATE: "DML", DELETE: "DML", MERGE: "DML", UPSERT: "DML",
+  SELECT: "SELECT", VALUES: "SELECT", TABLE: "SELECT",
+  SHOW: "READ_INFO", DESCRIBE: "READ_INFO", DESC: "READ_INFO",
+  PRAGMA: "READ_INFO", USE: "READ_INFO",
+  INSERT: "DML", UPDATE: "DML", DELETE: "DML", MERGE: "DML",
+  UPSERT: "DML", REPLACE: "DML",
   CREATE: "DDL", DROP: "DDL", ALTER: "DDL", TRUNCATE: "DDL",
   RENAME: "DDL", COMMENT: "DDL",
   GRANT: "DCL", REVOKE: "DCL",
   SET: "SESSION", RESET: "SESSION",
   BEGIN: "TX", START: "TX", COMMIT: "TX", ROLLBACK: "TX",
   SAVEPOINT: "TX", RELEASE: "TX",
-  CALL: "ROUTINE", EXECUTE: "ROUTINE",
+  CALL: "ROUTINE", EXECUTE: "ROUTINE", DO: "ROUTINE",
   COPY: "BULK",
   EXPLAIN: "META", ANALYZE: "META", VACUUM: "META",
 });
 
+// Main-statement keywords that may follow a WITH (CTE) clause list —
+// the verb that decides the statement's effect. `WITH src AS (...)
+// INSERT INTO ...` is a write; classifying it by its leading keyword
+// would label it a read and wave it past the residency write gate.
+var _CTE_MAIN_VERBS = Object.freeze({
+  SELECT: true, VALUES: true, TABLE: true,
+  INSERT: true, UPDATE: true, DELETE: true,
+  MERGE: true, UPSERT: true, REPLACE: true,
+});
+
+// SQL identifier character classes, as char-range predicates rather
+// than `_isIdentChar(ch)` regex literals — faster per-char in
+// the tight statement-scan loops and keeps the trivial word-char class
+// out of the cross-file duplicate-regex catalog.
+function _isIdentStart(ch) {
+  return (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || ch === "_";
+}
+function _isIdentChar(ch) {
+  return _isIdentStart(ch) || (ch >= "0" && ch <= "9");
+}
+
+// If sql[i] begins an opaque span — a string literal ('...' with
+// doubled-quote escapes), a quoted identifier ("..." / `...` / [...]),
+// a Postgres dollar-quoted body ($tag$...$tag$), or a SQL line / block
+// comment — return the index just past its close; -1 if the span is
+// unterminated; i unchanged if sql[i] does not begin a span. One
+// linear scan per call, no backtracking regex (CWE-1333). Shared by
+// every SQL leading-/effective-verb scanner below so the multi-
+// statement, CTE, EXPLAIN, and COPY walkers all agree on what counts
+// as data vs. structure across the Postgres / MySQL / SQLite dialects
+// external-db targets. A doubled closing quote ('it''s') re-enters as
+// a fresh empty span on the caller's next iteration, staying opaque.
+function _skipOpaqueSpan(sql, i) {
+  var n = sql.length;
+  var ch = sql.charAt(i);
+  if (ch === "'" || ch === "\"" || ch === "`") {
+    var close = sql.indexOf(ch, i + 1);
+    return close === -1 ? -1 : close + 1;
+  }
+  if (ch === "[") {                              // SQLite / MSSQL bracket identifier
+    var rb = sql.indexOf("]", i + 1);
+    return rb === -1 ? -1 : rb + 1;
+  }
+  if (ch === "$") {
+    // $tag$ ... $tag$ dollar-quoted body; a bare $n placeholder has no
+    // second `$` after the run of word chars and is not a span.
+    var tagEnd = i + 1;
+    while (tagEnd < n && _isIdentChar(sql.charAt(tagEnd))) tagEnd += 1;
+    if (tagEnd < n && sql.charAt(tagEnd) === "$") {
+      var tag = sql.slice(i, tagEnd + 1);
+      var closeTag = sql.indexOf(tag, tagEnd + 1);
+      return closeTag === -1 ? -1 : closeTag + tag.length;
+    }
+    return i;
+  }
+  if (ch === "-" && sql.charAt(i + 1) === "-") {
+    var nl = sql.indexOf("\n", i + 2);
+    return nl === -1 ? -1 : nl + 1;
+  }
+  if (ch === "/" && sql.charAt(i + 1) === "*") {
+    var ce = sql.indexOf("*/", i + 2);
+    return ce === -1 ? -1 : ce + 2;
+  }
+  return i;
+}
+
+// Resolve the main-statement keyword of a WITH-prefixed (CTE)
+// statement: walk past the CTE definition list to the first top-level
+// main verb (opaque spans skipped via _skipOpaqueSpan, parens tracked
+// by depth). `WITH src AS (...) INSERT INTO ...` is a write; the
+// leading keyword would label it a read and wave it past the residency
+// write gate. Returns the uppercased verb, or null when unresolvable
+// (unterminated span, parenthesized main statement, stray close-paren,
+// no verb found) — the gate REFUSES unresolvable statements on its
+// enforced path, so a parse miss fails closed.
+function _cteMainKeyword(sql, start) {
+  var n = sql.length;
+  var depth = 0;
+  var i = start;
+  while (i < n) {
+    var ch = sql.charAt(i);
+    var skipped = _skipOpaqueSpan(sql, i);
+    if (skipped === -1) return null;
+    if (skipped !== i) { i = skipped; continue; }
+    if (ch === "(") { depth += 1; i += 1; continue; }
+    if (ch === ")") { depth -= 1; i += 1; continue; }
+    if (_isIdentStart(ch)) {
+      var we = i + 1;
+      while (we < n && _isIdentChar(sql.charAt(we))) we += 1;
+      if (depth === 0) {
+        var word = sql.slice(i, we).toUpperCase();
+        if (_CTE_MAIN_VERBS[word] === true) return word;
+        // Top-level word that is not a main verb: CTE name, AS,
+        // RECURSIVE, [NOT] MATERIALIZED, or a SEARCH / CYCLE clause
+        // word — keep walking.
+      }
+      i = we;
+      continue;
+    }
+    i += 1;
+  }
+  return null;
+}
+
+// EXPLAIN option words (Postgres parenthesized + legacy bare; MySQL
+// bare). These precede the inner statement and never terminate the
+// option list, so the verb scanner skips them; only ANALYZE flips the
+// "this EXPLAIN actually executes the statement" bit.
+var _EXPLAIN_OPTION_WORDS = Object.freeze({
+  ANALYZE: true, VERBOSE: true, COSTS: true, BUFFERS: true,
+  SETTINGS: true, WAL: true, TIMING: true, SUMMARY: true,
+  SERIALIZE: true, MEMORY: true, GENERIC_PLAN: true, FORMAT: true,
+  TEXT: true, JSON: true, YAML: true, XML: true, TREE: true,
+  EXTENDED: true, PARTITIONS: true,
+  ON: true, OFF: true, TRUE: true, FALSE: true,
+});
+
+// Resolve an EXPLAIN prefix: skip the option list (a parenthesized
+// `( ANALYZE, FORMAT JSON )` group and/or bare option words), noting
+// whether ANALYZE is present, and return { hasAnalyze, innerStart }
+// pointing at the wrapped statement's leading keyword. null when
+// unresolvable (unterminated span, unbalanced option parens, no inner
+// statement). EXPLAIN ANALYZE EXECUTES the wrapped statement, so an
+// `EXPLAIN ANALYZE INSERT ...` is a real write the gate must see.
+function _explainResolve(sql, start) {
+  var n = sql.length;
+  var hasAnalyze = false;
+  var i = start;
+  while (i < n) {
+    var ch = sql.charAt(i);
+    var skipped = _skipOpaqueSpan(sql, i);
+    if (skipped === -1) return null;
+    if (skipped !== i) { i = skipped; continue; }
+    if (ch === "(") {
+      var depth = 0;
+      var j = i;
+      while (j < n) {
+        var c2 = sql.charAt(j);
+        var s2 = _skipOpaqueSpan(sql, j);
+        if (s2 === -1) return null;
+        if (s2 !== j) { j = s2; continue; }
+        if (c2 === "(") { depth += 1; j += 1; continue; }
+        if (c2 === ")") { depth -= 1; j += 1; if (depth === 0) break; continue; }
+        if (_isIdentStart(c2)) {
+          var oe = j + 1;
+          while (oe < n && _isIdentChar(sql.charAt(oe))) oe += 1;
+          if (sql.slice(j, oe).toUpperCase() === "ANALYZE") hasAnalyze = true;
+          j = oe;
+          continue;
+        }
+        j += 1;
+      }
+      if (depth !== 0) return null;
+      i = j;
+      continue;
+    }
+    if (_isIdentStart(ch)) {
+      var we = i + 1;
+      while (we < n && _isIdentChar(sql.charAt(we))) we += 1;
+      var word = sql.slice(i, we).toUpperCase();
+      if (word === "ANALYZE") { hasAnalyze = true; i = we; continue; }
+      if (_EXPLAIN_OPTION_WORDS[word] === true) { i = we; continue; }
+      return { hasAnalyze: hasAnalyze, innerStart: i };
+    }
+    i += 1;
+  }
+  return null;
+}
+
+// COPY <target> FROM <source> LOADS rows (a write); COPY <target> /
+// COPY (query) TO <dest> EXPORTS rows (a read). Find the first
+// top-level FROM / TO keyword after COPY, skipping a parenthesized
+// source query and opaque spans. FROM → true (load); TO → false
+// (export); unresolvable or neither → true (fail-closed write).
+function _copyLoadsRows(sql) {
+  var m = _STATEMENT_CLASS_RE.exec(sql);
+  if (!m) return true;
+  var n = sql.length;
+  var i = m.index + m[0].length;
+  while (i < n) {
+    var ch = sql.charAt(i);
+    var skipped = _skipOpaqueSpan(sql, i);
+    if (skipped === -1) return true;
+    if (skipped !== i) { i = skipped; continue; }
+    if (ch === "(") {
+      var depth = 0;
+      var j = i;
+      while (j < n) {
+        var c2 = sql.charAt(j);
+        var s2 = _skipOpaqueSpan(sql, j);
+        if (s2 === -1) return true;
+        if (s2 !== j) { j = s2; continue; }
+        if (c2 === "(") { depth += 1; j += 1; continue; }
+        if (c2 === ")") { depth -= 1; j += 1; if (depth === 0) break; continue; }
+        j += 1;
+      }
+      i = j;
+      continue;
+    }
+    if (_isIdentStart(ch)) {
+      var we = i + 1;
+      while (we < n && _isIdentChar(sql.charAt(we))) we += 1;
+      var word = sql.slice(i, we).toUpperCase();
+      if (word === "FROM") return true;
+      if (word === "TO") return false;
+      i = we;
+      continue;
+    }
+    i += 1;
+  }
+  return true;
+}
+
+// Forensic / gate statement class. Resolves WITH (CTE) and EXPLAIN
+// [ANALYZE] prefixes to the effective verb so a write wearing a
+// harmless leading keyword classifies as the write it is; unresolvable
+// prefixes classify UNKNOWN (fail-closed at the gate).
 function _classifyStatement(sql) {
   if (typeof sql !== "string" || sql.length === 0) return "UNKNOWN";
   var m = _STATEMENT_CLASS_RE.exec(sql);
   if (!m) return "UNKNOWN";
-  return _STATEMENT_CLASS_MAP[m[1].toUpperCase()] || "OTHER";
+  var kw = m[1].toUpperCase();
+  if (kw === "WITH") {
+    var main = _cteMainKeyword(sql, m.index + m[0].length);
+    return main === null ? "UNKNOWN" : (_STATEMENT_CLASS_MAP[main] || "OTHER");
+  }
+  if (kw === "EXPLAIN") {
+    // Plan-only EXPLAIN reads (META). EXPLAIN ANALYZE executes the
+    // wrapped statement, so its effective class is the inner one's.
+    var ex = _explainResolve(sql, m.index + m[0].length);
+    if (ex === null) return "UNKNOWN";
+    if (!ex.hasAnalyze) return "META";
+    return _classifyStatement(sql.slice(ex.innerStart));
+  }
+  return _STATEMENT_CLASS_MAP[kw] || "OTHER";
 }
 
+// Statement classes that place no rows on the backend, so the cross-
+// border residency write gate lets them pass without a row tag. Every
+// other class — DML, ROUTINE (CALL / EXECUTE / DO), a COPY ... FROM
+// load, or an unmapped/unresolved statement — is treated as a write
+// and must carry a residency tag on the enforced path. DDL (schema
+// changes) and DCL (grants) move no row data across a border; the one
+// edge they don't cover, CREATE TABLE AS SELECT / SELECT INTO, is a
+// documented residency limitation rather than a silent bypass.
+var _RESIDENCY_READ_CLASS = Object.freeze({
+  SELECT: true, READ_INFO: true, SESSION: true,
+  TX: true, DCL: true, DDL: true, META: true,
+});
+
 // ---- OpenTelemetry database-client semantic conventions ----
 //
 // db.* span / metric attributes on the query / transaction / read emit
@@ -738,6 +993,7 @@ function _servesClassification(b, cls) {
  *   backend?:           string,   // explicit backend name; bypasses classification + role pick
  *   classification?:    string,   // route to first backend whose classifications include this value
  *   includeSqlInAudit?: boolean,  // emit SQL text in audit metadata (off by default — may carry literal PII)
+ *   rowResidencyTag?:   string,   // the row's residency region tag; required for a write (DML, CALL/EXECUTE/DO, COPY ... FROM, REPLACE, or a WITH/EXPLAIN-ANALYZE wrapping one) to a residency-tagged backend under a cross-border regulated posture (pass "global"/"unrestricted" for region-neutral rows)
  *
  * @example
  *   var res = await b.externalDb.query(
@@ -754,6 +1010,14 @@ async function query(sql, params, opts) {
   var b = _pickBackend(opts);
   var role = dbRoleContext.getRole();
 
+  // Per-row residency write gate — refuses a cross-border write before
+  // the statement reaches the wire (see _assertRowResidency).
+  var _resRefusal = _assertRowResidency(sql, opts, b);
+  if (_resRefusal) {
+    _emit("db.residency.gate.rejected", "denied", _resRefusal.metadata, _resRefusal.code);
+    throw _err(_resRefusal.code, _resRefusal.message, true);
+  }
+
   var t0 = Date.now();
   try {
     var result = await retryHelper.withRetry(function () {
@@ -854,6 +1118,7 @@ async function query(sql, params, opts) {
  *   statementTimeoutMs?:         number,                       // SET LOCAL statement_timeout
  *   idleInTransactionTimeoutMs?: number,                       // SET LOCAL idle_in_transaction_session_timeout
  *   deadlockRetries?:            number,                       // retries for 40P01 / 40001 (default 3)
+ *   rowResidencyTag?:            string,                       // residency tag applied to every statement; a per-call tx.query(sql, params, { rowResidencyTag }) overrides it for that statement
  *
  * @example
  *   var summary = await b.externalDb.transaction(async function (tx) {
@@ -907,10 +1172,34 @@ async function transaction(fn, opts) {
   }
   var maxRetries = (typeof opts.deadlockRetries === "number")
     ? Math.floor(opts.deadlockRetries) : 3;                                       // allow:numeric-opt-Infinity
+  // Validate the transaction-level residency tag shape at entry (the
+  // sessionGucs / deadlockRetries discipline) so an empty-string tag
+  // fails before BEGIN rather than at the first statement.
+  if (opts.rowResidencyTag !== undefined && opts.rowResidencyTag !== null &&
+      (typeof opts.rowResidencyTag !== "string" || opts.rowResidencyTag.length === 0)) {
+    throw _err("INVALID_OPT",
+      "transaction: opts.rowResidencyTag must be a non-empty string when supplied", true);
+  }
   return await b.breaker.wrap(async function () {
     var client = await b.pool.acquire();
     var txClient = {
-      query: function (sql, params) { return b.query(client, sql, params || []); },
+      // Per-statement residency gate inside the transaction: a
+      // transaction-level opts.rowResidencyTag applies to every
+      // statement; an optional per-call third argument overrides it
+      // for that statement. A refusal throws into the operator's tx
+      // body, which rolls the transaction back — no partial commit of
+      // a cross-border write.
+      query: function (sql, params, perCallOpts) {
+        var effOpts = (perCallOpts && perCallOpts.rowResidencyTag !== undefined)
+          ? perCallOpts
+          : { rowResidencyTag: opts.rowResidencyTag };
+        var refusal = _assertRowResidency(sql, effOpts, b);
+        if (refusal) {
+          _emit("db.residency.gate.rejected", "denied", refusal.metadata, refusal.code);
+          throw _err(refusal.code, refusal.message, true);
+        }
+        return b.query(client, sql, params || []);
+      },
     };
     var committed = false;
     var attempt = 0;
@@ -1229,9 +1518,17 @@ var REPLICA_UNHEALTHY_COOLDOWN_MS = C.TIME.seconds(30);
 //   - "unrestricted" tag on either side: compatible (operator
 //     declared no constraint).
 //   - Different tags: compatible only when allowCrossBorder is true.
-var CROSS_BORDER_REGULATED_POSTURES = Object.freeze([
-  "gdpr", "uk-gdpr", "dpdp", "pipl-cn", "lgpd-br", "appi-jp", "pdpa-sg",
-]);
+//
+// The regulated-posture set itself lives on b.compliance
+// (CROSS_BORDER_REGULATED_POSTURES) — one vocabulary shared with the
+// local db-query residency gate.
+function _crossBorderRegulated(posture) {
+  if (posture === null || posture === undefined) return false;
+  try {
+    var compliance = require("./compliance");                                                    // allow:inline-require — defensive against optional load
+    return compliance.isCrossBorderRegulated(posture);
+  } catch (_e) { return false; }
+}
 
 function _residencyCompatible(primaryTag, replicaTag) {
   if (!primaryTag || !replicaTag) return true;
@@ -1240,6 +1537,54 @@ function _residencyCompatible(primaryTag, replicaTag) {
   return false;
 }
 
+// True when `sql` carries a non-comment, non-whitespace statement after
+// the first top-level semicolon — the multi-statement shape that would
+// let a trailing DML hide behind a harmless leading keyword. A `;`
+// inside any opaque span (string literal, quoted identifier, dollar-
+// quoted body, comment) is data, not a separator: the main scan skips
+// every span via _skipOpaqueSpan, so a `;` inside `$$ ... ; ... $$` or
+// a doubled-quote run can't be mistaken for a top-level separator (and
+// can't desync the scanner into missing a real one). Single linear
+// pass, no backtracking regex (CWE-1333).
+function _hasTrailingStatement(sql) {
+  if (typeof sql !== "string") return false;
+  var n = sql.length;
+  var i = 0;
+  while (i < n) {
+    var ch = sql.charAt(i);
+    var skipped = _skipOpaqueSpan(sql, i);
+    if (skipped === -1) return false;            // unterminated span — no top-level content beyond it
+    if (skipped !== i) { i = skipped; continue; }
+    if (ch !== ";") { i += 1; continue; }
+    // First top-level `;` decides: if everything after it is only
+    // whitespace and SQL comments there is no second statement (a
+    // single statement may end with `;`); any other character is one.
+    // Comments-only skip here (not _skipOpaqueSpan) — a string / ident
+    // after the `;` IS trailing content, so it must count, not be
+    // skipped as a span.
+    var j = i + 1;
+    while (j < n) {
+      var c = sql.charAt(j);
+      if (c === " " || c === "\t" || c === "\r" || c === "\n") { j += 1; continue; }
+      if (c === "/" && sql.charAt(j + 1) === "*") {
+        var end = sql.indexOf("*/", j + 2);
+        if (end === -1) return false;            // unterminated comment — no content
+        j = end + 2;
+        continue;
+      }
+      if (c === "-" && sql.charAt(j + 1) === "-") {
+        var nl = sql.indexOf("\n", j + 2);
+        if (nl === -1) return false;             // line comment to EOF — no content
+        j = nl + 1;
+        continue;
+      }
+      return true;
+    }
+    return false;
+  }
+  return false;
+}
+
 function _activePosture() {
   try {
     var compliance = require("./compliance");                                                    // allow:inline-require — defensive against optional load
@@ -1247,6 +1592,115 @@ function _activePosture() {
   } catch (_e) { return null; }
 }
 
+// Per-row residency write gate (GDPR Art 44-46 / PIPL Art 38 / DPDP
+// §16 cross-border transfer restrictions). External-db takes raw SQL,
+// not row objects, so the row's residency tag travels as
+// `opts.rowResidencyTag` — the operator computes it from app logic
+// (session / declared user region), never inferred from request
+// metadata. Under a cross-border regulated posture, DML to a
+// residency-tagged backend REQUIRES the tag and refuses a mismatch;
+// untagged backends, unregulated postures, and non-DML statements
+// pass (with an advisory audit when a tag was supplied anyway).
+// Returns null on pass or { code, message, metadata } — the caller
+// throws via _err so the refusal carries permanent=true.
+function _assertRowResidency(sql, opts, backend) {
+  var tag = opts && opts.rowResidencyTag;
+  if (tag !== undefined && tag !== null &&
+      (typeof tag !== "string" || tag.length === 0)) {
+    return {
+      code:     "INVALID_OPT",
+      message:  "rowResidencyTag must be a non-empty string when supplied",
+      metadata: { backend: backend.name, statementClass: _classifyStatement(sql) },
+    };
+  }
+  var backendTag = backend.residencyTag || "unrestricted";
+  var posture = _activePosture();
+  var regulated = _crossBorderRegulated(posture);
+  // The gate only enforces on the cross-border-regulated + residency-
+  // tagged-backend path. Everywhere else (unregulated posture,
+  // unrestricted backend — including the framework's own coordination
+  // stores) statements pass untouched; multi-statement SQL stays the
+  // operator's business there.
+  if (regulated && backendTag !== "unrestricted") {
+    // A trailing statement after a top-level `;` could hide a write
+    // behind a harmless prefix — refuse multi-statement SQL on the
+    // enforced path so a residency-bound write cannot ride a SELECT.
+    if (_hasTrailingStatement(sql)) {
+      return {
+        code:     "MULTI_STATEMENT_REFUSED",
+        message:  "multi-statement SQL is not supported on the residency-gated " +
+                  "write path; pass one statement per query()",
+        metadata: { backend: backend.name, backendTag: backendTag, posture: posture,
+                    statementClass: _classifyStatement(sql), scope: "external" },
+      };
+    }
+    var cls = _classifyStatement(sql);
+    // Fail-closed: a statement whose effective class can't be resolved
+    // (an unparseable WITH / EXPLAIN prefix or pathological quoting)
+    // could be hiding a write, so refuse it rather than wave it through
+    // as a read.
+    if (cls === "UNKNOWN") {
+      return {
+        code:     "STATEMENT_UNRESOLVED_REFUSED",
+        message:  "could not resolve the effective statement class on the " +
+                  "residency-gated write path; pass one plain statement per " +
+                  "query() (an unparseable WITH/EXPLAIN prefix or quoting)",
+        metadata: { backend: backend.name, backendTag: backendTag, posture: posture,
+                    statementClass: cls, scope: "external" },
+      };
+    }
+    // The gate enforces on writes, not just DML: ROUTINE (CALL /
+    // EXECUTE / DO), a COPY ... FROM load, and an unmapped (OTHER)
+    // verb all place rows and must carry a tag. Recognized pure reads
+    // (and a COPY ... TO export) place none and pass untagged.
+    var isWrite = !(_RESIDENCY_READ_CLASS[cls] === true ||
+                    (cls === "BULK" && !_copyLoadsRows(sql)));
+    if (!isWrite) return null;
+    if (!tag) {
+      return {
+        code: "RESIDENCY_GATE_REQUIRED",
+        message: "write to backend '" + backend.name + "' (residencyTag='" +
+          backendTag + "') under '" + posture + "' posture requires " +
+          "opts.rowResidencyTag. Pass { rowResidencyTag: \"" + backendTag +
+          "\" } for rows belonging to this region, or declare per-row " +
+          "residency via b.cryptoField.declarePerRowResidency for local tables",
+        metadata: { backend: backend.name, backendTag: backendTag,
+                    rowTag: null, posture: posture, statementClass: cls,
+                    scope: "external" },
+      };
+    }
+    if (tag !== "global" && tag !== "unrestricted" &&
+        !_residencyCompatible(tag, backendTag)) {
+      return {
+        code: "RESIDENCY_TAG_MISMATCH",
+        message: "row residencyTag '" + tag + "' is not compatible with backend '" +
+          backend.name + "' residencyTag '" + backendTag + "' under '" + posture +
+          "' posture (cross-border transfer refused)",
+        metadata: { backend: backend.name, backendTag: backendTag,
+                    rowTag: tag, posture: posture, statementClass: cls,
+                    scope: "external" },
+      };
+    }
+    return null;
+  }
+  if (tag) {
+    // Unregulated posture or untagged backend with a tag supplied on a
+    // write — pass, but surface the advisory so operators staging a
+    // posture flip can see what WOULD be evaluated.
+    var advisoryCls = _classifyStatement(sql);
+    var advisoryWrite = advisoryCls !== "UNKNOWN" &&
+      !(_RESIDENCY_READ_CLASS[advisoryCls] === true ||
+        (advisoryCls === "BULK" && !_copyLoadsRows(sql)));
+    if (advisoryWrite) {
+      _emit("db.residency.gate.advisory", "info", {
+        backend: backend.name, backendTag: backendTag, rowTag: tag,
+        posture: posture || null, statementClass: advisoryCls, scope: "external",
+      });
+    }
+  }
+  return null;
+}
+
 function _buildReplicas(backendName, cfg) {
   if (!cfg.replicas) return null;
   if (!Array.isArray(cfg.replicas) || cfg.replicas.length === 0) {
@@ -1275,7 +1729,7 @@ function _buildReplicas(backendName, cfg) {
     var replicaTag = r.residencyTag || "unrestricted";
     var allowCrossBorder = r.allowCrossBorder === true;
     if (!_residencyCompatible(primaryTag, replicaTag) && !allowCrossBorder) {
-      var underPosture = posture && CROSS_BORDER_REGULATED_POSTURES.indexOf(posture) !== -1;
+      var underPosture = _crossBorderRegulated(posture);
       throw _err("RESIDENCY_MISMATCH",
         "backend '" + backendName + "': replica[" + i +
         "] residencyTag '" + replicaTag +
@@ -1286,7 +1740,12 @@ function _buildReplicas(backendName, cfg) {
         "documented legal basis (SCCs / BCRs / adequacy decision) to suppress.", true);
     }
     if (!_residencyCompatible(primaryTag, replicaTag) && allowCrossBorder) {
-      _emit("externalDb.replica.cross_border_allowed", "warning",
+      // The action name MUST stay in the registered `db.` namespace and
+      // lowercase — the audit validator refuses "externalDb.*" (the old
+      // name silently dropped every cross-border-allowed event through
+      // safeEmit, leaving no audit-chain record of the operator's
+      // conscious opt-in). Mirrors the read-path event name below.
+      _emit("db.residency.replica.cross_border_allowed", "warning",
         { backend: backendName, replicaIndex: i,
           primaryTag: primaryTag, replicaTag: replicaTag,
           legalBasis: r.legalBasis || null,
@@ -1344,6 +1803,35 @@ async function _readQuery(sql, params, opts) {
     throw _err("ALL_REPLICAS_UNHEALTHY",
       "backend '" + b.name + "': all replicas unhealthy and fallback disabled", true);
   }
+  // Replica residency check — when the caller identifies the row's
+  // region (opts.rowResidencyTag) under a regulated posture, a read
+  // routed to an incompatible replica is refused unless the replica
+  // was explicitly configured allowCrossBorder (which is audited).
+  if (opts.rowResidencyTag && typeof opts.rowResidencyTag === "string") {
+    var _readPosture = _activePosture();
+    if (_crossBorderRegulated(_readPosture) &&
+        opts.rowResidencyTag !== "global" && opts.rowResidencyTag !== "unrestricted" &&
+        !_residencyCompatible(opts.rowResidencyTag, replica.residencyTag)) {
+      if (replica.allowCrossBorder) {
+        _emit("db.residency.replica.cross_border", "warning", {
+          backend: b.name, replicaIdx: replica.index,
+          rowTag: opts.rowResidencyTag, replicaTag: replica.residencyTag,
+          posture: _readPosture,
+        });
+      } else {
+        _emit("db.residency.replica.incompatible", "denied", {
+          backend: b.name, replicaIdx: replica.index,
+          rowTag: opts.rowResidencyTag, replicaTag: replica.residencyTag,
+          posture: _readPosture,
+        });
+        throw _err("REPLICA_RESIDENCY_INCOMPATIBLE",
+          "read for row residencyTag '" + opts.rowResidencyTag + "' routed to replica " +
+          replica.index + " of backend '" + b.name + "' (residencyTag='" +
+          replica.residencyTag + "') under '" + _readPosture +
+          "' posture; set allowCrossBorder on the replica to permit (audited)", true);
+      }
+    }
+  }
   var role = dbRoleContext.getRole();
   var t0 = Date.now();
   try {

package/lib/framework-error.js

@@ -125,6 +125,11 @@ var QueueError            = defineClass("QueueError");
 // them and skips immediately rather than hammering a misconfig.
 var RedisError            = defineClass("RedisError");
 var ExternalDbError       = defineClass("ExternalDbError");
+// DbQueryError covers the local-SQLite query-builder refusal paths
+// (residency write gates, malformed-call shapes). Refusals pass the
+// permanent flag explicitly — a residency mismatch never becomes valid
+// on retry, while the class stays open for transient codes later.
+var DbQueryError          = defineClass("DbQueryError");
 var ClusterError          = defineClass("ClusterError");
 var ClusterProviderError  = defineClass("ClusterProviderError");
 var HandlerError          = defineClass("HandlerError",          { withCause: true });
@@ -653,6 +658,7 @@ module.exports = {
   QueueError:             QueueError,
   RedisError:             RedisError,
   ExternalDbError:        ExternalDbError,
+  DbQueryError:           DbQueryError,
   ClusterError:           ClusterError,
   ClusterProviderError:   ClusterProviderError,
   HandlerError:           HandlerError,