@blamejs/core 0.14.27 → 0.15.1

package/lib/framework-schema.js

@@ -34,17 +34,24 @@
  *   Append-only WORM enforcement: `ensureSchema` installs BEFORE
  *   DELETE / BEFORE UPDATE triggers on `audit_log`, `consent_log`,
  *   and `audit_checkpoints` — Postgres via plpgsql RAISE EXCEPTION
- *   functions, SQLite via `RAISE(ABORT, ...)`. Idempotent across
- *   reboots; any operator-applied DROP TRIGGER is restored on the
- *   next ensureSchema pass. MySQL is not currently supported —
- *   operators on MySQL must run on Postgres or SQLite until a MySQL
- *   adapter ships.
+ *   functions, MySQL via `SIGNAL SQLSTATE '45000'`, SQLite via
+ *   `RAISE(ABORT, ...)`. Idempotent across reboots; any operator-applied
+ *   DROP TRIGGER is restored on the next ensureSchema pass.
+ *
+ *   Dialect portability: `postgres`, `mysql`, and `sqlite` are all
+ *   supported targets. The integer token is BIGINT on Postgres + MySQL
+ *   (a 32-bit INTEGER overflows a Date.now() ms-epoch value) and INTEGER
+ *   on SQLite; the binary token is BYTEA / LONGBLOB / BLOB. TEXT columns
+ *   that participate in a PRIMARY KEY or index become VARCHAR(191) on
+ *   MySQL (which refuses an unbounded TEXT/BLOB in a key) and stay plain
+ *   TEXT on Postgres + SQLite.
  *
  * @card
- *   Framework-defined SQL schema (audit / sessions / api_keys / cache / break-glass / scheduler-ticks / pubsub / rate-limit / seeders / etc.) — declarative, migration-aware, and dialect-portable across Postgres and SQLite.
+ *   Framework-defined SQL schema (audit / sessions / api_keys / cache / break-glass / scheduler-ticks / pubsub / rate-limit / seeders / etc.) — declarative, migration-aware, and dialect-portable across Postgres, MySQL, and SQLite.
  */
 
 var externalDb = require("./external-db");
