Struct Activity 

pub struct Activity {

    pub config: ActivityConfig,
    pub labels: Labels,
    pub metrics: Arc<ActivityMetrics>,
    pub op_sequence: OpSequence,
    pub phase_kernel: Option<Arc<ScopeKernel>>,
    pub error_policy: Arc<ErrorPolicy>,
    pub workload_params: Arc<HashMap<String, String>>,
    pub stop_flag: Arc<AtomicBool>,
    pub walk_stop: Option<Arc<AtomicBool>>,
    pub daemon_stop: Option<Arc<AtomicBool>>,
    pub stop_reason: Arc<Mutex<Option<String>>>,
    pub stop_outcome: Arc<Mutex<Option<Outcome>>>,
    pub phase_errors: Arc<Mutex<Vec<PhaseErrorDetail>>>,
    pub validation_frame: Arc<Mutex<Option<MetricSet>>>,
    pub component: Option<Arc<RwLock<Component>>>,
    pub wrappers_override: Option<Vec<String>>,
    pub wrap_default_order: Option<Vec<String>>,
    pub exemplar_config: Arc<ExemplarConfig>,
    pub advisory_gate: Arc<AdvisoryGate>,
    pub memo: Arc<ArcSwap<String>>,
    pub gutter: Arc<ArcSwapOption<GutterSpec>>,
    pub gutter_spec: Mutex<Option<(GutterKind, String)>>,
    pub gutter_final_spec: Mutex<Option<(GutterKind, String)>>,
    pub phase_poll: Option<PhasePollContext>,
    /* private fields */
}

A running activity.

Fields

config: ActivityConfig

labels: Labels

metrics: Arc<ActivityMetrics>

op_sequence: OpSequence

phase_kernel: Option<Arc<ScopeKernel>>

SRD-83 — this phase node’s own scope kernel (the structural walk’s cached_kernel). Stop-condition predicates bind to THIS native scope as it sits, not a conjured root. None when the phase has no installed kernel (then no conditions evaluate).

error_policy: Arc<ErrorPolicy>

SRD-82 — the phase shell’s [crate::error_policy::ErrorPolicy] (op router + aggregate guard), resolved at scope-init from the parent policy so equal configs share one instance. Built standalone only on the test/library path (Self::with_params).

workload_params: Arc<HashMap<String, String>>

Resolved workload parameters (constant per run).

stop_flag: Arc<AtomicBool>

Shared flag: set to true when a stop error handler fires. All fibers check this and exit their loop when set.

walk_stop: Option<Arc<AtomicBool>>

Per-execution walk-stop flag (SRD-82 Part 4), cloned from this execution’s WorkloadShell. Distinct from stop_flag (which is this phase’s OWN stop): set when the scenario WALK halts — a sibling phase failed (a fault) or a stop condition tripped — so in-flight fibers abort cooperatively and a concurrent (Bounded(N>1)) sibling phase stops instead of draining. None outside a walk (tests, the library shim) → never aborts.

daemon_stop: Option<Arc<AtomicBool>>

SRD-82 Part 6 — set ONLY for a daemon phase: the daemon-group completion flag, latched by the scenario shell once the scope’s foreground phases finish. A daemon phase’s fibers poll it at their cooperative boundaries and exit, so the daemon stops when the foreground it shadows completes. None for foreground phases.

stop_reason: Arc<Mutex<Option<String>>>

First error message that triggered stop_flag — captured once (the first stopping error wins, subsequent fibers’ errors don’t overwrite). Surfaced in the phase-level error so the user doesn’t have to grep the per-cycle log to learn what actually stopped the run.

stop_outcome: Arc<Mutex<Option<Outcome>>>

SRD-83 Part 5 — the two-axis Outcome of the FIRST stop-condition trip that stopped this phase, latched together with stop_reason (same first-stopper-wins discipline, written inside the same slot win). A stop effect latches Interrupted+Succeeded — a clean early halt whose partial result the phase keeps; fail/abort latch Interrupted+Failed. The executor reads this at phase end so the shell adopts the condition’s DECLARED outcome instead of deriving failure from the bare stop flag. None whenever the stop came from any other source (error router stop verb, walk stop, poll timeout, Ctrl-C) — those keep failure semantics.

