lean_ctx/proxy/
cache_safety.rs

1//! Cache-preservation telemetry for the proxy's frozen-region prose rewrites
2//! (#710).
3//!
4//! The proxy only ever rewrites prose inside the cache-safe frozen window
5//! `[cached_prefix_len, boundary)` — never inside the client-cached prefix and
6//! never in the live tail. This module turns that invariant into a *measurable*
7//! production signal: every request that performs a frozen-region prose rewrite
8//! reports whether the rewrite stayed cache-safe, and `/status` surfaces the
9//! resulting ratio (`1.0` = every rewrite was provably cache-safe, the
10//! healthy steady state). A value below `1.0` is a regression signal.
11
12use std::sync::atomic::{AtomicU64, Ordering};
13
14use serde::{Deserialize, Serialize};
15
16/// Total prose segments (text fields) compressed across all requests.
17static PROSE_SEGMENTS: AtomicU64 = AtomicU64::new(0);
18/// Requests that performed at least one frozen-region prose rewrite.
19static PROSE_REQUESTS: AtomicU64 = AtomicU64::new(0);
20/// Of those, the requests whose every rewrite was cache-safe.
21static CACHE_SAFE_REQUESTS: AtomicU64 = AtomicU64::new(0);
22/// Deliberate cold-prefix repacks (#480): requests where the proxy predicted the
23/// client-cached prefix was already cold and rewrote it on purpose. Tracked
24/// separately so an *intentional* prefix rewrite never dilutes the
25/// `cache_safe_ratio`, whose job is to catch *accidental* #448 regressions.
26static COLD_PREFIX_REPACKS: AtomicU64 = AtomicU64::new(0);
27
28/// Record one request's frozen-region prose activity.
29///
30/// `segments` is how many prose fields were compressed this request; `all_safe`
31/// is `true` when *every* rewrite landed strictly inside the cache-safe frozen
32/// window. A no-op request (`segments == 0`) is not counted, so the ratio
33/// reflects only requests that actually mutated prose.
34pub fn record(segments: u64, all_safe: bool) {
35    if segments == 0 {
36        return;
37    }
38    PROSE_SEGMENTS.fetch_add(segments, Ordering::Relaxed);
39    PROSE_REQUESTS.fetch_add(1, Ordering::Relaxed);
40    if all_safe {
41        CACHE_SAFE_REQUESTS.fetch_add(1, Ordering::Relaxed);
42    }
43}
44
45/// Record one deliberate cold-prefix repack (#480). Counted on its own gauge,
46/// never against [`record`]'s cache-safe ratio.
47pub fn record_cold_repack() {
48    COLD_PREFIX_REPACKS.fetch_add(1, Ordering::Relaxed);
49}
50
51/// Cache-preservation ratio: `safe / total`, or `1.0` when nothing has been
52/// rewritten yet (the trivially-safe empty state). Pure, so it is unit-tested
53/// independently of the global counters.
54#[must_use]
55pub fn ratio(safe: u64, total: u64) -> f64 {
56    if total == 0 {
57        return 1.0;
58    }
59    safe as f64 / total as f64
60}
61
62/// Point-in-time view of the cache-safety counters for `/status`.
63#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
64pub struct CacheSafety {
65    /// Prose segments compressed in the frozen region (cumulative).
66    pub prose_segments_compressed: u64,
67    /// Requests that performed at least one frozen-region prose rewrite.
68    pub prose_requests: u64,
69    /// Fraction of those requests whose every rewrite was cache-safe (`1.0` is
70    /// the healthy steady state; the proxy only rewrites inside the cache-safe
71    /// window by construction).
72    pub cache_safe_ratio: f64,
73    /// Deliberate cold-prefix repacks (#480), cumulative. Non-zero only when the
74    /// opt-in mode fired on a predicted-cold session resume — expected, not a
75    /// regression.
76    #[serde(default)]
77    pub cold_prefix_repacks: u64,
78}
79
80#[must_use]
81pub fn snapshot() -> CacheSafety {
82    let prose_requests = PROSE_REQUESTS.load(Ordering::Relaxed);
83    let safe = CACHE_SAFE_REQUESTS.load(Ordering::Relaxed);
84    CacheSafety {
85        prose_segments_compressed: PROSE_SEGMENTS.load(Ordering::Relaxed),
86        prose_requests,
87        cache_safe_ratio: ratio(safe, prose_requests),
88        cold_prefix_repacks: COLD_PREFIX_REPACKS.load(Ordering::Relaxed),
89    }
90}
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95
96    #[test]
97    fn ratio_is_one_when_empty() {
98        assert_eq!(ratio(0, 0), 1.0);
99    }
100
101    #[test]
102    fn ratio_reflects_unsafe_rewrites() {
103        assert_eq!(ratio(3, 3), 1.0);
104        assert_eq!(ratio(2, 4), 0.5);
105        assert_eq!(ratio(0, 2), 0.0);
106    }
107}
lean_ctx/proxy/cache_safety.rs

lean_ctx/proxy/
cache_safety.rs
