feat(otel): W3C traceparent transport-header propagation — Node core (ADR-0028)

Adds a HeaderCarrier seam (Record<string,string>, additive — the envelope stays
frozen, GR-1) and W3C traceparent inject/extract in otel.ts: the producer writes
the active span's traceparent onto an out-of-band header carrier; the consumer
starts its span as a child of that remote parent (true cross-hop linkage). No
header falls back to the v0.1 trace_id behaviour (no regression). traceparent
parse/format is hand-rolled — core stays dependency-free (GR-7). Per-adapter
wiring (babelqueue-node-adapters: bullmq/redis/rabbitmq/sqs) is a documented
follow-up.

Author: muhammetsafak

CHANGELOG.md

@@ -9,6 +9,27 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+### Added
+- **OpenTelemetry v0.2 — W3C `traceparent` cross-hop span linkage (ADR-0028).** The
+  `@babelqueue/core/otel` module now propagates the active span as a W3C `traceparent`
+  (and `tracestate`) **transport header** so a consumer span is a true **child** of the
+  producer span — not just a shared `trace_id` trace.
+  - New `HeaderCarrier` type (a `Record<string, string>` out-of-band header map) — the
+    seam the core and the `babelqueue-node-adapters` transports agree on. It rides
+    **beside** the frozen envelope, never inside it (`schema_version` stays **1**, GR-1).
+  - `publish(...)` takes an optional `options.headers` carrier and writes the producer
+    span's `traceparent` into it; `wrapHandler(tracer, handler, headers?)` reads a
+    delivered message's headers (a carrier or a sync/async getter) and starts the consumer
+    span as a remote-parent child. **No header ⇒ v0.1 `trace_id` fallback** (no regression);
+    fully opt-in and backward compatible.
+  - New low-level exports `injectTraceparent`, `remoteParentFromHeaders`,
+    `HEADER_TRACEPARENT`, `HEADER_TRACESTATE`. The W3C parse/format is implemented against
+    the frozen Trace Context format, so the optional dependency stays at `@opentelemetry/api`
+    only — the core itself remains zero-runtime-dependency (GR-7).
+  - **Per-adapter transport wiring** (bullmq/redis/rabbitmq/sqs in the separate
+    `babelqueue-node-adapters` repo) is a documented follow-up; until wired, propagation
+    degrades to v0.1 `trace_id` correlation with no error.
+
 ## [1.0.0] - 2026-06-07
 
 **1.0.0 — the public API is now SemVer-stable**: breaking changes require a MAJOR,

src/contracts.ts

@@ -18,3 +18,23 @@ export interface HasTraceId {
   /** The trace id to reuse, or null/undefined to mint a new one. */
   getBabelTraceId(): string | null | undefined;
 }
+
+/**
+ * Out-of-band per-message transport metadata that rides **beside** the frozen wire
+ * envelope, never inside it (GR-1: the envelope stays `schema_version: 1`). It is a
+ * plain string→string map — the seam the core and the `babelqueue-node-adapters`
+ * transports (bullmq/redis/rabbitmq/sqs) agree on for metadata that must not become an
+ * envelope field.
+ *
+ * The first rider is the W3C `traceparent` (and `tracestate`) header for true cross-hop
+ * span parent-child linkage (ADR-0028) — see `@babelqueue/core/otel`. It is the Node
+ * counterpart of the Go `HeaderPublisher.PublishWithHeaders` / `ReceivedMessage.Headers`
+ * seam and the same shape used by the replay-bypass marker (ADR-0027).
+ *
+ * An adapter carries it on its transport's native per-message metadata channel (e.g.
+ * AMQP message headers, SQS `MessageAttributes`, a Redis transport-owned frame), merging
+ * it beside the contract `bq-*`/`x-*` headers without clobbering them. A transport that
+ * has no such channel simply does not carry it, and propagation degrades to the v0.1
+ * `trace_id` correlation with no error — exactly as the Go side degrades.
+ */
+export type HeaderCarrier = Record<string, string>;

src/index.ts

@@ -23,7 +23,7 @@ export type {
   Meta,
 } from "./codec.js";
 
-export type { HasTraceId, PolyglotMessage } from "./contracts.js";
+export type { HasTraceId, HeaderCarrier, PolyglotMessage } from "./contracts.js";
 
 export { annotate } from "./deadLetter.js";
 export type { AnnotateOptions } from "./deadLetter.js";