phase_errors: Arc<Mutex<Vec<PhaseErrorDetail>>>

SRD-76 — chronologically ordered per-cycle error records. Populated by the per-cycle dispatch path (alongside the existing stop_reason formatted string) so the executor can drain a structured list into PhaseOutcome.errors at phase end. The stop_reason string stays — it’s the single load-bearing format the executor reads to compose the phase 'X' stopped by error handler: log line. This buffer is the orthogonal structured projection.

validation_frame: Arc<Mutex<Option<MetricSet>>>

Final validation metrics frame, populated after all cycles complete. Read by the metrics capture thread after the activity finishes.

component: Option<Arc<RwLock<Component>>>

Optional handle to this activity’s component in the session tree. Set by the runner via Self::attach_component before execution; when present, the executor declares the concurrency control on it (SRD 23) and wires the [crate::fiber_pool::ConcurrencyApplier] so runtime writes resize the fiber pool.

wrappers_override: Option<Vec<String>>

SRD-32a Push 3 — workload-root wrapper-composition override. When populated (from the workload’s wrappers: { order: [...] } block), every op template that doesn’t carry its own per-template override uses this innermost-to-outermost list as its composition order. Validated against the per-op triggered set at cascade time; mismatch is a hard error per SRD-32a §“Workload-level override”.

wrap_default_order: Option<Vec<String>>

SRD-32a Push 3 — CLI --wrap-default-order override. Replaces the resolver’s built-in DEFAULT_ORDER tiebreaker for this activity. None ⇒ resolver uses the built-in order. Distinct from wrappers_override: that pins the per-op stack; this changes the tiebreaker used when constraints leave order ambiguous.

exemplar_config: Arc<ExemplarConfig>

Shared retry-exemplar sampling config (exec_events): every tries wrapper in this activity that does NOT pin its own retry_exemplar_* op params samples through this cell, so the retry_exemplar_rate / retry_exemplar_max_hz dynamic controls (declared in Self::attach_component) move them all with one atomic store — push-on-set, no per-op control traffic, and the read only happens on the retry path.

advisory_gate: Arc<AdvisoryGate>

Shared per-phase retry advisory gate (exec_events): one first-sighting advisory per error class per phase, capped — the default-on signal that the retry loop started absorbing errors. Ops opt out with retry_advisory: off.

memo: Arc<ArcSwap<String>>

Phase memo — a short operator-visible string that the memo wrapper publishes via before: / after: templates. Read by the inline-status readout and rendered as [[ <memo> ]] above the status line when non-empty. Lock-free atomic so the inline thread can load it every tick without blocking the executor. Default empty.

gutter: Arc<ArcSwapOption<GutterSpec>>

Phase gutter — the contextual left-gutter cell content that the gutter wrapper publishes (distinct from memo, which owns the [[ ... ]] header line). None ⇒ the display derives the cell automatically (completion bar for metered phases, latency trend for daemons); Some overrides that derivation with the workload-declared spec. Lock-free atomic for the same reason as memo.

gutter_spec: Mutex<Option<(GutterKind, String)>>

The op-declared DURING-execution gutter template (kind + template), retained for the guaranteed one-final-update at phase end when no final: form is declared.

gutter_final_spec: Mutex<Option<(GutterKind, String)>>

The op-declared final: gutter template — evaluated once at phase end (wires first, status-metric aggregates as fallback) and rendered as the ✓ outcome detail line’s gutter cell.

phase_poll: Option<PhasePollContext>

SRD-75 phase-poll context. When present, the fiber loop checks the predicate after each source-exhaustion event; if false and the timeout hasn’t elapsed, the source factory rewinds and the loop continues. None ⇒ no phase-poll (standard activity semantics). Set by the executor at run-phase entry; not part of the YAML-derived ActivityConfig.

Implementations

impl Activity

pub fn new( config: ActivityConfig, parent_labels: &Labels, op_sequence: OpSequence, ) -> Self

