@blamejs/core 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.4** (2026-05-01) — wiki schema docs realigned with the actual lib API
 - **0.6.3** (2026-05-01) — externalDb pool tuning + role-aware connect + read-replica routing
 - **0.6.2** (2026-05-01) — input validation + identifier-quoting consistency
 - **0.6.1** (2026-05-01) — security tightenings + operator-facing jargon sweep

package/lib/db-declare-view.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * b.db.declareView — declarative view + GRANT migration spec.
+ *
+ * Returns a migration-shape object that b.externalDb.migrate(...) applies
+ * against a Postgres backend. The view exposes a deliberately-narrowed
+ * column projection of the source table — sensitive columns are dropped
+ * (redactColumns), sealed columns are auto-omitted (operator declares
+ * via sealedColumns; a future externalDb sealed-fields registry will
+ * make this automatic), and existing derived hash columns can be
+ * exposed in place of their plaintext source via hashColumns.
+ *
+ * Postgres-only: SQLite has no GRANT semantics; MySQL's CREATE VIEW
+ * grammar differs and isn't covered. Apply throws NOT_SUPPORTED at
+ * migration-apply time when the targeted backend's dialect isn't
+ * "postgres" so operators see the failure cause clearly.
+ *
+ * Public API (b.db.declareView):
+ *
+ *   var mig = b.db.declareView({
+ *     schema:         "analytics",          // target schema
+ *     name:           "sessions",           // view name
+ *     source:         "public.sessions",    // schema.table OR ["public","sessions"]
+ *     redactColumns:  ["ssn", "diagnosis"], // dropped from view
+ *     sealedColumns:  ["secrets_jsonb"],    // operator-declared sealed cols (auto-omit)
+ *     hashColumns:    { emailHash: "email" },// hide source plaintext, keep hash
+ *     whereClause:    "deleted_at IS NULL", // optional filter
+ *     grantTo:        ["analytics_user"],   // roles that get SELECT
+ *     backend:        "main",               // optional — defaults to default backend
+ *   });
+ *
+ *   // mig is a migration-shape object: { description, target, backend, up, down }
+ *   // Place it in a migration file:
+ *   //   module.exports = mig;
+ *   // and run b.externalDb.migrate.create({ dir }).up();
+ *
+ * Validation runs at migration apply (not declare) time so source-column
+ * existence and role existence checks query the live database. Operator
+ * typos surface as clear errors at the migrate command, not as silent
+ * empty views or grant-to-nonexistent-role footguns.
+ *
+ * Tier-A validation at declareView() call time:
+ *   - schema, name, source segments → safeSql.validateIdentifier
+ *   - column names in redactColumns / sealedColumns / hashColumns →
+ *     safeSql.validateIdentifier
+ *   - role names in grantTo → safeSql.validateIdentifier
+ *   - whereClause stays operator-supplied SQL (the framework cannot
+ *     validate arbitrary expressions); it interpolates as-is into the
+ *     migration text. Operators wrap any literal values inside
+ *     whereClause via standard SQL quoting.
+ *
+ * Audit metadata emitted on apply:
+ *   {
+ *     view:                "schema.name",
+ *     source:              "schema.table",
+ *     selectedColumns:     [string],
+ *     redactedColumns:     [string],   // intersection of redactColumns & source
+ *     autoExcludedSealed:  [string],   // sealedColumns members found in source
+ *     hashedColumns:       { aliasOrHashCol: srcCol },
+ *     grantedTo:           [string],
+ *   }
+ */
+var safeSql = require("./safe-sql");
+var { defineClass } = require("./framework-error");
+
+var DeclareViewError = defineClass("DeclareViewError", { alwaysPermanent: true });
+
+var ALLOWED_OPTS = [
+  "schema", "name", "source",
+  "redactColumns", "sealedColumns", "hashColumns",
+  "whereClause", "grantTo", "backend",
+];
+
+function _err(code, message) {
+  return new DeclareViewError(code, message);
+}
+
+function _validateIdent(where, value) {
+  try {
+    safeSql.validateIdentifier(value, { allowReserved: true });
+  } catch (e) {
+    throw _err("declare-view/bad-identifier",
+      where + ": invalid identifier '" + value + "': " + ((e && e.message) || String(e)));
+  }
+}
+
+function _validateStringArray(where, arr, optional) {
+  if (arr === undefined || arr === null) {
+    if (optional) return [];
+    throw _err("declare-view/missing-opt", where + " is required");
+  }
+  if (!Array.isArray(arr)) {
+    throw _err("declare-view/bad-type", where + " must be an array of strings");
+  }
+  for (var i = 0; i < arr.length; i++) {
+    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+      throw _err("declare-view/bad-entry",
+        where + "[" + i + "] must be a non-empty string");
+    }
+  }
+  return arr.slice();
+}
+
+function _parseSource(source) {
+  // Accepts "schema.table" or ["schema", "table"] or "table" (defaults to public).
+  var parts;
+  if (typeof source === "string") {
+    if (source.length === 0) {
+      throw _err("declare-view/bad-source", "source must be a non-empty string or array");
+    }
+    parts = source.split(".");
+  } else if (Array.isArray(source)) {
+    parts = source.slice();
+  } else {
+    throw _err("declare-view/bad-source",
+      "source must be a string ('schema.table') or array (['schema','table']), got " + typeof source);
+  }
+  if (parts.length === 1) parts = ["public", parts[0]];
+  if (parts.length !== 2) {
+    throw _err("declare-view/bad-source",
+      "source must resolve to two segments [schema, table]; got " + parts.length + " segment(s)");
+  }
+  for (var i = 0; i < parts.length; i++) _validateIdent("source[" + i + "]", parts[i]);
+  return { schema: parts[0], name: parts[1] };
+}
+
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("declare-view/bad-opts", "declareView requires an opts object");
+  }
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && ALLOWED_OPTS.indexOf(k) === -1) {
+      throw _err("declare-view/unknown-opt",
+        "unknown opt '" + k + "'. Allowed: " + ALLOWED_OPTS.join(", "));
+    }
+  }
+
+  if (typeof opts.schema !== "string" || opts.schema.length === 0) {
+    throw _err("declare-view/missing-opt", "schema is required");
+  }
+  _validateIdent("schema", opts.schema);
+
+  if (typeof opts.name !== "string" || opts.name.length === 0) {
+    throw _err("declare-view/missing-opt", "name is required");
+  }
+  _validateIdent("name", opts.name);
+
+  if (opts.source === undefined) {
+    throw _err("declare-view/missing-opt", "source is required");
+  }
+  var src = _parseSource(opts.source);
+
+  var redactColumns = _validateStringArray("redactColumns", opts.redactColumns, true);
+  for (var i = 0; i < redactColumns.length; i++) {
+    _validateIdent("redactColumns[" + i + "]", redactColumns[i]);
+  }
+
+  var sealedColumns = _validateStringArray("sealedColumns", opts.sealedColumns, true);
+  for (var j = 0; j < sealedColumns.length; j++) {
+    _validateIdent("sealedColumns[" + j + "]", sealedColumns[j]);
+  }
+
+  var hashColumns = {};
+  if (opts.hashColumns !== undefined && opts.hashColumns !== null) {
+    if (typeof opts.hashColumns !== "object" || Array.isArray(opts.hashColumns)) {
+      throw _err("declare-view/bad-type",
+        "hashColumns must be an object { aliasOrHashCol: srcCol }");
+    }
+    for (var hc in opts.hashColumns) {
+      if (!Object.prototype.hasOwnProperty.call(opts.hashColumns, hc)) continue;
+      _validateIdent("hashColumns key '" + hc + "'", hc);
+      var v = opts.hashColumns[hc];
+      if (typeof v !== "string" || v.length === 0) {
+        throw _err("declare-view/bad-entry",
+          "hashColumns['" + hc + "'] must be a non-empty string (the source plaintext column)");
+      }
+      _validateIdent("hashColumns['" + hc + "']", v);
+      hashColumns[hc] = v;
+    }
+  }
+
+  var whereClause = null;
+  if (opts.whereClause !== undefined && opts.whereClause !== null) {
+    if (typeof opts.whereClause !== "string") {
+      throw _err("declare-view/bad-type", "whereClause must be a string");
+    }
+    if (opts.whereClause.indexOf(";") !== -1) {
+      throw _err("declare-view/bad-where",
+        "whereClause must not contain ';' — use a single boolean expression");
+    }
+    whereClause = opts.whereClause;
+  }
+
+  var grantTo = _validateStringArray("grantTo", opts.grantTo, true);
+  for (var g = 0; g < grantTo.length; g++) {
+    _validateIdent("grantTo[" + g + "]", grantTo[g]);
+  }
+
+  if (opts.backend !== undefined && opts.backend !== null) {
+    if (typeof opts.backend !== "string" || opts.backend.length === 0) {
+      throw _err("declare-view/bad-type", "backend must be a non-empty string");
+    }
+  }
+
+  return {
+    schema:         opts.schema,
+    name:           opts.name,
+    source:         src,
+    redactColumns:  redactColumns,
+    sealedColumns:  sealedColumns,
+    hashColumns:    hashColumns,
+    whereClause:    whereClause,
+    grantTo:        grantTo,
+    backend:        opts.backend || null,
+  };
+}
+
+// ---- Apply-time helpers (run inside up()) ----
+
+async function _fetchSourceColumns(xdb, schema, table) {
+  var res = await xdb.query(
+    "SELECT column_name FROM information_schema.columns " +
+    "WHERE table_schema = $1 AND table_name = $2 " +
+    "ORDER BY ordinal_position ASC",
+    [schema, table]
+  );
+  var rows = (res && res.rows) || [];
+  return rows.map(function (r) { return r.column_name; });
+}
+
+async function _fetchExistingRoles(xdb, names) {
+  if (names.length === 0) return new Set();
+  var placeholders = names.map(function (_, i) { return "$" + (i + 1); }).join(", ");
+  var res = await xdb.query(
+    "SELECT rolname FROM pg_roles WHERE rolname IN (" + placeholders + ")",
+    names
+  );
+  var rows = (res && res.rows) || [];
+  return new Set(rows.map(function (r) { return r.rolname; }));
+}
+
+function _missing(required, available) {
+  var miss = [];
+  for (var i = 0; i < required.length; i++) {
+    if (available.indexOf(required[i]) === -1) miss.push(required[i]);
+  }
+  return miss;
+}
+
+function _buildSelectColumnList(sourceCols, spec) {
+  // Drop set: redactColumns ∩ source, sealedColumns ∩ source, hashColumns.values ∩ source.
+  var dropSet = Object.create(null);
+  for (var i = 0; i < spec.redactColumns.length; i++) dropSet[spec.redactColumns[i]] = true;
+  for (var j = 0; j < spec.sealedColumns.length; j++) dropSet[spec.sealedColumns[j]] = true;
+  for (var hc in spec.hashColumns) dropSet[spec.hashColumns[hc]] = true;
+
+  var kept = [];
+  for (var k = 0; k < sourceCols.length; k++) {
+    if (!dropSet[sourceCols[k]]) kept.push(sourceCols[k]);
+  }
+  return kept;
+}
+
+function _intersectInSource(list, sourceCols) {
+  var srcSet = Object.create(null);
+  for (var i = 0; i < sourceCols.length; i++) srcSet[sourceCols[i]] = true;
+  var out = [];
+  for (var j = 0; j < list.length; j++) {
+    if (srcSet[list[j]]) out.push(list[j]);
+  }
+  return out;
+}
+
+function _ensureBackendIsPostgres(externalDb, backendName) {
+  // externalDb.listBackends() returns { name, dialect, ... } per backend.
+  var list = externalDb.listBackends();
+  var found = null;
+  for (var i = 0; i < list.length; i++) {
+    if (list[i].name === backendName) { found = list[i]; break; }
+  }
+  if (!found) {
+    throw _err("declare-view/unknown-backend",
+      "no externalDb backend named '" + backendName + "' — declared backends: " +
+      list.map(function (b) { return b.name; }).join(", "));
+  }
+  if (found.dialect !== "postgres") {
+    throw _err("declare-view/not-supported",
+      "declareView is Postgres-only; backend '" + backendName + "' has dialect='" +
+      found.dialect + "'. Write the view as a hand-rolled migration for this dialect.");
+  }
+}
+
+// ---- The factory ----
+
+function declareView(opts) {
+  var spec = _validateOpts(opts);
+
+  // The migration shape consumed by b.externalDb.migrate. The runner
+  // resolves the backend at apply time (operator may set spec.backend
+  // explicitly OR rely on the migrate runner's default backend).
+  var description = "declareView " + spec.schema + "." + spec.name;
+  var qView   = safeSql.quoteQualified([spec.schema, spec.name], "postgres");
+  var qSource = safeSql.quoteQualified([spec.source.schema, spec.source.name], "postgres");
+
+  async function up(xdb, ctx) {
+    // Tier-A boundary: confirm we're on Postgres before any DDL leaves the process.
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+
+    // Live validation — source columns + roles must exist.
+    var sourceCols = await _fetchSourceColumns(xdb, spec.source.schema, spec.source.name);
+    if (sourceCols.length === 0) {
+      throw _err("declare-view/source-not-found",
+        "source table '" + spec.source.schema + "." + spec.source.name +
+        "' has no columns visible (does it exist? does the migration role have SELECT on information_schema.columns?)");
+    }
+
+    var missingRedact = _missing(spec.redactColumns, sourceCols);
+    if (missingRedact.length > 0) {
+      throw _err("declare-view/redact-not-in-source",
+        "redactColumns [" + missingRedact.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name + "'");
+    }
+
+    var missingHashKeys = _missing(Object.keys(spec.hashColumns), sourceCols);
+    if (missingHashKeys.length > 0) {
+      throw _err("declare-view/hash-key-not-in-source",
+        "hashColumns keys [" + missingHashKeys.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name +
+        "' — declare them as derivedHashes on the source schema first");
+    }
+
+    var missingHashSrc = _missing(_objValues(spec.hashColumns), sourceCols);
+    if (missingHashSrc.length > 0) {
+      throw _err("declare-view/hash-source-not-in-source",
+        "hashColumns values [" + missingHashSrc.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name + "'");
+    }
+
+    if (spec.grantTo.length > 0) {
+      var existing = await _fetchExistingRoles(xdb, spec.grantTo);
+      var missingRoles = [];
+      for (var i = 0; i < spec.grantTo.length; i++) {
+        if (!existing.has(spec.grantTo[i])) missingRoles.push(spec.grantTo[i]);
+      }
+      if (missingRoles.length > 0) {
+        throw _err("declare-view/role-not-found",
+          "grantTo roles [" + missingRoles.join(", ") +
+          "] not present in pg_roles — CREATE ROLE them in an earlier migration");
+      }
+    }
+
+    var selectedColumns = _buildSelectColumnList(sourceCols, spec);
+    if (selectedColumns.length === 0) {
+      throw _err("declare-view/empty-select",
+        "view '" + spec.schema + "." + spec.name +
+        "' would have zero columns after redact/sealed/hash exclusions — adjust the spec");
+    }
+
+    // Build CREATE VIEW. Each column is independently quoted so a
+    // reserved-word column name (e.g. "user", "order") resolves correctly.
+    var quotedCols = selectedColumns.map(function (c) {
+      return safeSql.quoteIdentifier(c, "postgres");
+    }).join(", ");
+    var createSql = "CREATE VIEW " + qView + " AS SELECT " + quotedCols +
+                    " FROM " + qSource;
+    if (spec.whereClause) createSql += " WHERE " + spec.whereClause;
+
+    await xdb.query(createSql, []);
+
+    // GRANT SELECT — one statement covers all roles.
+    if (spec.grantTo.length > 0) {
+      var quotedRoles = spec.grantTo.map(function (r) {
+        return safeSql.quoteIdentifier(r, "postgres");
+      }).join(", ");
+      await xdb.query(
+        "GRANT SELECT ON " + qView + " TO " + quotedRoles,
+        []
+      );
+    }
+
+    return {
+      view:                spec.schema + "." + spec.name,
+      source:              spec.source.schema + "." + spec.source.name,
+      selectedColumns:     selectedColumns,
+      redactedColumns:     _intersectInSource(spec.redactColumns, sourceCols),
+      autoExcludedSealed:  _intersectInSource(spec.sealedColumns, sourceCols),
+      hashedColumns:       Object.assign({}, spec.hashColumns),
+      grantedTo:           spec.grantTo.slice(),
+    };
+  }
+
+  async function down(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+    await xdb.query("DROP VIEW IF EXISTS " + qView, []);
+  }
+
+  return {
+    description: description,
+    target:      "externalDb",
+    backend:     spec.backend,
+    up:          up,
+    down:        down,
+    // Expose the validated spec for testability — declareView callers
+    // can introspect what the migration will emit without running it.
+    _spec:       spec,
+  };
+}
+
+function _objValues(obj) {
+  var out = [];
+  for (var k in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, k)) out.push(obj[k]);
+  }
+  return out;
+}
+
+module.exports = {
+  declareView:        declareView,
+  DeclareViewError:   DeclareViewError,
+};