+var safeSql = require("./safe-sql");
 var { FrameworkError } = require("./framework-error");
 
 class FrameworkSchemaError extends FrameworkError {
@@ -138,16 +145,105 @@ var LOCAL_TO_EXTERNAL = Object.freeze({
   _blamejs_break_glass_grants:   "_blamejs_break_glass_grants",
 });
 
+// ---- Configurable framework-table prefix ----
+//
+// Every external-db (and prefixed local) framework table name carries a
+// leading prefix so the framework's tables never collide with the
+// operator's application tables. The default is `_blamejs_`; an operator
+// running the framework alongside an app schema that itself uses
+// `_blamejs_`-shaped names (or who simply wants a house prefix) can swap
+// it at config-time via `setTablePrefix`. The default-prefix output is
+// byte-identical to the historical hardcoded names, so this is a no-op
+// for every existing deployment.
+var DEFAULT_TABLE_PREFIX = "_blamejs_";
+var currentPrefix = DEFAULT_TABLE_PREFIX;
+
+/**
+ * @primitive b.frameworkSchema.setTablePrefix
+ * @signature b.frameworkSchema.setTablePrefix(prefix)
+ * @since     0.14.30
+ * @status    stable
+ * @related   b.frameworkSchema.getTablePrefix, b.frameworkSchema.tableName, b.db.init
+ *
+ * Set the leading prefix applied to every framework-owned table name
+ * (audit / consent / sessions / jobs / cache / break-glass / …). The
+ * default is `_blamejs_`; pass a different value to namespace the
+ * framework's tables away from an operator schema that would otherwise
+ * collide. Config-time only — call it once, before schema creation
+ * (`b.db.init` calls it for you when you pass `tablePrefix`). Throws a
+ * `FrameworkSchemaError` ("framework-schema/invalid-prefix") when the
+ * prefix is not a non-empty SQL identifier, so a typo surfaces at boot
+ * rather than as a silently-misnamed table.
+ *
+ * The default-prefix output is byte-identical to the historical names,
+ * so leaving the prefix unchanged is a no-op.
+ *
+ * @example
+ *   b.frameworkSchema.setTablePrefix("acme_");
+ *   b.frameworkSchema.tableName("audit_log");
+ *   // → "acme_audit_log"
+ *
+ *   try { b.frameworkSchema.setTablePrefix(""); }
+ *   catch (e) { e.code; } // → "framework-schema/invalid-prefix"
+ */
+function setTablePrefix(prefix) {
+  try {
+    safeSql.validateIdentifier(prefix, { allowReserved: true });
+  } catch (e) {
+    throw new FrameworkSchemaError(
+      "setTablePrefix: prefix must be a non-empty SQL identifier — " +
+        ((e && e.message) || String(e)),
+      "framework-schema/invalid-prefix"
+    );
+  }
+  currentPrefix = prefix;
+  return currentPrefix;
+}
+
+/**
+ * @primitive b.frameworkSchema.getTablePrefix
+ * @signature b.frameworkSchema.getTablePrefix()
+ * @since     0.14.30
+ * @status    stable
+ * @related   b.frameworkSchema.setTablePrefix, b.frameworkSchema.tableName
+ *
+ * Return the prefix currently applied to framework-owned table names —
+ * `_blamejs_` unless `setTablePrefix` changed it.
+ *
+ * @example
+ *   b.frameworkSchema.getTablePrefix();
+ *   // → "_blamejs_"
+ */
+function getTablePrefix() {
+  return currentPrefix;
+}
+
+// Swap the leading default prefix on a resolved external name for the
+// configured prefix. With the default prefix this returns the name
+// unchanged (byte-identical to the historical literal); any framework
+// name not carrying the default prefix (there are none today) passes
+// through untouched.
+function _applyPrefix(externalName) {
+  if (currentPrefix === DEFAULT_TABLE_PREFIX) return externalName;
+  if (externalName.indexOf(DEFAULT_TABLE_PREFIX) === 0) {
+    return currentPrefix + externalName.slice(DEFAULT_TABLE_PREFIX.length);
+  }
+  return externalName;
+}
+
 /**
  * @primitive b.frameworkSchema.tableName
  * @signature b.frameworkSchema.tableName(localName)
  * @since     0.5.0
  * @status    stable
- * @related   b.frameworkSchema.ensureSchema
+ * @related   b.frameworkSchema.ensureSchema, b.frameworkSchema.setTablePrefix
  *
  * Translate a local-SQLite table name into the external-db name. The
  * mapping is the frozen `LOCAL_TO_EXTERNAL` object — tables that already
- * carry the `_blamejs_` prefix locally pass through unchanged. Cluster
+ * carry the framework prefix locally pass through the mapping unchanged.
+ * The resolved name's leading prefix is then swapped to the configured
+ * prefix (`setTablePrefix`); with the default `_blamejs_` prefix the
+ * output is byte-identical to the historical names. Cluster
  * write-dispatch code uses this lookup so the same SQL works against
  * both backends without per-call branching.
  *
@@ -163,121 +259,224 @@ var LOCAL_TO_EXTERNAL = Object.freeze({
  */
 function tableName(localName) {
   if (Object.prototype.hasOwnProperty.call(LOCAL_TO_EXTERNAL, localName)) {
-    return LOCAL_TO_EXTERNAL[localName];
+    return _applyPrefix(LOCAL_TO_EXTERNAL[localName]);
   }
-  // For framework-internal tables that are already prefixed locally
-  // (any name starting with _blamejs_), keep the same name.
-  return localName;
+  // Framework-internal tables already carrying the default prefix locally
+  // but not in the LOCAL_TO_EXTERNAL map (e.g. `_blamejs_migrations`,
+  // `_blamejs_migrations_lock`, `_blamejs_counters`) still honor the
+  // configured prefix: swap the leading default prefix for the configured
+  // one. Under the default prefix this returns the name byte-identical, so
+  // it is a no-op for every existing deployment; under a custom prefix it
+  // namespaces these tables the same way the mapped names are namespaced.
+  return _applyPrefix(localName);
 }
 
 // ---- Dialect-specific column types ----
-// TEXT and BOOLEAN are identical across both. INTEGER and BLOB diverge.
+// BOOLEAN is identical across all three. INTEGER, BLOB, and the
+// "TEXT-used-in-a-key" token diverge.
+//
+//   INT  — ms-epoch counters / timestamps. Postgres BIGINT, SQLite
+//          INTEGER, MySQL BIGINT (a 32-bit INTEGER overflows a
+//          Date.now() ms value, so BIGINT is required on MySQL too).
+//   BLOB — Postgres BYTEA, SQLite BLOB, MySQL LONGBLOB.
+//   KT   — "key text": a TEXT column that appears in a PRIMARY KEY or an
+//          index. MySQL refuses BLOB/TEXT in a key without a prefix
+//          length, so on MySQL such columns must be VARCHAR(n). 191 is
+//          the utf8mb4 index-safe length (191 * 4 bytes = 764 < the
+//          historical 767-byte InnoDB index-prefix limit), so a KT
+//          column is index-safe under every default MySQL/InnoDB
+//          configuration. On Postgres + SQLite a KT column is plain
+//          TEXT (both index TEXT without a length), so the on-disk shape
+//          is byte-identical to the historical schema there.
+//
+// Plain TEXT columns that are NEVER in a key (free-form payloads,
+// metadata, reason strings) stay TEXT on every dialect — only key
+// participants take the VARCHAR(n) treatment, so column values are not
+// length-capped beyond what the schema needs.
+var MYSQL_KEY_TEXT_LEN = 191;
 
+//   DT   — "defaulted text": a short TEXT column that carries a string
+//          DEFAULT (e.g. an enum-like 'throw' / 'cleartext'). MySQL refuses
+//          a DEFAULT on a TEXT/BLOB column (error 1101), so such a column is
+//          VARCHAR(n) on MySQL and plain TEXT on Postgres + SQLite (both
+//          allow a TEXT default). Same VARCHAR(191) width as KT.
 function _types(dialect) {
   if (dialect === "postgres") {
-    return { INT: "BIGINT", BLOB: "BYTEA" };
+    return { INT: "BIGINT", BLOB: "BYTEA", KT: "TEXT", DT: "TEXT" };
   }
   if (dialect === "sqlite") {
-    return { INT: "INTEGER", BLOB: "BLOB" };
+    return { INT: "INTEGER", BLOB: "BLOB", KT: "TEXT", DT: "TEXT" };
+  }
+  if (dialect === "mysql") {
+    return {
+      INT:  "BIGINT",
+      BLOB: "LONGBLOB",
+      KT:   "VARCHAR(" + MYSQL_KEY_TEXT_LEN + ")",
+      DT:   "VARCHAR(" + MYSQL_KEY_TEXT_LEN + ")",
+    };
   }
   throw new FrameworkSchemaError(
-    "unsupported dialect '" + dialect + "' (postgres or sqlite)",
+    "unsupported dialect '" + dialect + "' (postgres, sqlite, or mysql)",
     "framework-schema/unsupported-dialect"
   );
 }
 
-// ---- Table DDL builders ----
+// ---- Declarative, quote-by-construction DDL builder ----
 //
-// Each builder returns { create: <CREATE TABLE SQL>, indexes: [<CREATE INDEX SQL>, ...] }.
+// Every column identifier is emitted through safeSql.quoteIdentifier so
+// the on-disk name preserves its camelCase EXACTLY on every dialect.
+// Postgres folds UNQUOTED identifiers to lowercase; the framework's DML
+// reads camelCase (`row.rowHash` / `row.monotonicCounter`) and the
+// chain-writer INSERTs safeSql.quoteIdentifier-quoted camelCase columns,
+// so the DDL MUST quote to match — an unquoted DDL silently breaks the
+// audit chain, consent chain, and cluster leadership on Postgres
+// (the INSERT targets a column that doesn't exist; SELECT * returns
+// lowercase keys). Quoting also makes reserved-word columns (`key`,
+// `count`, `name`) safe by construction.
+//
+// A column entry is one of:
+//   { col: "<name>", def: "<TYPE> [constraints]" }   → "<name>" <TYPE> ...
+//   { pk:  ["<col>", ...] }                            → PRIMARY KEY ("a", "b")
+//   { raw: "<verbatim clause>" }                       → table-level CHECK etc.
+// An index entry is { suffix, cols: [...], unique? }.
+//
+// Each builder returns { create: <CREATE TABLE SQL>, indexes: [...] }.
 // All DDL uses IF NOT EXISTS so re-running is idempotent.
 
-function _auditLogDDL(dialect) {
-  var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL.audit_log;
+// safeSql.quoteIdentifier dialect token: mysql → backtick, everything
+// else → double-quote (postgres + sqlite share the SQL-standard form).
+function _qd(dialect) {
+  return dialect === "mysql" ? "mysql" : (dialect === "sqlite" ? "sqlite" : "postgres");
+}
+
+function _buildCreate(name, dialect, columns) {
+  var qd = _qd(dialect);
+  var parts = columns.map(function (c) {
+    if (c.raw) return "  " + c.raw;
+    if (c.pk) {
+      return "  PRIMARY KEY (" +
+        c.pk.map(function (k) { return safeSql.quoteIdentifier(k, qd); }).join(", ") + ")";
+    }
+    return "  " + safeSql.quoteIdentifier(c.col, qd) + " " + c.def;
+  });
+  return "CREATE TABLE IF NOT EXISTS " + name + " (" + parts.join(",") + ")";
+}
+
+// Cap a generated index name to the strictest dialect identifier limit
+// (Postgres NAMEDATALEN 63). A longer name is truncated with a short stable
+// checksum suffix so two long names cannot collide after truncation. The
+// name is a fresh label (never quoted / re-referenced), so sanitizing to a
+// bare identifier is safe.
+function _capIndexName(raw) {
+  // Framework index names are built from controlled identifiers (the
+  // _blamejs_* table name + an identifier suffix), so only the length needs
+  // bounding - a name over the limit is truncated with a short stable
+  // checksum suffix so two long names can't collide after truncation.
+  if (raw.length <= safeSql.MAX_IDENTIFIER_LENGTH) return raw;
+  var h = 0;
+  for (var i = 0; i < raw.length; i += 1) h = (h * 31 + raw.charCodeAt(i)) >>> 0;
+  return raw.slice(0, safeSql.MAX_IDENTIFIER_LENGTH - 9) + "_" + h.toString(36);
+}
+
+function _buildIndexes(name, dialect, indexes) {
+  var qd = _qd(dialect);
+  // MySQL has no CREATE INDEX IF NOT EXISTS — the clause is a syntax error
+  // there. Postgres + SQLite support it (idempotent re-creation). On MySQL
+  // the bare CREATE INDEX is emitted and ensureSchema swallows the
+  // duplicate-key-name error on re-run so the idempotence contract holds.
+  // The keyword phrase is a per-dialect string LITERAL (not a keyword + a
+  // variable) so the identifier-quoting detector reads it as the static
+  // clause it is.
+  var createIndex = dialect === "mysql" ? "CREATE INDEX " : "CREATE INDEX IF NOT EXISTS ";
+  var createUnique = dialect === "mysql" ? "CREATE UNIQUE INDEX " : "CREATE UNIQUE INDEX IF NOT EXISTS ";
+  return (indexes || []).map(function (ix) {
+    var idxName = _capIndexName("idx_" + name + "_" + ix.suffix);
+    return (ix.unique ? createUnique : createIndex) + idxName + " ON " + name +
+      " (" + ix.cols.map(function (col) { return safeSql.quoteIdentifier(col, qd); }).join(", ") + ")";
+  });
+}
+
+function _table(name, dialect, columns, indexes) {
   return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  _id                  TEXT PRIMARY KEY," +
-      "  recordedAt           " + t.INT + " NOT NULL," +
-      "  monotonicCounter     " + t.INT + " NOT NULL," +
-      "  actorUserId          TEXT," +
-      "  actorUserIdHash      TEXT," +
-      "  actorIp              TEXT," +
-      "  actorUserAgent       TEXT," +
-      "  actorSessionId       TEXT," +
-      "  action               TEXT NOT NULL," +
-      "  resourceKind         TEXT," +
-      "  resourceId           TEXT," +
-      "  resourceIdHash       TEXT," +
-      "  outcome              TEXT NOT NULL," +
-      "  reason               TEXT," +
-      "  metadata             TEXT," +
-      "  requestId            TEXT," +
-      "  prevHash             TEXT NOT NULL," +
-      "  rowHash              TEXT NOT NULL," +
-      "  nonce                " + t.BLOB + " NOT NULL," +
-      "  fencingToken         " + t.INT + " NOT NULL DEFAULT 0" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_actorUserIdHash ON " + name + " (actorUserIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_resourceIdHash ON " + name + " (resourceIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_recordedAt ON " + name + " (recordedAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_action ON " + name + " (action)",
-      "CREATE UNIQUE INDEX IF NOT EXISTS idx_" + name + "_monotonic ON " + name + " (monotonicCounter)",
-    ],
+    create:  _buildCreate(name, dialect, columns),
+    indexes: _buildIndexes(name, dialect, indexes),
   };
 }
 
+function _auditLogDDL(dialect) {
+  var t = _types(dialect);
+  return _table(tableName("audit_log"), dialect, [
+    { col: "_id",              def: t.KT + " PRIMARY KEY" },
+    { col: "recordedAt",       def: t.INT + " NOT NULL" },
+    { col: "monotonicCounter", def: t.INT + " NOT NULL" },
+    { col: "actorUserId",      def: "TEXT" },
+    { col: "actorUserIdHash",  def: t.KT },
+    { col: "actorIp",          def: "TEXT" },
+    { col: "actorUserAgent",   def: "TEXT" },
+    { col: "actorSessionId",   def: "TEXT" },
+    { col: "action",           def: t.KT + " NOT NULL" },
+    { col: "resourceKind",     def: t.KT },
+    { col: "resourceId",       def: "TEXT" },
+    { col: "resourceIdHash",   def: t.KT },
+    { col: "outcome",          def: t.KT + " NOT NULL" },
+    { col: "reason",           def: "TEXT" },
+    { col: "metadata",         def: "TEXT" },
+    { col: "requestId",        def: "TEXT" },
+    { col: "prevHash",         def: "TEXT NOT NULL" },
+    { col: "rowHash",          def: "TEXT NOT NULL" },
+    { col: "nonce",            def: t.BLOB + " NOT NULL" },
+    { col: "fencingToken",     def: t.INT + " NOT NULL DEFAULT 0" },
+  ], [
+    { suffix: "actorUserIdHash", cols: ["actorUserIdHash"] },
+    { suffix: "resourceIdHash",  cols: ["resourceIdHash"] },
+    { suffix: "recordedAt",      cols: ["recordedAt"] },
+    { suffix: "action",          cols: ["action"] },
+    { suffix: "resourceKind",    cols: ["resourceKind"] },
+    { suffix: "outcome",         cols: ["outcome"] },
+    { suffix: "monotonic",       cols: ["monotonicCounter"], unique: true },
+  ]);
+}
+
 function _consentLogDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL.consent_log;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  _id                  TEXT PRIMARY KEY," +
-      "  recordedAt           " + t.INT + " NOT NULL," +
-      "  monotonicCounter     " + t.INT + " NOT NULL," +
-      "  subjectId            TEXT NOT NULL," +
-      "  subjectIdHash        TEXT NOT NULL," +
-      "  purpose              TEXT NOT NULL," +
-      "  lawfulBasis          TEXT NOT NULL," +
-      "  action               TEXT NOT NULL," +
-      "  scope                TEXT," +
-      "  channel              TEXT NOT NULL," +
-      "  evidenceRef          TEXT," +
-      "  prevHash             TEXT NOT NULL," +
-      "  rowHash              TEXT NOT NULL," +
-      "  nonce                " + t.BLOB + " NOT NULL," +
-      "  fencingToken         " + t.INT + " NOT NULL DEFAULT 0" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_subjectIdHash ON " + name + " (subjectIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_recordedAt ON " + name + " (recordedAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_purpose ON " + name + " (purpose)",
-      "CREATE UNIQUE INDEX IF NOT EXISTS idx_" + name + "_monotonic ON " + name + " (monotonicCounter)",
-    ],
-  };
+  return _table(tableName("consent_log"), dialect, [
+    { col: "_id",              def: t.KT + " PRIMARY KEY" },
+    { col: "recordedAt",       def: t.INT + " NOT NULL" },
+    { col: "monotonicCounter", def: t.INT + " NOT NULL" },
+    { col: "subjectId",        def: "TEXT NOT NULL" },
+    { col: "subjectIdHash",    def: t.KT + " NOT NULL" },
+    { col: "purpose",          def: t.KT + " NOT NULL" },
+    { col: "lawfulBasis",      def: "TEXT NOT NULL" },
+    { col: "action",           def: "TEXT NOT NULL" },
+    { col: "scope",            def: "TEXT" },
+    { col: "channel",          def: "TEXT NOT NULL" },
+    { col: "evidenceRef",      def: "TEXT" },
+    { col: "prevHash",         def: "TEXT NOT NULL" },
+    { col: "rowHash",          def: "TEXT NOT NULL" },
+    { col: "nonce",            def: t.BLOB + " NOT NULL" },
+    { col: "fencingToken",     def: t.INT + " NOT NULL DEFAULT 0" },
+  ], [
+    { suffix: "subjectIdHash", cols: ["subjectIdHash"] },
+    { suffix: "recordedAt",    cols: ["recordedAt"] },
+    { suffix: "purpose",       cols: ["purpose"] },
+    { suffix: "monotonic",     cols: ["monotonicCounter"], unique: true },
+  ]);
 }
 
 function _auditCheckpointsDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL.audit_checkpoints;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  _id                  TEXT PRIMARY KEY," +
-      "  createdAt            " + t.INT + " NOT NULL," +
-      "  atMonotonicCounter   " + t.INT + " NOT NULL," +
-      "  atRowHash            TEXT NOT NULL," +
-      "  signature            " + t.BLOB + " NOT NULL," +
-      "  publicKeyFingerprint TEXT NOT NULL," +
-      "  fencingToken         " + t.INT + " NOT NULL DEFAULT 0" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_createdAt ON " + name + " (createdAt)",
-      "CREATE UNIQUE INDEX IF NOT EXISTS idx_" + name + "_chkpt_counter ON " + name + " (atMonotonicCounter)",
-    ],
-  };
+  return _table(tableName("audit_checkpoints"), dialect, [
+    { col: "_id",                  def: t.KT + " PRIMARY KEY" },
+    { col: "createdAt",            def: t.INT + " NOT NULL" },
+    { col: "atMonotonicCounter",   def: t.INT + " NOT NULL" },
+    { col: "atRowHash",            def: "TEXT NOT NULL" },
+    { col: "signature",            def: t.BLOB + " NOT NULL" },
+    { col: "publicKeyFingerprint", def: "TEXT NOT NULL" },
+    { col: "fencingToken",         def: t.INT + " NOT NULL DEFAULT 0" },
+  ], [
+    { suffix: "createdAt",     cols: ["createdAt"] },
+    { suffix: "chkpt_counter", cols: ["atMonotonicCounter"], unique: true },
+  ]);
 }
 
 // audit_tip is single-row coordination state for cluster-mode rollback
