@blamejs/core 0.7.94 → 0.7.96

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **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.
+
 - **0.7.94** (2026-05-06) — `b.compliance.REGIME_MAP` + `b.compliance.describe(<posture>)` — frozen lookup table mapping each posture name to its human-readable name + statutory citation + jurisdiction + domain. `b.compliance.describe("hipaa")` returns `{ name: "Health Insurance Portability and Accountability Act", citation: "Pub. L. 104-191; 45 CFR Parts 160, 162, 164", jurisdiction: "US", domain: "health" }`. Operators rendering the deployment posture in admin UI / audit logs reach for `REGIME_MAP[posture]` instead of hand-rolling a lookup table; values track the regulatory text and update with the framework rather than going stale in operator code. Covers all 19 postures shipped through v0.7.91 (hipaa / pci-dss / soc2 / sox + the v0.7.91 expansions: wmhmda / bipa / ccpa / gdpr / dora / nis2 / cra / ai-act / lgpd-br / pipl-cn / appi-jp / pdpa-sg / pipeda-ca / uk-gdpr). `domain` field categorizes the regime (privacy / health / payment / cybersecurity / financial-reporting / etc.) so operators can render compliance dashboards grouped by domain instead of alphabetical posture.
 
 - **0.7.93** (2026-05-06) — Adjacent-regulation incident-reporting deadline reference exported on `b.dora`. **`b.dora.DEADLINES_NIS2`** — NIS2 (Directive (EU) 2022/2555) Art. 23 deadlines: 24h early warning, 72h initial notification, 1 month final report. **`b.dora.DEADLINES_CRA`** — CRA (Regulation (EU) 2024/2847) Art. 14 deadlines: 24h early warning, 72h initial notification, 14 days final report. **`b.dora.DEADLINES_HIPAA_BREACH`** — HIPAA Breach Notification Rule (45 CFR §164.404 / §164.408) deadlines: 60 days for affected individuals, 60 days for HHS Secretary, annual aggregate report by March 1 for sub-500-individual breaches. Operators handling NIS2 / CRA / HIPAA reporting reach for these constants instead of pinning literal hour counts in their workflow code; the values track the regulatory text and update with the framework rather than going stale in operator code. The b.dora factory itself continues to enforce DORA Article 19 deadlines unchanged — operators wiring NIS2 / CRA / HIPAA workflows compose against the deadline constants directly with their own scheduler / submission code.

package/lib/observability.js

@@ -143,6 +143,57 @@ function safeEvent(name, value, labels) {
   catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
+// timed — convenience wrapper that measures wall-clock duration of a
+// sync or async operation and emits a counter event with
+// duration_ms in the labels. Returns the wrapped function's return
+// value verbatim; rethrows on error after emitting the failure event
+// with outcome: "fail".
+//
+//   var rows = await b.observability.timed("db.query", async function () {
+//     return await db.query("SELECT * FROM users");
+//   }, { [SEMCONV.DB_OPERATION_NAME]: "select" });
+//
+// On success: emits `<name>` with { ...labels, outcome: "ok",
+// duration_ms }. On throw: emits with outcome: "fail".
+//
+// The operation name MUST be a stable string (not derived from input)
+// to keep the metric cardinality bounded; operators dynamically
+// scope-naming via prefix should use the labels parameter instead.
+function timed(name, fn, labels) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("observability.timed: name must be a non-empty string");
+  }
+  if (typeof fn !== "function") {
+    throw new TypeError("observability.timed: fn must be a function");
+  }
+  var start = Date.now();
+  function _emit(outcome, extra) {
+    var allLabels = Object.assign({}, labels || {}, {
+      outcome:     outcome,
+      duration_ms: Date.now() - start,
+    }, extra || {});
+    try { event(name, 1, allLabels); }
+    catch (_e) { /* drop-silent — observability sink */ }
+  }
+  var ret;
+  try { ret = fn(); }
+  catch (e) {
+    _emit("fail", { error_type: (e && e.name) || "Error" });
+    throw e;
+  }
+  if (ret && typeof ret.then === "function") {
+    return ret.then(
+      function (v) { _emit("ok"); return v; },
+      function (e) {
+        _emit("fail", { error_type: (e && e.name) || "Error" });
+        throw e;
+      }
+    );
+  }
+  _emit("ok");
+  return ret;
+}
+
 // OpenTelemetry semantic-convention attribute names — the operator-
 // facing canonical vocabulary the framework's b.observability /
 // b.tracing / b.metrics emitters use when building span / metric
