Skip to main content

fetchium_core/intelligence/
sgt.rs

1//! Source Genealogy Tracker (SGT) — PRD §8.15.
2//!
3//! Traces claim provenance through citation chains to the primary source.
4//! Detects "mutations" where claims are altered as they propagate.
5//! Computes trust cascade scores (trust degrades with each hop).
6//!
7//! Uses bigram-Jaccard similarity (from `intelligence::string_similarity`) for
8//! mutation detection — no external `strsim` dependency required.
9
10use crate::intelligence::string_similarity;
11
12// ─── Types ───────────────────────────────────────────────────────────────────
13
14/// A single node in a citation chain.
15#[derive(Debug, Clone, serde::Serialize)]
16pub struct GenealogyNode {
17    pub url: String,
18    pub title: String,
19    pub claim_text: String,
20    /// Trust at this depth: 1.0 − (depth × 0.15).
21    pub trust_score: f64,
22    /// Depth in the chain (0 = original, higher = further from original).
23    pub depth: usize,
24}
25
26/// Severity of a detected claim mutation.
27#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
28#[serde(rename_all = "snake_case")]
29pub enum MutationSeverity {
30    /// Similarity ≥ 0.8 — minor phrasing change.
31    Low,
32    /// 0.5 ≤ similarity < 0.8 — significant rewording.
33    Medium,
34    /// similarity < 0.5 — claim substantially altered.
35    High,
36}
37
38/// A mutation detected between two adjacent chain nodes.
39#[derive(Debug, Clone, serde::Serialize)]
40pub struct Mutation {
41    /// Index of the source node (earlier in chain).
42    pub from_depth: usize,
43    /// Index of the citing node (later in chain).
44    pub to_depth: usize,
45    pub original_claim: String,
46    pub mutated_claim: String,
47    pub similarity: f64,
48    pub severity: MutationSeverity,
49    pub description: String,
50}
51
52/// A complete citation chain with mutations and trust cascade.
53#[derive(Debug, Clone, serde::Serialize)]
54pub struct CitationChain {
55    /// Ordered from original claim (index 0) to most recent cite.
56    pub nodes: Vec<GenealogyNode>,
57    pub mutations: Vec<Mutation>,
58    /// Trust cascade: one value per node, matching `nodes` order.
59    pub trust_cascade: Vec<f64>,
60    /// The last node — best guess for the primary source.
61    pub primary_source: Option<GenealogyNode>,
62}
63
64// ─── Builder ─────────────────────────────────────────────────────────────────
65
66/// Build a citation chain synchronously from pre-fetched `hops`.
67///
68/// Each `hop` is `(url, title, claim_text)` ordered from original → most recent.
69/// Callers are responsible for fetching and ordering the hops.
70pub fn build_chain(hops: Vec<(String, String, String)>) -> CitationChain {
71    let nodes: Vec<GenealogyNode> = hops
72        .into_iter()
73        .enumerate()
74        .map(|(depth, (url, title, claim_text))| GenealogyNode {
75            url,
76            title,
77            claim_text,
78            trust_score: (1.0 - depth as f64 * 0.15).clamp(0.1, 1.0),
79            depth,
80        })
81        .collect();
82
83    let mutations = detect_mutations(&nodes);
84    let trust_cascade: Vec<f64> = nodes.iter().map(|n| n.trust_score).collect();
85    let primary_source = nodes.last().cloned();
86
87    CitationChain {
88        nodes,
89        mutations,
90        trust_cascade,
91        primary_source,
92    }
93}
94
95// ─── Mutation detection ───────────────────────────────────────────────────────
96
97/// Detect mutations between adjacent nodes using bigram-Jaccard similarity.
98pub fn detect_mutations(nodes: &[GenealogyNode]) -> Vec<Mutation> {
99    let mut mutations = Vec::new();
100
101    for i in 0..nodes.len().saturating_sub(1) {
102        let from = &nodes[i];
103        let to = &nodes[i + 1];
104
105        let similarity = string_similarity(
106            &from.claim_text.to_lowercase(),
107            &to.claim_text.to_lowercase(),
108        );
109
110        // Only flag when similarity drops below 0.95.
111        if similarity < 0.95 {
112            let severity = if similarity < 0.5 {
113                MutationSeverity::High
114            } else if similarity < 0.8 {
115                MutationSeverity::Medium
116            } else {
117                MutationSeverity::Low
118            };
119
120            let description = describe_mutation(similarity, &severity);
121
122            mutations.push(Mutation {
123                from_depth: from.depth,
124                to_depth: to.depth,
125                // "from" is closer to origin; "to" is the citing version.
126                original_claim: from.claim_text.clone(),
127                mutated_claim: to.claim_text.clone(),
128                similarity,
129                severity,
130                description,
131            });
132        }
133    }
134
135    mutations
136}
137
138fn describe_mutation(similarity: f64, severity: &MutationSeverity) -> String {
139    match severity {
140        MutationSeverity::Low => format!(
141            "Minor phrasing change ({:.0}% similar) — meaning likely preserved.",
142            similarity * 100.0
143        ),
144        MutationSeverity::Medium => format!(
145            "Significant rewording ({:.0}% similar) — verify meaning is unchanged.",
146            similarity * 100.0
147        ),
148        MutationSeverity::High => format!(
149            "Claim substantially altered ({:.0}% similar) — original meaning may be lost.",
150            similarity * 100.0
151        ),
152    }
153}
154
155// ─── Display helpers ──────────────────────────────────────────────────────────
156
157impl CitationChain {
158    /// Markdown-formatted genealogy summary.
159    pub fn to_markdown(&self) -> String {
160        let mut out = String::new();
161        out.push_str("## Citation Chain\n\n");
162
163        for node in &self.nodes {
164            out.push_str(&format!(
165                "{}. **{}** (trust: {:.0}%)\n   - URL: {}\n   - Claim: \"{}\"\n\n",
166                node.depth + 1,
167                node.title,
168                node.trust_score * 100.0,
169                node.url,
170                node.claim_text,
171            ));
172        }
173
174        if !self.mutations.is_empty() {
175            out.push_str("### Mutations Detected\n\n");
176            for m in &self.mutations {
177                out.push_str(&format!(
178                    "- **{:?}** mutation (depth {} → {}): {}\n",
179                    m.severity, m.from_depth, m.to_depth, m.description
180                ));
181            }
182        }
183
184        if let Some(primary) = &self.primary_source {
185            out.push_str(&format!(
186                "\n**Primary Source**: {} ({})\n",
187                primary.title, primary.url
188            ));
189        }
190
191        out
192    }
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198
199    fn make_chain(hops: &[(&str, &str, &str)]) -> CitationChain {
200        build_chain(
201            hops.iter()
202                .map(|(u, t, c)| (u.to_string(), t.to_string(), c.to_string()))
203                .collect(),
204        )
205    }
206
207    #[test]
208    fn trust_degrades_per_hop() {
209        let chain = make_chain(&[
210            ("https://original.com", "Original", "Rust is memory safe"),
211            ("https://blog.com", "Blog", "Rust is memory safe"),
212            ("https://tweet.com", "Tweet", "Rust is memory safe"),
213        ]);
214        assert!(chain.trust_cascade[0] > chain.trust_cascade[1]);
215        assert!(chain.trust_cascade[1] > chain.trust_cascade[2]);
216    }
217
218    #[test]
219    fn identical_claims_have_no_mutations() {
220        let chain = make_chain(&[
221            ("https://a.com", "A", "Rust is fast"),
222            ("https://b.com", "B", "Rust is fast"),
223        ]);
224        assert!(chain.mutations.is_empty());
225    }
226
227    #[test]
228    fn substantially_different_claims_are_high_severity() {
229        let chain = make_chain(&[
230            (
231                "https://a.com",
232                "A",
233                "Rust provides memory safety without garbage collection",
234            ),
235            (
236                "https://b.com",
237                "B",
238                "Python is an interpreted scripting language for data science",
239            ),
240        ]);
241        let high = chain
242            .mutations
243            .iter()
244            .any(|m| m.severity == MutationSeverity::High);
245        assert!(high, "expected high-severity mutation");
246    }
247
248    #[test]
249    fn primary_source_is_last_node() {
250        let chain = make_chain(&[
251            ("https://origin.com", "Origin", "claim"),
252            ("https://cite.com", "Cite", "claim slightly modified"),
253        ]);
254        let ps = chain.primary_source.as_ref().unwrap();
255        assert_eq!(ps.url, "https://cite.com");
256    }
257
258    #[test]
259    fn markdown_output_not_empty() {
260        let chain = make_chain(&[
261            ("https://a.com", "A", "test claim"),
262            ("https://b.com", "B", "slightly changed claim"),
263        ]);
264        let md = chain.to_markdown();
265        assert!(md.contains("Citation Chain"), "md={md}");
266    }
267}