@blamejs/core 0.13.36 → 0.13.38

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.13.35 (2026-05-29) — **In-memory replay, idempotency, DNS, and i18n stores gain entry-count ceilings.** Several framework caches keyed on request-influenced input grew without an upper bound between their periodic sweeps, so a flood of unique keys could exhaust process memory faster than the sweep reclaimed it. Each now enforces a hard entry ceiling. The replay-protection nonce store is the security-sensitive one: rather than evict a live nonce to admit a new one — which would reopen a replay window for the evicted nonce — it purges expired entries and then fails closed at capacity, refusing the unrecordable request instead of admitting it unprotected. The idempotency, DNS, and i18n caches hold re-derivable values, so they evict the oldest entry instead (the worst case is a recomputed value or a single re-executed retry under flood). Ceilings are generous defaults that normal traffic never reaches; the nonce store and the agent idempotency in-memory backend expose options to tune them. **Fixed:** *Agent idempotency in-memory backend no longer grows without bound* — The default in-memory backend for `b.agent.idempotency` is keyed on the request-supplied idempotency key, and its garbage collector only reclaims expired rows when an operator wires a scheduler to call it — so a flood of distinct keys could grow it until the process ran out of memory. It now caps its entry count and evicts oldest-first; a dropped record just means that one key re-executes on a later retry, never a crash. A new `maxInMemoryEntries` option tunes the ceiling (default 100,000); deployments needing a hard guarantee at scale still supply a durable `store`. · *DNS resolver cache is bounded* — The positive and negative resolver caches in `b.network.dns` reclaimed an expired entry only when the same hostname was looked up again, so entries for never-requeried hostnames persisted — and hostnames reaching the resolver are request-influenced (outbound request targets, mail MX lookups). Both caches now cap their entry count and evict oldest-first; DNS simply re-resolves on the next miss. · *i18n formatter cache is bounded* — Per-instance `Intl` formatter caches in `b.i18n` are keyed on the locale plus a hash of the format options. The format-options shape is open-ended and caller-supplied, so the key space was request-influenced and uncapped. The cache now enforces an entry ceiling and evicts oldest-first — a formatter is pure-derived and re-created on the next miss. **Security:** *Replay-nonce store bounds memory and fails closed under a nonce flood* — The in-memory `b.nonceStore` backend recorded every request-supplied nonce until a periodic sweep ran, so a stream of unique nonces could exhaust memory between sweeps (a memory-amplification denial of service). It now caps its entry count. Because a replay-protection store must never evict a live nonce to make room — doing so would reopen a replay window for the evicted nonce — it instead purges expired entries inline and, if still at capacity with live nonces, fails closed: the new request is refused rather than admitted without replay protection. A new `maxEntries` option tunes the ceiling (default 1,000,000).

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/lib/db.js

@@ -132,6 +132,16 @@ var encPath   = null;       // encrypted-at-rest path (null in plain mode)
 var encKey    = null;       // DB encryption key buffer (null in plain mode)
 var encTimer  = null;       // periodic encrypt interval handle
 var atRest    = null;       // 'encrypted' or 'plain'
+// Tmpfs free-space guard (encrypted mode). The working copy lives on a
+// bounded tmpfs (Docker /dev/shm defaults to 64 MiB); if it fills, SQLite
+// hits ENOSPC and corrupts the working copy. A periodic probe refuses
+// growth writes (INSERT/UPDATE/REPLACE) before that happens — fail-clear
+// instead of corrupt-then-recover. DELETE + reads stay available so
+// retention can reclaim space and the app can keep serving.
+var storageProbeTimer = null;  // periodic free-space probe handle
+var writesRefused = false;     // true when free space < minFreeBytes
+var minFreeBytes  = 0;         // refuse growth writes below this (0 = guard off)
+var statfsProbe   = null;      // free-space reader (fs.statfsSync; injectable for tests)
 var dataDir   = null;
 var initialized = false;
 var dataResidency = null;   // operator's declared region config (validated by storage backends)
@@ -737,6 +747,66 @@ function _dbEncAad(dir) {
   return Buffer.from("blamejs.db-enc.v1\0" + (dir || ""), "utf8");
 }
 