@@ -220,12 +271,52 @@ var SEMCONV = Object.freeze({
   TELEMETRY_SDK_NAME:         "telemetry.sdk.name",
   TELEMETRY_SDK_LANGUAGE:     "telemetry.sdk.language",
   TELEMETRY_SDK_VERSION:      "telemetry.sdk.version",
+  // GenAI — OpenTelemetry semantic conventions for generative AI
+  // workloads (LLM clients, vector DB queries, agent frameworks).
+  // Tracking the otel-spec experimental namespace; covers the stable
+  // attribute set as of 2026-Q2.
+  GEN_AI_SYSTEM:                  "gen_ai.system",
+  GEN_AI_REQUEST_MODEL:           "gen_ai.request.model",
+  GEN_AI_REQUEST_TEMPERATURE:     "gen_ai.request.temperature",
+  GEN_AI_REQUEST_TOP_P:           "gen_ai.request.top_p",
+  GEN_AI_REQUEST_TOP_K:           "gen_ai.request.top_k",
+  GEN_AI_REQUEST_MAX_TOKENS:      "gen_ai.request.max_tokens",
+  GEN_AI_REQUEST_STOP_SEQUENCES:  "gen_ai.request.stop_sequences",
+  GEN_AI_RESPONSE_MODEL:          "gen_ai.response.model",
+  GEN_AI_RESPONSE_ID:             "gen_ai.response.id",
+  GEN_AI_RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons",
+  GEN_AI_USAGE_INPUT_TOKENS:      "gen_ai.usage.input_tokens",
+  GEN_AI_USAGE_OUTPUT_TOKENS:     "gen_ai.usage.output_tokens",
+  GEN_AI_USAGE_TOTAL_TOKENS:      "gen_ai.usage.total_tokens",
+  GEN_AI_OPERATION_NAME:          "gen_ai.operation.name",
+  GEN_AI_TOOL_NAME:               "gen_ai.tool.name",
+  GEN_AI_TOOL_CALL_ID:            "gen_ai.tool.call.id",
+  GEN_AI_AGENT_ID:                "gen_ai.agent.id",
+  GEN_AI_AGENT_NAME:              "gen_ai.agent.name",
+  GEN_AI_AGENT_DESCRIPTION:       "gen_ai.agent.description",
+  // Vector database / retrieval-augmented generation
+  DB_VECTOR_QUERY_TOP_K:          "db.vector.query.top_k",
+  DB_VECTOR_QUERY_DIMENSIONS:     "db.vector.query.dimensions",
+  DB_VECTOR_QUERY_DISTANCE_METRIC: "db.vector.query.distance_metric",
+  // Cloud / runtime context (frequently paired with GenAI)
+  CLOUD_PROVIDER:                 "cloud.provider",
+  CLOUD_REGION:                   "cloud.region",
+  CLOUD_ACCOUNT_ID:               "cloud.account.id",
+  CLOUD_RESOURCE_ID:              "cloud.resource_id",
+  // Container / orchestration
+  CONTAINER_ID:                   "container.id",
+  CONTAINER_IMAGE_NAME:           "container.image.name",
+  CONTAINER_IMAGE_TAG:            "container.image.tag",
+  K8S_NAMESPACE_NAME:             "k8s.namespace.name",
+  K8S_POD_NAME:                   "k8s.pod.name",
+  K8S_DEPLOYMENT_NAME:            "k8s.deployment.name",
 });
 
 module.exports = {
   tap:        tap,
   event:      event,
   safeEvent:  safeEvent,
+  timed:      timed,
   setTap:     setTap,
   SEMCONV:    SEMCONV,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.94",
+  "version": "0.7.96",
   "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:4a206dc4-5c8b-485f-8557-d266d9ad6730",
+  "serialNumber": "urn:uuid:f930dea4-02bf-424a-81d9-af05bce63d00",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T08:24:52.645Z",
+    "timestamp": "2026-05-06T08:44:44.540Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.94",
+      "bom-ref": "@blamejs/core@0.7.96",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.94",
+      "version": "0.7.96",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.94",
+      "purl": "pkg:npm/%40blamejs/core@0.7.96",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.94",
+      "ref": "@blamejs/core@0.7.96",
       "dependsOn": []
     }
   ]