@blamejs/core 0.13.37 → 0.13.39

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.39 (2026-05-29) — **Dual-control approvals are atomic — no quorum bypass or double-consume under concurrency.** The dual-control approval store read a grant, mutated it in memory, and wrote it back with an await in between — a non-atomic read-modify-write. Under concurrent calls (two approvals, or a retried one) each could act on a stale snapshot: the same approver could be appended twice and reach the M-of-N quorum with a single human, or a single-use grant could be consumed twice. approve / consume / revoke / cancel now commit through a new atomic cache.update primitive, so the check and the mutation are one indivisible step. The new b.cache.update is available to application code too — the memory backend is atomic by single-thread, and the cluster backend uses a transaction with compare-and-set so a concurrent writer on another node cannot lose an update. **Added:** *b.cache.update(key, mutatorFn, opts?) — atomic read-modify-write* — Reads the current value, calls `mutatorFn(current | null)`, and commits the result in one operation so a concurrent writer cannot clobber the change — the lost-update race that makes a plain `get` → mutate → `set` unsafe for counters, sets, and quorum state. The memory backend is atomic by single-thread; the cluster backend runs a transaction with a compare-and-set (and retries on contention) so the guarantee holds across nodes. `mutatorFn` returns `{ value }` to commit, `{ abort: data }` to leave the entry untouched and surface `data`, or `{ delete: true }` to remove it; the call resolves to `{ updated, value }`, `{ updated, deleted }`, or `{ aborted }`. **Security:** *Dual-control quorum and single-use guarantees hold under concurrent approvals* — `b.dualControl` persisted each grant through a cache read → in-memory mutate → write-back. Because the read and the write were separate awaited steps, two concurrent `approve` calls (or a retried one behind a load balancer) could each read the same pre-approval snapshot, so the duplicate-approver guard passed twice and the same approver was counted toward the M-of-N quorum twice — reaching quorum with one human. The same shape let two concurrent `consume` calls each see an unconsumed grant and both run the destructive operation. `approve` / `consume` / `revoke` / `cancel` now perform the check-and-mutate atomically via `cache.update`, so exactly one concurrent caller wins each transition.
+
+- v0.13.38 (2026-05-29) — **Atomic cache tag invalidation, and a clusterStorage.transaction primitive for multi-statement framework writes.** The cluster cache stored a value and its tag index with separate statements, so two concurrent writes to the same key could interleave their tag updates and leave the index out of step with the value — a later tag-based invalidation would then miss the key, letting a stale (possibly authorization-bearing) value survive a wipe. The value and tag writes now commit as one atomic unit. The enabling piece is a new b.clusterStorage.transaction primitive that runs a multi-statement read-modify-write all-or-nothing against the active backend — the external DB's pooled transaction in cluster mode, and a serialized transaction on the shared SQLite connection in single-node mode (so no concurrent statement can interleave into an open transaction). **Added:** *b.clusterStorage.transaction(fn) — atomic multi-statement framework-state writes* — Runs `fn` inside one transaction against the active backend so a multi-statement read-modify-write commits all-or-nothing. `fn` receives a transaction handle with the same `execute` / `executeOne` / `executeAll` surface, scoped to the open transaction. Cluster mode uses the external DB's pooled transaction (with its deadlock retry); single-node mode serializes against other transactions and against `execute` on the shared SQLite connection, so a concurrent statement cannot interleave into an open transaction. Use the handle's methods inside `fn` — calling the module-level `execute` from within `fn` would wait on the very transaction it is running. **Fixed:** *Cluster cache tag invalidation can no longer miss a key under concurrent writes* — The cluster cache wrote a value (`INSERT ... ON CONFLICT DO UPDATE`) and then rewrote its tag index (`DELETE` prior tags, `INSERT` new ones) as separate statements. Two concurrent `set()`s on the same key could interleave those tag statements, leaving the tag index inconsistent with the value — so a later `invalidateTag` could miss the key and a stale value would survive the wipe. The value and tag writes now run inside a single `clusterStorage.transaction`, so a concurrent writer observes either the whole prior state or the whole new state, never a mix.
+
 - v0.13.37 (2026-05-29) — **Encrypted-mode DB refuses writes before a full tmpfs corrupts it.** In encrypted-at-rest mode the live SQLite working copy is on a tmpfs (Docker's /dev/shm defaults to 64 MiB). If that fills — an append-only audit chain and session rows grow over time — SQLite hits ENOSPC and the working copy is corrupted. Earlier releases made that corruption self-heal on the next boot by rolling back to the last encrypted snapshot, but the rollback still loses writes since the last flush. This adds the prevention side: a periodic free-space probe refuses growth writes (INSERT / UPDATE / REPLACE) with a clear db/storage-low error once free space drops below a threshold, before the tmpfs fills. DELETE and reads stay available so retention can reclaim space and the application keeps serving, and the refusal lifts automatically once free space recovers. The threshold defaults to 16 MiB of headroom and is tunable; the guard is encrypted-mode only. **Security:** *Free-space guard refuses growth writes before the tmpfs working copy fills* — `b.db` in encrypted-at-rest mode now probes free space on the tmpfs holding the working copy and, when it falls below `minFreeBytes` (default 16 MiB), refuses `INSERT` / `UPDATE` / `REPLACE` with a clear `db/storage-low` error instead of letting the write run the mount out of space and corrupt the database. `DELETE`, reads, and DDL stay available so retention can prune and the app keeps serving; the refusal clears automatically when free space recovers. The error message points at the cause (Docker's 64 MiB `/dev/shm` default) and the fix (`shm_size` / `--shm-size`, or pruning). Set `minFreeBytes` to tune the headroom, or `0` to disable. This complements the existing boot-time recovery: prevention (fail clear, keep recent writes) ahead of recovery (roll back to the last snapshot).
 
 - v0.13.36 (2026-05-29) — **Certificate renewal trusts the sealed cert's own expiry, not the plaintext index.** The managed-certificate renewal check decided a cached cert was still fresh by reading expiresAt from the plaintext meta.json index that sits beside the sealed cert, rather than from the certificate itself. If that index drifted from — or was tampered relative to — the actual cert (a far-future expiry recorded over a certificate that is in fact near expiry), the manager would skip renewal and keep serving a cert that was about to expire or already had. Renewal now re-derives the expiry and fingerprint from the sealed certificate itself; meta.json is treated as an advisory convenience copy. A sealed cert that no longer parses is re-issued (the same recovery as an unreadable one), and a corrupt meta.json over a valid cert now loads cleanly from the cert instead of forcing a needless re-issue. The local job queue also bounds the size of a job payload it parses back from a stored row, matching the cap the dead-letter listing already used. **Fixed:** *Local job queue bounds the size of a payload parsed back from a stored row* — When the local queue leased a job or re-enqueued a repeating one, it parsed the job payload back from its stored row without an upper size bound, unlike the dead-letter listing which already capped it. A row with an oversized payload (a corrupted or tampered store) could force an unbounded parse. Both paths now cap the parse at the same 64 MiB ceiling the dead-letter path uses. **Security:** *Cert renewal re-derives expiry from the sealed certificate, not the meta.json index* — `b.cert`'s renewal short-circuit read `expiresAt` from the plaintext `meta.json` written beside each sealed cert. Because that index can drift from the actual certificate (or be altered independently of it), a far-future value over an actually-expiring cert would suppress renewal and serve a cert past — or about to pass — its validity. The renewal decision now parses the expiry and fingerprint from the sealed certificate itself on load, so `meta.json` is advisory only. A sealed cert that will not parse is treated as corrupt and re-issued; a corrupt `meta.json` over an otherwise-valid cert loads from the cert without a needless re-issue.

