@blamejs/core 0.7.101 → 0.7.103

package/lib/observability-tracer.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * b.observability.tracer — OTel-shaped distributed-tracing span builder.
+ *
+ * Builds OpenTelemetry-compatible spans without a vendored OTel SDK.
+ * The span objects are JSON-serializable and have the OTLP/JSON wire
+ * shape (Trace v1) so the operator can ship them to any OTLP-aware
+ * collector (Jaeger, Tempo, Honeycomb, Lightstep, Datadog, etc.) via
+ * b.observability.spanExporter or their own bridge.
+ *
+ *   var tracer = b.observability.tracer.create({
+ *     service: "checkout-api",
+ *     resource: { "service.version": "0.42.0",
+ *                 "deployment.environment": "prod" },
+ *     onEnd: function (span) { exporter.queue(span); },
+ *   });
+ *
+ *   var span = tracer.start("checkout.process", {
+ *     traceId: req.trace.traceId,         // optional — derive from context
+ *     parentId: req.trace.parentId,
+ *     sampled:  req.trace.sampled,
+ *     attributes: {
+ *       [SEMCONV.HTTP_REQUEST_METHOD]: "POST",
+ *       [SEMCONV.URL_PATH]:            "/checkout",
+ *     },
+ *     kind: "server",
+ *   });
+ *
+ *   try {
+ *     // ... do the work
+ *     span.setAttribute(SEMCONV.HTTP_RESPONSE_STATUS_CODE, 200);
+ *     span.addEvent("payment.charged", { amount: 4200 });
+ *     span.setStatus("ok");
+ *   } catch (e) {
+ *     span.recordException(e);
+ *     span.setStatus("error", e.message);
+ *     throw e;
+ *   } finally {
+ *     span.end();   // captures duration_ms, fires tracer.onEnd(span)
+ *   }
+ *
+ * Span lifecycle:
+ *   - start()       — captures startTime; assigns spanId; emits
+ *                     span.start observability counter
+ *   - setAttribute  — additive; rejects non-stable attribute names
+ *                     when strict: true
+ *   - addEvent      — appends { name, time, attributes }
+ *   - recordException — addEvent with `exception.*` attributes
+ *   - setStatus     — "unset" | "ok" | "error" with optional message
+ *   - end()         — captures endTime; emits span.end observability
+ *                     counter; calls tracer.onEnd(span) hook
+ *
+ * Span shape (OTLP/JSON-compatible):
+ *   {
+ *     traceId, spanId, parentSpanId, name, kind,
+ *     startTimeUnixNano, endTimeUnixNano, durationNs, durationMs,
+ *     attributes: { ... },
+ *     events: [ { name, timeUnixNano, attributes } ],
+ *     status: { code: "unset" | "ok" | "error", message? },
+ *     resource: { ... },
+ *     scope: { name: "blamejs", version },
+ *     droppedAttributesCount, droppedEventsCount,
+ *   }
+ *
+ * Attribute / event caps:
+ *   - maxAttributes per span: 128 (OTLP default)
+ *   - maxEvents per span:     128
+ *   - maxAttributeValueLength: 1024 chars (truncated past)
+ *
+ * Excess additions silently increment droppedAttributesCount /
+ * droppedEventsCount per OTLP convention; the span itself never
+ * throws on cap overflow (hot-path observability is drop-silent).
+ */
+
+var bCrypto = require("./crypto");
+var constants = require("./constants");
+var lazyRequire = require("./lazy-require");
+var safeBuffer = require("./safe-buffer");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var TRACE_ID_BYTES = constants.BYTES.bytes(16);                                    // W3C §3.2.2.3 — 128-bit trace-id
+var SPAN_ID_BYTES  = constants.BYTES.bytes(8);                                     // W3C §3.2.2.4 — 64-bit span-id
+
+var TracerError = defineClass("TracerError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var DEFAULT_MAX_ATTRIBUTES = 128;                                                  // allow:raw-byte-literal — OTLP default span attribute cap
+var DEFAULT_MAX_EVENTS     = 128;                                                  // allow:raw-byte-literal — OTLP default span event cap
+var DEFAULT_MAX_ATTR_VALUE_LEN = 1024;                                             // allow:raw-byte-literal — OTLP attribute value char cap
+
+var VALID_KINDS = ["internal", "server", "client", "producer", "consumer"];
+var VALID_STATUS_CODES = ["unset", "ok", "error"];
+
+function _now() { return Date.now(); }
+
+function _msToUnixNano(ms) {
+  // OTLP timestamps are uint64 nanoseconds since Unix epoch. JS Date.now()
+  // gives ms; multiply by 1e6 and stringify (OTLP/JSON uses string for
+  // uint64 values per https://protobuf.dev/programming-guides/proto3/#json).
+  return String(BigInt(ms) * 1000000n);                                            // allow:raw-byte-literal — ms→ns conversion factor (1e6)
+}
+
+function _truncateAttrValue(v, maxLen) {
+  if (typeof v === "string" && v.length > maxLen) {
+    return v.slice(0, maxLen);
+  }
+  return v;
+}
+
+function _validateKind(kind) {
+  if (typeof kind !== "string") return "internal";
+  if (VALID_KINDS.indexOf(kind) === -1) {
+    throw new TracerError("tracer/bad-kind",
+      "tracer.start: kind must be one of " + VALID_KINDS.join(", ") +
+      " (got " + JSON.stringify(kind) + ")");
+  }
+  return kind;
+}
+
+function _validateAttrKey(key) {
+  if (typeof key !== "string" || key.length === 0) return false;
+  // OTel attribute keys: ASCII printable, dot-separated, no spaces
+  // beyond what the SEMCONV vocabulary uses.
+  if (key.length > 255) return false;                                              // allow:raw-byte-literal — OTLP attribute key cap
+  return true;
+}
+
+function _validateAttrValue(v) {
+  // OTLP supports string / int / double / bool / array of those
+  var t = typeof v;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(v);
+  if (Array.isArray(v)) {
+    for (var i = 0; i < v.length; i++) {
+      var elT = typeof v[i];
+      if (elT !== "string" && elT !== "boolean" && elT !== "number") return false;
+      if (elT === "number" && !Number.isFinite(v[i])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+function _spanId() {
+  return bCrypto.generateBytes(SPAN_ID_BYTES).toString("hex");
+}
+
+function _traceId() {
+  return bCrypto.generateBytes(TRACE_ID_BYTES).toString("hex");
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "tracer", TracerError);
+  validateOpts(opts, [
+    "service", "resource", "scope",
+    "maxAttributes", "maxEvents", "maxAttributeValueLength",
+    "onEnd", "onStart", "audit",
+  ], "tracer.create");
+  validateOpts.requireNonEmptyString(opts.service,
+    "tracer.create: service", TracerError, "tracer/bad-service");
+  validateOpts.optionalFunction(opts.onEnd,
+    "tracer.create: onEnd", TracerError, "tracer/bad-opts");
+  validateOpts.optionalFunction(opts.onStart,
+    "tracer.create: onStart", TracerError, "tracer/bad-opts");
+
+  var resource = Object.assign({
+    "service.name": opts.service,
+  }, opts.resource || {});
+  var scope = opts.scope || { name: "blamejs", version: constants.version || null };
+  var maxAttributes = opts.maxAttributes || DEFAULT_MAX_ATTRIBUTES;
+  var maxEvents     = opts.maxEvents     || DEFAULT_MAX_EVENTS;
+  var maxAttrValLen = opts.maxAttributeValueLength || DEFAULT_MAX_ATTR_VALUE_LEN;
+
+  function _newSpan(name, spanOpts) {
+    spanOpts = spanOpts || {};
+    var traceId = spanOpts.traceId;
+    if (typeof traceId !== "string" || !safeBuffer.TRACE_ID_HEX_RE.test(traceId)) {  // allow:regex-no-length-cap — fixed-length hex constant from safe-buffer
+      traceId = _traceId();
+    }
+    var parentSpanId = spanOpts.parentId || null;
+    if (parentSpanId !== null && (typeof parentSpanId !== "string" || !safeBuffer.SPAN_ID_HEX_RE.test(parentSpanId))) {  // allow:regex-no-length-cap — fixed-length hex constant from safe-buffer
+      parentSpanId = null;
+    }
+    var spanId = _spanId();
+    var startMs = _now();
+    var kind = _validateKind(spanOpts.kind);
+    var sampled = spanOpts.sampled !== false;
+
+    var attributes = Object.create(null);
+    var droppedAttributesCount = 0;
+    var events = [];
+    var droppedEventsCount = 0;
+    var status = { code: "unset", message: null };
+    var ended = false;
+    var endMs = null;
+
+    function setAttribute(key, value) {
+      if (ended) return span;
+      if (!_validateAttrKey(key)) { droppedAttributesCount += 1; return span; }
+      if (!_validateAttrValue(value)) { droppedAttributesCount += 1; return span; }
+      var keyCount = Object.keys(attributes).length;
+      if (!(key in attributes) && keyCount >= maxAttributes) {
+        droppedAttributesCount += 1;
+        return span;
+      }
+      attributes[key] = _truncateAttrValue(value, maxAttrValLen);
+      return span;
+    }
+
+    function setAttributes(map) {
+      if (!map || typeof map !== "object") return span;
+      var keys = Object.keys(map);
+      for (var i = 0; i < keys.length; i++) setAttribute(keys[i], map[keys[i]]);
+      return span;
+    }
+
+    function addEvent(eventName, eventAttrs) {
+      if (ended) return span;
+      if (typeof eventName !== "string" || eventName.length === 0) {
+        droppedEventsCount += 1;
+        return span;
+      }
+      if (events.length >= maxEvents) { droppedEventsCount += 1; return span; }
+      var eventTime = _now();
+      var attrs = Object.create(null);
+      if (eventAttrs && typeof eventAttrs === "object") {
+        var ks = Object.keys(eventAttrs);
+        for (var i = 0; i < ks.length; i++) {
+          var k = ks[i], v = eventAttrs[k];
+          if (_validateAttrKey(k) && _validateAttrValue(v)) {
+            attrs[k] = _truncateAttrValue(v, maxAttrValLen);
+          }
+        }
+      }
+      events.push({
+        name:         eventName,
+        timeUnixNano: _msToUnixNano(eventTime),
+        attributes:   attrs,
+      });
+      return span;
+    }
+
+    function recordException(err) {
+      if (ended) return span;
+      if (!err) return span;
+      var name = (err.name || (err.constructor && err.constructor.name) || "Error");
+      var message = (err.message || String(err));
+      var stack = err.stack ? String(err.stack) : null;
+      addEvent("exception", {
+        "exception.type":       name,
+        "exception.message":    message,
+        "exception.stacktrace": stack || "",
+      });
+      return span;
+    }
+
+    function setStatus(code, message) {
+      if (ended) return span;
+      if (VALID_STATUS_CODES.indexOf(code) === -1) {
+        throw new TracerError("tracer/bad-status",
+          "span.setStatus: code must be one of " + VALID_STATUS_CODES.join(", "));
+      }
+      status.code = code;
+      status.message = (typeof message === "string") ? message : null;
+      return span;
+    }
+
+    function end(endTimestampMs) {
+      if (ended) return span;
+      ended = true;
+      endMs = (typeof endTimestampMs === "number" && isFinite(endTimestampMs)) ? endTimestampMs : _now();
+      if (typeof opts.onEnd === "function") {
+        try { opts.onEnd(toJSON()); }
+        catch (_e) { /* operator hook — drop-silent */ }
+      }
+      try { observability().safeEvent("tracer.span.end", 1, {
+        kind: kind, status: status.code, sampled: sampled ? "1" : "0",
+      }); } catch (_e) { /* drop-silent */ }
+      return span;
+    }
+
+    function isRecording() { return !ended; }
+
+    function toJSON() {
+      var endNano = endMs !== null ? _msToUnixNano(endMs) : null;
+      var durationMs = endMs !== null ? (endMs - startMs) : null;
+      // OTLP/JSON shape (Trace v1)
+      return {
+        traceId:           traceId,
+        spanId:            spanId,
+        parentSpanId:      parentSpanId,
+        name:              name,
+        kind:              kind,
+        startTimeUnixNano: _msToUnixNano(startMs),
+        endTimeUnixNano:   endNano,
+        durationNs:        endNano !== null ? String(BigInt(durationMs) * 1000000n) : null,  // allow:raw-byte-literal — ms→ns conversion factor (1e6)
+        durationMs:        durationMs,
+        attributes:        Object.assign({}, attributes),
+        events:            events.slice(),
+        status:            { code: status.code, message: status.message },
+        resource:          Object.assign({}, resource),
+        scope:             Object.assign({}, scope),
+        droppedAttributesCount: droppedAttributesCount,
+        droppedEventsCount:     droppedEventsCount,
+        sampled:           sampled,
+      };
+    }
+
+    var span = {
+      traceId:           traceId,
+      spanId:            spanId,
+      parentSpanId:      parentSpanId,
+      name:              name,
+      kind:              kind,
+      sampled:           sampled,
+      setAttribute:      setAttribute,
+      setAttributes:     setAttributes,
+      addEvent:          addEvent,
+      recordException:   recordException,
+      setStatus:         setStatus,
+      end:               end,
+      isRecording:       isRecording,
+      toJSON:            toJSON,
+    };
+
+    // Apply initial attributes
+    if (spanOpts.attributes && typeof spanOpts.attributes === "object") {
+      setAttributes(spanOpts.attributes);
+    }
+
+    if (typeof opts.onStart === "function") {
+      try { opts.onStart(span); }
+      catch (_e) { /* operator hook — drop-silent */ }
+    }
+    try { observability().safeEvent("tracer.span.start", 1, {
+      kind: kind, sampled: sampled ? "1" : "0",
+    }); } catch (_e) { /* drop-silent */ }
+
+    return span;
+  }
+
+  function start(name, spanOpts) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new TracerError("tracer/bad-name",
+        "tracer.start: name must be a non-empty string");
+    }
+    return _newSpan(name, spanOpts || {});
+  }
+
+  function startChildOf(parentSpan, name, spanOpts) {
+    if (!parentSpan || typeof parentSpan.traceId !== "string") {
+      throw new TracerError("tracer/bad-parent",
+        "tracer.startChildOf: parentSpan must be a span object");
+    }
+    var childOpts = Object.assign({}, spanOpts || {}, {
+      traceId:  parentSpan.traceId,
+      parentId: parentSpan.spanId,
+      sampled:  parentSpan.sampled,
+    });
+    return _newSpan(name, childOpts);
+  }
+
+  return {
+    start:            start,
+    startChildOf:     startChildOf,
+    service:          opts.service,
+    resource:         resource,
+    scope:            scope,
+    _attributeCaps:   {                                                            // exported for tests
+      maxAttributes:           maxAttributes,
+      maxEvents:                maxEvents,
+      maxAttributeValueLength: maxAttrValLen,
+    },
+  };
+}
+
+// Pure helper: derive the canonical W3C `traceparent` header from a span.
+function spanToTraceparent(span) {
+  if (!span || typeof span.traceId !== "string" || typeof span.spanId !== "string") {
+    throw new TracerError("tracer/bad-span",
+      "spanToTraceparent: argument must be a span with traceId + spanId");
+  }
+  return "00-" + span.traceId + "-" + span.spanId + "-" + (span.sampled ? "01" : "00");
+}
+
+module.exports = {
+  create:            create,
+  spanToTraceparent: spanToTraceparent,
+  TracerError:       TracerError,
+  _BASE64URL_RE:     safeBuffer.BASE64URL_RE,                                      // not used directly — exposed for downstream tests
+  VALID_KINDS:       VALID_KINDS,
+  VALID_STATUS_CODES: VALID_STATUS_CODES,
+};

package/lib/observability.js

@@ -54,8 +54,13 @@
  *   fn: function — sync or async. Return propagates; throws propagate
  *     after metrics fire.
  */
+var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 
+// safe-buffer can't be top-required: framework-error → observability →
+// safe-buffer → framework-error forms a cycle. Lazy-loaded at first use.
+var safeBuffer = lazyRequire(function () { return require("./safe-buffer"); });
+
 var tracing = lazyRequire(function () { return require("./tracing"); });
 var metrics = lazyRequire(function () { return require("./metrics"); });
 
@@ -355,10 +360,10 @@ function _buildTraceparent(opts) {
   }
   var traceId = opts.traceId;
   var parentId = opts.parentId;
-  if (typeof traceId !== "string" || !/^[0-9a-f]{32}$/.test(traceId) || traceId === _ALL_ZERO_TRACE) {
+  if (typeof traceId !== "string" || !safeBuffer().TRACE_ID_HEX_RE.test(traceId) || traceId === _ALL_ZERO_TRACE) {  // allow:regex-no-length-cap — fixed-length hex constant from safe-buffer
     throw new TypeError("traceContext.build: traceId must be 32 lowercase hex chars (non-zero)");
   }
-  if (typeof parentId !== "string" || !/^[0-9a-f]{16}$/.test(parentId) || parentId === _ALL_ZERO_PARENT) {
+  if (typeof parentId !== "string" || !safeBuffer().SPAN_ID_HEX_RE.test(parentId) || parentId === _ALL_ZERO_PARENT) {  // allow:regex-no-length-cap — fixed-length hex constant from safe-buffer
     throw new TypeError("traceContext.build: parentId must be 16 lowercase hex chars (non-zero)");
   }
   var flagsByte = (opts.sampled ? _TRACE_FLAG_SAMPLED : 0);
@@ -380,11 +385,227 @@ function _newParentId() {
   return hex === _ALL_ZERO_PARENT ? _nodeCryptoForTrace.randomBytes(_PARENT_ID_BYTES).toString("hex") : hex;
 }
 
+// W3C Trace Context §3.3 — tracestate: comma-separated list of
+// `vendor=value` pairs carrying vendor-specific trace data.
+//
+//   tracestate: rojo=00f067aa0ba902b7, congo=t61rcWkgMzE
+//
+// Spec rules (https://www.w3.org/TR/trace-context-1/#tracestate-header):
+//   - vendor key: lowercase ASCII letters, digits, `_`, `-`, `*`, `/`,
+//     length 1..256, optionally with `<tenant>@<system>` form
+//   - value: printable ASCII (0x20..0x7E) excluding `,` and `=`,
+//     length 1..256
+//   - max 32 entries, max 512 chars total
+//   - duplicate keys: keep first, drop rest
+var _TRACESTATE_KEY_RE   = /^[a-z0-9][a-z0-9_\-*/]{0,255}(@[a-z0-9][a-z0-9_\-*/]{0,255})?$/;
+var _TRACESTATE_VALUE_RE = /^[\x20-\x2B\x2D-\x3C\x3E-\x7E]{1,256}$/;     // printable, no "," or "="
+var _TRACESTATE_MAX_ENTRIES = 32;                                                  // allow:raw-byte-literal — W3C spec hard cap (§3.3.1.3)
+var _TRACESTATE_MAX_CHARS   = 512;                                                 // allow:raw-byte-literal — W3C spec hard cap (§3.3.1.3)
+
+function _parseTracestate(headerValue) {
+  if (typeof headerValue !== "string") return null;
+  if (headerValue.length === 0 || headerValue.length > _TRACESTATE_MAX_CHARS) return null;
+  var pairs = headerValue.split(",");
+  if (pairs.length > _TRACESTATE_MAX_ENTRIES) return null;
+  var seen = Object.create(null);
+  var out = [];
+  for (var i = 0; i < pairs.length; i++) {
+    var raw = pairs[i].trim();
+    if (raw.length === 0) continue;
+    var eqIdx = raw.indexOf("=");
+    if (eqIdx === -1) return null;
+    var key = raw.slice(0, eqIdx).trim();
+    var val = raw.slice(eqIdx + 1).trim();
+    if (!_TRACESTATE_KEY_RE.test(key)) return null;                              // allow:regex-no-length-cap — regex literal hard-caps key length per W3C §3.3.1.1
+    if (!_TRACESTATE_VALUE_RE.test(val)) return null;                            // allow:regex-no-length-cap — regex literal hard-caps value length per W3C §3.3.1.2
+    if (seen[key]) continue;     // dup-key: keep first
+    seen[key] = true;
+    out.push({ key: key, value: val });
+  }
+  return out;
+}
+
+function _buildTracestate(entries) {
+  if (!Array.isArray(entries)) {
+    throw new TypeError("traceContext.buildTracestate: entries must be an array");
+  }
+  if (entries.length > _TRACESTATE_MAX_ENTRIES) {
+    throw new TypeError("traceContext.buildTracestate: too many entries (max " +
+      _TRACESTATE_MAX_ENTRIES + ")");
+  }
+  var seen = Object.create(null);
+  var parts = [];
+  for (var i = 0; i < entries.length; i++) {
+    var e = entries[i];
+    if (!e || typeof e !== "object") {
+      throw new TypeError("traceContext.buildTracestate: entries[" + i + "] must be an object");
+    }
+    if (typeof e.key !== "string" || !_TRACESTATE_KEY_RE.test(e.key)) {          // allow:regex-no-length-cap — regex literal hard-caps key length per W3C §3.3.1.1
+      throw new TypeError("traceContext.buildTracestate: entries[" + i + "].key violates W3C key rules");
+    }
+    if (typeof e.value !== "string" || !_TRACESTATE_VALUE_RE.test(e.value)) {    // allow:regex-no-length-cap — regex literal hard-caps value length per W3C §3.3.1.2
+      throw new TypeError("traceContext.buildTracestate: entries[" + i + "].value violates W3C value rules");
+    }
+    if (seen[e.key]) continue;
+    seen[e.key] = true;
+    parts.push(e.key + "=" + e.value);
+  }
+  var s = parts.join(",");
+  if (s.length > _TRACESTATE_MAX_CHARS) {
+    throw new TypeError("traceContext.buildTracestate: built string exceeds W3C 512-char cap");
+  }
+  return s;
+}
+
 var traceContext = {
-  parse:        _parseTraceparent,
-  build:        _buildTraceparent,
-  newTraceId:   _newTraceId,
-  newParentId:  _newParentId,
+  parse:           _parseTraceparent,
+  build:           _buildTraceparent,
+  newTraceId:      _newTraceId,
+  newParentId:     _newParentId,
+  parseTracestate: _parseTracestate,
+  buildTracestate: _buildTracestate,
+};
+
+// ---- W3C Baggage (https://www.w3.org/TR/baggage/) ----
+//
+// `baggage` HTTP header carries a comma-separated list of
+// `key=value;property=value;property=value` triplets. Used to
+// propagate user-supplied context (tenantId, deploymentRegion,
+// experimentId, etc.) across service boundaries WITHOUT mixing it
+// into traceparent (which is reserved for trace identifiers).
+//
+// Spec rules:
+//   - key: token per RFC 7230 (`tchar` set: `!#$%&'*+\-.^_\`|~` +
+//     digits + ALPHA), length 1..255
+//   - value: percent-encoded UTF-8, must NOT contain CTL chars,
+//     `,`, `;`, `=` (those are structural delimiters)
+//   - properties: optional, semicolon-separated `key=value` or bare
+//     `key` after the main value
+//   - max 64 entries per Baggage section recommendation
+//   - max 8192 chars total (W3C recommended cap)
+// Resolved at first call; lazyRequire returns a function.
+function _baggageTokenRe() { return safeBuffer().RFC7230_TCHAR_RE; }
+var _BAGGAGE_MAX_ENTRIES = 64;                                                     // allow:raw-byte-literal — W3C Baggage recommended cap
+var _BAGGAGE_MAX_CHARS = C.BYTES.kib(8);                                           // W3C Baggage recommended 8192-char cap
+
+function _parseBaggage(headerValue) {
+  if (typeof headerValue !== "string") return null;
+  if (headerValue.length === 0 || headerValue.length > _BAGGAGE_MAX_CHARS) return null;
+  var entries = headerValue.split(",");
+  if (entries.length > _BAGGAGE_MAX_ENTRIES) return null;
+  var seen = Object.create(null);
+  var out = [];
+  for (var i = 0; i < entries.length; i++) {
+    var raw = entries[i].trim();
+    if (raw.length === 0) continue;
+    var parts = raw.split(";");
+    var head = parts[0].trim();
+    var eqIdx = head.indexOf("=");
+    if (eqIdx === -1) return null;
+    var key = head.slice(0, eqIdx).trim();
+    var rawValue = head.slice(eqIdx + 1).trim();
+    if (!_baggageTokenRe().test(key)) return null;                                 // allow:regex-no-length-cap — RFC 7230 tchar; bound by header-cap
+    if (key.length > 255) return null;                                             // allow:raw-byte-literal — W3C key length cap
+    var value;
+    try { value = decodeURIComponent(rawValue); }
+    catch (_e) { return null; }
+    var props = [];
+    for (var p = 1; p < parts.length; p++) {
+      var prop = parts[p].trim();
+      if (prop.length === 0) continue;
+      var pEq = prop.indexOf("=");
+      if (pEq === -1) {
+        if (!_baggageTokenRe().test(prop)) return null;                            // allow:regex-no-length-cap — RFC 7230 tchar; bound by header-cap
+        props.push({ key: prop, value: null });
+      } else {
+        var pKey = prop.slice(0, pEq).trim();
+        var pVal = prop.slice(pEq + 1).trim();
+        if (!_baggageTokenRe().test(pKey)) return null;                            // allow:regex-no-length-cap — RFC 7230 tchar; bound by header-cap
+        var pValueDecoded;
+        try { pValueDecoded = decodeURIComponent(pVal); }
+        catch (_e) { return null; }
+        props.push({ key: pKey, value: pValueDecoded });
+      }
+    }
+    if (seen[key]) continue;
+    seen[key] = true;
+    out.push({ key: key, value: value, properties: props });
+  }
+  return out;
+}
+
+function _buildBaggage(entries) {
+  if (!Array.isArray(entries)) {
+    throw new TypeError("traceContext.buildBaggage: entries must be an array");
+  }
+  if (entries.length > _BAGGAGE_MAX_ENTRIES) {
+    throw new TypeError("traceContext.buildBaggage: too many entries (max " +
+      _BAGGAGE_MAX_ENTRIES + ")");
+  }
+  var seen = Object.create(null);
+  var parts = [];
+  for (var i = 0; i < entries.length; i++) {
+    var e = entries[i];
+    if (!e || typeof e !== "object") {
+      throw new TypeError("traceContext.buildBaggage: entries[" + i + "] must be an object");
+    }
+    if (typeof e.key !== "string" || !_baggageTokenRe().test(e.key)) {             // allow:regex-no-length-cap — RFC 7230 tchar; bound by header-cap
+      throw new TypeError("traceContext.buildBaggage: entries[" + i + "].key violates W3C key rules");
+    }
+    if (typeof e.value !== "string") {
+      throw new TypeError("traceContext.buildBaggage: entries[" + i + "].value must be a string");
+    }
+    if (seen[e.key]) continue;
+    seen[e.key] = true;
+    var encodedValue = encodeURIComponent(e.value);
+    var item = e.key + "=" + encodedValue;
+    if (Array.isArray(e.properties)) {
+      for (var p = 0; p < e.properties.length; p++) {
+        var prop = e.properties[p];
+        if (!prop || typeof prop !== "object") continue;
+        if (typeof prop.key !== "string" || !_baggageTokenRe().test(prop.key)) {   // allow:regex-no-length-cap — RFC 7230 tchar; bound by header-cap
+          throw new TypeError("traceContext.buildBaggage: entries[" + i +
+            "].properties[" + p + "].key violates W3C property-key rules");
+        }
+        if (prop.value === null || prop.value === undefined) {
+          item += ";" + prop.key;
+        } else if (typeof prop.value === "string") {
+          item += ";" + prop.key + "=" + encodeURIComponent(prop.value);
+        } else {
+          throw new TypeError("traceContext.buildBaggage: entries[" + i +
+            "].properties[" + p + "].value must be a string or null");
+        }
+      }
+    }
+    parts.push(item);
+  }
+  var s = parts.join(",");
+  if (s.length > _BAGGAGE_MAX_CHARS) {
+    throw new TypeError("traceContext.buildBaggage: built string exceeds W3C 8192-char cap");
+  }
+  return s;
+}
+
+var baggage = {
+  parse: _parseBaggage,
+  build: _buildBaggage,
+  MAX_ENTRIES: _BAGGAGE_MAX_ENTRIES,
+};
+
+// Lazy-required to avoid a require cycle (tracer / exporter both
+// reach back into observability for safeEvent emissions).
+var _tracerModule       = lazyRequire(function () { return require("./observability-tracer"); });
+var _otlpExporterModule = lazyRequire(function () { return require("./observability-otlp-exporter"); });
+
+var tracer = {
+  create:            function (opts) { return _tracerModule().create(opts); },
+  spanToTraceparent: function (span) { return _tracerModule().spanToTraceparent(span); },
+  VALID_KINDS:       ["internal", "server", "client", "producer", "consumer"],
+  VALID_STATUS_CODES: ["unset", "ok", "error"],
+};
+
+var otlpExporter = {
+  create: function (opts) { return _otlpExporterModule().create(opts); },
 };
 
 module.exports = {
@@ -395,4 +616,7 @@ module.exports = {
   setTap:        setTap,
   SEMCONV:       SEMCONV,
   traceContext:  traceContext,
+  baggage:       baggage,
+  tracer:        tracer,
+  otlpExporter:  otlpExporter,
 };

package/lib/safe-buffer.js

@@ -196,6 +196,18 @@ var HEX_RE = /^[0-9a-fA-F]+$/;
 // is length-agnostic — callers cap length per protocol contract.
 var BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
 
+// Fixed-length hex predicates used by trace-context primitives (W3C
+// trace-id is 16 bytes = 32 hex chars; span-id / parent-id is 8
+// bytes = 16 hex chars). Extracted to keep callers length-bounded
+// without duplicating the literal in every file.
+var TRACE_ID_HEX_RE = /^[0-9a-f]{32}$/;                                            // allow:regex-no-length-cap — fixed 32 hex chars (W3C §3.2.2.3)
+var SPAN_ID_HEX_RE  = /^[0-9a-f]{16}$/;                                            // allow:regex-no-length-cap — fixed 16 hex chars (W3C §3.2.2.4)
+
+// RFC 7230 §3.2.6 / RFC 9110 §5.1 `tchar` grammar — used by HTTP
+// header tokens, MIME parameter names, W3C Baggage keys, etc.
+// Length-agnostic; callers cap per protocol.
+var RFC7230_TCHAR_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;                           // allow:regex-no-length-cap — caller bounds length
+
 // CRLF_RE matches any control character used in HTTP-header / SMTP-
 // envelope injection attacks. Header values that contain CR or LF must
 // be rejected before serialization.
@@ -238,6 +250,9 @@ module.exports = {
   stripTrailingHspace:   stripTrailingHspace,
   HEX_RE:                HEX_RE,
   BASE64URL_RE:          BASE64URL_RE,
+  TRACE_ID_HEX_RE:       TRACE_ID_HEX_RE,
+  SPAN_ID_HEX_RE:        SPAN_ID_HEX_RE,
+  RFC7230_TCHAR_RE:      RFC7230_TCHAR_RE,
   CRLF_RE:               CRLF_RE,
   TRAILING_HSPACE_RE:    TRAILING_HSPACE_RE,
   SafeBufferError:       SafeBufferError,