@@ -291,19 +490,14 @@ function _auditCheckpointsDDL(dialect) {
 // `scope` column.
 function _auditTipDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_audit_tip;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  scope                TEXT PRIMARY KEY," +
-      "  atMonotonicCounter   " + t.INT + " NOT NULL," +
-      "  rowHash              TEXT," +
-      "  signedAt             TEXT," +
-      "  fencingToken         " + t.INT + " NOT NULL DEFAULT 0," +
-      "  CHECK (scope = 'audit')" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_audit_tip"), dialect, [
+    { col: "scope",              def: t.KT + " PRIMARY KEY" },
+    { col: "atMonotonicCounter", def: t.INT + " NOT NULL" },
+    { col: "rowHash",            def: "TEXT" },
+    { col: "signedAt",           def: "TEXT" },
+    { col: "fencingToken",       def: t.INT + " NOT NULL DEFAULT 0" },
+    { raw: "CHECK (" + safeSql.quoteIdentifier("scope", _qd(dialect)) + " = 'audit')" },
+  ], []);
 }
 
 // Same shape + invariants as audit_tip but for the consent chain.
@@ -312,19 +506,14 @@ function _auditTipDDL(dialect) {
 // consent chain (previously only the audit chain had this protection).
 function _consentTipDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_consent_tip;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  scope                TEXT PRIMARY KEY," +
-      "  atMonotonicCounter   " + t.INT + " NOT NULL," +
-      "  rowHash              TEXT," +
-      "  signedAt             TEXT," +
-      "  fencingToken         " + t.INT + " NOT NULL DEFAULT 0," +
-      "  CHECK (scope = 'consent')" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_consent_tip"), dialect, [
+    { col: "scope",              def: t.KT + " PRIMARY KEY" },
+    { col: "atMonotonicCounter", def: t.INT + " NOT NULL" },
+    { col: "rowHash",            def: "TEXT" },
+    { col: "signedAt",           def: "TEXT" },
+    { col: "fencingToken",       def: t.INT + " NOT NULL DEFAULT 0" },
+    { raw: "CHECK (" + safeSql.quoteIdentifier("scope", _qd(dialect)) + " = 'consent')" },
+  ], []);
 }
 
 // _blamejs_audit_purge_anchor — single-row chain-origin anchor written
