@blamejs/core 0.18.42 → 0.18.43

package/CHANGELOG.md

@@ -8,6 +8,26 @@ upgrading across more than a few patches at a time.
 
 ## v0.18.x
 
+- v0.18.43 (2026-08-20) — **Three things the framework already knew how to do, reachable from outside it.** Each of these existed as working machinery with no public door: the largest-remainder split was locked behind a currency table that carries 43 of the ~180 ISO 4217 codes, the durable queue could only be driven by a resident consumer, and the MIME/extension table was reachable only through a test hook. In each case the predictable consequence downstream was a partial reimplementation of the part that is hardest to get right. **Added:** *`b.queue.tick(opts)` — drain what is due, then return* — Leases at most `max` available jobs, runs the handler over them, applies the same leasing, deterministic backoff and dead-letter transitions `b.queue.consume` applies, and settles. Nothing is left running when the promise resolves: no resident loop, no timer, no consumer for shutdown to wait on. Returns `{ leased, succeeded, failed, stale, unsettled, movedToDlq, mayHaveMore, queueDepth }`. Loop on `mayHaveMore` — the batch came back full, so more may be due right now. Not on `queueDepth`: that is the queue's total active depth and counts jobs whose `availableAt` is still in the future, so a caller looping on it spins through empty ticks waiting for a delayed job to come due. `queueDepth` is `null` when the backend could not be asked, because unknown is not empty. Two counts are not terminal states and mean different things. `unsettled` is the one to alert on: the backend REFUSED to record the outcome — complete or fail rejecting after its own retries — so the job is still inflight and the tick does not know whether the handler succeeded. A later sweep recovers it, and if the handler had already succeeded its side effects run again. `stale` is benign by comparison and counts jobs the tick ran but did not settle — the handler outlived the lease, the job was swept and re-leased, and the backend's attempt fence refused the completion. A non-zero `stale` means `leaseMs` is too short for the handler or the batch too large to finish inside it.
+
+Pair it with `b.queue.init({ sweepIntervalMs: 0 })`, new in this release. `init` otherwise starts a 30-second expired-lease sweep timer, and in a frozen isolate that timer either never fires or fires inside a LATER invocation, touching the backend outside any request the platform is accounting for. `tick` sweeps once per invocation itself, so the timer buys nothing there. The option also lets a resident deployment tune the period; the default is unchanged.
+
+It sweeps expired leases before taking a batch. A job whose holder died between leasing and settling stays `inflight` until something re-pends it, and the thing that normally does is the 30-second sweep timer started at `init` — a timer that never fires in the runtime this driver exists for. Without the sweep an invocation killed mid-lease would strand its job permanently, in exactly the deployment `tick` serves.
+
+This is the driver a scheduled invocation needs — a Cloudflare `scheduled()` handler, a Lambda on EventBridge, a Kubernetes CronJob. `consume` cannot serve those: it is a resident loop and it starts a background sweep, and such a runtime freezes between invocations, so the timer never fires and the consumer is either blocking the handler or killed mid-lease. Without a per-tick entry point the durable half gets reimplemented by the caller — attempt accounting, backoff schedule, DLQ transition — which is precisely the part that is hard to get right.
+
+`consume` and `tick` now run jobs through one shared path, so the retry schedule and the DLQ transition have exactly one implementation rather than two that can drift.
+
+It drives the `local` and `redis` protocols, the same boundary `consume` has. An `sqs` backend is refused with `TICK_UNSUPPORTED`: SQS completes and fails by `receiptHandle` and owns redelivery and the dead-letter queue through its own RedrivePolicy, so driving it here would complete without the receipt and let SQS redeliver messages the handler had already processed. Drive SQS directly — lease, handle, complete or fail. · *`b.money.splitUnits(total, weights)` — the largest-remainder split without a currency* — Splits an integer into parts proportional to `weights`, distributing every unit: floor each share, then hand the leftovers to the largest remainders, ties broken by index. The total is preserved by construction and no floating point is involved, so the result is identical across runtimes. Negative totals floor toward negative infinity, so the parts still sum to the total.
+
+A `Number` total or weight must be a SAFE integer. Past `Number.MAX_SAFE_INTEGER` the value has already been rounded before the function sees it — `9007199254740993` arrives as `...992` — so exact arithmetic there would faithfully split a total the caller never asked for. Those are refused with a message pointing at BigInt, which carries the value exactly.
+
+The algorithm was already there as `Money.allocate`, but reaching it required a `Money`, which requires a currency from `b.money.CURRENCIES` — a table carrying the codes the framework has minor-unit data for rather than all of ISO 4217. A caller holding a currency outside that set could not reach the split at all, and neither could a caller splitting something that is not money: seats, quota, shard weights, a rate limit across workers. `Money.allocate` now composes it, so both doors open onto one implementation. · *`b.fileType.extensionFor(mime)` and `b.fileType.mimeFor(extension)`* — Read-only accessors over the signature table `b.fileType.detect` already consults, in both directions. Unknown returns `null` rather than a guess — a caller minting an object-store key or a `Content-Disposition` filename needs to know when the framework does not recognise the type. Lookups are case-insensitive, `extensionFor` ignores content-type parameters so a `Content-Type` header value can be passed straight in, and `mimeFor` accepts a leading dot because that is what `path.extname` returns.
+
+`detect` answers what a file is; the next question is usually what to call it, and until now that had no answer, so consumers kept partial copies of a table the framework maintains — copies that drift the moment a signature is added.
+
+`mimeFor` answers a naming question, not a trust question: it reports what an extension claims. Only `detect` establishes what a file IS, by reading the bytes, because an attacker controls the name and never the magic. **References:** [RFC 2045 §5.1 — Content-Type is case-insensitive](https://www.rfc-editor.org/rfc/rfc2045#section-5.1)
+
 - v0.18.42 (2026-08-20) — **`b.middleware.botGuard` no longer refuses a request for omitting Accept-Language, which was returning 403 to every search-engine crawler.** `b.middleware.botGuard` treated a missing `Accept-Language` header as grounds for a 403 in its default blocking mode. Google documents that Googlebot sends requests without setting that header, and bingbot behaves the same, so every content page of a site running the default middleware chain answered 403 to a crawler while a browser was served normally. The header's absence is now an advisory signal, matching how the same middleware already treats a missing `Sec-Fetch-Mode`. **Changed:** *Vendored `@blamejs/pki` 0.5.16 to 0.5.17* — A failed integrity check now destroys the plaintext it had recovered rather than returning it, `AuthEnvelopedData` validates the attributes it is asked to authenticate, and the refusal for a content cipher in the wrong container cites the rule it actually applies — RFC 5083 §2 defines `AuthEnvelopedData` in terms of authenticated encryption and never names GCM, so the previous message sent operators to argue with a specification that says the opposite. **Fixed:** *A missing `Accept-Language` tags a request instead of refusing it* — The check was `if (!headers["accept-language"]) return "missing-accept-language"`, and `mode` defaults to `"block"`, so the request was answered 403. Whole client families omit the header — every major search-engine crawler, and with them uptime monitors, link previewers and feed readers — which made a site unreachable to all of them. On a deployment fronted by a cache this is easy to miss from the outside: the cached home page still answers 200, so the site looks partly indexed while every other URL is refused.
 
 It now sets `req.suspectedBot` in `mode: "tag"` and never blocks, which is exactly how the middleware already treats a missing `Sec-Fetch-Mode` — absent for Safari before 16.4 and for every plain-HTTP non-localhost origin — and how `b.middleware.fetchMetadata` already treats a missing `Sec-Fetch-Site` through its `allowMissing` default. A header a whole client family omits is not evidence of automation.

package/README.md

@@ -67,7 +67,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **DB lifecycle** — in-memory encrypted snapshot via `b.db.snapshot()`; standalone encrypted-DB-file lifecycle (`b.db.fileLifecycle({ dataDir, vault })` — decrypt-to-tmpfs, periodic re-encrypt flush, graceful shutdown — same envelope as `b.db`, no schema/audit-chain coupling); `db.init` opt-outs `frameworkTables: false` / `auditSigning: false` and path overrides `encryptedDbPath` / `encryptedDbName` / `dbKeyPath`
 - **External RDBMS** — bring-your-own Postgres / MySQL with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); an opt-in `requireTls` transport posture refuses a non-TLS backend at boot, and query / transaction / read traces carry OpenTelemetry `db.*` attributes. The framework's own data layer — the signed audit chain, cluster leadership and lease fencing, sessions, break-glass, and the local queue / cache / scheduler — is composed through the dialect-aware `b.sql` builder (every identifier quoted by construction, every value bound as a placeholder, dialect-correct SQLite / Postgres / MySQL output), so the framework's tables run on a Postgres or MySQL backend, not only local SQLite; `b.guardSql` validates result rows against NUL bytes, quote-jump sequences, and per-column / total-size boundaries
 - **Object store** — S3 / R2 / B2 / GCS / Azure with multipart upload + SSE + bucket-ops (create / delete / list / lifecycle / CORS); S3 Object Lock + per-object retention + legal hold for write-once-read-many compliance workloads, with versioned delete + `listVersions` for right-to-erasure / crypto-shred against an Object-Lock bucket (`b.storage`, `b.objectStore`)
