@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/cluster-provider-db.js

@@ -0,0 +1,317 @@
+"use strict";
+/**
+ * Default cluster-coordination provider — DB-row-based leader election.
+ *
+ * Uses an externalDb backend (already configured via b.externalDb.init)
+ * as the coordination point. A single row in `_blamejs_leader` holds
+ * the current lease; acquireLease is `INSERT ... ON CONFLICT ... DO
+ * UPDATE WHERE expiresAt < now() RETURNING ...`, which is atomic in
+ * Postgres and SQLite.
+ *
+ * Fencing tokens: every successful acquire bumps a monotonic integer.
+ * Leader-only DB writes include the current token; the audit-tip row's
+ * CHECK constraint rejects any incoming token below the stored one,
+ * which fences out a partitioned old leader even if its application-
+ * layer `_requireLeader()` gate somehow allowed the call through.
+ *
+ * Dialects: Postgres / SQLite use `INSERT ... ON CONFLICT ... DO
+ * UPDATE WHERE ... RETURNING` (atomic acquire-or-steal in one
+ * statement). MySQL takes a different shape because its
+ * `ON DUPLICATE KEY UPDATE` doesn't support a WHERE clause: each
+ * column update is gated by `IF(expiresAt < <nowMs>, VALUES(col), col)`
+ * so a non-expired lease is preserved untouched, and the followup
+ * SELECT reveals who currently holds the row. Both shapes are
+ * row-level atomic at the database — no client-side locking required.
+ *
+ * Public API:
+ *   create({ externalDbBackend, dialect? }) → provider instance
+ *
+ * Provider instance:
+ *   ensureSchema()                                async; idempotent CREATE
+ *                                                 TABLE + ALTER for
+ *                                                 endpoint migration
+ *   acquireLease(nodeId, leaseTtlMs, opts?)       async; → Lease | null.
+ *                                                 opts.endpoint persists
+ *                                                 in the row for discovery.
+ *   renewLease(lease, opts?)                      async; → Lease (throws on
+ *                                                 takeover). opts.endpoint
+ *                                                 refreshes the row.
+ *   releaseLease(lease)                           async; → void
+ *   currentLeader()                               async; →
+ *                                                 { nodeId, leaseExpiresAt,
+ *                                                   fencingToken,
+ *                                                   endpoint } | null
+ *
+ * Lease object shape:
+ *   { nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint }
+ */
+var C = require("./constants");
+var { generateToken } = require("./crypto");
+var externalDb = require("./external-db");
+var { ClusterProviderError } = require("./framework-error");
+
+var _err = ClusterProviderError.factory;
+
+function create(config) {
+  if (!config || !config.externalDbBackend) {
+    throw _err("INVALID_CONFIG",
+      "cluster-provider-db requires { externalDbBackend: <name> }", true);
+  }
+  var backendName = config.externalDbBackend;
+  var dialect = (config.dialect || "postgres").toLowerCase();
+  if (dialect !== "postgres" && dialect !== "sqlite" && dialect !== "mysql") {
+    throw _err("UNSUPPORTED_DIALECT",
+      "cluster-provider-db dialect must be 'postgres', 'sqlite', or 'mysql' (got: " + dialect + ")",
+      true);
+  }
+
+  // Postgres + SQLite use $1/$2 placeholders; MySQL uses ?. Keeping a
+  // single helper means the SQL builder doesn't have to care.
+  function _placeholder(n) {
+    return dialect === "mysql" ? "?" : "$" + n;
+  }
+
+  function _q(sql, params) {
+    return externalDb.query(sql, params || [], { backend: backendName });
+  }
+
+  async function ensureSchema() {
+    // Postgres + MySQL: BIGINT for ms-precision timestamps. SQLite:
+    // INTEGER (which is wide enough to hold a 64-bit value).
+    var intType = dialect === "sqlite" ? "INTEGER" : "BIGINT";
+    // MySQL needs explicit lengths on TEXT columns when used as a
+    // PRIMARY KEY; VARCHAR(64) covers our scope/nodeId/leaseId values
+    // with room to spare. Postgres and SQLite happily PRIMARY-KEY a
+    // plain TEXT column.
+    var pkText = dialect === "mysql" ? "VARCHAR(64)" : "TEXT";
+    var bodyText = dialect === "mysql" ? "VARCHAR(255)" : "TEXT";
+    // MySQL doesn't enforce CHECK constraints in some MariaDB / older
+    // MySQL versions; the constant-scope invariant is a documentation
+    // belt-and-braces — application code only ever writes 'leader' /
+    // 'state' so the check is informational. Skip on MySQL to avoid
+    // CREATE TABLE failures on installations where CHECK is parsed
+    // but then dropped silently (which would cause version drift).
+    var leaderCheck = dialect === "mysql" ? "" : ", CHECK (scope = 'leader')";
+    var stateCheck  = dialect === "mysql" ? "" : ", CHECK (scope = 'state')";
+
+    await _q(
+      "CREATE TABLE IF NOT EXISTS _blamejs_leader (" +
+      "  scope         " + pkText + " PRIMARY KEY," +
+      "  nodeId        " + bodyText + " NOT NULL," +
+      "  leaseId       " + bodyText + " NOT NULL," +
+      "  acquiredAt    " + intType + " NOT NULL," +
+      "  expiresAt     " + intType + " NOT NULL," +
+      "  fencingToken  " + intType + " NOT NULL," +
+      "  endpoint      " + bodyText + leaderCheck +
+      ")"
+    );
+    // Migration for installs that pre-date the endpoint column. Both
+    // Postgres (≥9.6) and SQLite (≥3.35, March 2021) support ADD COLUMN
+    // IF NOT EXISTS; MySQL 8.0.29+ does as well. We go through try/catch
+    // to keep the path version-agnostic — the only "expected" failure
+    // here is "column already exists," which we swallow.
+    try {
+      await _q("ALTER TABLE _blamejs_leader ADD COLUMN endpoint " + bodyText);
+    } catch (_e) { /* column already exists — fine */ }
+
+    await _q(
+      "CREATE TABLE IF NOT EXISTS _blamejs_cluster_state (" +
+      "  scope           " + pkText + " PRIMARY KEY," +
+      "  vaultKeyFp      " + bodyText + " NOT NULL," +
+      "  recordedAt      " + intType + " NOT NULL," +
+      "  recordedByNode  " + bodyText + " NOT NULL" + stateCheck +
+      ")"
+    );
+  }
+
+  async function acquireLease(nodeId, leaseTtlMs, opts) {
+    if (!nodeId) throw _err("INVALID_NODE_ID", "nodeId required", true);
+    if (typeof leaseTtlMs !== "number" || leaseTtlMs <= 0) {
+      throw _err("INVALID_TTL", "leaseTtlMs must be a positive number", true);
+    }
+    var endpoint = (opts && opts.endpoint) || null;
+    var leaseId = generateToken(C.BYTES.bytes(16));
+    var nowMs = Date.now();
+    var expiresAt = nowMs + leaseTtlMs;
+
+    var row;
+    if (dialect === "mysql") {
+      // MySQL has no `ON CONFLICT ... DO UPDATE WHERE` and no
+      // `RETURNING`. Atomicity comes from `INSERT ... ON DUPLICATE
+      // KEY UPDATE` evaluated as one statement; the WHERE-clause
+      // semantics are implemented per-column with `IF(expiresAt <
+      // nowMs, VALUES(col), col)` so a still-valid lease is preserved
+      // and an expired one is overwritten. The follow-up SELECT
+      // reveals who currently holds the row — same as Postgres'
+      // RETURNING but as a separate statement.
+      var insertSql =
+        "INSERT INTO _blamejs_leader " +
+        "  (scope, nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint) " +
+        "VALUES " +
+        "  ('leader', ?, ?, ?, ?, 1, ?) " +
+        "ON DUPLICATE KEY UPDATE " +
+        "  nodeId       = IF(expiresAt < ?, VALUES(nodeId), nodeId)," +
+        "  leaseId      = IF(expiresAt < ?, VALUES(leaseId), leaseId)," +
+        "  acquiredAt   = IF(expiresAt < ?, VALUES(acquiredAt), acquiredAt)," +
+        "  fencingToken = IF(expiresAt < ?, fencingToken + 1, fencingToken)," +
+        "  endpoint     = IF(expiresAt < ?, VALUES(endpoint), endpoint)," +
+        // expiresAt MUST be the last assignment — IF() evaluates each
+        // column against the row state BEFORE that column's update is
+        // applied, so checking expiresAt for the other columns first
+        // and overwriting it last keeps the predicate consistent.
+        "  expiresAt    = IF(expiresAt < ?, VALUES(expiresAt), expiresAt)";
+      await _q(insertSql, [
+        nodeId, leaseId, nowMs, expiresAt, endpoint,
+        nowMs, nowMs, nowMs, nowMs, nowMs, nowMs,
+      ]);
+      var sel = await _q(
+        "SELECT nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint " +
+        "FROM _blamejs_leader WHERE scope = 'leader'"
+      );
+      if (!sel.rows || sel.rows.length === 0) return null;
+      row = sel.rows[0];
+    } else {
+      // Postgres / SQLite — single-statement RETURNING.
+      var sql =
+        "INSERT INTO _blamejs_leader " +
+        "  (scope, nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint) " +
+        "VALUES " +
+        "  ('leader', " + _placeholder(1) + ", " + _placeholder(2) + ", " +
+        "   " + _placeholder(3) + ", " + _placeholder(4) + ", 1, " + _placeholder(5) + ") " +
+        "ON CONFLICT (scope) DO UPDATE SET " +
+        "  nodeId       = EXCLUDED.nodeId," +
+        "  leaseId      = EXCLUDED.leaseId," +
+        "  acquiredAt   = EXCLUDED.acquiredAt," +
+        "  expiresAt    = EXCLUDED.expiresAt," +
+        "  fencingToken = _blamejs_leader.fencingToken + 1," +
+        "  endpoint     = EXCLUDED.endpoint " +
+        "WHERE _blamejs_leader.expiresAt < " + _placeholder(6) + " " +
+        "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
+      var result = await _q(sql, [nodeId, leaseId, nowMs, expiresAt, endpoint, nowMs]);
+      if (!result.rows || result.rows.length === 0) return null;
+      row = result.rows[0];
+    }
+    if (row.nodeId !== nodeId || row.leaseId !== leaseId) {
+      // Another node won the race (the row reflects their values, not ours).
+      return null;
+    }
+    return {
+      nodeId:        row.nodeId,
+      leaseId:       row.leaseId,
+      acquiredAt:    Number(row.acquiredAt),
+      expiresAt:     Number(row.expiresAt),
+      fencingToken:  Number(row.fencingToken),
+      endpoint:      row.endpoint || null,
+    };
+  }
+
+  async function renewLease(lease, opts) {
+    if (!lease || !lease.leaseId) throw _err("INVALID_LEASE", "lease required", true);
+    var nowMs = Date.now();
+    var newExpiresAt = nowMs + (lease.expiresAt - lease.acquiredAt);
+    // opts.endpoint, when provided, refreshes the stored endpoint so
+    // operators who hot-update their config see the discovery row catch
+    // up. Default = preserve whatever was stored at acquire time.
+    var endpoint = (opts && opts.endpoint !== undefined) ? opts.endpoint : lease.endpoint || null;
+
+    // Match on (nodeId, leaseId) so a takeover is detectable: if our
+    // leaseId is no longer in the row, the SELECT-after-UPDATE
+    // returns either no row OR a row with a different leaseId, and
+    // we throw LEASE_LOST. Don't bump fencingToken on renewal — only
+    // on a fresh acquire.
+    var row;
+    if (dialect === "mysql") {
+      var rv = await _q(
+        "UPDATE _blamejs_leader SET " +
+        "  expiresAt = ?, endpoint = ? " +
+        "WHERE scope = 'leader' AND nodeId = ? AND leaseId = ?",
+        [newExpiresAt, endpoint, lease.nodeId, lease.leaseId]
+      );
+      var affected = rv && (rv.affectedRows || rv.rowCount || 0);
+      if (!affected) {
+        throw _err("LEASE_LOST",
+          "lease for node '" + lease.nodeId + "' was taken over (renewal rejected)",
+          false);
+      }
+      var sel = await _q(
+        "SELECT nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint " +
+        "FROM _blamejs_leader WHERE scope = 'leader'"
+      );
+      if (!sel.rows || sel.rows.length === 0 ||
+          sel.rows[0].nodeId !== lease.nodeId ||
+          sel.rows[0].leaseId !== lease.leaseId) {
+        throw _err("LEASE_LOST",
+          "lease for node '" + lease.nodeId + "' was taken over after renewal",
+          false);
+      }
+      row = sel.rows[0];
+    } else {
+      var sql =
+        "UPDATE _blamejs_leader SET " +
+        "  expiresAt = " + _placeholder(1) + "," +
+        "  endpoint  = " + _placeholder(2) + " " +
+        "WHERE scope = 'leader' AND nodeId = " + _placeholder(3) +
+        "  AND leaseId = " + _placeholder(4) + " " +
+        "RETURNING nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint";
+      var result = await _q(sql, [newExpiresAt, endpoint, lease.nodeId, lease.leaseId]);
+      if (!result.rows || result.rows.length === 0) {
+        throw _err("LEASE_LOST",
+          "lease for node '" + lease.nodeId + "' was taken over (renewal rejected)",
+          false);
+      }
+      row = result.rows[0];
+    }
+    return {
+      nodeId:        row.nodeId,
+      leaseId:       row.leaseId,
+      acquiredAt:    Number(row.acquiredAt),
+      expiresAt:     Number(row.expiresAt),
+      fencingToken:  Number(row.fencingToken),
+      endpoint:      row.endpoint || null,
+    };
+  }
+
+  async function releaseLease(lease) {
+    if (!lease || !lease.leaseId) return;
+    // Clear our row so the next acquire wins immediately. Match on
+    // leaseId so a takeover-then-release race doesn't clear someone
+    // else's lease.
+    var sql =
+      "UPDATE _blamejs_leader SET " +
+      "  expiresAt = 0 " +
+      "WHERE scope = 'leader' AND nodeId = " + _placeholder(1) +
+      "  AND leaseId = " + _placeholder(2);
+    await _q(sql, [lease.nodeId, lease.leaseId]);
+  }
+
+  async function currentLeader() {
+    var result = await _q(
+      "SELECT nodeId, expiresAt, fencingToken, endpoint FROM _blamejs_leader " +
+      "WHERE scope = 'leader'"
+    );
+    if (!result.rows || result.rows.length === 0) return null;
+    var row = result.rows[0];
+    if (Number(row.expiresAt) < Date.now()) return null;
+    return {
+      nodeId:           row.nodeId,
+      leaseExpiresAt:   Number(row.expiresAt),
+      fencingToken:     Number(row.fencingToken),
+      endpoint:         row.endpoint || null,
+    };
+  }
+
+  return {
+    kind:           "db",
+    backendName:    backendName,
+    dialect:        dialect,
+    ensureSchema:   ensureSchema,
+    acquireLease:   acquireLease,
+    renewLease:     renewLease,
+    releaseLease:   releaseLease,
+    currentLeader: currentLeader,
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/vendor/blamejs/lib/cluster-storage.js

@@ -0,0 +1,351 @@
+"use strict";
+/**
+ * @module b.clusterStorage
+ * @nav    Production
+ * @title  Cluster Storage
+ *
+ * @intro
+ *   Cluster-aware framework-state SQL dispatch — runs against the
+ *   framework's local SQLite in single-node mode and against the
+ *   operator-supplied external DB in cluster mode. Distributed shared
+ *   state for audit, consent, sessions, queue, and subject tables;
+ *   write paths carry the cluster's fencing token so a stale leader
+ *   cannot extend a chain after losing its lease.
+ *
+ *   Callers write SQL once using unprefixed logical table names
+ *   (`audit_log`, `consent_log`, …) and `?` placeholders. The
+ *   dispatcher rewrites bare framework tables to their `_blamejs_`-
+ *   prefixed cluster names and translates `?` to `$N` for Postgres.
+ *   Unknown identifiers pass through unchanged so operator-written
+ *   migrations and app-data SQL are never touched.
+ *
+ *   The dispatcher is async-only. Even single-node SQLite calls
+ *   return a resolved Promise so the call shape stays uniform across
+ *   deployment topologies — callers `await` every method.
+ *
+ * @card
+ *   Cluster-aware framework-state SQL dispatch — runs against the framework's local SQLite in single-node mode and against the operator-supplied external DB in cluster mode.
+ */
+
+var cluster = require("./cluster");
+var frameworkSchema = require("./framework-schema");
+var externalDb = require("./external-db");
+var lazyRequire = require("./lazy-require");
+var { FrameworkError } = require("./framework-error");
+
+class ClusterStorageError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "ClusterStorageError";
+    this.code = code || "cluster-storage/invalid";
+    this.isClusterStorageError = true;
+  }
+}
+
+// ---- Lazy db ref to avoid circular require ----
+var _localDb = lazyRequire(function () { return require("./db"); });
+
+// ---- Table-name resolution ----
+
+/**
+ * @primitive b.clusterStorage.tableName
+ * @signature b.clusterStorage.tableName(local)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.resolveTables, b.cluster.isClusterMode
+ *
+ * Resolve a logical framework table name to the active backend's
+ * concrete name. In single-node mode returns the input unchanged; in
+ * cluster mode returns the `_blamejs_`-prefixed name from the
+ * framework-schema mapping (e.g. `audit_log` to `_blamejs_audit_log`).
+ * Use this when composing SQL by hand against framework tables — the
+ * `execute` family rewrites bare names automatically, but ad-hoc DDL
+ * or admin queries that reference a specific table need the resolved
+ * name explicitly.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var name = b.clusterStorage.tableName("audit_log");
+ *   // → "audit_log"             (single-node)
+ *   // → "_blamejs_audit_log"    (cluster mode)
+ */
+function tableName(local) {
+  if (cluster.isClusterMode()) return frameworkSchema.tableName(local);
+  return local;
+}
+
+// Precomputed rewrite table for resolveTables(). Built once at module
+// load from the static frozen frameworkSchema.LOCAL_TO_EXTERNAL mapping —
+// not from operator/request input. Order longest-first so prefix matches
+// don't collide (audit_log before audit). Identity mappings are filtered
+// out so the loop body has no no-op iterations. Framework table names
+// are entirely [A-Za-z0-9_], so a manual word-boundary scan replaces
+// the regex `\b...\b` exactly without runtime regex compilation.
+// Character-code bounds for the word-character class \w that JavaScript
+// regex `\b` uses. Stored as code-from-literal so the magic numbers are
+// self-evident at the source rather than needing a comment to decode.
+var _CC_0          = "0".charCodeAt(0);
+var _CC_9          = "9".charCodeAt(0);
+var _CC_A          = "A".charCodeAt(0);
+var _CC_Z          = "Z".charCodeAt(0);
+var _CC_UNDERSCORE = "_".charCodeAt(0);
+var _CC_a          = "a".charCodeAt(0);
+var _CC_z          = "z".charCodeAt(0);
+
+function _isWordChar(code) {
+  return (code >= _CC_0 && code <= _CC_9) ||
+         (code >= _CC_A && code <= _CC_Z) ||
+         code === _CC_UNDERSCORE          ||
+         (code >= _CC_a && code <= _CC_z);
+}
+
+function _replaceWordBoundaryAll(haystack, needle, replacement) {
+  if (haystack.length < needle.length) return haystack;
+  var out = "";
+  var cursor = 0;
+  var matched = false;
+  var idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    var beforeCode = idx === 0 ? -1 : haystack.charCodeAt(idx - 1);
+    var afterPos   = idx + needle.length;
+    var afterCode  = afterPos >= haystack.length ? -1 : haystack.charCodeAt(afterPos);
+    var leftBoundary  = beforeCode === -1 || !_isWordChar(beforeCode);
+    var rightBoundary = afterCode  === -1 || !_isWordChar(afterCode);
+    if (leftBoundary && rightBoundary) {
+      out += haystack.slice(cursor, idx) + replacement;
+      cursor = afterPos;
+      matched = true;
+      idx = haystack.indexOf(needle, cursor);
+    } else {
+      // Boundary mismatch — advance past this position by one and keep
+      // scanning. We do NOT flush partial output here; the final
+      // haystack.slice(cursor) below covers any non-rewritten tail.
+      idx = haystack.indexOf(needle, idx + 1);
+    }
+  }
+  if (!matched) return haystack;
+  return out + haystack.slice(cursor);
+}
+
+var _REWRITE_TABLE = (function () {
+  var mapping = frameworkSchema.LOCAL_TO_EXTERNAL;
+  var names = Object.keys(mapping).sort(function (a, b) {
+    return b.length - a.length;
+  });
+  var entries = [];
+  for (var i = 0; i < names.length; i++) {
+    var local = names[i];
+    var external = mapping[local];
+    if (local === external) continue;
+    entries.push({ local: local, external: external });
+  }
+  return Object.freeze(entries);
+})();
+
+// Rewrite bare table names in SQL when running in cluster mode. We only
+// touch tokens that are exactly one of the framework's known table names
+// (audit_log, consent_log, …) — anything else passes through unchanged
+// so app-data SQL composed via this dispatcher (or operator-written
+// migrations) isn't rewritten by accident.
+/**
+ * @primitive b.clusterStorage.resolveTables
+ * @signature b.clusterStorage.resolveTables(sql)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.tableName, b.clusterStorage.execute
+ *
+ * Rewrite bare framework table names in a SQL string to their
+ * cluster-mode `_blamejs_`-prefixed equivalents. Word-boundary scan;
+ * only exact identifier matches are rewritten — substrings,
+ * column-qualified names, and operator app tables pass through
+ * untouched. In single-node mode the SQL is returned unchanged. The
+ * `execute` family calls this internally; callers reach for it
+ * directly only when running raw SQL through a different path
+ * (admin tooling, migration runners).
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var sql = b.clusterStorage.resolveTables(
+ *     "SELECT id FROM audit_log WHERE counter > ?"
+ *   );
+ *   // → "SELECT id FROM audit_log WHERE counter > ?"          (single-node)
+ *   // → "SELECT id FROM _blamejs_audit_log WHERE counter > ?" (cluster)
+ */
+function resolveTables(sql) {
+  if (!cluster.isClusterMode()) return sql;
+  var translated = sql;
+  for (var i = 0; i < _REWRITE_TABLE.length; i++) {
+    var entry = _REWRITE_TABLE[i];
+    translated = _replaceWordBoundaryAll(translated, entry.local, entry.external);
+  }
+  return translated;
+}
+
+// ---- Placeholder translation ----
+//
+// SQLite and Postgres both accept `?` in some contexts, but Postgres
+// only accepts `$N` for parameter binding. We translate at dispatch
+// time so callers always write `?` and the right thing happens per
+// dialect.
+
+/**
+ * @primitive b.clusterStorage.placeholderize
+ * @signature b.clusterStorage.placeholderize(sql, dialect)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.cluster.dialect
+ *
+ * Translate `?` placeholders to numbered `$1`, `$2`, … form for
+ * Postgres backends; passthrough for `"sqlite"` and `"mysql"`. The
+ * walker skips question marks inside single-quoted string literals so
+ * `WHERE s = '?'` is preserved verbatim. Doubled-quote escapes (`''`)
+ * inside strings are recognized. The `execute` family calls this on
+ * every cluster-mode dispatch; reach for it directly only when
+ * shipping raw SQL through a non-`execute` driver path.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var sql = b.clusterStorage.placeholderize(
+ *     "SELECT id FROM audit_log WHERE counter > ? AND actor = ?",
+ *     "postgres"
+ *   );
+ *   // → "SELECT id FROM audit_log WHERE counter > $1 AND actor = $2"
+ */
+function placeholderize(sql, dialect) {
+  if (dialect !== "postgres") return sql;
+  // Walk the SQL and replace `?` with $1, $2, … but skip ones inside
+  // single-quoted string literals.
+  var out = "";
+  var n = 0;
+  var inStr = false;
+  for (var i = 0; i < sql.length; i++) {
+    var c = sql.charAt(i);
+    if (c === "'" && !inStr) { inStr = true;  out += c; continue; }
+    if (c === "'" &&  inStr) {
+      // Handle escaped '' inside string
+      if (sql.charAt(i + 1) === "'") { out += "''"; i += 1; continue; }
+      inStr = false; out += c; continue;
+    }
+    if (!inStr && c === "?") { n += 1; out += "$" + n; continue; }
+    out += c;
+  }
+  return out;
+}
+
+// ---- execute() ----
+
+/**
+ * @primitive b.clusterStorage.execute
+ * @signature b.clusterStorage.execute(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @compliance soc2
+ * @related   b.clusterStorage.executeOne, b.clusterStorage.executeAll, b.cluster.isClusterMode
+ *
+ * Run framework-state SQL against the active backend. In cluster mode
+ * the SQL is routed through `resolveTables` + `placeholderize`, then
+ * dispatched to the operator-supplied external DB. In single-node
+ * mode it runs against the framework's local SQLite via
+ * `db().prepare(...)` — `SELECT` and `RETURNING` queries use `.all()`,
+ * everything else uses `.run()`. The shape is uniform either way:
+ * resolves to `{ rows, rowCount }` where `rows` is the array of result
+ * objects and `rowCount` is `rows.length` for selects or `info.changes`
+ * for writes. Throws `ClusterStorageError` (code
+ * `cluster-storage/bad-arg`) when `sql` is not a string.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var result = await b.clusterStorage.execute(
+ *     "SELECT counter, row_hash FROM audit_log WHERE counter > ?",
+ *     [42]
+ *   );
+ *   // → { rows: [ { counter: 43, row_hash: "..." } ], rowCount: 1 }
+ */
+async function execute(sql, params) {
+  if (typeof sql !== "string") {
+    throw new ClusterStorageError("sql must be a string", "cluster-storage/bad-arg");
+  }
+  params = params || [];
+
+  if (cluster.isClusterMode()) {
+    var translated = placeholderize(resolveTables(sql), cluster.dialect());
+    var result = await externalDb.query(translated, params, {
+      backend: cluster.externalDbBackend(),
+    });
+    return result;
+  }
+
+  // Local SQLite path. node:sqlite is sync — wrap in a resolved Promise
+  // so callers always see the same shape regardless of mode.
+  var stmt = _localDb().prepare(sql);
+  // Heuristic: if the statement returns rows (SELECT or has RETURNING),
+  // use .all(); otherwise .run() and report changes as rowCount.
+  if (/^\s*SELECT\b/i.test(sql) || /\bRETURNING\b/i.test(sql)) {
+    var rows = stmt.all.apply(stmt, params);
+    return { rows: rows, rowCount: rows.length };
+  }
+  var info = stmt.run.apply(stmt, params);
+  return { rows: [], rowCount: info.changes };
+}
+
+// Convenience wrappers for the two common patterns.
+/**
+ * @primitive b.clusterStorage.executeOne
+ * @signature b.clusterStorage.executeOne(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.clusterStorage.executeAll
+ *
+ * Convenience over `execute` for queries expected to return at most
+ * one row. Returns the first row when the result set is non-empty,
+ * `null` otherwise. The same dispatch rules as `execute` apply —
+ * cluster mode routes to external DB, single-node hits local SQLite.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var row = await b.clusterStorage.executeOne(
+ *     "SELECT counter, row_hash FROM audit_tip WHERE id = ?",
+ *     [1]
+ *   );
+ *   // → { counter: 128, row_hash: "..." }
+ *   // → null when no row matches
+ */
+async function executeOne(sql, params) {
+  var result = await execute(sql, params);
+  return result.rows.length > 0 ? result.rows[0] : null;
+}
+
+/**
+ * @primitive b.clusterStorage.executeAll
+ * @signature b.clusterStorage.executeAll(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.clusterStorage.executeOne
+ *
+ * Convenience over `execute` for queries expected to return a row
+ * array. Returns the `rows` array directly without the surrounding
+ * `{ rows, rowCount }` envelope. Empty result sets resolve to `[]`.
+ * The same dispatch rules as `execute` apply.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rows = await b.clusterStorage.executeAll(
+ *     "SELECT id, status FROM queue_jobs WHERE status = ?",
+ *     ["pending"]
+ *   );
+ *   // → [ { id: 1, status: "pending" }, { id: 2, status: "pending" } ]
+ */
+async function executeAll(sql, params) {
+  var result = await execute(sql, params);
+  return result.rows;
+}
+
+module.exports = {
+  execute:               execute,
+  executeOne:            executeOne,
+  executeAll:            executeAll,
+  tableName:             tableName,
+  resolveTables:         resolveTables,
+  placeholderize:        placeholderize,
+  ClusterStorageError:   ClusterStorageError,
+};