@@ -334,19 +523,14 @@ function _consentTipDDL(dialect) {
 // column (matches _blamejs_audit_tip pattern).
 function _auditPurgeAnchorDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_audit_purge_anchor;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  scope             TEXT PRIMARY KEY," +
-      "  lastPurgedCounter " + t.INT + " NOT NULL," +
-      "  lastPurgedRowHash TEXT NOT NULL," +
-      "  archiveBundleId   TEXT NOT NULL," +
-      "  purgedAt          " + t.INT + " NOT NULL," +
-      "  CHECK (scope = 'audit')" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_audit_purge_anchor"), dialect, [
+    { col: "scope",             def: t.KT + " PRIMARY KEY" },
+    { col: "lastPurgedCounter", def: t.INT + " NOT NULL" },
+    { col: "lastPurgedRowHash", def: "TEXT NOT NULL" },
+    { col: "archiveBundleId",   def: "TEXT NOT NULL" },
+    { col: "purgedAt",          def: t.INT + " NOT NULL" },
+    { raw: "CHECK (" + safeSql.quoteIdentifier("scope", _qd(dialect)) + " = 'audit')" },
+  ], []);
 }
 
 // _blamejs_scheduler_ticks — exactly-once tick-claim table. PRIMARY KEY
@@ -354,20 +538,15 @@ function _auditPurgeAnchorDDL(dialect) {
 // the tick. claimedBy carries the node id for diagnostic.
 function _schedulerTicksDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_scheduler_ticks;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  tickKey         TEXT PRIMARY KEY," +
-      "  name            TEXT NOT NULL," +
-      "  scheduledAtUnix " + t.INT + " NOT NULL," +
-      "  claimedAtUnix   " + t.INT + " NOT NULL," +
-      "  claimedBy       TEXT" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_scheduledAt ON " + name + " (scheduledAtUnix)",
-    ],
-  };
+  return _table(tableName("_blamejs_scheduler_ticks"), dialect, [
+    { col: "tickKey",         def: t.KT + " PRIMARY KEY" },
+    { col: "name",            def: "TEXT NOT NULL" },
+    { col: "scheduledAtUnix", def: t.INT + " NOT NULL" },
+    { col: "claimedAtUnix",   def: t.INT + " NOT NULL" },
+    { col: "claimedBy",       def: "TEXT" },
+  ], [
+    { suffix: "scheduledAt", cols: ["scheduledAtUnix"] },
+  ]);
 }
 
 // _blamejs_rate_limit_counters — fixed-window counter table for the
@@ -377,60 +556,48 @@ function _schedulerTicksDDL(dialect) {
 // retention sweeps of expired windows.
 function _rateLimitCountersDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_rate_limit_counters;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  key         TEXT PRIMARY KEY," +
-      "  windowStart " + t.INT + " NOT NULL," +
-      "  count       " + t.INT + " NOT NULL DEFAULT 0" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_windowStart ON " + name + " (windowStart)",
-    ],
-  };
+  return _table(tableName("_blamejs_rate_limit_counters"), dialect, [
+    { col: "key",         def: t.KT + " PRIMARY KEY" },
+    { col: "windowStart", def: t.INT + " NOT NULL" },
+    { col: "count",       def: t.INT + " NOT NULL DEFAULT 0" },
+  ], [
+    { suffix: "windowStart", cols: ["windowStart"] },
+  ]);
 }
 
 // _blamejs_pubsub_messages — cluster fan-out for `b.pubsub` (the
 // generalization of the previous WebSocket-specific table). publish()
 // on any node writes a row; other nodes poll for new ids past their
 // last seen and dispatch to local subscribers. Auto-incrementing id
-// is essential — postgres needs BIGSERIAL, sqlite gets INTEGER
-// PRIMARY KEY (which auto-increments implicitly).
+// is essential — postgres needs BIGSERIAL, sqlite gets INTEGER PRIMARY
+// KEY (which auto-increments implicitly), mysql gets BIGINT
+// AUTO_INCREMENT (which requires an explicit PRIMARY KEY clause).
 function _pubsubMessagesDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_pubsub_messages;
-  var idCol = dialect === "postgres"
-    ? "id          BIGSERIAL PRIMARY KEY"
-    : "id          INTEGER PRIMARY KEY AUTOINCREMENT";
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  " + idCol + "," +
-      "  topic       TEXT NOT NULL," +
-      "  payload     TEXT NOT NULL," +
-      "  publishedAt " + t.INT + " NOT NULL," +
-      "  publishedBy TEXT NOT NULL" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_publishedAt ON " + name + " (publishedAt)",
-    ],
-  };
+  var idType = dialect === "postgres"
+    ? "BIGSERIAL PRIMARY KEY"
+    : (dialect === "mysql"
+        ? "BIGINT AUTO_INCREMENT PRIMARY KEY"
+        : "INTEGER PRIMARY KEY AUTOINCREMENT");
+  return _table(tableName("_blamejs_pubsub_messages"), dialect, [
+    { col: "id",          def: idType },
+    { col: "topic",       def: "TEXT NOT NULL" },
+    { col: "payload",     def: "TEXT NOT NULL" },
+    { col: "publishedAt", def: t.INT + " NOT NULL" },
+    { col: "publishedBy", def: "TEXT NOT NULL" },
+  ], [
+    { suffix: "publishedAt", cols: ["publishedAt"] },
+  ]);
 }
 
 function _apiEncryptNoncesDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_api_encrypt_nonces;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  nonceHash TEXT PRIMARY KEY," +
