@blamejs/core 0.6.22 → 0.6.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.24** (2026-05-02) — `b.logStream` gains an OTLP/HTTP-JSON sink. `protocol: "otlp"` now forwards log records to any OpenTelemetry collector via the OTel Logs Data Model — `resourceLogs` → `scopeLogs` → `logRecords` envelope with `severityNumber` (debug=5/info=9/warn=13/error=17), `severityText`, `timeUnixNano` (string-encoded for JSON-safe 64-bit), `body.stringValue`, and OTel-typed attributes. Operator config: `{ url, serviceName, serviceVersion, resourceAttributes, auth, headers, batchSize, retry, onDrop, ... }` — same back-pressure semantics as the webhook sink (per-sink ring buffer, batched flush on size or maxBatchAgeMs, exponential-backoff retry, drop-on-overflow with operator-supplied onDrop callback). URL convention: `/v1/logs` is auto-appended when the operator passes the collector root. JSON not protobuf — operators benchmarking >100K logs/s ship the OTel Collector locally so the framework hands JSON to a sidecar that forwards via gRPC. Removed `otlp` from `DEFERRED_PROTOCOLS`. Wiki observability page documents the new sink with a `b.logStream.init` example pointing at an OTel collector. Tests cover URL resolution, attribute encoding (string / int / float / bool / array / nested object), severity mapping, round-trip via mock collector, auth header pass-through, retry on 5xx + drop on retry-exhaustion, buffer overflow, dispatcher integration. Verified 0 leaks across 291 commits via `gitleaks`.
+- **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/README.md

@@ -47,7 +47,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), DNS with IPv6 / DoH / DoT / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
-- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
+- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
 - **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).
 - **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles with pre-flush fail-closed mode (`b.backup`); restore with pulled-bundle footprint preflight (`b.restore`); GDPR / PCI / HIPAA-shaped retention rules with multi-stage warn → archive → erase, legal-hold exemptions, dry-run preview, cross-table cascade (`b.retention`).

