@@ -0,0 +1,1192 @@ +use std::{ + collections::{BTreeMap, BTreeSet}, + fs, + path::{Path, PathBuf}, +}; + +use anyhow::{bail, Context, Result}; +use chrono::Utc; +use klbr_core::models::ToolCall; +use rusqlite::{params, Connection, OptionalExtension}; +use serde::Serialize; +use serde_json::Value; + +#[derive(Debug)] +pub(crate) struct FolgezettelUsageOptions { + pub(crate) db: PathBuf, + pub(crate) out: Option, + pub(crate) lookahead_turns: usize, + pub(crate) excerpt_chars: usize, +} + +#[derive(Debug, Serialize)] +struct FolgezettelUsageReport { + schema_version: u8, + generated_at: String, + db_path: String, + options: ReportOptions, + note_inventory: BTreeMap, + totals: FolgezettelUsageTotals, + review: ReviewSummary, + calls: Vec, +} + +#[derive(Debug, Serialize)] +struct ReportOptions { + lookahead_turns: usize, + excerpt_chars: usize, +} + +#[derive(Debug, Default, Serialize)] +struct FolgezettelUsageTotals { + total_calls: usize, + failures: usize, + writes: usize, + searches: usize, + follows: usize, + recalls: usize, + links: usize, + revisions: usize, + notes_written: usize, + later_answer_citation_hits: usize, + later_tool_reuse_hits: usize, + later_fleeting_promotion_hits: usize, + revisions_with_supersedes: usize, + revisions_without_supersedes: usize, + stale_old_ref_mentions_after_revision: usize, + calls_by_tool: BTreeMap, +} + +#[derive(Debug, Default, Serialize)] +struct ReviewSummary { + failures: Vec, + writes_without_later_reuse: Vec, + revisions_without_supersedes: Vec, + stale_old_ref_mentions_after_revision: Vec, + vague_titles: Vec, + fleeting_without_promotion: Vec, +} + +#[derive(Debug, Clone, Serialize)] +struct ReviewItem { + assistant_turn_id: i64, + tool: String, + note_id: Option, + title: Option, + reason: String, +} + +#[derive(Debug, Clone, Serialize)] +struct MkToolCallReport { + assistant_turn_id: i64, + tool_result_turn_id: Option, + timestamp: i64, + tool_call_id: String, + tool: String, + arguments: Value, + output: ToolOutputSummary, + reuse: ReuseSummary, + revision: Option, + review_flags: Vec, +} + +#[derive(Debug, Clone, Serialize)] +struct ToolOutputSummary { + status: String, + error: Option, + note: Option, + link: Option, + notes: Vec, + raw_excerpt: Option, +} + +#[derive(Debug, Clone, Serialize)] +struct NoteOutput { + id: String, + ref_id: String, + title: String, + lane: String, + kind: String, + path: String, + status: String, + parent: Option, + source_refs: Vec, + child_count: usize, + body_excerpt: String, +} + +#[derive(Debug, Clone, Serialize)] +struct NoteHandle { + id: String, + ref_id: String, + title: String, + lane: String, + kind: String, + status: String, + parent: Option, +} + +#[derive(Debug, Clone, Serialize)] +struct LinkOutput { + edge_id: Option, + from: String, + to: String, + relation: String, +} + +#[derive(Debug, Clone, Default, Serialize)] +struct ReuseSummary { + later_answer_citations: Vec, + later_tool_uses: Vec, + later_fleeting_promotions: Vec, +} + +#[derive(Debug, Clone, Serialize)] +struct LaterAnswerHit { + turn_id: i64, + matched: String, + match_kind: String, + excerpt: String, +} + +#[derive(Debug, Clone, Serialize)] +struct LaterToolUseHit { + assistant_turn_id: i64, + tool_call_id: String, + tool: String, + matched: String, + match_kind: String, + arguments: Value, +} + +#[derive(Debug, Clone, Serialize)] +struct RevisionCheck { + old_id: String, + new_id: Option, + old_canonical_refs: Vec, + new_canonical_refs: Vec, + has_ref_status_link: bool, + has_supersedes_edge: bool, + stale_old_mentions_after_revision: Vec, +} + +#[derive(Debug, Clone)] +struct ReuseKey { + kind: &'static str, + value: String, +} + +struct ToolResultRow { + id: i64, + content: String, +} + +pub(crate) async fn run_folgezettel_usage_command(options: FolgezettelUsageOptions) -> Result<()> { + if options.lookahead_turns == 0 { + bail!("--lookahead-turns must be greater than 0"); + } + + let conn = Connection::open(&options.db) + .with_context(|| format!("failed to open sqlite db {}", options.db.display()))?; + let report = build_folgezettel_usage_report(&conn, &options.db, &options)?; + let output_json = serde_json::to_vec_pretty(&report)?; + + if let Some(out) = &options.out { + if let Some(parent) = out.parent().filter(|path| !path.as_os_str().is_empty()) { + fs::create_dir_all(parent)?; + } + fs::write(out, output_json)?; + println!( + "folgezettel usage: {} mk calls, {} writes, {} failures, {} review flags", + report.totals.total_calls, + report.totals.writes, + report.totals.failures, + report.review_flag_count() + ); + println!("wrote folgezettel usage report to {}", out.display()); + } else { + println!("{}", String::from_utf8(output_json)?); + } + + Ok(()) +} + +fn build_folgezettel_usage_report( + conn: &Connection, + db_path: &Path, + options: &FolgezettelUsageOptions, +) -> Result { + let turn_ranks = load_turn_ranks(conn)?; + let mut calls = load_mk_tool_calls(conn, options.excerpt_chars)?; + + let reuses = calls + .iter() + .enumerate() + .map(|(idx, _)| { + find_later_reuse( + conn, + &turn_ranks, + &calls, + idx, + options.lookahead_turns, + options.excerpt_chars, + ) + }) + .collect::>>()?; + for (call, reuse) in calls.iter_mut().zip(reuses) { + call.reuse = reuse; + } + + let revisions = calls + .iter() + .map(|call| { + if call.tool == "mk_revise" { + check_revision( + conn, + &turn_ranks, + call, + options.lookahead_turns, + options.excerpt_chars, + ) + .map(Some) + } else { + Ok(None) + } + }) + .collect::>>()?; + for (call, revision) in calls.iter_mut().zip(revisions) { + call.revision = revision; + } + + for call in &mut calls { + call.review_flags = review_flags(call); + } + + let totals = compute_totals(&calls); + let review = collect_review(&calls); + + Ok(FolgezettelUsageReport { + schema_version: 1, + generated_at: Utc::now().to_rfc3339(), + db_path: db_path.display().to_string(), + options: ReportOptions { + lookahead_turns: options.lookahead_turns, + excerpt_chars: options.excerpt_chars, + }, + note_inventory: load_note_inventory(conn)?, + totals, + review, + calls, + }) +} + +fn load_mk_tool_calls(conn: &Connection, excerpt_chars: usize) -> Result> { + let mut stmt = conn.prepare( + "SELECT id, ts, tool_calls + FROM turns + WHERE role = 'assistant' + AND tool_calls IS NOT NULL + AND tool_calls <> '' + ORDER BY id ASC", + )?; + let rows = stmt.query_map([], |row| { + Ok(( + row.get::<_, i64>(0)?, + row.get::<_, i64>(1)?, + row.get::<_, String>(2)?, + )) + })?; + + let mut calls = Vec::new(); + for row in rows { + let (assistant_turn_id, timestamp, tool_calls_json) = row?; + let tool_calls: Vec = serde_json::from_str(&tool_calls_json) + .with_context(|| format!("failed to parse tool_calls for turn {assistant_turn_id}"))?; + + for tool_call in tool_calls + .into_iter() + .filter(|call| call.function.name.starts_with("mk_")) + { + let arguments = parse_arguments(&tool_call.function.arguments); + let result = load_tool_result(conn, &tool_call.id)?; + let output = summarize_tool_output( + result.as_ref().map(|row| row.content.as_str()), + excerpt_chars, + ); + calls.push(MkToolCallReport { + assistant_turn_id, + tool_result_turn_id: result.as_ref().map(|row| row.id), + timestamp, + tool_call_id: tool_call.id, + tool: tool_call.function.name, + arguments, + output, + reuse: ReuseSummary::default(), + revision: None, + review_flags: Vec::new(), + }); + } + } + + Ok(calls) +} + +fn load_tool_result(conn: &Connection, tool_call_id: &str) -> Result> { + conn.query_row( + "SELECT id, content + FROM turns + WHERE role = 'tool' + AND tool_call_id = ?1 + ORDER BY id ASC + LIMIT 1", + params![tool_call_id], + |row| { + Ok(ToolResultRow { + id: row.get(0)?, + content: row.get(1)?, + }) + }, + ) + .optional() + .map_err(Into::into) +} + +fn load_turn_ranks(conn: &Connection) -> Result> { + let mut stmt = conn.prepare("SELECT id FROM turns ORDER BY id ASC")?; + let rows = stmt.query_map([], |row| row.get::<_, i64>(0))?; + let mut ranks = BTreeMap::new(); + for (idx, row) in rows.enumerate() { + ranks.insert(row?, idx); + } + Ok(ranks) +} + +fn load_note_inventory(conn: &Connection) -> Result> { + let mut stmt = + conn.prepare("SELECT kind, COUNT(*) FROM markdown_notes GROUP BY kind ORDER BY kind")?; + let rows = stmt.query_map([], |row| { + Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?)) + })?; + let mut inventory = BTreeMap::new(); + for row in rows { + let (kind, count) = row?; + inventory.insert(kind, count as usize); + } + Ok(inventory) +} + +fn summarize_tool_output(content: Option<&str>, excerpt_chars: usize) -> ToolOutputSummary { + let Some(content) = content else { + return ToolOutputSummary { + status: "missing_result".to_string(), + error: Some("missing tool result row".to_string()), + note: None, + link: None, + notes: Vec::new(), + raw_excerpt: None, + }; + }; + + let trimmed = content.trim(); + if trimmed.starts_with("error:") { + return ToolOutputSummary { + status: "error".to_string(), + error: Some(trimmed.to_string()), + note: None, + link: None, + notes: Vec::new(), + raw_excerpt: Some(truncate_chars(trimmed, excerpt_chars)), + }; + } + + let Ok(value) = serde_json::from_str::(trimmed) else { + return ToolOutputSummary { + status: "raw".to_string(), + error: None, + note: None, + link: None, + notes: Vec::new(), + raw_excerpt: Some(truncate_chars(trimmed, excerpt_chars)), + }; + }; + + let note = note_output_from_value(&value, excerpt_chars); + let link = link_output_from_value(&value); + let mut notes = Vec::new(); + collect_note_handles(&value, &mut notes); + dedup_note_handles(&mut notes); + + ToolOutputSummary { + status: "ok".to_string(), + error: None, + note, + link, + notes, + raw_excerpt: None, + } +} + +fn parse_arguments(arguments: &str) -> Value { + serde_json::from_str(arguments).unwrap_or_else(|_| Value::String(arguments.to_string())) +} + +fn note_output_from_value(value: &Value, excerpt_chars: usize) -> Option { + let handle = note_handle_from_value(value)?; + let body = value.get("body").and_then(Value::as_str)?; + Some(NoteOutput { + id: handle.id, + ref_id: handle.ref_id, + title: handle.title, + lane: handle.lane, + kind: handle.kind, + path: string_field(value, "path").unwrap_or_default(), + status: handle.status, + parent: handle.parent, + source_refs: string_array_field(value, "source_refs"), + child_count: value + .get("child_count") + .and_then(Value::as_u64) + .unwrap_or(0) as usize, + body_excerpt: truncate_chars(body, excerpt_chars), + }) +} + +fn note_handle_from_value(value: &Value) -> Option { + let id = string_field(value, "id")?; + let ref_id = string_field(value, "ref_id").unwrap_or_else(|| id.clone()); + Some(NoteHandle { + id, + ref_id, + title: string_field(value, "title").unwrap_or_default(), + lane: string_field(value, "lane").unwrap_or_default(), + kind: string_field(value, "kind").unwrap_or_default(), + status: string_field(value, "status").unwrap_or_default(), + parent: string_field(value, "parent"), + }) +} + +fn link_output_from_value(value: &Value) -> Option { + Some(LinkOutput { + edge_id: value.get("edge_id").and_then(Value::as_i64), + from: string_field(value, "from")?, + to: string_field(value, "to")?, + relation: string_field(value, "relation")?, + }) +} + +fn collect_note_handles(value: &Value, out: &mut Vec) { + if let Some(note) = note_handle_from_value(value) { + out.push(note); + } + + match value { + Value::Array(items) => { + for item in items { + collect_note_handles(item, out); + } + } + Value::Object(map) => { + for nested in map.values() { + collect_note_handles(nested, out); + } + } + _ => {} + } +} + +fn dedup_note_handles(notes: &mut Vec) { + let mut seen = BTreeSet::new(); + notes.retain(|note| seen.insert(note.ref_id.clone())); +} + +fn find_later_reuse( + conn: &Connection, + turn_ranks: &BTreeMap, + calls: &[MkToolCallReport], + idx: usize, + lookahead_turns: usize, + excerpt_chars: usize, +) -> Result { + let call = &calls[idx]; + let keys = reuse_keys(call); + if keys.is_empty() { + return Ok(ReuseSummary::default()); + } + + let later_answer_citations = later_answer_hits( + conn, + turn_ranks, + call.tool_result_turn_id.unwrap_or(call.assistant_turn_id), + lookahead_turns, + excerpt_chars, + &keys, + )?; + + let later_tool_uses = calls + .iter() + .skip(idx + 1) + .filter(|later| { + within_lookahead( + turn_ranks, + call.tool_result_turn_id.unwrap_or(call.assistant_turn_id), + later.assistant_turn_id, + lookahead_turns, + ) + }) + .filter_map(|later| { + let arg_text = serde_json::to_string(&later.arguments).ok()?; + key_match(&arg_text, &keys, MatchMode::ToolArgument).map(|matched| LaterToolUseHit { + assistant_turn_id: later.assistant_turn_id, + tool_call_id: later.tool_call_id.clone(), + tool: later.tool.clone(), + matched: matched.value, + match_kind: matched.kind, + arguments: later.arguments.clone(), + }) + }) + .collect::>(); + + let later_fleeting_promotions = if call.tool == "mk_fleeting" { + later_tool_uses + .iter() + .filter(|hit| matches!(hit.tool.as_str(), "mk_remember" | "mk_revise")) + .cloned() + .collect() + } else { + Vec::new() + }; + + Ok(ReuseSummary { + later_answer_citations, + later_tool_uses, + later_fleeting_promotions, + }) +} + +fn later_answer_hits( + conn: &Connection, + turn_ranks: &BTreeMap, + after_turn_id: i64, + lookahead_turns: usize, + excerpt_chars: usize, + keys: &[ReuseKey], +) -> Result> { + let mut stmt = conn.prepare( + "SELECT id, content + FROM turns + WHERE id > ?1 + AND role = 'assistant' + AND content <> '' + ORDER BY id ASC", + )?; + let rows = stmt.query_map(params![after_turn_id], |row| { + Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?)) + })?; + + let mut hits = Vec::new(); + for row in rows { + let (turn_id, content) = row?; + if !within_lookahead(turn_ranks, after_turn_id, turn_id, lookahead_turns) { + break; + } + if let Some(matched) = key_match(&content, keys, MatchMode::AnswerText) { + hits.push(LaterAnswerHit { + turn_id, + matched: matched.value, + match_kind: matched.kind, + excerpt: matched_excerpt(&content, &matched.raw, excerpt_chars), + }); + } + } + + Ok(hits) +} + +fn check_revision( + conn: &Connection, + turn_ranks: &BTreeMap, + call: &MkToolCallReport, + lookahead_turns: usize, + excerpt_chars: usize, +) -> Result { + let old_id = string_field(&call.arguments, "id").unwrap_or_default(); + let old_canonical_refs = canonical_refs(conn, &old_id)?; + let new_id = call.output.note.as_ref().map(|note| note.id.clone()); + let mut new_refs = BTreeSet::new(); + if let Some(note) = &call.output.note { + for value in [¬e.id, ¬e.ref_id] { + for ref_id in canonical_refs(conn, value)? { + new_refs.insert(ref_id); + } + } + } + let new_canonical_refs = new_refs.into_iter().collect::>(); + + let has_ref_status_link = + refs_have_superseded_status(conn, &old_canonical_refs, &new_canonical_refs)?; + let has_supersedes_edge = + refs_have_supersedes_edge(conn, &old_canonical_refs, &new_canonical_refs)?; + let old_keys = old_canonical_refs + .iter() + .map(|value| ReuseKey { + kind: "old_ref", + value: value.clone(), + }) + .collect::>(); + let stale_old_mentions_after_revision = later_answer_hits( + conn, + turn_ranks, + call.tool_result_turn_id.unwrap_or(call.assistant_turn_id), + lookahead_turns, + excerpt_chars, + &old_keys, + )?; + + Ok(RevisionCheck { + old_id, + new_id, + old_canonical_refs, + new_canonical_refs, + has_ref_status_link, + has_supersedes_edge, + stale_old_mentions_after_revision, + }) +} + +fn canonical_refs(conn: &Connection, value: &str) -> Result> { + let value = value.trim(); + if value.is_empty() { + return Ok(Vec::new()); + } + + let mut refs = BTreeSet::from([value.to_string()]); + conn.query_row( + "SELECT ref_id FROM ref_aliases WHERE alias = ?1", + params![value], + |row| row.get::<_, String>(0), + ) + .optional()? + .into_iter() + .for_each(|ref_id| { + refs.insert(ref_id); + }); + conn.query_row( + "SELECT ref_id FROM refs WHERE ref_id = ?1", + params![value], + |row| row.get::<_, String>(0), + ) + .optional()? + .into_iter() + .for_each(|ref_id| { + refs.insert(ref_id); + }); + + Ok(refs.into_iter().collect()) +} + +fn refs_have_superseded_status( + conn: &Connection, + old_refs: &[String], + new_refs: &[String], +) -> Result { + for old_ref in old_refs { + let replacement = conn + .query_row( + "SELECT replacement_ref_id + FROM refs + WHERE ref_id = ?1 + AND status = 'superseded'", + params![old_ref], + |row| row.get::<_, Option>(0), + ) + .optional()? + .flatten(); + if replacement + .as_ref() + .is_some_and(|replacement| new_refs.iter().any(|new_ref| new_ref == replacement)) + { + return Ok(true); + } + } + Ok(false) +} + +fn refs_have_supersedes_edge( + conn: &Connection, + old_refs: &[String], + new_refs: &[String], +) -> Result { + for new_ref in new_refs { + for old_ref in old_refs { + let count: i64 = conn.query_row( + "SELECT COUNT(*) + FROM edges + WHERE rel_type = 'supersedes' + AND edge_state = 'active' + AND (src_ref_id = ?1 OR src_ref_id_original = ?1) + AND (dst_ref_id = ?2 OR dst_ref_id_original = ?2)", + params![new_ref, old_ref], + |row| row.get(0), + )?; + if count > 0 { + return Ok(true); + } + } + } + Ok(false) +} + +fn reuse_keys(call: &MkToolCallReport) -> Vec { + let mut keys = Vec::new(); + let mut seen = BTreeSet::new(); + if let Some(note) = &call.output.note { + push_key(&mut keys, &mut seen, "note_id", ¬e.id); + push_key(&mut keys, &mut seen, "ref_id", ¬e.ref_id); + push_title_key(&mut keys, &mut seen, ¬e.title); + } + if let Some(link) = &call.output.link { + push_key(&mut keys, &mut seen, "link_from", &link.from); + push_key(&mut keys, &mut seen, "link_to", &link.to); + } + + for field in ["id", "note_ref", "parent", "from", "to"] { + if let Some(value) = string_field(&call.arguments, field) { + push_key(&mut keys, &mut seen, field, &value); + } + } + for source_ref in string_array_field(&call.arguments, "source_refs") { + push_key(&mut keys, &mut seen, "source_ref", &source_ref); + } + + keys +} + +fn push_key( + keys: &mut Vec, + seen: &mut BTreeSet<(String, String)>, + kind: &'static str, + value: &str, +) { + let value = value.trim(); + if value.len() < 2 { + return; + } + if seen.insert((kind.to_string(), value.to_string())) { + keys.push(ReuseKey { + kind, + value: value.to_string(), + }); + } +} + +fn push_title_key(keys: &mut Vec, seen: &mut BTreeSet<(String, String)>, title: &str) { + if title.chars().count() >= 8 { + push_key(keys, seen, "title", title); + } +} + +#[derive(Clone, Copy)] +enum MatchMode { + AnswerText, + ToolArgument, +} + +struct KeyMatch { + kind: String, + value: String, + raw: String, +} + +fn key_match(text: &str, keys: &[ReuseKey], mode: MatchMode) -> Option { + for key in keys { + let Some(raw) = key_match_raw(text, key, mode) else { + continue; + }; + return Some(KeyMatch { + kind: key.kind.to_string(), + value: key.value.clone(), + raw, + }); + } + None +} + +fn key_match_raw(text: &str, key: &ReuseKey, mode: MatchMode) -> Option { + match (mode, key.kind) { + (MatchMode::AnswerText, "title") => { + contains_case_insensitive(text, &key.value).then(|| key.value.clone()) + } + (MatchMode::AnswerText, _) => { + let bracketed = format!("[{}]", key.value); + if text.contains(&bracketed) { + Some(bracketed) + } else if key.value.len() >= 6 && text.contains(&key.value) { + Some(key.value.clone()) + } else { + None + } + } + (MatchMode::ToolArgument, "title") => { + contains_case_insensitive(text, &key.value).then(|| key.value.clone()) + } + (MatchMode::ToolArgument, _) => text.contains(&key.value).then(|| key.value.clone()), + } +} + +fn contains_case_insensitive(haystack: &str, needle: &str) -> bool { + haystack + .to_ascii_lowercase() + .contains(&needle.to_ascii_lowercase()) +} + +fn within_lookahead( + turn_ranks: &BTreeMap, + after_turn_id: i64, + target_turn_id: i64, + lookahead_turns: usize, +) -> bool { + match ( + turn_ranks.get(&after_turn_id), + turn_ranks.get(&target_turn_id), + ) { + (Some(after), Some(target)) => target > after && target - after <= lookahead_turns, + _ => target_turn_id > after_turn_id, + } +} + +fn review_flags(call: &MkToolCallReport) -> Vec { + let mut flags = Vec::new(); + if call.output.error.is_some() { + flags.push("failure".to_string()); + } + if is_write_tool(&call.tool) + && call.output.note.is_some() + && call.reuse.later_answer_citations.is_empty() + && call.reuse.later_tool_uses.is_empty() + { + flags.push("write_without_later_reuse".to_string()); + } + if let Some(revision) = &call.revision { + if !(revision.has_ref_status_link && revision.has_supersedes_edge) { + flags.push("revision_without_supersedes_evidence".to_string()); + } + if !revision.stale_old_mentions_after_revision.is_empty() { + flags.push("stale_old_ref_mentioned_after_revision".to_string()); + } + } + if let Some(note) = &call.output.note { + if title_is_vague(¬e.title) { + flags.push("vague_title".to_string()); + } + } + if call.tool == "mk_fleeting" + && call.output.note.is_some() + && call.reuse.later_fleeting_promotions.is_empty() + { + flags.push("fleeting_without_promotion".to_string()); + } + flags +} + +fn compute_totals(calls: &[MkToolCallReport]) -> FolgezettelUsageTotals { + let mut totals = FolgezettelUsageTotals { + total_calls: calls.len(), + ..FolgezettelUsageTotals::default() + }; + for call in calls { + *totals.calls_by_tool.entry(call.tool.clone()).or_default() += 1; + if call.output.error.is_some() { + totals.failures += 1; + } + match call.tool.as_str() { + "mk_search" => totals.searches += 1, + "mk_follow" => totals.follows += 1, + "mk_recall" => totals.recalls += 1, + "mk_link" => totals.links += 1, + "mk_revise" => { + totals.revisions += 1; + totals.writes += 1; + } + "mk_remember" | "mk_fleeting" => totals.writes += 1, + _ => {} + } + if is_write_tool(&call.tool) && call.output.note.is_some() { + totals.notes_written += 1; + } + totals.later_answer_citation_hits += call.reuse.later_answer_citations.len(); + totals.later_tool_reuse_hits += call.reuse.later_tool_uses.len(); + totals.later_fleeting_promotion_hits += call.reuse.later_fleeting_promotions.len(); + if let Some(revision) = &call.revision { + if revision.has_ref_status_link && revision.has_supersedes_edge { + totals.revisions_with_supersedes += 1; + } else { + totals.revisions_without_supersedes += 1; + } + totals.stale_old_ref_mentions_after_revision += + revision.stale_old_mentions_after_revision.len(); + } + } + totals +} + +fn collect_review(calls: &[MkToolCallReport]) -> ReviewSummary { + let mut review = ReviewSummary::default(); + for call in calls { + for flag in &call.review_flags { + let item = review_item(call, flag); + match flag.as_str() { + "failure" => review.failures.push(item), + "write_without_later_reuse" => review.writes_without_later_reuse.push(item), + "revision_without_supersedes_evidence" => { + review.revisions_without_supersedes.push(item); + } + "stale_old_ref_mentioned_after_revision" => { + review.stale_old_ref_mentions_after_revision.push(item); + } + "vague_title" => review.vague_titles.push(item), + "fleeting_without_promotion" => review.fleeting_without_promotion.push(item), + _ => {} + } + } + } + review +} + +fn review_item(call: &MkToolCallReport, reason: &str) -> ReviewItem { + ReviewItem { + assistant_turn_id: call.assistant_turn_id, + tool: call.tool.clone(), + note_id: call.output.note.as_ref().map(|note| note.id.clone()), + title: call.output.note.as_ref().map(|note| note.title.clone()), + reason: reason.to_string(), + } +} + +impl FolgezettelUsageReport { + fn review_flag_count(&self) -> usize { + self.review.failures.len() + + self.review.writes_without_later_reuse.len() + + self.review.revisions_without_supersedes.len() + + self.review.stale_old_ref_mentions_after_revision.len() + + self.review.vague_titles.len() + + self.review.fleeting_without_promotion.len() + } +} + +fn is_write_tool(tool: &str) -> bool { + matches!(tool, "mk_remember" | "mk_revise" | "mk_fleeting") +} + +fn title_is_vague(title: &str) -> bool { + let normalized = title.trim().to_ascii_lowercase(); + if normalized.is_empty() { + return true; + } + if title.chars().count() > 120 { + return true; + } + if normalized.split_whitespace().count() <= 1 { + return true; + } + matches!( + normalized.as_str(), + "memory" | "note" | "todo" | "preference" | "project" | "context" | "misc" | "scratch" + ) +} + +fn string_field(value: &Value, key: &str) -> Option { + value + .get(key) + .and_then(Value::as_str) + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(str::to_string) +} + +fn string_array_field(value: &Value, key: &str) -> Vec { + value + .get(key) + .and_then(Value::as_array) + .into_iter() + .flatten() + .filter_map(Value::as_str) + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(str::to_string) + .collect() +} + +fn matched_excerpt(text: &str, matched: &str, max_chars: usize) -> String { + let Some(byte_idx) = text.find(matched) else { + return truncate_chars(text, max_chars); + }; + let char_idx = text[..byte_idx].chars().count(); + let half = max_chars / 2; + let start = char_idx.saturating_sub(half); + let excerpt = text.chars().skip(start).take(max_chars).collect::(); + if start == 0 && excerpt.chars().count() == text.chars().count() { + excerpt + } else { + format!("...{}...", excerpt) + } +} + +fn truncate_chars(text: &str, max_chars: usize) -> String { + if text.chars().count() <= max_chars { + return text.to_string(); + } + let mut out = text.chars().take(max_chars).collect::(); + out.push_str("..."); + out +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn report_detects_later_answer_citation_for_written_note() { + let conn = trace_db(); + let tool_calls = json!([{ + "id": "call_remember", + "type": "function", + "function": { + "name": "mk_remember", + "arguments": "{\"title\":\"Durable source policy\",\"content\":\"body\",\"source_refs\":[\"src-turn\"]}" + } + }]); + conn.execute( + "INSERT INTO turns(id, role, content, tool_calls, ts) VALUES (1, 'assistant', '', ?1, 10)", + params![tool_calls.to_string()], + ) + .unwrap(); + conn.execute( + "INSERT INTO turns(id, role, content, tool_call_id, ts) VALUES (2, 'tool', ?1, 'call_remember', 11)", + params![note_json("z-durable-source-policy", "Durable source policy").to_string()], + ) + .unwrap(); + conn.execute( + "INSERT INTO turns(id, role, content, ts) VALUES (3, 'assistant', 'i will use [z-durable-source-policy] here', 12)", + [], + ) + .unwrap(); + conn.execute( + "INSERT INTO markdown_notes(kind) VALUES ('zettel_note')", + [], + ) + .unwrap(); + + let report = + build_folgezettel_usage_report(&conn, Path::new("trace.db"), &options()).unwrap(); + + assert_eq!(report.totals.total_calls, 1); + assert_eq!(report.totals.writes, 1); + assert_eq!(report.totals.failures, 0); + assert_eq!(report.totals.later_answer_citation_hits, 1); + assert!(report.review.writes_without_later_reuse.is_empty()); + } + + #[test] + fn report_verifies_revision_supersedes_edges() { + let conn = trace_db(); + conn.execute_batch( + "INSERT INTO refs(ref_id, status, replacement_ref_id) VALUES ('old-note', 'superseded', 'new-note'); + INSERT INTO refs(ref_id, status, replacement_ref_id) VALUES ('new-note', 'active', NULL); + INSERT INTO edges(src_ref_id, dst_ref_id, src_ref_id_original, dst_ref_id_original, rel_type, edge_state) + VALUES ('new-note', 'old-note', 'new-note', 'old-note', 'supersedes', 'active');", + ) + .unwrap(); + let tool_calls = json!([{ + "id": "call_revise", + "type": "function", + "function": { + "name": "mk_revise", + "arguments": "{\"id\":\"old-note\",\"title\":\"Replacement policy\",\"content\":\"body\",\"source_refs\":[\"src-turn\"]}" + } + }]); + conn.execute( + "INSERT INTO turns(id, role, content, tool_calls, ts) VALUES (1, 'assistant', '', ?1, 10)", + params![tool_calls.to_string()], + ) + .unwrap(); + conn.execute( + "INSERT INTO turns(id, role, content, tool_call_id, ts) VALUES (2, 'tool', ?1, 'call_revise', 11)", + params![note_json("new-note", "Replacement policy").to_string()], + ) + .unwrap(); + conn.execute( + "INSERT INTO markdown_notes(kind) VALUES ('zettel_note')", + [], + ) + .unwrap(); + + let report = + build_folgezettel_usage_report(&conn, Path::new("trace.db"), &options()).unwrap(); + let revision = report.calls[0].revision.as_ref().unwrap(); + + assert!(revision.has_ref_status_link); + assert!(revision.has_supersedes_edge); + assert_eq!(report.totals.revisions_with_supersedes, 1); + assert!(report.review.revisions_without_supersedes.is_empty()); + } + + fn trace_db() -> Connection { + let conn = Connection::open_in_memory().unwrap(); + conn.execute_batch( + "CREATE TABLE turns ( + id INTEGER PRIMARY KEY, + role TEXT NOT NULL, + content TEXT NOT NULL DEFAULT '', + thinking TEXT, + tool_calls TEXT, + tool_call_id TEXT, + status TEXT NOT NULL DEFAULT 'active', + ts INTEGER NOT NULL, + metadata TEXT NOT NULL DEFAULT '{}' + ); + CREATE TABLE markdown_notes (kind TEXT NOT NULL); + CREATE TABLE refs ( + ref_id TEXT PRIMARY KEY, + status TEXT NOT NULL, + replacement_ref_id TEXT + ); + CREATE TABLE ref_aliases (alias TEXT PRIMARY KEY, ref_id TEXT NOT NULL); + CREATE TABLE edges ( + src_ref_id TEXT, + dst_ref_id TEXT, + src_ref_id_original TEXT NOT NULL, + dst_ref_id_original TEXT NOT NULL, + rel_type TEXT NOT NULL, + edge_state TEXT NOT NULL + );", + ) + .unwrap(); + conn + } + + fn options() -> FolgezettelUsageOptions { + FolgezettelUsageOptions { + db: PathBuf::from("trace.db"), + out: None, + lookahead_turns: 40, + excerpt_chars: 120, + } + } + + fn note_json(id: &str, title: &str) -> Value { + json!({ + "id": id, + "ref_id": id, + "title": title, + "lane": "semantic", + "kind": "zettel_note", + "path": format!("zettel/{id}.md"), + "status": "active", + "parent": null, + "source_refs": ["src-turn"], + "child_count": 0, + "body": "sourced body" + }) + } +}