-      "  expireAt  " + t.INT + " NOT NULL" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_expireAt ON " + name + " (expireAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_api_encrypt_nonces"), dialect, [
+    { col: "nonceHash", def: t.KT + " PRIMARY KEY" },
+    { col: "expireAt",  def: t.INT + " NOT NULL" },
+  ], [
+    { suffix: "expireAt", cols: ["expireAt"] },
+  ]);
 }
 
 // _blamejs_api_keys — operator-facing API-key registry. PRIMARY KEY is
@@ -439,31 +606,26 @@ function _apiEncryptNoncesDDL(dialect) {
 // lookups; expiresAt index supports purgeExpired sweeps.
 function _apiKeysDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_api_keys;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  id                    TEXT PRIMARY KEY," +
-      "  namespace             TEXT NOT NULL," +
-      "  ownerId               TEXT NOT NULL," +
-      "  ownerIdHash           TEXT NOT NULL," +
-      "  secretHash            TEXT NOT NULL," +
-      "  secondarySecretHash   TEXT," +
-      "  secondaryExpiresAt    " + t.INT + "," +
-      "  scopes                TEXT," +
-      "  metadata              TEXT," +
-      "  createdAt             " + t.INT + " NOT NULL," +
-      "  expiresAt             " + t.INT + "," +
-      "  revokedAt             " + t.INT + "," +
-      "  lastUsedAt            " + t.INT + "," +
-      "  prefix                TEXT NOT NULL" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_ownerIdHash ON " + name + " (ownerIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_namespace_owner ON " + name + " (namespace, ownerIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_expiresAt ON " + name + " (expiresAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_api_keys"), dialect, [
+    { col: "id",                  def: t.KT + " PRIMARY KEY" },
+    { col: "namespace",           def: t.KT + " NOT NULL" },
+    { col: "ownerId",             def: "TEXT NOT NULL" },
+    { col: "ownerIdHash",         def: t.KT + " NOT NULL" },
+    { col: "secretHash",          def: "TEXT NOT NULL" },
+    { col: "secondarySecretHash", def: "TEXT" },
+    { col: "secondaryExpiresAt",  def: t.INT },
+    { col: "scopes",              def: "TEXT" },
+    { col: "metadata",            def: "TEXT" },
+    { col: "createdAt",           def: t.INT + " NOT NULL" },
+    { col: "expiresAt",           def: t.INT },
+    { col: "revokedAt",           def: t.INT },
+    { col: "lastUsedAt",          def: t.INT },
+    { col: "prefix",              def: "TEXT NOT NULL" },
+  ], [
+    { suffix: "ownerIdHash",     cols: ["ownerIdHash"] },
+    { suffix: "namespace_owner", cols: ["namespace", "ownerIdHash"] },
+    { suffix: "expiresAt",       cols: ["expiresAt"] },
+  ]);
 }
 
 // _blamejs_sessions — DB-backed session store. Mirrors the local-SQLite
@@ -473,23 +635,18 @@ function _apiKeysDDL(dialect) {
 // session id never lands here).
 function _sessionsDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_sessions;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  sidHash         TEXT PRIMARY KEY," +
-      "  userId          TEXT NOT NULL," +
-      "  userIdHash      TEXT NOT NULL," +
-      "  data            TEXT," +
-      "  createdAt       " + t.INT + " NOT NULL," +
-      "  expiresAt       " + t.INT + " NOT NULL," +
-      "  lastActivity    " + t.INT + " NOT NULL" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_userIdHash ON " + name + " (userIdHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_expiresAt ON " + name + " (expiresAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_sessions"), dialect, [
+    { col: "sidHash",      def: t.KT + " PRIMARY KEY" },
+    { col: "userId",       def: "TEXT NOT NULL" },
+    { col: "userIdHash",   def: t.KT + " NOT NULL" },
+    { col: "data",         def: "TEXT" },
+    { col: "createdAt",    def: t.INT + " NOT NULL" },
+    { col: "expiresAt",    def: t.INT + " NOT NULL" },
+    { col: "lastActivity", def: t.INT + " NOT NULL" },
+  ], [
+    { suffix: "userIdHash", cols: ["userIdHash"] },
+    { suffix: "expiresAt",  cols: ["expiresAt"] },
+  ]);
 }
 
 // _blamejs_jobs — local-protocol queue jobs. Mirrors db.js's
@@ -499,39 +656,34 @@ function _sessionsDDL(dialect) {
 // sweep (leaseExpiresAt).
 function _jobsDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_jobs;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  _id              TEXT PRIMARY KEY," +
-      "  queueName        TEXT NOT NULL," +
-      "  payload          TEXT," +
-      "  status           TEXT NOT NULL," +
-      "  enqueuedAt       " + t.INT + " NOT NULL," +
-      "  availableAt      " + t.INT + " NOT NULL," +
-      "  leasedAt         " + t.INT + "," +
-      "  leaseExpiresAt   " + t.INT + "," +
-      "  attempts         " + t.INT + " NOT NULL DEFAULT 0," +
-      "  maxAttempts      " + t.INT + " NOT NULL DEFAULT 5," +
-      "  lastError        TEXT," +
-      "  finishedAt       " + t.INT + "," +
-      "  traceId          TEXT," +
-      "  classification   TEXT," +
-      "  priority         " + t.INT + " NOT NULL DEFAULT 0," +
-      "  repeatCron       TEXT," +
-      "  repeatTimezone   TEXT," +
-      "  flowId           TEXT," +
-      "  flowChildName    TEXT," +
-      "  dependsOn        TEXT" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_lease ON " + name + " (queueName, status, availableAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_priority ON " + name + " (queueName, status, priority, availableAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_flow ON " + name + " (flowId)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_leaseExpiresAt ON " + name + " (leaseExpiresAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_finishedAt ON " + name + " (finishedAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_jobs"), dialect, [
+    { col: "_id",            def: t.KT + " PRIMARY KEY" },
+    { col: "queueName",      def: t.KT + " NOT NULL" },
+    { col: "payload",        def: "TEXT" },
+    { col: "status",         def: t.KT + " NOT NULL" },
+    { col: "enqueuedAt",     def: t.INT + " NOT NULL" },
+    { col: "availableAt",    def: t.INT + " NOT NULL" },
+    { col: "leasedAt",       def: t.INT },
+    { col: "leaseExpiresAt", def: t.INT },
+    { col: "attempts",       def: t.INT + " NOT NULL DEFAULT 0" },
+    { col: "maxAttempts",    def: t.INT + " NOT NULL DEFAULT 5" },
+    { col: "lastError",      def: "TEXT" },
+    { col: "finishedAt",     def: t.INT },
+    { col: "traceId",        def: "TEXT" },
+    { col: "classification", def: "TEXT" },
+    { col: "priority",       def: t.INT + " NOT NULL DEFAULT 0" },
+    { col: "repeatCron",     def: "TEXT" },
+    { col: "repeatTimezone", def: "TEXT" },
+    { col: "flowId",         def: t.KT },
+    { col: "flowChildName",  def: "TEXT" },
+    { col: "dependsOn",      def: "TEXT" },
+  ], [
+    { suffix: "lease",          cols: ["queueName", "status", "availableAt"] },
+    { suffix: "priority",       cols: ["queueName", "status", "priority", "availableAt"] },
+    { suffix: "flow",           cols: ["flowId"] },
+    { suffix: "leaseExpiresAt", cols: ["leaseExpiresAt"] },
+    { suffix: "finishedAt",     cols: ["finishedAt"] },
+  ]);
 }
 
 // _blamejs_seeders — registry of applied seed files for the b.seeders
@@ -541,35 +693,26 @@ function _jobsDDL(dialect) {
 // entries are insert-once.
 function _seedersDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_seeders;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  env         TEXT NOT NULL," +
-      "  name        TEXT NOT NULL," +
-      "  description TEXT," +
-      "  appliedAt   TEXT NOT NULL," +
-      "  rerunnable  " + t.INT + " NOT NULL DEFAULT 0," +
-      "  PRIMARY KEY (env, name)" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_seeders"), dialect, [
+    { col: "env",         def: t.KT + " NOT NULL" },
+    { col: "name",        def: t.KT + " NOT NULL" },
+    { col: "description", def: "TEXT" },
+    { col: "appliedAt",   def: "TEXT NOT NULL" },
+    { col: "rerunnable",  def: t.INT + " NOT NULL DEFAULT 0" },
+    { pk: ["env", "name"] },
+  ], []);
 }
 
 // _blamejs_seeders_lock — single-row advisory lock matching the
 // _blamejs_migrations_lock pattern. CHECK enforces single row.
 function _seedersLockDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_seeders_lock;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  scope     TEXT PRIMARY KEY CHECK (scope = 'lock')," +
-      "  lockedAt  " + t.INT + " NOT NULL," +
-      "  lockedBy  TEXT NOT NULL" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_seeders_lock"), dialect, [
+    { col: "scope",    def: t.KT + " PRIMARY KEY CHECK (" +
+                            safeSql.quoteIdentifier("scope", _qd(dialect)) + " = 'lock')" },
+    { col: "lockedAt", def: t.INT + " NOT NULL" },
+    { col: "lockedBy", def: "TEXT NOT NULL" },
+  ], []);
 }
 
 // _blamejs_cache — operator-facing cache primitive's cluster backend