package/lib/db.js

@@ -1168,6 +1168,11 @@ module.exports = {
     var m = tableMetadata[name];
     return m ? JSON.parse(JSON.stringify(m)) : null;
   },
+  // declareView — declarative CREATE VIEW + GRANT migration spec for an
+  // externalDb backend. Returns a migration-shape object for use with
+  // b.externalDb.migrate. Postgres-only; fail-fast at apply time on other
+  // dialects. See lib/db-declare-view.js.
+  declareView:         require("./db-declare-view").declareView,
   // Internal accessors used by audit / subject / consent modules.
   // Not part of the public contract — apps should not depend on them.
   _getSubjectTables:   function () { return subjectTables.slice(); },

package/lib/external-db-migrate.js

@@ -0,0 +1,434 @@
+"use strict";
+/**
+ * b.externalDb.migrate — versioned migrations for an externalDb backend.
+ *
+ * Mirrors b.migrations (which targets the framework's local SQLite) but
+ * runs against an externalDb backend. Tracking + lock tables live on
+ * the externalDb side under `_blamejs_externaldb_migrations` and
+ * `_blamejs_externaldb_migrations_lock`. Each migration runs inside
+ * `externalDb.transaction(fn)` so a failing migration rolls back
+ * cleanly and stops the wave.
+ *
+ * Migration file format (filename pattern: NNNN-<slug>.js):
+ *
+ *   module.exports = {
+ *     description: "Create users table",
+ *     up:   async function (xdb, ctx) { await xdb.query("CREATE TABLE ..."); },
+ *     down: async function (xdb, ctx) { await xdb.query("DROP TABLE ..."); },
+ *   };
+ *
+ * `xdb` exposes `.query(sql, params) → { rows, rowCount }`. `ctx` carries
+ * `{ externalDb, backendName }` so migrations that need backend-introspection
+ * (e.g. `b.db.declareView()`-shaped specs) can call back into the framework.
+ *
+ * `up` is required; `down` is optional. Calling `down()` on a migration
+ * that didn't export `down()` surfaces a clear error.
+ *
+ *   var migrate = b.externalDb.migrate.create({
+ *     dir:      "./migrations-pg",
+ *     backend:  "main",         // optional; defaults to default backend
+ *     audit:    b.audit,        // optional
+ *   });
+ *
+ *   await migrate.up();         // → { applied: [name], skipped: [name] }
+ *   await migrate.down({ steps: 1 });
+ *   migrate.status();           // → { applied: [{name, description, appliedAt}], pending: [name], total }
+ *
+ * Concurrent-apply protection: a single-row advisory lock in
+ * `_blamejs_externaldb_migrations_lock` ensures two processes can't apply
+ * the same wave concurrently. The losing process gets a clear "lock held
+ * by other process" error. Stale locks can be force-replaced via
+ * `staleAfterMs`.
+ *
+ * Audit emissions when wired with `audit: b.audit`:
+ *   - externaldb.migrate.up.success      { migration, durationMs }
+ *   - externaldb.migrate.up.failure      { migration, durationMs, reason }
+ *   - externaldb.migrate.down.success    { migration, durationMs }
+ *   - externaldb.migrate.down.failure    { migration, durationMs, reason }
+ *   - externaldb.migrate.lock.acquired   { holder }
+ *   - externaldb.migrate.lock.released   { holder }
+ */
+var path = require("path");
+var atomicFile = require("./atomic-file");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var ExternalDbMigrateError = defineClass("ExternalDbMigrateError", { alwaysPermanent: true });
+
+// Lazy require — external-db imports back into this module via its
+// public `migrate` namespace; load-order would cycle without lazy.
+var externalDbModule = lazyRequire(function () { return require("./external-db"); });
+
+var TRACKING_TABLE = "_blamejs_externaldb_migrations";
+var LOCK_TABLE     = "_blamejs_externaldb_migrations_lock";
+// Identifiers wrapped in `"..."` per project convention so a reserved-word
+// or whitespace-bearing name resolves correctly.
+var Q_TRACKING = '"' + TRACKING_TABLE + '"';
+var Q_LOCK     = '"' + LOCK_TABLE + '"';
+
+// Filename grammar — mirrors lib/migrations.js so operators with a
+// mixed local + externalDb workflow use the same numeric-prefix pattern.
+var FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+
+function _err(code, message) {
+  return new ExternalDbMigrateError(code, message);
+}
+
+function _lockHolderId() {
+  return String(process.pid) + "@" + (require("node:os").hostname() || "unknown");
+}
+
+async function _ensureTrackingTable(xdb) {
+  // Tracking table holds the migration history. ISO-8601 timestamp
+  // strings (TEXT) keep the framework's tracking table portable across
+  // Postgres/SQLite without dialect-specific type juggling — operators
+  // who want strict TIMESTAMPTZ for their own ad-hoc queries against
+  // the table ALTER it post-creation.
+  await xdb.query(
+    "CREATE TABLE IF NOT EXISTS " + Q_TRACKING + " (" +
+    "  name        TEXT PRIMARY KEY," +
+    "  description TEXT," +
+    "  appliedAt   TEXT NOT NULL" +
+    ")",
+    []
+  );
+}
+
+async function _ensureLockTable(xdb) {
+  await xdb.query(
+    "CREATE TABLE IF NOT EXISTS " + Q_LOCK + " (" +
+    "  scope     TEXT PRIMARY KEY," +
+    "  lockedAt  INTEGER NOT NULL," +
+    "  lockedBy  TEXT NOT NULL," +
+    "  CHECK (scope = 'lock')" +
+    ")",
+    []
+  );
+}
+
+// ---- Lock acquire / release ----
+
+async function _acquireLock(xdb, opts) {
+  await _ensureLockTable(xdb);
+  var holder = _lockHolderId();
+  var nowMs = Date.now();
+  var staleAfterMs = (opts && typeof opts.staleAfterMs === "number" && opts.staleAfterMs > 0)
+                       ? opts.staleAfterMs : 0;
+  try {
+    await xdb.query(
+      "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
+      [nowMs, holder]
+    );
+    return holder;
+  } catch (_e) {
+    // PRIMARY KEY conflict → existing lock. Inspect it.
+    var existingRes = await xdb.query(
+      "SELECT lockedAt, lockedBy FROM " + Q_LOCK + " WHERE scope = 'lock'",
+      []
+    );
+    var existing = existingRes && existingRes.rows && existingRes.rows[0];
+    if (!existing) {
+      try {
+        await xdb.query(
+          "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
+          [nowMs, holder]
+        );
+        return holder;
+      } catch (e2) {
+        throw _err("externaldb-migrate/lock-busy",
+          "could not acquire migration lock: " + ((e2 && e2.message) || String(e2)));
+      }
+    }
+    var ageMs = nowMs - Number(existing.lockedat || existing.lockedAt);
+    if (staleAfterMs > 0 && ageMs > staleAfterMs) {
+      // Force-replace the stale lock atomically.
+      await xdb.query(
+        "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedAt = $1",
+        [Number(existing.lockedat || existing.lockedAt)]
+      );
+      await xdb.query(
+        "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
+        [nowMs, holder]
+      );
+      return holder;
+    }
+    throw _err("externaldb-migrate/lock-held",
+      "migration lock is held by " + (existing.lockedby || existing.lockedBy) +
+      " (acquired " + ageMs + "ms ago). Another process is running migrations" +
+      " — wait for it to finish, or pass staleAfterMs to force-replace stale locks.");
+  }
+}
+
+async function _releaseLock(xdb, holder) {
+  try {
+    await xdb.query(
+      "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedBy = $1",
+      [holder]
+    );
+  } catch (_e) {
+    // best-effort release; operator can DELETE manually.
+  }
+}
+
+// ---- File loading ----
+
+function _list(dir) {
+  return atomicFile.listDir(dir, {
+    filter: function (f) { return FILE_RE.test(f); },
+  }).map(function (e) { return e.name; }).sort();
+}
+
+function _loadMigration(file, dir) {
+  var fullPath = path.join(dir, file);
+  // Drop the require cache so a test/dev that edits a file picks up the
+  // new content. Matches lib/migrations.js semantics.
+  try { delete require.cache[require.resolve(fullPath)]; } catch (_e) { /* not yet cached */ }
+  var mod;
+  try { mod = require(fullPath); }
+  catch (e) {
+    throw _err("externaldb-migrate/load-failed",
+      "migration '" + file + "' failed to load: " + ((e && e.message) || String(e)));
+  }
+  if (!mod || typeof mod.up !== "function") {
+    throw _err("externaldb-migrate/missing-up",
+      "migration '" + file + "' must export an `up(xdb, ctx)` function");
+  }
+  return mod;
+}
+
+// ---- Audit emit (drop-silent) ----
+
+function _emit(audit, action, outcome, info, reason) {
+  if (!audit) return;
+  try {
+    audit.safeEmit({
+      action:   action,
+      outcome:  outcome,
+      metadata: info || {},
+      reason:   reason || null,
+    });
+  } catch (_e) { /* Tier B: drop-silent */ }
+}
+
+// ---- Backend resolution ----
+
+function _resolveBackendName(opts) {
+  if (opts && typeof opts.backend === "string" && opts.backend.length > 0) {
+    return opts.backend;
+  }
+  // Default to the externalDb's defaultBackend; throw clear if not initialized.
+  var listed;
+  try { listed = externalDbModule().listBackends(); }
+  catch (_e) {
+    throw _err("externaldb-migrate/not-initialized",
+      "externalDb is not initialized — call b.externalDb.init({ backends }) first");
+  }
+  if (!listed || listed.length === 0) {
+    throw _err("externaldb-migrate/no-backends",
+      "externalDb has no backends configured");
+  }
+  return listed[0].name;
+}
+
+// ---- Public factory ----
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["dir", "backend", "audit", "staleAfterMs"], "b.externalDb.migrate");
+  if (typeof opts.dir !== "string" || opts.dir.length === 0) {
+    throw _err("externaldb-migrate/no-dir",
+      "externalDb.migrate.create requires opts.dir (path to migrations directory)");
+  }
+  if (opts.staleAfterMs !== undefined &&
+      (typeof opts.staleAfterMs !== "number" || !isFinite(opts.staleAfterMs) || opts.staleAfterMs < 0)) {
+    throw _err("externaldb-migrate/bad-stale",
+      "staleAfterMs must be a non-negative finite number");
+  }
+  if (opts.audit !== undefined && opts.audit !== null &&
+      (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function")) {
+    throw _err("externaldb-migrate/bad-audit",
+      "audit must be a b.audit-shaped object (safeEmit fn)");
+  }
+  var dir = opts.dir;
+  var audit = opts.audit || null;
+
+  function _ctx(backendName) {
+    return {
+      externalDb:  externalDbModule(),
+      backendName: backendName,
+    };
+  }
+
+  async function status() {
+    var backendName = _resolveBackendName(opts);
+    return await externalDbModule().transaction(async function (xdb) {
+      await _ensureTrackingTable(xdb);
+      var res = await xdb.query(
+        "SELECT name, description, appliedAt FROM " + Q_TRACKING +
+        " ORDER BY appliedAt ASC, name ASC",
+        []
+      );
+      var applied = (res && res.rows) || [];
+      var appliedNames = new Set(applied.map(function (r) { return r.name; }));
+      var files = _list(dir);
+      var pending = files.filter(function (f) { return !appliedNames.has(f); });
+      return {
+        applied:  applied,
+        pending:  pending,
+        total:    files.length,
+        backend:  backendName,
+      };
+    }, { backend: backendName });
+  }
+
+  async function up() {
+    var backendName = _resolveBackendName(opts);
+    var ctx = _ctx(backendName);
+
+    return await externalDbModule().transaction(async function (xdb) {
+      await _ensureTrackingTable(xdb);
+      await _ensureLockTable(xdb);
+    }, { backend: backendName }).then(async function () {
+      // Acquire the lock OUTSIDE the per-migration transaction so the
+      // lock survives across migration boundaries. We use a separate
+      // pool acquisition for the lock connection — the migrate runner
+      // serializes apply order, so this single-connection lock is
+      // sufficient.
+      var lockHolder = await externalDbModule().transaction(async function (xdb) {
+        return await _acquireLock(xdb, opts);
+      }, { backend: backendName });
+
+      _emit(audit, "externaldb.migrate.lock.acquired", "success",
+            { holder: lockHolder, backend: backendName }, null);
+
+      try {
+        var appliedRes = await externalDbModule().query(
+          "SELECT name FROM " + Q_TRACKING, [], { backend: backendName }
+        );
+        var appliedSet = new Set(((appliedRes && appliedRes.rows) || []).map(function (r) { return r.name; }));
+        var files = _list(dir);
+        var applied = [];
+        var skipped = [];
+
+        for (var i = 0; i < files.length; i++) {
+          var file = files[i];
+          if (appliedSet.has(file)) { skipped.push(file); continue; }
+          var mod = _loadMigration(file, dir);
+          var t0 = Date.now();
+          try {
+            await externalDbModule().transaction(async function (xdb) {
+              await mod.up(xdb, ctx);
+              await xdb.query(
+                "INSERT INTO " + Q_TRACKING +
+                " (name, description, appliedAt) VALUES ($1, $2, $3)",
+                [file, mod.description || "", new Date().toISOString()]
+              );
+            }, { backend: backendName });
+            _emit(audit, "externaldb.migrate.up", "success",
+                  { migration: file, durationMs: Date.now() - t0, backend: backendName }, null);
+            applied.push(file);
+          } catch (e) {
+            _emit(audit, "externaldb.migrate.up", "failure",
+                  { migration: file, durationMs: Date.now() - t0, backend: backendName },
+                  (e && e.message) || String(e));
+            throw _err("externaldb-migrate/up-failed",
+              "migration '" + file + "' failed to apply: " + ((e && e.message) || String(e)));
+          }
+        }
+        return { applied: applied, skipped: skipped, backend: backendName };
+      } finally {
+        try {
+          await externalDbModule().transaction(async function (xdb) {
+            await _releaseLock(xdb, lockHolder);
+          }, { backend: backendName });
+          _emit(audit, "externaldb.migrate.lock.released", "success",
+                { holder: lockHolder, backend: backendName }, null);
+        } catch (_e) { /* best-effort release; emit a failure audit */
+          _emit(audit, "externaldb.migrate.lock.released", "failure",
+                { holder: lockHolder, backend: backendName }, "release failed");
+        }
+      }
+    });
+  }
+
+  async function down(downOpts) {
+    downOpts = downOpts || {};
+    var steps = (typeof downOpts.steps === "number" && downOpts.steps > 0)
+                  ? Math.floor(downOpts.steps) : 1;
+    var backendName = _resolveBackendName(opts);
+    var ctx = _ctx(backendName);
+
+    await externalDbModule().transaction(async function (xdb) {
+      await _ensureTrackingTable(xdb);
+      await _ensureLockTable(xdb);
+    }, { backend: backendName });
+
+    var lockHolder = await externalDbModule().transaction(async function (xdb) {
+      return await _acquireLock(xdb, opts);
+    }, { backend: backendName });
+
+    _emit(audit, "externaldb.migrate.lock.acquired", "success",
+          { holder: lockHolder, backend: backendName }, null);
+
+    try {
+      var appliedRes = await externalDbModule().query(
+        "SELECT name FROM " + Q_TRACKING + " ORDER BY appliedAt DESC, name DESC LIMIT $1",
+        [steps], { backend: backendName }
+      );
+      var rows = (appliedRes && appliedRes.rows) || [];
+      var reverted = [];
+      for (var i = 0; i < rows.length; i++) {
+        var file = rows[i].name;
+        var mod = _loadMigration(file, dir);
+        if (typeof mod.down !== "function") {
+          throw _err("externaldb-migrate/no-down",
+            "migration '" + file + "' has no down() — write one or restore from backup");
+        }
+        var t0 = Date.now();
+        try {
+          await externalDbModule().transaction(async function (xdb) {
+            await mod.down(xdb, ctx);
+            await xdb.query(
+              "DELETE FROM " + Q_TRACKING + " WHERE name = $1",
+              [file]
+            );
+          }, { backend: backendName });
+          _emit(audit, "externaldb.migrate.down", "success",
+                { migration: file, durationMs: Date.now() - t0, backend: backendName }, null);
+          reverted.push(file);
+        } catch (e) {
+          _emit(audit, "externaldb.migrate.down", "failure",
+                { migration: file, durationMs: Date.now() - t0, backend: backendName },
+                (e && e.message) || String(e));
+          throw _err("externaldb-migrate/down-failed",
+            "migration '" + file + "' failed to roll back: " + ((e && e.message) || String(e)));
+        }
+      }
+      return { reverted: reverted, backend: backendName };
+    } finally {
+      try {
+        await externalDbModule().transaction(async function (xdb) {
+          await _releaseLock(xdb, lockHolder);
+        }, { backend: backendName });
+        _emit(audit, "externaldb.migrate.lock.released", "success",
+              { holder: lockHolder, backend: backendName }, null);
+      } catch (_e) {
+        _emit(audit, "externaldb.migrate.lock.released", "failure",
+              { holder: lockHolder, backend: backendName }, "release failed");
+      }
+    }
+  }
+
+  return {
+    up:       up,
+    down:     down,
+    status:   status,
+  };
+}
+
+module.exports = {
+  create:                  create,
+  ExternalDbMigrateError:  ExternalDbMigrateError,
+  TRACKING_TABLE:          TRACKING_TABLE,
+};