-- **Queues + cache** — durable queue with priority + cron + flows on local SQLite, shared Redis, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 (`b.queue`, `b.jobs`) — the local backend can target an operator-supplied database / table / schema; cluster-shared cache (`b.cache`)
+- **Queues + cache** — durable queue with priority + cron + flows on local SQLite, shared Redis, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 (`b.queue`, `b.jobs`) — the local backend can target an operator-supplied database / table / schema; driven either by a resident consumer (`b.queue.consume`) or one batch at a time for a scheduled runtime that cannot host one (`b.queue.tick`); cluster-shared cache (`b.cache`)
 ### Identity & access
 
 - **Passwords** — Argon2id + policy primitive (`b.auth.password`); NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles; HaveIBeenPwned k-anonymity breach check; length / context / dictionary / complexity rules; rotation + history
@@ -156,7 +156,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Mobile credentials (mDL)** — `b.mdoc` ISO/IEC 18013-5 verification: `verifyIssuerSigned` checks the COSE_Sign1 IssuerAuth (issuer cert from the `x5chain` header), the MSO validity window, and every disclosed element's digest against the MSO `valueDigests` (selective-disclosure integrity), with optional issuer-chain verification; `verifyDeviceAuth` proves holder binding (§9.1.3 signature variant) — the device COSE_Sign1 over the `DeviceAuthentication` structure with the MSO device key + protocol `sessionTranscript`. The ISO credential ecosystem alongside `b.vc` and `b.auth.sdJwtVc`. Composes `b.cose` + `b.cbor`
 - **Decentralized Identifiers** — `b.did` W3C DID resolution (DID Core 1.0): `resolve` a `did:key` / `did:jwk` (deterministic, offline — Ed25519 / P-256 / P-384 / secp256k1) or `did:web` (operator-fetched document) to `node:crypto` verification keys, so a credential's issuer DID resolves to the key that verifies it (`b.vc` / `b.mdoc` / `b.scitt`). `keyToDid` names a key as a `did:key` or `did:jwk`; document/JWK keys are kty/crv-allowlisted before import
 - **Document parsers** — `b.parsers` (XML / TOML / YAML / .env); `b.config` (schema-validated env)
-- **File-type detection** — `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.)
+- **File-type detection** — `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.); `extensionFor` / `mimeFor` read the same table in both directions, so naming a detected file does not need a second copy of it
 ### Content-safety gates
 
 - **Composition contract** — `b.gateContract` uniform mode posture / hooks / forensic snapshot / decision cache / runtime cap

