@blamejs/core 0.6.22 → 0.6.23

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.23** (2026-05-02) — v0.6.22 follow-up cleanup. The cron-repeat call site in queue-local.js was passing both `availableAt` AND `delaySeconds` (the former was the precise next-fire ms; the latter was a redundant `Math.floor((nextMs - nowMs) / 1000)` computation that only existed to work around the bug v0.6.22 fixed). Dropped — the cron repeat now passes `availableAt` alone, matching the queue's documented precedence rule. The enqueue() docstring gains a 20-line "SCHEDULING PRECEDENCE" header documenting that `opts.availableAt` wins over `opts.delaySeconds` when both are passed, why the framework chose that direction, and which callers should use which form. New round-trip preservation regression test (`testEnqueueRoundTripsAvailableAt`) covers three precise targets, the delaySeconds-only path, and the both-opts-set case — gates against any future "I'll just rederive it from the floored seconds" mistake. Audited the rest of the framework for the same `(absolute-time, relative-time)` opt-overlap shape (cache.set, session.rotate, apiKey, dualControl): queue is the only primitive carrying both forms, so a generalized `b.time.resolveTimePoint` primitive would be premature with one call site.
 - **0.6.22** (2026-05-02) — `b.queue.enqueue({ availableAt })` is now honoured. Previously the local-protocol enqueue() ignored opts.availableAt entirely, recomputing from `Date.now() + delaySeconds*1000`. The cron-repeat path passes both fields (the exact next-fire ms in availableAt + the floored seconds in delaySeconds), and the enqueue's recomputation lost sub-second precision plus drifted on the internal clock-vs-caller delta. Symptoms: cron-scheduled jobs landed up to 999ms off the intended boundary; the queue-flow-repeat smoke test was intermittently flaky on slow CI runners (caught by ubuntu-latest on the v0.6.21 commit). Fix: enqueue() honours opts.availableAt directly when finite; falls back to delaySeconds-based shorthand otherwise. Operators relying on `enqueue({ availableAt: T })` for non-cron scheduled jobs (e.g. "deliver this notification at exactly 09:00 tomorrow") now get the requested time instead of nowMs+0.
 - **0.6.21** (2026-05-02) — closes the medium / low audit findings flagged after v0.6.18. **Cluster cache `invalidateTag`** now actually works — the cluster backend gained a `_blamejs_cache_tags` junction table (`(cacheKey, tag)` PK + index on `tag`), tag-aware `set` / `del` / `clear` / `_sweep`, plus `getTags(key)`. The old NOT_SUPPORTED-on-cluster path is gone; multi-tag rotation, mid-flight tag replacement on update, and namespace-scoped sweeps all covered. **Multi-column cursor pagination** — `b.pagination.cursor({ orderBy: [{column,direction},...] })` accepts a string (single column), an array of strings (multi, all using `opts.direction`), or an array of `{column,direction}` objects (mixed directions). The keyset WHERE expands to the standard OR cascade so successive pages can't skip or repeat rows when ties on the leading columns are broken by trailing ones. `_id` is appended as a tiebreaker if not in the chain. The Query class also gained chained `orderBy(col, dir)` calls — second-and-later calls extend a multi-column ORDER BY in the SQL. Cursor format is bumped to encode `{ orderKey, vals, forward }` instead of the old `{ orderBy, dir, orderByVal, id, forward }` — pre-1.0 break, no compat shim. **DoH POST mode** (RFC 8484 §4.1) — `b.network.dns.useDnsOverHttps({ method })` accepts `"GET" | "POST" | undefined` (auto). Auto switches to POST when the GET URL would exceed 2048 bytes (long DNS names). **DoT connection pooling** — per-`(host:port)` cached TLS socket with a 2-minute idle timeout, serialized in-flight queries per socket. Eliminates the per-query handshake. **INI parser** shipped as `b.parsers.ini` — covers Windows .ini / .gitconfig / systemd-unit / php.ini / tox.ini shape: sections (incl. `[parent.child]` / `[parent "child"]` nesting), `;` and `#` comments (inline + leading), single + double quoting with `\n` `\t` `\\` `\"` `\'` escapes, boolean coercion (`true`/`false`/`yes`/`no`/`on`/`off`), decimal + hex integers + floats. Prototype-pollution defense (`__proto__` / `constructor` / `prototype` rejected). Duplicate-key policy throws by default; `onDuplicate: "first" | "last"` opts in to silent shadowing. Section / per-section key / value-bytes caps configurable. **Cookie-jar file persistence** — `b.httpClient.cookieJar.create({ persist: "file", file: "/abs/path", vault: b.vault })` loads at construct, debounce-flushes on every set/clear, plus `flush()` and `close()` for explicit lifecycle. With `vault`, on-disk bytes are sealed; without, plaintext JSON (operator chooses). **Comment cleanups per rule §4** — `vault/index.js` stale `// later` removed, `mail.js` "future patch" wording rewritten as scope, `bundler.js` "What it does NOT do today (deliberately deferred)" rewritten as "Out of scope", `archive.js` "v1 scope cuts (deferred)" rewritten as "Out of scope", `framework-schema.js` "next release" wording rewritten to describe what's actually shipped, `http-client.js` "out of reach today" / "we'll plumb it through when h3 lands" rewritten as scope statements. **README CLI section** updated to reflect the v0.6.17 + v0.6.18 + v0.6.19 + v0.6.20 additions (security / config-drift / file-type / password / erase / retention) — was missing 6 subcommands.
 - **0.6.20** (2026-05-02) — CI / packaging fix-up. The npm-publish workflow's "Attach SBOM as release asset" step started failing with HTTP 422 ("Cannot upload assets to an immutable release") because the operator's manual `gh release create` had already been published when the workflow ran. Two changes: (1) `sbom.cyclonedx.json` is now bundled into the npm tarball (`files` block in package.json), so `npm install @blamejs/core && cat node_modules/@blamejs/core/sbom.cyclonedx.json` is the canonical SBOM access path. The prepack guard's known-allowed list covers the just-in-time generation. (2) The workflow's GH-release-attach step is now non-fatal: it tries to upload, logs a warning if the release is immutable, and lets the publish proceed regardless. The npm tarball is the load-bearing artifact; the GitHub release attachment was only ever supplementary. `.gitignore` adds `sbom.cyclonedx.json` so a stray local `npm sbom` doesn't pollute the repo.

