babelqueue 1.9.0__tar.gz → 1.11.0__tar.gz

{babelqueue-1.9.0 → babelqueue-1.11.0}/CHANGELOG.md

@@ -9,6 +9,31 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-06-21
+
+### Added
+- **W3C `traceparent` span-context propagation** (OpenTelemetry v0.2, ADR-0028) — the optional
+  `babelqueue.otel` module now carries true cross-hop **span** parent-child linkage, not just
+  shared-`trace_id` correlation. On publish, `otel.publish` injects the active span context as a
+  W3C `traceparent` **transport header** (and still stamps `trace_id` for the v0.1 fallback); on
+  consume, `otel.wrap_handler` extracts it and starts the CONSUMER span as a true **child** of the
+  producer span. With no `traceparent` present it falls back to the v0.1 `trace_id`-derived parent,
+  so it is a strict, backward-compatible upgrade — no regression. The header rides **out of band**
+  via a new dependency-free core seam — `BabelQueue.publish_with_headers(urn, data, headers, …)`
+  (produce side) and `babelqueue.headers_from_context()` (consume side, surfaced by the runtime) —
+  so the wire envelope stays **frozen** (`schema_version: 1`, GR-1) and the core stays
+  zero-dependency (OTel remains the optional `[otel]` extra, GR-7). `traceparent` is carried on the
+  **in-memory** (reference), **Redis** (a transport-owned `__bq_frame` JSON frame with bare-value
+  back-compat, so cross-version queues interoperate; degrades to a bare publish in Laravel-compat
+  mode), **RabbitMQ** (native AMQP header table, beside the contract `x-*` headers) and **SQS**
+  (native `MessageAttributes`, beside the contract `bq-*` attributes) transports; where a transport
+  can't carry headers, propagation degrades cleanly to v0.1 `trace_id` correlation with no error.
+  A plain `publish` is byte-identical to before. Unit-tested without a broker (frame round-trip +
+  bare back-compat, header merge/extract per transport, and an in-memory producer→consumer
+  parent-child end-to-end with the OTel SDK's `InMemorySpanExporter`); broker-gated integration
+  tests assert a published `traceparent` arrives on the consumed message's headers beside the
+  unchanged body. The envelope is unchanged; this is purely additive. Ships as a MINOR.
+
 ## [1.6.0] - 2026-06-14
 
 ### Added

{babelqueue-1.9.0 → babelqueue-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.9.0
+Version: 1.11.0
 Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
 Project-URL: Homepage, https://babelqueue.com
 Project-URL: Source, https://github.com/BabelQueue/babelqueue-python
@@ -234,6 +234,42 @@ def on_created(data, meta): ...
 python manage.py babelqueue_worker --queue orders          # run the consumer
 ```
 
+## OpenTelemetry tracing (optional)
+
+`pip install "babelqueue[otel]"` adds the optional `babelqueue.otel` module — the core never
+imports OpenTelemetry, so it stays zero-dependency. It emits a PRODUCER span per publish and a
+CONSUMER span per handled message, correlated across every hop and SDK, at two layered levels:
+
+- **`trace_id` correlation** (v0.1): the envelope's `trace_id` maps 1:1 to an OTel trace id, so
+  every hop that shares a `trace_id` shares one trace — with **zero** wire/transport change.
+- **W3C `traceparent` span linkage** (v0.2): the producer also injects its active span context as
+  a `traceparent` **transport header** (beside the frozen envelope, never in it), so the consumer
+  starts its span as a true **child** of the producer span — real cross-hop parent-child linkage.
+  With no `traceparent` present it falls back to the v0.1 `trace_id` behaviour, so enabling it is a
+  strict, backward-compatible upgrade.
+
+```python
+from opentelemetry import trace
+from babelqueue import BabelQueue, otel
+
+tracer = trace.get_tracer("orders")
+app = BabelQueue("redis://localhost:6379/0", queue="orders")
+
+# consumer: wrap_handler starts a CONSUMER span (child of the producer span when a
+# traceparent rode along; else in the trace_id-derived trace)
+app.register("urn:babel:orders:created", otel.wrap_handler(tracer, on_order_created))
+
+# producer: otel.publish starts a PRODUCER span and carries traceparent + trace_id
+otel.publish(tracer, app, "urn:babel:orders:created", {"order_id": 1042})
+```
+
+The `traceparent` rides the out-of-band transport-header seam (`publish_with_headers` /
+`headers_from_context`) — the same seam the replay-bypass marker uses — so the envelope stays
+frozen (`schema_version: 1`). It is carried on the in-memory, Redis (a transport-owned JSON frame,
+with bare-value back-compat), RabbitMQ (AMQP header table) and SQS (`MessageAttributes`)
+transports; where a transport can't carry it, propagation degrades cleanly to v0.1 `trace_id`
+correlation with no error.
+
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime

{babelqueue-1.9.0 → babelqueue-1.11.0}/README.md

@@ -182,6 +182,42 @@ def on_created(data, meta): ...
 python manage.py babelqueue_worker --queue orders          # run the consumer
 ```
 
+## OpenTelemetry tracing (optional)
+
+`pip install "babelqueue[otel]"` adds the optional `babelqueue.otel` module — the core never
+imports OpenTelemetry, so it stays zero-dependency. It emits a PRODUCER span per publish and a
+CONSUMER span per handled message, correlated across every hop and SDK, at two layered levels:
+
+- **`trace_id` correlation** (v0.1): the envelope's `trace_id` maps 1:1 to an OTel trace id, so
+  every hop that shares a `trace_id` shares one trace — with **zero** wire/transport change.
+- **W3C `traceparent` span linkage** (v0.2): the producer also injects its active span context as
+  a `traceparent` **transport header** (beside the frozen envelope, never in it), so the consumer
+  starts its span as a true **child** of the producer span — real cross-hop parent-child linkage.
+  With no `traceparent` present it falls back to the v0.1 `trace_id` behaviour, so enabling it is a
+  strict, backward-compatible upgrade.
+
+```python
+from opentelemetry import trace
+from babelqueue import BabelQueue, otel
+
+tracer = trace.get_tracer("orders")
+app = BabelQueue("redis://localhost:6379/0", queue="orders")
+
+# consumer: wrap_handler starts a CONSUMER span (child of the producer span when a
+# traceparent rode along; else in the trace_id-derived trace)
+app.register("urn:babel:orders:created", otel.wrap_handler(tracer, on_order_created))
+
+# producer: otel.publish starts a PRODUCER span and carries traceparent + trace_id
+otel.publish(tracer, app, "urn:babel:orders:created", {"order_id": 1042})
+```
+
+The `traceparent` rides the out-of-band transport-header seam (`publish_with_headers` /
+`headers_from_context`) — the same seam the replay-bypass marker uses — so the envelope stays
+frozen (`schema_version: 1`). It is carried on the in-memory, Redis (a transport-owned JSON frame,
+with bare-value back-compat), RabbitMQ (AMQP header table) and SQS (`MessageAttributes`)
+transports; where a transport can't carry it, propagation degrades cleanly to v0.1 `trace_id`
+correlation with no error.
+
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core), the `BabelQueue` runtime

{babelqueue-1.9.0 → babelqueue-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.9.0"
+version = "1.11.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"

{babelqueue-1.9.0 → babelqueue-1.11.0}/src/babelqueue/__init__.py

@@ -11,16 +11,18 @@ and dead-letter helpers. Framework adapters (Celery, Django, ...) build on this.
 
 from __future__ import annotations
 
-from . import dead_letter, idempotency, redrive
+from . import dead_letter, headers, idempotency, redrive, replay
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
+from .headers import headers_from_context
 from .idempotency import IdempotencyStore, InMemoryStore
 from .exceptions import BabelQueueError, UnknownUrnError
+from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
-from .transport import InMemoryTransport, ReceivedMessage, Transport
+from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "1.6.0"
+__version__ = "1.11.0"
 
 __all__ = [
     "BabelQueue",
@@ -33,11 +35,18 @@ __all__ = [
     "Transport",
     "InMemoryTransport",
     "ReceivedMessage",
+    "HeaderPublisher",
     "BabelQueueError",
     "UnknownUrnError",
     "dead_letter",
+    "headers",
     "idempotency",
     "redrive",
+    "replay",
+    "is_replay",
+    "bypass_external_effects",
+    "headers_from_context",
+    "HEADER_REPLAY_BYPASS",
     "IdempotencyStore",
     "InMemoryStore",
     "__version__",

{babelqueue-1.9.0 → babelqueue-1.11.0}/src/babelqueue/app.py

@@ -25,8 +25,10 @@ from typing import Any, Callable, Dict, Mapping, Optional
 from . import dead_letter
 from .codec import EnvelopeCodec
 from .exceptions import UnknownUrnError
+from .headers import _headers_scope
+from .replay import HEADER_REPLAY_BYPASS, _replay_scope
 from .routing import UnknownUrnStrategy
-from .transport import ReceivedMessage, Transport, make_transport
+from .transport import HeaderPublisher, ReceivedMessage, Transport, make_transport
 
 Handler = Callable[..., None]
 
@@ -69,6 +71,37 @@ class BabelQueue:
         self.transport.publish(target, EnvelopeCodec.encode(envelope))
         return envelope["meta"]["id"]
 
+    def publish_with_headers(
+        self,
+        urn: str,
+        data: Mapping[str, Any],
+        headers: Mapping[str, str],
+        *,
+        queue: Optional[str] = None,
+        trace_id: Optional[str] = None,
+    ) -> str:
+        """Publish a message together with out-of-band transport ``headers``; returns its id.
+
+        The headers ride **beside** the frozen envelope (GR-1) on the transport's per-message
+        metadata channel — e.g. a W3C ``traceparent`` for cross-hop span linkage (ADR-0028) —
+        never inside it. It is the produce-side counterpart of the headers the runtime surfaces
+        to a handler via :func:`~babelqueue.headers.headers_from_context`.
+
+        When the transport implements :class:`~babelqueue.transport.HeaderPublisher` and
+        ``headers`` is non-empty, the headers are propagated; otherwise it transparently falls
+        back to a plain :meth:`publish` (the headers are dropped — no error, no regression),
+        exactly as :func:`~babelqueue.redrive.redrive` degrades. Passing empty headers is
+        equivalent to :meth:`publish`, so callers need not branch on transport capability.
+        """
+        target = queue or self.queue
+        envelope = EnvelopeCodec.make(urn, data, queue=target, trace_id=trace_id)
+        body = EnvelopeCodec.encode(envelope)
+        if headers and isinstance(self.transport, HeaderPublisher):
+            self.transport.publish_with_headers(target, body, dict(headers))
+        else:
+            self.transport.publish(target, body)
+        return envelope["meta"]["id"]
+
     # -- Register handlers --------------------------------------------------
 
     def handler(self, urn: str) -> Callable[[Handler], Handler]:
@@ -115,19 +148,28 @@ class BabelQueue:
     run = consume
 
     def dispatch(self, received: ReceivedMessage) -> None:
-        """Route one reserved message to its handler and acknowledge it."""
-        envelope = EnvelopeCodec.decode(received.body)
-        urn = str(envelope.get("job") or envelope.get("urn") or "")
-        handler = self._handlers.get(urn) if urn else None
+        """Route one reserved message to its handler and acknowledge it.
 
-        try:
-            if handler is None:
-                self._route_unknown(urn, received, envelope)
-                return
-            self._invoke(handler, envelope)
-            self.transport.ack(received)
-        except Exception as exc:  # noqa: BLE001 - one bad message must not kill the loop
-            self._retry_or_dead_letter(received, envelope, exc)
+        The delivered message's out-of-band transport headers are surfaced onto the context for
+        the span of this dispatch (:func:`~babelqueue.headers.headers_from_context`), so a handler
+        or an optional wrapper (e.g. the ``otel`` module reading a W3C ``traceparent``, ADR-0028)
+        can read metadata that travels beside the frozen envelope (GR-1).
+        """
+        with _headers_scope(received.headers), _replay_scope(
+            bool(received.headers.get(HEADER_REPLAY_BYPASS))
+        ):
+            envelope = EnvelopeCodec.decode(received.body)
+            urn = str(envelope.get("job") or envelope.get("urn") or "")
+            handler = self._handlers.get(urn) if urn else None
+
+            try:
+                if handler is None:
+                    self._route_unknown(urn, received, envelope)
+                    return
+                self._invoke(handler, envelope)
+                self.transport.ack(received)
+            except Exception as exc:  # noqa: BLE001 - one bad message must not kill the loop
+                self._retry_or_dead_letter(received, envelope, exc)
 
     # -- Internals ----------------------------------------------------------
 

babelqueue-1.11.0/src/babelqueue/headers.py

@@ -0,0 +1,70 @@
+"""Consume-side out-of-band transport headers (the Python mirror of Go's ``headers.go``).
+
+The runtime surfaces a delivered message's :attr:`~babelqueue.transport.ReceivedMessage.headers`
+onto a :class:`contextvars.ContextVar` for the span of one dispatch, so a handler — or an
+optional wrapper such as the ``otel`` module — can read per-message metadata that travels
+**beside** the frozen envelope (GR-1), never in it. It is the consume-side counterpart of
+:class:`~babelqueue.transport.HeaderPublisher`.
+
+This is the same out-of-band seam the replay-bypass marker rides (ADR-0027); ADR-0028's W3C
+``traceparent`` (for cross-hop span parent-child linkage) is the second rider on it. The header
+map is read-only — treat it as immutable. Adds only :mod:`contextvars` + a plain ``dict`` (no
+dependency), exactly like :mod:`babelqueue.replay`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+from typing import Dict, Iterator, Mapping, Optional
+
+#: The delivered message's out-of-band transport headers, for the span of one dispatch.
+#: Defaults to an empty mapping so :func:`headers_from_context` is always nil-safe.
+_headers_var: contextvars.ContextVar[Mapping[str, str]] = contextvars.ContextVar(
+    "babelqueue_headers", default={}
+)
+
+
+def headers_from_context() -> Mapping[str, str]:
+    """Return the out-of-band transport headers that arrived with the message currently being
+    handled, or an empty mapping when none were carried (or the transport surfaces none).
+
+    The returned mapping is read-only — do not mutate it. It is the consume-side counterpart of
+    :class:`~babelqueue.transport.HeaderPublisher`: a handler or an optional wrapper (e.g. the
+    ``otel`` module's :func:`~babelqueue.otel.wrap_handler`) reads per-message metadata that
+    travels beside the frozen envelope, never in it (GR-1).
+    """
+    return _headers_var.get()
+
+
+@contextlib.contextmanager
+def _headers_scope(headers: Optional[Mapping[str, str]]) -> Iterator[None]:
+    """Internal: surface ``headers`` on the context for the span of one dispatch, then reset.
+
+    A nil/empty map is fine; reads stay nil-safe. The runtime calls this in
+    :meth:`~babelqueue.app.BabelQueue.dispatch` so wrappers can read the delivered headers.
+    """
+    scoped: Mapping[str, str] = headers or {}
+    token = _headers_var.set(scoped)
+    try:
+        yield
+    finally:
+        _headers_var.reset(token)
+
+
+def merge_headers(*sources: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    """Combine header maps into a single ``dict[str, str]``, dropping blank keys and blank values.
+
+    Later sources win a key collision. Returns a fresh dict (callers may mutate it freely). Used
+    to merge an injected ``traceparent`` onto a transport's contract headers without clobbering
+    them — the contract keys are passed *last* so they win (mirrors the Go merge-not-clobber).
+    """
+    out: Dict[str, str] = {}
+    for source in sources:
+        if not source:
+            continue
+        for key, value in source.items():
+            if not key or value is None or value == "":
+                continue
+            out[str(key)] = str(value)
+    return out

babelqueue-1.11.0/src/babelqueue/otel.py

@@ -0,0 +1,265 @@
+"""Optional OpenTelemetry tracing: produce/consume spans correlated across hops, with true
+cross-hop span parent-child linkage.
+
+The Python mirror of the Go ``babelqueue-go/otel`` module. It emits a CONSUMER span per
+handled message and a PRODUCER span per publish. Cross-hop trace propagation works at two
+layered levels:
+
+* **trace_id ↔ TraceID** (ADR-0025, v0.1): the envelope's ``trace_id`` — a UUID — maps 1:1 to a
+  128-bit OTel trace id, so every hop that shares a ``trace_id`` shares one OTel trace
+  (correlation + per-hop timing) with **zero** wire/transport change.
+* **W3C ``traceparent``** (ADR-0028, v0.2): the producer also injects the active span context as
+  a ``traceparent`` transport header (beside the frozen envelope, never in it), so the consumer
+  starts its span as a **true child** of the producer span — real cross-hop parent-child linkage.
+  This rides the out-of-band :class:`~babelqueue.transport.HeaderPublisher` /
+  :func:`~babelqueue.headers.headers_from_context` seam (ADR-0027) and is available on any
+  transport that carries headers. With no ``traceparent`` present it falls back to the v0.1
+  ``trace_id`` behaviour — a strict, backward-compatible upgrade (no regression).
+
+The wire envelope is untouched (GR-1) and the core never imports OpenTelemetry: this module is
+only importable with the ``[otel]`` extra (``pip install babelqueue[otel]``), exactly like the
+optional transport drivers.
+
+    from opentelemetry import trace
+    from babelqueue import BabelQueue, otel
+
+    tracer = trace.get_tracer("orders")
+    app = BabelQueue("redis://localhost:6379/0", queue="orders")
+    app.register("urn:babel:orders:created", otel.wrap_handler(tracer, on_order_created))
+    # producer side:
+    otel.publish(tracer, app, "urn:babel:orders:created", {"order_id": 1042})
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from opentelemetry.context import Context
+from opentelemetry.trace import (
+    NonRecordingSpan,
+    SpanContext,
+    SpanKind,
+    TraceFlags,
+    Tracer,
+    get_current_span,
+    set_span_in_context,
+)
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from .headers import headers_from_context, merge_headers
+
+Handler = Callable[..., None]
+
+_SYSTEM = "babelqueue"
+_MASK_128 = (1 << 128) - 1
+
+#: The out-of-band transport headers that carry W3C Trace Context across a hop (ADR-0028). They
+#: ride beside the frozen envelope on the transport's per-message metadata channel — the same
+#: seam as the replay-bypass marker (ADR-0027) — so a consumer starts its span as a true child of
+#: the producer's span, not merely share the ``trace_id``-derived trace. The envelope is untouched
+#: (GR-1). ``traceparent``/``tracestate`` are exactly the W3C wire format, so a babelqueue header
+#: interoperates with any OTel SDK or W3C-compliant peer.
+HEADER_TRACEPARENT = "traceparent"
+HEADER_TRACESTATE = "tracestate"
+
+#: The W3C Trace Context propagator. It reads/writes the ``traceparent`` (and ``tracestate``)
+#: headers — the exact wire format ADR-0028 names — so a babelqueue header interoperates with any
+#: W3C peer. The propagator's default getter/setter operate on a plain ``dict``/``Mapping``, which
+#: is exactly the shape of the SDK-owned transport-header map, so no custom carrier is needed.
+_propagator = TraceContextTextMapPropagator()
+
+
+def _inject_traceparent(context: Optional[Context]) -> Dict[str, str]:
+    """Write the active span context (in ``context``) as W3C ``traceparent`` (and ``tracestate``)
+    into a fresh header map. The producer half: the result is handed to a
+    :class:`~babelqueue.transport.HeaderPublisher` so the consumer can reconstruct the remote
+    parent. With no valid span context the propagator writes nothing and the map stays empty (so a
+    no-trace publish stays header-free)."""
+    carrier: Dict[str, str] = {}
+    _propagator.inject(carrier, context=context)
+    return carrier
+
+
+def _remote_parent_from_headers() -> Optional[Context]:
+    """Extract a W3C ``traceparent`` from the out-of-band transport headers surfaced on the
+    current context (:func:`~babelqueue.headers.headers_from_context`) and return a
+    :class:`~opentelemetry.context.Context` carrying the remote parent span context, or ``None``
+    when no valid ``traceparent`` is present.
+
+    The consumer half of true cross-hop parent-child linkage: a span started from the returned
+    context is a child of the producer's span (remote parent). ``None`` signals the caller to fall
+    back to the v0.1 ``trace_id``-derived parent (ADR-0025 Option 1)."""
+    headers = headers_from_context()
+    if not headers.get(HEADER_TRACEPARENT):
+        return None
+    extracted = _propagator.extract(dict(headers))
+    span_context = get_current_span(extracted).get_span_context()
+    if not span_context.is_valid:
+        return None
+    return extracted
+
+
+def trace_id_of(trace_id: str) -> int:
+    """Map an envelope ``trace_id`` to a deterministic 128-bit OTel trace id.
+
+    A UUID maps to its 16 raw bytes; any other string is hashed (SHA-256, first 16 bytes).
+    The result is never zero (OTel's invalid trace id). The inverse of :func:`uuid_of` for
+    the UUID case.
+    """
+    raw = _uuid_bytes(trace_id)
+    if raw is not None:
+        n = int.from_bytes(raw, "big")
+        if n != 0:
+            return n
+    digest = hashlib.sha256(trace_id.encode("utf-8")).digest()[:16]
+    return int.from_bytes(digest, "big") or 1
+
+
+def uuid_of(trace_id_int: int) -> str:
+    """Format a 128-bit OTel trace id as a canonical UUID string.
+
+    The form a producer stamps into the message's ``trace_id`` so a consumer can recover the
+    same trace id via :func:`trace_id_of`.
+    """
+    h = format(trace_id_int & _MASK_128, "032x")
+    return f"{h[0:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:32]}"
+
+
+def _uuid_bytes(s: str) -> Optional[bytes]:
+    h = s.replace("-", "")
+    if len(h) != 32:
+        return None
+    try:
+        return bytes.fromhex(h)
+    except ValueError:
+        return None
+
+
+def _span_id_of(trace_id: str) -> int:
+    """Derive a deterministic, non-zero 64-bit span id so the remote parent context is valid
+    (a span needs a valid parent to inherit a specific trace)."""
+    digest = hashlib.sha256(("babelqueue-span:" + trace_id).encode("utf-8")).digest()[:8]
+    return int.from_bytes(digest, "big") or 1
+
+
+def _parent_context(trace_id: str) -> Context:
+    sc = SpanContext(
+        trace_id=trace_id_of(trace_id),
+        span_id=_span_id_of(trace_id),
+        is_remote=True,
+        trace_flags=TraceFlags(TraceFlags.SAMPLED),
+    )
+    return set_span_in_context(NonRecordingSpan(sc))
+
+
+def _wants_envelope(fn: Handler) -> bool:
+    """True if ``fn`` takes a 3rd positional arg (the full envelope) or ``*args``."""
+    try:
+        params = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError):  # pragma: no cover - builtins / C callables
+        return False
+    positional = [
+        p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    return any(p.kind == p.VAR_POSITIONAL for p in params) or len(positional) >= 3
+
+
+def wrap_handler(tracer: Tracer, handler: Handler) -> Handler:
+    """Wrap a consume handler to emit a CONSUMER span per message.
+
+    Register it like any handler: ``app.register(urn, wrap_handler(tracer, handler))``. The
+    wrapper's ``*args`` signature makes the runtime pass the full envelope (``data, meta,
+    envelope``), so it can read ``trace_id``/``job`` even when the inner handler only wants
+    ``(data, meta)``. A raising handler records the exception on the span and re-raises, so the
+    runtime's retry / dead-letter path still applies.
+
+    **Parent selection** (ADR-0028): when the producer carried a W3C ``traceparent`` on the
+    transport (surfaced by the runtime via :func:`~babelqueue.headers.headers_from_context`), the
+    span is started as a true **child** of the producer's span — real cross-hop parent-child
+    linkage with per-hop span timing. With no ``traceparent`` present it falls back to the v0.1
+    behaviour: a remote parent derived from the envelope's ``trace_id`` (ADR-0025 Option 1), which
+    shares the trace but not the exact span link. So enabling propagation is a strict,
+    backward-compatible upgrade — no regression for messages produced without it.
+    """
+
+    def wrapped(*args: Any) -> None:
+        envelope = args[2] if len(args) > 2 and isinstance(args[2], Mapping) else {}
+        meta = args[1] if len(args) > 1 and isinstance(args[1], Mapping) else {}
+        trace_id = str(envelope.get("trace_id") or "")
+        urn = str(envelope.get("job") or envelope.get("urn") or "")
+
+        attributes: dict[str, Any] = {
+            "messaging.system": _SYSTEM,
+            "messaging.operation": "process",
+            "messaging.destination.name": str(meta.get("queue") or ""),
+            "messaging.message.id": str(meta.get("id") or ""),
+            "messaging.message.conversation_id": trace_id,
+            "messaging.babelqueue.attempts": int(envelope.get("attempts", 0) or 0),
+        }
+        # Prefer a true remote parent from a carried W3C traceparent (v0.2); else fall back to the
+        # trace_id-derived parent (v0.1). A header-less / malformed traceparent yields None.
+        context = _remote_parent_from_headers()
+        if context is None and trace_id:
+            context = _parent_context(trace_id)
+
+        with tracer.start_as_current_span(
+            "process " + urn,
+            context=context,
+            kind=SpanKind.CONSUMER,
+            attributes=attributes,
+        ):
+            if _wants_envelope(handler):
+                handler(*args)
+            else:
+                handler(args[0], args[1])
+
+    return wrapped
+
+
+def publish(
+    tracer: Tracer,
+    app: Any,
+    urn: str,
+    data: Mapping[str, Any],
+    *,
+    queue: Optional[str] = None,
+) -> str:
+    """Publish via a PRODUCER span ``publish <urn>``, propagating the trace downstream two ways
+    (ADR-0028):
+
+    * It injects the active span context as a W3C ``traceparent`` (and ``tracestate``) onto the
+      outgoing transport headers, so a consumer can start its span as a true **child** of this
+      producer span — real cross-hop parent-child linkage. The header rides beside the frozen
+      envelope, never in it (GR-1), via ``app.publish_with_headers``; if the transport can't carry
+      headers it degrades to a plain publish (the ``traceparent`` is simply not propagated — no
+      error).
+    * It also carries the active trace's id into the message's ``trace_id`` (the v0.1 behaviour),
+      so even a consumer that ignores the header — or a transport that drops it — still recovers
+      the same trace (correlation without exact span linkage).
+
+    Behaves like ``app.publish`` (returns the message id). ``app`` is any object exposing
+    ``publish(urn, data, *, queue=None, trace_id=None) -> str``; when it also exposes
+    ``publish_with_headers(urn, data, headers, *, queue=None, trace_id=None) -> str`` the
+    ``traceparent`` is propagated, otherwise it transparently falls back to ``publish``.
+    """
+    attributes = {
+        "messaging.system": _SYSTEM,
+        "messaging.operation": "publish",
+        "messaging.destination.name": urn,
+    }
+    with tracer.start_as_current_span(
+        "publish " + urn, kind=SpanKind.PRODUCER, attributes=attributes
+    ) as span:
+        trace_id = uuid_of(span.get_span_context().trace_id)
+        headers = merge_headers(_inject_traceparent(set_span_in_context(span)))
+        publish_with_headers = getattr(app, "publish_with_headers", None)
+        if headers and callable(publish_with_headers):
+            message_id = publish_with_headers(
+                urn, data, headers, queue=queue, trace_id=trace_id
+            )
+        else:
+            message_id = app.publish(urn, data, queue=queue, trace_id=trace_id)
+        span.set_attribute("messaging.message.id", message_id)
+        return message_id