@blamejs/core 0.7.96 → 0.7.98

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - **0.7.95** (2026-05-06) — `b.observability.SEMCONV` GenAI + cloud + container coverage. Twenty-eight new attribute names tracking OpenTelemetry semantic conventions for generative AI workloads, vector databases, cloud runtime context, and Kubernetes orchestration. **GenAI:** `GEN_AI_SYSTEM` / `GEN_AI_REQUEST_MODEL` / `GEN_AI_REQUEST_TEMPERATURE` / `GEN_AI_REQUEST_TOP_P` / `GEN_AI_REQUEST_TOP_K` / `GEN_AI_REQUEST_MAX_TOKENS` / `GEN_AI_REQUEST_STOP_SEQUENCES` / `GEN_AI_RESPONSE_MODEL` / `GEN_AI_RESPONSE_ID` / `GEN_AI_RESPONSE_FINISH_REASONS` / `GEN_AI_USAGE_INPUT_TOKENS` / `GEN_AI_USAGE_OUTPUT_TOKENS` / `GEN_AI_USAGE_TOTAL_TOKENS` / `GEN_AI_OPERATION_NAME` / `GEN_AI_TOOL_NAME` / `GEN_AI_TOOL_CALL_ID` / `GEN_AI_AGENT_ID` / `GEN_AI_AGENT_NAME` / `GEN_AI_AGENT_DESCRIPTION`. **Vector DB / RAG:** `DB_VECTOR_QUERY_TOP_K` / `DB_VECTOR_QUERY_DIMENSIONS` / `DB_VECTOR_QUERY_DISTANCE_METRIC`. **Cloud:** `CLOUD_PROVIDER` / `CLOUD_REGION` / `CLOUD_ACCOUNT_ID` / `CLOUD_RESOURCE_ID`. **Container / K8s:** `CONTAINER_ID` / `CONTAINER_IMAGE_NAME` / `CONTAINER_IMAGE_TAG` / `K8S_NAMESPACE_NAME` / `K8S_POD_NAME` / `K8S_DEPLOYMENT_NAME`. Operators wiring LLM client telemetry, vector-DB query traces, or Kubernetes-deployed services to an OTel collector reference these constants directly — string typos throw at access time instead of producing mis-named span attributes the OTel collector silently drops.

package/lib/compliance.js

@@ -245,14 +245,68 @@ function describe(posture) {
   return REGIME_MAP[posture] || null;
 }
 
+// posturesByDomain — list every posture that maps to the named
+// domain (privacy / health / payment / cybersecurity / etc.).
+// Operators rendering compliance dashboards grouped by domain pull
+// the per-domain posture list with this; admin UIs that show "we
+// satisfy the privacy regimes for {users.country}" use it to pick
+// the right posture name without hand-rolling the lookup.
+function posturesByDomain(domain) {
+  if (typeof domain !== "string" || domain.length === 0) return [];
+  var out = [];
+  var keys = Object.keys(REGIME_MAP);
+  for (var i = 0; i < keys.length; i++) {
+    if (REGIME_MAP[keys[i]].domain === domain) out.push(keys[i]);
+  }
+  return out;
+}
+
+// posturesByJurisdiction — same shape, keyed off the ISO 3166 alpha-2
+// code or `EU` / `international`. Operators handling a multi-region
+// deployment (e.g. one that serves users in EU + CA + JP) iterate
+// over jurisdiction codes and resolve to per-jurisdiction posture
+// configs without hand-rolling the lookup table.
+function posturesByJurisdiction(jurisdiction) {
+  if (typeof jurisdiction !== "string" || jurisdiction.length === 0) return [];
+  var out = [];
+  var keys = Object.keys(REGIME_MAP);
+  for (var i = 0; i < keys.length; i++) {
+    if (REGIME_MAP[keys[i]].jurisdiction === jurisdiction) out.push(keys[i]);
+  }
+  return out;
+}
+
+// list — returns every posture as a { name, ...regime-map-fields }
+// object array, in canonical KNOWN_POSTURES order. Useful for admin
+// UIs that render the full set as a dropdown / table.
+function list() {
+  var out = [];
+  for (var i = 0; i < KNOWN_POSTURES.length; i++) {
+    var p = KNOWN_POSTURES[i];
+    var meta = REGIME_MAP[p];
+    if (!meta) continue;
+    out.push({
+      posture:      p,
+      name:         meta.name,
+      citation:     meta.citation,
+      jurisdiction: meta.jurisdiction,
+      domain:       meta.domain,
+    });
+  }
+  return out;
+}
+
 module.exports = {
-  set:              set,
-  current:          current,
-  assert:           assert,
-  clear:            clear,
-  describe:         describe,
-  KNOWN_POSTURES:   KNOWN_POSTURES,
-  REGIME_MAP:       REGIME_MAP,
-  ComplianceError:  ComplianceError,
-  _resetForTest:    _resetForTest,
+  set:                    set,
+  current:                current,
+  assert:                 assert,
+  clear:                  clear,
+  describe:               describe,
+  posturesByDomain:       posturesByDomain,
+  posturesByJurisdiction: posturesByJurisdiction,
+  list:                   list,
+  KNOWN_POSTURES:         KNOWN_POSTURES,
+  REGIME_MAP:             REGIME_MAP,
+  ComplianceError:        ComplianceError,
+  _resetForTest:          _resetForTest,
 };

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.96",
+  "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:f930dea4-02bf-424a-81d9-af05bce63d00",
+  "serialNumber": "urn:uuid:387ca63b-9d87-46d5-a7a5-ff7e577e0bd3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T08:44:44.540Z",
+    "timestamp": "2026-05-06T09:03:18.727Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.96",
+      "bom-ref": "@blamejs/core@0.7.98",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.96",
+      "version": "0.7.98",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.96",
+      "purl": "pkg:npm/%40blamejs/core@0.7.98",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.96",
+      "ref": "@blamejs/core@0.7.98",
       "dependsOn": []
     }
   ]