@blamejs/core 0.7.97 → 0.7.98

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.98** (2026-05-06) — `b.ntpCheck.monitor({ intervalMs, ... })` — periodic clock-drift monitor that runs `checkDrift` on a schedule and emits audit + observability events on threshold crossings. Returns a handle with `.stop()` for graceful shutdown. Audit emissions: `system.ntp.checked` (every check), `system.ntp.drift_warn` (drift exceeds warn threshold), `system.ntp.drift_fatal` (drift exceeds fatal threshold), `system.ntp.unreachable` (every server in the list failed to respond). Observability event: `ntp.drift_ms` gauge on every successful check, labeled with the responding server. Optional `onDrift(result)` operator hook fires on every warning/fatal check so operators can wire pager / Slack notifications. The previous boot-time-only `b.ntpCheck.bootCheck` continues to run unchanged at db.init; the monitor is for long-running deployments where clock-drift can develop after boot (container with no RTC sync, ntpd stopped after boot, etc.). Closes the v0.7.79 audit-batch slice for continuous time integrity.
+
 - **0.7.97** (2026-05-06) — `b.compliance` lookup helpers. **`b.compliance.posturesByDomain(domain)`** returns every posture matching the named domain (`"privacy"` / `"health"` / `"payment"` / `"cybersecurity"` / `"financial-reporting"` / `"financial-resilience"` / `"product-cybersecurity"` / `"ai-governance"` / `"biometrics"` / `"audit-attestation"`). **`b.compliance.posturesByJurisdiction(jurisdiction)`** returns postures matching the ISO 3166 alpha-2 code, `EU`, or `international` — useful for multi-region deployments that resolve different posture configs per region. **`b.compliance.list()`** returns every posture as a `{ posture, name, citation, jurisdiction, domain }` row in canonical `KNOWN_POSTURES` order — admin UIs render the full set as a dropdown / table without iterating REGIME_MAP keys themselves. All three helpers are pure functions over the v0.7.94 REGIME_MAP and stay in sync with it as new postures land.
 
 - **0.7.96** (2026-05-06) — `b.observability.timed(name, fn, labels)` — convenience wrapper that measures wall-clock duration of a sync or async operation and emits a counter event carrying `duration_ms` in the labels alongside `outcome: "ok" | "fail"`. Returns the wrapped function's return value verbatim; rethrows on error after emitting the failure event with `error_type` capturing the thrown error's `.name`. Operators previously hand-rolled `var t0 = Date.now(); var r = await fn(); event(name, 1, { ...labels, duration_ms: Date.now() - t0, outcome: "ok" })` patterns at every call site — `timed` is the consolidated form. Composes with the existing `b.observability.SEMCONV` constants: `b.observability.timed("db.query", async () => db.query("SELECT ..."), { [SEMCONV.DB_OPERATION_NAME]: "select" })`. Operation name MUST be a stable string (not derived from input) to keep metric cardinality bounded; dynamic per-tenant labels go in the `labels` parameter.

package/lib/ntp-check.js

@@ -27,6 +27,11 @@
  */
 var dgram = require("dgram");
 var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var safeAsync = require("./safe-async");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
 
 // NTP epoch: 1900-01-01. Unix epoch: 1970-01-01. Offset: 70 years incl. 17
 // leap days = 2,208,988,800 seconds.
@@ -227,10 +232,81 @@ async function bootCheck(opts) {
   };
 }
 
+// Periodic drift monitor — runs checkDrift on a schedule and emits
+// audit + observability events on threshold crossings. Returns a
+// handle with `.stop()` for graceful shutdown.
+//
+//   var mon = b.ntpCheck.monitor({
+//     intervalMs:    C.TIME.minutes(15),
+//     servers:       ["time.cloudflare.com", "pool.ntp.org"],
+//     driftWarnMs:   C.TIME.seconds(2),
+//     driftFatalMs:  C.TIME.seconds(30),
+//     onDrift: function (result) { /* operator hook — drift > warn */ },
+//   });
+//   ...
+//   await mon.stop();
+//
+// Audit emissions:
+//   system.ntp.checked     — every check, success or fail
+//   system.ntp.drift_warn  — drift exceeds warn threshold
+//   system.ntp.drift_fatal — drift exceeds fatal threshold
+//   system.ntp.unreachable — every server in the list failed to respond
+//
+// Observability events: ntp.drift_ms (gauge) on every successful check.
+function monitor(opts) {
+  opts = opts || {};
+  var intervalMs = opts.intervalMs || C.TIME.minutes(15);
+  var auditOn = opts.audit !== false;
+  if (typeof intervalMs !== "number" || !isFinite(intervalMs) || intervalMs <= 0) {
+    throw new TypeError("ntpCheck.monitor: intervalMs must be a positive finite number");
+  }
+
+  function _emit(action, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  metadata && metadata.severity === "fatal" ? "fail" : "ok",
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  async function _tick() {
+    var res;
+    try { res = await bootCheck(opts); }
+    catch (e) {
+      _emit("system.ntp.checked", { severity: "fatal", error: (e && e.message) || String(e) });
+      return;
+    }
+    if (res.driftMs === null) {
+      _emit("system.ntp.unreachable", { severity: "warning", message: res.message });
+      return;
+    }
+    try { observability().safeEvent("ntp.drift_ms", res.driftMs, { server: res.server || "unknown" }); }
+    catch (_e) { /* drop-silent */ }
+    _emit("system.ntp.checked", { severity: res.severity, driftMs: res.driftMs, server: res.server });
+    if (res.severity === "fatal") {
+      _emit("system.ntp.drift_fatal", { driftMs: res.driftMs, server: res.server });
+    } else if (res.severity === "warning") {
+      _emit("system.ntp.drift_warn", { driftMs: res.driftMs, server: res.server });
+    }
+    if (typeof opts.onDrift === "function" && res.severity !== "info") {
+      try { await opts.onDrift(res); } catch (_e) { /* operator hook — drop-silent */ }
+    }
+  }
+
+  var handle = safeAsync.repeating(_tick, intervalMs, { name: "ntp-monitor" });
+  return {
+    stop: function () { if (handle) { handle.stop(); handle = null; } },
+  };
+}
+
 module.exports = {
   querySingle:               querySingle,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
+  monitor:                   monitor,
   setThresholds:             setThresholds,
   getThresholds:             getThresholds,
   DEFAULT_SERVERS:           DEFAULT_SERVERS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.97",
+  "version": "0.7.98",
   "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:55086519-816f-48aa-8cc1-ab945665d119",
+  "serialNumber": "urn:uuid:387ca63b-9d87-46d5-a7a5-ff7e577e0bd3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T08:53:19.996Z",
+    "timestamp": "2026-05-06T09:03:18.727Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.97",
+      "bom-ref": "@blamejs/core@0.7.98",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.97",
+      "version": "0.7.98",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.97",
+      "purl": "pkg:npm/%40blamejs/core@0.7.98",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.97",
+      "ref": "@blamejs/core@0.7.98",
       "dependsOn": []
     }
   ]