@blamejs/core 0.14.26 → 0.15.0

package/lib/audit.js

@@ -55,7 +55,9 @@ var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
+var frameworkSchema = require("./framework-schema");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var dbRoleContext = require("./db-role-context");
 var handlers = require("./handlers");
 var { boot } = require("./log");
@@ -101,19 +103,36 @@ var _externalStore = null;
 // the worst case.
 var FRAMEWORK_SQL_TIMEOUT_MS = C.TIME.seconds(30);
 
+// b.sql opts for every framework-table statement: thread the ACTIVE backend
+// dialect (clusterStorage.dialect() — "sqlite" single-node, "postgres" |
+// "mysql" in cluster mode) so the emitted identifier quoting + dialect
+// idioms (ON CONFLICT vs ON DUPLICATE KEY) match the backend the SQL
+// dispatches to. Defaulting to "sqlite" works on Postgres only by accident
+// (both double-quote identifiers) and emits the wrong quoting on MySQL.
+// clusterStorage.execute still rewrites table names + translates `?`
+// placeholders at dispatch; this controls only the builder-side quoting +
+// idiom selection.
+function _sqlOpts() { return { dialect: clusterStorage.dialect() }; }
+
 // ---- Resilience-wrapped SQL operations (audit-specific reads) ----
 // Chain APPEND lives in chain-writer (race-safe via mutex, retry, timeout).
 // The wrappers below cover audit-specific reads/writes that aren't part
 // of the chain append: checkpoint queries, verifyCheckpoints reads,
 // audit-tip cluster-row updates.
 
