@blamejs/blamejs-shop 0.2.15 → 0.2.18

package/lib/vendor/blamejs/examples/wiki/docker-compose.prod.yml

@@ -53,6 +53,34 @@ services:
     ports: !override []
     expose:
       - "3008"
+    # Encrypted-at-rest mode (WIKI_DB_AT_REST=encrypted) keeps the live
+    # SQLite working copy in a tmpfs (BLAMEJS_TMPDIR=/dev/shm below);
+    # plaintext only ever touches RAM. Docker's default /dev/shm is just
+    # 64 MiB, which the DB outgrows over time (append-only audit chain,
+    # sessions) — and a tmpfs overflow truncates the working copy mid-
+    # write, surfacing as "database disk image is malformed" on the next
+    # boot. Give it real headroom.
+    shm_size: '512m'
+    # Persist the encrypted-at-rest copy (db.enc) + sealed keys so they
+    # survive `docker rm`, host reboot, and image redeploys, and give a
+    # restore point. Without a volume, /data lives in the container's
+    # writable layer and is destroyed on every recreate — a corrupt boot
+    # then has nothing to roll back to.
+    volumes:
+      - wiki-data:/data
+    # Stop grace must exceed the app's 30s shutdown budget (graceMs) plus
+    # the forced-exit watchdog margin, so a `docker stop` / rolling redeploy
+    # lets the DB re-encrypt phase finish before SIGKILL — otherwise the
+    # final flush is lost and the next boot rolls back to the prior db.enc
+    # snapshot. (Inherited from the base compose; restated here because the
+    # data-loss risk is highest in encrypted mode.)
+    stop_grace_period: 40s
+    # NOTE for PaaS platforms (Coolify, Dokku, CapRover, …) that
+    # regenerate this compose file on deploy: set the above via the platform
+    # UI instead of hand-editing here — a "Persistent Storage" mount for
+    # /data, a custom docker run option `--shm-size 512m`, and a stop grace
+    # period of at least 40s. Edits to this file are otherwise overwritten
+    # on the next deploy.
     # Full operator-facing environment surface. Every value is
     # overridable from the .env file; defaults match the framework's
     # built-in defaults so an operator who just wants the basics can
@@ -227,5 +255,6 @@ services:
         condition: service_healthy
 
 volumes:
+  wiki-data:        # encrypted-at-rest DB (db.enc) + sealed keys — persistent, survives recreate/redeploy
   caddy-data:
   caddy-config:

package/lib/vendor/blamejs/examples/wiki/docker-compose.yml

@@ -17,6 +17,13 @@ services:
     image: blamejs-wiki:0.11.45
     container_name: blamejs-wiki
     restart: unless-stopped
+    # Graceful-shutdown budget. The app's shutdown orchestrator runs its
+    # phases within a 30s grace (graceMs) — drain in-flight, close the HTTP
+    # server, then the DB phase that WAL-checkpoints and (in encrypted mode)
+    # re-encrypts to db.enc. Docker's default 10s stop grace SIGKILLs before
+    # the DB phase gets to run, losing the final flush. Allow more than
+    # graceMs plus the forced-exit watchdog margin.
+    stop_grace_period: 40s
     ports:
       - "3008:3008"
     environment:

package/lib/vendor/blamejs/lib/agent-idempotency.js

@@ -68,6 +68,16 @@ var bCrypto           = require("./crypto");
 var safeJson          = require("./safe-json");
 var guardIdempotencyKey = require("./guard-idempotency-key");
 var agentAudit        = require("./agent-audit");
