@blamejs/core 0.15.41 → 0.15.42

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.15.x
 
+- v0.15.42 (2026-06-28) — **The agent orchestrator and tenant registries serialize registration per name, so two concurrent register() calls for the same name can no longer both create a row (duplicate-create / lost registration), and a new b.safeAsync.keyedSerializer exposes that per-key serialization.** b.agent.orchestrator and b.agent.tenant registered a name with a check-then-create: read the backend row for the name, throw a duplicate error if it exists, otherwise write the new row. Because the read and the write are separated by an await, two concurrent register() calls for the same name both observed absence and both wrote — a duplicate-create where the second silently clobbered the first and both callers saw success, violating the one-row-per-name invariant. register() (and unregister()) now run through a per-name in-process serializer, so concurrent calls for the same name apply one at a time and the second is correctly refused as a duplicate; distinct names still run concurrently. The serializer is exposed as b.safeAsync.keyedSerializer() for any read-modify-write or check-then-create that must not interleave per key. It is in-process only: a registry backend shared across processes still needs its own atomic create or unique constraint to refuse a cross-process duplicate. **Added:** *b.safeAsync.keyedSerializer — serialize async work per key* — b.safeAsync.keyedSerializer() returns a { run(key, fn) } that queues fn behind any in-flight or queued work for the same key and runs it once they settle, so a read-modify-write or a check-then-create on a shared store cannot interleave with another call for the same key in the same process. Distinct keys run concurrently, and the per-key chain is dropped once it drains. It is the serialization the agent registries now use, and the same primitive backs the lockout and bot-challenge per-key failure counters. **Fixed:** *Agent orchestrator + tenant registries serialize registration per name (no duplicate-create race)* — b.agent.orchestrator.register and b.agent.tenant.register did a check-then-create (await backend.get -> throw-if-exists -> await backend.set) with an await between the read and the write, so two concurrent registrations of the same name both passed the duplicate check and both wrote — the second silently clobbering the first while both callers saw success. Registration now serializes per name in-process, so concurrent calls for one name apply sequentially and the second is refused with the duplicate error; distinct names are unaffected. A backend shared across processes still needs its own uniqueness constraint to refuse a cross-process duplicate. **Detectors:** *Build guard: a registry check-then-create must serialize per key* — A codebase guard now fails the build if a primitive does an async check-then-create on a pluggable backend (await backend.get -> throw a /duplicate error -> await backend.set) without serializing per key, so the duplicate-create race fixed here cannot reappear at a new registry.
+
 - v0.15.41 (2026-06-28) — **Counters kept on a shared cache — byte quotas and the static server's bandwidth/concurrency caps — now accumulate with an atomic compare-and-set, so concurrent requests can no longer lose each other's charges and slip under the limit.** Several caps maintained a counter on a cache with a non-atomic read-modify-write: read the current value, add to it in memory, write it back. On a cache shared across nodes, two concurrent requests both read the same value, each added only its own contribution, and one write clobbered the other — a lost update that under-counted the cap and let a peer slip under it. b.network.byteQuota (and the b.middleware.dailyByteQuota that composes it) and the static server's per-actor/global bandwidth and per-actor concurrency caps all did this. They now accumulate through the cache's atomic update() (compare-and-set, with retry on the cluster backend under contention), so every concurrent charge is counted. A cache backing these caps must support atomic update(); b.cache provides it, and both primitives refuse a get/set-only cache at construction. The single-node in-memory paths were already safe (they accumulate synchronously). **Fixed:** *Byte quota on a shared cache counts concurrent requests atomically (no lost updates)* — b.network.byteQuota's cache backend accumulated bytes with a get → add → set that is not atomic, so concurrent requests from one peer on a multi-node deployment lost each other's byte charges and the rolling daily byte budget was under-enforced. Accounting now uses the cache's atomic compare-and-set update(), counting every concurrent request, and retries the cluster CAS under a contention burst rather than dropping a charge. A cache wired to a byte quota must support update() — b.cache does; a plain get/set cache is refused at create() (byte-quota/cache-no-atomic-update), and a backend that can't actually commit an atomic update surfaces loud on first use instead of silently disabling the quota. b.middleware.dailyByteQuota, which composes byteQuota, inherits the fix. · *Static server bandwidth + concurrency caps count concurrent requests atomically* — b.staticServe's per-actor and global bandwidth caps and its per-actor concurrency cap kept their counters on the cache with a non-atomic get → add → set, so concurrent downloads from one actor on a multi-replica deployment lost each other's charges and the caps were under-enforced (a bandwidth/concurrency limit bypass). The counters now accumulate through the cache's atomic update() with the same contention retry, and the quota cache is required to support update() at create(). **Detectors:** *Build guard: a cache-backed counter must use atomic update(), not get → set* — A codebase guard now fails the build if a primitive accumulates a counter on a cache with a get → mutate → set read-modify-write instead of the atomic update(), so the lost-update class fixed here cannot reappear at a new cap. Caches used for lookups or cache-aside (the value is replaced wholesale, not incremented), or whose writes are serialized in-process, are allowlisted with the reason they cannot lose an increment.
 
 - v0.15.40 (2026-06-27) — **The durable webhook dispatcher's retry poller now claims due deliveries with FOR UPDATE SKIP LOCKED on Postgres and MySQL, so two pollers running at once (multiple app nodes) can no longer both grab the same delivery and send the webhook twice in one cycle.** The webhook dispatcher's retry poller claimed due deliveries by flipping them pending->in-flight and then re-selecting the in-flight rows by id. On Postgres or MySQL under the default READ COMMITTED isolation, two pollers running concurrently could both re-select the same row: the loser's UPDATE matched zero rows (the winner had already flipped it), but its reselect-by-id still re-read the row the winner had just claimed, so both pollers attempted the same HTTP delivery in one cycle. The claim now row-locks the due rows with SELECT ... FOR UPDATE SKIP LOCKED on the row-locking backends, so concurrent pollers see disjoint sets and each delivery is claimed by exactly one poller; sqlite (a single writer) keeps the existing mark-then-reselect, which it serializes safely. This matches the claim used by the framework's transactional outbox and cluster queue. Receivers that already dedup on the X-Webhook-Delivery-Id header were protected from a duplicate POST; this closes the at-most-once-per-cycle gap at the dispatcher itself. **Fixed:** *Webhook retry pollers no longer double-deliver under concurrency on Postgres / MySQL* — b.webhook.dispatcher's processRetries() claimed due deliveries with a mark-then-reselect that had no row lock, so on Postgres / MySQL at READ COMMITTED two concurrent pollers (for example, the dispatcher running on more than one app node) could both hand back the same delivery and POST it twice in a single retry cycle. The claim now uses SELECT ... FOR UPDATE SKIP LOCKED on those backends so each due row is locked by exactly one poller and concurrent pollers claim disjoint sets; the rows a poller selects are exactly the rows it owns. sqlite keeps the mark-then-reselect path, which its single writer serializes. Operators running the dispatcher on a single node, or whose receivers dedup on X-Webhook-Delivery-Id, were not exposed to a duplicate delivery; no configuration change is required to pick up the fix. **Detectors:** *Build guard: a competing-consumer claim must use FOR UPDATE SKIP LOCKED* — A codebase guard now fails the build if a poller that claims due rows across workers — SELECT status='pending' inside a transaction, then flip the rows to in-flight — omits FOR UPDATE SKIP LOCKED on the row-locking backends. Without the row lock, two pollers under READ COMMITTED both claim the same row; the guard keeps any future poller from re-introducing the shape, with the transactional outbox and cluster queue as the reference claims.

