Module scope 

obs::scope! and obs::context! runtime support — task-local / thread-local stacks of ScopeFrames, the tail-on-error ring buffer, and the auto-fill machinery used by EventSchema::project.

Spec 13 §§ 2 + 3, spec 11 § 4.1 (pipeline order steps 3 + 5).

Structs

ScopeFrame

One frame on the per-task / per-thread scope stack.

ScopeFrameBuilder

Programmatic builder for pushing an obs::scope!-shaped frame.

ScopeGuard

RAII guard returned by obs::scope! and obs::context!. Dropping pops the frame; for Scope kind frames where any >= ERROR envelope was observed, the tail buffer is flushed back through the active observer with sampling_reason = TAIL_ERROR.

Enums

ScopeField

A field declared on obs::scope! / obs::context!. Field types match the envelope projection contract: trace ids land on the typed envelope slots, labels go into env.labels. Spec 13 § 2.1.

ScopeKind

Whether a frame carries a tail-on-error buffer (Scope) or is a pure broadcast frame (Context). Spec 13 § 2.2.

Functions

active_correlation

Read the active scope’s correlation pair as Some((trace_id, span_id)) when both have been pushed, otherwise None. Walks the stack innermost-first so the deepest set value wins — matches the auto-fill ordering in auto_fill_envelope.

active_sampled

Inbound sampled decision exposed under the same naming as active_correlation so callers can grab both with one symmetrical import. Equivalent to inbound_traceparent_sampled. Spec 95 D8-2.

auto_fill_envelope

Walk active scopes innermost-first and inject any declared fields the envelope is missing. Mirrors spec 13 § 2.1: only None-equivalent envelope slots inherit; explicit values pass through untouched.

inbound_traceparent_sampled

Inbound traceparent.sampled decision from the outermost (oldest) scope frame, when set. Spec 13 § 6.

mark_error_on_active_scopes

Mark every active scope frame as having seen an error so the outermost scope’s drop will trigger the tail-on-error flush. Spec 13 § 6.

pop_frame_pub

Public pop helper. See push_frame_pub for ownership rules.

push_frame_pub

Public push helper for external integrations that own their own pop (e.g. the tracing bridge pushes on on_enter and pops on on_exit). External callers MUST pair every call to push_frame_pub with exactly one call to pop_frame_pub in LIFO order — using ScopeFrameBuilder + the returned ScopeGuard is preferred when the lifetime is RAII-shaped. Spec 94 D7-3.

push_tail_buffer

Push an envelope onto the innermost active scope’s tail buffer (if the scope is a Scope, not a Context). No-op when no frame is active or the active frame is Context. Spec 13 § 6.

with_frames_innermost_first

Visit every active scope frame innermost-first. Used by auto_fill_envelope and by obs::SpanTrace.