@blamejs/core 0.13.37 → 0.13.38

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- 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

@@ -511,32 +511,41 @@ 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]]
+          );
+        }
       }
-    }
+    });
   }
 
   async function del(key) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.37",
+  "version": "0.13.38",
   "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:fc7082b3-a639-421e-8e57-fac70e7ced00",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T14:52:03.887Z",
+    "timestamp": "2026-05-29T16:34:17.392Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.37",
+      "bom-ref": "@blamejs/core@0.13.38",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.37",
+      "version": "0.13.38",
       "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.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.37",
+      "ref": "@blamejs/core@0.13.38",
       "dependsOn": []
     }
   ]