@@ -581,39 +724,33 @@ function _seedersLockDDL(dialect) {
 // expiresAt for the periodic prune query.
 function _cacheDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_cache;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  cacheKey      TEXT PRIMARY KEY," +
-      "  valueJson     TEXT NOT NULL," +
-      "  expiresAt     " + t.INT + " NOT NULL," +
-      "  updatedAt     " + t.INT + " NOT NULL" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_expiresAt ON " + name + " (expiresAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_cache"), dialect, [
+    { col: "cacheKey",  def: t.KT + " PRIMARY KEY" },
+    { col: "valueJson", def: "TEXT NOT NULL" },
+    { col: "expiresAt", def: t.INT + " NOT NULL" },
+    { col: "updatedAt", def: t.INT + " NOT NULL" },
+  ], [
+    { suffix: "expiresAt", cols: ["expiresAt"] },
+  ]);
 }
 
 // _blamejs_cache_tags — tag→cacheKey junction for cluster-backend
 // tag invalidation. b.cache.invalidateTag(t) finds matching cacheKeys
 // via the indexed `tag` column, deletes them from _blamejs_cache, and
 // drops the junction rows. Cleared on cache.clear() and del() too.
-function _cacheTagsDDL(_dialect) {
-  // Junction table is TEXT-only — no dialect-specific INT / BLOB needed.
-  var name = LOCAL_TO_EXTERNAL._blamejs_cache_tags;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  cacheKey  TEXT NOT NULL," +
-      "  tag       TEXT NOT NULL," +
-      "  PRIMARY KEY (cacheKey, tag)" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_tag ON " + name + " (tag)",
-    ],
-  };
+function _cacheTagsDDL(dialect) {
+  // Junction table is TEXT-only, but every column participates in a key
+  // (composite PK + the tag index), so all take the key-text token —
+  // VARCHAR(n) on MySQL (TEXT in a key is refused there), plain TEXT on
+  // Postgres + SQLite.
+  var t = _types(dialect);
+  return _table(tableName("_blamejs_cache_tags"), dialect, [
+    { col: "cacheKey", def: t.KT + " NOT NULL" },
+    { col: "tag",      def: t.KT + " NOT NULL" },
+    { pk: ["cacheKey", "tag"] },
+  ], [
+    { suffix: "tag", cols: ["tag"] },
+  ]);
 }
 
 // _blamejs_break_glass_policies — column-level break-glass policy
@@ -622,29 +759,24 @@ function _cacheTagsDDL(_dialect) {
 // column-list / factor-list / bypass config from cleartext browsing.
 function _breakGlassPoliciesDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_break_glass_policies;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  tableName                  TEXT PRIMARY KEY," +
-      "  columnsJson                TEXT NOT NULL," +
-      "  factorsJson                TEXT NOT NULL," +
-      "  cryptographic              " + t.INT + " NOT NULL DEFAULT 0," +
-      "  grantTtlMs                 " + t.INT + " NOT NULL," +
-      "  maxRowsPerGrant            " + t.INT + " NOT NULL DEFAULT 1," +
-      "  reasonRequired             " + t.INT + " NOT NULL DEFAULT 1," +
-      "  reasonMinLength            " + t.INT + " NOT NULL DEFAULT 12," +
-      "  pinIp                      " + t.INT + " NOT NULL DEFAULT 1," +
-      "  sessionPin                 " + t.INT + " NOT NULL DEFAULT 1," +
-      "  onLockedAccess             TEXT NOT NULL DEFAULT 'throw'," +
-      "  requireScope               TEXT," +
-      "  serviceAccountBypassJson   TEXT," +
-      "  dekSealed                  TEXT," +
-      "  auditReasonStorage         TEXT NOT NULL DEFAULT 'cleartext'," +
-      "  updatedAt                  " + t.INT + " NOT NULL" +
-      ")",
-    indexes: [],
-  };
+  return _table(tableName("_blamejs_break_glass_policies"), dialect, [
+    { col: "tableName",                def: t.KT + " PRIMARY KEY" },
+    { col: "columnsJson",              def: "TEXT NOT NULL" },
+    { col: "factorsJson",              def: "TEXT NOT NULL" },
+    { col: "cryptographic",            def: t.INT + " NOT NULL DEFAULT 0" },
+    { col: "grantTtlMs",               def: t.INT + " NOT NULL" },
+    { col: "maxRowsPerGrant",          def: t.INT + " NOT NULL DEFAULT 1" },
+    { col: "reasonRequired",           def: t.INT + " NOT NULL DEFAULT 1" },
+    { col: "reasonMinLength",          def: t.INT + " NOT NULL DEFAULT 12" },
+    { col: "pinIp",                    def: t.INT + " NOT NULL DEFAULT 1" },
+    { col: "sessionPin",               def: t.INT + " NOT NULL DEFAULT 1" },
+    { col: "onLockedAccess",           def: t.DT + " NOT NULL DEFAULT 'throw'" },
+    { col: "requireScope",             def: "TEXT" },
+    { col: "serviceAccountBypassJson", def: "TEXT" },
+    { col: "dekSealed",                def: "TEXT" },
+    { col: "auditReasonStorage",       def: t.DT + " NOT NULL DEFAULT 'cleartext'" },
+    { col: "updatedAt",                def: t.INT + " NOT NULL" },
+  ], []);
 }
 
 // _blamejs_break_glass_grants — issued grants. One row per successful