+var { boundedMap }    = require("./bounded-map");
+
+// The default in-memory backend is keyed on (method, actorId, keyHash) —
+// the key hash comes from request-supplied idempotency keys, so a flood of
+// distinct keys would grow the Map without bound (gc only reclaims EXPIRED
+// rows, and only if the operator wires a scheduler to call it). Cap it.
+// Evict-oldest degrades gracefully under flood: the worst case is a dropped
+// dedup record, so a retry of that one key re-executes — never an OOM.
+// Operators who need a hard guarantee at scale supply a durable `opts.store`.
+var DEFAULT_IN_MEMORY_MAX_ENTRIES = 100000;
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 var cryptoField       = lazyRequire(function () { return require("./crypto-field"); });
@@ -130,7 +140,7 @@ function _ensureSealTable() {
  */
 function create(opts) {
   opts = opts || {};
-  var store = opts.store || _inMemoryBackend();
+  var store = opts.store || _inMemoryBackend(opts.maxInMemoryEntries);
   if (typeof store.get !== "function" || typeof store.put !== "function" ||
       typeof store.delete !== "function") {
     throw new AgentIdempotencyError("agent-idempotency/bad-store",
@@ -470,8 +480,10 @@ function _checkArgs(method, actorId, key) {
   // key is validated separately via guardIdempotencyKey.validate.
 }
 
-function _inMemoryBackend() {
-  var map = new Map();
+function _inMemoryBackend(maxEntries) {
+  // boundedMap validates maxEntries (throws bounded-map/bad-max-entries on a
+  // non-positive-int); undefined falls back to the default ceiling.
+  var map = boundedMap({ maxEntries: maxEntries || DEFAULT_IN_MEMORY_MAX_ENTRIES, policy: "evict-oldest" });
   function _k(method, actorId, hash) { return method + "\0" + actorId + "\0" + hash; }
   return {
     get:    function (method, actorId, hash) {

package/lib/vendor/blamejs/lib/agent-orchestrator.js

@@ -64,6 +64,7 @@ var cluster           = lazyRequire(function () { return require("./cluster"); }
 var vault             = lazyRequire(function () { return require("./vault"); });
 var cryptoField       = lazyRequire(function () { return require("./crypto-field"); });
 var safeJson          = require("./safe-json");
+var agentTenant       = lazyRequire(function () { return require("./agent-tenant"); });
 
 var AgentOrchestratorError = defineClass("AgentOrchestratorError", { alwaysPermanent: true });
 
@@ -168,6 +169,12 @@ function create(opts) {
     cluster:     clusterImpl,
     audit:       auditImpl,
     permissions: permissions,
+    // When true, registry reads (list / lookup) are scoped to the actor's
+    // tenant — an actor only sees / resolves agents in its own tenant
+    // unless it holds the cross-tenant-admin scope. Mirrors the tenant
+    // scoping agent-event-bus enforces on subscribe / delivery. Off by
+    // default (single-tenant deployments are unaffected).
+    tenantScope: opts.tenantScope === true,
     spawnedConsumers: [],
     streams:     new Map(),
     elections:   new Map(),
@@ -358,6 +365,19 @@ async function _unregister(ctx, name, args) {
 async function _lookup(ctx, name, args) {
   guardAgentRegistry.validate({ kind: "lookup", name: name }, {});
   _checkPermission(ctx, args.actor, "agent-registry:read");
+  // Tenant-scope gate: the row's declared tenant gates access even to a
+  // live in-process ref, so an actor can't acquire a handle to another
+  // tenant's agent. Consult the backend row (it exists as a metadata
+  // declaration even where a live ref is hydrated).
+  if (ctx.tenantScope) {
+    var sealedRow = await ctx.backend.get(name);
+    var declRow = sealedRow ? _unsealRegistryRow(sealedRow) : null;
+    if (declRow && !_tenantAllows(ctx, args.actor, declRow.tenantId)) {
+      _safeAudit(ctx, "agent.orchestrator.lookup_denied", args.actor,
+        { name: name, reason: "cross-tenant" });
+      return null;
+    }
+  }
   // Live agent ref lives in-process; the backend row exists only as
   // a metadata declaration. In multi-process deployments each process
   // hydrates its own liveAgents map by calling register() locally.
@@ -383,6 +403,10 @@ async function _list(ctx, args) {
   return rows.filter(function (r) {
     if (args.kind && r.kind !== args.kind) return false;
     if (args.tenantId && r.tenantId !== args.tenantId) return false;
+    // Tenant-scope gate: drop rows the actor's tenant may not see, so
+    // enumeration can't disclose other tenants' agents. The args.tenantId
+    // above is a caller-supplied FILTER, not an authorization boundary.
+    if (!_tenantAllows(ctx, args.actor, r.tenantId)) return false;
     return true;
   }).map(function (r) {
     return {
@@ -753,6 +777,21 @@ function _checkPermission(ctx, actor, scope) {
   }
 }
 
+// Tenant-scope gate for registry reads. Returns true when the actor may
+// see / resolve an agent row in `rowTenantId`: scoping disabled, the actor
+// holds the cross-tenant-admin scope, or the actor's tenant matches the
+// row's. Mirrors agent-tenant's CROSS_TENANT_ADMIN_SCOPE check so registry
+// enumeration can't leak agents (or hand out live refs) across tenants.
+function _tenantAllows(ctx, actor, rowTenantId) {
+  if (!ctx.tenantScope) return true;
+  if (ctx.permissions && actor &&
+      ctx.permissions.check(actor, agentTenant().CROSS_TENANT_ADMIN_SCOPE)) {
+    return true;
+  }
+  var actorTenant = (actor && actor.tenantId) || null;
+  return actorTenant !== null && actorTenant === (rowTenantId || null);
+}
+
 function _safeAudit(ctx, action, actor, metadata) {
   agentAudit.safeAudit(ctx.audit, action, actor, metadata);
 }

package/lib/vendor/blamejs/lib/app-shutdown.js

@@ -53,6 +53,10 @@ var AppShutdownError = defineClass("AppShutdownError", { alwaysPermanent: true }
 var log = boot("app-shutdown");
 
 var DEFAULT_GRACE_MS = C.TIME.seconds(30);
+// Headroom between the shutdown grace budget and the hard forced-exit
+// watchdog, so the watchdog fires before a container supervisor's own
+// stop-grace SIGKILL (set stop_grace_period > graceMs + this margin).
+var FORCE_EXIT_MARGIN_MS = C.TIME.seconds(5);
 
 /**
  * @primitive b.appShutdown.create
@@ -71,6 +75,7 @@ var DEFAULT_GRACE_MS = C.TIME.seconds(30);
  *
  * @opts
  *   graceMs:               number,    // total budget across all phases (default 30000)
+ *   forceExitMarginMs:     number,    // headroom after graceMs before the signal-handler watchdog forces exit (default 5000); set the container stop grace above graceMs + this
  *   phases:                array,     // [{ name, run: async fn, timeoutMs? }]
  *   installSignalHandlers: boolean,   // wire SIGTERM/SIGINT (default false)
  *   signals:               array,     // signal names (default ["SIGTERM","SIGINT"])
@@ -94,6 +99,9 @@ function create(opts) {
   numericBounds.requirePositiveFiniteIntIfPresent(opts.graceMs,
     "app-shutdown.create: opts.graceMs", AppShutdownError, "app-shutdown/bad-grace-ms");
   var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.forceExitMarginMs,
+    "app-shutdown.create: opts.forceExitMarginMs", AppShutdownError, "app-shutdown/bad-force-exit-margin-ms");
+  var forceExitMarginMs = opts.forceExitMarginMs !== undefined ? opts.forceExitMarginMs : FORCE_EXIT_MARGIN_MS;
   var phases = Array.isArray(opts.phases) ? opts.phases.slice() : [];
   var installSignalHandlers = !!opts.installSignalHandlers;
   for (var i = 0; i < phases.length; i++) {
@@ -224,6 +232,30 @@ function create(opts) {
   function _signalCallback(sig) {
     return function () {
       log("received " + sig + " — initiating graceful shutdown");
+      // Hard-deadline safety net. Per-phase budgets use a SOFT timeout
+      // (withTimeout lets the underlying work keep running on expiry), so
+      // shutdown() RESOLVING does not guarantee the process EXITS: a hung
+      // phase's leaked handle (a socket that won't close, a timer that keeps
+      // firing) can hold the event loop alive past the grace window, after
+      // which the supervisor SIGKILLs us and the final DB re-encrypt is lost.
+      // Arm an unref'd watchdog that forces a clean exit at the deadline.
+      // It is deliberately NOT cleared when shutdown() resolves — the whole
+      // point is to catch the case where the orchestration finished but the
+      // process won't die. unref() so it never itself keeps us alive: a clean
+      // shutdown with no leaked handles exits naturally well before it fires.
+      // process.exit() runs the registered exit handlers (db re-encrypts
+      // there), so the last flush still happens.
+      var watchdog = setTimeout(function () {
+        log.error("shutdown exceeded " + (graceMs + forceExitMarginMs) +
+          "ms without the process exiting — forcing exit (exit handlers run " +
+          "the final DB flush) before the supervisor SIGKILLs");
+        // Bounded forced exit after the grace deadline, armed ONLY inside the
+        // signal handler (operator opted into installSignalHandlers,
+        // delegating process lifecycle to the orchestrator).
+        // allow:process-exit — operator-delegated lifecycle, watchdog only
+        process.exit(process.exitCode || 1);
+      }, graceMs + forceExitMarginMs);
+      if (typeof watchdog.unref === "function") watchdog.unref();
       shutdown().then(function (result) {
         if (process.exitCode === undefined || process.exitCode === 0) {
           process.exitCode = result.ok ? 0 : 1;

package/lib/vendor/blamejs/lib/bounded-map.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * bounded-map — a Map facade that caps its entry count.
+ *
+ * Defends the unbounded-in-bounded resource-exhaustion class: an in-memory
+ * store keyed on request-derived input (a locale, a hostname, an
+ * idempotency key, a replay nonce) grows without limit between sweeps
+ * unless something enforces a ceiling. A periodic TTL sweep alone does not
+ * bound peak memory — a flood of unique keys arrives faster than the sweep
+ * interval. This adds the missing ceiling.
+ *
+ * Two policies for what happens on `set` when already at `maxEntries`:
+ *
+ *   "evict-oldest" (default) — drop the oldest entry (insertion order)
+ *     to make room, then store the new one. For caches whose entries are
+ *     re-derivable on demand (Intl formatters, DNS results, idempotency
+ *     records) eviction is cheap — the worst case is a recomputed value or
+ *     a missed dedup under active flood, never a correctness or security
+ *     hole. `set` always stores and returns true.
+ *
+ *   "reject" — refuse the new entry (do NOT evict a live one) and return
+ *     false. For stores where evicting an unexpired entry would be unsafe:
+ *     a replay-protection nonce store must not drop a live nonce to admit a
+ *     new one, because that reopens a replay window for the dropped nonce.
+ *     The caller fails closed on a false return (treats the request as
+ *     un-recordable → reject it). Callers should purge expired entries
+ *     before relying on this so the ceiling is hit only under genuine flood.
+ *
+ * This is deliberately NOT `b.cache` — that is an operator-facing primitive
+ * with TTL, LRU-touch, observability, and pluggable backends. This is the
+ * minimal internal ceiling the framework's own request-keyed Maps need, and
+ * leaves TTL/expiry semantics to the caller (which already owns them).
+ *
+ * `onEvict(key, value)` (optional) fires when an entry is dropped to make
+ * room under "evict-oldest" — for an observability counter, say. It never
+ * fires under "reject" (nothing is evicted; the new entry is dropped).
+ */
+
+var numericBounds = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+
+var BoundedMapError = defineClass("BoundedMapError");
+
+/**
+ * @param {object} opts
+ * @param {number} opts.maxEntries    - hard ceiling; throws if not a positive finite int
+ * @param {string} [opts.policy]      - "evict-oldest" (default) | "reject"
+ * @param {function} [opts.onEvict]   - (key, value) called on eviction under "evict-oldest"
+ * @returns Map-like facade: get/has/set/delete/clear, size getter, keys/values/entries/forEach, [Symbol.iterator]
+ */
+function boundedMap(opts) {
+  opts = opts || {};
+  if (!numericBounds.isPositiveFiniteInt(opts.maxEntries)) {
+    throw new BoundedMapError("bounded-map/bad-max-entries",
+      "boundedMap: opts.maxEntries must be a positive finite integer, got " + JSON.stringify(opts.maxEntries));
+  }
+  var maxEntries = opts.maxEntries;
+  var policy = opts.policy || "evict-oldest";
+  if (policy !== "evict-oldest" && policy !== "reject") {
+    throw new BoundedMapError("bounded-map/bad-policy",
+      "boundedMap: opts.policy must be 'evict-oldest' | 'reject', got " + JSON.stringify(policy));
+  }
+  var onEvict = typeof opts.onEvict === "function" ? opts.onEvict : null;
+  var inner = new Map();
+
+  function set(key, value) {
+    // Updating an existing key never grows the map — always allowed.
+    if (inner.has(key)) { inner.set(key, value); return true; }
+    if (inner.size >= maxEntries) {
+      if (policy === "reject") return false;
+      // evict-oldest: the first key in insertion order is the oldest.
+      var oldest = inner.keys().next().value;
+      if (oldest !== undefined || inner.has(oldest)) {
+        var evictedVal = inner.get(oldest);
+        inner.delete(oldest);
+        if (onEvict) { try { onEvict(oldest, evictedVal); } catch (_e) { /* obs hook — drop-silent */ } }
+      }
+    }
+    inner.set(key, value);
+    return true;
+  }
+
+  return {
+    get:    function (k) { return inner.get(k); },
+    has:    function (k) { return inner.has(k); },
+    set:    set,
+    delete: function (k) { return inner.delete(k); },
+    clear:  function () { inner.clear(); },
+    keys:   function () { return inner.keys(); },
+    values: function () { return inner.values(); },
+    entries: function () { return inner.entries(); },
+    forEach: function (fn, thisArg) { return inner.forEach(fn, thisArg); },
+    get size() { return inner.size; },
+    get maxEntries() { return maxEntries; },
+    get policy() { return policy; },
+    // Iterable like a Map, so `for (var e of bmap)` yields [key, value]
+    // entries — callers that iterate a plain Map keep working unchanged.
+    [Symbol.iterator]: function () { return inner[Symbol.iterator](); },
+  };
+}
+
+module.exports = { boundedMap: boundedMap, BoundedMapError: BoundedMapError };

package/lib/vendor/blamejs/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,