package/lib/agent-orchestrator.js

@@ -60,6 +60,7 @@ var bCrypto           = require("./crypto");
 var agentAudit        = require("./agent-audit");
 var vaultAad          = require("./vault-aad");
 var validateOpts      = require("./validate-opts");
+var safeAsync         = require("./safe-async");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 var cluster           = lazyRequire(function () { return require("./cluster"); });
@@ -165,6 +166,11 @@ function create(opts) {
 
   var ctx = {
     backend:     backend,
+    // Serializes register/unregister per name so a concurrent pair for the same
+    // name can't interleave the check-then-create (await get -> throw-if-exists
+    // -> await set) and both write — a duplicate-create / lost-registration. In
+    // process only; a shared persistent backend also needs its own uniqueness.
+    registrySerializer: safeAsync.keyedSerializer(),
     cluster:     clusterImpl,
     audit:       auditImpl,
     permissions: permissions,
@@ -235,9 +241,9 @@ function create(opts) {
   }
 
   return {
-    register:        function (name, agent, regOpts)         { return _register(ctx, name, agent, regOpts || {}); },
+    register:        function (name, agent, regOpts)         { return ctx.registrySerializer.run(name, function () { return _register(ctx, name, agent, regOpts || {}); }); },
     hydrate:         function (name, agent)                  { return _hydrate(ctx, name, agent); },
-    unregister:      function (name, args)                   { return _unregister(ctx, name, args || {}); },
+    unregister:      function (name, args)                   { return ctx.registrySerializer.run(name, function () { return _unregister(ctx, name, args || {}); }); },
     lookup:          function (name, args)                   { return _lookup(ctx, name, args || {}); },
     list:            function (args)                         { return _list(ctx, args || {}); },
     spawnConsumers:  function (args)                         { return _spawnConsumers(ctx, args || {}); },

package/lib/agent-tenant.js

@@ -60,6 +60,7 @@ var agentAudit       = require("./agent-audit");
 var safeJson         = require("./safe-json");
 var vaultAad         = require("./vault-aad");
 var validateOpts     = require("./validate-opts");
+var safeAsync        = require("./safe-async");
 
 var audit            = lazyRequire(function () { return require("./audit"); });
 var cryptoField      = lazyRequire(function () { return require("./crypto-field"); });
@@ -159,13 +160,19 @@ function create(opts) {
   var permissions = opts.permissions || null;
   var ctx = {
     backend: backend, audit: auditImpl, permissions: permissions,
+    // Serializes register/unregister per tenantId so a concurrent pair for the
+    // same tenant can't interleave the check-then-create (await get ->
+    // throw-if-exists -> await set) and both write — a duplicate-create /
+    // lost-registration. In process only; a shared persistent backend also
+    // needs its own uniqueness constraint.
+    registrySerializer: safeAsync.keyedSerializer(),
     // Archived tenants — keys retained but no live config; restore
     // requires explicit operator opt-in.
     archive: new Map(),
   };
   return {
-    register:    function (tenantId, regOpts)      { return _register(ctx, tenantId, regOpts || {}); },
-    unregister:  function (tenantId, args)         { return _unregister(ctx, tenantId, args || {}); },
+    register:    function (tenantId, regOpts)      { return ctx.registrySerializer.run(tenantId, function () { return _register(ctx, tenantId, regOpts || {}); }); },
+    unregister:  function (tenantId, args)         { return ctx.registrySerializer.run(tenantId, function () { return _unregister(ctx, tenantId, args || {}); }); },
     lookup:      function (tenantId, args)         { return _lookup(ctx, tenantId, args || {}); },
     list:        function (args)                   { return _list(ctx, args || {}); },
     check:       function (actor, agentTenantId)   { return _check(ctx, actor, agentTenantId); },

package/lib/auth/lockout.js

@@ -84,6 +84,7 @@ var numericBounds = require("../numeric-bounds");
 var lazyRequire = require("../lazy-require");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
+var safeAsync = require("../safe-async");
 var { LockoutError } = require("../framework-error");
 
 var observability = lazyRequire(function () { return require("../observability"); });
@@ -264,17 +265,11 @@ function create(opts) {
 
   // Per-key serialization of the failure counter (read→increment→write on an
   // async store): concurrent recordFailure calls for the same key would lose
-  // updates, letting parallel failures stay under the lockout threshold. A
-  // per-key promise chain applies them sequentially in-process.
-  var _recordChains = new Map();
+  // updates, letting parallel failures stay under the lockout threshold. The
+  // keyed serializer applies them sequentially in-process.
+  var _recordSerializer = safeAsync.keyedSerializer();
   function recordFailure(key, callOpts) {
-    var prev = _recordChains.get(key) || Promise.resolve();
-    var run = prev.then(function () { return _doRecordFailure(key, callOpts); },
-                        function () { return _doRecordFailure(key, callOpts); });
-    var tail = run.then(function () {}, function () {});
-    _recordChains.set(key, tail);
-    tail.then(function () { if (_recordChains.get(key) === tail) _recordChains.delete(key); });
-    return run;
+    return _recordSerializer.run(key, function () { return _doRecordFailure(key, callOpts); });
   }
 
   async function _doRecordFailure(key, callOpts) {

package/lib/auth-bot-challenge.js

@@ -41,6 +41,7 @@ var lazyRequire = require("./lazy-require");
 var requestHelpers = require("./request-helpers");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
+var safeAsync = require("./safe-async");
 var { AuthBotChallengeError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -280,15 +281,9 @@ function create(opts) {
   // per-key promise chain applies advances for a key sequentially. (Cross-node
   // atomicity additionally needs an atomic store; this fixes the in-process
   // race the gate actually depends on.)
-  var _advanceChains = new Map();
+  var _advanceSerializer = safeAsync.keyedSerializer();
   function _advanceFailure(key, req) {
-    var prev = _advanceChains.get(key) || Promise.resolve();
-    var run = prev.then(function () { return _doAdvanceFailure(key, req); },
-                        function () { return _doAdvanceFailure(key, req); });
-    var tail = run.then(function () {}, function () {});
-    _advanceChains.set(key, tail);
-    tail.then(function () { if (_advanceChains.get(key) === tail) _advanceChains.delete(key); });
-    return run;
+    return _advanceSerializer.run(key, function () { return _doAdvanceFailure(key, req); });
   }
 
   async function _doAdvanceFailure(key, req) {

package/lib/safe-async.js

@@ -1611,6 +1611,47 @@ function flushLoop(fn, intervalMs, opts) {
 // We re-export them here under safe-async-shaped names so call sites
 // reaching for async safety primitives find them in one place.
 
+/**
+ * @primitive b.safeAsync.keyedSerializer
+ * @signature b.safeAsync.keyedSerializer()
+ * @since     0.15.42
+ * @status    stable
+ * @related   b.safeAsync.parallel
+ *
+ * Serializes async work per key: `run(key, fn)` queues `fn` behind any in-flight
+ * or queued work for the same `key` and runs it once they settle, so a
+ * read-modify-write or a check-then-create on a shared store cannot interleave
+ * with another call for the same key in the same process. Different keys run
+ * concurrently. The per-key chain is dropped once it drains, so the map does not
+ * grow without bound.
+ *
+ * In-process only: it serializes calls within ONE process. A registry shared
+ * across processes still needs its backend's own atomic create / unique
+ * constraint to refuse a cross-process duplicate.
+ *
+ * @example
+ *   var reg = b.safeAsync.keyedSerializer();
+ *   // concurrent register("acme") calls apply one-at-a-time, so the second
+ *   // sees the first's row and is refused as a duplicate:
+ *   await reg.run("acme", function () { return register("acme", row); });
+ */
+function keyedSerializer() {
+  var chains = new Map();
+  function run(key, fn) {
+    var prev = chains.get(key) || Promise.resolve();
+    // Run fn after prev settles (resolved OR rejected) so one failure does not
+    // wedge the key's queue. Wrap so prev's settled value/reason is NOT leaked
+    // into fn as an argument — fn runs as a thunk with its own closure, never
+    // the previous task's result.
+    var result = prev.then(function () { return fn(); }, function () { return fn(); });
+    var tail = result.then(function () {}, function () {});
+    chains.set(key, tail);
+    tail.then(function () { if (chains.get(key) === tail) chains.delete(key); });
+    return result;
+  }
+  return { run: run };
+}
+
 var retryHelper = require("./retry");
 
 var asyncRetry     = retryHelper.withRetry;
@@ -1632,6 +1673,7 @@ module.exports = {
   makeBatchDrain:     makeBatchDrain,
   makeBatchingSink:   makeBatchingSink,
   parallel:           parallel,
+  keyedSerializer:    keyedSerializer,
   Mutex:              Mutex,
   Semaphore:          Semaphore,
   Once:               Once,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.15.41",
+  "version": "0.15.42",
   "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:b6890c56-a06c-431c-b27d-d91ce739441d",
+  "serialNumber": "urn:uuid:25fff8f4-b758-413d-b63d-fc1b5b5a19ad",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-28T08:26:04.321Z",
+    "timestamp": "2026-06-28T09:41:21.905Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.15.41",
+      "bom-ref": "@blamejs/core@0.15.42",
       "type": "application",
       "name": "blamejs",
-      "version": "0.15.41",
+      "version": "0.15.42",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.15.41",
+      "purl": "pkg:npm/%40blamejs/core@0.15.42",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.15.41",
+      "ref": "@blamejs/core@0.15.42",
       "dependsOn": []
     }
   ]