+// Framework-state reads compose b.sql with BARE logical table names —
+// clusterStorage rewrites the framework names to their configured-prefix
+// form and placeholderizes per dialect; b.sql quotes the camelCase columns
+// and runs the output validator.
 async function _readLastCheckpointCounter() {
+  var built = sql.select("audit_checkpoints", _sqlOpts())
+    .columns(["atMonotonicCounter"])
+    .orderBy("atMonotonicCounter", "desc")
+    .limit(1)
+    .toSql();
   return await safeAsync.withTimeout(
     safeAsync.asyncRetry(function () {
-      return clusterStorage.executeOne(
-        "SELECT atMonotonicCounter FROM audit_checkpoints " +
-        "ORDER BY atMonotonicCounter DESC LIMIT 1"
-      );
+      return clusterStorage.executeOne(built.sql, built.params);
     }),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.readLastCheckpoint" }
@@ -121,11 +140,12 @@ async function _readLastCheckpointCounter() {
 }
 
 async function _readAllAuditRowsAsc() {
+  var built = sql.select("audit_log", _sqlOpts())
+    .orderBy("monotonicCounter", "asc")
+    .toSql();
   return await safeAsync.withTimeout(
     safeAsync.asyncRetry(function () {
-      return clusterStorage.executeAll(
-        'SELECT * FROM "audit_log" ORDER BY monotonicCounter ASC'
-      );
+      return clusterStorage.executeAll(built.sql, built.params);
     }),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.readAllRowsAsc" }
@@ -133,11 +153,12 @@ async function _readAllAuditRowsAsc() {
 }
 
 async function _readAllCheckpointsAsc() {
+  var built = sql.select("audit_checkpoints", _sqlOpts())
+    .orderBy("atMonotonicCounter", "asc")
+    .toSql();
   return await safeAsync.withTimeout(
     safeAsync.asyncRetry(function () {
-      return clusterStorage.executeAll(
-        "SELECT * FROM audit_checkpoints ORDER BY atMonotonicCounter ASC"
-      );
+      return clusterStorage.executeAll(built.sql, built.params);
     }),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.readAllCheckpoints" }
@@ -145,12 +166,13 @@ async function _readAllCheckpointsAsc() {
 }
 
 async function _readAuditRowHashAtCounter(counter) {
+  var built = sql.select("audit_log", _sqlOpts())
+    .columns(["rowHash"])
+    .where("monotonicCounter", counter)
+    .toSql();
   return await safeAsync.withTimeout(
     safeAsync.asyncRetry(function () {
-      return clusterStorage.executeOne(
-        "SELECT rowHash FROM audit_log WHERE monotonicCounter = ?",
-        [counter]
-      );
+      return clusterStorage.executeOne(built.sql, built.params);
     }),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.readRowHashAtCounter" }
@@ -158,26 +180,37 @@ async function _readAuditRowHashAtCounter(counter) {
 }
 
 async function _insertAuditRow(allCols, values) {
-  // No retry — non-idempotent. Timeout only.
-  var placeholders = allCols.map(function () { return "?"; }).join(", ");
-  var quoted = allCols.map(function (c) { return '"' + c + '"'; }).join(", ");
+  // No retry — non-idempotent. Timeout only. Map each column to its
+  // positional value and bind as a row object (the unambiguous b.sql form;
+  // a flat value array whose first element is a Buffer would be misread as
+  // an array-of-rows). BARE logical table name → clusterStorage rewrites.
+  var rowObj = {};
+  for (var i = 0; i < allCols.length; i++) rowObj[allCols[i]] = values[i];
+  var built = sql.insert("audit_log", _sqlOpts())
+    .columns(allCols)
+    .values(rowObj)
+    .toSql();
   return await safeAsync.withTimeout(
-    clusterStorage.execute(
-      "INSERT INTO audit_log (" + quoted + ") VALUES (" + placeholders + ")",
-      values
-    ),
+    clusterStorage.execute(built.sql, built.params),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.insertRow" }
   );
 }
 
+var _CHECKPOINT_COLS = [
+  "_id", "createdAt", "atMonotonicCounter", "atRowHash",
+  "signature", "publicKeyFingerprint", "fencingToken",
+];
+
 async function _insertCheckpoint(values) {
+  var rowObj = {};
+  for (var i = 0; i < _CHECKPOINT_COLS.length; i++) rowObj[_CHECKPOINT_COLS[i]] = values[i];
+  var built = sql.insert("audit_checkpoints", _sqlOpts())
+    .columns(_CHECKPOINT_COLS)
+    .values(rowObj)
+    .toSql();
   return await safeAsync.withTimeout(
-    clusterStorage.execute(
-      "INSERT INTO audit_checkpoints (_id, createdAt, atMonotonicCounter, atRowHash, signature, publicKeyFingerprint, fencingToken) " +
-      "VALUES (?, ?, ?, ?, ?, ?, ?)",
-      values
-    ),
+    clusterStorage.execute(built.sql, built.params),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.insertCheckpoint" }
   );
@@ -198,24 +231,79 @@ async function _upsertAuditTip(counter, rowHash, signedAt, fencingToken) {
   // as ClusterError(code='FENCED_OUT', permanent=true) so the
   // dispatching node knows it's been superseded and should step down
   // rather than retry.
-  var result = await safeAsync.withTimeout(
-    clusterStorage.execute(
-      "INSERT INTO _blamejs_audit_tip " +
-      "  (scope, atMonotonicCounter, rowHash, signedAt, fencingToken) " +
-      "VALUES ('audit', ?, ?, ?, ?) " +
-      "ON CONFLICT (scope) DO UPDATE SET " +
-      "  atMonotonicCounter = EXCLUDED.atMonotonicCounter, " +
-      "  rowHash            = EXCLUDED.rowHash, " +
-      "  signedAt           = EXCLUDED.signedAt, " +
-      "  fencingToken       = EXCLUDED.fencingToken " +
-      "WHERE _blamejs_audit_tip.fencingToken <= EXCLUDED.fencingToken " +
-      "RETURNING fencingToken",
-      [counter, rowHash, signedAt, fencingToken]
-    ),
-    FRAMEWORK_SQL_TIMEOUT_MS,
-    { name: "audit.upsertAuditTip" }
-  );
-  if (!result.rows || result.rows.length === 0) {
+  // Single atomic INSERT … ON CONFLICT(scope) DO UPDATE … WHERE … RETURNING
+  // via b.sql. BARE logical table name (`_blamejs_audit_tip`) — clusterStorage
+  // rewrites it (and the same bare name inside the conflictWhere fence) to
+  // the configured prefix and placeholderizes. The fenced WHERE enforces the
+  // monotonic-non-decreasing fencingToken at the DB level; on rejection
+  // RETURNING produces 0 rows.
+  // The audit-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.
+  //
+  // The fence `<table>.<fencingToken> <= EXCLUDED.<fencingToken>` references
+  // both the EXISTING row (table-qualified) and the PROPOSED row (EXCLUDED on
+  // Postgres/SQLite, VALUES() on MySQL ON DUPLICATE KEY UPDATE), and the
+  // identifier quoting differs per dialect — so the raw fragment is built
+  // dialect-aware: safeSql.quoteQualified for the table-qualified existing
+  // column (backticks on MySQL, double-quotes on PG/SQLite), and the
+  // proposed-row reference spelled per dialect (the EXCLUDED keyword has no
+  // MySQL equivalent — ON DUPLICATE KEY UPDATE uses VALUES(col)). guardColumn
+  // tells the MySQL upsert renderer that the fence protects `fencingToken`,
+  // so the IF(<fence>, …, col) wrap on the other SET targets evaluates
+  // against the fencingToken column's PRE-update value (the IF-eval-order
+  // hazard) and the guard column is assigned last.
+  var dialect = clusterStorage.dialect();
+  var fenceExisting = safeSql.quoteQualified(["_blamejs_audit_tip", "fencingToken"], dialect);   // allow:hand-rolled-sql
+  var fenceProposed = dialect === "mysql"
+    ? "VALUES(" + safeSql.quoteIdentifier("fencingToken", "mysql") + ")"
+    : "EXCLUDED." + safeSql.quoteIdentifier("fencingToken", dialect);
+  var tipFence = fenceExisting + " <= " + fenceProposed;
+  var tipBuilt = sql.upsert("_blamejs_audit_tip", { dialect: dialect })   // allow:hand-rolled-sql
+    .columns(["scope", "atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    .values({
+      scope:              "audit",
+      atMonotonicCounter: counter,
+      rowHash:            rowHash,
+      signedAt:           signedAt,
+      fencingToken:       fencingToken,
+    })
+    .onConflict(["scope"])
+    .doUpdateFromExcluded(["atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    .conflictWhere(tipFence, [], { guardColumn: "fencingToken" })
+    .returning(["fencingToken"])
+    .toSql();
+  var fenced;
+  if (dialect === "mysql") {
+    // MySQL ON DUPLICATE KEY UPDATE has no WHERE + no RETURNING — the fence
+    // becomes an IF(<guard>, VALUES(col), col) per SET target, so a fenced-out
+    // (strictly-lower) token leaves every column at its stored value and the
+    // statement still "succeeds". Detection therefore can't read RETURNING
+    // rows: run the upsert, then read the stored fencingToken back (the b.sql
+    // builder hands us the keyed readback SELECT) and compare. If the stored
+    // token is ABOVE our incoming one, a higher-token successor won and we
+    // were fenced out.
+    await safeAsync.withTimeout(
+      clusterStorage.execute(tipBuilt.sql, tipBuilt.params),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: "audit.upsertAuditTip" }
+    );
+    var back = await safeAsync.withTimeout(
+      clusterStorage.executeOne(tipBuilt.readbackSql.sql, tipBuilt.readbackSql.params),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: "audit.upsertAuditTip.readback" }
+    );
+    fenced = !back || Number(back.fencingToken) > Number(fencingToken);
+  } else {
+    var result = await safeAsync.withTimeout(
+      clusterStorage.execute(tipBuilt.sql, tipBuilt.params),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: "audit.upsertAuditTip" }
+    );
+    fenced = !result.rows || result.rows.length === 0;
+  }
+  if (fenced) {
     throw new ClusterError(
       "FENCED_OUT",
       "audit-tip update rejected: incoming fencingToken=" + fencingToken +
@@ -617,11 +705,18 @@ function useStore(store) {
 //
 // Self-logging (PCI DSS 10.2.3): every read of audit_log is itself recorded
 // as an 'audit.read' event before the query runs, so an exfiltration attempt
-// is forensically visible. The recursion guard (_selfLogging flag) prevents
-// the audit.read recording from triggering its own self-log; queries
-// SPECIFICALLY filtering for action='audit.read' don't auto-log either
-// (otherwise legitimate audit auditing produces a Russell-set spiral).
-var _selfLogging = false;
+// is forensically visible. The self-log goes through record() (which never
+// re-enters query()), so the only re-entrancy to suppress is a query whose
+// own criteria filters for action='audit.read' — those don't auto-log
+// (otherwise legitimate audit-of-audits produces a Russell-set spiral, and
+// the self-read itself would log a read). That suppression is decided PER
+// INVOCATION from the call's own criteria.action, never from shared mutable
+// state: a prior design used a module-global `_selfLogging` boolean toggled
+// across record()'s await (chain mutex + SQL yield), so a CONCURRENT
+// query() racing a mid-flight self-log observed the flag set and silently
+// skipped emitting its own audit.read — under-logging reads exactly when
+// load is highest. b.audit.query is reachable from concurrent request
+// handlers, so the guard MUST be invocation-local.
 
 /**
  * @primitive b.audit.query
@@ -633,9 +728,10 @@ var _selfLogging = false;
  * Read audit rows matching the criteria, returning unsealed rows for
  * the auditor's view. Every call self-logs an `audit.read` event before
  * returning (PCI DSS 10.2.3) so exfiltration attempts are forensically
- * visible; recursion is guarded so the self-log doesn't trigger its own
- * self-log. Plain-field criteria translate into derived-hash equality
- * where the column is sealed.
+ * visible; the self-log is suppressed per-invocation only for a query
+ * whose own criteria targets `action: "audit.read"`, so concurrent reads
+ * each record their own `audit.read`. Plain-field criteria translate into
+ * derived-hash equality where the column is sealed.
  *
  * @opts
  *   from:         number | Date | string,   // recordedAt >=
@@ -658,21 +754,21 @@ var _selfLogging = false;
  */
 async function query(criteria) {
   criteria = criteria || {};
-  if (!_selfLogging && criteria.action !== "audit.read") {
-    _selfLogging = true;
-    try {
-      await record({
-        actor:    criteria.actor || {},
-        action:   "audit.read",
-        outcome:  "success",
-        metadata: {
-          criteria: _redactCriteria(criteria),
-          traceId:  criteria.traceId || null,
-        },
-      });
-    } finally {
-      _selfLogging = false;
-    }
+  // Suppress the self-log ONLY for a query whose own criteria targets
+  // action='audit.read' (the self-read's shape + audit-of-audits). This is
+  // derived from THIS call's criteria — no shared flag — so concurrent
+  // reads each emit their own audit.read instead of one racing read
+  // swallowing another's self-log.
+  if (criteria.action !== "audit.read") {
+    await record({
+      actor:    criteria.actor || {},
+      action:   "audit.read",
+      outcome:  "success",
+      metadata: {
+        criteria: _redactCriteria(criteria),
+        traceId:  criteria.traceId || null,
+      },
+    });
   }
 
   // In single-node mode the query builder gives us field-crypto unsealing
@@ -700,35 +796,31 @@ async function query(criteria) {
 }
 
 async function _queryCluster(criteria) {
-  var conds = [];
-  var params = [];
-  if (criteria.from) {
-    conds.push("recordedAt >= ?");
-    params.push(_toMs(criteria.from));
-  }
-  if (criteria.to) {
-    conds.push("recordedAt <= ?");
-    params.push(_toMs(criteria.to));
-  }
+  // Compose the criteria onto a b.sql SELECT with a BARE logical table name
+  // (clusterStorage rewrites + placeholderizes). Sealed-field criteria
+  // translate to the derived-hash column via cryptoField.lookupHash exactly
+  // as before; b.sql quotes every identifier and binds every value.
+  var qb = sql.select("audit_log", _sqlOpts());
+  if (criteria.from) qb.whereOp("recordedAt", ">=", _toMs(criteria.from));
+  if (criteria.to)   qb.whereOp("recordedAt", "<=", _toMs(criteria.to));
   if (criteria.actorUserId) {
     var auh = cryptoField.lookupHash("audit_log", "actorUserId", criteria.actorUserId);
-    if (auh) { conds.push(auh.field + " = ?"); params.push(auh.value); }
+    if (auh) qb.where(auh.field, auh.value);
   }
   if (criteria.resourceId) {
     var rh = cryptoField.lookupHash("audit_log", "resourceId", criteria.resourceId);
-    if (rh) { conds.push(rh.field + " = ?"); params.push(rh.value); }
+    if (rh) qb.where(rh.field, rh.value);
   }
-  if (criteria.action)        { conds.push("action = ?");        params.push(criteria.action); }
-  if (criteria.resourceKind)  { conds.push("resourceKind = ?");  params.push(criteria.resourceKind); }
-  if (criteria.outcome)       { conds.push("outcome = ?");       params.push(criteria.outcome); }
+  if (criteria.action)       qb.where("action", criteria.action);
+  if (criteria.resourceKind) qb.where("resourceKind", criteria.resourceKind);
+  if (criteria.outcome)      qb.where("outcome", criteria.outcome);
 
-  var sql = "SELECT * FROM audit_log";
-  if (conds.length > 0) sql += " WHERE " + conds.join(" AND ");
-  sql += " ORDER BY monotonicCounter ASC";
-  if (criteria.limit != null)  { sql += " LIMIT ?";  params.push(criteria.limit); }
-  if (criteria.offset != null) { sql += " OFFSET ?"; params.push(criteria.offset); }
+  qb.orderBy("monotonicCounter", "asc");
+  if (criteria.limit  != null) qb.limit(criteria.limit);
+  if (criteria.offset != null) qb.offset(criteria.offset);
 
-  var rows = await clusterStorage.executeAll(sql, params);
+  var built = qb.toSql();
+  var rows = await clusterStorage.executeAll(built.sql, built.params);
   return rows.map(function (row) { return cryptoField.unsealRow("audit_log", row); });
 }
 
@@ -840,12 +932,14 @@ async function checkpoint(opts) {
   cluster.requireLeader();
   opts = opts || {};
 
+  var tipReadBuilt = sql.select("audit_log", _sqlOpts())
+    .columns(["_id", "monotonicCounter", "rowHash"])
+    .orderBy("monotonicCounter", "desc")
+    .limit(1)
+    .toSql();
   var tip = await safeAsync.withTimeout(
     safeAsync.asyncRetry(function () {
-      return clusterStorage.executeOne(
-        "SELECT _id, monotonicCounter, rowHash FROM audit_log " +
-        "ORDER BY monotonicCounter DESC LIMIT 1"
-      );
+      return clusterStorage.executeOne(tipReadBuilt.sql, tipReadBuilt.params);
     }),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "audit.checkpoint.readTip" }
@@ -890,16 +984,31 @@ async function checkpoint(opts) {
   if (cluster.isClusterMode()) {
     await _upsertAuditTip(counter, tip.rowHash, String(createdAt), fencingToken);
   } else {
-    try {
-      db()._writeAuditTip({
-        atMonotonicCounter:  counter,
-        atRowHash:           tip.rowHash,
-        anchoredAt:          createdAt,
-        checkpointId:        ckptId,
-        publicKeyFingerprint: pubFp,
-        version:             1,
-      });
-    } catch (_e) { /* best effort */ }
+    // Flush the anchored rows to durable db.enc BEFORE advancing the durable
+    // tip sidecar. Otherwise a crash between this checkpoint and the next
+    // encrypt leaves the tip referencing a counter not yet on durable disk;
+    // on reboot the rollback detector reads the tip ahead of the restored
+    // db.enc and FALSELY refuses boot as a rollback/deletion, even though the
+    // chain is intact and only unflushed rows were lost in a normal crash.
+    // Rows-before-tip is the correct durability ordering. flushToDisk is a
+    // no-op outside encrypted-at-rest mode (the live file is already durable).
+    // The tip advances ONLY if the flush succeeded, so the durable tip can
+    // never get ahead of the durable rows.
+    var rowsFlushed = false;
+    try { db().flushToDisk(); rowsFlushed = true; }
+    catch (_e) { /* flush failed - do not advance the tip ahead of the rows */ }
+    if (rowsFlushed) {
+      try {
+        db()._writeAuditTip({
+          atMonotonicCounter:  counter,
+          atRowHash:           tip.rowHash,
+          anchoredAt:          createdAt,
+          checkpointId:        ckptId,
+          publicKeyFingerprint: pubFp,
+          version:             1,
+        });
+      } catch (_e) { /* best effort */ }
+    }
   }
 
   return {
@@ -947,28 +1056,28 @@ async function verifyCheckpoints() {
 
   if (rows.length === 0) return { ok: true, checkpointsVerified: 0 };
 
-  var currentFp = auditSign.getPublicKeyFingerprint();
-  var currentPub = auditSign.getPublicKey();
-
   for (var i = 0; i < rows.length; i++) {
     var c = rows[i];
-    // Public key check: only the current key is accepted — there is no
-    // key-history table, so any rotation requires re-signing existing
-    // checkpoints. A fingerprint mismatch fails verification.
-    if (c.publicKeyFingerprint !== currentFp) {
+    // Resolve the public key the checkpoint was signed under: the current
+    // key, or a rotated-out key from the unsealed public-key history. A
+    // rotation archives the prior public key, so a checkpoint anchored
+    // before the rotation still verifies (no re-signing required). A
+    // fingerprint with no recorded key is the genuine break (key rotated
+    // away with no history, or a forged fingerprint).
+    var pub = auditSign.getPublicKeyByFingerprint(c.publicKeyFingerprint);
+    if (!pub) {
       return {
         ok:                  false,
         checkpointsVerified: i,
         breakAt:             i,
         checkpointId:        c._id,
-        reason:              "public key fingerprint mismatch (key rotated without history?)",
-        expected:            currentFp,
+        reason:              "no audit-signing key on record for this checkpoint's fingerprint (key rotated without history?)",
         actual:              c.publicKeyFingerprint,
       };
     }
     var payload = _checkpointPayload(Number(c.atMonotonicCounter), c.atRowHash, Number(c.createdAt));
     var sigBuf = Buffer.isBuffer(c.signature) ? c.signature : Buffer.from(c.signature);
-    if (!auditSign.verify(payload, sigBuf, currentPub)) {
+    if (!auditSign.verify(payload, sigBuf, pub)) {
       return {
         ok:                  false,
         checkpointsVerified: i,
@@ -1515,10 +1624,15 @@ function bindActor(actorId, opts) {
 function generateActorBindingTriggerSql(opts) {
   opts = opts || {};
   var columnRaw    = opts.column || "actorUserId";
-  var tableNameRaw = opts.tableName || "_blamejs_audit_log";
+  // Default resolves through frameworkSchema.tableName so the configurable
+  // framework-table prefix flows into the operator-applied trigger DDL.
+  var tableNameRaw = opts.tableName || frameworkSchema.tableName("audit_log");
   var allowRoles   = Array.isArray(opts.allowRoles) ? opts.allowRoles : [];
-  var fnNameRaw    = "_blamejs_audit_actor_binding_check";
-  var trigNameRaw  = "_blamejs_audit_actor_binding_trig";
+  // Trigger function + trigger object NAMES (not framework tables — they have
+  // no LOCAL_TO_EXTERNAL mapping and carry no prefix). assertSegregation
+  // looks them up under these exact names.
+  var fnNameRaw    = "_blamejs_audit_actor_binding_check";   // allow:hand-rolled-sql
+  var trigNameRaw  = "_blamejs_audit_actor_binding_trig";    // allow:hand-rolled-sql
   // Quote-and-validate every identifier through safeSql.quoteIdentifier
   // so operator-supplied opts.column / opts.tableName / opts.roleMappingFn
   // can't reach raw concatenation. PostgreSQL + SQLite both use the
@@ -1537,8 +1651,14 @@ function generateActorBindingTriggerSql(opts) {
   var roleMatch = qRoleMapFn
     ? "  IF " + qRoleMapFn + "(NEW." + qColumn + ") IS DISTINCT FROM current_user THEN\n"
     : "  IF NEW." + qColumn + " IS DISTINCT FROM current_user THEN\n";
+  // Operator-applied plpgsql trigger DDL — a CREATE FUNCTION body + RAISE
+  // EXCEPTION + CREATE/DROP TRIGGER, none of which b.sql's verb builders
+  // model. Every identifier is quoted through safeSql.quoteIdentifier above;
+  // the table name resolves via frameworkSchema.tableName, so the prefix is
+  // honored. allow:hand-rolled-sql — this is migration-script generation,
+  // not a framework-state DML path.
   var up =
-    "CREATE OR REPLACE FUNCTION " + qFn + "() RETURNS trigger AS $$\n" +
+    "CREATE OR REPLACE FUNCTION " + qFn + "() RETURNS trigger AS $$\n" +   // allow:hand-rolled-sql
     "BEGIN\n" +
     allowList +
     roleMatch +
@@ -1548,12 +1668,12 @@ function generateActorBindingTriggerSql(opts) {
     "  RETURN NEW;\n" +
     "END;\n" +
     "$$ LANGUAGE plpgsql;\n" +
-    "DROP TRIGGER IF EXISTS " + qTrig + " ON " + qTable + ";\n" +
-    "CREATE TRIGGER " + qTrig + "\n" +
+    "DROP TRIGGER IF EXISTS " + qTrig + " ON " + qTable + ";\n" +          // allow:hand-rolled-sql
+    "CREATE TRIGGER " + qTrig + "\n" +                                     // allow:hand-rolled-sql
     "  BEFORE INSERT ON " + qTable + "\n" +
     "  FOR EACH ROW EXECUTE FUNCTION " + qFn + "();\n";
   var down =
-    "DROP TRIGGER IF EXISTS " + qTrig + " ON " + qTable + ";\n" +
+    "DROP TRIGGER IF EXISTS " + qTrig + " ON " + qTable + ";\n" +          // allow:hand-rolled-sql
     "DROP FUNCTION IF EXISTS " + qFn + "();\n";
   return { up: up, down: down, functionName: fnNameRaw, triggerName: trigNameRaw };
 }
@@ -1592,14 +1712,20 @@ async function assertSegregation(opts) {
     throw new AuditSegregationError("audit/segregation-no-db",
       "audit.assertSegregation: opts.db with a query() method is required");
   }
-  var fnName = opts.functionName || "_blamejs_audit_actor_binding_check";
-  var trigName = opts.triggerName || "_blamejs_audit_actor_binding_trig";
+  // Trigger / function object NAMES (not framework tables — they have no
+  // LOCAL_TO_EXTERNAL mapping and carry no prefix). They must match the
+  // names generateActorBindingTriggerSql emits.
+  var fnName = opts.functionName || "_blamejs_audit_actor_binding_check";    // allow:hand-rolled-sql
+  var trigName = opts.triggerName || "_blamejs_audit_actor_binding_trig";    // allow:hand-rolled-sql
+  // Operator-DB system-catalog introspection (Postgres pg_proc / pg_trigger,
+  // $N-native, against the operator-supplied db.query) — not a framework
+  // table, so b.sql's verb builders don't apply.
   var fnRes = await db.query(
-    "SELECT 1 FROM pg_proc WHERE proname = $1 LIMIT 1", [fnName]
+    "SELECT 1 FROM pg_proc WHERE proname = $1 LIMIT 1", [fnName]             // allow:hand-rolled-sql
   );
   var fnPresent = !!(fnRes && fnRes.rows && fnRes.rows.length > 0);
   var trigRes = await db.query(
-    "SELECT 1 FROM pg_trigger WHERE tgname = $1 LIMIT 1", [trigName]
+    "SELECT 1 FROM pg_trigger WHERE tgname = $1 LIMIT 1", [trigName]         // allow:hand-rolled-sql
   );
   var trigPresent = !!(trigRes && trigRes.rows && trigRes.rows.length > 0);
   var missing = [];