@blamejs/core 0.7.101 → 0.7.103

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.103** (2026-05-06) — W3C distributed tracing suite. End-to-end OTel-shaped tracing without a vendored OTel SDK: tracestate + Baggage parsers, span builder, OTLP/JSON exporter, HTTP-server span middleware, log correlation. **`b.observability.traceContext.parseTracestate / buildTracestate`** — W3C Trace Context §3.3 vendor data: enforces vendor-key shape (lcase-alnum + `_-*/`, optional `<tenant>@<system>`), value charset (printable ASCII excluding `,` and `=`), 32-entry cap, 512-char total cap, dup-key-keep-first per §3.3.1.5. **`b.observability.baggage.parse / build`** — W3C Baggage spec parser + builder for operator-supplied context (tenantId, region, experimentId, etc.) propagated across service boundaries. RFC 7230 tchar key grammar, percent-encoded UTF-8 values, optional per-entry properties (`key=value;property=value`), 64-entry / 8192-char caps. **`b.observability.tracer.create({ service, resource, onEnd })`** — OTel-shaped span builder. `tracer.start(name, opts)` returns a span with `setAttribute` / `setAttributes` / `addEvent` / `recordException` / `setStatus` / `end` / `isRecording` / `toJSON`. OTLP/JSON-compatible output (Trace v1) with `traceId` / `spanId` / `parentSpanId` / `name` / `kind` / `startTimeUnixNano` / `endTimeUnixNano` / `attributes` / `events` / `status` / `resource` / `scope` / `droppedAttributesCount` / `droppedEventsCount`. Attribute caps (128 keys, 1024-char values), event cap (128) per OTLP defaults. `tracer.startChildOf(parent, name)` derives child spans sharing the trace context. **`b.observability.tracer.spanToTraceparent(span)`** — emits the canonical W3C `traceparent` for outbound propagation. **`b.observability.otlpExporter.create({ endpoint, ... })`** — buffered OTLP/HTTP JSON span exporter. Batches spans (default 200), flushes on size + interval (default 5s), retries 5xx + 408/429 with exponential backoff, drops oldest on queue overflow (default 4096). Custom `fetchImpl` opt for testing or non-default HTTP transports; `allowedProtocols` opt for cleartext dev collectors. **`b.middleware.tracePropagate`** extended to also read inbound `tracestate` and stamp `req.trace.tracestate` as the parsed entries array (or `[]` when missing); when `setResponseHeader: true`, echoes both `traceparent` and `tracestate` on the response. **`b.middleware.spanHttpServer({ tracer, ... })`** — auto-creates a root server span per HTTP request, populates OTel `SEMCONV.HTTP_*` / `URL_*` / `SERVER_*` / `CLIENT_*` attributes, attaches the span to `req.span`, ends on response close, fires `onEnd(span.toJSON())` for export. `ignorePaths` (string + RegExp) keeps healthz / static-asset routes out of span volume; `captureRequestHeaders` / `captureResponseHeaders` lift named headers into the span as `http.request.header.*` / `http.response.header.*` attributes. **`b.middleware.traceLogCorrelation({ logger })`** — wraps a `b.log` instance for the request lifetime so every `info()` / `warn()` / `error()` / etc. emission inside the handler auto-includes `trace_id` + `span_id` from the active context (via `req.trace` + `req.span`). Pass-through when no trace context present. Internal sweep: `safeBuffer.TRACE_ID_HEX_RE` / `SPAN_ID_HEX_RE` / `RFC7230_TCHAR_RE` extracted as shared regex constants; `guard-mime` / `middleware/headers` / `observability` consolidated against the new shared constants.
+
+- **0.7.102** (2026-05-06) — `b.middleware.tracePropagate({ generateIfMissing, ... })` — middleware that consumes the inbound `traceparent` header per W3C Trace Context and stamps `req.trace = { traceId, parentId, sampled, hadUpstream }` for downstream handlers + propagation into outbound HTTP calls. `generateIfMissing: true` (default) synthesises a fresh trace when the inbound header is missing/malformed and stamps `hadUpstream: false`. `auditOnMissing: true` emits `system.trace.synthesised` audit events on every locally-originated trace. `setResponseHeader: true` echoes the resolved traceparent on the response (useful when the framework is the back-end of an L7 router that wants to log it). Composes with `b.observability.traceContext` (v0.7.101) for outbound propagation: downstream handlers read `req.trace.traceId` and pass it to `traceContext.build({ traceId: req.trace.traceId, parentId: traceContext.newParentId(), sampled: req.trace.sampled })` for the `traceparent` header on upstream calls.
+
 - **0.7.101** (2026-05-06) — `b.observability.traceContext` — W3C Trace Context (https://www.w3.org/TR/trace-context-1/) parser + builder. **`traceContext.parse(headerValue)`** consumes a `traceparent` HTTP header value (`00-<32hex traceId>-<16hex parentId>-<2hex flags>`) and returns `{ version, traceId, parentId, flags, sampled }` or null on malformed input. Enforces the §3.2.2.3 / §3.2.2.4 all-zero-rejection rule (zero trace-id and zero parent-id are explicitly forbidden by spec). **`traceContext.build({ traceId, parentId, sampled })`** produces a v1 `traceparent` header value; throws on bad input shape. **`traceContext.newTraceId()` / `newParentId()`** generate fresh randomized 128-bit / 64-bit hex strings (with the all-zero retry path the spec requires). Operators wiring distributed tracing across services use these to propagate trace IDs across an outbound HTTP call without a vendored OTel SDK — pair with the SEMCONV constants from v0.7.95 to build OTel-aligned spans on top.
 
 - **0.7.100** (2026-05-06) — `b.network.tls.expiryMonitor({ intervalMs, windowMs, onExpiring })` — periodic CA-trust-store expiry monitor. Runs `expiringSoon(windowMs)` on a schedule; emits `network.tls.ca.expiry_check` audit event on every check (with `expiring` count + `total` CA count), `network.tls.ca.expiring` audit event when any CA falls inside the window, and the matching `network.tls.ca.expiring` observability counter. Optional `onExpiring(rows)` operator hook fires on every check that surfaces expiring CAs so operators can wire pager / Slack alerts. Audit metadata captures the expiring CA labels + the earliest `validTo` timestamp so dashboards can compute "days until first expiry" without re-querying. Returns a handle with `.stop()` for graceful shutdown. Closes the v0.7.26 OCSP/CT batch's continuous-trust-monitoring follow-up.

package/lib/guard-mime.js

@@ -36,6 +36,7 @@ var lazyRequire = require("./lazy-require");
 var gateContract = require("./gate-contract");
 var C = require("./constants");
 var numericBounds = require("./numeric-bounds");
+var safeBuffer = require("./safe-buffer");
 var { GuardMimeError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -48,8 +49,8 @@ var _err = GuardMimeError.factory;
 // 127 octets per token.
 var TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9!#$&\-^_.+]{0,126}$/;
 
-// Parameter token (RFC 7231 §3.1.1.1): tchar set.
-var PARAM_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// Parameter token (RFC 7231 §3.1.1.1): tchar set per RFC 7230.
+var PARAM_TOKEN_RE = safeBuffer.RFC7230_TCHAR_RE;
 
 // Quoted-string body (between double quotes) per RFC 7230 §3.2.6.
 var QUOTED_STRING_BODY_RE = /^[\t\x20-\x7e]*$/;                                   // allow:raw-byte-literal — printable ASCII range

package/lib/middleware/headers.js

@@ -34,12 +34,13 @@
  */
 
 var lazyRequire = require("../lazy-require");
+var safeBuffer = require("../safe-buffer");
 
 var observability = lazyRequire(function () { return require("../observability"); });
 void observability;
 
-// RFC 9110 §5.1 token grammar — tchar set.
-var TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// RFC 9110 §5.1 token grammar — tchar set per RFC 7230.
+var TOKEN_RE = safeBuffer.RFC7230_TCHAR_RE;
 
 var DEPRECATED_TRUST_HEADERS = Object.freeze([
   "x-forwarded-for",

package/lib/middleware/index.js

@@ -45,7 +45,10 @@ var requireContentType = require("./require-content-type");
 var requireMethods = require("./require-methods");
 var securityHeaders = require("./security-headers");
 var securityTxt = require("./security-txt");
+var spanHttpServer = require("./span-http-server");
 var sse = require("./sse");
+var traceLogCorrelation = require("./trace-log-correlation");
+var tracePropagate = require("./trace-propagate");
 var tusUpload = require("./tus-upload");
 var webAppManifest = require("./web-app-manifest");
 
@@ -80,6 +83,9 @@ module.exports = {
   dpop:             dpop.create,
   hostAllowlist:    hostAllowlist.create,
   networkAllowlist: networkAllowlist.create,
+  spanHttpServer:        spanHttpServer.create,
+  traceLogCorrelation:   traceLogCorrelation.create,
+  tracePropagate:        tracePropagate.create,
   tusUpload:        tusUpload.create,
   webAppManifest:   webAppManifest.create,
 
@@ -112,6 +118,9 @@ module.exports = {
     dpop:             dpop,
     hostAllowlist:    hostAllowlist,
     networkAllowlist: networkAllowlist,
+    spanHttpServer:        spanHttpServer,
+    traceLogCorrelation:   traceLogCorrelation,
+    tracePropagate:        tracePropagate,
     tusUpload:        tusUpload,
     webAppManifest:   webAppManifest,
   },

package/lib/middleware/span-http-server.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * spanHttpServer middleware — auto-creates a root span per HTTP
+ * request, populates OTel SEMCONV.HTTP_* attributes, attaches
+ * the span to req.span, and ends the span on response close.
+ *
+ *   var tracer = b.observability.tracer.create({ service: "checkout" });
+ *   var exporter = b.observability.otlpExporter.create({
+ *     endpoint: "https://collector.example.com/v1/traces",
+ *   });
+ *
+ *   router.use(b.middleware.tracePropagate());      // populates req.trace
+ *   router.use(b.middleware.spanHttpServer({
+ *     tracer:    tracer,
+ *     onEnd:     exporter.queue,
+ *     ignorePaths: ["/healthz", /^\/static/],
+ *     captureRequestHeaders:  ["user-agent", "x-tenant-id"],
+ *     captureResponseHeaders: ["content-type", "content-length"],
+ *   }));
+ *
+ *   app.get("/checkout", function (req, res) {
+ *     // req.span is the active root server span
+ *     req.span.setAttribute("checkout.cart_size", cart.items.length);
+ *     var childSpan = tracer.startChildOf(req.span, "db.query");
+ *     // ... do query work
+ *     childSpan.end();
+ *     res.json({ ok: true });
+ *   });
+ *
+ * Span attributes auto-populated per OTel HTTP-server semconv:
+ *   - http.request.method, http.route (when available)
+ *   - url.scheme, url.path, url.query
+ *   - server.address, client.address
+ *   - user_agent.original
+ *   - http.response.status_code (set when response writeHead fires)
+ *
+ * Span kind: "server".
+ *
+ * Skip paths: opts.ignorePaths accepts an array of strings (exact match)
+ * or RegExp instances. Use this to keep healthz / static-asset routes
+ * out of the span volume.
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var SpanHttpError = defineClass("SpanHttpError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _shouldIgnore(path, ignorePaths) {
+  if (!ignorePaths || !Array.isArray(ignorePaths)) return false;
+  for (var i = 0; i < ignorePaths.length; i++) {
+    var rule = ignorePaths[i];
+    if (typeof rule === "string" && rule === path) return true;
+    if (rule instanceof RegExp && rule.test(path)) return true;
+  }
+  return false;
+}
+
+function _splitUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return { path: "/", query: null };
+  var qIdx = url.indexOf("?");
+  if (qIdx === -1) return { path: url, query: null };
+  return { path: url.slice(0, qIdx), query: url.slice(qIdx + 1) };
+}
+
+function _scheme(req) {
+  var x = req.headers && (req.headers["x-forwarded-proto"] || "");
+  if (typeof x === "string" && x.length > 0) {
+    var first = x.split(",")[0].trim().toLowerCase();
+    if (first === "http" || first === "https") return first;
+  }
+  return (req.socket && req.socket.encrypted) ? "https" : "http";
+}
+
+function _serverAddress(req) {
+  var hostHeader = req.headers && (req.headers["x-forwarded-host"] || req.headers.host);
+  if (typeof hostHeader === "string" && hostHeader.length > 0) {
+    return hostHeader.split(",")[0].trim();
+  }
+  return null;
+}
+
+function _captureHeaderAttrs(req, captureList, prefix) {
+  if (!Array.isArray(captureList) || captureList.length === 0) return {};
+  var out = Object.create(null);
+  for (var i = 0; i < captureList.length; i++) {
+    var name = String(captureList[i] || "").toLowerCase();
+    if (!name) continue;
+    var v = req.headers && req.headers[name];
+    if (v === undefined) continue;
+    if (Array.isArray(v)) v = v.join(", ");
+    out[prefix + "." + name] = String(v);
+  }
+  return out;
+}
+
+function _captureResponseHeaderAttrs(res, captureList, prefix) {
+  if (!Array.isArray(captureList) || captureList.length === 0) return {};
+  var out = Object.create(null);
+  for (var i = 0; i < captureList.length; i++) {
+    var name = String(captureList[i] || "").toLowerCase();
+    if (!name) continue;
+    var v;
+    try { v = res.getHeader(name); } catch (_e) { continue; }
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) v = v.join(", ");
+    out[prefix + "." + name] = String(v);
+  }
+  return out;
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.spanHttpServer", SpanHttpError);
+  validateOpts(opts, [
+    "tracer", "onEnd", "ignorePaths",
+    "captureRequestHeaders", "captureResponseHeaders",
+    "spanNameFn", "audit",
+  ], "middleware.spanHttpServer");
+
+  if (!opts.tracer || typeof opts.tracer.start !== "function") {
+    throw new SpanHttpError("span-http/bad-tracer",
+      "middleware.spanHttpServer: tracer must be a b.observability.tracer.create() instance");
+  }
+  validateOpts.optionalFunction(opts.onEnd,
+    "middleware.spanHttpServer: onEnd", SpanHttpError, "span-http/bad-opts");
+  validateOpts.optionalFunction(opts.spanNameFn,
+    "middleware.spanHttpServer: spanNameFn", SpanHttpError, "span-http/bad-opts");
+
+  var tracer            = opts.tracer;
+  var onEnd             = opts.onEnd || null;
+  var ignorePaths       = opts.ignorePaths || null;
+  var captureReqHeaders = opts.captureRequestHeaders || null;
+  var captureResHeaders = opts.captureResponseHeaders || null;
+  var spanNameFn        = opts.spanNameFn || null;
+  var auditOn           = opts.audit !== false;
+
+  return function spanHttpServerMiddleware(req, res, next) {
+    var SEMCONV = observability().SEMCONV;
+    var url = _splitUrl(req.url || "/");
+    if (_shouldIgnore(url.path, ignorePaths)) return next();
+
+    var spanName;
+    if (typeof spanNameFn === "function") {
+      try { spanName = String(spanNameFn(req)); }
+      catch (_e) { spanName = "http.server.request"; }
+    } else {
+      spanName = (req.method ? req.method.toUpperCase() + " " : "") + (url.path || "/");
+    }
+
+    var traceId = req.trace && req.trace.traceId;
+    var parentId = req.trace && req.trace.parentId;
+    var sampled = !req.trace || req.trace.sampled !== false;
+
+    var span = tracer.start(spanName, {
+      traceId:  traceId,
+      parentId: parentId,
+      sampled:  sampled,
+      kind:     "server",
+      attributes: Object.assign({},
+        {
+          [SEMCONV.HTTP_REQUEST_METHOD]: (req.method || "").toUpperCase(),
+          [SEMCONV.URL_SCHEME]:          _scheme(req),
+          [SEMCONV.URL_PATH]:            url.path,
+        },
+        url.query !== null ? { [SEMCONV.URL_QUERY]: url.query } : {},
+        (function () {
+          var serverAddr = _serverAddress(req);
+          return serverAddr ? { [SEMCONV.SERVER_ADDRESS]: serverAddr } : {};
+        })(),
+        (function () {
+          var clientAddr = requestHelpers.clientIp(req);
+          return clientAddr ? { [SEMCONV.CLIENT_ADDRESS]: clientAddr } : {};
+        })(),
+        (function () {
+          var ua = req.headers && req.headers["user-agent"];
+          return ua ? { [SEMCONV.USER_AGENT_ORIGINAL]: String(ua) } : {};
+        })(),
+        _captureHeaderAttrs(req, captureReqHeaders, "http.request.header")),
+    });
+
+    req.span = span;
+
+    var ended = false;
+    function _finish(err) {
+      if (ended) return;
+      ended = true;
+      try {
+        var status = res.statusCode;
+        if (typeof status === "number") {
+          span.setAttribute(SEMCONV.HTTP_RESPONSE_STATUS_CODE, status);
+          if (status >= 500) {
+            span.setStatus("error", "HTTP " + status);
+          } else if (status >= 400) {
+            // Per OTel semconv: client errors don't auto-set error status
+            // (they're "expected" failures). Operators that want to flag
+            // 4xx as errors call span.setStatus("error", ...) themselves.
+            span.setStatus("ok");
+          } else {
+            span.setStatus("ok");
+          }
+        }
+        if (err) span.recordException(err);
+        var resHeaders = _captureResponseHeaderAttrs(res, captureResHeaders, "http.response.header");
+        var resHeaderKeys = Object.keys(resHeaders);
+        for (var i = 0; i < resHeaderKeys.length; i++) {
+          span.setAttribute(resHeaderKeys[i], resHeaders[resHeaderKeys[i]]);
+        }
+        if (req.route && req.route.path) {
+          span.setAttribute(SEMCONV.HTTP_ROUTE, String(req.route.path));
+        }
+      } catch (_e) { /* drop-silent — observability sink */ }
+      try { span.end(); }
+      catch (_e) { /* drop-silent */ }
+      if (typeof onEnd === "function") {
+        try { onEnd(span.toJSON()); }
+        catch (_e) { /* operator hook — drop-silent */ }
+      }
+      if (auditOn) {
+        try {
+          observability().safeEvent("middleware.spanHttpServer.complete", 1, {
+            kind:    "server",
+            sampled: span.sampled ? "1" : "0",
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+    }
+
+    res.on("finish", function () { _finish(null); });
+    res.on("close",  function () { _finish(null); });
+    res.on("error",  function (e) { _finish(e); });
+
+    return next();
+  };
+}
+
+module.exports = {
+  create:        create,
+  SpanHttpError: SpanHttpError,
+};

package/lib/middleware/trace-log-correlation.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * trace-log-correlation middleware — wraps the operator's b.log
+ * instance for the request lifetime so every log() / info() / warn()
+ * / error() / debug() call inside the handler auto-includes the
+ * canonical trace_id + span_id (and tenant context from W3C Baggage
+ * when present).
+ *
+ *   var log = b.log.boot("api");
+ *   router.use(b.middleware.tracePropagate());
+ *   router.use(b.middleware.traceLogCorrelation({
+ *     logger:   log,
+ *     reqField: "log",   // attaches as req.log
+ *   }));
+ *
+ *   app.get("/widgets", function (req, res) {
+ *     // req.log is the wrapped logger; every emission carries
+ *     // trace_id + span_id + (optional) baggage attributes
+ *     req.log.info("loading widgets");
+ *     // → { ..., trace_id: "abc...", span_id: "def...",
+ *     //     baggage: { tenant: "acme" } }
+ *   });
+ *
+ * The wrapper is a thin adapter: it does not change log levels,
+ * sinks, or the b.log API surface. Logs pass through to the
+ * wrapped logger with the trace fields injected via the meta-object
+ * second argument.
+ *
+ * When no req.trace is present (unusual — operators typically mount
+ * tracePropagate first), the wrapper is a no-op pass-through; logs
+ * still flow but without correlation fields.
+ */
+
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var TraceLogError = defineClass("TraceLogError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+var LOG_LEVELS = ["debug", "info", "warn", "error", "fatal"];
+
+function _baggageToObject(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  var out = Object.create(null);
+  for (var i = 0; i < entries.length; i++) {
+    out[entries[i].key] = entries[i].value;
+  }
+  return out;
+}
+
+function _wrapLogger(baseLogger, req, opts) {
+  if (!baseLogger || typeof baseLogger !== "object") return baseLogger;
+  var wrapped = Object.create(null);
+  // Preserve any non-level properties the operator put on the
+  // logger (e.g. boot context, child-logger metadata).
+  var keys = Object.keys(baseLogger);
+  for (var i = 0; i < keys.length; i++) {
+    if (LOG_LEVELS.indexOf(keys[i]) === -1) wrapped[keys[i]] = baseLogger[keys[i]];
+  }
+
+  function _enrichMeta(meta) {
+    var enriched = Object.assign({}, meta || {});
+    if (req && req.trace) {
+      enriched.trace_id = req.trace.traceId;
+      // span_id prefers the active span (set by spanHttpServer) over
+      // the trace context's parentId
+      if (req.span && typeof req.span.spanId === "string") {
+        enriched.span_id = req.span.spanId;
+      } else if (typeof req.trace.parentId === "string") {
+        enriched.span_id = req.trace.parentId;
+      }
+      if (opts.includeBaggage !== false) {
+        var bg = _baggageToObject(req.trace.tracestate);
+        // tracestate is vendor-trace data; baggage is operator data.
+        // Operators usually want baggage in logs, not tracestate.
+        // We don't have a separate req.baggage today; keep this as
+        // the path for when tracePropagate exposes it. For now,
+        // emit the resolved tracestate shape under "trace_state".
+        if (bg) enriched.trace_state = bg;
+      }
+    }
+    return enriched;
+  }
+
+  // Bind each level on the underlying logger so it emits with the
+  // enriched meta. We don't replace the underlying logger's bound
+  // emitter shape — it still receives meta as the second argument.
+  for (var li = 0; li < LOG_LEVELS.length; li++) {
+    (function (lvl) {
+      if (typeof baseLogger[lvl] !== "function") return;
+      wrapped[lvl] = function (msg, meta) {
+        try { return baseLogger[lvl](msg, _enrichMeta(meta)); }
+        catch (_e) { /* drop-silent — log sink */ }
+      };
+    })(LOG_LEVELS[li]);
+  }
+  // Pass through anything else the logger might expose (boot, child, etc.)
+  if (typeof baseLogger.boot === "function") wrapped.boot = baseLogger.boot.bind(baseLogger);
+  if (typeof baseLogger.child === "function") wrapped.child = baseLogger.child.bind(baseLogger);
+  return wrapped;
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.traceLogCorrelation", TraceLogError);
+  validateOpts(opts, [
+    "logger", "reqField", "includeBaggage", "audit",
+  ], "middleware.traceLogCorrelation");
+
+  if (!opts.logger || typeof opts.logger !== "object") {
+    throw new TraceLogError("trace-log/bad-logger",
+      "middleware.traceLogCorrelation: logger must be a b.log instance");
+  }
+  var reqField = opts.reqField || "log";
+  if (typeof reqField !== "string" || reqField.length === 0) {
+    throw new TraceLogError("trace-log/bad-reqfield",
+      "middleware.traceLogCorrelation: reqField must be a non-empty string");
+  }
+
+  return function traceLogCorrelationMiddleware(req, res, next) {
+    req[reqField] = _wrapLogger(opts.logger, req, opts);
+    void observability;     // touch lazyRequire so the dep is captured
+    return next();
+  };
+}
+
+module.exports = {
+  create:        create,
+  TraceLogError: TraceLogError,
+  // exported for tests
+  _wrapLogger:   _wrapLogger,
+  LOG_LEVELS:    LOG_LEVELS,
+};

package/lib/middleware/trace-propagate.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * trace-propagate middleware — consumes the inbound `traceparent`
+ * header per W3C Trace Context (https://www.w3.org/TR/trace-context-1/)
+ * and stamps `req.trace = { traceId, parentId, sampled, hadUpstream }`
+ * for downstream handlers + propagation into outbound HTTP calls.
+ *
+ *   router.use(b.middleware.tracePropagate({
+ *     generateIfMissing: true,   // default — synthesise when absent
+ *     auditOnMissing:    true,   // emit `system.trace.synthesised` event
+ *     setResponseHeader: true,   // echo the resolved traceparent on res
+ *   }));
+ *
+ *   app.get("/widgets", function (req, res) {
+ *     // req.trace.traceId is the canonical id for this request
+ *     b.observability.event("widgets.request", 1, {
+ *       [b.observability.SEMCONV.HTTP_REQUEST_METHOD]: req.method,
+ *     });
+ *     // Propagate to an upstream call:
+ *     fetch(upstreamUrl, {
+ *       headers: {
+ *         traceparent: b.observability.traceContext.build({
+ *           traceId:  req.trace.traceId,
+ *           parentId: b.observability.traceContext.newParentId(),
+ *           sampled:  req.trace.sampled,
+ *         }),
+ *       },
+ *     });
+ *   });
+ *
+ * On bad / missing inbound traceparent:
+ *   - generateIfMissing: true (default) → synthesise a fresh trace,
+ *     stamp `hadUpstream: false` so downstream code knows this trace
+ *     was originated locally
+ *   - generateIfMissing: false → leave `req.trace = null`; downstream
+ *     code that depends on a trace MUST handle the null case
+ */
+
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var TracePropagateError = defineClass("TracePropagateError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+var audit = lazyRequire(function () { return require("../audit"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "generateIfMissing", "auditOnMissing",
+    "setResponseHeader", "audit",
+  ], "middleware.tracePropagate");
+
+  var generateIfMissing = opts.generateIfMissing !== false;     // default true
+  var auditOnMissing    = opts.auditOnMissing === true;         // default false (every request that doesn't carry a trace is noisy)
+  var setResponseHeader = opts.setResponseHeader === true;      // default false
+  var auditOn           = opts.audit !== false;
+
+  return function tracePropagateMiddleware(req, res, next) {
+    var tc = observability().traceContext;
+    var inbound = req.headers && req.headers.traceparent;
+    var parsed = (typeof inbound === "string") ? tc.parse(inbound) : null;
+    var inboundTracestate = req.headers && req.headers.tracestate;
+    var tracestateEntries = (typeof inboundTracestate === "string")
+      ? tc.parseTracestate(inboundTracestate)
+      : null;
+    if (parsed) {
+      req.trace = {
+        traceId:     parsed.traceId,
+        parentId:    parsed.parentId,
+        sampled:     parsed.sampled,
+        hadUpstream: true,
+        tracestate:  tracestateEntries || [],
+      };
+    } else if (generateIfMissing) {
+      req.trace = {
+        traceId:     tc.newTraceId(),
+        parentId:    tc.newParentId(),
+        sampled:     true,
+        hadUpstream: false,
+        tracestate:  [],
+      };
+      if (auditOnMissing && auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "system.trace.synthesised",
+            outcome:  "ok",
+            metadata: { route: req.url || "/", traceId: req.trace.traceId },
+          });
+        } catch (_e) { /* drop-silent — observability sink */ }
+      }
+    } else {
+      req.trace = null;
+    }
+
+    if (setResponseHeader && req.trace && !res.headersSent) {
+      try {
+        res.setHeader("traceparent", tc.build({
+          traceId:  req.trace.traceId,
+          parentId: req.trace.parentId,
+          sampled:  req.trace.sampled,
+        }));
+        if (req.trace.tracestate && req.trace.tracestate.length > 0) {
+          res.setHeader("tracestate", tc.buildTracestate(req.trace.tracestate));
+        }
+      } catch (_e) { /* drop-silent — header set best-effort */ }
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:               create,
+  TracePropagateError:  TracePropagateError,
+};