package/lib/log-stream-otlp.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * OTLP/HTTP-JSON log sink — OpenTelemetry Protocol logs over HTTP/JSON.
+ *
+ * Per the OTLP spec (v1.3+, Logs Data Model), log records are wrapped in
+ * a ResourceLogs envelope and POSTed to the operator's collector
+ * endpoint. Marshalling is OTel-native: timeUnixNano (string), severity
+ * mapping per OTel spec, attribute typing.
+ *
+ * Operator config:
+ *
+ *   {
+ *     url:                 "https://otel-collector.example.com:4318/v1/logs"
+ *                          // OR the collector root — "/v1/logs" auto-appended
+ *     headers:             { ... }   // additional headers (api keys, tenant ids)
+ *     auth:                'none' | 'bearer' | 'basic' | 'header'
+ *     token / username+password
+ *     serviceName:         "my-service"   // emitted as resource service.name
+ *     serviceVersion:      "1.2.3"        // resource service.version
+ *     resourceAttributes:  { env: "prod", region: "us-east-1" }
+ *                          // additional resource attributes
+ *     scopeName:           "blamejs"      // instrumentation scope name
+ *     batchSize:           100
+ *     maxBatchAgeMs:       C.TIME.seconds(5)
+ *     timeoutMs:           C.TIME.seconds(30)
+ *     retry:               { maxAttempts, baseDelayMs, ... }
+ *     bufferLimit:         10000   // ring-buffer cap; drops oldest on overflow
+ *     onDrop:              function ({ reason, batch, error }) { ... }
+ *   }
+ *
+ * Severity mapping (per OTel Logs Data Model):
+ *   debug → 5 (DEBUG)
+ *   info  → 9 (INFO)
+ *   warn  → 13 (WARN)
+ *   error → 17 (ERROR)
+ *
+ * Endpoint convention: most OTel collectors expose:
+ *   <base>:4318/v1/logs   — HTTP/JSON path (per OTLP HTTP §4.5)
+ *   <base>:4317           — gRPC path (NOT supported here)
+ *
+ * If `url` ends in `/v1/logs` it's used as-is. If not, `/v1/logs` is
+ * appended (collector root → logs endpoint). Operators with a custom
+ * routing prefix pass the full URL.
+ *
+ * Why JSON not protobuf: protobuf needs a schema parser (vendored dep
+ * or hand-rolled). The OTLP/HTTP spec accepts both Content-Type:
+ * application/json and application/x-protobuf; the JSON variant is the
+ * "no extra deps" path consistent with the framework's vendoring stance.
+ * Operators benchmarking >100K logs/s ship the OTel Collector locally
+ * (collector → upstream gRPC) — this sink hands JSON to the local
+ * collector which forwards.
+ */
+var C = require("./constants");
+var retryHelper = require("./retry");
+var { LogStreamError } = require("./framework-error");
+var httpClient = require("./http-client");
+var safeUrl = require("./safe-url");
+var authHeader = require("./auth-header");
+
+var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
+
+// OTel Logs Data Model severity numbers.
+// https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+var SEVERITY = {
+  debug: { number: 5,  text: "DEBUG" },
+  info:  { number: 9,  text: "INFO"  },
+  warn:  { number: 13, text: "WARN"  },
+  error: { number: 17, text: "ERROR" },
+};
+
+var DEFAULTS = {
+  scopeName:     "blamejs",
+  batchSize:     100,
+  maxBatchAgeMs: C.TIME.seconds(5),
+  timeoutMs:     C.TIME.seconds(30),
+  bufferLimit:   10000,
+};
+
+var _err = LogStreamError.factory;
+
+function _resolveUrl(url) {
+  // If the URL already ends in "/v1/logs" (with or without trailing slash),
+  // use as-is. Otherwise treat as the collector root and append.
+  var trimmed = url.replace(/\/+$/, "");
+  if (/\/v1\/logs$/.test(trimmed)) return trimmed;
+  return trimmed + "/v1/logs";
+}
+
+function _authHeaders(config) {
+  if (config.auth === "header") return Object.assign({}, config.headers || {});
+  return authHeader.fromConfig(config);
+}
+
+// OTel attribute encoding — JSON form per OTLP spec. Each attribute is
+// { key: <name>, value: { <type>Value: <v> } } where the type field
+// matches the JS type at the boundary.
+function _encodeAttrValue(v) {
+  if (v === null || v === undefined) return null;
+  var t = typeof v;
+  if (t === "string")  return { stringValue: v };
+  if (t === "boolean") return { boolValue: v };
+  if (t === "number") {
+    if (Number.isInteger(v)) return { intValue: String(v) };       // OTLP int is string-encoded
+    return { doubleValue: v };
+  }
+  if (Array.isArray(v)) {
+    return { arrayValue: { values: v.map(function (e) { return _encodeAttrValue(e); }).filter(Boolean) } };
+  }
+  if (t === "object") {
+    return { kvlistValue: { values: _encodeAttrs(v) } };
+  }
+  return { stringValue: String(v) };
+}
+
+function _encodeAttrs(obj) {
+  if (!obj || typeof obj !== "object") return [];
+  return Object.keys(obj).map(function (k) {
+    var encoded = _encodeAttrValue(obj[k]);
+    if (!encoded) return null;
+    return { key: k, value: encoded };
+  }).filter(Boolean);
+}
+
+function _resourceAttrs(cfg) {
+  var attrs = {};
+  if (cfg.serviceName)    attrs["service.name"]    = cfg.serviceName;
+  if (cfg.serviceVersion) attrs["service.version"] = cfg.serviceVersion;
+  if (cfg.resourceAttributes && typeof cfg.resourceAttributes === "object") {
+    Object.assign(attrs, cfg.resourceAttributes);
+  }
+  return attrs;
+}
+
+function _toLogRecord(record) {
+  var sev = SEVERITY[record.level] || SEVERITY.info;
+  // OTel timeUnixNano is a string (JSON can't safely represent 64-bit ints).
+  var nanos = String(BigInt(record.ts) * 1000000n);
+  var attrs = record.meta ? _encodeAttrs(record.meta) : [];
+  return {
+    timeUnixNano:     nanos,
+    observedTimeUnixNano: nanos,
+    severityNumber:   sev.number,
+    severityText:     sev.text,
+    body:             { stringValue: record.message == null ? "" : String(record.message) },
+    attributes:       attrs,
+  };
+}
+
+function _serializeBatch(records, cfg, scopeVersion) {
+  var resourceAttrs = _resourceAttrs(cfg);
+  return Buffer.from(JSON.stringify({
+    resourceLogs: [
+      {
+        resource: {
+          attributes: _encodeAttrs(resourceAttrs),
+        },
+        scopeLogs: [
+          {
+            scope: {
+              name:    cfg.scopeName,
+              version: scopeVersion,
+            },
+            logRecords: records.map(_toLogRecord),
+          },
+        ],
+      },
+    ],
+  }), "utf8");
+}
+
+function _post(url, body, headers, timeoutMs, allowedProtocols, allowInternal) {
+  return httpClient.request({
+    method:           "POST",
+    url:              url,
+    headers:          headers,
+    body:             body,
+    idleTimeoutMs:    timeoutMs,
+    maxResponseBytes: MAX_RESPONSE_BYTES,
+    errorClass:       LogStreamError,
+    allowedProtocols: allowedProtocols,
+    allowInternal:    allowInternal,
+  });
+}
+
+function create(config) {
+  if (!config || !config.url) throw _err("BAD_OPT", "log-stream otlp requires { url }");
+  var cfg = Object.assign({}, DEFAULTS, config);
+  var resolvedUrl = _resolveUrl(cfg.url);
+  // Validate URL shape + scheme at create time. Default HTTPS-only;
+  // operators with an internal cleartext OTel collector pass
+  // cfg.allowedProtocols (safeUrl.ALLOW_HTTP_ALL).
+  safeUrl.parse(resolvedUrl, {
+    allowedProtocols: cfg.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
+    errorClass:       LogStreamError,
+  });
+  var scopeVersion = cfg.scopeVersion || (function () {
+    try { return require("../package.json").version; } catch (_e) { return "unknown"; }
+  })();
+  var headers = Object.assign({
+    "Content-Type": "application/json",
+    "Accept":       "application/json",
+  }, _authHeaders(cfg));
+  var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) { /* drop callback is best-effort */ }
+  }
+  var buffer = [];
+  var dropCount = 0;
+  var flushTimer = null;
+  var inFlight = false;
+  var closed = false;
+
+  function _scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(function () { flushTimer = null; _flush(); }, cfg.maxBatchAgeMs);
+    flushTimer.unref();
+  }
+
+  async function _flush() {
+    if (inFlight) return;
+    if (buffer.length === 0) return;
+    inFlight = true;
+    try {
+      while (buffer.length > 0 && !closed) {
+        var batch = buffer.splice(0, cfg.batchSize);
+        var body = _serializeBatch(batch, cfg, scopeVersion);
+        try {
+          await retryHelper.withRetry(function () {
+            return _post(resolvedUrl, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
+          }, cfg.retry);
+        } catch (e) {
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
+          break;
+        }
+      }
+    } finally {
+      inFlight = false;
+      if (buffer.length > 0) _scheduleFlush();
+    }
+  }
+
+  function emit(record) {
+    if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
+    if (buffer.length >= cfg.bufferLimit) {
+      var dropped = buffer.shift();
+      dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
+    }
+    buffer.push(record);
+    if (buffer.length >= cfg.batchSize) {
+      _flush().catch(function () {});
+    } else {
+      _scheduleFlush();
+    }
+    return Promise.resolve({ accepted: true, queued: buffer.length });
+  }
+
+  async function close() {
+    closed = true;
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    await _flush();
+  }
+
+  function stats() {
+    return {
+      queued:   buffer.length,
+      dropped:  dropCount,
+      inFlight: inFlight,
+      url:      resolvedUrl,
+    };
+  }
+
+  return {
+    protocol: "otlp",
+    emit:     emit,
+    close:    close,
+    stats:    stats,
+    flush:    _flush,
+  };
+}
+
+module.exports = {
+  create:       create,
+  // Exposed for tests + advanced operator wiring.
+  _resolveUrl:  _resolveUrl,
+  _encodeAttrs: _encodeAttrs,
+  _toLogRecord: _toLogRecord,
+  SEVERITY:     SEVERITY,
+};

