coding_agent_search/search/
runtime_optimizations.rs

1//! Runtime-toggleable performance optimizations.
2//!
3//! Per `coding_agent_session_search-yvv7r` (rollback env vars for ifr7/lxn5)
4//! and `coding_agent_session_search-waijq` (CASS_F16_PRECONVERT for mng4).
5//!
6//! ## Design contract
7//!
8//! Each runtime optimization is gated by a `CASS_<FEATURE>` env var read once
9//! at startup and cached in a `OnceLock<bool>`. Operators flipping a toggle
10//! must restart cass; per-query toggling is intentionally not supported (the
11//! contract is "operator flips, restarts, measures").
12//!
13//! ## Truthful values
14//!
15//! Bool semantics (case-insensitive):
16//! - Unset, `1`, `true`, `on`, `yes` → optimization ENABLED (default).
17//! - `0`, `false`, `off`, `no` → optimization DISABLED (rollback path).
18//! - Any other value → log a `tracing::warn!` and treat as ENABLED.
19//!
20//! ## Health surface
21//!
22//! `cass health --json` exposes `runtime_optimizations: { simd_dot, parallel_search,
23//! preconvert_f16, config_source }` so operators and monitoring can confirm the
24//! flip took effect.
25//!
26//! ## Why not std::env::var
27//!
28//! Per AGENTS.md, ALL configuration must load via `dotenvy::var()` — it
29//! respects the project's `.env` file. `std::env::var` would skip `.env`
30//! entries and produce inconsistent behavior between dev and production.
31
32use std::sync::OnceLock;
33
34use serde::Serialize;
35
36/// Cached truth values for the three optimization toggles.
37static SIMD_DOT: OnceLock<bool> = OnceLock::new();
38static PARALLEL_SEARCH: OnceLock<bool> = OnceLock::new();
39static PRECONVERT_F16: OnceLock<bool> = OnceLock::new();
40
41/// Tracks whether the cached value came from an env var (`env`) or the
42/// default (`default`). Useful for the health surface.
43static CONFIG_SOURCE: OnceLock<ConfigSource> = OnceLock::new();
44
45/// Source of the runtime-optimization configuration as surfaced in
46/// `cass health --json` under `runtime_optimizations.config_source`.
47#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
48#[serde(rename_all = "lowercase")]
49pub enum ConfigSource {
50    /// At least one toggle was driven by an env var.
51    Env,
52    /// All toggles are at their defaults (no env vars set).
53    Default,
54}
55
56impl ConfigSource {
57    pub fn as_str(self) -> &'static str {
58        match self {
59            ConfigSource::Env => "env",
60            ConfigSource::Default => "default",
61        }
62    }
63}
64
65/// Read a CASS_* env var as a bool. Unrecognized values log a warning and
66/// default to `default_value`. The env var name is included in every log
67/// event so operators can grep for it.
68fn read_bool_env(name: &str, default_value: bool) -> (bool, bool) {
69    let raw = match dotenvy::var(name) {
70        Ok(v) => v,
71        Err(_) => return (default_value, false),
72    };
73    let normalized = raw.trim().to_ascii_lowercase();
74    let parsed = match normalized.as_str() {
75        "" => Some(default_value),
76        "1" | "true" | "on" | "yes" => Some(true),
77        "0" | "false" | "off" | "no" => Some(false),
78        _ => None,
79    };
80    match parsed {
81        Some(b) => {
82            tracing::debug!(
83                target: "cass::runtime_optimizations",
84                env_var = name,
85                raw = raw.as_str(),
86                value = b,
87                "runtime optimization configured from env var"
88            );
89            (b, true)
90        }
91        None => {
92            tracing::warn!(
93                target: "cass::runtime_optimizations",
94                env_var = name,
95                raw = raw.as_str(),
96                "unrecognized CASS_* env var value; treating as enabled. Recognized values: 1/true/on/yes (enable) or 0/false/off/no (disable)."
97            );
98            (default_value, true)
99        }
100    }
101}
102
103/// Force-resolve all toggles. Called once at startup before any query path
104/// reads them. Subsequent calls are no-ops thanks to `OnceLock::set`.
105///
106/// Returns the resolved snapshot for telemetry. If toggles were already
107/// resolved (e.g. by an earlier explicit call), the existing snapshot is
108/// returned unchanged.
109pub fn init_from_env() -> RuntimeOptimizationsSnapshot {
110    let (simd, simd_from_env) = read_bool_env("CASS_SIMD_DOT", true);
111    let (par, par_from_env) = read_bool_env("CASS_PARALLEL_SEARCH", true);
112    let (pre, pre_from_env) = read_bool_env("CASS_F16_PRECONVERT", true);
113
114    let _ = SIMD_DOT.set(simd);
115    let _ = PARALLEL_SEARCH.set(par);
116    let _ = PRECONVERT_F16.set(pre);
117
118    let any_from_env = simd_from_env || par_from_env || pre_from_env;
119    let source = if any_from_env {
120        ConfigSource::Env
121    } else {
122        ConfigSource::Default
123    };
124    let _ = CONFIG_SOURCE.set(source);
125
126    let snap = RuntimeOptimizationsSnapshot {
127        simd_dot: *SIMD_DOT.get().unwrap_or(&true),
128        parallel_search: *PARALLEL_SEARCH.get().unwrap_or(&true),
129        preconvert_f16: *PRECONVERT_F16.get().unwrap_or(&true),
130        config_source: *CONFIG_SOURCE.get().unwrap_or(&ConfigSource::Default),
131    };
132    tracing::info!(
133        target: "cass::runtime_optimizations",
134        simd_dot = snap.simd_dot,
135        parallel_search = snap.parallel_search,
136        preconvert_f16 = snap.preconvert_f16,
137        config_source = snap.config_source.as_str(),
138        "runtime optimizations resolved"
139    );
140    snap
141}
142
143/// Whether SIMD dot product is enabled. Lazily initializes from env on first
144/// read if `init_from_env()` has not been called yet.
145#[must_use]
146pub fn simd_dot_enabled() -> bool {
147    if SIMD_DOT.get().is_none() {
148        init_from_env();
149    }
150    *SIMD_DOT.get().unwrap_or(&true)
151}
152
153/// Whether parallel rayon-driven vector search is enabled.
154#[must_use]
155pub fn parallel_search_enabled() -> bool {
156    if PARALLEL_SEARCH.get().is_none() {
157        init_from_env();
158    }
159    *PARALLEL_SEARCH.get().unwrap_or(&true)
160}
161
162/// Whether f16→f32 preconversion at vector-load time is enabled.
163#[must_use]
164pub fn preconvert_f16_enabled() -> bool {
165    if PRECONVERT_F16.get().is_none() {
166        init_from_env();
167    }
168    *PRECONVERT_F16.get().unwrap_or(&true)
169}
170
171/// Snapshot of the cached toggle values. This is the canonical shape exposed
172/// in `cass health --json` under `runtime_optimizations`.
173#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
174pub struct RuntimeOptimizationsSnapshot {
175    pub simd_dot: bool,
176    pub parallel_search: bool,
177    pub preconvert_f16: bool,
178    pub config_source: ConfigSource,
179}
180
181impl RuntimeOptimizationsSnapshot {
182    /// Build a snapshot from the cached values. Forces lazy init if not yet
183    /// resolved, mirroring `simd_dot_enabled()` / etc.
184    #[must_use]
185    pub fn current() -> Self {
186        // Touch each accessor so init_from_env runs at least once.
187        let simd = simd_dot_enabled();
188        let par = parallel_search_enabled();
189        let pre = preconvert_f16_enabled();
190        let src = *CONFIG_SOURCE.get().unwrap_or(&ConfigSource::Default);
191        RuntimeOptimizationsSnapshot {
192            simd_dot: simd,
193            parallel_search: par,
194            preconvert_f16: pre,
195            config_source: src,
196        }
197    }
198
199    /// JSON shape used by the health surface.
200    #[must_use]
201    pub fn to_json_value(&self) -> serde_json::Value {
202        serde_json::json!({
203            "simd_dot": self.simd_dot,
204            "parallel_search": self.parallel_search,
205            "preconvert_f16": self.preconvert_f16,
206            "config_source": self.config_source.as_str(),
207        })
208    }
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214
215    /// Direct test of read_bool_env without OnceLock interference. Each
216    /// scenario uses a unique env-var name so concurrent test runs don't race.
217    #[test]
218    fn read_bool_env_recognizes_truthy_and_falsy_values() {
219        unsafe {
220            std::env::set_var("CASS_TEST_RBE_TRUTHY_1", "1");
221            std::env::set_var("CASS_TEST_RBE_TRUTHY_2", "true");
222            std::env::set_var("CASS_TEST_RBE_TRUTHY_3", "ON");
223            std::env::set_var("CASS_TEST_RBE_TRUTHY_4", "yes");
224            std::env::set_var("CASS_TEST_RBE_FALSY_1", "0");
225            std::env::set_var("CASS_TEST_RBE_FALSY_2", "false");
226            std::env::set_var("CASS_TEST_RBE_FALSY_3", "OFF");
227            std::env::set_var("CASS_TEST_RBE_FALSY_4", "no");
228        }
229        for name in [
230            "CASS_TEST_RBE_TRUTHY_1",
231            "CASS_TEST_RBE_TRUTHY_2",
232            "CASS_TEST_RBE_TRUTHY_3",
233            "CASS_TEST_RBE_TRUTHY_4",
234        ] {
235            let (v, _) = read_bool_env(name, true);
236            assert!(v, "{name} should resolve as true");
237        }
238        for name in [
239            "CASS_TEST_RBE_FALSY_1",
240            "CASS_TEST_RBE_FALSY_2",
241            "CASS_TEST_RBE_FALSY_3",
242            "CASS_TEST_RBE_FALSY_4",
243        ] {
244            let (v, _) = read_bool_env(name, true);
245            assert!(!v, "{name} should resolve as false");
246        }
247    }
248
249    #[test]
250    fn read_bool_env_unset_returns_default_with_not_from_env() {
251        let (v, from_env) = read_bool_env("CASS_TEST_RBE_NEVER_SET_8c14a293", true);
252        assert!(v);
253        assert!(!from_env);
254        let (v, from_env) = read_bool_env("CASS_TEST_RBE_NEVER_SET_8c14a294", false);
255        assert!(!v);
256        assert!(!from_env);
257    }
258
259    #[test]
260    fn read_bool_env_unrecognized_value_falls_back_to_default_with_from_env_true() {
261        unsafe {
262            std::env::set_var("CASS_TEST_RBE_BANANA", "banana");
263        }
264        let (v, from_env) = read_bool_env("CASS_TEST_RBE_BANANA", true);
265        // Default was true; banana is unrecognized → stays true.
266        assert!(v);
267        // Source is still env (the var WAS set, just unparseable).
268        assert!(from_env);
269    }
270
271    #[test]
272    fn snapshot_to_json_has_documented_shape() {
273        let snap = RuntimeOptimizationsSnapshot {
274            simd_dot: true,
275            parallel_search: false,
276            preconvert_f16: true,
277            config_source: ConfigSource::Env,
278        };
279        let v = snap.to_json_value();
280        assert_eq!(v["simd_dot"], true);
281        assert_eq!(v["parallel_search"], false);
282        assert_eq!(v["preconvert_f16"], true);
283        assert_eq!(v["config_source"], "env");
284    }
285
286    #[test]
287    fn config_source_default_when_no_env_set() {
288        let snap = RuntimeOptimizationsSnapshot {
289            simd_dot: true,
290            parallel_search: true,
291            preconvert_f16: true,
292            config_source: ConfigSource::Default,
293        };
294        assert_eq!(snap.to_json_value()["config_source"], "default");
295    }
296}
coding_agent_search/search/runtime_optimizations.rs

coding_agent_search/search/
runtime_optimizations.rs
