Skip to main content

fetchium_core/validate/
temporal.rs

1//! V3 Temporal/freshness validation — exponential decay scoring (PRD §19, §21).
2
3use crate::validate::types::*;
4use chrono::{DateTime, Datelike, TimeZone, Utc};
5
6/// Query temporal intent.
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8pub enum TemporalIntent {
9    Recent,
10    Historical,
11    Default,
12}
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15struct TemporalQueryProfile {
16    intent: TemporalIntent,
17    explicit_year: Option<i32>,
18}
19
20/// Freshness metadata for a single source.
21#[derive(Debug, Clone)]
22pub struct SourceFreshness {
23    pub url: String,
24    pub published_date: Option<DateTime<Utc>>,
25    pub last_modified: Option<DateTime<Utc>>,
26}
27
28/// V3 Temporal Validator.
29pub struct TemporalValidator {
30    pub default_max_age_days: u64,
31    pub recent_max_age_days: u64,
32    pub historical_max_age_days: u64,
33}
34
35impl Default for TemporalValidator {
36    fn default() -> Self {
37        Self {
38            default_max_age_days: 365,
39            recent_max_age_days: 30,
40            historical_max_age_days: 3650,
41        }
42    }
43}
44
45impl TemporalValidator {
46    /// Classify query temporal intent from keywords.
47    pub fn classify_intent(query: &str) -> TemporalIntent {
48        Self::analyze_query(query).intent
49    }
50
51    fn analyze_query(query: &str) -> TemporalQueryProfile {
52        let q = query.to_lowercase();
53        if [
54            "latest",
55            "newest",
56            "recent",
57            "current",
58            "today",
59            "yesterday",
60            "tonight",
61            "this week",
62            "this month",
63            "this quarter",
64            "this year",
65            "as of",
66            "breaking",
67            "just announced",
68            "just released",
69        ]
70        .iter()
71        .any(|s| q.contains(s))
72        {
73            return TemporalQueryProfile {
74                intent: TemporalIntent::Recent,
75                explicit_year: extract_explicit_year(&q),
76            };
77        }
78
79        let explicit_year = extract_explicit_year(&q);
80        if let Some(year) = explicit_year {
81            let current_year = Utc::now().year();
82            let intent = if year >= current_year - 1 {
83                TemporalIntent::Recent
84            } else {
85                TemporalIntent::Historical
86            };
87            return TemporalQueryProfile {
88                intent,
89                explicit_year: Some(year),
90            };
91        }
92
93        if [
94            "history of",
95            "origin of",
96            "when was",
97            "first",
98            "originally",
99            "founded",
100        ]
101        .iter()
102        .any(|s| q.contains(s))
103        {
104            return TemporalQueryProfile {
105                intent: TemporalIntent::Historical,
106                explicit_year: None,
107            };
108        }
109
110        TemporalQueryProfile {
111            intent: TemporalIntent::Default,
112            explicit_year: None,
113        }
114    }
115
116    fn max_age_days(&self, profile: TemporalQueryProfile, now: DateTime<Utc>) -> u64 {
117        if profile.intent == TemporalIntent::Recent {
118            return self.recent_max_age_days;
119        }
120
121        if let Some(year) = profile.explicit_year {
122            if year > now.year() {
123                return 30;
124            }
125            if let Some(start_of_year) = Utc.with_ymd_and_hms(year, 1, 1, 0, 0, 0).single() {
126                let days_since_year_start = (now - start_of_year).num_days().max(0) as u64;
127                let floor = match profile.intent {
128                    TemporalIntent::Historical => 365,
129                    TemporalIntent::Default => self.default_max_age_days,
130                    TemporalIntent::Recent => self.recent_max_age_days,
131                };
132                return (days_since_year_start + 366).max(floor);
133            }
134        }
135
136        match profile.intent {
137            TemporalIntent::Recent => self.recent_max_age_days,
138            TemporalIntent::Historical => self.historical_max_age_days,
139            TemporalIntent::Default => self.default_max_age_days,
140        }
141    }
142
143    fn source_matches_explicit_year(date: DateTime<Utc>, year: i32) -> bool {
144        date.year() == year
145    }
146
147    /// Validate freshness of sources against query intent.
148    pub fn validate(&self, sources: &[SourceFreshness], query: &str) -> LayerResult {
149        let start = std::time::Instant::now();
150        let now = Utc::now();
151        let profile = Self::analyze_query(query);
152        let max_age = self.max_age_days(profile, now);
153
154        let mut issues = Vec::new();
155        let mut scores = Vec::new();
156
157        for s in sources {
158            let best = s.published_date.or(s.last_modified);
159            match best {
160                Some(date) => {
161                    if date > now {
162                        scores.push(0.0);
163                        issues.push(ValidationIssue {
164                            severity: IssueSeverity::Error,
165                            code: "V3_FUTURE_DATE".into(),
166                            message: format!(
167                                "Source timestamp is in the future: {}",
168                                date.date_naive()
169                            ),
170                            source_url: Some(s.url.clone()),
171                        });
172                        continue;
173                    }
174
175                    let age = (now - date).num_days().max(0) as u64;
176                    let mut score = (-2.0 * age as f64 / max_age as f64).exp();
177
178                    if let Some(year) = profile.explicit_year {
179                        if !Self::source_matches_explicit_year(date, year) {
180                            score *= 0.25;
181                            issues.push(ValidationIssue {
182                                severity: if profile.intent == TemporalIntent::Recent {
183                                    IssueSeverity::Error
184                                } else {
185                                    IssueSeverity::Warning
186                                },
187                                code: "V3_YEAR_MISMATCH".into(),
188                                message: format!(
189                                    "Source dated {} but query targets year {}",
190                                    date.year(),
191                                    year
192                                ),
193                                source_url: Some(s.url.clone()),
194                            });
195                        }
196                    }
197
198                    let edf = crate::intelligence::edf::EvidenceDecayFunction::new();
199                    let edf_result = edf.decay(score, "technology", age as f64);
200                    score = edf_result.decayed_confidence;
201
202                    scores.push(score);
203                    if age > max_age {
204                        issues.push(ValidationIssue {
205                            severity: if age > max_age * 2 {
206                                IssueSeverity::Error
207                            } else {
208                                IssueSeverity::Warning
209                            },
210                            code: "V3_STALE_CONTENT".into(),
211                            message: format!(
212                                "{} days old (max {} for {:?})",
213                                age, max_age, profile.intent
214                            ),
215                            source_url: Some(s.url.clone()),
216                        });
217                    }
218                }
219                None => {
220                    scores.push(0.3);
221                    issues.push(ValidationIssue {
222                        severity: IssueSeverity::Warning,
223                        code: "V3_NO_DATE".into(),
224                        message: "No published date found".into(),
225                        source_url: Some(s.url.clone()),
226                    });
227                }
228            }
229        }
230
231        let avg = if scores.is_empty() {
232            0.5
233        } else {
234            scores.iter().sum::<f64>() / scores.len() as f64
235        };
236
237        LayerResult {
238            layer: ValidationLayerId::V3Freshness,
239            passed: avg >= 0.3
240                && !issues
241                    .iter()
242                    .any(|issue| issue.severity == IssueSeverity::Error),
243            score: avg,
244            issues,
245            duration_ms: start.elapsed().as_millis() as u64,
246        }
247    }
248}
249
250fn extract_explicit_year(query: &str) -> Option<i32> {
251    query.split(|c: char| !c.is_ascii_digit()).find_map(|part| {
252        if part.len() == 4 {
253            part.parse::<i32>()
254                .ok()
255                .filter(|year| (1900..=2100).contains(year))
256        } else {
257            None
258        }
259    })
260}
261
262#[cfg(test)]
263#[allow(unused_imports)]
264mod tests {
265    use super::*;
266    use chrono::Duration;
267
268    #[test]
269    fn fresh_content_passes() {
270        let v = TemporalValidator::default();
271        let r = v.validate(
272            &[SourceFreshness {
273                url: "https://x.com".into(),
274                published_date: Some(Utc::now() - Duration::days(5)),
275                last_modified: None,
276            }],
277            "what is Rust",
278        );
279        assert!(r.passed);
280        assert!(r.score > 0.9);
281    }
282
283    #[test]
284    fn stale_for_recent_query() {
285        let v = TemporalValidator::default();
286        let r = v.validate(
287            &[SourceFreshness {
288                url: "https://x.com".into(),
289                published_date: Some(Utc::now() - Duration::days(90)),
290                last_modified: None,
291            }],
292            "latest Rust news 2026",
293        );
294        assert!(r.issues.iter().any(|i| i.code == "V3_STALE_CONTENT"));
295    }
296
297    #[test]
298    fn undated_penalized() {
299        let v = TemporalValidator::default();
300        let r = v.validate(
301            &[SourceFreshness {
302                url: "https://x.com".into(),
303                published_date: None,
304                last_modified: None,
305            }],
306            "what is Rust",
307        );
308        assert!(r.issues.iter().any(|i| i.code == "V3_NO_DATE"));
309        assert!((r.score - 0.3).abs() < 1e-9);
310    }
311
312    #[test]
313    fn intent_classification() {
314        assert_eq!(
315            TemporalValidator::classify_intent("latest news"),
316            TemporalIntent::Recent
317        );
318        assert_eq!(
319            TemporalValidator::classify_intent("history of Rust"),
320            TemporalIntent::Historical
321        );
322        assert_eq!(
323            TemporalValidator::classify_intent("what is Rust"),
324            TemporalIntent::Default
325        );
326    }
327
328    #[test]
329    fn detects_relative_date_queries_as_recent() {
330        assert_eq!(
331            TemporalValidator::classify_intent("current interest rates today"),
332            TemporalIntent::Recent
333        );
334        assert_eq!(
335            TemporalValidator::classify_intent("Q1 2026 earnings"),
336            TemporalIntent::Recent
337        );
338    }
339
340    #[test]
341    fn future_dated_source_fails_closed() {
342        let v = TemporalValidator::default();
343        let r = v.validate(
344            &[SourceFreshness {
345                url: "https://x.com".into(),
346                published_date: Some(Utc::now() + Duration::days(2)),
347                last_modified: None,
348            }],
349            "latest security advisory",
350        );
351        assert!(!r.passed);
352        assert!(r.issues.iter().any(|i| i.code == "V3_FUTURE_DATE"));
353    }
354
355    #[test]
356    fn explicit_year_mismatch_is_flagged() {
357        let v = TemporalValidator::default();
358        let r = v.validate(
359            &[SourceFreshness {
360                url: "https://x.com".into(),
361                published_date: Some(Utc.with_ymd_and_hms(2025, 6, 1, 0, 0, 0).single().unwrap()),
362                last_modified: None,
363            }],
364            "best ETFs for 2024",
365        );
366        assert!(r.issues.iter().any(|i| i.code == "V3_YEAR_MISMATCH"));
367    }
368}