use parking_lot::Mutex;
use std::collections::HashMap;
use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::time::Instant;
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub enum FetchKind {
FileContext,
Symbol,
FileContent,
}
#[derive(Clone, Debug, Eq, PartialEq, Hash)]
struct FetchKey {
kind: FetchKind,
path: String,
symbol: String,
params_hash: u64,
}
#[derive(Clone, Debug)]
pub struct SessionFetchRecord {
pub approx_tokens: u32,
pub fetched_at: Instant,
pub retrieve_handle: String,
}
#[derive(Clone, Debug)]
pub struct SessionCacheHitMeta {
pub kind: &'static str,
pub path: String,
pub name: String,
pub prior_tokens: u32,
pub session_age_secs: u64,
pub retrieve_handle: String,
}
pub struct SessionContext {
inner: Mutex<SessionInner>,
}
struct SessionInner {
fetched_symbols: HashMap<(String, String), u32>,
listed_symbols: HashMap<(String, String), u32>,
fetched_files: HashMap<String, u32>,
listed_files: HashMap<String, u32>,
summary_outputs: HashMap<String, u32>,
detailed_fetches: HashMap<FetchKey, SessionFetchRecord>,
cache_hit_count: u32,
total_tokens: u64,
started_at: Instant,
}
pub struct SessionSnapshot {
pub fetched_symbols: Vec<(String, String, u32)>, pub listed_symbols: Vec<(String, String, u32)>, pub fetched_files: Vec<(String, u32)>, pub listed_files: Vec<(String, u32)>, pub summary_outputs: Vec<(String, u32)>, pub cache_hit_count: u32,
pub total_tokens: u64,
pub duration_secs: u64,
}
impl Default for SessionContext {
fn default() -> Self {
Self::new()
}
}
impl SessionContext {
pub fn new() -> Self {
Self {
inner: Mutex::new(SessionInner {
fetched_symbols: HashMap::new(),
listed_symbols: HashMap::new(),
fetched_files: HashMap::new(),
listed_files: HashMap::new(),
summary_outputs: HashMap::new(),
detailed_fetches: HashMap::new(),
cache_hit_count: 0,
total_tokens: 0,
started_at: Instant::now(),
}),
}
}
pub fn reset(&self) {
let mut inner = self.inner.lock();
*inner = SessionInner {
fetched_symbols: HashMap::new(),
listed_symbols: HashMap::new(),
fetched_files: HashMap::new(),
listed_files: HashMap::new(),
summary_outputs: HashMap::new(),
detailed_fetches: HashMap::new(),
cache_hit_count: 0,
total_tokens: 0,
started_at: Instant::now(),
};
}
pub fn record_symbol(&self, path: &str, name: &str, tokens: u32) {
let mut inner = self.inner.lock();
let key = (path.to_string(), name.to_string());
inner.listed_symbols.remove(&key);
inner.fetched_symbols.insert(key, tokens);
inner.total_tokens += tokens as u64;
}
pub fn record_listed_symbol(&self, path: &str, name: &str) {
let mut inner = self.inner.lock();
let key = (path.to_string(), name.to_string());
if inner.fetched_symbols.contains_key(&key) {
return;
}
inner.listed_symbols.entry(key).or_insert(0);
}
pub fn record_file(&self, path: &str, tokens: u32) {
let mut inner = self.inner.lock();
inner.listed_files.remove(path);
inner.fetched_files.insert(path.to_string(), tokens);
inner.total_tokens += tokens as u64;
}
pub fn record_listed_file(&self, path: &str, tokens: u32) {
let mut inner = self.inner.lock();
if inner.fetched_files.contains_key(path) {
return;
}
inner.listed_files.insert(path.to_string(), tokens);
inner.total_tokens += tokens as u64;
}
pub fn record_cache_hit(&self) {
let mut inner = self.inner.lock();
inner.cache_hit_count = inner.cache_hit_count.saturating_add(1);
}
pub fn record_summary_output(&self, label: &str, tokens: u32) {
let mut inner = self.inner.lock();
*inner.summary_outputs.entry(label.to_string()).or_insert(0) += tokens;
inner.total_tokens += tokens as u64;
}
pub fn has_symbol(&self, path: &str, name: &str) -> bool {
let inner = self.inner.lock();
inner
.fetched_symbols
.contains_key(&(path.to_string(), name.to_string()))
}
pub fn has_file(&self, path: &str) -> bool {
let inner = self.inner.lock();
inner.fetched_files.contains_key(path)
}
pub fn symbol_prior_tokens(&self, path: &str, name: &str) -> Option<u32> {
let inner = self.inner.lock();
inner
.fetched_symbols
.get(&(path.to_string(), name.to_string()))
.copied()
}
pub fn file_prior_tokens(&self, path: &str) -> Option<u32> {
let inner = self.inner.lock();
inner.fetched_files.get(path).copied()
}
pub fn session_age_secs(&self) -> u64 {
self.inner.lock().started_at.elapsed().as_secs()
}
fn try_cache_hit(
&self,
kind: FetchKind,
path: &str,
symbol: &str,
params_hash: u64,
force_refresh: bool,
) -> Option<SessionCacheHitMeta> {
if force_refresh {
return None;
}
let inner = self.inner.lock();
let key = FetchKey {
kind,
path: path.to_string(),
symbol: symbol.to_string(),
params_hash,
};
let record = inner.detailed_fetches.get(&key)?;
let (kind_label, name) = match kind {
FetchKind::Symbol => ("symbol", symbol.to_string()),
FetchKind::FileContext | FetchKind::FileContent => ("file", String::new()),
};
Some(SessionCacheHitMeta {
kind: kind_label,
path: path.to_string(),
name,
prior_tokens: record.approx_tokens,
session_age_secs: inner.started_at.elapsed().as_secs(),
retrieve_handle: record.retrieve_handle.clone(),
})
}
pub(crate) fn record_detailed_fetch(
&self,
kind: FetchKind,
path: &str,
symbol: &str,
params_hash: u64,
tokens: u32,
retrieve_handle: &str,
) {
let mut inner = self.inner.lock();
let key = FetchKey {
kind,
path: path.to_string(),
symbol: symbol.to_string(),
params_hash,
};
inner.detailed_fetches.insert(
key,
SessionFetchRecord {
approx_tokens: tokens,
fetched_at: Instant::now(),
retrieve_handle: retrieve_handle.to_string(),
},
);
}
pub fn prior_fetch_for_dedup(
&self,
kind: FetchKind,
path: &str,
symbol: &str,
params_hash: u64,
) -> Option<SessionFetchRecord> {
let inner = self.inner.lock();
inner
.detailed_fetches
.get(&FetchKey {
kind,
path: path.to_string(),
symbol: symbol.to_string(),
params_hash,
})
.cloned()
}
pub fn try_symbol_cache_hit(
&self,
path: &str,
name: &str,
params_hash: u64,
force_refresh: bool,
) -> Option<SessionCacheHitMeta> {
self.try_cache_hit(FetchKind::Symbol, path, name, params_hash, force_refresh)
}
pub fn try_file_context_cache_hit(
&self,
path: &str,
params_hash: u64,
force_refresh: bool,
) -> Option<SessionCacheHitMeta> {
self.try_cache_hit(FetchKind::FileContext, path, "", params_hash, force_refresh)
}
pub fn try_file_content_cache_hit(
&self,
path: &str,
params_hash: u64,
force_refresh: bool,
) -> Option<SessionCacheHitMeta> {
self.try_cache_hit(FetchKind::FileContent, path, "", params_hash, force_refresh)
}
pub fn record_symbol_fetch(
&self,
path: &str,
name: &str,
params_hash: u64,
tokens: u32,
retrieve_handle: &str,
) {
self.record_symbol(path, name, tokens);
self.record_detailed_fetch(
FetchKind::Symbol,
path,
name,
params_hash,
tokens,
retrieve_handle,
);
}
pub fn record_file_context_fetch(
&self,
path: &str,
params_hash: u64,
tokens: u32,
retrieve_handle: &str,
) {
self.record_detailed_fetch(
FetchKind::FileContext,
path,
"",
params_hash,
tokens,
retrieve_handle,
);
}
pub fn record_file_content_fetch(
&self,
path: &str,
params_hash: u64,
tokens: u32,
retrieve_handle: &str,
) {
self.record_file(path, tokens);
self.record_detailed_fetch(
FetchKind::FileContent,
path,
"",
params_hash,
tokens,
retrieve_handle,
);
}
#[allow(clippy::unused_self)]
pub fn try_cache_hit_from_stel_step(
&self,
_tool: &str,
_args: &serde_json::Value,
) -> Option<SessionCacheHitMeta> {
None
}
pub fn snapshot(&self) -> SessionSnapshot {
let inner = self.inner.lock();
let mut fetched_symbols: Vec<(String, String, u32)> = inner
.fetched_symbols
.iter()
.map(|((p, n), t)| (p.clone(), n.clone(), *t))
.collect();
fetched_symbols.sort_by(compare_fetched_symbols);
let mut listed_symbols: Vec<(String, String, u32)> = inner
.listed_symbols
.iter()
.map(|((p, n), t)| (p.clone(), n.clone(), *t))
.collect();
listed_symbols.sort_by(|a, b| a.1.cmp(&b.1).then(a.0.cmp(&b.0)));
let mut fetched_files: Vec<(String, u32)> = inner
.fetched_files
.iter()
.map(|(p, t)| (p.clone(), *t))
.collect();
fetched_files.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
let mut listed_files: Vec<(String, u32)> = inner
.listed_files
.iter()
.map(|(p, t)| (p.clone(), *t))
.collect();
listed_files.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
let mut summary_outputs: Vec<(String, u32)> = inner
.summary_outputs
.iter()
.map(|(label, tokens)| (label.clone(), *tokens))
.collect();
summary_outputs.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
SessionSnapshot {
fetched_symbols,
listed_symbols,
fetched_files,
listed_files,
summary_outputs,
cache_hit_count: inner.cache_hit_count,
total_tokens: inner.total_tokens,
duration_secs: inner.started_at.elapsed().as_secs(),
}
}
}
fn compare_fetched_symbols(
a: &(String, String, u32),
b: &(String, String, u32),
) -> std::cmp::Ordering {
b.2.cmp(&a.2).then(a.1.cmp(&b.1)).then(a.0.cmp(&b.0))
}
pub fn hash_value(value: &serde_json::Value) -> u64 {
let mut hasher = DefaultHasher::new();
value.to_string().hash(&mut hasher);
hasher.finish()
}
pub fn hash_file_context_params(
max_tokens: Option<u64>,
sections: Option<&[String]>,
project: &str,
source: Option<&str>,
publication_generation: u64,
content_generation: u64,
) -> u64 {
hash_value(&serde_json::json!({
"max_tokens": max_tokens,
"sections": sections,
"project": project,
"source": source,
"publication_generation": publication_generation,
"content_generation": content_generation,
}))
}
pub fn hash_file_context_params_json(args: &serde_json::Value) -> u64 {
hash_value(&serde_json::json!({
"max_tokens": args.get("max_tokens"),
"sections": args.get("sections"),
}))
}
pub fn hash_symbol_params_json(args: &serde_json::Value) -> u64 {
hash_value(&serde_json::json!({
"kind": args.get("kind"),
"symbol_line": args.get("symbol_line"),
"max_tokens": args.get("max_tokens"),
}))
}
pub fn hash_symbol_params(
kind: Option<&str>,
symbol_line: Option<u32>,
max_tokens: Option<u64>,
project_generation: u64,
source_id: &str,
publication_generation: u64,
content_generation: u64,
) -> u64 {
hash_value(&serde_json::json!({
"kind": kind,
"symbol_line": symbol_line,
"max_tokens": max_tokens,
"project_generation": project_generation,
"source_id": source_id,
"publication_generation": publication_generation,
"content_generation": content_generation,
}))
}
pub fn hash_file_content_params_json(args: &serde_json::Value) -> u64 {
hash_value(args)
}
pub fn format_context_inventory(
snap: &SessionSnapshot,
ccr: crate::index_lifecycle::guidance::compression::CcrEconomics,
) -> String {
let minutes = snap.duration_secs / 60;
let total_items = snap.fetched_symbols.len()
+ snap.fetched_files.len()
+ snap.listed_symbols.len()
+ snap.listed_files.len()
+ snap.summary_outputs.len();
let mut lines = vec![format!(
"Session Context ({} minutes, {} tracked entries, ~{} tokens total)",
minutes, total_items, snap.total_tokens
)];
if !snap.fetched_symbols.is_empty() {
lines.push(String::new());
lines.push(format!(
"Symbol bodies fetched ({}):",
snap.fetched_symbols.len()
));
for (path, name, tokens) in snap.fetched_symbols.iter().take(15) {
lines.push(format!(" {name} ({path}) — ~{tokens} tokens"));
}
if snap.fetched_symbols.len() > 15 {
lines.push(format!(
" ... and {} more",
snap.fetched_symbols.len() - 15
));
}
}
if !snap.fetched_files.is_empty() {
lines.push(String::new());
lines.push(format!(
"File bodies fetched ({}):",
snap.fetched_files.len()
));
for (path, tokens) in snap.fetched_files.iter().take(10) {
lines.push(format!(" {path} — ~{tokens} tokens"));
}
if snap.fetched_files.len() > 10 {
lines.push(format!(" ... and {} more", snap.fetched_files.len() - 10));
}
}
if !snap.listed_symbols.is_empty() {
lines.push(String::new());
lines.push(format!(
"Symbols listed only in search/summary results ({}):",
snap.listed_symbols.len()
));
for (path, name, _) in snap.listed_symbols.iter().take(15) {
if path.is_empty() {
lines.push(format!(" {name}"));
} else {
lines.push(format!(" {name} ({path})"));
}
}
if snap.listed_symbols.len() > 15 {
lines.push(format!(" ... and {} more", snap.listed_symbols.len() - 15));
}
}
if !snap.listed_files.is_empty() {
lines.push(String::new());
lines.push(format!(
"Files listed only in search/summary results ({}):",
snap.listed_files.len()
));
for (path, tokens) in snap.listed_files.iter().take(10) {
lines.push(format!(" {path} — ~{tokens} tokens of overview"));
}
if snap.listed_files.len() > 10 {
lines.push(format!(" ... and {} more", snap.listed_files.len() - 10));
}
}
if !snap.summary_outputs.is_empty() {
lines.push(String::new());
lines.push(format!(
"Summary/search outputs without fetched bodies ({}):",
snap.summary_outputs.len()
));
for (label, tokens) in snap.summary_outputs.iter().take(10) {
lines.push(format!(" {label} — ~{tokens} tokens"));
}
if snap.summary_outputs.len() > 10 {
lines.push(format!(
" ... and {} more",
snap.summary_outputs.len() - 10
));
}
}
if snap.cache_hit_count > 0 || ccr.offloads > 0 || ccr.retrieves > 0 {
lines.push(String::new());
lines.push("Compression economics (heuristic estimates, 011):".to_string());
lines.push(format!(" cache_hits: {}", snap.cache_hit_count));
lines.push(format!(" ccr_offloads: {}", ccr.offloads));
lines.push(format!(" ccr_bytes_stored: {}", ccr.bytes_stored));
lines.push(format!(" ccr_bytes_retrieved: {}", ccr.bytes_retrieved));
}
lines.join("\n")
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn duplicate_fetched_symbol_ties_use_path_order() {
let earlier = ("a.rs".to_owned(), "same".to_owned(), 10);
let later = ("z.rs".to_owned(), "same".to_owned(), 10);
assert_eq!(
compare_fetched_symbols(&earlier, &later),
std::cmp::Ordering::Less
);
}
#[test]
fn test_record_and_query() {
let ctx = SessionContext::new();
assert!(!ctx.has_symbol("src/lib.rs", "main"));
ctx.record_listed_symbol("src/lib.rs", "main");
assert!(
!ctx.has_symbol("src/lib.rs", "main"),
"list-only symbols should not count as fetched"
);
ctx.record_symbol("src/lib.rs", "main", 100);
assert!(ctx.has_symbol("src/lib.rs", "main"));
assert!(!ctx.has_file("src/lib.rs"));
ctx.record_listed_file("src/lib.rs", 250);
assert!(
!ctx.has_file("src/lib.rs"),
"overview-only files should not count as fetched"
);
ctx.record_file("src/lib.rs", 500);
assert!(ctx.has_file("src/lib.rs"));
}
#[test]
fn test_snapshot() {
let ctx = SessionContext::new();
ctx.record_listed_symbol("z.rs", "listed_fn");
ctx.record_symbol("a.rs", "foo", 100);
ctx.record_symbol("b.rs", "bar", 200);
ctx.record_listed_file("outline.rs", 40);
ctx.record_file("c.rs", 300);
ctx.record_summary_output("explore", 60);
let snap = ctx.snapshot();
assert_eq!(snap.fetched_symbols.len(), 2);
assert_eq!(snap.listed_symbols.len(), 1);
assert_eq!(snap.fetched_files.len(), 1);
assert_eq!(snap.listed_files.len(), 1);
assert_eq!(snap.summary_outputs.len(), 1);
assert_eq!(snap.total_tokens, 700);
}
#[test]
fn test_reset_clears_accounting() {
let ctx = SessionContext::new();
ctx.record_symbol("old_root/a.rs", "foo", 100);
ctx.record_file("old_root/b.rs", 200);
assert!(ctx.has_symbol("old_root/a.rs", "foo"));
ctx.reset();
assert!(
!ctx.has_symbol("old_root/a.rs", "foo"),
"reset must drop symbols recorded under the previous root"
);
assert!(!ctx.has_file("old_root/b.rs"));
let snap = ctx.snapshot();
assert_eq!(snap.fetched_symbols.len(), 0);
assert_eq!(snap.fetched_files.len(), 0);
assert_eq!(snap.total_tokens, 0);
}
#[test]
fn test_format_inventory() {
let ctx = SessionContext::new();
ctx.record_listed_symbol("src/search.rs", "SearchHit");
ctx.record_symbol("src/lib.rs", "LiveIndex", 500);
ctx.record_listed_file("src/overview.rs", 120);
ctx.record_file("src/main.rs", 1000);
ctx.record_summary_output("explore", 75);
let snap = ctx.snapshot();
let output = format_context_inventory(
&snap,
crate::index_lifecycle::guidance::compression::CcrEconomics::default(),
);
assert!(output.contains("LiveIndex"));
assert!(output.contains("SearchHit"));
assert!(output.contains("src/overview.rs"));
assert!(output.contains("src/main.rs"));
assert!(output.contains("explore"));
assert!(output.contains("1695"));
}
#[test]
fn hash_symbol_params_binds_generation_identity() {
let base = hash_symbol_params(None, None, None, 1, "src-a", 2, 3);
assert_ne!(
base,
hash_symbol_params(None, None, None, 1, "src-a", 2, 4),
"content_generation must be part of the cache key"
);
assert_ne!(
base,
hash_symbol_params(None, None, None, 1, "src-b", 2, 3),
"source_id must be part of the cache key"
);
assert_ne!(
base,
hash_symbol_params(None, None, None, 2, "src-a", 2, 3),
"project_generation must be part of the cache key"
);
assert_ne!(
base,
hash_symbol_params(None, None, None, 1, "src-a", 3, 3),
"publication_generation must be part of the cache key"
);
}
#[test]
fn generation_change_in_hash_is_a_cache_miss() {
let ctx = SessionContext::new();
let gen1 = hash_symbol_params(None, None, None, 1, "src-a", 1, 1);
let gen2 = hash_symbol_params(None, None, None, 1, "src-a", 1, 2);
ctx.record_symbol_fetch("src/lib.rs", "foo", gen1, 200, "cafe01234567");
assert!(
ctx.try_symbol_cache_hit("src/lib.rs", "foo", gen1, false)
.is_some()
);
assert!(
ctx.try_symbol_cache_hit("src/lib.rs", "foo", gen2, false)
.is_none(),
"a later generation identity must not reuse the prior fetch"
);
}
#[test]
fn stel_admission_does_not_cache_hit_generation_blind_reads() {
let ctx = SessionContext::new();
ctx.record_symbol_fetch(
"src/lib.rs",
"foo",
hash_symbol_params(None, None, None, 0, "unavailable", 0, 0),
200,
"cafe01234567",
);
ctx.record_file_context_fetch("src/lib.rs", 1, 100, "cafe01234567");
let symbol_args = serde_json::json!({ "path": "src/lib.rs", "name": "foo" });
let file_args = serde_json::json!({ "path": "src/lib.rs" });
assert!(
ctx.try_cache_hit_from_stel_step("get_symbol", &symbol_args)
.is_none()
);
assert!(
ctx.try_cache_hit_from_stel_step("get_file_context", &file_args)
.is_none()
);
assert!(
ctx.try_cache_hit_from_stel_step("get_file_content", &file_args)
.is_none()
);
}
#[test]
fn cache_hit_meta_carries_retrieve_handle() {
let ctx = SessionContext::new();
ctx.record_symbol_fetch("src/lib.rs", "foo", 7, 200, "deadbeefcafe");
let meta = ctx
.try_symbol_cache_hit("src/lib.rs", "foo", 7, false)
.expect("recorded fetch");
assert_eq!(meta.retrieve_handle, "deadbeefcafe");
assert!(
ctx.try_symbol_cache_hit("src/lib.rs", "foo", 7, true)
.is_none(),
"force_refresh must bypass cache_hit"
);
}
}