package/lib/file-type.js

@@ -353,9 +353,89 @@ function assertOneOf(buf, allowlist, opts) {
   return detected;
 }
 
+// Both directions of the signature table, built once at load. Every row is
+// 1:1 in both directions, so neither map loses an entry; a row added with a
+// duplicate mime or extension would silently shadow, which the test asserts
+// against by round-tripping every row.
+var _MIME_TO_EXT = Object.create(null);
+var _EXT_TO_MIME = Object.create(null);
+SIGNATURES.forEach(function (row) {
+  if (row.mime && !(row.mime.toLowerCase() in _MIME_TO_EXT)) {
+    _MIME_TO_EXT[row.mime.toLowerCase()] = row.extension;
+  }
+  if (row.extension && !(row.extension.toLowerCase() in _EXT_TO_MIME)) {
+    _EXT_TO_MIME[row.extension.toLowerCase()] = row.mime;
+  }
+});
+
+/**
+ * @primitive b.fileType.extensionFor
+ * @signature b.fileType.extensionFor(mime)
+ * @since     0.18.43
+ * @status    stable
+ * @related   b.fileType.detect, b.fileType.mimeFor
+ *
+ * The canonical file extension for a MIME type, with no leading dot, or `null`
+ * when the framework does not recognise the type. Never a guess: a caller
+ * minting an object-store key or a `Content-Disposition` filename needs to
+ * know when the answer is unknown rather than receive a plausible-looking one.
+ *
+ * `detect` answers "what is this"; the next question is usually "what should I
+ * call it", and the table that answers it is the same one. Reading it here
+ * rather than keeping a private copy is what stops the two drifting when a
+ * signature is added.
+ *
+ * The lookup is case-insensitive and ignores content-type parameters, so the
+ * `Content-Type` header value a request arrived with can be passed straight in.
+ *
+ * @example
+ *   b.fileType.extensionFor("image/png");
+ *   // → "png"
+ */
+function extensionFor(mime) {
+  if (typeof mime !== "string" || mime.length === 0) return null;
+  // MIME types are case-insensitive (RFC 2045 §5.1) and may carry parameters.
+  var bare = mime.split(";")[0].trim().toLowerCase();
+  if (bare.length === 0) return null;
+  return Object.prototype.hasOwnProperty.call(_MIME_TO_EXT, bare) ? _MIME_TO_EXT[bare] : null;
+}
+
+/**
+ * @primitive b.fileType.mimeFor
+ * @signature b.fileType.mimeFor(extension)
+ * @since     0.18.43
+ * @status    stable
+ * @related   b.fileType.detect, b.fileType.extensionFor
+ *
+ * The MIME type for a file extension, or `null` when the framework does not
+ * recognise it. The inverse of `b.fileType.extensionFor`, over the same table.
+ *
+ * A leading dot is accepted, because that is the form `path.extname` returns
+ * and therefore the form a caller usually has in hand. The lookup is
+ * case-insensitive.
+ *
+ * This answers a naming question, not a trust question. It reports what an
+ * extension claims; it does not establish what a file IS. Only
+ * `b.fileType.detect` does that, by reading the bytes — an attacker controls
+ * the name, never the magic.
+ *
+ * @example
+ *   b.fileType.mimeFor(".png");
+ *   // → "image/png"
+ */
+function mimeFor(extension) {
+  if (typeof extension !== "string" || extension.length === 0) return null;
+  var ext = extension.charAt(0) === "." ? extension.slice(1) : extension;
+  ext = ext.trim().toLowerCase();
+  if (ext.length === 0) return null;
+  return Object.prototype.hasOwnProperty.call(_EXT_TO_MIME, ext) ? _EXT_TO_MIME[ext] : null;
+}
+
 module.exports = {
   detect:        detect,
   assertOneOf:   assertOneOf,
+  extensionFor:  extensionFor,
+  mimeFor:       mimeFor,
   FileTypeError: FileTypeError,
   // Internal — exposed so tests can introspect the registry shape.
   _SIGNATURES:   SIGNATURES,

package/lib/money.js

@@ -444,22 +444,77 @@ function roundMinor(minor, step, mode) {
 // method: floor each share, then hand out the leftover units to the
 // shares with the largest fractional remainder. Total preserved by
 // construction; deterministic across runtimes.
-Money.prototype.allocate = function (weights) {
+/**
+ * @primitive b.money.splitUnits
+ * @signature b.money.splitUnits(total, weights)
+ * @since     0.18.43
+ * @status    stable
+ * @related   b.money.fromMinorUnits, b.money.roundMinor
+ *
+ * Split an integer into parts proportional to `weights`, distributing every
+ * unit. Largest-remainder method: floor each share, then hand the leftover
+ * units to the shares with the largest fractional remainder, ties broken by
+ * index. The total is preserved by construction and the result is identical
+ * across runtimes — no floating point is involved at any step.
+ *
+ * This is the algorithm behind `Money.allocate`, reachable without a Money.
+ * `Money` requires a currency from `b.money.CURRENCIES`, which carries the
+ * codes the framework has minor-unit data for rather than all of ISO 4217, so
+ * a caller holding a currency outside that set could not reach the split at
+ * all. Nor could a caller splitting something that is not money — seats,
+ * quota, shard weights, a rate limit across workers — which is the same
+ * arithmetic with the same requirement that nothing be lost to rounding.
+ *
+ * `total` may be negative: shares floor toward negative infinity so the
+ * leftover pass stays positive and the parts still sum to `total`.
+ *
+ * @example
+ *   b.money.splitUnits(100n, [1, 1, 1]);
+ *   // → [34n, 33n, 33n]
+ */
+function splitUnits(total, weights) {
+  return _largestRemainder(_toBigIntUnits(total, "total"), weights, "splitUnits");
+}
+
+// Coerce a BigInt or SAFE integer Number; anything else is a caller error.
+//
+// Number.isInteger is not enough. Beyond Number.MAX_SAFE_INTEGER a literal has
+// already been rounded to a representable neighbour before this function ever
+// sees it — 9007199254740993 arrives as 9007199254740992, isInteger says yes,
+// and BigInt() faithfully preserves the wrong value. The split would then be
+// exact arithmetic over a total the caller never asked for, which breaks the
+// one guarantee this function makes. Above that range the caller has to pass a
+// BigInt, which carries the value exactly.
+function _toBigIntUnits(v, label) {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isSafeInteger(v)) return BigInt(v);
+  throw new MoneyError("money/bad-units",
+    label + " must be a BigInt or a safe integer Number (beyond " +
+    "Number.MAX_SAFE_INTEGER a Number has already lost the value — pass a BigInt); got " +
+    (typeof v === "number" ? String(v) : typeof v));
+}
+
+// The shared largest-remainder split. `label` names the caller in refusals so
+// an operator sees the API they actually invoked.
+function _largestRemainder(total, weights, label) {
   if (!Array.isArray(weights) || weights.length === 0) {
     throw new MoneyError("money/bad-weights",
-      "allocate requires a non-empty array of weights");
+      label + " requires a non-empty array of weights");
   }
   var sum = 0n;
   var w = new Array(weights.length);
   for (var i = 0; i < weights.length; i++) {
     var wi = weights[i];
     var wBig;
+    // Safe-integer, not merely integer — see _toBigIntUnits. A weight past the
+    // safe range has already been rounded, and the shares would be exact
+    // arithmetic over proportions the caller did not give.
     if (typeof wi === "bigint") wBig = wi;
-    else if (typeof wi === "number" && Number.isInteger(wi)) wBig = BigInt(wi);
+    else if (typeof wi === "number" && Number.isSafeInteger(wi)) wBig = BigInt(wi);
     else {
       throw new MoneyError("money/bad-weight",
-        "weight[" + i + "] must be BigInt or integer Number; got " +
-        (typeof wi));
+        "weight[" + i + "] must be a BigInt or a safe integer Number; got " +
+        (typeof wi === "number" ? String(wi) : typeof wi));
     }
     if (wBig < 0n) {
       throw new MoneyError("money/bad-weight",
@@ -470,9 +525,8 @@ Money.prototype.allocate = function (weights) {
   }
   if (sum === 0n) {
     throw new MoneyError("money/bad-weights",
-      "allocate weights sum to zero");
+      label + " weights sum to zero");
   }
-  var total = this._minor;
   var shares = new Array(weights.length);
   var remainders = new Array(weights.length);
   var allocated = 0n;
@@ -508,6 +562,14 @@ Money.prototype.allocate = function (weights) {
     leftover = leftover - 1n;
     k = k + 1;
   }
+  return shares;
+}
+
+// allocate -- split `this` into `weights.length` parts proportional to the
+// weights, distributing every minor unit. The arithmetic is b.money.splitUnits;
+// this wraps each share back into a Money of the same currency.
+Money.prototype.allocate = function (weights) {
+  var shares = _largestRemainder(this._minor, weights, "allocate");
   var out = new Array(shares.length);
   for (var s2 = 0; s2 < shares.length; s2++) {
     out[s2] = new Money(shares[s2], this.currency);
@@ -800,6 +862,7 @@ module.exports = {
   zero:            zero,
   convert:         convert,
   roundMinor:      roundMinor,
+  splitUnits:      splitUnits,
   CURRENCIES:      CURRENCIES,
   Money:           Money,
   MoneyError:      MoneyError,

package/lib/queue.js

@@ -136,6 +136,7 @@ var sweepTimer = null;
  *     },
  *   },
  *   defaultBackend?: string,  // name to use when enqueue/consume omit { backend }
+ *   sweepIntervalMs?: number, // expired-lease sweep period; default 30s, 0 = no timer
  *
  * @example
  *   b.queue.init({
@@ -153,6 +154,20 @@ function init(opts) {
   if (!opts || !opts.backends) {
     throw _err("INVALID_CONFIG", "queue.init({ backends }) is required", true);
   }
+  // Validate every option BEFORE touching module state. `initialized` stays
+  // false on a throw, so a rejected init is expected to leave nothing behind —
+  // but `backends` and `defaultBackend` are module-level and a later init does
+  // not clear them, so validating after assignment would leave the refused
+  // configuration's queues visible through listBackends() and selectable by
+  // name.
+  var sweepIntervalMs = opts.sweepIntervalMs === undefined
+    ? C.TIME.seconds(30)
+    : opts.sweepIntervalMs;
+  if (sweepIntervalMs !== 0 && !numericChecks.isPositiveInt(sweepIntervalMs)) {
+    throw _err("INVALID_CONFIG",
+      "queue.init({ sweepIntervalMs }) must be a positive integer, or 0 to run no " +
+      "sweep timer; got " + JSON.stringify(opts.sweepIntervalMs), true);
+  }
 
   // Self-register the _blamejs_jobs sealed-column declaration so payload +
   // lastError seal at rest even when this process never ran db.init (a
@@ -218,13 +233,21 @@ function init(opts) {
 
   // Sweep expired leases periodically (every 30s) so crashed-handler jobs
   // get re-pended.
-  sweepTimer = safeAsync.repeating(function () {
+  //
+  // `sweepIntervalMs: 0` starts no timer at all. That is the mode a scheduled
+  // runtime wants — a Cloudflare `scheduled()` handler, a Lambda, a CronJob —
+  // where a resident timer is not merely useless but wrong: the isolate is
+  // frozen between invocations, so it either never fires, or fires inside a
+  // LATER invocation and touches the backend outside any request the platform
+  // is accounting for. b.queue.tick sweeps once per invocation itself, so
+  // nothing is lost by turning the timer off there.
+  sweepTimer = sweepIntervalMs === 0 ? null : safeAsync.repeating(function () {
     Object.keys(backends).forEach(function (n) {
       if (backends[n].sweepExpired) {
         backends[n].sweepExpired().catch(function () { /* best effort */ });
       }
     });
-  }, C.TIME.seconds(30), { name: "queue-sweep" });
+  }, sweepIntervalMs, { name: "queue-sweep" });
 
   initialized = true;
 }
@@ -394,10 +417,6 @@ function consume(queueName, handler, opts) {
     if (rateLimit) rateLimit.timestamps.push(Date.now());
   }
 
-  // Progress audit-emit rate-limit — protect the audit chain from a
-  // chatty handler that calls progress() every loop iteration.
-  var PROGRESS_MIN_INTERVAL_MS = 250;
-
   // Each consumer has its own AbortController so cancel() unblocks any
   // in-flight poll-sleep immediately rather than waiting up to
   // pollIntervalMs (default 1s) for the next while-loop iteration.
@@ -463,101 +482,13 @@ function consume(queueName, handler, opts) {
           _emit("system.queue.consume.start", {
             metadata: { queue: queueName, backend: b.name, jobId: job.jobId, attempt: job.attempts, traceId: job.traceId },
           });
-          // Consume a rate-limit slot at handler-start so the budget
-          // tracks invocation rate, not lease rate (a single lease that
-          // splits work across many sub-units doesn't double-count).
+          // Consume a rate-limit slot at handler-start so the budget tracks
+          // invocation rate, not lease rate (a single lease that splits work
+          // across many sub-units doesn't double-count).
           _rateLimitConsume();
-
-          // Handler context — second arg to handler. Carries
-          // ctx.extendLease(ms) for long-running handlers and
-          // ctx.progress(0..100) for surfacing job progress to the
-          // audit chain (rate-limited so chatty handlers don't drown it).
-          var lastProgressEmitAt = 0;
-          var lastProgressValue = -1;
-          var ctx = {
-            extendLease: function (additionalMs) {
-              if (typeof b.extendLease !== "function") {
-                throw _err("EXTEND_LEASE_UNSUPPORTED",
-                  "queue backend '" + b.name + "' does not support extendLease",
-                  true);
-              }
-              return b.extendLease(job.jobId, additionalMs, { attempt: job.attempts }).then(function (ok) {
-                if (ok) {
-                  _emit("system.queue.lease.extended", {
-                    metadata: { queue: queueName, backend: b.name, jobId: job.jobId, additionalMs: additionalMs },
-                  });
-                }
-                return ok;
-              });
-            },
-            progress: function (pct) {
-              if (typeof pct !== "number" || !isFinite(pct)) return;
-              var clamped = Math.max(0, Math.min(100, Math.floor(pct)));
-              var now = Date.now();
-              // Always emit 0 and 100 (start/done markers); throttle the rest.
-              var isMarker = clamped === 0 || clamped === 100;
-              if (!isMarker && (now - lastProgressEmitAt) < PROGRESS_MIN_INTERVAL_MS) return;
-              if (clamped === lastProgressValue && !isMarker) return;
-              lastProgressEmitAt = now;
-              lastProgressValue = clamped;
-              observability.event("queue.progress", clamped, { queueName: queueName });
-              _emit("system.queue.progress", {
-                metadata: {
-                  queue: queueName, backend: b.name, jobId: job.jobId,
-                  attempt: job.attempts, traceId: job.traceId,
-                  percent: clamped,
-                },
-              });
-            },
-          };
-          observability.tap("queue.consume",
-            { queueName: queueName, backend: b.name, jobId: job.jobId, attempt: job.attempts },
-            function () {
-              return Promise.resolve()
-                .then(function () { return handler(job, ctx); })
-                .then(function () {
-                  return b.complete(job.jobId, { attempt: job.attempts }).then(function () {
-                    _emit("system.queue.consume.success", {
-                      metadata: { queue: queueName, backend: b.name, jobId: job.jobId, attempt: job.attempts, traceId: job.traceId },
-                    });
-                    observability.event("queue.complete", 1, { queueName: queueName });
-                  });
-                }, function (err) {
-              var msg = (err && err.message) || String(err);
-              var willRetry = job.attempts < job.maxAttempts;
-              return b.fail(job.jobId, msg, { retryDelayMs: _backoffDelay(job.attempts), attempt: job.attempts })
-                .then(function () {
-                  observability.event("queue.fail", 1, { queueName: queueName, willRetry: willRetry });
-                  _emit("system.queue.consume.failure", {
-                    metadata: {
-                      queue:    queueName, backend: b.name, jobId: job.jobId,
-                      attempt:  job.attempts, traceId: job.traceId,
-                      maxAttempts: job.maxAttempts, willRetry: willRetry,
-                    },
-                    reason:   msg,
-                    outcome:  "failure",
-                  });
-                  // DLQ-write event when the job has exhausted its retries.
-                  // Operators wire this to their alerting / dashboards
-                  // — failed-after-retries is "needs human review" not
-                  // "in the normal flow." Audit chain captures the
-                  // final state for forensics.
-                  if (!willRetry) {
-                    _emit("system.queue.dlq.write", {
-                      metadata: {
-                        queue: queueName, backend: b.name, jobId: job.jobId,
-                        attempts: job.attempts, traceId: job.traceId,
-                      },
-                      reason:  msg,
-                      outcome: "failure",
-                    });
-                  }
-                });
-            })
+          _runJob(b, queueName, job, handler)
             .catch(function (_e) { /* lifecycle errors swallowed — operator sees via audit */ })
             .then(function () { state.inFlight.delete(job.jobId); });
-            }
-          );
         })(jobs[i]);
       }
       await _pollSleep(fastPollMs);
@@ -576,6 +507,318 @@ function _backoffDelay(attempt) {
   return retryHelper.backoffDelay(attempt, _QUEUE_BACKOFF_OPTS);
 }
 
+// The handler context passed as the second argument to a job handler:
+// ctx.extendLease(ms) for a handler that outlives its lease, ctx.progress(0..100)
+// for surfacing progress to the audit chain (rate-limited so a chatty handler
+// cannot drown it).
+var _PROGRESS_MIN_INTERVAL_MS = 250;
+function _handlerContext(backend, queueName, job) {
+  var lastProgressEmitAt = 0;
+  var lastProgressValue = -1;
+  return {
+    extendLease: function (additionalMs) {
+      if (typeof backend.extendLease !== "function") {
+        throw _err("EXTEND_LEASE_UNSUPPORTED",
+          "queue backend '" + backend.name + "' does not support extendLease", true);
+      }
+      return backend.extendLease(job.jobId, additionalMs, { attempt: job.attempts }).then(function (ok) {
+        if (ok) {
+          _emit("system.queue.lease.extended", {
+            metadata: { queue: queueName, backend: backend.name, jobId: job.jobId, additionalMs: additionalMs },
+          });
+        }
+        return ok;
+      });
+    },
+    progress: function (pct) {
+      if (typeof pct !== "number" || !isFinite(pct)) return;
+      var clamped = Math.max(0, Math.min(100, Math.floor(pct)));
+      var now = Date.now();
+      // Always emit 0 and 100 (start/done markers); throttle the rest.
+      var isMarker = clamped === 0 || clamped === 100;
+      if (!isMarker && (now - lastProgressEmitAt) < _PROGRESS_MIN_INTERVAL_MS) return;
+      if (clamped === lastProgressValue && !isMarker) return;
+      lastProgressEmitAt = now;
+      lastProgressValue = clamped;
+      observability.event("queue.progress", clamped, { queueName: queueName });
+      _emit("system.queue.progress", {
+        metadata: {
+          queue: queueName, backend: backend.name, jobId: job.jobId,
+          attempt: job.attempts, traceId: job.traceId, percent: clamped,
+        },
+      });
+    },
+  };
+}
+
+// Run one leased job to its terminal state: complete on success, or fail with
+// the deterministic backoff and — once the attempts are exhausted — the DLQ
+// event. Resolves to "succeeded" or "failed"; `movedToDlq` says whether this
+// failure was the last one.
+//
+// Both drivers go through here. b.queue.consume runs it inside a resident
+// polling loop; b.queue.tick runs it over one leased batch and returns. The
+// retry schedule, the attempt accounting and the DLQ transition are the part
+// that is genuinely hard to get right, so there is exactly one copy of it.
+function _runJob(backend, queueName, job, handler) {
+  var ctx = _handlerContext(backend, queueName, job);
+  return observability.tap("queue.consume",
+    { queueName: queueName, backend: backend.name, jobId: job.jobId, attempt: job.attempts },
+    function () {
+      return Promise.resolve()
+        .then(function () { return handler(job, ctx); })
+        .then(function () {
+          return backend.complete(job.jobId, { attempt: job.attempts }).then(function (settled) {
+            // complete() answers FALSE when the attempt fence no longer
+            // matches: this worker's lease expired, the sweep re-pended the
+            // job, and someone else owns it now. Nothing was settled here, so
+            // claiming success would emit a success event for work this worker
+            // did not finish and inflate the caller's tally. Report it as
+            // stale and stay quiet.
+            if (settled === false) {
+              observability.event("queue.stale", 1, { queueName: queueName });
+              return { status: "stale", movedToDlq: false };
+            }
+            _emit("system.queue.consume.success", {
+              metadata: { queue: queueName, backend: backend.name, jobId: job.jobId, attempt: job.attempts, traceId: job.traceId },
+            });
+            observability.event("queue.complete", 1, { queueName: queueName });
+            // `status`, not `outcome` — `outcome` is the audit-event
+            // vocabulary (success / failure / denied) and this is the job's
+            // terminal state for the caller, not an audit row.
+            return { status: "succeeded", movedToDlq: false };
+          });
+        }, function (err) {
+          var msg = (err && err.message) || String(err);
+          var willRetry = job.attempts < job.maxAttempts;
+          return backend.fail(job.jobId, msg, { retryDelayMs: _backoffDelay(job.attempts), attempt: job.attempts })
+            .then(function (settled) {
+              // Same fence as complete(): a false answer means the job was
+              // re-leased under this worker, so this failure did not land.
+              // Emitting the failure — or worse, the DLQ write — would report
+              // a terminal state for a job that is running elsewhere.
+              if (settled === false) {
+                observability.event("queue.stale", 1, { queueName: queueName });
+                return { status: "stale", movedToDlq: false };
+              }
+              observability.event("queue.fail", 1, { queueName: queueName, willRetry: willRetry });
+              _emit("system.queue.consume.failure", {
+                metadata: {
+                  queue:    queueName, backend: backend.name, jobId: job.jobId,
+                  attempt:  job.attempts, traceId: job.traceId,
+                  maxAttempts: job.maxAttempts, willRetry: willRetry,
+                },
+                reason:   msg,
+                outcome:  "failure",
+              });
+              // DLQ-write event when the job has exhausted its retries.
+              // Operators wire this to their alerting / dashboards —
+              // failed-after-retries is "needs human review" not "in the
+              // normal flow." The audit chain captures the final state.
+              if (!willRetry) {
+                _emit("system.queue.dlq.write", {
+                  metadata: {
+                    queue: queueName, backend: backend.name, jobId: job.jobId,
+                    attempts: job.attempts, traceId: job.traceId,
+                  },
+                  reason:  msg,
+                  outcome: "failure",
+                });
+              }
+              return { status: "failed", movedToDlq: !willRetry };
+            });
+        });
+    }
+  );
+}
+
+/**
+ * @primitive b.queue.tick
+ * @signature b.queue.tick(opts)
+ * @since     0.18.43
+ * @status    stable
+ * @related   b.queue.consume, b.queue.enqueue, b.queue.dlqList
+ *
+ * Drain what is due, then return. Leases at most `max` available jobs, runs
+ * `handler` over them, applies the same leasing, deterministic backoff and
+ * dead-letter transitions `b.queue.consume` applies, and settles. Nothing is
+ * left running when the promise resolves: no resident loop, no timer, no
+ * consumer registered for shutdown to wait on.
+ *
+ * Pair it with `b.queue.init({ sweepIntervalMs: 0 })`. `init` otherwise starts
+ * a 30-second expired-lease sweep timer, and in a frozen isolate that timer
+ * either never fires or fires inside a later invocation, touching the backend
+ * outside any request the platform is accounting for. `tick` sweeps once per
+ * invocation itself, so the timer buys nothing there.
+ *
+ * This is the driver for a scheduled invocation — a Cloudflare `scheduled()`
+ * handler, a Lambda on EventBridge, a Kubernetes CronJob. `consume` cannot
+ * serve those: it is a resident loop and it starts a background sweep, and such
+ * a runtime freezes between invocations, so the timer never fires and the
+ * consumer is either blocking the handler or killed mid-lease. Without a
+ * per-tick entry point the durable half — attempt accounting, backoff schedule,
+ * DLQ transition — gets reimplemented by the caller, which is the part that is
+ * genuinely hard to get right.
+ *
+ * Returns `{ leased, succeeded, failed, stale, unsettled, movedToDlq,
+ * mayHaveMore, queueDepth }`.
+ *
+ * Two of those counts are not terminal states and mean different things.
+ * `stale` is benign: the backend answered that this worker no longer owns the
+ * job, so someone else is running it. `unsettled` is not: the backend REFUSED
+ * to record the outcome — complete or fail rejected after its own retries — so
+ * the job is still inflight and this tick does not know whether the handler
+ * succeeded. Those are recovered by a later sweep, and if the handler had
+ * already succeeded its side effects run a second time, so a non-zero
+ * `unsettled` is worth alerting on rather than counting as noise.
+ *
+ * `mayHaveMore` is the tick-again signal: the batch came back full, so more
+ * may be due right now. Loop on that, not on a depth count — `queueDepth` is
+ * the queue's total active depth (pending plus inflight) and includes jobs
+ * whose `availableAt` is still in the future, so a caller looping on it would
+ * spin through empty ticks waiting for a delayed job to come due. `queueDepth`
+ * is `null` when the backend could not be asked: unknown is not empty.
+ *
+ * `stale` counts jobs this tick ran but did not settle: the handler outlived
+ * the lease, the job was swept and re-leased, and the backend's attempt fence
+ * refused the completion. Those are not failures — another worker owns them —
+ * and a non-zero `stale` means `leaseMs` is too short for the handler, or the
+ * batch too large to finish inside it.
+ *
+ * Jobs run sequentially by default. Pass `concurrency` to overlap them; the
+ * lease is held for `leaseMs` either way, so a batch that will take longer than
+ * the lease should either raise `leaseMs` or call `ctx.extendLease(ms)` from
+ * the handler.
+ *
+ * @opts
+ *   queue:       string,     // required — the queue name to drain
+ *   handler:     function,   // required — (job, ctx) => Promise, same as consume
+ *   max:         number,     // default: 10 — most jobs to lease this tick
+ *   leaseMs:     number,     // default: 30s — lease duration for the batch
+ *   concurrency: number,     // default: 1 — jobs run in parallel
+ *   backend:     string,     // named backend; default the init default
+ *
+ * @example
+ *   var result = await b.queue.tick({
+ *     queue:   "webhooks",
+ *     max:     50,
+ *     handler: async function (job) { await deliver(job.payload); },
+ *   });
+ *   while (result.mayHaveMore) result = await b.queue.tick({ queue: "webhooks", max: 50, handler: deliver });
+ *   // → { leased: 50, succeeded: 48, failed: 2, stale: 0, unsettled: 0,
+ *   //     movedToDlq: 1, mayHaveMore: true, queueDepth: 62 }
+ */
+async function tick(opts) {
+  _requireInit();
+  opts = opts || {};
+  var queueName = opts.queue;
+  if (!queueName) throw _err("MISSING_QUEUE", "tick requires opts.queue", true);
+  if (typeof opts.handler !== "function") {
+    throw _err("INVALID_HANDLER", "tick requires opts.handler to be a function", true);
+  }
+  var max = opts.max === undefined ? 10 : opts.max;
+  if (!numericChecks.isPositiveInt(max)) {
+    throw _err("BAD_MAX", "tick({ max }) must be a positive integer, got " + JSON.stringify(opts.max), true);
+  }
+  var leaseMs = opts.leaseMs === undefined ? C.TIME.seconds(30) : opts.leaseMs;
+  if (!numericChecks.isPositiveInt(leaseMs)) {
+    throw _err("BAD_LEASE", "tick({ leaseMs }) must be a positive integer, got " + JSON.stringify(opts.leaseMs), true);
+  }
+  var concurrency = opts.concurrency === undefined ? 1 : opts.concurrency;
+  if (!numericChecks.isPositiveInt(concurrency)) {
+    throw _err("BAD_CONCURRENCY", "tick({ concurrency }) must be a positive integer, got " + JSON.stringify(opts.concurrency), true);
+  }
+
+  var backend = _backendFor(opts);
+  // Same boundary b.queue.consume has: the framework-side lifecycle (lease by
+  // count, complete/fail by jobId, framework backoff and DLQ) is what `local`
+  // and `redis` implement. `sqs` is a different model — lease returns a
+  // receiptHandle the caller must thread back, redelivery and the dead-letter
+  // queue are the SQS queue's own RedrivePolicy — so driving it through here
+  // would call complete/fail without the receipt, leave every handled message
+  // in the queue, and let SQS redeliver work that already succeeded. Refuse
+  // rather than do that quietly; an SQS consumer drives lease/complete/fail
+  // directly, as lib/queue-sqs.js documents.
+  if (backend.protocol === "sqs") {
+    throw _err("TICK_UNSUPPORTED",
+      "queue.tick does not drive the 'sqs' protocol: SQS completes and fails by " +
+      "receiptHandle and owns redelivery + DLQ server-side. Drive it directly " +
+      "(lease -> handle -> complete/fail) as lib/queue-sqs.js describes.", true);
+  }
+  // Recover abandoned leases before taking a batch. A job whose holder died
+  // between leasing and completing sits in `inflight` until something re-pends
+  // it, and the thing that normally does is the 30-second sweep timer started
+  // at init — a timer that never fires in the runtime tick exists for, because
+  // the isolate is frozen between invocations. Without this, an invocation
+  // killed mid-lease strands its job permanently in exactly the deployment
+  // this driver serves. Best-effort: a sweep failure must not stop the tick
+  // from doing the work it can still do.
+  if (backend.sweepExpired) {
+    try { await backend.sweepExpired(); }
+    catch (e) { log.debug("tick-sweep-failed", { op: "sweepExpired", queue: queueName, error: e.message }); }
+  }
+  var jobs = await backend.lease(queueName, leaseMs, max);
+  jobs = jobs || [];
+
+  var result = {
+    leased:      jobs.length,
+    succeeded:   0,
+    failed:      0,
+    stale:       0,
+    unsettled:   0,
+    movedToDlq:  0,
+    // The batch came back full, so there may be more due right now. This is
+    // the tick-again signal: it is exact, free, and unlike a depth count it
+    // cannot be fooled by jobs that are not yet available.
+    mayHaveMore: jobs.length === max,
+    queueDepth:  0,
+  };
+  var next = 0;
+  async function worker() {
+    while (next < jobs.length) {
+      var job = jobs[next++];
+      observability.event("queue.lease", 1, { queueName: queueName });
+      _emit("system.queue.consume.start", {
+        metadata: { queue: queueName, backend: backend.name, jobId: job.jobId, attempt: job.attempts, traceId: job.traceId },
+      });
+      var settled;
+      try { settled = await _runJob(backend, queueName, job, opts.handler); }
+      catch (e) {
+        // A throw here is the BACKEND refusing to record the outcome —
+        // complete or fail rejected after its own retries. The job's state was
+        // never changed, so it is still inflight and this tick does not know
+        // whether the handler succeeded. Calling that a handler failure would
+        // be wrong twice: it reports a terminal state the job never reached,
+        // and it hides an infrastructure problem inside an ordinary tally.
+        // Report it as unsettled; a later sweep re-pends the job.
+        log.debug("tick-settle-failed", { op: "_runJob", queue: queueName, jobId: job.jobId, error: e.message });
+        settled = { status: "unsettled", movedToDlq: false };
+      }
+      if (settled && settled.status === "stale") result.stale += 1;
+      else if (settled && settled.status === "unsettled") result.unsettled += 1;
+      else if (settled && settled.status === "succeeded") result.succeeded += 1;
+      else result.failed += 1;
+      if (settled && settled.movedToDlq) result.movedToDlq += 1;
+    }
+  }
+  var workers = [];
+  for (var w = 0; w < Math.min(concurrency, jobs.length); w++) workers.push(worker());
+  await Promise.all(workers);
+
+  // Depth AFTER the batch. This is the queue's total active depth — pending
+  // plus inflight — and it deliberately does NOT drive the tick-again
+  // decision: it counts jobs whose availableAt is still in the future, so a
+  // caller looping on it would spin through empty ticks waiting for a delayed
+  // job to come due. null when the backend could not be asked; unknown is not
+  // the same as empty.
+  try { result.queueDepth = await size(queueName, opts); }
+  catch (e) {
+    log.debug("tick-size-failed", { op: "size", queue: queueName, error: e.message });
+    result.queueDepth = null;
+  }
+  return result;
+}
+
 /**
  * @primitive b.queue.size
  * @signature b.queue.size(queueName, opts)
@@ -1064,6 +1307,7 @@ module.exports = {
   enqueue:            enqueue,
   enqueueFlow:        enqueueFlow,
   consume:            consume,
+  tick:               tick,
   size:               size,
   purge:              purge,
   shutdown:           shutdown,
@@ -1074,4 +1318,8 @@ module.exports = {
   PROTOCOLS:          dispatcher.protocols,
   DEFERRED_PROTOCOLS: dispatcher.deferred,
   _resetForTest:      _resetForTest,
+  // Internal — the wrapped backend object, so a test can break one of its
+  // lifecycle calls (an exhausted breaker, an unreachable store) and assert
+  // what the drivers do about it. There is no other way to reach that path.
+  _backendForTest:    _backendFor,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.18.42",
+  "version": "0.18.43",
   "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:035db9d2-b000-46ab-bdef-fe4bff353228",
+  "serialNumber": "urn:uuid:a214f954-8702-46e7-819d-20eb98e5ca08",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-20T17:21:22.951Z",
+    "timestamp": "2026-08-20T20:10:05.952Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.18.42",
+      "bom-ref": "@blamejs/core@0.18.43",
       "type": "application",
       "name": "blamejs",
-      "version": "0.18.42",
+      "version": "0.18.43",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.18.42",
+      "purl": "pkg:npm/%40blamejs/core@0.18.43",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.18.42",
+      "ref": "@blamejs/core@0.18.43",
       "dependsOn": []
     }
   ]