use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Mutex;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value as Json};
use crate::facts::Hashes;
pub const FILE: &str = "memfork-sidecar.json";
const VERSION: u32 = 1;
pub const MAX_FACT_RECORDS: usize = 50_000;
pub const MAX_SEEN_RECORDS: usize = 10_000;
pub const MAX_STALE_KEPT: usize = 1000;
pub const MAX_BRIEFINGS_KEPT: usize = 100;
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct Counters {
pub briefings: u64,
pub briefing_bytes: u64,
pub memory_bytes: u64,
pub lessons_recorded: u64,
pub lessons_served: u64,
pub facts_fresh: u64,
pub facts_stale: u64,
pub facts_unverified: u64,
pub claims: u64,
pub claim_conflicts: u64,
pub finds: u64,
pub handoffs_picked_up: u64,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct Briefing {
pub order: u64,
pub seq: u64,
pub branch: String,
pub to: String,
pub bytes: u64,
pub keys: Vec<String>,
pub handoff: Option<String>,
pub since_commits: Option<u64>,
pub omitted: BTreeMap<String, u64>,
pub task: Option<String>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
struct FactRecord {
order: u64,
hashes: Hashes,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
struct SeenRecord {
commit: String,
seq: u64,
order: u64,
}
#[derive(Debug, Default, Serialize, Deserialize)]
#[serde(default)]
struct Data {
version: u32,
stats: BTreeMap<String, BTreeMap<String, Counters>>,
facts: BTreeMap<String, FactRecord>,
next_order: u64,
seen: BTreeMap<String, BTreeMap<String, BTreeMap<String, SeenRecord>>>,
maintenance: BTreeMap<String, Maintenance>,
stale: BTreeMap<String, std::collections::BTreeSet<String>>,
fresh: BTreeMap<String, std::collections::BTreeSet<String>>,
briefings: BTreeMap<String, Vec<Briefing>>,
autopilot: BTreeMap<String, AutopilotSide>,
reflog_cursors: BTreeMap<String, u64>,
followed: BTreeMap<String, std::collections::BTreeSet<String>>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
struct AutopilotSide {
journal: Vec<crate::autopilot::JournalEntry>,
orphans: Vec<String>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
struct Maintenance {
off: bool,
fired: BTreeMap<String, String>,
next: u64,
}
#[derive(Debug)]
pub struct Sidecar {
path: Option<PathBuf>,
data: Mutex<Data>,
dirty: AtomicBool,
}
impl Default for Sidecar {
fn default() -> Self {
Sidecar::in_memory()
}
}
impl Sidecar {
pub fn in_memory() -> Self {
Sidecar {
path: None,
data: Mutex::new(Data {
version: VERSION,
..Data::default()
}),
dirty: AtomicBool::new(false),
}
}
pub fn open(dir: &Path) -> (Self, Option<String>) {
let path = dir.join(FILE);
let mut note = None;
let data = match std::fs::read(&path) {
Ok(bytes) => match serde_json::from_slice::<Data>(&bytes) {
Ok(data) => data,
Err(e) => {
let aside = dir.join(format!("{FILE}.unreadable"));
let _ = std::fs::rename(&path, &aside);
note = Some(format!(
"{} could not be read ({e}) and was set aside as {}; statistics \
start again and older facts are unverified until rewritten",
path.display(),
aside.display()
));
Data::default()
}
},
Err(_) => Data::default(),
};
(
Sidecar {
path: Some(path),
data: Mutex::new(Data {
version: VERSION,
..data
}),
dirty: AtomicBool::new(false),
},
note,
)
}
fn data(&self) -> std::sync::MutexGuard<'_, Data> {
self.data.lock().unwrap_or_else(|e| e.into_inner())
}
pub fn count(&self, project: &str, client: &str, change: impl FnOnce(&mut Counters)) {
let mut data = self.data();
change(
data.stats
.entry(project.to_owned())
.or_default()
.entry(client.to_owned())
.or_default(),
);
self.dirty.store(true, Ordering::Relaxed);
}
pub fn record_fact(&self, id: &str, hashes: Hashes) {
let mut data = self.data();
let order = data.next_order;
data.next_order += 1;
data.facts
.insert(id.to_owned(), FactRecord { order, hashes });
if data.facts.len() > MAX_FACT_RECORDS {
if let Some(oldest) = data
.facts
.iter()
.min_by_key(|(_, r)| r.order)
.map(|(k, _)| k.clone())
{
data.facts.remove(&oldest);
}
}
self.dirty.store(true, Ordering::Relaxed);
}
pub fn saw(&self, project: &str, client: &str, branch: &str, commit: &str, seq: u64) {
let mut data = self.data();
let unchanged = data
.seen
.get(project)
.and_then(|c| c.get(client))
.and_then(|b| b.get(branch))
.is_some_and(|r| r.commit == commit);
if unchanged {
return;
}
let order = data.next_order;
data.next_order += 1;
data.seen
.entry(project.to_owned())
.or_default()
.entry(client.to_owned())
.or_default()
.insert(
branch.to_owned(),
SeenRecord {
commit: commit.to_owned(),
seq,
order,
},
);
let total: usize = data
.seen
.values()
.flat_map(BTreeMap::values)
.map(BTreeMap::len)
.sum();
if total > MAX_SEEN_RECORDS {
let oldest = data
.seen
.iter()
.flat_map(|(p, clients)| {
clients.iter().flat_map(move |(c, branches)| {
branches
.iter()
.map(move |(b, r)| (r.order, p.clone(), c.clone(), b.clone()))
})
})
.min();
if let Some((_, p, c, b)) = oldest {
if let Some(branches) = data.seen.get_mut(&p).and_then(|cs| cs.get_mut(&c)) {
branches.remove(&b);
}
}
}
self.dirty.store(true, Ordering::Relaxed);
}
pub fn last_seen(&self, project: &str, client: &str, branch: &str) -> Option<(String, u64)> {
self.data()
.seen
.get(project)
.and_then(|c| c.get(client))
.and_then(|b| b.get(branch))
.map(|r| (r.commit.clone(), r.seq))
}
pub fn note_facts(&self, project: &str, facts: &[(String, String)]) {
if facts.is_empty() {
return;
}
let mut data = self.data();
let Data { stale, fresh, .. } = &mut *data;
let stale = stale.entry(project.to_owned()).or_default();
let fresh = fresh.entry(project.to_owned()).or_default();
for (key, state) in facts {
match state.as_str() {
"stale" => {
if stale.len() < MAX_STALE_KEPT {
stale.insert(key.clone());
}
fresh.remove(key);
}
"fresh" => {
stale.remove(key);
if fresh.len() < MAX_STALE_KEPT {
fresh.insert(key.clone());
}
}
_ => {}
}
}
self.dirty.store(true, Ordering::Relaxed);
}
pub fn note_briefing(&self, project: &str, mut briefing: Briefing) -> bool {
let mut data = self.data();
briefing.order = data.next_order;
data.next_order += 1;
let list = data.briefings.entry(project.to_owned()).or_default();
let picked_up = briefing.handoff.as_ref().is_some_and(|handoff| {
!list
.iter()
.any(|b| b.to == briefing.to && b.handoff.as_ref() == Some(handoff))
});
list.push(briefing);
if list.len() > MAX_BRIEFINGS_KEPT {
let excess = list.len() - MAX_BRIEFINGS_KEPT;
list.drain(..excess);
}
self.dirty.store(true, Ordering::Relaxed);
picked_up
}
pub fn briefings(&self, project: &str) -> Vec<Briefing> {
self.data()
.briefings
.get(project)
.cloned()
.unwrap_or_default()
}
pub fn fresh_facts(&self, project: &str) -> Vec<String> {
self.data()
.fresh
.get(project)
.map(|s| s.iter().cloned().collect())
.unwrap_or_default()
}
pub fn stale_facts(&self, project: &str) -> Vec<String> {
self.data()
.stale
.get(project)
.map(|s| s.iter().cloned().collect())
.unwrap_or_default()
}
pub fn maintenance_on(&self, project: &str) -> bool {
!self.data().maintenance.get(project).is_some_and(|m| m.off)
}
pub fn set_maintenance(&self, project: &str, on: bool) {
self.data()
.maintenance
.entry(project.to_owned())
.or_default()
.off = !on;
self.dirty.store(true, Ordering::Relaxed);
}
pub fn fired(&self, project: &str, trigger: &str) -> Option<String> {
self.data()
.maintenance
.get(project)
.and_then(|m| m.fired.get(trigger).cloned())
}
pub fn fired_all(&self, project: &str) -> BTreeMap<String, String> {
self.data()
.maintenance
.get(project)
.map(|m| m.fired.clone())
.unwrap_or_default()
}
pub fn fire(
&self,
project: &str,
trigger: &str,
key_for: impl FnOnce(u64) -> String,
) -> String {
let mut data = self.data();
let m = data.maintenance.entry(project.to_owned()).or_default();
m.next += 1;
let key = key_for(m.next);
m.fired.insert(trigger.to_owned(), key.clone());
self.dirty.store(true, Ordering::Relaxed);
key
}
pub fn rearm(&self, project: &str, trigger: &str) {
if let Some(m) = self.data().maintenance.get_mut(project) {
m.fired.remove(trigger);
}
self.dirty.store(true, Ordering::Relaxed);
}
pub fn fact(&self, id: &str) -> Option<Hashes> {
self.data().facts.get(id).map(|r| r.hashes.clone())
}
pub fn reflog_cursor(&self, worktree: &str) -> Option<u64> {
self.data().reflog_cursors.get(worktree).copied()
}
pub fn set_reflog_cursor(&self, worktree: &str, cursor: u64) {
let mut data = self.data();
if data.reflog_cursors.get(worktree) == Some(&cursor) {
return;
}
data.reflog_cursors.insert(worktree.to_owned(), cursor);
self.dirty.store(true, Ordering::Relaxed);
}
pub fn followed(&self, repo: &str) -> std::collections::BTreeSet<String> {
self.data().followed.get(repo).cloned().unwrap_or_default()
}
pub fn note_followed(&self, repo: &str, branch: &str) {
let mut data = self.data();
let set = data.followed.entry(repo.to_owned()).or_default();
if set.contains(branch) {
return;
}
if set.len() >= crate::autopilot::git::MAX_BRANCHES {
return;
}
set.insert(branch.to_owned());
self.dirty.store(true, Ordering::Relaxed);
}
pub fn set_orphans(&self, project: &str, orphans: Vec<String>) {
let mut data = self.data();
let side = data.autopilot.entry(project.to_owned()).or_default();
if side.orphans == orphans {
return;
}
side.orphans = orphans;
self.dirty.store(true, Ordering::Relaxed);
}
pub fn orphans(&self, project: &str) -> Vec<String> {
self.data()
.autopilot
.get(project)
.map(|a| a.orphans.clone())
.unwrap_or_default()
}
pub fn journal(&self, project: &str, mut entry: crate::autopilot::JournalEntry) {
let mut data = self.data();
entry.order = data.next_order;
data.next_order += 1;
let side = data.autopilot.entry(project.to_owned()).or_default();
side.journal.push(entry);
if side.journal.len() > crate::autopilot::MAX_JOURNAL {
let excess = side.journal.len() - crate::autopilot::MAX_JOURNAL;
side.journal.drain(..excess);
}
self.dirty.store(true, Ordering::Relaxed);
}
pub fn journal_entries(&self, project: &str) -> Vec<crate::autopilot::JournalEntry> {
self.data()
.autopilot
.get(project)
.map(|a| a.journal.clone())
.unwrap_or_default()
}
pub fn stats(&self, project: Option<&str>) -> Json {
let data = self.data();
let mut projects = serde_json::Map::new();
let mut total = Counters::default();
for (name, clients) in &data.stats {
if project.is_some_and(|p| p != name) {
continue;
}
let mut by_client = serde_json::Map::new();
for (client, c) in clients {
add(&mut total, c);
by_client.insert(client.clone(), json!(c));
}
projects.insert(name.clone(), Json::Object(by_client));
}
json!({ "projects": projects, "total": total })
}
pub fn flush(&self) -> Result<(), String> {
let Some(path) = &self.path else {
return Ok(());
};
if !self.dirty.swap(false, Ordering::Relaxed) {
return Ok(());
}
let bytes = serde_json::to_vec(&*self.data())
.map_err(|e| format!("cannot encode {}: {e}", path.display()))?;
let tmp = path.with_extension("json.tmp");
std::fs::write(&tmp, bytes)
.and_then(|()| std::fs::rename(&tmp, path))
.map_err(|e| {
self.dirty.store(true, Ordering::Relaxed);
format!("cannot write {}: {e}", path.display())
})
}
}
fn add(total: &mut Counters, c: &Counters) {
total.briefings += c.briefings;
total.briefing_bytes += c.briefing_bytes;
total.memory_bytes += c.memory_bytes;
total.lessons_recorded += c.lessons_recorded;
total.lessons_served += c.lessons_served;
total.facts_fresh += c.facts_fresh;
total.facts_stale += c.facts_stale;
total.facts_unverified += c.facts_unverified;
total.claims += c.claims;
total.claim_conflicts += c.claim_conflicts;
total.finds += c.finds;
total.handoffs_picked_up += c.handoffs_picked_up;
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_survives_a_restart_and_sets_a_bad_file_aside() {
let tmp = tempfile::tempdir().unwrap();
let (side, note) = Sidecar::open(tmp.path());
assert!(note.is_none());
side.count("shop", "claude-code", |c| c.claims += 2);
let mut hashes = Hashes::new();
hashes.insert("src/a.rs".to_owned(), Some("abc".to_owned()));
side.record_fact("f1", hashes.clone());
side.flush().unwrap();
let (again, _) = Sidecar::open(tmp.path());
assert_eq!(again.stats(None)["total"]["claims"], 2);
assert_eq!(again.fact("f1"), Some(hashes));
std::fs::write(tmp.path().join(FILE), "not json").unwrap();
let (fresh, note) = Sidecar::open(tmp.path());
assert!(note.unwrap().contains("set aside"));
assert_eq!(fresh.stats(None)["total"]["claims"], 0);
assert!(tmp.path().join(format!("{FILE}.unreadable")).exists());
}
#[test]
fn fact_records_are_bounded_oldest_first() {
let side = Sidecar::in_memory();
for i in 0..(MAX_FACT_RECORDS + 3) {
side.record_fact(&format!("f{i}"), Hashes::new());
}
assert!(side.fact("f0").is_none());
assert!(side.fact("f2").is_none());
assert!(side.fact("f3").is_some());
}
#[test]
fn stats_are_per_project_and_client_with_totals() {
let side = Sidecar::in_memory();
side.count("a", "x", |c| c.briefings += 1);
side.count("a", "y", |c| c.briefings += 2);
side.count("b", "x", |c| c.briefings += 4);
let all = side.stats(None);
assert_eq!(all["total"]["briefings"], 7);
assert_eq!(all["projects"]["a"]["y"]["briefings"], 2);
assert_eq!(side.stats(Some("b"))["total"]["briefings"], 4);
}
#[test]
fn briefings_are_kept_bounded_and_a_handoff_is_picked_up_once_per_client() {
let side = Sidecar::in_memory();
let brief = |to: &str, handoff: Option<&str>| Briefing {
to: to.to_owned(),
branch: "main".to_owned(),
handoff: handoff.map(str::to_owned),
keys: handoff.map(str::to_owned).into_iter().collect(),
..Briefing::default()
};
assert!(!side.note_briefing("shop", brief("codex", None)));
assert!(side.note_briefing("shop", brief("codex", Some("shop:handoff:00000001"))));
assert!(!side.note_briefing("shop", brief("codex", Some("shop:handoff:00000001"))));
assert!(side.note_briefing("shop", brief("claude", Some("shop:handoff:00000001"))));
assert!(side.note_briefing("shop", brief("codex", Some("shop:handoff:00000002"))));
let kept = side.briefings("shop");
assert_eq!(kept.len(), 5);
assert!(kept.windows(2).all(|w| w[0].order < w[1].order));
assert!(side.briefings("other").is_empty());
for i in 0..(MAX_BRIEFINGS_KEPT + 7) {
side.note_briefing("big", brief(&format!("c{i}"), None));
}
let big = side.briefings("big");
assert_eq!(big.len(), MAX_BRIEFINGS_KEPT);
assert_eq!(big[0].to, "c7", "the oldest were not the ones dropped");
}
}