The bridge's keyed (session_id, macrostep) span-context read: the public lookup a wire-format producer needs to stamp OTel correlation ids onto the messages it emits.

Why it exists

statifier_ui's trace wire format (its ADR-0013) reserves an optional otel envelope key carrying the W3C trace and span ids of the statifier.macrostep span a message belongs to, and specifies the seam that fills it as a host-supplied function:

otel_context: (session_id, macrostep ->
                 {:ok, %{trace_id: binary, span_id: binary}} | :none)

That record's arguments are (session_id, macrostep) and not "the currently open span" on purpose: the subscriber stamping the message is its own process consuming asynchronously, so "current" would silently stamp the wrong macrostep under lag. The same record names the lookup as an open dependency on this package, and this module is the answer - lookup/2 has exactly that arity and exactly that return shape, so a host wires the two together by passing the capture and nothing else:

StatifierUI.Trace.Subscriber.start_link(
  session: session,
  otel_context: &OpentelemetryStatifier.SpanContext.lookup/2
)

(The subscriber's :otel_context option is statifier_ui's own follow-up to that record; this side of the seam is ready for it.)

What it reads

The bridge already holds every open macrostep span in the ETS table OpentelemetryStatifier.SpanTable owns, for its own link stitching. This is a read of that table and nothing more: no OTel context is created, entered, or attached, so ADR-0003 decision 8 - a macrostep span never starts from and is never attached to the process's ambient context - is untouched, and calling lookup/2 from any process is safe.

The macrostep counter a span covers is stamped onto its row by OpentelemetryStatifier.Handler from the first intra-macrostep event that lands on it, because statifier's macrostep :start event carries no such measurement. Every message the wire format may stamp is produced by one of those events, so a macrostep with a message to correlate always has its counter recorded.

When it answers :none

:none is an ordinary answer, not an error, and it is what the wire format degrades to (the key is simply absent). It is returned when the bridge was never set up, when session_id is unknown, when the macrostep's span has already closed - a subscriber lagging behind the session process is the common case - and when the span context on the row carries no valid ids. Consumers never see half a pair: ADR-0013 requires both ids or neither, and this module returns both or :none.