pub fn with_params( config: ActivityConfig, parent_labels: &Labels, op_sequence: OpSequence, params: HashMap<String, String>, ) -> Self

pub fn with_params_and_sigdigs( config: ActivityConfig, parent_labels: &Labels, op_sequence: OpSequence, params: HashMap<String, String>, sigdigs: u8, error_policy: Arc<ErrorPolicy>, phase_kernel: Option<Arc<ScopeKernel>>, metric_detail: &MetricDetailConfig, ) -> Self

Build an activity with explicit HDR significant-digits precision. Used by the runner after it resolves hdr.sigdigs from the session root (SRD 40); every histogram the activity owns is constructed at this precision. Callers that don’t resolve from a tree can use Self::with_params which defaults to nmbrs_metrics::instruments::histogram::DEFAULT_HDR_SIGDIGS.

pub fn walk_stop_requested(&self) -> bool

Whether this execution’s scenario walk has halted (SRD-82 Part 4). Fibers poll this at their cooperative boundaries, alongside stop_flag and session_signals::stop_requested(), to abort an in-flight phase when a sibling failed or a stop condition tripped. false when no walk-stop flag is wired (tests / shim).

pub fn daemon_stop_requested(&self) -> bool

Whether this (daemon) phase’s group has signalled completion (SRD-82 Part 6) — the scenario shell latches daemon_stop once the scope’s foreground phases finish, and the daemon’s fibers poll this to exit. false for a foreground phase (no flag wired).

pub fn stopped(&self) -> bool

SRD-92 Step 0 — the cooperative-stop view at a loop BREAK boundary: the activity stop_flag, the global / per-execution session stop, the SRD-83 walk_stop, and the SRD-82 P6 daemon_stop. Replaces the scattered per-flag loads at the fiber boundaries. (The failure-determining return deliberately uses a different set that EXCLUDES daemon_stop — see crate::session_signals::StopView::abnormal.)

pub fn stop_view(&self) -> StopView

The portable StopView for this activity — handed to the while: wrapper (a Send + 'static dispenser that cannot borrow the activity) so its loop observes the full stop set, not just stop_flag. Built once at wrapper construction, after walk_stop / daemon_stop are set in run_phase.

pub fn set_wrappers_override(&mut self, order: Option<Vec<String>>)

SRD-32a Push 3 — set the workload-root wrapper- composition override on this activity. Pass None to clear; pass Some(order) to install. The order list is innermost-to-outermost; per-op wrappers: blocks shadow this entry entirely.

pub fn set_wrap_default_order(&mut self, order: Option<Vec<String>>)

SRD-32a Push 3 — set the resolver’s default-order tiebreaker for this activity (CLI --wrap-default-order). None ⇒ the resolver uses its built-in DEFAULT_ORDER list.

pub fn attach_component(&mut self, component: Arc<RwLock<Component>>)

Attach this activity to its component in the session tree. The runner creates the component and installs it here so run_with_* can register appliers on the activity’s declared controls.

Structural control declarations happen here — not at run time — so dryrun=controls (and every other pre-execution discovery path) sees the activity’s controls without needing to start any cycles. Appliers that depend on run-time state (the fiber pool, the rate limiter) are registered later in run_with_adapters.

pub fn shared_metrics(&self) -> Arc<ActivityMetrics>

Get a shared reference to the metrics for external capture.

pub async fn run_with_driver( self, adapter: Arc<dyn DriverAdapter>, op_builder: Arc<OpBuilder>, ) -> bool

Run the activity with a single adapter for all ops.

pub async fn run_with_adapters( self, adapters: HashMap<String, Arc<dyn DriverAdapter>>, default_adapter: &str, op_builder: Arc<OpBuilder>, ) -> bool

Run the activity with multiple adapters (SRD 38/40).

Each op template’s adapter param selects which adapter to use. Templates without an explicit adapter use default_adapter. At init time: maps each template to a dispenser from the appropriate adapter. Per fiber: creates a FiberBuilder. Per cycle: resolves fields via GK, executes via dispenser. Returns true if the activity was stopped by an error handler.