package/lib/external-db.js

@@ -174,8 +174,21 @@ function init(opts) {
     if (typeof cfg.query !== "function") {
       throw _err("INVALID_CONFIG", "backend '" + name + "' missing query() function", true);
     }
+    // dialect — informational marker so dialect-specific consumers
+    // (e.g. b.db.declareView) can fail-fast at apply time. Defaults to
+    // "postgres" because that's the dominant blamejs externalDb target;
+    // operators on SQLite/MySQL/etc. set this explicitly so downstream
+    // primitives surface NOT_SUPPORTED with a clear message instead of
+    // emitting Postgres-flavored DDL into the wrong dialect.
+    var dialect = (cfg.dialect || "postgres").toLowerCase();
+    if (["postgres", "mysql", "sqlite", "mongodb", "other"].indexOf(dialect) === -1) {
+      throw _err("INVALID_CONFIG",
+        "backend '" + name + "': dialect must be one of " +
+        "'postgres' | 'mysql' | 'sqlite' | 'mongodb' | 'other', got '" + dialect + "'", true);
+    }
     backends[name] = {
       name:            name,
+      dialect:         dialect,
       pool:            new Pool(name, cfg),
       query:           cfg.query,
       ping:            cfg.ping || null,
@@ -372,6 +385,7 @@ function listBackends() {
     var b = backends[name];
     return {
       name:            name,
+      dialect:         b.dialect,
       classifications: b.classifications.slice(),
       residencyTag:    b.residencyTag,
       breakerState:    b.breaker.getState(),
@@ -790,6 +804,10 @@ module.exports = {
   adapters: {
     connectAs:    _adaptersConnectAs,
   },
+  // Migration runner targeting an externalDb backend. Mirrors b.migrations
+  // (which targets local SQLite) but runs against externalDb. Tracking +
+  // lock tables live on the externalDb side. See lib/external-db-migrate.js.
+  migrate:        require("./external-db-migrate"),
   Pool:           Pool,
   _resetForTest:  _resetForTest,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",