-spec child_context(context(), map()) -> {ok, context()} | {error, term()}.

Create a correlated child span context.

Trace/run/session identity is inherited. The parent's span ID becomes the child parent ID. Additional agent/model/tool/call fields may be overridden.

-spec decode(map()) -> {ok, envelope()} | {error, term()}.

Decode a persisted envelope. Unknown schema versions are rejected.

-spec deliver(envelope(), map()) -> {ok, term()} | {error, term()}.

Deliver through either the compatibility synchronous path or the bounded supervised asynchronous bus.

Async admission is explicit: a full queue is returned to the caller and is also visible in bus counters. failure_policy controls whether admission failure is reported (closed) or converted into a structural dropped result (open).

-spec emit([atom(), ...], map(), context(), map()) -> {ok, envelope()} | {error, term()}.

Emit a connected telemetry event and return its structured envelope.

Options are attributes, capture_content (default false), and content. Even when capture is enabled, secret-bearing keys are removed before either telemetry handlers or exporters can see them.

-spec encode(envelope()) -> {ok, envelope()} | {error, term()}.

Verify and return the canonical JSON-safe envelope.

-spec export(envelope(), [map()]) -> {ok, [map()]} | {error, term()} | {error, term(), [map()]}.

Deliver one already-safe envelope to bounded exporters in list order.

Exporter descriptors use id, module, optional config, timeout_ms, max_heap_words, and failure_policy (open by default). Fail-open exporters report failure and allow later exporters to run. Fail-closed stops immediately with a typed error.

-spec finish_span(map(), term(), map()) -> {ok, map()} | {error, term()}.

Finish an operation span and update bounded low-cardinality metrics.

-spec from_headers(map() | list(), map()) -> {ok, context()} | {error, term()} | not_found.

Continue a valid inbound W3C trace with a fresh local span.

This function validates wire syntax but deliberately does not decide whether the remote sampling bit should be trusted. Network boundaries may clear trace_flags or start a new trace before calling it.

-spec inject_headers(context(), map() | list()) -> {ok, map() | list()} | {error, term()}.

Inject this context into outbound HTTP-style headers.

-spec new_context(map()) -> {ok, context()} | {error, term()}.

Build a root correlation context.

Known identity fields are copied explicitly; unknown safe fields are placed below attributes. Binary input is never converted into an atom.

-spec report_delivery_failure(atom(), term(), map()) -> ok.

Surface an exporter failure which happened after an operation had already completed. Only structural tags and correlation IDs are emitted; the untrusted exporter reason is never forwarded. This diagnostic is deliberately separate from the operation result so callers cannot replay a successful model/tool side effect merely because span delivery failed.

-spec start_span(atom() | binary(), atom() | binary(), context(), map(), map()) ->
                    {ok, map()} | {error, term()}.

Start a real operation span at the execution boundary.

Details is mapped through the pinned metadata-only GenAI convention; it cannot inject prompt/output content. The returned handle carries monotonic timing and must be finished exactly once by the operation owner.

-spec validate_exporters([map()]) -> ok | {error, term()}.

Validate exporter descriptors at Runner construction time. Callback execution still revalidates the immutable descriptors so a forged Runner term cannot bypass the boundary.