package/lib/cache.js

@@ -331,6 +331,25 @@ function _memoryBackend(cfg) {
     return true;
   }
 
+  // Atomic read-modify-write. Single-process V8 is single-threaded and the
+  // read + mutatorFn decision run with no `await` before the write, so no
+  // concurrent task can interleave between reading the current value and
+  // committing the new one. Same contract as the cluster backend's update.
+  async function _updateEntry(key, mutatorFn, expiresAt, meta) {
+    var now = clock();
+    var entry = entries.get(key);
+    var current = (entry && !_isExpired(entry, now)) ? entry.value : null;
+    var decision = mutatorFn(current);
+    if (decision && decision.abort !== undefined) return { aborted: decision.abort };
+    if (decision && decision.delete === true) {
+      if (entry) { _untrack(key, entry); entries.delete(key); }
+      return { updated: true, deleted: true };
+    }
+    var effExpires = (decision.expiresAt !== undefined) ? decision.expiresAt : expiresAt;
+    await set(key, decision.value, effExpires, meta);
+    return { updated: true, value: decision.value };
+  }
+
   async function has(key) {
     var entry = entries.get(key);
     if (!entry) return false;
@@ -420,6 +439,7 @@ function _memoryBackend(cfg) {
     name:           "memory",
     get:            get,
     set:            set,
+    update:         _updateEntry,
     del:            del,
     has:            has,
     clear:          clear,
@@ -511,32 +531,109 @@ function _clusterBackend(cfg) {
     var storedExpires = (expiresAt === Infinity) ? Number.MAX_SAFE_INTEGER : expiresAt;
     var now = clock();
     var ck = _composedKey(key);
-    // SQLite + Postgres both honor ON CONFLICT (cacheKey) DO UPDATE.
-    await clusterStorage.execute(
-      "INSERT INTO _blamejs_cache (cacheKey, valueJson, expiresAt, updatedAt) " +
-      "VALUES (?, ?, ?, ?) " +
-      "ON CONFLICT (cacheKey) DO UPDATE SET " +
-      "valueJson = ?, expiresAt = ?, updatedAt = ?",
-      [ck, json, storedExpires, now, json, storedExpires, now]
-    );
-    // Tag handling: drop any prior tags for this key (tags can change
-    // across sets), then INSERT the new ones. The PRIMARY KEY on
-    // (cacheKey, tag) makes the INSERT idempotent if duplicate tags
-    // sneak in.
     var tags = meta && Array.isArray(meta.tags) ? meta.tags : null;
-    await clusterStorage.execute(
-      "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
-      [ck]
-    );
-    if (tags && tags.length > 0) {
-      for (var i = 0; i < tags.length; i++) {
-        await clusterStorage.execute(
-          "INSERT INTO _blamejs_cache_tags (cacheKey, tag) VALUES (?, ?) " +
-          "ON CONFLICT (cacheKey, tag) DO NOTHING",
-          [ck, tags[i]]
-        );
+    // The value UPSERT and the tag-index rewrite (DELETE prior tags, then
+    // INSERT the new set) must commit as ONE unit. Done as separate
+    // statements they race: two concurrent set()s on the same key can
+    // interleave their DELETE/INSERT pairs, leaving a tag index that no
+    // longer matches the value row — so a later invalidateTag misses the
+    // key (a stale, possibly authorization-bearing, value survives a wipe).
+    // Wrapping them in a transaction makes a concurrent set see either the
+    // whole prior state or the whole new state, never a mix.
+    // SQLite + Postgres both honor ON CONFLICT (cacheKey) DO UPDATE.
+    await clusterStorage.transaction(async function (tx) {
+      await tx.execute(
+        "INSERT INTO _blamejs_cache (cacheKey, valueJson, expiresAt, updatedAt) " +
+        "VALUES (?, ?, ?, ?) " +
+        "ON CONFLICT (cacheKey) DO UPDATE SET " +
+        "valueJson = ?, expiresAt = ?, updatedAt = ?",
+        [ck, json, storedExpires, now, json, storedExpires, now]
+      );
+      // Drop any prior tags for this key (tags can change across sets),
+      // then INSERT the new ones. The PRIMARY KEY on (cacheKey, tag) makes
+      // the INSERT idempotent if duplicate tags sneak in.
+      await tx.execute(
+        "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
+        [ck]
+      );
+      if (tags && tags.length > 0) {
+        for (var i = 0; i < tags.length; i++) {
+          await tx.execute(
+            "INSERT INTO _blamejs_cache_tags (cacheKey, tag) VALUES (?, ?) " +
+            "ON CONFLICT (cacheKey, tag) DO NOTHING",
+            [ck, tags[i]]
+          );
+        }
       }
+    });
+  }
+
+  // Atomic read-modify-write. Reads the current value, calls mutatorFn,
+  // and commits the result in one transaction — with a compare-and-set
+  // (UPDATE ... WHERE valueJson = <the exact bytes we read>) so a
+  // concurrent writer on another node cannot clobber the change (lost
+  // update). On a CAS miss the whole thing retries against the fresh
+  // value. Single-node serializes via clusterStorage.transaction, so the
+  // CAS never misses there; the retry only fires in cluster mode.
+  // mutatorFn(current|null) returns { value } to commit, { abort: data }
+  // to leave the row untouched and surface `data`, or { delete: true }.
+  async function _updateRow(key, mutatorFn, expiresAt, meta) {
+    var ck = _composedKey(key);
+    var maxRetries = 5;
+    for (var attempt = 0; attempt < maxRetries; attempt++) {
+      var outcome = await clusterStorage.transaction(async function (tx) {
+        var now = clock();
+        var row = await tx.executeOne(
+          "SELECT valueJson, expiresAt FROM _blamejs_cache WHERE cacheKey = ?", [ck]);
+        var oldRaw = null;
+        var current = null;
+        if (row && row.expiresAt > now) {
+          oldRaw = row.valueJson;
+          var stored = row.valueJson;
+          if (typeof stored === "string" && stored.indexOf(CACHE_SEAL_PREFIX) === 0) {
+            stored = vault().unseal(stored.substring(CACHE_SEAL_PREFIX.length));
+          }
+          current = safeJson.parse(stored, { maxBytes: C.BYTES.mib(64) });
+        }
+        var decision = mutatorFn(current);
+        if (decision && decision.abort !== undefined) return { aborted: decision.abort };
+        if (decision && decision.delete === true) {
+          if (oldRaw !== null) {
+            await tx.execute("DELETE FROM _blamejs_cache WHERE cacheKey = ? AND valueJson = ?", [ck, oldRaw]);
+            await tx.execute("DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?", [ck]);
+          }
+          return { updated: true, deleted: true };
+        }
+        var json = safeJson.stringify(decision.value);
+        if (meta && meta.seal === true) json = CACHE_SEAL_PREFIX + vault().seal(json);
+        // The mutator may pin the entry's expiry to the value's own
+        // lifetime (e.g. a grant whose expiresAt the mutator just read);
+        // otherwise the caller-resolved ttl applies.
+        var effExpires = (decision.expiresAt !== undefined) ? decision.expiresAt : expiresAt;
+        var storedExpires = (effExpires === Infinity) ? Number.MAX_SAFE_INTEGER : effExpires;
+        if (oldRaw === null) {
+          // Row was absent/expired — insert, but lose the race if another
+          // writer inserted concurrently (ON CONFLICT DO NOTHING → 0 rows).
+          var ins = await tx.execute(
+            "INSERT INTO _blamejs_cache (cacheKey, valueJson, expiresAt, updatedAt) " +
+            "VALUES (?, ?, ?, ?) ON CONFLICT (cacheKey) DO NOTHING",
+            [ck, json, storedExpires, now]);
+          if (!ins || ins.rowCount !== 1) return { conflict: true };
+        } else {
+          // CAS: only commit if the row still holds the exact bytes we read.
+          var upd = await tx.execute(
+            "UPDATE _blamejs_cache SET valueJson = ?, expiresAt = ?, updatedAt = ? " +
+            "WHERE cacheKey = ? AND valueJson = ?",
+            [json, storedExpires, now, ck, oldRaw]);
+          if (!upd || upd.rowCount !== 1) return { conflict: true };
+        }
+        return { updated: true, value: decision.value };
+      });
+      if (outcome && outcome.conflict) continue;   // value moved under us — retry
+      return outcome;
     }
+    throw _err("UPDATE_CONTENTION",
+      "cache.update: exceeded " + maxRetries + " retries under write contention for key");
   }
 
   async function del(key) {
@@ -672,6 +769,7 @@ function _clusterBackend(cfg) {
     name:           "cluster",
     get:            get,
     set:            set,
+    update:         _updateRow,
     del:            del,
     has:            has,
     clear:          clear,
@@ -1014,6 +1112,68 @@ function create(opts) {
     emitObs("cache.set", { namespace: namespace });
   }
 
+  /**
+   * @primitive b.cache.update
+   * @signature b.cache.update(key, mutatorFn, opts?)
+   * @since     0.13.39
+   * @status    stable
+   * @related   b.cache.create
+   *
+   * Atomic read-modify-write. Reads the current value, calls
+   * `mutatorFn(current | null)`, and commits the result in one operation
+   * so a concurrent writer cannot clobber the change (lost update) — the
+   * race that makes a plain `get` → mutate → `set` unsafe for counters,
+   * sets, and quorum state. The memory backend is atomic by single-thread;
+   * the cluster backend uses a transaction with compare-and-set + retry.
+   *
+   * `mutatorFn` returns one of: `{ value }` to commit the new value,
+   * `{ abort: data }` to leave the entry untouched and surface `data` to
+   * the caller, or `{ delete: true }` to remove the entry. The call
+   * resolves to `{ updated: true, value }`, `{ updated: true, deleted: true }`,
+   * or `{ aborted: data }`.
+   *
+   * @opts
+   *   ttlMs:  number | Infinity,   // lifetime of the written value; default the instance ttlMs
+   *   seal:   boolean,             // cluster backend only — seal the value at rest
+   *
+   * @example
+   *   await counters.update("hits", function (n) {
+   *     return { value: (n || 0) + 1 };
+   *   });
+   */
+  async function update(key, mutatorFn, callerOpts) {
+    _ensureOpen("update");
+    _validateKey(key, "cache.update");
+    if (typeof mutatorFn !== "function") {
+      throw _err("BAD_OPT", "cache.update: mutatorFn must be a function, got " + typeof mutatorFn);
+    }
+    if (typeof backend.update !== "function") {
+      throw _err("UNSUPPORTED",
+        "cache.update is unsupported by the '" + (backend.name || "custom") + "' backend " +
+        "(memory + cluster implement it; a custom backend must provide update for atomic RMW).");
+    }
+    var ttlMs = _resolveTtl(callerOpts, "update");
+    var expiresAt = (ttlMs === Infinity) ? Infinity : (clock() + ttlMs);
+    var seal = !!(callerOpts && callerOpts.seal === true);
+    if (seal && backend.name !== "cluster") {
+      throw _err("BAD_OPT",
+        "cache.update: seal: true is only supported on the cluster backend " +
+        "(this cache instance uses '" + (backend.name || "custom") + "').");
+    }
+    var result;
+    try { result = await backend.update(key, mutatorFn, expiresAt, { ttlMs: ttlMs, seal: seal }); }
+    catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "update" });
+      _backendFailedAudit("update", e);
+      throw e;
+    }
+    if (result && (result.updated || result.deleted)) {
+      emitObs("cache.update", { namespace: namespace });
+      if (result.deleted) { softExpiry.delete(key); _publishInvalidation({ kind: "del", key: key }); }
+    }
+    return result;
+  }
+
   async function del(key) {
     _ensureOpen("del");
     _validateKey(key, "cache.del");
@@ -1308,6 +1468,7 @@ function create(opts) {
   return {
     get:                    get,
     set:                    set,
+    update:                 update,
     del:                    del,
     has:                    has,
     clear:                  clear,

package/lib/cluster-storage.js

@@ -261,6 +261,33 @@ function placeholderize(sql, dialect) {
  *   );
  *   // → { rows: [ { counter: 43, row_hash: "..." } ], rowCount: 1 }
  */
+// Single-node transaction serialization. node:sqlite is synchronous and
+// the framework shares ONE local connection, so a SQLite transaction is
+// connection-global: any statement that runs between this connection's
+// BEGIN and COMMIT lands INSIDE the transaction. `_activeTx` is a promise
+// held for the duration of a single-node transaction(); execute() waits it
+// out before running so a concurrent statement can't interleave into the
+// open transaction on the shared connection. It is null in cluster mode
+// (the pool gives each transaction its own connection, so the DB enforces
+// isolation and no global lock is needed).
+var _activeTx = null;
+
+// Raw local exec — synchronous, no transaction-lock wait. Used by execute()
+// AFTER the lock wait and by transaction() for its own statements (which
+// must NOT wait on the lock they themselves hold). Because node:sqlite is
+// synchronous this runs atomically to completion with no interleaving.
+function _localExec(sql, params) {
+  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 };
+}
+
 async function execute(sql, params) {
   if (typeof sql !== "string") {
     throw new ClusterStorageError("sql must be a string", "cluster-storage/bad-arg");
@@ -275,17 +302,93 @@ async function execute(sql, params) {
     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 };
+  // Local SQLite path. Wait out any open single-node transaction so this
+  // statement can't interleave into it on the shared connection. The loop
+  // re-checks after each wait (a new transaction may have started while we
+  // waited); once it exits, `_localExec` runs synchronously to completion,
+  // so no transaction can begin between the check and the statement.
+  while (_activeTx) { try { await _activeTx; } catch (_e) { /* tx failed — proceed */ } }
+  return _localExec(sql, params);
+}
+
+/**
+ * @primitive b.clusterStorage.transaction
+ * @signature b.clusterStorage.transaction(fn)
+ * @since     0.13.38
+ * @status    stable
+ * @related   b.clusterStorage.execute
+ *
+ * Run `fn` inside an atomic transaction against the active backend, so a
+ * multi-statement read-modify-write commits all-or-nothing. `fn` receives a
+ * transaction handle exposing the same `execute` / `executeOne` /
+ * `executeAll` surface as the module — but scoped to the open transaction.
+ * Use the handle's methods inside `fn`; calling the module-level
+ * `b.clusterStorage.execute` from within `fn` would deadlock single-node
+ * (it waits for the very transaction `fn` is running).
+ *
+ * Cluster mode dispatches to the external DB's transaction (its own pooled
+ * connection + deadlock retry). Single-node serializes against other
+ * transactions and against `execute` on the shared SQLite connection.
+ *
+ * @example
+ *   await b.clusterStorage.transaction(async function (tx) {
+ *     var row = await tx.executeOne("SELECT v FROM t WHERE k = ?", ["x"]);
+ *     await tx.execute("UPDATE t SET v = ? WHERE k = ?", [row.v + 1, "x"]);
+ *   });
+ */
+async function transaction(fn) {
+  if (typeof fn !== "function") {
+    throw new ClusterStorageError("transaction requires a function", "cluster-storage/bad-arg");
+  }
+
+  if (cluster.isClusterMode()) {
+    var dialect = cluster.dialect();
+    return await externalDb.transaction(async function (txClient) {
+      function txExec(sql, params) {
+        var translated = placeholderize(resolveTables(sql), dialect);
+        return txClient.query(translated, params || []);
+      }
+      var txHandle = {
+        execute:    txExec,
+        executeOne: async function (sql, params) {
+          var r = await txExec(sql, params); return r.rows.length > 0 ? r.rows[0] : null;
+        },
+        executeAll: async function (sql, params) {
+          var r = await txExec(sql, params); return r.rows;
+        },
+      };
+      return await fn(txHandle);
+    }, { backend: cluster.externalDbBackend() });
+  }
+
+  // Single-node: serialize this transaction behind any other open one, then
+  // hold `_activeTx` so concurrent execute()/transaction() calls wait.
+  while (_activeTx) { try { await _activeTx; } catch (_e) { /* prior tx failed */ } }
+  var releaseTx;
+  _activeTx = new Promise(function (resolve) { releaseTx = resolve; });
+  function txExecLocal(sql, params) { return Promise.resolve(_localExec(sql, params)); }
+  var localHandle = {
+    execute:    txExecLocal,
+    executeOne: async function (sql, params) {
+      var r = await txExecLocal(sql, params); return r.rows.length > 0 ? r.rows[0] : null;
+    },
+    executeAll: async function (sql, params) {
+      var r = await txExecLocal(sql, params); return r.rows;
+    },
+  };
+  try {
+    _localExec("BEGIN", []);
+    try {
+      var result = await fn(localHandle);
+      _localExec("COMMIT", []);
+      return result;
+    } catch (e) {
+      try { _localExec("ROLLBACK", []); } catch (_e) { /* already errored */ }
+      throw e;
+    }
+  } finally {
+    var r = releaseTx; _activeTx = null; r();
   }
-  var info = stmt.run.apply(stmt, params);
-  return { rows: [], rowCount: info.changes };
 }
 
 // Convenience wrappers for the two common patterns.
@@ -344,6 +447,7 @@ module.exports = {
   execute:               execute,
   executeOne:            executeOne,
   executeAll:            executeAll,
+  transaction:           transaction,
   tableName:             tableName,
   resolveTables:         resolveTables,
   placeholderize:        placeholderize,

package/lib/dual-control.js

@@ -301,27 +301,27 @@ function create(opts) {
 
   async function cancel(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "cancel: args required");
-    var record = await _load(args.grantId);
-    if (!record) return { error: "grant-not-found", grantId: args.grantId };
-    if (record.consumedAt !== null) return { error: "grant-already-consumed", grantId: record.grantId };
-    if (record.revokedAt !== null)  return { error: "grant-revoked", grantId: record.grantId };
-    if (record.cancelledAt !== null) return { error: "grant-already-cancelled", grantId: record.grantId };
     var actorId = _actorIdOf(args.cancelledBy);
-    if (actorId !== record.requestedBy) {
-      // Cancellation by anyone other than the requester is a revoke,
-      // not a cancel. Surface explicitly.
-      return { error: "only-requester-can-cancel", grantId: record.grantId,
-        requestedBy: record.requestedBy };
-    }
-    record.cancelledAt = Date.now();
-    record.cancelledReason = args.reason || null;
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      if (record.revokedAt !== null)  return { abort: { response: { error: "grant-revoked", grantId: record.grantId } } };
+      if (record.cancelledAt !== null) return { abort: { response: { error: "grant-already-cancelled", grantId: record.grantId } } };
+      // Cancellation by anyone other than the requester is a revoke, not a
+      // cancel — surface explicitly.
+      if (actorId !== record.requestedBy) {
+        return { abort: { response: { error: "only-requester-can-cancel", grantId: record.grantId, requestedBy: record.requestedBy } } };
+      }
+      record.cancelledAt = Date.now();
+      record.cancelledReason = args.reason || null;
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+    if (outcome.aborted) return outcome.aborted.response;
+    var rec = outcome.value;
     _emit("dual.grant.cancelled",
-      { grantId: record.grantId, action: record.action,
-        cancelledBy: actorId, reason: args.reason || null },
+      { grantId: rec.grantId, action: rec.action, cancelledBy: actorId, reason: args.reason || null },
       "success", args.req);
-    return { grantId: record.grantId, status: "cancelled" };
+    return { grantId: rec.grantId, status: "cancelled" };
   }
 
   async function _load(grantId) {
@@ -334,156 +334,152 @@ function create(opts) {
 
   async function approve(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "approve: args required");
-    var record = await _load(args.grantId);
-    if (!record) {
-      return { error: "grant-not-found", grantId: args.grantId };
-    }
-    if (record.consumedAt !== null) {
-      return { error: "grant-already-consumed", grantId: record.grantId };
-    }
-    if (record.revokedAt !== null) {
-      return { error: "grant-revoked", grantId: record.grantId, revokedReason: record.revokedReason };
-    }
-    if (record.cancelledAt !== null) {
-      return { error: "grant-cancelled", grantId: record.grantId };
-    }
-    if (record.expiresAt < Date.now()) {
-      _emit("dual.grant.expired", { grantId: record.grantId, action: record.action },
-        "failure", args.req);
-      await cache.del(_key(record.grantId));
-      return { error: "grant-expired", grantId: record.grantId };
-    }
     var approverId = _actorIdOf(args.approver);
     if (!approverId) throw _err("BAD_ARG", "approve: args.approver must be an actor with a stable id");
-    if (forbidSelfApprove && approverId === record.requestedBy) {
-      _emit("dual.grant.self_approval_denied",
-        { grantId: record.grantId, action: record.action, approver: approverId },
-        "denied", args.req);
-      return { error: "self-approval-forbidden", grantId: record.grantId };
-    }
-    if (!_approverRoleOk(args.approver)) {
-      _emit("dual.grant.role_denied",
-        { grantId: record.grantId, action: record.action, approver: approverId,
-          requiredRoles: approverRoles,
-          actorRoles: (args.approver && Array.isArray(args.approver.roles)) ? args.approver.roles : [] },
-        "denied", args.req);
-      return { error: "approver-role-required", grantId: record.grantId,
-        requiredRoles: approverRoles };
-    }
-    if (record.approvedBy.indexOf(approverId) !== -1) {
-      return { error: "already-approved-by-this-actor", grantId: record.grantId,
-        approvedBy: record.approvedBy };
-    }
+    // Pre-compute the pure, record-independent checks so the mutator stays
+    // side-effect-free (it may re-run under cluster CAS contention).
+    var roleOk = _approverRoleOk(args.approver);
     var reasonProblem = _checkReason(args.reason, "approve");
-    if (reasonProblem) {
-      return Object.assign({ grantId: record.grantId }, reasonProblem);
-    }
-    record.approvedBy.push(approverId);
-    record.approvalsAt.push(Date.now());
-    record.approvalReasons.push(args.reason || null);
-    if (approverRoles && args.approver && Array.isArray(args.approver.roles)) {
-      // Record which of the required roles satisfied the approval —
-      // useful when an audit reviewer needs to confirm the actor
-      // approved as e.g. their security-officer role and not their
-      // engineer role.
-      var hits = args.approver.roles.filter(function (r) { return approverRoles.indexOf(r) !== -1; });
-      record.approverRoleHits.push(hits);
-    }
-    var status = "pending";
-    if (record.approvedBy.length >= record.minApprovers) {
-      status = "approved";
-      if (record.quorumReachedAt === null) record.quorumReachedAt = Date.now();
+    var roleHits = (approverRoles && args.approver && Array.isArray(args.approver.roles))
+      ? args.approver.roles.filter(function (r) { return approverRoles.indexOf(r) !== -1; })
+      : null;
+
+    // Atomic read-modify-write: the duplicate-approver guard and the
+    // approvedBy append commit together, so two concurrent approvals (or a
+    // retried one) cannot each read a stale snapshot and append the same
+    // approver twice — the quorum-bypass the get/set version allowed.
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      if (record.revokedAt !== null) return { abort: { response: { error: "grant-revoked", grantId: record.grantId, revokedReason: record.revokedReason } } };
+      if (record.cancelledAt !== null) return { abort: { response: { error: "grant-cancelled", grantId: record.grantId } } };
+      if (record.expiresAt < Date.now()) {
+        return { abort: { response: { error: "grant-expired", grantId: record.grantId },
+          event: "dual.grant.expired", meta: { grantId: record.grantId, action: record.action }, outcome: "failure" } };
+      }
+      if (forbidSelfApprove && approverId === record.requestedBy) {
+        return { abort: { response: { error: "self-approval-forbidden", grantId: record.grantId },
+          event: "dual.grant.self_approval_denied",
+          meta: { grantId: record.grantId, action: record.action, approver: approverId }, outcome: "denied" } };
+      }
+      if (!roleOk) {
+        return { abort: { response: { error: "approver-role-required", grantId: record.grantId, requiredRoles: approverRoles },
+          event: "dual.grant.role_denied",
+          meta: { grantId: record.grantId, action: record.action, approver: approverId, requiredRoles: approverRoles,
+            actorRoles: (args.approver && Array.isArray(args.approver.roles)) ? args.approver.roles : [] }, outcome: "denied" } };
+      }
+      if (record.approvedBy.indexOf(approverId) !== -1) {
+        return { abort: { response: { error: "already-approved-by-this-actor", grantId: record.grantId, approvedBy: record.approvedBy.slice() } } };
+      }
+      if (reasonProblem) return { abort: { response: Object.assign({ grantId: record.grantId }, reasonProblem) } };
+      record.approvedBy.push(approverId);
+      record.approvalsAt.push(Date.now());
+      record.approvalReasons.push(args.reason || null);
+      // Record which required role satisfied the approval — an audit
+      // reviewer can confirm the actor approved as e.g. security-officer.
+      if (roleHits) record.approverRoleHits.push(roleHits);
+      if (record.approvedBy.length >= record.minApprovers && record.quorumReachedAt === null) {
+        record.quorumReachedAt = Date.now();
+      }
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+
+    if (outcome.aborted) {
+      var ab = outcome.aborted;
+      if (ab.event) _emit(ab.event, ab.meta, ab.outcome, args.req);
+      return ab.response;
     }
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var rec = outcome.value;
+    var status = (rec.approvedBy.length >= rec.minApprovers) ? "approved" : "pending";
+    var consumeUnlockAt = rec.quorumReachedAt !== null ? rec.quorumReachedAt + rec.consumeLockMs : null;
     _emit("dual.grant.approved",
-      { grantId: record.grantId, action: record.action, approver: approverId,
-        approverCount: record.approvedBy.length, needs: record.minApprovers,
-        status: status, reason: args.reason || null,
-        consumeUnlockAt: record.quorumReachedAt !== null
-          ? record.quorumReachedAt + record.consumeLockMs : null },
+      { grantId: rec.grantId, action: rec.action, approver: approverId,
+        approverCount: rec.approvedBy.length, needs: rec.minApprovers,
+        status: status, reason: args.reason || null, consumeUnlockAt: consumeUnlockAt },
       "success", args.req);
     return {
-      grantId:    record.grantId,
+      grantId:    rec.grantId,
       status:     status,
-      approvedBy: record.approvedBy.slice(),
-      needs:      record.minApprovers,
-      expiresAt:  record.expiresAt,
-      consumeUnlockAt: record.quorumReachedAt !== null
-        ? record.quorumReachedAt + record.consumeLockMs : null,
+      approvedBy: rec.approvedBy.slice(),
+      needs:      rec.minApprovers,
+      expiresAt:  rec.expiresAt,
+      consumeUnlockAt: consumeUnlockAt,
     };
   }
 
   async function revoke(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "revoke: args required");
-    var record = await _load(args.grantId);
-    if (!record) return { error: "grant-not-found", grantId: args.grantId };
-    if (record.consumedAt !== null) {
-      return { error: "grant-already-consumed", grantId: record.grantId };
-    }
-    record.revokedAt = Date.now();
-    record.revokedReason = args.reason || null;
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var revokedById = _actorIdOf(args.revokedBy);
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      record.revokedAt = Date.now();
+      record.revokedReason = args.reason || null;
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+    if (outcome.aborted) return outcome.aborted.response;
+    var rec = outcome.value;
     _emit("dual.grant.denied",
-      { grantId: record.grantId, action: record.action,
-        revokedBy: _actorIdOf(args.revokedBy), reason: args.reason || null },
+      { grantId: rec.grantId, action: rec.action, revokedBy: revokedById, reason: args.reason || null },
       "denied", args.req);
-    return { grantId: record.grantId, status: "revoked" };
+    return { grantId: rec.grantId, status: "revoked" };
   }
 
   async function consume(grantId, args) {
     args = args || {};
-    var record = await _load(grantId);
-    if (!record) return { ready: false, reason: "grant-not-found" };
-    if (record.revokedAt !== null) {
-      return { ready: false, reason: "revoked" };
-    }
-    if (record.cancelledAt !== null) {
-      return { ready: false, reason: "cancelled" };
-    }
-    if (record.consumedAt !== null) {
-      return { ready: false, reason: "already-consumed" };
-    }
-    if (record.expiresAt < Date.now()) {
-      _emit("dual.grant.expired", { grantId: record.grantId, action: record.action },
-        "failure", args.req);
-      await cache.del(_key(record.grantId));
-      return { ready: false, reason: "expired" };
-    }
-    if (record.approvedBy.length < record.minApprovers) {
-      return { ready: false, reason: "not-enough-approvers",
-        approvedBy: record.approvedBy.slice(), needs: record.minApprovers };
-    }
-    // Cooling-off lock: ANY approval-quorum-reached grant can't consume
-    // until consumeLockMs has passed since the final approval. Defends
-    // against rapid-burst compromise of requester+approver.
-    if ((record.consumeLockMs || 0) > 0 && record.quorumReachedAt !== null) {
-      var unlockAt = record.quorumReachedAt + record.consumeLockMs;
-      if (Date.now() < unlockAt) {
-        _emit("dual.grant.consume_locked",
-          { grantId: record.grantId, action: record.action,
-            unlockAt: unlockAt, waitMs: unlockAt - Date.now() },
-          "denied", args.req);
-        return { ready: false, reason: "consume-locked", unlockAt: unlockAt,
-          waitMs: unlockAt - Date.now() };
+    // Atomic read-modify-write: the consumedAt check and the consumedAt set
+    // commit together (compare-and-set), so two concurrent consumes cannot
+    // both observe consumedAt === null and both proceed — exactly one wins
+    // and runs the destructive operation. The get/set version let a
+    // single-use grant be consumed twice.
+    var outcome = await cache.update(_key(grantId), function (record) {
+      if (!record) return { abort: { response: { ready: false, reason: "grant-not-found" } } };
+      if (record.revokedAt !== null) return { abort: { response: { ready: false, reason: "revoked" } } };
+      if (record.cancelledAt !== null) return { abort: { response: { ready: false, reason: "cancelled" } } };
+      if (record.consumedAt !== null) return { abort: { response: { ready: false, reason: "already-consumed" } } };
+      if (record.expiresAt < Date.now()) {
+        return { abort: { response: { ready: false, reason: "expired" }, del: true,
+          event: "dual.grant.expired", meta: { grantId: record.grantId, action: record.action }, outcome: "failure" } };
       }
+      if (record.approvedBy.length < record.minApprovers) {
+        return { abort: { response: { ready: false, reason: "not-enough-approvers",
+          approvedBy: record.approvedBy.slice(), needs: record.minApprovers } } };
+      }
+      // Cooling-off lock: a quorum-reached grant can't consume until
+      // consumeLockMs has passed since the final approval — defends against
+      // rapid-burst compromise of requester + approver.
+      if ((record.consumeLockMs || 0) > 0 && record.quorumReachedAt !== null) {
+        var unlockAt = record.quorumReachedAt + record.consumeLockMs;
+        if (Date.now() < unlockAt) {
+          return { abort: { response: { ready: false, reason: "consume-locked", unlockAt: unlockAt, waitMs: unlockAt - Date.now() },
+            event: "dual.grant.consume_locked",
+            meta: { grantId: record.grantId, action: record.action, unlockAt: unlockAt, waitMs: unlockAt - Date.now() }, outcome: "denied" } };
+        }
+      }
+      record.consumedAt = Date.now();
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+
+    if (outcome.aborted) {
+      var ab = outcome.aborted;
+      if (ab.event) _emit(ab.event, ab.meta, ab.outcome, args.req);
+      if (ab.del) { try { await cache.del(_key(grantId)); } catch (_e) { /* sweep handles it */ } }
+      return ab.response;
     }
-    record.consumedAt = Date.now();
-    // Drop the grant from the cache after consume — single-use by design.
-    await cache.del(_key(record.grantId));
+    var rec = outcome.value;
+    // Single-use by design — drop the (now consumed) grant from the cache.
+    await cache.del(_key(rec.grantId));
     _emit("dual.grant.consumed",
-      { grantId: record.grantId, action: record.action,
-        approvedBy: record.approvedBy.slice(),
-        approvalReasons: record.approvalReasons.slice() },
+      { grantId: rec.grantId, action: rec.action,
+        approvedBy: rec.approvedBy.slice(), approvalReasons: rec.approvalReasons.slice() },
       "success", args.req);
     return {
       ready:      true,
-      grantId:    record.grantId,
-      action:     record.action,
-      resource:   record.resource,
-      approvedBy: record.approvedBy.slice(),
-      requestedBy:record.requestedBy,
+      grantId:    rec.grantId,
+      action:     rec.action,
+      resource:   rec.resource,
+      approvedBy: rec.approvedBy.slice(),
+      requestedBy:rec.requestedBy,
     };
   }
 

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:67acf3f3-dbcf-463e-a7d2-58115594e0d6",
+  "serialNumber": "urn:uuid:8c1e3aad-b831-4d99-b528-7ca57a3a6ba3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T14:52:03.887Z",
+    "timestamp": "2026-05-29T17:14:11.141Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.37",
+      "bom-ref": "@blamejs/core@0.13.39",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.37",
+      "version": "0.13.39",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.37",
+      "purl": "pkg:npm/%40blamejs/core@0.13.39",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.37",
+      "ref": "@blamejs/core@0.13.39",
       "dependsOn": []
     }
   ]