package/lib/log-stream.js

@@ -4,12 +4,22 @@
  * redaction and bidirectional command channel.
  *
  * Same dispatcher pattern: backends configured per-name with a protocol
- * + protocol-specific options. Built-in protocols are 'local'
- * (append-only file with rotation) and 'webhook' (generic HTTP POST —
- * covers Splunk HEC, Datadog, Sumo Logic, Loki, custom). Specialized
- * adapters (syslog over TLS, OpenTelemetry OTLP, AWS CloudWatch,
- * Vector/Fluentd) are listed as deferred and surface a clear error
- * when selected.
+ * + protocol-specific options. Built-in protocols:
+ *
+ *   local    — append-only file with rotation
+ *   webhook  — generic HTTP POST; covers Splunk HEC, Datadog, Sumo
+ *              Logic, Loki, custom collectors that ingest JSON
+ *   otlp     — OpenTelemetry Protocol over HTTP/JSON; ResourceLogs
+ *              envelope with severity mapping per OTel Logs Data
+ *              Model. Operators with an OTel collector running
+ *              (k8s, cloud) get standard log forwarding without a
+ *              vendor-specific adapter.
+ *
+ * Adapters listed as deferred and surfacing a clear error when
+ * selected:
+ *
+ *   syslog     — RFC 5424 syslog over TLS
+ *   cloudwatch — AWS CloudWatch Logs (PutLogEvents)
  *
  * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
  * never reaches operational logs even on a misconfigured field name —