package/lib/queue-local.js

@@ -109,12 +109,24 @@ function create(_config) {
     cluster.requireLeader();
     opts = opts || {};
     var nowMs = Date.now();
-    // Caller-supplied opts.availableAt wins (cron-repeat pre-computes
-    // the exact next-fire ms). delaySeconds is the operator-shorthand
-    // alternative — used when opts.availableAt isn't provided. Falling
-    // through delaySeconds without honouring an explicit availableAt
-    // loses sub-second precision (delaySeconds is integer-floored)
-    // and drifts on the internal clock vs the caller's intended ms.
+    // ----------------------------------------------------------------------
+    // SCHEDULING PRECEDENCE — the contract for every queue.enqueue caller
+    // ----------------------------------------------------------------------
+    // The queue accepts TWO ways to express "when should this job run":
+    //   - opts.availableAt  (absolute unix-ms)   — precise, framework-internal
+    //   - opts.delaySeconds (integer seconds)    — operator shorthand
+    //
+    // PRECEDENCE: opts.availableAt wins when finite. Operators passing both
+    // get the absolute value; the relative form is computed from
+    // Date.now() and is therefore strictly less precise (loses sub-second
+    // resolution AND drifts on the internal-clock-vs-caller delta).
+    //
+    // If you're a caller computing a precise time (cron-repeat,
+    // scheduler.scheduleAt, notify.deferUntil), pass opts.availableAt
+    // ONLY. Don't pass both — the second one is noise (and was the
+    // shape that caused the v0.6.21 silent-drift bug). If you only have
+    // a relative offset, pass opts.delaySeconds ONLY.
+    // ----------------------------------------------------------------------
     var availableAt;
     if (typeof opts.availableAt === "number" && isFinite(opts.availableAt)) {
       availableAt = opts.availableAt;
@@ -259,8 +271,12 @@ function create(_config) {
         await enqueue(unsealedRow.queueName,
           unsealedRow.payload ? safeJson.parse(unsealedRow.payload) : null,
           {
+            // availableAt is the precise next-fire ms — pass it alone.
+            // Don't also pass delaySeconds (the v0.6.22 / v0.6.23 fix
+            // codified that opts.availableAt wins, but mixing both is
+            // the shape that masked the silent-drift bug; keep this
+            // call site clean as documentation by example).
             availableAt:     nextMs,
-            delaySeconds:    Math.max(0, Math.floor((nextMs - nowMs) / 1000)),
             repeat:          { cron: unsealedRow.repeatCron, timezone: unsealedRow.repeatTimezone },
             priority:        Number(unsealedRow.priority) || 0,
             classification:  unsealedRow.classification || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.22",
+  "version": "0.6.23",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:2dcbd08d-cbaf-408b-8b68-8982ea425a0f",
+  "serialNumber": "urn:uuid:47563cfb-199b-4000-ba99-0e3102e87442",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T07:32:02.459Z",
+    "timestamp": "2026-05-02T14:07:01.711Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.22",
+      "bom-ref": "@blamejs/core@0.6.23",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.22",
+      "version": "0.6.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.22",
+      "purl": "pkg:npm/%40blamejs/core@0.6.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.22",
+      "ref": "@blamejs/core@0.6.23",
       "dependsOn": []
     }
   ]