Struct TraceContext 

pub struct TraceContext { /* private fields */ }

Cloneable handle carrying the sink, the lazily-loaded digest key, the session identity, and metadata-only degradation counters.

Implementations

impl TraceContext

pub fn emit_execution_enriched(&self, request_id: &TraceId)

Replace the first matching request record with an execution-enriched snapshot. Sinks that persist append-only records may retain both; the latest snapshot is authoritative for the request ID.

pub fn session_id(&self) -> &TraceId

Session identity shared by all request/tool events in this context.

pub fn record_execution_event(&self, event: ToolExecutionEvent)

Append bounded execution metadata for a request. This never fails the turn; malformed/unrepresentable fields are rejected before this seam.

pub fn execution_events(&self, request_id: &TraceId) -> Vec<ToolExecutionEvent>

pub fn latest_request_correlation(&self) -> Option<(TraceId, TraceId, TraceId)>

Test/stream seam: correlated IDs for the most recently begun request.

pub fn reserve_request_correlation(&self) -> Option<RequestCorrelation>

pub fn disabled() -> Self

Disabled context: no-op sink, no key I/O, zero request-path work.

pub fn with_sink(sink: Arc<dyn TraceSink>) -> Self

Context with the given sink and the installation default key path.

pub fn fork_with_sink(&self, sink: Arc<dyn TraceSink>) -> Self

Fork this context with a replacement sink, preserving the session identity, digest-key state, degradation counters, request sequence, and — crucially — the shared session [CacheSnapshotStore], so an armed one-shot request feeds the same §6.6 diagnostics that /context reads. The one-shot gate and content capture are NOT inherited: the caller attaches them explicitly.

pub fn with_content_capture(self, capture: Arc<ContentCapture>) -> Self

Attach a one-request content capture arm (see trace::controls).

pub fn with_one_shot_request_gate(self) -> Self

Arm the one-shot request gate: exactly one logical request (RequestTracer::begin) traces through this context, all its retry attempts included; subsequent requests are disabled. Only armed ephemeral contexts carry this — normal Basic/Full contexts never do.

pub fn cache_snapshots(&self) -> &Arc<CacheSnapshotStore>

The session cache snapshot store (spec §6.6 previous-turn compare).

pub fn capture_request_content(&self, request_id: &TraceId, body_bytes: &[u8])

Capture the request body for an armed one-shot content capture (no-op in every other context). body_bytes must be the request body only — never headers or credentials.

pub fn capture_unsupported(&self, reason: &str)

Explicitly fail an armed content capture on a provider path that has no capturable request body (e.g. the extension sidecar, which owns framing/serialization out of process). Fix for silent consumption: the arm is consumed visibly — one metadata-only warning plus a bump of the degraded-records counter that /trace status reports — instead of vanishing with no artifact and no signal. No-op in every context without an armed capture.

pub fn with_key_path(self, path: PathBuf) -> Self

Override the digest-key path (tests / non-default installs).

pub fn enabled(&self) -> bool

pub fn degraded_records(&self) -> u64

Records degraded/dropped for internal reasons since context creation.

pub async fn digest_key(&self) -> Option<Arc<TraceDigestKey>>

Load (or create) the installation digest key, once per context, off the async threads. Failure is remembered: it warns once (metadata only), bumps the degradation counter, and yields None forever — it can never fail or delay the request itself.

Trait Implementations

impl Clone for TraceContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TraceContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TraceContext

fn default() -> Self

Returns the “default value” for a type.