@blamejs/core 0.7.1 → 0.7.18

package/lib/framework-schema.js

@@ -1,717 +1,717 @@
-"use strict";
-/**
- * Framework state schema for cluster-mode external storage.
- *
- * When cluster mode is active, the framework's audit chain + consent
- * log + audit checkpoints + audit tip live in the operator's external-db
- * (configured via b.externalDb.init). This module owns the DDL for
- * those tables and exposes a single idempotent ensureSchema() entry
- * point that operators (or the framework's leader-acquire hook in a
- * later release) call to create them.
- *
- * In external-db the framework tables are prefixed with `_blamejs_`
- * to avoid collision with the operator's app data:
- *
- *   audit_log          local-SQLite name
- *   _blamejs_audit_log external-db name
- *
- * The mapping is exposed via tableName(local) so write-dispatch code
- * (cluster-storage.js) uses a single name reference and the
- * dialect-aware ensureSchema fans out the DDL to either the local-
- * SQLite (db.js's FRAMEWORK_SCHEMA) or the external-db backend.
- *
- * Dialects: Postgres + SQLite. Both support CREATE TABLE IF NOT EXISTS,
- * CREATE INDEX IF NOT EXISTS, and the same column types modulo
- * INTEGER/BIGINT and BLOB/BYTEA differences. MySQL is not currently
- * supported — operators on MySQL must use one of the supported
- * dialects until a MySQL adapter ships.
- *
- * What ensureSchema does NOT do:
- *   - Migrate existing audit_log rows from local SQLite into external-db.
- *     That migration belongs to a separate operator-driven tool.
- *   - Verify chain integrity in external-db. That happens at boot via
- *     the audit module's regular verify() path on every read.
- *   - Install append-only triggers. The framework's tamper-evidence
- *     model is the audit chain's hash linkage + SLH-DSA-signed
- *     checkpoints — triggers would add a defense-in-depth layer
- *     but they're not load-bearing for the threat model. Operators
- *     who want triggers add them per their dialect's syntax.
- *
- * Public API:
- *   await frameworkSchema.ensureSchema({ externalDbBackend, dialect })
- *   frameworkSchema.tableName(localName)   external table name lookup
- *   frameworkSchema.LOCAL_TO_EXTERNAL      mapping (read-only)
- *   frameworkSchema.FrameworkSchemaError   error class
- */
-
-var externalDb = require("./external-db");
-var { FrameworkError } = require("./framework-error");
-
-class FrameworkSchemaError extends FrameworkError {
-  constructor(message, code) {
-    super(message);
-    this.name = "FrameworkSchemaError";
-    this.code = code || "framework-schema/invalid";
-    this.isFrameworkSchemaError = true;
-  }
-}
-
-// Local-SQLite name → external-db name. The prefix protects against
-// operator-app-table collision when the framework writes alongside
-// app tables in the same database.
-var LOCAL_TO_EXTERNAL = Object.freeze({
-  audit_log:          "_blamejs_audit_log",
-  consent_log:        "_blamejs_consent_log",
-  audit_checkpoints:  "_blamejs_audit_checkpoints",
-  // No local equivalent — only exists in external-db. Coordinates with
-  // the cluster module's lease + fencing-token guard.
-  _blamejs_audit_tip:   "_blamejs_audit_tip",
-  // Same shape and purpose as _blamejs_audit_tip but for consent_log.
-  // Single-row coordination state recording the tip of the consent
-  // chain so a new leader (or any boot) can detect external-db
-  // rollback against the consent chain too.
-  _blamejs_consent_tip: "_blamejs_consent_tip",
-  // Single-row anchor recording the boundary of the most recent
-  // audit-tools.purge(). After a purge, audit-chain.verifyChain reads
-  // this row to set its starting prevHash to lastPurgedRowHash and skip
-  // rows whose monotonicCounter ≤ lastPurgedCounter — without it the
-  // chain math breaks the moment the row referenced by survivors'
-  // prevHash is gone.
-  _blamejs_audit_purge_anchor: "_blamejs_audit_purge_anchor",
-  // Scheduler tick-claim table: closes the once-globally gap during
-  // cluster leader hand-offs (where two leaders briefly coexist) by
-  // making each fire claim a row before dispatching. UNIQUE on the
-  // composite tickKey (name + ":" + scheduledAtUnix) — loser of the
-  // INSERT race skips the tick.
-  _blamejs_scheduler_ticks:    "_blamejs_scheduler_ticks",
-  // Rate-limit cluster-shared backend storage — fixed-window counter
-  // per key. The middleware atomically INSERT...ON CONFLICT increments
-  // count within the current window and rolls over when the window
-  // advances. Created in cluster mode by ensureSchema; mirrored in
-  // single-node SQLite by db.js's FRAMEWORK_SCHEMA so the same SQL
-  // works on either side of cluster-storage's dispatch.
-  _blamejs_rate_limit_counters: "_blamejs_rate_limit_counters",
-  // WebSocket channel-hub cluster fan-out — publish() writes a row,
-  // other nodes poll for new ids and dispatch to their local
-  // subscribers. Same dual-storage shape as sessions / jobs / etc.
-  _blamejs_pubsub_messages:        "_blamejs_pubsub_messages",
-  _blamejs_api_encrypt_nonces: "_blamejs_api_encrypt_nonces",
-  // _blamejs_api_keys — operator-facing API-key registry table for the
-  // b.apiKey primitive. PRIMARY KEY is namespace-scoped id (so multiple
-  // namespaces can coexist in one table). Sealed columns: ownerId,
-  // scopes (JSON array), metadata (JSON object). Indexed lookup by
-  // ownerIdHash. The secret itself never lands here — only its
-  // SHA3-512 hash, constant-time-compared on verify.
-  _blamejs_api_keys: "_blamejs_api_keys",
-  // _blamejs_sessions exists in both local SQLite (single-node mode,
-  // created by db.js's FRAMEWORK_SCHEMA at boot) and external-db
-  // (cluster mode, created by ensureSchema below). Same name in both
-  // places — cluster-storage.execute routes the SQL to the right DB
-  // based on cluster.isClusterMode().
-  _blamejs_sessions:  "_blamejs_sessions",
-  // _blamejs_jobs — same dual-storage pattern as sessions. The local-
-  // protocol queue (lib/queue-local.js) routes through cluster-storage
-  // so writes/reads land in the leader's external-db when cluster
-  // mode is active and any node can observe the queue state.
-  _blamejs_jobs:      "_blamejs_jobs",
-  // _blamejs_cache — operator-facing cache primitive's cluster backend.
-  // Single shared table across all CacheInstance instances; the
-  // namespace prefix in cacheKey isolates instances. JSON-serialized
-  // values, BIGINT expiresAt for ttl. Indexed on expiresAt for the
-  // periodic prune query.
-  _blamejs_cache:     "_blamejs_cache",
-  // _blamejs_cache_tags — junction table for tag-based cache
-  // invalidation on the cluster backend. Composite PK
-  // (cacheKey, tag) lets a single cacheKey carry many tags;
-  // index on tag makes invalidateTag(t) a single indexed scan.
-  _blamejs_cache_tags: "_blamejs_cache_tags",
-  // _blamejs_seeders — registry of applied seed files for b.seeders
-  // (lib/seeders.js). Composite PK (env, name) lets the same filename
-  // apply per env. Mirrors the local-SQLite shape in db.js
-  // FRAMEWORK_SCHEMA so cluster-storage.execute routes to either side.
-  _blamejs_seeders:        "_blamejs_seeders",
-  _blamejs_seeders_lock:   "_blamejs_seeders_lock",
-  // Break-glass policy + grant tables. Cluster-shared so a grant
-  // issued on node A is honored on node B; policies updated on the
-  // leader propagate to all followers via the shared table.
-  _blamejs_break_glass_policies: "_blamejs_break_glass_policies",
-  _blamejs_break_glass_grants:   "_blamejs_break_glass_grants",
-});
-
-function tableName(localName) {
-  if (Object.prototype.hasOwnProperty.call(LOCAL_TO_EXTERNAL, localName)) {
-    return LOCAL_TO_EXTERNAL[localName];
-  }
-  // For framework-internal tables that are already prefixed locally
-  // (any name starting with _blamejs_), keep the same name.
-  return localName;
-}
-
-// ---- Dialect-specific column types ----
-// TEXT and BOOLEAN are identical across both. INTEGER and BLOB diverge.
-
-function _types(dialect) {
-  if (dialect === "postgres") {
-    return { INT: "BIGINT", BLOB: "BYTEA" };
-  }
-  if (dialect === "sqlite") {
-    return { INT: "INTEGER", BLOB: "BLOB" };
-  }
-  throw new FrameworkSchemaError(
-    "unsupported dialect '" + dialect + "' (postgres or sqlite)",
-    "framework-schema/unsupported-dialect"
-  );
-}
-
-// ---- Table DDL builders ----
-//
-// Each builder returns { create: <CREATE TABLE SQL>, indexes: [<CREATE INDEX SQL>, ...] }.
-// 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;
-  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)",
-    ],
-  };
-}
-
-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)",
-    ],
-  };
-}
-
-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)",
-    ],
-  };
-}
-
-// audit_tip is single-row coordination state for cluster-mode rollback
-// detection. The CHECK constraint on fencingToken is the canonical
-// fencing-token guard from the cluster spec — enforced at the DB
-// level so a partitioned old leader can't insert rows behind a new
-// leader's back regardless of application-layer state.
-//
-// Postgres and SQLite both honour CHECK constraints. The single-row
-// invariant is enforced via PRIMARY KEY on the constant-valued
-// `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: [],
-  };
-}
-
-// Same shape + invariants as audit_tip but for the consent chain.
-// Updated on every consent.grant / consent.withdraw write so the boot-
-// time rollback check can detect external-db rollback against the
-// 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: [],
-  };
-}
-
-// _blamejs_audit_purge_anchor — single-row chain-origin anchor written
-// by audit-tools.purge(). Holds the lastRowHash of the most recently
-// purged range so verifyChain can ground its walk at the new origin.
-// Single-row invariant via PRIMARY KEY on the constant-valued `scope`
-// 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: [],
-  };
-}
-
-// _blamejs_scheduler_ticks — exactly-once tick-claim table. PRIMARY KEY
-// on composite tickKey makes concurrent INSERTs race; the loser skips
-// 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)",
-    ],
-  };
-}
-
-// _blamejs_rate_limit_counters — fixed-window counter table for the
-// cluster-shared rate-limit backend. PRIMARY KEY on the rate-limit
-// key lets INSERT...ON CONFLICT atomically increment within a window
-// and roll over on window advance. The windowStart index supports
-// 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)",
-    ],
-  };
-}
-
-// _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).
-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)",
-    ],
-  };
-}
-
-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)",
-    ],
-  };
-}
-
-// _blamejs_api_keys — operator-facing API-key registry. PRIMARY KEY is
-// the namespace-scoped id ("<namespace>:<idHex>"); ownerId/scopes/metadata
-// are sealed by cryptoField. ownerIdHash supports indexed listForOwner
-// 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)",
-    ],
-  };
-}
-
-// _blamejs_sessions — DB-backed session store. Mirrors the local-SQLite
-// schema in db.js's FRAMEWORK_SCHEMA so single-node and cluster-mode
-// behavior is identical at the column level. Sealed columns (userId,
-// data) are stored vault-sealed; sidHash is the PRIMARY KEY (the raw
-// 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)",
-    ],
-  };
-}
-
-// _blamejs_jobs — local-protocol queue jobs. Mirrors db.js's
-// FRAMEWORK_SCHEMA for the same table; sealed columns (payload,
-// lastError) are stored vault-sealed. Indexes target the lease
-// hot-path (queueName + status + availableAt) and lease-expiry
-// 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)",
-    ],
-  };
-}
-
-// _blamejs_seeders — registry of applied seed files for the b.seeders
-// primitive (lib/seeders.js). Composite PK (env, name) so the same
-// filename can apply per env without collision. rerunnable=1 entries
-// have their appliedAt updated in place on each run; non-rerunnable
-// 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: [],
-  };
-}
-
-// _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: [],
-  };
-}
-
-// _blamejs_cache — operator-facing cache primitive's cluster backend
-// (lib/cache.js). PRIMARY KEY is the composite "<namespace>:<key>" so a
-// single shared table serves every CacheInstance regardless of namespace
-// without per-namespace table proliferation. valueJson is the
-// JSON-serialized stored value; expiresAt is the unix-ms TTL boundary
-// (Number.MAX_SAFE_INTEGER for never-expiring entries). Indexed on
-// 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)",
-    ],
-  };
-}
-
-// _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)",
-    ],
-  };
-}
-
-// _blamejs_break_glass_policies — column-level break-glass policy
-// registry. One row per (table) declares which columns are
-// glass-locked + the operator's grant rules. Sealed columns hide
-// 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: [],
-  };
-}
-
-// _blamejs_break_glass_grants — issued grants. One row per successful
-// step-up. Default maxRowsPerGrant=1 enforces row-by-row auth per the
-// operator-confirmed shape ("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)",
-    ],
-  };
-}
-
-// ---- ensureSchema ----
-
-async function ensureSchema(opts) {
-  if (!opts || !opts.externalDbBackend) {
-    throw new FrameworkSchemaError(
-      "ensureSchema requires { externalDbBackend: <name> }",
-      "framework-schema/invalid-config"
-    );
-  }
-  var dialect = (opts.dialect || "postgres").toLowerCase();
-  if (dialect !== "postgres" && dialect !== "sqlite") {
-    throw new FrameworkSchemaError(
-      "unsupported dialect '" + dialect + "' (postgres or sqlite)",
-      "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 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 });
-    }
-    created.push(d.create.match(/CREATE TABLE IF NOT EXISTS\s+(\S+)/)[1]);
-  }
-  return { tables: created };
-}
-
-module.exports = {
-  ensureSchema:           ensureSchema,
-  tableName:              tableName,
-  LOCAL_TO_EXTERNAL:      LOCAL_TO_EXTERNAL,
-  FrameworkSchemaError:   FrameworkSchemaError,
-};
+"use strict";
+/**
+ * Framework state schema for cluster-mode external storage.
+ *
+ * When cluster mode is active, the framework's audit chain + consent
+ * log + audit checkpoints + audit tip live in the operator's external-db
+ * (configured via b.externalDb.init). This module owns the DDL for
+ * those tables and exposes a single idempotent ensureSchema() entry
+ * point that operators (or the framework's leader-acquire hook in a
+ * later release) call to create them.
+ *
+ * In external-db the framework tables are prefixed with `_blamejs_`
+ * to avoid collision with the operator's app data:
+ *
+ *   audit_log          local-SQLite name
+ *   _blamejs_audit_log external-db name
+ *
+ * The mapping is exposed via tableName(local) so write-dispatch code
+ * (cluster-storage.js) uses a single name reference and the
+ * dialect-aware ensureSchema fans out the DDL to either the local-
+ * SQLite (db.js's FRAMEWORK_SCHEMA) or the external-db backend.
+ *
+ * Dialects: Postgres + SQLite. Both support CREATE TABLE IF NOT EXISTS,
+ * CREATE INDEX IF NOT EXISTS, and the same column types modulo
+ * INTEGER/BIGINT and BLOB/BYTEA differences. MySQL is not currently
+ * supported — operators on MySQL must use one of the supported
+ * dialects until a MySQL adapter ships.
+ *
+ * What ensureSchema does NOT do:
+ *   - Migrate existing audit_log rows from local SQLite into external-db.
+ *     That migration belongs to a separate operator-driven tool.
+ *   - Verify chain integrity in external-db. That happens at boot via
+ *     the audit module's regular verify() path on every read.
+ *   - Install append-only triggers. The framework's tamper-evidence
+ *     model is the audit chain's hash linkage + SLH-DSA-signed
+ *     checkpoints — triggers would add a defense-in-depth layer
+ *     but they're not load-bearing for the threat model. Operators
+ *     who want triggers add them per their dialect's syntax.
+ *
+ * Public API:
+ *   await frameworkSchema.ensureSchema({ externalDbBackend, dialect })
+ *   frameworkSchema.tableName(localName)   external table name lookup
+ *   frameworkSchema.LOCAL_TO_EXTERNAL      mapping (read-only)
+ *   frameworkSchema.FrameworkSchemaError   error class
+ */
+
+var externalDb = require("./external-db");
+var { FrameworkError } = require("./framework-error");
+
+class FrameworkSchemaError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "FrameworkSchemaError";
+    this.code = code || "framework-schema/invalid";
+    this.isFrameworkSchemaError = true;
+  }
+}
+
+// Local-SQLite name → external-db name. The prefix protects against
+// operator-app-table collision when the framework writes alongside
+// app tables in the same database.
+var LOCAL_TO_EXTERNAL = Object.freeze({
+  audit_log:          "_blamejs_audit_log",
+  consent_log:        "_blamejs_consent_log",
+  audit_checkpoints:  "_blamejs_audit_checkpoints",
+  // No local equivalent — only exists in external-db. Coordinates with
+  // the cluster module's lease + fencing-token guard.
+  _blamejs_audit_tip:   "_blamejs_audit_tip",
+  // Same shape and purpose as _blamejs_audit_tip but for consent_log.
+  // Single-row coordination state recording the tip of the consent
+  // chain so a new leader (or any boot) can detect external-db
+  // rollback against the consent chain too.
+  _blamejs_consent_tip: "_blamejs_consent_tip",
+  // Single-row anchor recording the boundary of the most recent
+  // audit-tools.purge(). After a purge, audit-chain.verifyChain reads
+  // this row to set its starting prevHash to lastPurgedRowHash and skip
+  // rows whose monotonicCounter ≤ lastPurgedCounter — without it the
+  // chain math breaks the moment the row referenced by survivors'
+  // prevHash is gone.
+  _blamejs_audit_purge_anchor: "_blamejs_audit_purge_anchor",
+  // Scheduler tick-claim table: closes the once-globally gap during
+  // cluster leader hand-offs (where two leaders briefly coexist) by
+  // making each fire claim a row before dispatching. UNIQUE on the
+  // composite tickKey (name + ":" + scheduledAtUnix) — loser of the
+  // INSERT race skips the tick.
+  _blamejs_scheduler_ticks:    "_blamejs_scheduler_ticks",
+  // Rate-limit cluster-shared backend storage — fixed-window counter
+  // per key. The middleware atomically INSERT...ON CONFLICT increments
+  // count within the current window and rolls over when the window
+  // advances. Created in cluster mode by ensureSchema; mirrored in
+  // single-node SQLite by db.js's FRAMEWORK_SCHEMA so the same SQL
+  // works on either side of cluster-storage's dispatch.
+  _blamejs_rate_limit_counters: "_blamejs_rate_limit_counters",
+  // WebSocket channel-hub cluster fan-out — publish() writes a row,
+  // other nodes poll for new ids and dispatch to their local
+  // subscribers. Same dual-storage shape as sessions / jobs / etc.
+  _blamejs_pubsub_messages:        "_blamejs_pubsub_messages",
+  _blamejs_api_encrypt_nonces: "_blamejs_api_encrypt_nonces",
+  // _blamejs_api_keys — operator-facing API-key registry table for the
+  // b.apiKey primitive. PRIMARY KEY is namespace-scoped id (so multiple
+  // namespaces can coexist in one table). Sealed columns: ownerId,
+  // scopes (JSON array), metadata (JSON object). Indexed lookup by
+  // ownerIdHash. The secret itself never lands here — only its
+  // SHA3-512 hash, constant-time-compared on verify.
+  _blamejs_api_keys: "_blamejs_api_keys",
+  // _blamejs_sessions exists in both local SQLite (single-node mode,
+  // created by db.js's FRAMEWORK_SCHEMA at boot) and external-db
+  // (cluster mode, created by ensureSchema below). Same name in both
+  // places — cluster-storage.execute routes the SQL to the right DB
+  // based on cluster.isClusterMode().
+  _blamejs_sessions:  "_blamejs_sessions",
+  // _blamejs_jobs — same dual-storage pattern as sessions. The local-
+  // protocol queue (lib/queue-local.js) routes through cluster-storage
+  // so writes/reads land in the leader's external-db when cluster
+  // mode is active and any node can observe the queue state.
+  _blamejs_jobs:      "_blamejs_jobs",
+  // _blamejs_cache — operator-facing cache primitive's cluster backend.
+  // Single shared table across all CacheInstance instances; the
+  // namespace prefix in cacheKey isolates instances. JSON-serialized
+  // values, BIGINT expiresAt for ttl. Indexed on expiresAt for the
+  // periodic prune query.
+  _blamejs_cache:     "_blamejs_cache",
+  // _blamejs_cache_tags — junction table for tag-based cache
+  // invalidation on the cluster backend. Composite PK
+  // (cacheKey, tag) lets a single cacheKey carry many tags;
+  // index on tag makes invalidateTag(t) a single indexed scan.
+  _blamejs_cache_tags: "_blamejs_cache_tags",
+  // _blamejs_seeders — registry of applied seed files for b.seeders
+  // (lib/seeders.js). Composite PK (env, name) lets the same filename
+  // apply per env. Mirrors the local-SQLite shape in db.js
+  // FRAMEWORK_SCHEMA so cluster-storage.execute routes to either side.
+  _blamejs_seeders:        "_blamejs_seeders",
+  _blamejs_seeders_lock:   "_blamejs_seeders_lock",
+  // Break-glass policy + grant tables. Cluster-shared so a grant
+  // issued on node A is honored on node B; policies updated on the
+  // leader propagate to all followers via the shared table.
+  _blamejs_break_glass_policies: "_blamejs_break_glass_policies",
+  _blamejs_break_glass_grants:   "_blamejs_break_glass_grants",
+});
+
+function tableName(localName) {
+  if (Object.prototype.hasOwnProperty.call(LOCAL_TO_EXTERNAL, localName)) {
+    return LOCAL_TO_EXTERNAL[localName];
+  }
+  // For framework-internal tables that are already prefixed locally
+  // (any name starting with _blamejs_), keep the same name.
+  return localName;
+}
+
+// ---- Dialect-specific column types ----
+// TEXT and BOOLEAN are identical across both. INTEGER and BLOB diverge.
+
+function _types(dialect) {
+  if (dialect === "postgres") {
+    return { INT: "BIGINT", BLOB: "BYTEA" };
+  }
+  if (dialect === "sqlite") {
+    return { INT: "INTEGER", BLOB: "BLOB" };
+  }
+  throw new FrameworkSchemaError(
+    "unsupported dialect '" + dialect + "' (postgres or sqlite)",
+    "framework-schema/unsupported-dialect"
+  );
+}
+
+// ---- Table DDL builders ----
+//
+// Each builder returns { create: <CREATE TABLE SQL>, indexes: [<CREATE INDEX SQL>, ...] }.
+// 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;
+  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)",
+    ],
+  };
+}
+
+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)",
+    ],
+  };
+}
+
+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)",
+    ],
+  };
+}
+
+// audit_tip is single-row coordination state for cluster-mode rollback
+// detection. The CHECK constraint on fencingToken is the canonical
+// fencing-token guard from the cluster spec — enforced at the DB
+// level so a partitioned old leader can't insert rows behind a new
+// leader's back regardless of application-layer state.
+//
+// Postgres and SQLite both honour CHECK constraints. The single-row
+// invariant is enforced via PRIMARY KEY on the constant-valued
+// `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: [],
+  };
+}
+
+// Same shape + invariants as audit_tip but for the consent chain.
+// Updated on every consent.grant / consent.withdraw write so the boot-
+// time rollback check can detect external-db rollback against the
+// 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: [],
+  };
+}
+
+// _blamejs_audit_purge_anchor — single-row chain-origin anchor written
+// by audit-tools.purge(). Holds the lastRowHash of the most recently
+// purged range so verifyChain can ground its walk at the new origin.
+// Single-row invariant via PRIMARY KEY on the constant-valued `scope`
+// 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: [],
+  };
+}
+
+// _blamejs_scheduler_ticks — exactly-once tick-claim table. PRIMARY KEY
+// on composite tickKey makes concurrent INSERTs race; the loser skips
+// 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)",
+    ],
+  };
+}
+
+// _blamejs_rate_limit_counters — fixed-window counter table for the
+// cluster-shared rate-limit backend. PRIMARY KEY on the rate-limit
+// key lets INSERT...ON CONFLICT atomically increment within a window
+// and roll over on window advance. The windowStart index supports
+// 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)",
+    ],
+  };
+}
+
+// _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).
+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)",
+    ],
+  };
+}
+
+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)",
+    ],
+  };
+}
+
+// _blamejs_api_keys — operator-facing API-key registry. PRIMARY KEY is
+// the namespace-scoped id ("<namespace>:<idHex>"); ownerId/scopes/metadata
+// are sealed by cryptoField. ownerIdHash supports indexed listForOwner
+// 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)",
+    ],
+  };
+}
+
+// _blamejs_sessions — DB-backed session store. Mirrors the local-SQLite
+// schema in db.js's FRAMEWORK_SCHEMA so single-node and cluster-mode
+// behavior is identical at the column level. Sealed columns (userId,
+// data) are stored vault-sealed; sidHash is the PRIMARY KEY (the raw
+// 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)",
+    ],
+  };
+}
+
+// _blamejs_jobs — local-protocol queue jobs. Mirrors db.js's
+// FRAMEWORK_SCHEMA for the same table; sealed columns (payload,
+// lastError) are stored vault-sealed. Indexes target the lease
+// hot-path (queueName + status + availableAt) and lease-expiry
+// 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)",
+    ],
+  };
+}
+
+// _blamejs_seeders — registry of applied seed files for the b.seeders
+// primitive (lib/seeders.js). Composite PK (env, name) so the same
+// filename can apply per env without collision. rerunnable=1 entries
+// have their appliedAt updated in place on each run; non-rerunnable
+// 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: [],
+  };
+}
+
+// _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: [],
+  };
+}
+
+// _blamejs_cache — operator-facing cache primitive's cluster backend
+// (lib/cache.js). PRIMARY KEY is the composite "<namespace>:<key>" so a
+// single shared table serves every CacheInstance regardless of namespace
+// without per-namespace table proliferation. valueJson is the
+// JSON-serialized stored value; expiresAt is the unix-ms TTL boundary
+// (Number.MAX_SAFE_INTEGER for never-expiring entries). Indexed on
+// 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)",
+    ],
+  };
+}
+
+// _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)",
+    ],
+  };
+}
+
+// _blamejs_break_glass_policies — column-level break-glass policy
+// registry. One row per (table) declares which columns are
+// glass-locked + the operator's grant rules. Sealed columns hide
+// 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: [],
+  };
+}
+
+// _blamejs_break_glass_grants — issued grants. One row per successful
+// step-up. Default maxRowsPerGrant=1 enforces row-by-row auth per the
+// operator-confirmed shape ("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)",
+    ],
+  };
+}
+
+// ---- ensureSchema ----
+
+async function ensureSchema(opts) {
+  if (!opts || !opts.externalDbBackend) {
+    throw new FrameworkSchemaError(
+      "ensureSchema requires { externalDbBackend: <name> }",
+      "framework-schema/invalid-config"
+    );
+  }
+  var dialect = (opts.dialect || "postgres").toLowerCase();
+  if (dialect !== "postgres" && dialect !== "sqlite") {
+    throw new FrameworkSchemaError(
+      "unsupported dialect '" + dialect + "' (postgres or sqlite)",
+      "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 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 });
+    }
+    created.push(d.create.match(/CREATE TABLE IF NOT EXISTS\s+(\S+)/)[1]);
+  }
+  return { tables: created };
+}
+
+module.exports = {
+  ensureSchema:           ensureSchema,
+  tableName:              tableName,
+  LOCAL_TO_EXTERNAL:      LOCAL_TO_EXTERNAL,
+  FrameworkSchemaError:   FrameworkSchemaError,
+};