Skip to main content

reflex/pulse/write/
gate.rs

1//! The grounding gate: deterministic checks on every LLM sentence.
2//!
3//! A sentence survives only if:
4//! 1. it cites at least one fact of its pack;
5//! 2. every code-shaped mention (backticks, `snake_case`, `CamelCase`, paths, flags)
6//!    names something the index knows, and a *cited* fact names it too;
7//! 3. every number of two or more digits appears in a cited fact;
8//! 4. every capability phrase ("HTTP server", "terminal UI", "database", …) is backed
9//!    by a cited capability fact, or a cited document that says it.
10//!
11//! A paragraph that loses more than half its sentences is dropped; a section that
12//! keeps less than [`GateConfig::min_kept_ratio`] of its sentences, or fewer than
13//! `min_sentences`, is rejected and renders its structural fallback. The gate runs on
14//! every render, cache hits included, so a renamed symbol cannot leave stale prose.
15
16use super::contract::Contract;
17use crate::pulse::model::evidence::{EvidenceKind, EvidencePack};
18use serde::Serialize;
19use std::collections::HashSet;
20use std::sync::LazyLock;
21
22#[derive(Debug, Clone, Copy)]
23pub struct GateConfig {
24    pub min_kept_ratio: f32,
25    pub min_sentences: usize,
26}
27
28impl Default for GateConfig {
29    fn default() -> Self {
30        Self {
31            min_kept_ratio: 0.6,
32            min_sentences: 2,
33        }
34    }
35}
36
37#[derive(Debug, Clone, PartialEq, Serialize)]
38#[serde(tag = "reason", content = "detail", rename_all = "kebab-case")]
39pub enum DropReason {
40    Uncited,
41    /// A code mention the index does not know: invented.
42    UnresolvedIdentifier(String),
43    /// A real name the cited facts do not mention: unsupported.
44    UngroundedIdentifier(String),
45    NumberMismatch(String),
46    UnsupportedClaim(String),
47}
48
49#[derive(Debug, Clone, PartialEq, Serialize)]
50pub struct KeptSentence {
51    pub text: String,
52    /// Indices into the pack.
53    pub cites: Vec<usize>,
54}
55
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
57#[serde(rename_all = "kebab-case")]
58pub enum Confidence {
59    High,
60    Medium,
61    Low,
62}
63
64#[derive(Debug, Clone, Default, PartialEq, Serialize)]
65pub struct GateReport {
66    pub slot: String,
67    pub total: usize,
68    pub kept: usize,
69    pub dropped: Vec<(String, DropReason)>,
70    /// Why the whole section fell back, if it did.
71    pub rejected: Option<String>,
72}
73
74#[derive(Debug, Clone, PartialEq)]
75pub struct Verified {
76    pub paragraphs: Vec<Vec<KeptSentence>>,
77    pub confidence: Confidence,
78    pub report: GateReport,
79}
80
81/// Every name the index knows: symbol names and paths, module paths, file paths,
82/// commands. A code mention outside this set was invented.
83#[derive(Debug, Clone, Default)]
84pub struct KnownNames {
85    names: HashSet<String>,
86}
87
88impl KnownNames {
89    pub fn insert(&mut self, name: &str) {
90        let n = name.trim();
91        if n.is_empty() {
92            return;
93        }
94        self.names.insert(n.to_string());
95        // `a::b::C` is also known as `C` and `b::C`; `src/x/y.rs` also as `y.rs`.
96        for sep in ["::", ".", "/"] {
97            let parts: Vec<&str> = n.split(sep).collect();
98            for i in 1..parts.len() {
99                self.names.insert(parts[i..].join(sep));
100            }
101        }
102    }
103
104    pub fn contains(&self, m: &str) -> bool {
105        let m = m.trim_end_matches("()").trim_end_matches('!');
106        self.names.contains(m)
107            || m.rsplit("::")
108                .next()
109                .is_some_and(|last| self.names.contains(last))
110    }
111}
112
113/// Words that look like code but are ordinary names.
114const PROSE_WORDS: &[&str] = &[
115    "TypeScript",
116    "JavaScript",
117    "GitHub",
118    "GitLab",
119    "PostgreSQL",
120    "MySQL",
121    "SQLite",
122    "WebSocket",
123    "OpenAI",
124    "OpenRouter",
125    "LLMs",
126    "APIs",
127    "JSON",
128    "YAML",
129    "TOML",
130    "HTTP",
131    "HTTPS",
132    "MCP",
133    "CLI",
134    "TUI",
135    "AST",
136    "IDE",
137    "macOS",
138    "iOS",
139    "NodeJS",
140    "README",
141    "CHANGELOG",
142    "e.g",
143    "i.e",
144    "etc",
145];
146
147static BACKTICK: LazyLock<regex::Regex> =
148    LazyLock::new(|| regex::Regex::new(r"`([^`]+)`").expect("valid regex"));
149static CODEISH: LazyLock<regex::Regex> = LazyLock::new(|| {
150    regex::Regex::new(
151        r"(?x)
152        (--[a-z][a-z0-9-]+)                              # --flag
153      | ([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)+) # a::b
154      | ([a-z0-9_]+_[a-z0-9_]+)                          # snake_case
155      | ([A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+)              # CamelCase
156      | ((?:[\w.-]+/)+[\w.-]+\.[a-z]{1,5})               # path/to/file.ext
157    ",
158    )
159    .expect("valid regex")
160});
161static NUMBER: LazyLock<regex::Regex> =
162    LazyLock::new(|| regex::Regex::new(r"\b\d[\d,]*(?:\.\d+)?\b").expect("valid regex"));
163
164/// (phrase pattern, capability id) for claims that need evidence.
165static CLAIMS: LazyLock<Vec<(regex::Regex, &'static str)>> = LazyLock::new(|| {
166    [
167        (r"(?i)\b(http|web|rest|api)\s+server\b|\bhttp api\b|\bweb (app|application|service)\b|\bendpoints?\b", "http-server"),
168        (r"(?i)\bterminal (ui|user interface)\b|\btui\b|\binteractive terminal\b", "tui"),
169        (r"(?i)\bdatabases?\b|\bsqlite\b|\bsql\b", "database"),
170        (r"(?i)\bllms?\b|\blanguage models?\b|\bai providers?\b", "llm"),
171        (r"(?i)\bfile[- ]watch(er|ing)\b|\bwatches (files|the file ?system)\b", "file-watching"),
172        (r"(?i)\bweb (ui|user interface|frontend)\b", "web-ui"),
173    ]
174    .into_iter()
175    .map(|(p, c)| (regex::Regex::new(p).expect("valid regex"), c))
176    .collect()
177});
178
179fn mentions(text: &str) -> Vec<String> {
180    let mut out: Vec<String> = BACKTICK
181        .captures_iter(text)
182        .map(|c| c[1].trim().to_string())
183        .collect();
184    let outside = BACKTICK.replace_all(text, " ");
185    for c in CODEISH.captures_iter(&outside) {
186        let m = c.get(0).unwrap().as_str().trim_end_matches('.');
187        if !PROSE_WORDS.contains(&m) {
188            out.push(m.to_string());
189        }
190    }
191    out.retain(|m| !m.is_empty() && !PROSE_WORDS.contains(&m.as_str()));
192    out
193}
194
195fn norm_number(s: &str) -> String {
196    s.replace(',', "")
197}
198
199fn fact_text(e: &crate::pulse::model::evidence::Evidence) -> String {
200    format!("{}\n{}\n{}", e.subject, e.text, e.names.join("\n"))
201}
202
203/// A code mention that a cited fact does not name but another fact of the pack does
204/// is grounded by that fact: add it to the cites (the sentence then shows it as a
205/// source) instead of dropping the sentence. Returns the extra cites.
206fn extra_cites(text: &str, cites: &[usize], pack: &EvidencePack) -> Vec<usize> {
207    let cited_text: String = cites
208        .iter()
209        .filter_map(|&i| pack.items.get(i))
210        .map(fact_text)
211        .collect::<Vec<_>>()
212        .join("\n");
213    let mut extra = Vec::new();
214    for m in mentions(text) {
215        if cited_text.contains(&m) {
216            continue;
217        }
218        if let Some(i) = pack
219            .items
220            .iter()
221            .position(|e| e.names.iter().any(|n| n == &m) || e.subject == m)
222            && !cites.contains(&i)
223            && !extra.contains(&i)
224        {
225            extra.push(i);
226        }
227    }
228    extra
229}
230
231/// Check one sentence against its cited facts.
232fn check(
233    text: &str,
234    cites: &[usize],
235    pack: &EvidencePack,
236    known: &KnownNames,
237) -> Option<DropReason> {
238    if cites.is_empty() {
239        return Some(DropReason::Uncited);
240    }
241    let cited: Vec<_> = cites.iter().filter_map(|&i| pack.items.get(i)).collect();
242    let cited_text: String = cited
243        .iter()
244        .map(|e| format!("{}\n{}\n{}", e.subject, e.text, e.names.join("\n")))
245        .collect::<Vec<_>>()
246        .join("\n");
247
248    for m in mentions(text) {
249        // A mention with spaces is prose in backticks (a command line); check its first word.
250        let head = m.split_whitespace().next().unwrap_or(&m).to_string();
251        if !known.contains(&m) && !known.contains(&head) && !cited_text.contains(&m) {
252            return Some(DropReason::UnresolvedIdentifier(m));
253        }
254        let grounded = cited_text.contains(&m)
255            || cited_text.contains(&head)
256            || m.rsplit("::")
257                .next()
258                .is_some_and(|last| cited_text.contains(last))
259            || m.rsplit('/')
260                .next()
261                .is_some_and(|last| cited_text.contains(last));
262        if !grounded {
263            return Some(DropReason::UngroundedIdentifier(m));
264        }
265    }
266
267    let cited_numbers: HashSet<String> = NUMBER
268        .find_iter(&cited_text)
269        .map(|n| norm_number(n.as_str()))
270        .collect();
271    for n in NUMBER.find_iter(&BACKTICK.replace_all(text, " ")) {
272        let v = norm_number(n.as_str());
273        if v.len() >= 2 && !cited_numbers.contains(&v) {
274            return Some(DropReason::NumberMismatch(n.as_str().to_string()));
275        }
276    }
277
278    for (re, cap) in CLAIMS.iter() {
279        if let Some(m) = re.find(text) {
280            let phrase = m.as_str().to_ascii_lowercase();
281            let backed = cited.iter().any(|e| {
282                e.capability.as_deref() == Some(*cap)
283                    || (matches!(
284                        e.kind,
285                        EvidenceKind::DocSection
286                            | EvidenceKind::ModuleDoc
287                            | EvidenceKind::Item
288                            | EvidenceKind::Command
289                    ) && e.text.to_ascii_lowercase().contains(&phrase))
290            });
291            if !backed {
292                return Some(DropReason::UnsupportedClaim(m.as_str().to_string()));
293            }
294        }
295    }
296    None
297}
298
299/// Split model sentences that hold several real sentences; each piece keeps the cites.
300fn split_sentences(text: &str) -> Vec<String> {
301    let mut out = Vec::new();
302    let mut cur = String::new();
303    let mut in_tick = false;
304    let chars: Vec<char> = text.chars().collect();
305    for (i, &c) in chars.iter().enumerate() {
306        cur.push(c);
307        if c == '`' {
308            in_tick = !in_tick;
309        }
310        let end = matches!(c, '.' | '!' | '?')
311            && !in_tick
312            && chars.get(i + 1) == Some(&' ')
313            && chars.get(i + 2).is_some_and(|n| n.is_uppercase());
314        if end {
315            out.push(cur.trim().to_string());
316            cur.clear();
317        }
318    }
319    if !cur.trim().is_empty() {
320        out.push(cur.trim().to_string());
321    }
322    out
323}
324
325/// Verify a parsed contract. `Err` means the section falls back to structure.
326pub fn verify(
327    contract: &Contract,
328    pack: &EvidencePack,
329    known: &KnownNames,
330    cfg: &GateConfig,
331) -> Result<Verified, GateReport> {
332    let mut report = GateReport {
333        slot: pack.slot.clone(),
334        ..GateReport::default()
335    };
336    if contract.status != "ok" {
337        report.rejected = Some(format!(
338            "insufficient evidence: {}",
339            contract.missing.join("; ")
340        ));
341        return Err(report);
342    }
343    let mut paragraphs = Vec::new();
344    for p in &contract.paragraphs {
345        let mut kept = Vec::new();
346        let mut total = 0;
347        for s in &p.sentences {
348            let cites: Vec<usize> = s
349                .cite
350                .iter()
351                .filter_map(|h| {
352                    let n: usize = h.trim().trim_start_matches('F').parse().ok()?;
353                    (n >= 1 && n <= pack.items.len()).then_some(n - 1)
354                })
355                .take(3)
356                .collect();
357            for piece in split_sentences(&s.text) {
358                total += 1;
359                report.total += 1;
360                let mut cites = cites.clone();
361                if !cites.is_empty() {
362                    cites.extend(extra_cites(&piece, &cites, pack));
363                }
364                match check(&piece, &cites, pack, known) {
365                    None => kept.push(KeptSentence { text: piece, cites }),
366                    Some(r) => report.dropped.push((piece, r)),
367                }
368            }
369        }
370        if total > 0 && kept.len() * 2 >= total {
371            report.kept += kept.len();
372            paragraphs.push(kept);
373        } else {
374            // Drop the whole paragraph; its survivors read badly alone.
375            for k in kept {
376                report.dropped.push((k.text, DropReason::Uncited));
377            }
378        }
379    }
380    let ratio = if report.total == 0 {
381        0.0
382    } else {
383        report.kept as f32 / report.total as f32
384    };
385    if report.kept < cfg.min_sentences || ratio < cfg.min_kept_ratio {
386        report.rejected = Some(format!(
387            "kept {} of {} sentences (need {} and {:.0}%)",
388            report.kept,
389            report.total,
390            cfg.min_sentences,
391            cfg.min_kept_ratio * 100.0
392        ));
393        return Err(report);
394    }
395    let g = pack.groundability();
396    let confidence = if ratio >= 0.9 && g >= 0.5 {
397        Confidence::High
398    } else if ratio < 0.75 || g < 0.3 {
399        Confidence::Low
400    } else {
401        Confidence::Medium
402    };
403    Ok(Verified {
404        paragraphs,
405        confidence,
406        report,
407    })
408}
409
410#[cfg(test)]
411mod tests {
412    use super::*;
413    use crate::pulse::model::evidence::Evidence;
414    use crate::pulse::write::contract::{Paragraph, Sentence};
415
416    fn ev(kind: EvidenceKind, text: &str, names: &[&str], cap: Option<&str>) -> Evidence {
417        Evidence {
418            id: text.into(),
419            kind,
420            subject: "src/interactive".into(),
421            text: text.into(),
422            names: names.iter().map(|s| s.to_string()).collect(),
423            source: None,
424            capability: cap.map(str::to_string),
425        }
426    }
427
428    fn pack() -> EvidencePack {
429        let mut p = EvidencePack::new("module:src/interactive", "the module src/interactive");
430        p.push(ev(EvidenceKind::Metric, "files=12 lines=4,210", &[], None));
431        p.push(ev(
432            EvidenceKind::Capability,
433            "terminal user interface (imports `ratatui` in src/interactive/app.rs:5)",
434            &["ratatui"],
435            Some("tui"),
436        ));
437        p.push(ev(
438            EvidenceKind::Item,
439            "pub struct InteractiveApp — Interactive search session state",
440            &["InteractiveApp"],
441            None,
442        ));
443        p
444    }
445
446    fn known() -> KnownNames {
447        let mut k = KnownNames::default();
448        for n in [
449            "reflex::interactive::InteractiveApp",
450            "src/interactive",
451            "src/interactive/app.rs",
452            "ratatui",
453            "reflex::cache::CacheManager",
454        ] {
455            k.insert(n);
456        }
457        k
458    }
459
460    fn contract(sents: &[(&str, &[&str])]) -> Contract {
461        Contract {
462            status: "ok".into(),
463            missing: vec![],
464            paragraphs: vec![Paragraph {
465                sentences: sents
466                    .iter()
467                    .map(|(t, c)| Sentence {
468                        text: t.to_string(),
469                        cite: c.iter().map(|s| s.to_string()).collect(),
470                    })
471                    .collect(),
472            }],
473        }
474    }
475
476    fn reasons(c: &Contract) -> Vec<DropReason> {
477        match verify(
478            c,
479            &pack(),
480            &known(),
481            &GateConfig {
482                min_kept_ratio: 0.0,
483                min_sentences: 0,
484            },
485        ) {
486            Ok(v) => v.report.dropped.into_iter().map(|(_, r)| r).collect(),
487            Err(r) => r.dropped.into_iter().map(|(_, r)| r).collect(),
488        }
489    }
490
491    #[test]
492    fn grounded_sentences_pass() {
493        let c = contract(&[
494            (
495                "The module renders an interactive terminal UI with `ratatui`.",
496                &["F2"],
497            ),
498            (
499                "`InteractiveApp` holds the session state across 12 files.",
500                &["F3", "F1"],
501            ),
502        ]);
503        let v = verify(&c, &pack(), &known(), &GateConfig::default()).unwrap();
504        assert_eq!(v.report.kept, 2, "{:?}", v.report.dropped);
505    }
506
507    #[test]
508    fn the_http_server_regression_is_blocked() {
509        // The old Pulse said "src/interactive provides an HTTP server": no fact backs it.
510        let c = contract(&[("This module provides an HTTP server for search.", &["F3"])]);
511        assert_eq!(
512            reasons(&c),
513            vec![DropReason::UnsupportedClaim("HTTP server".into())]
514        );
515    }
516
517    #[test]
518    fn each_drop_reason() {
519        assert_eq!(
520            reasons(&contract(&[("It renders things.", &[])])),
521            vec![DropReason::Uncited]
522        );
523        assert_eq!(
524            reasons(&contract(&[("It uses `FooBarBaz` internally.", &["F3"])])),
525            vec![DropReason::UnresolvedIdentifier("FooBarBaz".into())]
526        );
527        assert_eq!(
528            reasons(&contract(&[(
529                "It wraps `CacheManager` for storage.",
530                &["F3"]
531            )])),
532            vec![DropReason::UngroundedIdentifier("CacheManager".into())]
533        );
534        assert_eq!(
535            reasons(&contract(&[("It spans 40 files.", &["F1"])])),
536            vec![DropReason::NumberMismatch("40".into())]
537        );
538        assert_eq!(
539            reasons(&contract(&[("It has 4210 lines.", &["F1"])])).len(),
540            0,
541            "4,210 and 4210 are the same number"
542        );
543    }
544
545    #[test]
546    fn a_name_from_another_fact_of_the_pack_is_cited_automatically() {
547        // The sentence cites only the metric, but `InteractiveApp` is named by F3.
548        let c = contract(&[(
549            "`InteractiveApp` holds the session state across 12 files.",
550            &["F1"],
551        )]);
552        let v = verify(
553            &c,
554            &pack(),
555            &known(),
556            &GateConfig {
557                min_kept_ratio: 0.0,
558                min_sentences: 0,
559            },
560        )
561        .unwrap();
562        assert_eq!(v.report.kept, 1, "{:?}", v.report.dropped);
563        assert_eq!(v.paragraphs[0][0].cites, vec![0, 2]);
564    }
565
566    #[test]
567    fn bad_sections_are_rejected() {
568        let c = contract(&[
569            ("It uses `Nope`.", &["F3"]),
570            ("It spans 99 files.", &["F1"]),
571        ]);
572        let r = verify(&c, &pack(), &known(), &GateConfig::default()).unwrap_err();
573        assert!(r.rejected.is_some());
574        let insufficient = Contract {
575            status: "insufficient_evidence".into(),
576            missing: vec!["what the module does".into()],
577            paragraphs: vec![],
578        };
579        let r = verify(&insufficient, &pack(), &known(), &GateConfig::default()).unwrap_err();
580        assert!(r.rejected.unwrap().contains("what the module does"));
581    }
582
583    #[test]
584    fn run_on_sentences_are_split() {
585        assert_eq!(
586            split_sentences("It parses code. It caches symbols in `a.b`. Done"),
587            vec!["It parses code.", "It caches symbols in `a.b`.", "Done"]
588        );
589    }
590
591    #[test]
592    fn mentions_find_code_shapes() {
593        let m = mentions(
594            "Run `rfx index` with --force; see src/cache.rs and the QueryEngine or query_engine, not TypeScript.",
595        );
596        assert!(m.contains(&"rfx index".to_string()));
597        assert!(m.contains(&"--force".to_string()));
598        assert!(m.contains(&"src/cache.rs".to_string()));
599        assert!(m.contains(&"QueryEngine".to_string()));
600        assert!(m.contains(&"query_engine".to_string()));
601        assert!(!m.contains(&"TypeScript".to_string()));
602    }
603}