+// Probe free space on the tmpfs holding the working copy and flip the
+// write-refusal flag. Encrypted mode only (the bounded-tmpfs surface);
+// guard disabled when minFreeBytes is 0. A probe failure leaves the flag
+// unchanged — we never refuse writes on a stat error (that would be a
+// self-inflicted outage). Growth writes (INSERT/UPDATE/REPLACE) are gated
+// by the prepare() wrapper installed in init(); DELETE + reads always pass
+// so retention can reclaim space and the app keeps serving.
+function _probeStorageHeadroom() {
+  if (atRest !== "encrypted" || !minFreeBytes || !dbPath || !statfsProbe) return;
+  var free;
+  try {
+    var st = statfsProbe(nodePath.dirname(dbPath));
+    free = st.bavail * st.bsize;
+    if (!isFinite(free)) return;
+  } catch (_e) { return; }
+  if (free < minFreeBytes && !writesRefused) {
+    writesRefused = true;
+    log.error("storage low: " + free + " bytes free on the tmpfs working-copy mount (< " +
+      minFreeBytes + ") — refusing growth writes (INSERT/UPDATE/REPLACE) until space " +
+      "recovers. Raise shm_size / --shm-size, or let retention prune. DELETE + reads still serve.");
+    try {
+      audit.safeEmit({ action: "db.storage.low", outcome: "failure",
+        metadata: { freeBytes: free, minFreeBytes: minFreeBytes } });
+    } catch (_e2) { /* drop-silent — observability */ }
+  } else if (free >= minFreeBytes && writesRefused) {
+    writesRefused = false;
+    log("storage recovered: " + free + " bytes free — growth writes re-enabled");
+    try {
+      audit.safeEmit({ action: "db.storage.recovered", outcome: "success",
+        metadata: { freeBytes: free } });
+    } catch (_e3) { /* drop-silent */ }
+  }
+}
+
+// Install the growth-write gate on the SQLite handle: shadow prepare() so
+// INSERT/UPDATE/REPLACE statements throw db/storage-low when the tmpfs is
+// critically low, instead of proceeding into an ENOSPC corruption. Reads,
+// DELETE, PRAGMA, and DDL pass through ungated. Called once in init() after
+// schema setup so init's own writes are never gated (writesRefused is false
+// until the first probe anyway).
+function _installWriteGate() {
+  var rawPrepare = database.prepare.bind(database);
+  database.prepare = function (sql) {
+    var stmt = rawPrepare(sql);
+    if (/^\s*(?:INSERT|UPDATE|REPLACE)\b/i.test(sql)) {
+      var rawRun = stmt.run.bind(stmt);
+      stmt.run = function () {
+        if (writesRefused) {
+          throw _dbErr("db/storage-low",
+            "db: refusing write — the encrypted-mode working copy is on a tmpfs with less than " +
+            minFreeBytes + " bytes free (Docker /dev/shm defaults to 64 MiB). Raise shm_size / " +
+            "--shm-size, or let retention prune expired rows. DELETE and reads remain available.");
+        }
+        return rawRun.apply(stmt, arguments);
+      };
+    }
+    return stmt;
+  };
+}
+
 function encryptToDisk() {
   if (!encPath) return;
   // Force WAL checkpoint so the .db file holds all committed transactions.
@@ -915,11 +985,11 @@ async function init(opts) {
     if (!nodeFs.existsSync(tmpDir)) nodeFs.mkdirSync(tmpDir, { recursive: true });
 
     // D-H7 — if the resolved tmpDir is NOT actually tmpfs, the
-    // plaintext DB file lives on persistent storage. statvfs/statfs
-    // isn't in stable Node, but on Linux we can check that tmpDir
-    // resolves under /dev/shm or /run/shm as a heuristic. On other
+    // plaintext DB file lives on persistent storage. We check that tmpDir
+    // resolves under /dev/shm or /run/shm on Linux as a heuristic; on other
     // platforms we warn that the operator must verify tmpfs binding
-    // out-of-band.
+    // out-of-band. (Free-space headroom is enforced separately via
+    // fs.statfsSync in the storage guard below.)
     if (process.platform === "linux") {
       var realTmp = "";
       try { realTmp = nodeFs.realpathSync(tmpDir); } catch (_e) { /* stat best-effort */ }
@@ -941,6 +1011,21 @@ async function init(opts) {
     dbPath  = nodePath.join(tmpDir, "blamejs-" + generateToken(C.BYTES.bytes(16)) + ".db");
     encKey  = loadOrCreateDbKey(dataDir, opts.dbKeyPath);
 
+    // Tmpfs free-space guard. Default headroom is 16 MiB below which growth
+    // writes are refused (fail-clear) before the working copy fills its
+    // bounded tmpfs and corrupts. opts.minFreeBytes tunes it; 0 disables.
+    // opts._statfsForTest injects a free-space reader for tests.
+    if (opts.minFreeBytes !== undefined) {
+      require("./numeric-bounds").requireNonNegativeFiniteIntIfPresent(
+        opts.minFreeBytes, "db.init: opts.minFreeBytes", DbError, "db/bad-min-free-bytes");
+      minFreeBytes = opts.minFreeBytes;
+    } else {
+      minFreeBytes = C.BYTES.mib(16);
+    }
+    statfsProbe = typeof opts._statfsForTest === "function"
+      ? opts._statfsForTest
+      : (typeof nodeFs.statfsSync === "function" ? nodeFs.statfsSync : null);
+
     cleanStaleTmpDbs(tmpDir);
     decryptToTmp();
   } else {
@@ -1337,6 +1422,18 @@ async function init(opts) {
       }
     }, C.TIME.minutes(5), { name: "db-periodic-encrypt" });
 
+    // Tmpfs free-space guard. Install the growth-write gate now (after all
+    // of init's own writes), then probe on a short interval so the
+    // refuse-writes flag tracks a fast-filling tmpfs (the 5-minute encrypt
+    // cadence is far too coarse to catch a fill in time). The guard is a
+    // no-op when minFreeBytes is 0 or no statfs reader is available.
+    if (minFreeBytes && statfsProbe) {
+      _installWriteGate();
+      _probeStorageHeadroom();   // seed the flag from current free space
+      storageProbeTimer = safeAsync.repeating(_probeStorageHeadroom,
+        C.TIME.seconds(10), { name: "db-storage-probe" });
+    }
+
     // Final encrypt on process exit. We don't try to unlink the plaintext
     // here — the SQLite handle may still be open, and the OS reclaims tmpfs
     // on reboot anyway. close() does the orderly shutdown.
@@ -1979,6 +2076,11 @@ function close() {
     encTimer.stop();
     encTimer = null;
   }
+  if (storageProbeTimer) {
+    storageProbeTimer.stop();
+    storageProbeTimer = null;
+  }
+  writesRefused = false;
   // Drop prepared-statement cache so the underlying Statement handles
   // release ahead of database.close().
   _prepareCache.clear();
@@ -2503,6 +2605,7 @@ function _cascadeStep(name, ref) {
 // Test helpers — not part of public contract
 function _resetForTest() {
   if (encTimer) { encTimer.stop(); encTimer = null; }
+  if (storageProbeTimer) { storageProbeTimer.stop(); storageProbeTimer = null; }
   try { if (database) database.close(); }
   catch (e) { log.debug("test-reset close failed", { error: e.message }); }
   database = null;
@@ -2511,10 +2614,20 @@ function _resetForTest() {
   encKey = null;
   atRest = null;
   dataDir = null;
+  minFreeBytes = 0;
+  statfsProbe = null;
+  writesRefused = false;
   initialized = false;
   cryptoField.clearForTest();
 }
 
+// Test seam — force a storage-headroom probe synchronously (the production
+// path runs it on a 10s timer) and read the resulting refuse-writes flag.
+function _probeStorageForTest() {
+  _probeStorageHeadroom();
+  return { writesRefused: writesRefused, minFreeBytes: minFreeBytes };
+}
+
 
 /**
  * @primitive b.db.vacuumAfterErase
@@ -3165,6 +3278,8 @@ module.exports = {
     _cascadeStep("redact",      _resetRedact);
     _cascadeStep("external-db", _resetExternalDb);
   },
+  // Test seam for the tmpfs free-space guard — force a probe + read the flag.
+  _probeStorageForTest: _probeStorageForTest,
   // Helper for audit.checkpoint to write the rollback-detection sidecar
   _writeAuditTip: function (tip) {
     if (!dataDir) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.36",
+  "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:dcd20559-66bc-408f-8990-fd2eda10f240",
+  "serialNumber": "urn:uuid:fc7082b3-a639-421e-8e57-fac70e7ced00",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T13:55:36.439Z",
+    "timestamp": "2026-05-29T16:34:17.392Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.36",
+      "bom-ref": "@blamejs/core@0.13.38",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.36",
+      "version": "0.13.38",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.36",
+      "purl": "pkg:npm/%40blamejs/core@0.13.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.36",
+      "ref": "@blamejs/core@0.13.38",
       "dependsOn": []
     }
   ]