@@ -652,33 +784,174 @@ function _breakGlassPoliciesDDL(dialect) {
 // ("each row access = its own grant").
 function _breakGlassGrantsDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_break_glass_grants;
-  return {
-    create:
-      "CREATE TABLE IF NOT EXISTS " + name + " (" +
-      "  _id                TEXT PRIMARY KEY," +
-      "  issuedToActorId    TEXT NOT NULL," +
-      "  issuedToActorHash  TEXT NOT NULL," +
-      "  factorType         TEXT NOT NULL," +
-      "  reasonSealed       TEXT," +
-      "  scopeTable         TEXT NOT NULL," +
-      "  scopeColumnsJson   TEXT NOT NULL," +
-      "  issuedAt           " + t.INT + " NOT NULL," +
-      "  expiresAt          " + t.INT + " NOT NULL," +
-      "  maxRowsPerGrant    " + t.INT + " NOT NULL," +
-      "  rowsConsumed       " + t.INT + " NOT NULL DEFAULT 0," +
-      "  revokedAt          " + t.INT + "," +
-      "  sessionId          TEXT," +
-      "  ip                 TEXT," +
-      "  kwGrantHalf        TEXT" +
-      ")",
-    indexes: [
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_actor   ON " + name + " (issuedToActorHash)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_table   ON " + name + " (scopeTable)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_expires ON " + name + " (expiresAt)",
-      "CREATE INDEX IF NOT EXISTS idx_" + name + "_revoked ON " + name + " (revokedAt)",
-    ],
-  };
+  return _table(tableName("_blamejs_break_glass_grants"), dialect, [
+    { col: "_id",               def: t.KT + " PRIMARY KEY" },
+    { col: "issuedToActorId",   def: "TEXT NOT NULL" },
+    { col: "issuedToActorHash", def: t.KT + " NOT NULL" },
+    { col: "factorType",        def: "TEXT NOT NULL" },
+    { col: "reasonSealed",      def: "TEXT" },
+    { col: "scopeTable",        def: t.KT + " NOT NULL" },
+    { col: "scopeColumnsJson",  def: "TEXT NOT NULL" },
+    { col: "issuedAt",          def: t.INT + " NOT NULL" },
+    { col: "expiresAt",         def: t.INT + " NOT NULL" },
+    { col: "maxRowsPerGrant",   def: t.INT + " NOT NULL" },
+    { col: "rowsConsumed",      def: t.INT + " NOT NULL DEFAULT 0" },
+    { col: "revokedAt",         def: t.INT },
+    { col: "sessionId",         def: "TEXT" },
+    { col: "ip",                def: "TEXT" },
+    { col: "kwGrantHalf",       def: "TEXT" },
+  ], [
+    { suffix: "actor",   cols: ["issuedToActorHash"] },
+    { suffix: "table",   cols: ["scopeTable"] },
+    { suffix: "expires", cols: ["expiresAt"] },
+    { suffix: "revoked", cols: ["revokedAt"] },
+  ]);
+}
+
+// Every framework-owned table builder, in creation order. Single source
+// for ensureSchema's DDL pass AND the canonical-column registry below.
+function _allDDLs(dialect) {
+  return [
+    _auditLogDDL(dialect),
+    _consentLogDDL(dialect),
+    _auditCheckpointsDDL(dialect),
+    _auditTipDDL(dialect),
+    _consentTipDDL(dialect),
+    _auditPurgeAnchorDDL(dialect),
+    _schedulerTicksDDL(dialect),
+    _rateLimitCountersDDL(dialect),
+    _pubsubMessagesDDL(dialect),
+    _apiEncryptNoncesDDL(dialect),
+    _apiKeysDDL(dialect),
+    _sessionsDDL(dialect),
+    _jobsDDL(dialect),
+    _cacheDDL(dialect),
+    _cacheTagsDDL(dialect),
+    _seedersDDL(dialect),
+    _seedersLockDDL(dialect),
+    _breakGlassPoliciesDDL(dialect),
+    _breakGlassGrantsDDL(dialect),
+  ];
+}
+
+// Canonical, case-preserving column names across every framework table —
+// derived from the GENERATED DDL (the only quoted identifiers in a CREATE
+// statement are the column names; the table name is unquoted), so the set
+// can never drift from the actual schema. The codebase-patterns
+// `framework-column-must-be-quoted` detector consumes this set to flag any
+// camelCase framework-column reference left unquoted in SQL, which would
+// fold to lowercase on Postgres and miss the column. Computed once over
+// both supported dialects at module load.
+var CANONICAL_COLUMNS = (function () {
+  var set = new Set();
+  var all = _allDDLs("postgres").concat(_allDDLs("sqlite"));
+  for (var i = 0; i < all.length; i++) {
+    var quoted = all[i].create.match(/"([A-Za-z_][A-Za-z0-9_]*)"/g) || [];
+    for (var j = 0; j < quoted.length; j++) set.add(quoted[j].slice(1, -1));
+  }
+  return set;
+})();
+
+// Per-column type CATEGORY ("int" | "blob" | "text"), derived from the
+// generated DDL so it can never drift from the real schema. Drivers
+// disagree on the JS shape of non-text columns: node-postgres returns
+// BIGINT as a STRING and BYTEA as a Buffer; better-sqlite3 returns
+// INTEGER as a number and BLOB as a Buffer. coerceRow() uses this map to
+// normalize every framework column to one stable JS shape regardless of
+// backend — without it, BIGINT-as-string breaks numeric comparisons and
+// hash-chain recomputation on Postgres (the chain only verified on
+// SQLite). Computed once over both supported dialects at module load.
+var COLUMN_TYPES = (function () {
+  var map = {};
+  var all = _allDDLs("postgres").concat(_allDDLs("sqlite"));
+  // Match a quoted column name followed by its TYPE word (the PK-clause
+  // `("cacheKey", "tag")` form has a comma/paren after the name, never a
+  // type word, so it is correctly skipped).
+  var re = /"([A-Za-z_][A-Za-z0-9_]*)"\s+([A-Za-z]+)/g;
+  for (var i = 0; i < all.length; i++) {
+    var m; re.lastIndex = 0;
+    while ((m = re.exec(all[i].create)) !== null) {
+      var col = m[1];
+      if (Object.prototype.hasOwnProperty.call(map, col)) continue;  // first def wins
+      var typeWord = m[2].toUpperCase();
+      map[col] = (typeWord === "BIGINT" || typeWord === "INTEGER" ||
+                  typeWord === "INT"    || typeWord === "BIGSERIAL")
+        ? "int"
+        : (typeWord === "BYTEA" || typeWord === "BLOB") ? "blob" : "text";
+    }
+  }
+  return Object.freeze(map);
+})();
+
+/**
+ * @primitive b.frameworkSchema.coerceRow
+ * @signature b.frameworkSchema.coerceRow(row)
+ * @since     0.14.29
+ * @status    stable
+ * @related   b.frameworkSchema.coerceRows, b.externalDb.query
+ *
+ * Normalize one driver-returned framework row to a type-stable JS shape
+ * using `COLUMN_TYPES`, so a framework column reads identically on every
+ * backend: `int` columns become JS numbers (node-postgres hands BIGINT
+ * back as a string), `blob` columns become Buffers. `text` columns and
+ * any column NOT in the framework schema (operator tables, computed
+ * aliases) pass through untouched; `null` stays `null`. Idempotent — safe
+ * to call on an already-coerced or SQLite-shaped row. Mutates and returns
+ * the row.
+ *
+ * A BIGINT beyond `Number.MAX_SAFE_INTEGER` is left as a string rather
+ * than silently losing precision (framework counters/timestamps stay well
+ * within 2^53, so this never bites in practice).
+ *
+ * @example
+ *   var row = frameworkSchema.coerceRow(driverRow);
+ *   typeof row.monotonicCounter;  // → "number" (was "1" on Postgres)
+ *   Buffer.isBuffer(row.nonce);   // → true
+ */
+function coerceRow(row) {
+  if (!row || typeof row !== "object") return row;
+  var keys = Object.keys(row);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    var cat = COLUMN_TYPES[k];
+    if (!cat) continue;
+    var v = row[k];
+    if (v === null || v === undefined) continue;
+    if (cat === "int") {
+      // node-postgres returns BIGINT / int8 as a decimal string. Coerce
+      // back to a JS number only when it round-trips exactly as a safe
+      // integer (canonical decimal, no leading zeros or sign padding);
+      // leave anything outside safe-integer range as the string so no
+      // precision is silently lost.
+      if (typeof v === "string") {
+        var n = Number(v);
+        if (Number.isSafeInteger(n) && String(n) === v) row[k] = n;
+      }
+    } else if (cat === "blob") {
+      if (!Buffer.isBuffer(v) && v instanceof Uint8Array) row[k] = Buffer.from(v);
+    }
+  }
+  return row;
+}
+
+/**
+ * @primitive b.frameworkSchema.coerceRows
+ * @signature b.frameworkSchema.coerceRows(rows)
+ * @since     0.14.29
+ * @status    stable
+ * @related   b.frameworkSchema.coerceRow
+ *
+ * Apply `coerceRow` to every row in an array (in place); returns the
+ * array. A non-array argument is returned unchanged.
+ *
+ * @example
+ *   var rows = frameworkSchema.coerceRows(await queryAll(sql));
+ */
+function coerceRows(rows) {
+  if (Array.isArray(rows)) {
+    for (var i = 0; i < rows.length; i++) coerceRow(rows[i]);
+  }
+  return rows;
 }
 
 // ---- ensureSchema ----
