Module exec_events 

Structured exec-event exemplars — the wrapper-facing tap onto the system’s structured event sink (the observer surface, SRD-81/-88).

Wrappers OPT IN by implementing ExecEventSubscriber, a decorator service in the established wrapper style (a dyn-safe trait whose default methods ARE the service — the same shape as WrappingDispenser): implementing it grants the wrapper the canonical submission surface, and nothing else changes about the wrapper’s construction or registration. The default routing is the single chokepoint submit_exemplar: one rendered projection per event through crate::observer::log_tagged, which fans out to every installed sink — the durable session.log always, the live display per its level gates. No wrapper hand-rolls its own event formatting or reaches for a sink directly.

Exemplars, not streams

An ExecExemplar is a SAMPLED counter-exemplar: a concrete specimen of an error class that is otherwise visible only as a counter (e.g. attempt_failure inside the retry loop, where the error policy never sees the message because the attempt recovers). Sampling is the submitting wrapper’s job via ExemplarSampler: a fraction (rate, default 0.0 = off) decides which caught errors become exemplars, and a frequency ceiling (max_hz) squelches bursts. Squelched admissions are COUNTED, never dropped silently: the next emitted exemplar carries (+N squelched), and any leftover tally is flushed at Debug when the sampler drops.

Structs

AdvisoryGate

Per-phase advisory gate: by DEFAULT (no exemplar sampling opted in) the operator still gets at least SOME signal when the retry loop starts absorbing errors — one advisory per error class per phase, capped, so a retry storm identifies itself without flooding the session output. Shared per activity (like ExemplarConfig) so many ops in one phase share the budget.

ExecExemplar

One sampled error specimen from an execution wrapper.

ExemplarConfig

The sampling configuration cell: rate and frequency ceiling as shared atomics, so a dynamic control can move every sampler reading the cell with ONE store — push-on-set, no polling, no per-op control traffic (the cql_trace_rate pattern). Readers pay one atomic load, and only on the retry path.

ExemplarSampler

Sampling + squelch gate for exemplar submission.

Traits

ExecEventSubscriber

Decorator service: a wrapper subscribes to the structured event sink by implementing this trait (dyn-safe; default methods are the whole service). Override nothing to get the canonical routing; the trait exists so the subscription is a declared, greppable property of the wrapper type rather than an ad-hoc call into logging.

Functions

render_advisory

Render a first-sighting retry advisory. Pure — testable without an observer.

render_exemplar

Render an exemplar to its one-line session projection. Pure — separated from submit_exemplar so the format is testable without an observer.

submit_exemplar

The canonical submission chokepoint: one projection through the observer’s categorized log surface at Warn (an exemplar IS an error specimen the operator asked to see).