@@ -34,6 +44,7 @@
  */
 var localProto   = require("./log-stream-local");
 var webhookProto = require("./log-stream-webhook");
+var otlpProto    = require("./log-stream-otlp");
 var redactor     = require("./redact");
 var lazyRequire  = require("./lazy-require");
 var protocolDispatcher = require("./protocol-dispatcher");
@@ -42,10 +53,13 @@ var { LogStreamError } = require("./framework-error");
 var dispatcher = protocolDispatcher.create({
   name:       "log-stream",
   errorClass: LogStreamError,
-  protocols:  { "local": localProto, "webhook": webhookProto },
+  protocols:  {
+    "local":   localProto,
+    "webhook": webhookProto,
+    "otlp":    otlpProto,
+  },
   deferred:   {
     "syslog":     { description: "RFC 5424 syslog over TLS" },
-    "otlp":       { description: "OpenTelemetry Logs OTLP/HTTP" },
     "cloudwatch": { description: "AWS CloudWatch Logs (PutLogEvents)" },
   },
   fallbackProtocol: "local",

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.24",
   "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:aa9c8c0c-504f-4c75-87d4-297f40e4d752",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T07:32:02.459Z",
+    "timestamp": "2026-05-02T14:22:45.058Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.22",
+      "bom-ref": "@blamejs/core@0.6.24",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.22",
+      "version": "0.6.24",
       "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.24",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.22",
+      "ref": "@blamejs/core@0.6.24",
       "dependsOn": []
     }
   ]