nmbrs_runtime/lib.rs
1// Copyright 2024-2026 Jonathan Shook
2// SPDX-License-Identifier: Apache-2.0
3
4//! # nmbrs-runtime
5//!
6//! Workload execution runtime for nmbrs. Owns the async dispatch
7//! loop, the adapter trait that workload backends implement, op
8//! sequencing across stanzas, error-handler integration, observer
9//! callbacks, and the runner that ties everything together.
10//!
11//! This is the integration crate — it depends on every other
12//! `nb-*` library and is depended on by `nmbrs` (and by every
13//! persona binary). External consumers shouldn't usually need to
14//! reach into it directly; the public-facing path is `nmbrs run`
15//! or [`runner::Runner`].
16//!
17//! ## Pieces
18//!
19//! - [`adapter::DriverAdapter`] — the trait every workload
20//! backend implements. CQL, HTTP, stdout, testkit, plotter, and
21//! user-supplied adapters all register via the inventory
22//! pattern in [`adapters`].
23//! - [`activity::Activity`] — one running concurrency unit. Owns
24//! the cycle source, the op sequencer, the fiber pool, the
25//! error router, and the metrics scope. Multiple activities
26//! can run concurrently within one phase.
27//! - [`runner::Runner`] — orchestrates the whole session: parse
28//! workload, build component tree, route metrics, walk the
29//! scenario tree, supervise activities.
30//! - [`scope_tree`] / [`scene_tree`] — the canonical scenario-
31//! tree shape and the runtime presentation surface (SRD 18b).
32//! - [`scheduler`] — `schedule=` CLI param parses to a
33//! [`scheduler::ScheduleSpec`]; the [`scheduler::TreeScheduler`]
34//! walks the tree and forks concurrent siblings via
35//! `tokio::JoinSet` + `Semaphore` based on per-level limits.
36//! - [`observer::RunObserver`] — lifecycle callbacks (phase
37//! start / progress / complete / fail). The TUI is one
38//! implementor; stderr is the default.
39//! - [`bindings`] / [`scope`] — workload bindings → Polydat Kernel
40//! compilation, with cache-and-rebind across phase iterations.
41//!
42//! ## Out of scope
43//!
44//! - Polydat DSL parsing and compilation: see [`polydat`].
45//! - Workload YAML parsing: see [`nmbrs_workload`].
46//! - Component tree, instruments, cadence reporter: see
47//! [`nmbrs_metrics`].
48//! - Rate limiting: see [`nmbrs_rate`].
49//! - Error handler primitives: see [`nmbrs_errorhandler`].
50//!
51//! ## See also
52//!
53//! - SRD 29 (`docs/SRD/29_execution_engine.md`) — the engine
54//! front door: this crate's public contract surface, the
55//! load-bearing axioms, and the SRD ↔ module map.
56//! - SRD 01 (`docs/SRD/01_system_overview.md`) — overall
57//! architecture.
58//! - SRD 18b — scenario-tree, scope-tree, scheduler.
59//! - SRD 22 (`docs/SRD/22_op_sequencing.md`) — op sequencing
60//! and stanza model.
61//! - SRD 30 (`docs/SRD/30_adapter_interface.md`) — adapter
62//! trait surface.
63
64// Polydat node registrations that need nmbrs-runtime's runtime
65// services (component tree + controls + fiber context). Moved out
66// of polydat itself so polydat can publish standalone — see
67// `polydat_nodes/mod.rs` for the rationale.
68pub mod activity;
69pub mod adapter;
70pub(crate) mod adapters;
71pub mod bindings;
72pub mod checkpoint;
73/// SRD-92 / ExecUnification Step 5a — the unified child-stream contract
74/// (`ChildSource` + `Realizability`). Additive; callers land in 5b+.
75pub(crate) mod child_source;
76pub mod concurrent;
77pub mod control_catalog;
78pub(crate) mod daemon_pool;
79pub(crate) mod describe;
80pub(crate) mod error_policy;
81pub mod exec_events;
82pub mod execution_context;
83pub(crate) mod executor;
84pub mod fiber_engine;
85pub(crate) mod fiber_pool;
86pub mod fixture;
87/// Lifecycle event vocabulary: the kind-tag [`lifecycle::EventType`]
88/// and its [`lifecycle::SubjectKind`], shared by the readout
89/// binder and the checkpoint log.
90pub mod lifecycle;
91pub mod log_sink;
92pub mod observer;
93pub mod op_modifier;
94pub mod opseq;
95/// SRD-86 — the optimizer service boundary: the `Optimizer`/`Objective`
96/// contract + registry the phase-execution driver uses, defined here in the
97/// core with no dependency on any algorithm crate. Public so algorithm crates
98/// (e.g. `nmbrs-optimizers`) can register against it and the CLI can discover.
99pub mod optimize;
100pub mod output_channel;
101pub(crate) mod params;
102/// Phase-end trigger registry — content-agnostic callbacks
103/// that fire after every phase completion or failure. Used by
104/// the `watch=plots` / `watch=report` CLI flags to keep an
105/// external view (plot image, report html) up-to-date as the
106/// run progresses.
107pub mod phase_end_triggers;
108pub(crate) mod phase_filter;
109/// SRD-76 phase outcome disposition (structured
110/// per-phase status + error list).
111pub mod phase_outcome;
112/// SRD-71 P3 phase-scoped CLI parameter overrides
113/// (`<phase-pattern>.<param>=<value>`).
114pub(crate) mod phase_params;
115pub mod polydat_nodes;
116pub(crate) mod profiler;
117pub(crate) mod readout_context;
118pub mod readouts;
119/// SRD-77 refine plan — pre-computed skip set + next-execution
120/// id, derived from a session's prior `phase_outcomes` rows.
121/// The runner builds one when `nmbrs refine` re-attaches to an
122/// existing session; the executor's phase-walk gate checks it
123/// before dispatching each phase's per-cycle work.
124pub mod refine_plan;
125pub(crate) mod relevancy;
126pub mod resource_pool;
127pub mod runner;
128pub mod scene_tree;
129pub(crate) mod scheduler;
130pub mod scope;
131pub(crate) mod scope_elision;
132pub mod scope_kernel;
133pub mod scope_synth;
134pub mod scope_tree;
135pub mod session;
136pub mod session_signals;
137pub(crate) mod stop_conditions;
138pub mod synthesis;
139pub mod sysmon;
140pub mod throttle;
141pub mod timeval;
142pub(crate) mod trace_router;
143pub mod validation;
144pub mod wires;
145pub mod workload_lint;
146pub(crate) mod workload_shell;
147pub(crate) mod wrapper_registrations;
148pub mod wrapper_registry;
149pub mod wrapper_resolver;
150pub mod wrappers;
151/// SRD-100 P2 — the per-phase status builder, re-exported for the display
152/// consumer (nmbrs-tui) that now folds `active_phases` and renders each
153/// phase's status line itself (the module otherwise stays crate-private).
154pub use readout_context::{build_inline_refresh_context, is_internal_counter};
155pub mod report_anchor;
156
157/// A scratch-name suffix unique across parallel tests and processes:
158/// parallel tests can read the same clock tick, so the pid and a
159/// per-process sequence keep their directories apart.
160#[cfg(test)]
161pub(crate) fn scratch_suffix() -> String {
162 use std::sync::atomic::{AtomicU64, Ordering};
163 static SEQ: AtomicU64 = AtomicU64::new(0);
164 let n = std::time::SystemTime::now()
165 .duration_since(std::time::UNIX_EPOCH)
166 .unwrap()
167 .as_nanos();
168 let seq = SEQ.fetch_add(1, Ordering::Relaxed);
169 format!("{}-{n:x}-{seq}", std::process::id())
170}