Skip to main content

provable_contracts/lint/
refinement_gate.rs

1//! ONT-001 ONT-3b (#4073) — the `refinement` gate: every `models:` entry in `formalization.yaml` names a Rust item
2//! the workspace resolves (through ONT-3a's `syn` walk), and two counts that must never get worse are checked HEAD
3//! against BASE in the same run, by the same scanner: the theorem-bearing Lean modules with no L4 model
4//! (`unrefined`), and the contract-bound theorems outside the root's import cone (`orphaned_roots`). See
5//! [`crate::discharge::refinement`] for what a model earns.
6//!
7//! There is no stored limit. The operator's ruling (2026-09-27, relayed by the cop): "counts that must never get
8//! worse are checked head against base, not against a number committed to the repo". BASE is
9//! merge-base(HEAD, origin/main), else the origin/main tip (`lib_baseline_ratchet.sh`'s order); its Lean tree and
10//! contracts are read out of git (`git archive`), never out of the work tree.
11//!
12//! Rules (`reject:`, exit 1):
13//!
14//! - PV-ONT-031 — a `model_of` does not resolve: a ghost formalization, named;
15//! - PV-ONT-032 — a `models:` entry is malformed (no module/model_of/evidence, unknown `relation.kind`, a module
16//!   modelled twice) or names a module outside the root's import cone;
17//! - PV-ONT-033 — a module is unrefined at HEAD and was not at BASE (a new unproven module, or one that lost its
18//!   model), named;
19//! - PV-ONT-034 — a contract-bound theorem is outside the cone at HEAD and was not at BASE (ORPHANED-ROOT), named.
20//!
21//! Declines (exit 2): no Lean tree or `formalization.yaml` beside the corpus (the fixture corpora), no BASE to
22//! compare with, or the resolver's positive control did not fire.
23
24use std::collections::{BTreeMap, BTreeSet};
25use std::path::{Path, PathBuf};
26use std::process::{Command, Stdio};
27use std::time::Instant;
28
29use serde::Serialize;
30
31use crate::discharge::{self, refinement, summary, Tree};
32use crate::ontology::extract::code::positive_control;
33use crate::ontology::verdict::Verdict;
34
35use super::finding::LintFinding;
36use super::ratchet_gates::RatchetOutcome;
37use super::rules::RuleSeverity;
38use super::{GateDetail, GateExtra, GateResult};
39
40/// The gate's name, under `--gate` and in a full run.
41pub const GATE: &str = "refinement";
42
43/// The Lean tree, relative to the corpus's parent.
44pub const LEAN_DIR: &str = "crates/aprender-contracts-staging/lean";
45
46/// How many modules or roots a finding names before it says "and N more".
47const NAMED: usize = 12;
48
49/// The counters `--gate refinement` reports, flattened into [`GateExtra::Refinement`]'s JSON.
50#[derive(Debug, Clone, Default, Serialize)]
51pub struct RefinementCounters {
52    /// Well-formed `models:` entries.
53    pub models: usize,
54    pub resolved: usize,
55    /// Models granting L4 (`extraction`/`simulation`, resolving, in the cone).
56    pub l4_models: usize,
57    /// Models granting L3 (`test_witnessed`, resolving, in the cone).
58    pub l3_models: usize,
59    /// `model_of` that does not resolve (PV-ONT-031).
60    pub ghosts: usize,
61    /// HEAD: modules in the root's import cone with at least one theorem.
62    pub theorem_modules: usize,
63    /// HEAD: of those, the ones no L4 model covers.
64    pub unrefined: usize,
65    /// HEAD: contract-bound theorems outside the cone.
66    pub orphaned_roots: usize,
67    /// What HEAD was compared with (`merge-base(HEAD, origin/main) <sha>`).
68    pub base: String,
69    pub base_theorem_modules: usize,
70    pub base_unrefined: usize,
71    /// Same measured value as `base_unrefined`, under the name the ONT-3b spec probe reads. Measured at the
72    /// merge-base in this run; never a stored count.
73    pub unrefined_baseline: usize,
74    pub base_orphaned_roots: usize,
75    /// Unrefined at HEAD, not at BASE (PV-ONT-033).
76    pub new_unrefined: usize,
77    /// Orphaned at HEAD, not at BASE (PV-ONT-034).
78    pub new_orphaned_roots: usize,
79    /// `fired` — the resolver found a present item and refused an absent one this run.
80    pub pc_resolver: String,
81    pub violations: usize,
82}
83
84/// One side (HEAD or BASE), measured from source by one scanner.
85#[derive(Debug, Clone, Default)]
86pub struct Side {
87    /// Modules in the root's import cone (paths relative to the lean dir).
88    pub cone: BTreeSet<String>,
89    /// Theorem-bearing modules in the cone, with their theorems.
90    pub theorem_modules: BTreeMap<String, Vec<String>>,
91    /// Theorem-bearing modules no L4 model covers.
92    pub unrefined: BTreeSet<String>,
93    /// Contract-bound theorems (fully qualified) whose module is outside the cone.
94    pub orphaned: BTreeSet<String>,
95    pub judged: Vec<refinement::Judged>,
96    pub malformed: Vec<String>,
97}
98
99/// Measure the tree at `lean_dir` against the contracts at `contract_dir`, with `rec`'s models. `Err` is a decline.
100pub fn measure(
101    lean_dir: &Path,
102    contract_dir: &Path,
103    rec: refinement::Record,
104    resolve: impl FnMut(&str) -> Result<(), String>,
105) -> Result<Side, String> {
106    let tree = Tree::load(lean_dir)?;
107    let modules = summary::modules(&tree);
108    let cone: BTreeSet<String> = modules.iter().map(|m| m.path.clone()).collect();
109    let theorem_modules: BTreeMap<String, Vec<String>> = modules
110        .into_iter()
111        .filter(|m| !m.theorems.is_empty())
112        .map(|m| (m.path, m.theorems))
113        .collect();
114    let judged = refinement::judge(&rec.models, &cone, resolve);
115    let l4 = refinement::l4_modules(&judged);
116    let unrefined = refinement::unrefined(&theorem_modules, &l4)
117        .into_iter()
118        .map(str::to_string)
119        .collect();
120    let cone_mods = tree.cone();
121    let orphaned = discharge::bind(&tree, contract_dir)
122        .roots
123        .into_iter()
124        .filter(|r| !cone_mods.contains(&r.module))
125        .map(|r| r.fqn)
126        .collect();
127    Ok(Side {
128        cone,
129        theorem_modules,
130        unrefined,
131        orphaned,
132        judged,
133        malformed: rec.malformed,
134    })
135}
136
137fn finding(rule: &str, msg: String) -> LintFinding {
138    LintFinding::new(
139        rule,
140        RuleSeverity::Error,
141        msg,
142        format!("{LEAN_DIR}/formalization.yaml"),
143    )
144}
145
146/// `a, b, c and N more`.
147fn named(items: &[&String]) -> String {
148    let shown: Vec<&str> = items.iter().take(NAMED).map(|s| s.as_str()).collect();
149    let rest = items.len().saturating_sub(NAMED);
150    if rest == 0 {
151        shown.join(", ")
152    } else {
153        format!("{} and {rest} more", shown.join(", "))
154    }
155}
156
157/// Run the gate over `contract_dir`: HEAD is the work tree, BASE comes out of git.
158#[must_use]
159pub fn run_refinement_gate(contract_dir: &Path) -> RatchetOutcome {
160    let root = crate::ontology::extract::repo_root(contract_dir);
161    if !root.join(LEAN_DIR).join("formalization.yaml").is_file() {
162        return RatchetOutcome::Declined(format!(
163            "no {LEAN_DIR}/formalization.yaml beside the corpus"
164        ));
165    }
166    let base = match BaseTree::extract(&root, contract_dir) {
167        Ok(b) => b,
168        Err(e) => return RatchetOutcome::Declined(format!("no BASE to compare with: {e}")),
169    };
170    run_with(
171        &root.join(LEAN_DIR),
172        contract_dir,
173        &base.lean,
174        &base.contracts,
175        &base.label,
176        refinement::workspace_resolver(&root),
177    )
178}
179
180/// The gate: HEAD's tree at `lean_dir` + `contract_dir` against BASE's at `base_lean` + `base_contracts`, one
181/// scanner and one resolver for both.
182pub fn run_with(
183    lean_dir: &Path,
184    contract_dir: &Path,
185    base_lean: &Path,
186    base_contracts: &Path,
187    base_label: &str,
188    mut resolve: impl FnMut(&str) -> Result<(), String>,
189) -> RatchetOutcome {
190    let start = Instant::now();
191    if !positive_control() {
192        return RatchetOutcome::Declined(
193            "positive control pc_resolver did not fire: the resolver cannot tell a present item from an absent one"
194                .into(),
195        );
196    }
197    let head = match load_head_side(lean_dir, contract_dir, &mut resolve) {
198        Ok(s) => s,
199        Err(e) => return RatchetOutcome::Declined(format!("HEAD: {e}")),
200    };
201    let base = match load_base_side(base_lean, base_contracts, &mut resolve) {
202        Ok(s) => s,
203        Err(e) => return RatchetOutcome::Declined(format!("BASE {base_label}: {e}")),
204    };
205
206    let mut findings: Vec<LintFinding> = head
207        .malformed
208        .iter()
209        .map(|m| finding("PV-ONT-032", m.clone()))
210        .collect();
211    let mut c = RefinementCounters {
212        models: head.judged.len(),
213        theorem_modules: head.theorem_modules.len(),
214        unrefined: head.unrefined.len(),
215        orphaned_roots: head.orphaned.len(),
216        base: base_label.to_string(),
217        base_theorem_modules: base.theorem_modules.len(),
218        base_unrefined: base.unrefined.len(),
219        unrefined_baseline: base.unrefined.len(),
220        base_orphaned_roots: base.orphaned.len(),
221        pc_resolver: crate::ontology::witness::FIRED.to_string(),
222        ..RefinementCounters::default()
223    };
224    judge_findings(&head.judged, &mut findings, &mut c);
225    diff_findings(&head, &base, base_label, &mut findings, &mut c);
226    c.violations = findings.len();
227    build_result(c, findings, start)
228}
229
230/// Load and measure HEAD's side: `Err` is a decline reason (no "HEAD:" prefix yet).
231fn load_head_side(
232    lean_dir: &Path,
233    contract_dir: &Path,
234    resolve: &mut impl FnMut(&str) -> Result<(), String>,
235) -> Result<Side, String> {
236    refinement::load(lean_dir)
237        .map_err(|e| format!("no formalization.yaml: {e}"))
238        .and_then(|rec| measure(lean_dir, contract_dir, rec, resolve))
239}
240
241/// Load and measure BASE's side. A BASE with no `formalization.yaml` yet has no models: every
242/// theorem-bearing module there is unrefined.
243fn load_base_side(
244    base_lean: &Path,
245    base_contracts: &Path,
246    resolve: &mut impl FnMut(&str) -> Result<(), String>,
247) -> Result<Side, String> {
248    let rec = if base_lean.join("formalization.yaml").exists() {
249        refinement::load(base_lean)?
250    } else {
251        refinement::Record::default()
252    };
253    measure(base_lean, base_contracts, rec, resolve)
254}
255
256/// Score each judged model into `c`'s counters, and raise PV-ONT-031/032 for ghosts and out-of-cone models.
257fn judge_findings(
258    judged: &[refinement::Judged],
259    findings: &mut Vec<LintFinding>,
260    c: &mut RefinementCounters,
261) {
262    for j in judged {
263        let m = &j.model;
264        match &j.resolved {
265            Ok(()) => c.resolved += 1,
266            Err(why) => {
267                c.ghosts += 1;
268                findings.push(finding(
269                    "PV-ONT-031",
270                    format!(
271                        "{}: model_of `{}` does not resolve (ghost formalization): {why}",
272                        m.module, m.model_of
273                    ),
274                ));
275            }
276        }
277        if !j.in_tree {
278            findings.push(finding(
279                "PV-ONT-032",
280                format!("{}: not a module in the root's import cone", m.module),
281            ));
282        }
283        match j.level() {
284            Some(4) => c.l4_models += 1,
285            Some(3) => c.l3_models += 1,
286            _ => {}
287        }
288    }
289}
290
291/// Raise PV-ONT-033/034 for anything unrefined or orphaned at HEAD that BASE did not have, and count them.
292fn diff_findings(
293    head: &Side,
294    base: &Side,
295    base_label: &str,
296    findings: &mut Vec<LintFinding>,
297    c: &mut RefinementCounters,
298) {
299    let new_unrefined: Vec<&String> = head.unrefined.difference(&base.unrefined).collect();
300    c.new_unrefined = new_unrefined.len();
301    if !new_unrefined.is_empty() {
302        findings.push(finding(
303            "PV-ONT-033",
304            format!(
305                "{} unrefined at HEAD vs {} at BASE {base_label}: {} module(s) with no L4 model that BASE did not have: {}",
306                c.unrefined,
307                c.base_unrefined,
308                new_unrefined.len(),
309                named(&new_unrefined)
310            ),
311        ));
312    }
313    let new_orphaned: Vec<&String> = head.orphaned.difference(&base.orphaned).collect();
314    c.new_orphaned_roots = new_orphaned.len();
315    if !new_orphaned.is_empty() {
316        findings.push(finding(
317            "PV-ONT-034",
318            format!(
319                "{} ORPHANED-ROOT at HEAD vs {} at BASE {base_label}: {} contract-bound theorem(s) outside the root's import cone that BASE did not have: {}",
320                c.orphaned_roots,
321                c.base_orphaned_roots,
322                new_orphaned.len(),
323                named(&new_orphaned)
324            ),
325        ));
326    }
327}
328
329/// Assemble the final [`RatchetOutcome`] from the counters and findings collected for both sides.
330fn build_result(
331    c: RefinementCounters,
332    findings: Vec<LintFinding>,
333    start: Instant,
334) -> RatchetOutcome {
335    let verdict = if findings.is_empty() {
336        Verdict::Pass
337    } else {
338        Verdict::Fail
339    };
340    let result = GateResult {
341        name: GATE.into(),
342        passed: verdict == Verdict::Pass,
343        skipped: false,
344        verdict,
345        duration_ms: u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX),
346        detail: GateDetail::Validate {
347            contracts: c.models,
348            errors: findings.len(),
349            warnings: 0,
350            error_messages: findings.iter().map(|f| f.message.clone()).collect(),
351        },
352        extra: Some(GateExtra::Refinement(Box::new(c))),
353    };
354    RatchetOutcome::Ran {
355        result: Box::new(result),
356        findings,
357    }
358}
359
360/// BASE's Lean tree and contracts, extracted from git into a scratch dir that is removed on drop.
361struct BaseTree {
362    dir: PathBuf,
363    lean: PathBuf,
364    contracts: PathBuf,
365    label: String,
366}
367
368impl BaseTree {
369    fn extract(root: &Path, contract_dir: &Path) -> Result<Self, String> {
370        let (commit, label) = default_commit(root)
371            .ok_or("neither merge-base(HEAD, origin/main) nor origin/main resolves")?;
372        let top = git(root, &["rev-parse", "--show-toplevel"]).ok_or("not a git work tree")?;
373        let top = PathBuf::from(top);
374        let rel = |p: &Path| -> Result<String, String> {
375            let abs = p
376                .canonicalize()
377                .map_err(|e| format!("{}: {e}", p.display()))?;
378            let top = top
379                .canonicalize()
380                .map_err(|e| format!("{}: {e}", top.display()))?;
381            abs.strip_prefix(&top)
382                .map(|r| r.to_string_lossy().replace('\\', "/"))
383                .map_err(|_| format!("{} is outside the work tree", abs.display()))
384        };
385        let lean_rel = rel(&root.join(LEAN_DIR))?;
386        let contracts_rel = rel(contract_dir)?;
387        let nanos = std::time::SystemTime::now()
388            .duration_since(std::time::UNIX_EPOCH)
389            .map_or(0, |d| d.as_nanos());
390        let dir =
391            std::env::temp_dir().join(format!("pv-refinement-base-{}-{nanos}", std::process::id()));
392        std::fs::create_dir_all(&dir).map_err(|e| format!("{}: {e}", dir.display()))?;
393        let me = Self {
394            lean: dir.join(&lean_rel),
395            contracts: dir.join(&contracts_rel),
396            dir,
397            label,
398        };
399        me.archive(&top, &commit, &[&lean_rel, &contracts_rel])?;
400        Ok(me)
401    }
402
403    /// `git archive <commit> -- <paths> | tar -x -C <dir>`. A path BASE does not have is not an error: that
404    /// side is then empty.
405    fn archive(&self, top: &Path, commit: &str, paths: &[&str]) -> Result<(), String> {
406        for p in paths {
407            let present = git(top, &["cat-file", "-e", &format!("{commit}:{p}")]).is_some();
408            if !present {
409                continue;
410            }
411            let mut git_archive = Command::new("git")
412                .arg("-C")
413                .arg(top)
414                .args(["archive", "--format=tar", commit, "--", p])
415                .env_remove("GIT_DIR")
416                .env_remove("GIT_WORK_TREE")
417                .env_remove("GIT_INDEX_FILE")
418                .stdout(Stdio::piped())
419                .stderr(Stdio::null())
420                .spawn()
421                .map_err(|e| format!("git archive: {e}"))?;
422            let out = git_archive.stdout.take().ok_or("git archive: no stdout")?;
423            let tar = Command::new("tar")
424                .arg("-x")
425                .arg("-C")
426                .arg(&self.dir)
427                .stdin(out)
428                .stderr(Stdio::null())
429                .status()
430                .map_err(|e| format!("tar: {e}"))?;
431            let ga = git_archive
432                .wait()
433                .map_err(|e| format!("git archive: {e}"))?;
434            if !ga.success() || !tar.success() {
435                return Err(format!("git archive {commit} -- {p} | tar -x failed"));
436            }
437        }
438        Ok(())
439    }
440}
441
442impl Drop for BaseTree {
443    fn drop(&mut self) {
444        if self
445            .dir
446            .file_name()
447            .and_then(|n| n.to_str())
448            .is_some_and(|n| n.starts_with("pv-refinement-base-"))
449        {
450            let _ = std::fs::remove_dir_all(&self.dir);
451        }
452    }
453}
454
455/// merge-base(HEAD, origin/main), else the origin/main tip — `lib_baseline_ratchet.sh`'s order.
456fn default_commit(root: &Path) -> Option<(String, String)> {
457    if let Some(commit) = git(root, &["merge-base", "HEAD", "origin/main"]) {
458        let label = format!("merge-base(HEAD, origin/main) {}", short(&commit));
459        return Some((commit, label));
460    }
461    let commit = git(
462        root,
463        &["rev-parse", "--verify", "--quiet", "origin/main^{commit}"],
464    )?;
465    let label = format!("origin/main {}", short(&commit));
466    Some((commit, label))
467}
468
469fn short(commit: &str) -> &str {
470    commit.get(..12).unwrap_or(commit)
471}
472
473fn git(dir: &Path, args: &[&str]) -> Option<String> {
474    let out = Command::new("git")
475        .arg("-C")
476        .arg(dir)
477        .args(args)
478        .env_remove("GIT_DIR")
479        .env_remove("GIT_WORK_TREE")
480        .env_remove("GIT_INDEX_FILE")
481        .stderr(Stdio::null())
482        .output()
483        .ok()?;
484    if !out.status.success() {
485        return None;
486    }
487    Some(
488        String::from_utf8_lossy(&out.stdout)
489            .trim_end_matches('\n')
490            .to_string(),
491    )
492}
493
494#[cfg(test)]
495#[path = "refinement_gate_tests.rs"]
496mod tests;