lean_ctx/core/
heatmap.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3use std::path::PathBuf;
4use std::sync::atomic::{AtomicUsize, Ordering};
5use std::sync::Mutex;
6
7const HEATMAP_FLUSH_EVERY: usize = 25;
8const HEATMAP_MAX_ENTRIES: usize = 10_000;
9
10static HEATMAP_BUFFER: Mutex<Option<HeatMap>> = Mutex::new(None);
11static HEATMAP_CALLS: AtomicUsize = AtomicUsize::new(0);
12
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct HeatEntry {
15    pub path: String,
16    pub access_count: u32,
17    pub last_access: String,
18    pub total_tokens_saved: u64,
19    pub total_original_tokens: u64,
20    pub avg_compression_ratio: f32,
21    /// Per-agent access counts — the stigmergic pheromone field.  When multiple
22    /// agents access the same file, downstream consumers can identify shared
23    /// context (co-access patterns) and compute credit for useful preloads.
24    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
25    pub agent_accesses: HashMap<String, u32>,
26}
27
28#[derive(Debug, Clone, Serialize, Deserialize, Default)]
29pub struct HeatMap {
30    pub entries: HashMap<String, HeatEntry>,
31    #[serde(skip)]
32    dirty: bool,
33}
34
35impl HeatMap {
36    pub fn load() -> Self {
37        let mut guard = HEATMAP_BUFFER
38            .lock()
39            .unwrap_or_else(std::sync::PoisonError::into_inner);
40        if let Some(ref hm) = *guard {
41            return hm.clone();
42        }
43        let hm = load_from_disk();
44        *guard = Some(hm.clone());
45        hm
46    }
47
48    pub fn record_access(&mut self, file_path: &str, original_tokens: usize, saved_tokens: usize) {
49        self.record_access_with_agent(file_path, original_tokens, saved_tokens, None);
50    }
51
52    /// Record a file access with an optional agent identifier (stigmergic trace).
53    pub fn record_access_with_agent(
54        &mut self,
55        file_path: &str,
56        original_tokens: usize,
57        saved_tokens: usize,
58        agent_id: Option<&str>,
59    ) {
60        let now = chrono::Utc::now().to_rfc3339();
61        let entry = self
62            .entries
63            .entry(file_path.to_string())
64            .or_insert_with(|| HeatEntry {
65                path: file_path.to_string(),
66                access_count: 0,
67                last_access: now.clone(),
68                total_tokens_saved: 0,
69                total_original_tokens: 0,
70                avg_compression_ratio: 0.0,
71                agent_accesses: HashMap::new(),
72            });
73        entry.access_count += 1;
74        entry.last_access = now;
75        entry.total_tokens_saved += saved_tokens as u64;
76        entry.total_original_tokens += original_tokens as u64;
77        if entry.total_original_tokens > 0 {
78            entry.avg_compression_ratio = 1.0
79                - (entry.total_original_tokens - entry.total_tokens_saved) as f32
80                    / entry.total_original_tokens as f32;
81        }
82        if let Some(aid) = agent_id {
83            if !aid.is_empty() {
84                *entry.agent_accesses.entry(aid.to_string()).or_insert(0) += 1;
85            }
86        }
87        self.dirty = true;
88    }
89
90    pub fn save(&self) -> std::io::Result<()> {
91        if !self.dirty && !self.entries.is_empty() {
92            return Ok(());
93        }
94        save_to_disk(self)?;
95        let mut guard = HEATMAP_BUFFER
96            .lock()
97            .unwrap_or_else(std::sync::PoisonError::into_inner);
98        *guard = Some(self.clone());
99        Ok(())
100    }
101
102    pub fn top_files(&self, limit: usize) -> Vec<&HeatEntry> {
103        let mut sorted: Vec<&HeatEntry> = self.entries.values().collect();
104        sorted.sort_by_key(|x| std::cmp::Reverse(x.access_count));
105        sorted.truncate(limit);
106        sorted
107    }
108
109    /// Compute stigmergic context credit: which agents' file-access traces
110    /// benefited other agents? An agent A gets credit for a file F when A
111    /// accessed F before (or alongside) agent B, because A's trace effectively
112    /// pointed B to useful context. The credit for each (agent_A, file) pair is
113    /// proportional to how many *other* agents also accessed that file.
114    /// Returns `Vec<(agent_id, total_credit)>` sorted descending.
115    pub fn context_credit(&self) -> Vec<(String, f64)> {
116        let mut credit: HashMap<String, f64> = HashMap::new();
117        for entry in self.entries.values() {
118            let n_agents = entry.agent_accesses.len();
119            if n_agents < 2 {
120                continue;
121            }
122            // Shapley-inspired: each agent that accessed a shared file gets
123            // credit = (n_other_agents) / n_agents. The more agents a file
124            // served, the more each contributor is credited.
125            let share = (n_agents - 1) as f64 / n_agents as f64;
126            for agent in entry.agent_accesses.keys() {
127                *credit.entry(agent.clone()).or_insert(0.0) += share;
128            }
129        }
130        let mut sorted: Vec<(String, f64)> = credit.into_iter().collect();
131        sorted.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
132        sorted
133    }
134
135    pub fn directory_summary(&self) -> Vec<(String, u32, u64)> {
136        let mut dirs: HashMap<String, (u32, u64)> = HashMap::new();
137        for entry in self.entries.values() {
138            let dir = std::path::Path::new(&entry.path)
139                .parent()
140                .map_or_else(|| ".".to_string(), |p| p.to_string_lossy().to_string());
141            let stat = dirs.entry(dir).or_insert((0, 0));
142            stat.0 += entry.access_count;
143            stat.1 += entry.total_tokens_saved;
144        }
145        let mut result: Vec<(String, u32, u64)> = dirs
146            .into_iter()
147            .map(|(dir, (count, saved))| (dir, count, saved))
148            .collect();
149        result.sort_by_key(|x| std::cmp::Reverse(x.1));
150        result
151    }
152
153    pub fn cold_files(&self, all_files: &[String], limit: usize) -> Vec<String> {
154        let hot: std::collections::HashSet<&str> = self
155            .entries
156            .keys()
157            .map(std::string::String::as_str)
158            .collect();
159        let mut cold: Vec<String> = all_files
160            .iter()
161            .filter(|f| !hot.contains(f.as_str()))
162            .cloned()
163            .collect();
164        cold.truncate(limit);
165        cold
166    }
167
168    fn storage_path() -> PathBuf {
169        crate::core::data_dir::lean_ctx_data_dir()
170            .unwrap_or_else(|_| PathBuf::from("."))
171            .join("heatmap.json")
172    }
173}
174
175fn load_from_disk() -> HeatMap {
176    let path = HeatMap::storage_path();
177    match std::fs::read_to_string(&path) {
178        Ok(content) => serde_json::from_str(&content).unwrap_or_default(),
179        Err(_) => HeatMap::default(),
180    }
181}
182
183fn save_to_disk(hm: &HeatMap) -> std::io::Result<()> {
184    let path = HeatMap::storage_path();
185    if let Some(parent) = path.parent() {
186        std::fs::create_dir_all(parent)?;
187    }
188    let json = serde_json::to_string_pretty(hm)?;
189    let tmp = path.with_extension("json.tmp");
190    std::fs::write(&tmp, &json)?;
191    std::fs::rename(&tmp, &path)
192}
193
194pub fn record_file_access(file_path: &str, original_tokens: usize, saved_tokens: usize) {
195    // Attribute every read to the current agent identity so the per-agent
196    // pheromone field (stigmergic trace) is populated in production, not just
197    // when callers explicitly pass an id.
198    let agent = crate::core::agent_identity::current_agent_id();
199    record_file_access_with_agent(file_path, original_tokens, saved_tokens, Some(agent));
200}
201
202/// Like [`record_file_access`] but attaches an agent identifier so the heatmap
203/// builds a per-agent pheromone field (stigmergic trace for multi-agent routing).
204pub fn record_file_access_with_agent(
205    file_path: &str,
206    original_tokens: usize,
207    saved_tokens: usize,
208    agent_id: Option<&str>,
209) {
210    // Universal per-read chokepoint (CLI via tool_lifecycle, MCP via ctx_read/ctx_multi_read):
211    // also append one auditable savings event. Best-effort; never blocks/breaks the read.
212    crate::core::savings_ledger::record_read_event(original_tokens, saved_tokens);
213
214    let file_path = std::fs::canonicalize(file_path).map_or_else(
215        |_| file_path.to_string(),
216        |p| p.to_string_lossy().into_owned(),
217    );
218    let file_path = file_path.as_str();
219
220    let mut guard = HEATMAP_BUFFER
221        .lock()
222        .unwrap_or_else(std::sync::PoisonError::into_inner);
223    let hm = guard.get_or_insert_with(load_from_disk);
224    hm.record_access_with_agent(file_path, original_tokens, saved_tokens, agent_id);
225
226    // Enforce bounded retention.
227    if hm.entries.len() > HEATMAP_MAX_ENTRIES {
228        let mut items: Vec<(String, u32)> = hm
229            .entries
230            .values()
231            .map(|e| (e.path.clone(), e.access_count))
232            .collect();
233        items.sort_by_key(|x| x.1);
234        let drop_n = hm.entries.len().saturating_sub(HEATMAP_MAX_ENTRIES);
235        for (path, _) in items.into_iter().take(drop_n) {
236            hm.entries.remove(&path);
237        }
238    }
239
240    let n = HEATMAP_CALLS.fetch_add(1, Ordering::Relaxed) + 1;
241    if n.is_multiple_of(HEATMAP_FLUSH_EVERY) && save_to_disk(hm).is_ok() {
242        hm.dirty = false;
243    }
244}
245
246pub fn flush() {
247    let guard = HEATMAP_BUFFER
248        .lock()
249        .unwrap_or_else(std::sync::PoisonError::into_inner);
250    if let Some(ref hm) = *guard {
251        if hm.dirty {
252            let _ = save_to_disk(hm);
253        }
254    }
255}
256
257pub fn reset() {
258    let mut guard = HEATMAP_BUFFER
259        .lock()
260        .unwrap_or_else(std::sync::PoisonError::into_inner);
261    *guard = Some(HeatMap::default());
262    if let Some(hm) = guard.as_ref() {
263        let _ = save_to_disk(hm);
264    }
265}
266
267pub fn format_heatmap_status(heatmap: &HeatMap, limit: usize) -> String {
268    let top = heatmap.top_files(limit);
269    if top.is_empty() {
270        return "No file access data recorded yet.".to_string();
271    }
272    let mut lines = vec![format!(
273        "File Access Heat Map ({} tracked files):",
274        heatmap.entries.len()
275    )];
276    lines.push(String::new());
277    for (i, entry) in top.iter().enumerate() {
278        let short = short_path(&entry.path);
279        let heat = heat_indicator(entry.access_count);
280        lines.push(format!(
281            "  {heat} #{} {} — {} accesses, {:.0}% compression, {} tok saved",
282            i + 1,
283            short,
284            entry.access_count,
285            entry.avg_compression_ratio * 100.0,
286            entry.total_tokens_saved
287        ));
288    }
289    lines.join("\n")
290}
291
292pub fn format_directory_summary(heatmap: &HeatMap) -> String {
293    let dirs = heatmap.directory_summary();
294    if dirs.is_empty() {
295        return "No directory data.".to_string();
296    }
297    let mut lines = vec!["Directory Heat Map:".to_string(), String::new()];
298    for (dir, count, saved) in dirs.iter().take(15) {
299        let heat = heat_indicator(*count);
300        lines.push(format!(
301            "  {heat} {dir}/ — {count} accesses, {saved} tok saved"
302        ));
303    }
304    lines.join("\n")
305}
306
307fn heat_indicator(count: u32) -> &'static str {
308    match count {
309        0 => "  ",
310        1..=3 => "▁▁",
311        4..=8 => "▃▃",
312        9..=15 => "▅▅",
313        16..=30 => "▇▇",
314        _ => "██",
315    }
316}
317
318fn short_path(path: &str) -> &str {
319    let parts: Vec<&str> = path.rsplitn(3, '/').collect();
320    if parts.len() >= 2 {
321        let start = path.len() - parts[0].len() - parts[1].len() - 1;
322        &path[start..]
323    } else {
324        path
325    }
326}
327
328#[cfg(test)]
329mod tests {
330    use super::*;
331
332    #[test]
333    fn record_and_query() {
334        let mut hm = HeatMap::default();
335        hm.record_access("src/main.rs", 100, 80);
336        hm.record_access("src/main.rs", 100, 90);
337        hm.record_access("src/lib.rs", 200, 50);
338
339        assert_eq!(hm.entries.len(), 2);
340        assert_eq!(hm.entries["src/main.rs"].access_count, 2);
341        assert_eq!(hm.entries["src/lib.rs"].total_tokens_saved, 50);
342    }
343
344    #[test]
345    fn top_files_sorted() {
346        let mut hm = HeatMap::default();
347        hm.record_access("a.rs", 100, 50);
348        hm.record_access("b.rs", 100, 50);
349        hm.record_access("b.rs", 100, 50);
350        hm.record_access("c.rs", 100, 50);
351        hm.record_access("c.rs", 100, 50);
352        hm.record_access("c.rs", 100, 50);
353
354        let top = hm.top_files(2);
355        assert_eq!(top.len(), 2);
356        assert_eq!(top[0].path, "c.rs");
357        assert_eq!(top[1].path, "b.rs");
358    }
359
360    #[test]
361    fn directory_summary_works() {
362        let mut hm = HeatMap::default();
363        hm.record_access("src/a.rs", 100, 50);
364        hm.record_access("src/b.rs", 100, 50);
365        hm.record_access("tests/t.rs", 200, 100);
366
367        let dirs = hm.directory_summary();
368        assert!(dirs.len() >= 2);
369    }
370
371    #[test]
372    fn cold_files_detection() {
373        let mut hm = HeatMap::default();
374        hm.record_access("src/a.rs", 100, 50);
375
376        let all = vec![
377            "src/a.rs".to_string(),
378            "src/b.rs".to_string(),
379            "src/c.rs".to_string(),
380        ];
381        let cold = hm.cold_files(&all, 10);
382        assert_eq!(cold.len(), 2);
383        assert!(cold.contains(&"src/b.rs".to_string()));
384    }
385
386    #[test]
387    fn heat_indicators() {
388        assert_eq!(heat_indicator(0), "  ");
389        assert_eq!(heat_indicator(1), "▁▁");
390        assert_eq!(heat_indicator(10), "▅▅");
391        assert_eq!(heat_indicator(50), "██");
392    }
393
394    #[test]
395    fn compression_ratio() {
396        let mut hm = HeatMap::default();
397        hm.record_access("a.rs", 1000, 800);
398        let entry = &hm.entries["a.rs"];
399        assert!((entry.avg_compression_ratio - 0.8).abs() < 0.01);
400    }
401
402    #[test]
403    fn agent_scoped_access_and_context_credit() {
404        let mut hm = HeatMap::default();
405        hm.record_access_with_agent("shared.rs", 100, 50, Some("agent-a"));
406        hm.record_access_with_agent("shared.rs", 100, 60, Some("agent-b"));
407        hm.record_access_with_agent("only-a.rs", 100, 70, Some("agent-a"));
408
409        let entry = &hm.entries["shared.rs"];
410        assert_eq!(entry.agent_accesses.len(), 2);
411        assert_eq!(entry.agent_accesses["agent-a"], 1);
412        assert_eq!(entry.agent_accesses["agent-b"], 1);
413
414        let credit = hm.context_credit();
415        assert!(!credit.is_empty());
416        // Both agents get credit for the shared file; only-a.rs contributes
417        // no credit (single-agent access).
418        let a_credit = credit.iter().find(|(id, _)| id == "agent-a").unwrap().1;
419        let b_credit = credit.iter().find(|(id, _)| id == "agent-b").unwrap().1;
420        assert!(a_credit > 0.0);
421        assert!((a_credit - b_credit).abs() < 1e-9);
422    }
423}
lean_ctx/core/heatmap.rs

lean_ctx/core/
heatmap.rs