@@ -702,11 +975,12 @@ function _breakGlassGrantsDDL(dialect) {
  * Throws `FrameworkSchemaError("framework-schema/invalid-config")`
  * when `externalDbBackend` is missing and
  * `FrameworkSchemaError("framework-schema/unsupported-dialect")`
- * when `dialect` is anything other than `postgres` or `sqlite`.
+ * when `dialect` is anything other than `postgres`, `mysql`, or
+ * `sqlite`.
  *
  * @opts
  *   externalDbBackend: string,     // backend name registered with b.externalDb (required)
- *   dialect:           "postgres"|"sqlite",  // default: "postgres"
+ *   dialect:           "postgres"|"mysql"|"sqlite",  // default: "postgres"
  *
  * @example
  *   try {
@@ -727,41 +1001,35 @@ async function ensureSchema(opts) {
     );
   }
   var dialect = (opts.dialect || "postgres").toLowerCase();
-  if (dialect !== "postgres" && dialect !== "sqlite") {
+  if (dialect !== "postgres" && dialect !== "sqlite" && dialect !== "mysql") {
     throw new FrameworkSchemaError(
-      "unsupported dialect '" + dialect + "' (postgres or sqlite)",
+      "unsupported dialect '" + dialect + "' (postgres, sqlite, or mysql)",
       "framework-schema/unsupported-dialect"
     );
   }
 
-  var ddls = [
-    _auditLogDDL(dialect),
-    _consentLogDDL(dialect),
-    _auditCheckpointsDDL(dialect),
-    _auditTipDDL(dialect),
-    _consentTipDDL(dialect),
-    _auditPurgeAnchorDDL(dialect),
-    _schedulerTicksDDL(dialect),
-    _rateLimitCountersDDL(dialect),
-    _pubsubMessagesDDL(dialect),
-    _apiEncryptNoncesDDL(dialect),
-    _apiKeysDDL(dialect),
-    _sessionsDDL(dialect),
-    _jobsDDL(dialect),
-    _cacheDDL(dialect),
-    _cacheTagsDDL(dialect),
-    _seedersDDL(dialect),
-    _seedersLockDDL(dialect),
-    _breakGlassPoliciesDDL(dialect),
-    _breakGlassGrantsDDL(dialect),
-  ];
+  var ddls = _allDDLs(dialect);
 
   var created = [];
   for (var i = 0; i < ddls.length; i++) {
     var d = ddls[i];
     await externalDb.query(d.create, [], { backend: opts.externalDbBackend });
     for (var j = 0; j < d.indexes.length; j++) {
-      await externalDb.query(d.indexes[j], [], { backend: opts.externalDbBackend });
+      // MySQL has no CREATE INDEX IF NOT EXISTS, so a second ensureSchema
+      // pass re-issues a plain CREATE INDEX and the engine rejects the
+      // duplicate index name (error 1061 "Duplicate key name"). That is the
+      // intended idempotent end state — the index already exists — so the
+      // duplicate error is swallowed on MySQL only; every other dialect uses
+      // the native IF NOT EXISTS and never reaches here.
+      if (dialect === "mysql") {
+        try {
+          await externalDb.query(d.indexes[j], [], { backend: opts.externalDbBackend });
+        } catch (e) {
+          if (!/duplicate|exist|1061/i.test((e && e.message) || "")) throw e;
+        }
+      } else {
+        await externalDb.query(d.indexes[j], [], { backend: opts.externalDbBackend });
+      }
     }
     created.push(d.create.match(/CREATE TABLE IF NOT EXISTS\s+(\S+)/)[1]);
   }
@@ -784,9 +1052,9 @@ async function ensureSchema(opts) {
 // at the next ensureSchema pass.
 async function _installWormTriggers(backend, dialect) {
   var wormTables = [
-    LOCAL_TO_EXTERNAL.audit_log,
-    LOCAL_TO_EXTERNAL.consent_log,
-    LOCAL_TO_EXTERNAL.audit_checkpoints,
+    tableName("audit_log"),
+    tableName("consent_log"),
+    tableName("audit_checkpoints"),
   ];
   for (var i = 0; i < wormTables.length; i++) {
     var t = wormTables[i];
@@ -818,6 +1086,32 @@ async function _installWormTriggers(backend, dialect) {
         " FOR EACH ROW EXECUTE FUNCTION " + fnName + "()",
         [], { backend: backend }
       );
+    } else if (dialect === "mysql") {
+      // MySQL has no CREATE TRIGGER IF NOT EXISTS, so DROP-then-CREATE
+      // is the idempotent shape (matches the Postgres path). The body
+      // SIGNALs SQLSTATE '45000' (unhandled user-defined exception) with
+      // an append-only MESSAGE_TEXT — MySQL aborts the DELETE/UPDATE and
+      // the driver surfaces it as a query-failure audit row, exactly like
+      // the Postgres RAISE EXCEPTION and the SQLite RAISE(ABORT).
+      var qt = "`" + t + "`";
+      await externalDb.query(
+        "DROP TRIGGER IF EXISTS no_delete_" + t, [], { backend: backend }
+      );
+      await externalDb.query(
+        "CREATE TRIGGER no_delete_" + t + " BEFORE DELETE ON " + qt +
+        " FOR EACH ROW SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '" +
+        t + " is append-only — DELETE prohibited'",
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        "DROP TRIGGER IF EXISTS no_update_" + t, [], { backend: backend }
+      );
+      await externalDb.query(
+        "CREATE TRIGGER no_update_" + t + " BEFORE UPDATE ON " + qt +
+        " FOR EACH ROW SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '" +
+        t + " is append-only — UPDATE prohibited'",
+        [], { backend: backend }
+      );
     } else {
       // SQLite cluster path. CREATE TRIGGER IF NOT EXISTS matches the
       // local-SQLite shape installed by lib/db.js.
@@ -840,6 +1134,13 @@ async function _installWormTriggers(backend, dialect) {
 module.exports = {
   ensureSchema:           ensureSchema,
   tableName:              tableName,
+  setTablePrefix:         setTablePrefix,
+  getTablePrefix:         getTablePrefix,
+  DEFAULT_TABLE_PREFIX:   DEFAULT_TABLE_PREFIX,
   LOCAL_TO_EXTERNAL:      LOCAL_TO_EXTERNAL,
+  CANONICAL_COLUMNS:      CANONICAL_COLUMNS,
+  COLUMN_TYPES:           COLUMN_TYPES,
+  coerceRow:              coerceRow,
+  coerceRows:             coerceRows,
   FrameworkSchemaError:   FrameworkSchemaError,
 };