Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

87.2 KB
Raw Blame
//! Does a retrieved slice still support the claims an answer rests on?
//!
//! [`crate::projection_check`] answers "how much of the source neighbourhood
//! survived", which is not the question. A slice at 99% coverage can have
//! dropped the one triple an answer depends on, and a slice at 60% coverage can
//! preserve every conclusion that matters. Worse, the number moves the wrong
//! way: it rises as the projection grows, so a retriever tuned on it learns to
//! fetch MORE rather than to fetch the right thing, and a retrieval-augmented
//! answer grounded in such a slice can be false while every displayed metric is
//! green.
//!
//! This module asks the property instead. Let `G` be the loaded store, `P` the
//! retrieved slice and `Q` a set of ground positive triples the answer rests
//! on. For each `q` in `Q`, does `P` entail `q` exactly when `G` does, decided
//! under ONE pinned rule profile, with a machine-checked certificate for each
//! `q` the projection preserves?
//!
//! # Four cells, and they are four different answers
//!
//! | `G` derives `q` | `P` derives `q` | what it is |
//! |---|---|---|
//! | yes | yes | preserved. The only cell that can carry a certificate. |
//! | yes | no | lost by the projection. The retrieval finding. |
//! | no | yes | the projection is not a subset of the source, or OWL RL monotonicity has been violated and the engine is unsound. Never a retrieval finding. |
//! | no | no | `ungrounded_in_source`. The claim has no support in the graph at all. The fix is in the generator, not the retriever. |
//!
//! The fourth cell is where most of the real value sits, and it is why the two
//! negatives are never collapsed into "loss": a generator that invented a claim
//! and a retriever that dropped a triple have opposite fixes, and a tool that
//! reports both as "not preserved" sends every investigation to the wrong team.
//! `ungrounded_in_source` does NOT mean the claim is false. RDF entailment is
//! open-world and this engine covers 29 of OWL 2 RL's 78 rules, so it means
//! "not derivable from `G` under this profile" and nothing stronger.
//!
//! # Why membership is decided over the certificate FILES
//!
//! [`Reasoner::run_full`] is run twice with `materialize = false` and a
//! `certificate_dir`, and membership of `q` is decided by reading
//! `asserted.tsv` and `derivations.tsv` back off disk rather than by consulting
//! an in-memory closure. That is deliberate. The Lean checker only ever sees
//! those two files. If membership were decided against a set the checker never
//! reads, the engine could report "derived" over a certificate that does not
//! contain the derivation, and the verdict would be unchecked while wearing the
//! checked word. Deciding over the artefact the checker reads makes that class
//! of bug impossible rather than tested against.
//!
//! # The free differential
//!
//! OWL RL is monotone and `P` is a subset of `G`, so every entailment of `P`
//! must be an entailment of `G`. A conclusion of `P` that is not a conclusion of
//! `G` is therefore a SOUNDNESS BUG IN THE ENGINE, not a retrieval finding, and
//! it is reported as `STOP_THE_LINE`. It is worth nothing unless it is DISARMED
//! whenever its premises do not hold, and there are three such conditions, each
//! of which occurs on real input: the projection is not a subset (computed,
//! never assumed from provenance); blank nodes could not be matched; or either
//! run stopped at the iteration cap instead of a fixpoint, which makes the
//! larger closure a LOWER BOUND and manufactures spurious `P`-only entailments.
//! Disarming is reported, never silent.
//!
//! See [decision 0007](../../docs/decisions/0007-a-slice-preserves-a-conclusion-or-it-does-not.md).

use crate::graph::GraphStore;
use crate::projection_check::{check_projection_loss, ProjectionLossReport};
use crate::reason::{InferenceTarget, Reasoner};
use crate::verdict::{CheckerBinary, CheckerRun, Certified};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Arc;

/// A triple in the store's own N-Triples spelling: byte-identical to what
/// [`GraphStore::all_triples`] yields and to what `asserted.tsv` carries.
/// Every comparison in this module is over this type and never over user text.
pub type Spelled = (String, String, String);

/// RDF 1.1 section 3.5 reserves `.well-known/genid/` for skolem constants.
pub const SKOLEM_PREFIX: &str = "https://open-ontologies.org/.well-known/genid/";

/// How to get the checker, printed wherever it is missing.
pub const LAKE_INSTALL: &str =
    "install elan from https://github.com/leanprover/elan; lean/lean-toolchain pins the version, \
     then `cd lean && lake build` (oo-cert and oo-horn are in defaultTargets). Or set OO_CERT to \
     the binary.";

/// The sentence that travels with the coverage number, in the payload rather
/// than only in the docs.
pub const COVERAGE_LABEL: &str =
    "coverage_ratio is a PROXY and is neither necessary nor sufficient for entailment \
     preservation: a slice at 0.99 can have dropped the one triple an answer rests on, and a \
     slice at 0.60 can preserve every claim in this report. It also moves the wrong way, rising \
     as the projection grows, so a retriever tuned on it learns to fetch MORE rather than the \
     right thing. Read the per-goal verdicts; this number is a cheap signal and never a warrant.";

/// The severity word `src/projection_check.rs`'s neighbours use for a finding
/// that must stop a pipeline rather than be filed under "other".
pub const STOP_THE_LINE: &str = "STOP_THE_LINE";

// ───────────────────────────────────────────────────────────────────────────
// Blank nodes
// ───────────────────────────────────────────────────────────────────────────

/// True when the term is a blank node in N-Triples spelling (`_:label`).
pub fn is_blank(term: &str) -> bool {
    term.starts_with("_:")
}

fn has_blank(t: &Spelled) -> bool {
    is_blank(&t.0) || is_blank(&t.1) || is_blank(&t.2)
}

/// Replace every blank node in `g` with a Skolem IRI, returning the new store
/// beside the map that did it.
///
/// THIS IS NOT [`GraphStore::canonicalize_blank_nodes`], and reaching for that
/// instead is the trap this function exists to stop. RDFC-1.0 labels are a
/// function of the WHOLE graph: a blank node with seven triples in the source
/// and three in a slice canonicalises to two DIFFERENT labels. Canonicalising
/// both sides separately and diffing is exactly as wrong as not canonicalising
/// at all, and it looks principled, which is worse.
///
/// Skolemising the SOURCE before a retriever ever sees it is the only thing
/// that makes a re-parsed slice comparable, because the slice then carries real
/// IRIs and nothing has to be matched.
pub fn skolemise(g: &Arc<GraphStore>) -> anyhow::Result<(Arc<GraphStore>, BTreeMap<String, String>)> {
    skolemise_with_prefix(g, SKOLEM_PREFIX)
}

/// [`skolemise`] under a caller-chosen prefix.
///
/// Two graphs skolemised SEPARATELY under the same prefix can collide: the map
/// is `_:label ↦ prefix + label`, and two unrelated graphs both containing
/// `_:b0` would then agree on an IRI that names two different things. Any
/// caller that skolemises one graph and later merges another into it has to
/// keep the two apart, and a distinct prefix is the only thing that does it.
/// `_` is not a legal character-run separator in an N-Triples blank node label
/// and `/` cannot appear in one at all, so a prefix ending in `/base/` cannot
/// be produced by the default prefix over any label.
pub fn skolemise_with_prefix(
    g: &Arc<GraphStore>,
    prefix: &str,
) -> anyhow::Result<(Arc<GraphStore>, BTreeMap<String, String>)> {
    let mut map: BTreeMap<String, String> = BTreeMap::new();
    let mut nt = String::new();
    for (s, p, o) in g.all_triples()? {
        let mut one = |term: &str| -> String {
            if let Some(label) = term.strip_prefix("_:") {
                let iri = format!("<{prefix}{label}>");
                map.insert(iri.clone(), term.to_string());
                iri
            } else {
                term.to_string()
            }
        };
        let (s, p, o) = (one(&s), one(&p), one(&o));
        nt.push_str(&s);
        nt.push(' ');
        nt.push_str(&p);
        nt.push(' ');
        nt.push_str(&o);
        nt.push_str(" .\n");
    }
    let out = GraphStore::new();
    out.load_ntriples(&nt)?;
    Ok((Arc::new(out), map))
}

// ───────────────────────────────────────────────────────────────────────────
// Goals
// ───────────────────────────────────────────────────────────────────────────

/// One claim an answer rests on.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Goal {
    pub id: String,
    /// Exactly what the caller wrote, where the caller's bytes are recoverable.
    ///
    /// They are on the TSV and bindings paths. On the Turtle path the document
    /// is parsed as a whole and there is no per-triple source text to keep, so
    /// this holds the parser's rendering and equals [`Goal::triple`] by
    /// construction; the field is still printed, because the case where the two
    /// differ is the one that bites.
    pub as_written: String,
    /// What is actually asked: the spelling that came back out of the parser.
    pub triple: Spelled,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct RefusedGoal {
    pub as_written: String,
    pub reason: GoalRefusal,
    pub means: &'static str,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GoalRefusal {
    /// A blank node in a goal is an existential, not a claim. This engine asks
    /// ground triples and cannot ask "there exists something such that".
    BlankNode,
    /// "no supplier is sanctioned", "exactly one registered address". Not a
    /// triple. Mapping absence-from-the-closure onto such a claim converts an
    /// open-world absence into a closed-world fact with a certificate stapled
    /// to it, which is the laundering this tool exists to attack, produced by
    /// the anti-laundering tool.
    NotAPositiveGroundTriple,
    /// A variable, a prefix that resolves to nothing, or text the parser
    /// refused.
    Unparseable,
}

impl GoalRefusal {
    pub fn means(self) -> &'static str {
        match self {
            GoalRefusal::BlankNode => {
                "a blank node in a goal is an existential rather than a claim. This layer asks \
                 whether a GROUND triple is entailed and has no way to ask 'there exists \
                 something such that'. Skolemise the source and ask about the Skolem constant, or \
                 ask a SHACL shape instead"
            }
            GoalRefusal::NotAPositiveGroundTriple => {
                "this is a closed-world or negative claim, not a positive ground triple. Reading \
                 'absent from the closure' as 'the claim holds' would turn an open-world absence \
                 into a fact with a certificate stapled to it. A closed-world question belongs in \
                 SHACL: use onto_shacl"
            }
            GoalRefusal::Unparseable => {
                "the parser refused this. A goal has to survive the SAME parser the store uses, \
                 because that is the only thing that makes the caller's spelling of a term \
                 comparable with the interner's"
            }
        }
    }
}

/// The OWL vocabulary for writing down a NEGATIVE fact. A caller reaching for
/// it is asking a closed-world question, and the refusal says where that
/// belongs. Nothing here is a general-purpose ban on the OWL namespace: a goal
/// asking whether `A owl:equivalentClass B` is entailed is a perfectly ordinary
/// positive ground triple and is accepted.
const NEGATIVE_VOCABULARY: [&str; 5] = [
    "<http://www.w3.org/2002/07/owl#NegativePropertyAssertion>",
    "<http://www.w3.org/2002/07/owl#sourceIndividual>",
    "<http://www.w3.org/2002/07/owl#assertionProperty>",
    "<http://www.w3.org/2002/07/owl#targetIndividual>",
    "<http://www.w3.org/2002/07/owl#targetValue>",
];

/// Prefixes a caller uses when trying to write "not this" into a goal line.
const NEGATION_MARKERS: [&str; 4] = ["NOT ", "not ", "!", "\u{00ac}"];

fn classify(t: &Spelled, as_written: &str) -> Result<(), GoalRefusal> {
    if has_blank(t) {
        return Err(GoalRefusal::BlankNode);
    }
    if t.0.starts_with('"') {
        // A literal subject is not writable RDF and no rule can conclude one.
        return Err(GoalRefusal::NotAPositiveGroundTriple);
    }
    if NEGATIVE_VOCABULARY.contains(&t.1.as_str()) || NEGATIVE_VOCABULARY.contains(&t.2.as_str()) {
        return Err(GoalRefusal::NotAPositiveGroundTriple);
    }
    if NEGATION_MARKERS.iter().any(|m| as_written.starts_with(m)) {
        return Err(GoalRefusal::NotAPositiveGroundTriple);
    }
    Ok(())
}

fn refuse(as_written: &str, reason: GoalRefusal) -> RefusedGoal {
    RefusedGoal { as_written: as_written.to_string(), reason, means: reason.means() }
}

fn accept(idx: usize, as_written: String, t: Spelled) -> Goal {
    Goal { id: format!("g{idx}"), as_written, triple: t }
}

/// Parse a Turtle document in which every triple is a goal.
///
/// Prefix resolution comes from the same parser the store uses, and each goal
/// is spelled by a store round trip, so a goal's spelling is the interner's.
/// A literal is asked as written: since #335 the store keeps
/// `"01"^^xsd:integer` as `"01"`, so it matches a certificate holding `"01"`
/// and not one holding `"1"`. Those are one value and two terms, and no rule
/// or checker here compares literals by value.
pub fn parse_goals_turtle(goals_ttl: &str) -> anyhow::Result<(Vec<Goal>, Vec<RefusedGoal>)> {
    let parsed = match GraphStore::parse_triples_ordered(goals_ttl, "turtle") {
        Ok(v) => v,
        Err(e) => {
            // All or nothing: this parser collects the whole document before
            // yielding anything, so one syntax error means no goals at all.
            // Reported as a refusal rather than an error so the caller sees it
            // in the same place every other rejected goal appears.
            return Ok((
                Vec::new(),
                vec![RefusedGoal {
                    as_written: truncate(goals_ttl, 200),
                    reason: GoalRefusal::Unparseable,
                    means: Box::leak(
                        format!("{}: {e}", GoalRefusal::Unparseable.means()).into_boxed_str(),
                    ),
                }],
            ));
        }
    };
    // The parser's rendering is `as_written`; the STORE's is what is asked.
    // Until #335 they differed (the store normalised a literal's lexical
    // form); the pinned store keeps it, and the round trip stays so that the
    // two are spelled by the same code whatever the store does.
    let raw: Vec<(String, Spelled)> = parsed
        .into_iter()
        .map(|t| (format!("{} {} {}", t.0, t.1, t.2), t))
        .collect();
    canonicalise_batch(raw, Vec::new())
}

/// The `fol --goals` shape, so `derivations.tsv` pipes in with
/// `skip_columns = 1` (its first column is the rule name).
pub fn parse_goals_tsv(text: &str, skip_columns: usize) -> anyhow::Result<(Vec<Goal>, Vec<RefusedGoal>)> {
    let mut raw: Vec<(String, Spelled)> = Vec::new();
    let mut refused: Vec<RefusedGoal> = Vec::new();
    for line in text.lines() {
        if line.trim().is_empty() {
            continue;
        }
        let f: Vec<&str> = line.split('\t').collect();
        if f.len() < skip_columns + 3 {
            refused.push(refuse(&truncate(line, 200), GoalRefusal::Unparseable));
            continue;
        }
        let (s, p, o) = (f[skip_columns], f[skip_columns + 1], f[skip_columns + 2]);
        let written = format!("{s} {p} {o}");
        if NEGATION_MARKERS.iter().any(|m| written.starts_with(m)) {
            refused.push(refuse(&written, GoalRefusal::NotAPositiveGroundTriple));
            continue;
        }
        raw.push((written, (s.to_string(), p.to_string(), o.to_string())));
    }
    canonicalise_batch(raw, refused)
}

/// Goals from the basic graph pattern of the query an answer was rendered
/// from, with the answer's bindings substituted.
///
/// The source that needs no trust in a generator at all: it is fully
/// mechanical, and available to any system that builds answers from SPARQL.
/// A variable with no binding is refused by name rather than dropped.
pub fn goals_from_bindings(
    bgp: &[(String, String, String)],
    bindings: &BTreeMap<String, String>,
) -> anyhow::Result<(Vec<Goal>, Vec<RefusedGoal>)> {
    let mut raw: Vec<(String, Spelled)> = Vec::new();
    let mut refused: Vec<RefusedGoal> = Vec::new();
    for (s, p, o) in bgp {
        let sub = |t: &String| -> Option<String> {
            match t.strip_prefix('?').or_else(|| t.strip_prefix('$')) {
                Some(v) => bindings.get(v).cloned(),
                None => Some(t.clone()),
            }
        };
        let written = format!("{s} {p} {o}");
        match (sub(s), sub(p), sub(o)) {
            (Some(s), Some(p), Some(o)) => raw.push((written, (s, p, o))),
            _ => refused.push(refuse(&written, GoalRefusal::Unparseable)),
        }
    }
    canonicalise_batch(raw, refused)
}

/// Round-trip every candidate through a STORE in ONE pass, in document order,
/// keeping the pairing between what was written and what came back.
///
/// The store, not just the parser, because a certificate holds what the store
/// gave back. Under Oxigraph 0.5.9 `"01"^^xsd:integer` survived `RdfParser`
/// and came out of a store as `"1"^^xsd:integer`, so a goal spelled only by
/// the parser matched nothing and was reported LOST. The pinned store keeps
/// the spelling (#335), so the two now agree; `as_written` and `goal` are
/// both still printed.
fn canonicalise_batch(
    raw: Vec<(String, Spelled)>,
    mut refused: Vec<RefusedGoal>,
) -> anyhow::Result<(Vec<Goal>, Vec<RefusedGoal>)> {
    let inputs: Vec<Spelled> = raw.iter().map(|(_, t)| t.clone()).collect();
    let canonical = GraphStore::canonicalise_triples(&inputs)?;
    let mut goals = Vec::new();
    for (i, ((written, _), c)) in raw.iter().zip(canonical).enumerate() {
        let Some(t) = c else {
            // The store refused it. A literal subject is the realistic case and
            // it is not a positive ground triple; anything else the parser
            // rejected is unparseable.
            let why = if raw[i].1 .0.starts_with('"') {
                GoalRefusal::NotAPositiveGroundTriple
            } else {
                GoalRefusal::Unparseable
            };
            refused.push(refuse(written, why));
            continue;
        };
        match classify(&t, written) {
            Ok(()) => goals.push(accept(i, written.clone(), t)),
            Err(r) => refused.push(refuse(written, r)),
        }
    }
    Ok((goals, refused))
}

fn truncate(s: &str, n: usize) -> String {
    let t: String = s.chars().take(n).collect();
    if s.chars().count() > n { format!("{t}…") } else { t }
}

// ───────────────────────────────────────────────────────────────────────────
// The certificate, read back as the checker will read it
// ───────────────────────────────────────────────────────────────────────────

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Membership {
    /// In `asserted.tsv`. No derivation exists and none is needed.
    Asserted,
    /// Concluded by a line in the derivation file.
    Derived,
    /// In neither. Under this profile and this rule table only; the engine
    /// covers 29 of OWL 2 RL's 78 rules and this is not "false".
    NotDerivable,
}

/// Which certificate format a run wrote, and therefore which checker reads it.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CertKind {
    /// `asserted.tsv` + `derivations.tsv`, checked by `oo-cert`.
    OoCert,
    /// `rules.tsv` + `asserted.tsv` + `horn.tsv`, checked by `oo-horn check`.
    OoHorn,
}

impl CertKind {
    pub fn derivations_file(self) -> &'static str {
        match self {
            CertKind::OoCert => "derivations.tsv",
            CertKind::OoHorn => "horn.tsv",
        }
    }
    pub fn binary(self) -> &'static str {
        match self {
            CertKind::OoCert => "oo-cert",
            CertKind::OoHorn => "oo-horn",
        }
    }
}

/// One run's certificate, indexed for lookup and slicing.
///
/// Raw lines are kept so a slice is byte-identical to what the emitter wrote.
pub struct CertificateIndex {
    dir: PathBuf,
    kind: CertKind,
    asserted: HashSet<Spelled>,
    lines: Vec<String>,
    conclusions: Vec<Spelled>,
    premises: Vec<Vec<Spelled>>,
    rules: Vec<String>,
    by_conclusion: HashMap<Spelled, usize>,
}

impl CertificateIndex {
    pub fn read(dir: &Path) -> anyhow::Result<Self> {
        let kind = if dir.join("horn.tsv").exists() { CertKind::OoHorn } else { CertKind::OoCert };
        let asserted_text = std::fs::read_to_string(dir.join("asserted.tsv"))
            .map_err(|e| anyhow::anyhow!("cannot read {}: {e}", dir.join("asserted.tsv").display()))?;
        let mut asserted = HashSet::new();
        for line in asserted_text.lines() {
            if line.is_empty() {
                continue;
            }
            let f: Vec<&str> = line.split('\t').collect();
            if f.len() >= 3 {
                asserted.insert((f[0].to_string(), f[1].to_string(), f[2].to_string()));
            }
        }
        let dpath = dir.join(kind.derivations_file());
        let dtext = std::fs::read_to_string(&dpath)
            .map_err(|e| anyhow::anyhow!("cannot read {}: {e}", dpath.display()))?;

        let mut lines = Vec::new();
        let mut conclusions = Vec::new();
        let mut premises = Vec::new();
        let mut rules = Vec::new();
        let mut by_conclusion: HashMap<Spelled, usize> = HashMap::new();
        for line in dtext.lines() {
            if line.is_empty() {
                continue;
            }
            let f: Vec<&str> = line.split('\t').collect();
            // `oo-cert`: rule, then 3(1+k) term fields.
            // `oo-horn`: rule index, binding count b, 2b binding fields, then
            //            3(1+k) term fields.
            let (rule, start) = match kind {
                CertKind::OoCert => (f.first().copied().unwrap_or("").to_string(), 1),
                CertKind::OoHorn => {
                    let b: usize = f.get(1).and_then(|x| x.parse().ok()).unwrap_or(0);
                    (f.first().copied().unwrap_or("").to_string(), 2 + 2 * b)
                }
            };
            if f.len() < start + 3 || !(f.len() - start).is_multiple_of(3) {
                anyhow::bail!(
                    "{} line {} is not a {} step",
                    dpath.display(),
                    lines.len() + 1,
                    kind.binary()
                );
            }
            let terms: Vec<Spelled> = f[start..]
                .chunks(3)
                .map(|c| (c[0].to_string(), c[1].to_string(), c[2].to_string()))
                .collect();
            let idx = lines.len();
            let conclusion = terms[0].clone();
            by_conclusion.entry(conclusion.clone()).or_insert(idx);
            conclusions.push(conclusion);
            premises.push(terms[1..].to_vec());
            rules.push(rule);
            lines.push(line.to_string());
        }
        Ok(CertificateIndex {
            dir: dir.to_path_buf(),
            kind,
            asserted,
            lines,
            conclusions,
            premises,
            rules,
            by_conclusion,
        })
    }

    pub fn kind(&self) -> CertKind {
        self.kind
    }
    pub fn dir(&self) -> &Path {
        &self.dir
    }
    pub fn asserted_path(&self) -> PathBuf {
        self.dir.join("asserted.tsv")
    }
    pub fn rules_path(&self) -> PathBuf {
        self.dir.join("rules.tsv")
    }
    pub fn asserted_count(&self) -> usize {
        self.asserted.len()
    }
    pub fn derivation_count(&self) -> usize {
        self.lines.len()
    }
    pub fn rule_of(&self, i: usize) -> Option<&str> {
        self.rules.get(i).map(|s| s.as_str())
    }
    pub fn premises_of(&self, i: usize) -> Option<&[Spelled]> {
        self.premises.get(i).map(|v| v.as_slice())
    }
    pub fn conclusion_index(&self, t: &Spelled) -> Option<usize> {
        self.by_conclusion.get(t).copied()
    }
    pub fn conclusion_of_line(&self, i: usize) -> Option<&Spelled> {
        self.conclusions.get(i)
    }

    /// `asserted ⊎ {conclusions}`. The `emit` closure in `src/reason.rs`
    /// records a derivation only when the triple is not already in the closure,
    /// so the two sets are disjoint and this IS the closure the run reached.
    pub fn closure(&self) -> HashSet<Spelled> {
        let mut c = self.asserted.clone();
        for t in &self.conclusions {
            c.insert(t.clone());
        }
        c
    }

    pub fn asserted_set(&self) -> &HashSet<Spelled> {
        &self.asserted
    }

    pub fn membership(&self, t: &Spelled) -> Membership {
        // Asserted FIRST. The certificate holds only INFERRED triples, so a
        // goal that is literally in the slice has no derivation line at all,
        // and an implementation that searches the derivations first finds
        // nothing and reports the goal lost. That is inverted, and the
        // happy-path test would never catch it because it naturally uses a
        // derived goal.
        if self.asserted.contains(t) {
            return Membership::Asserted;
        }
        if self.by_conclusion.contains_key(t) {
            return Membership::Derived;
        }
        Membership::NotDerivable
    }

    /// Line indices of a certificate that concludes `t`, closed under premises
    /// and in ASCENDING original order.
    ///
    /// The order is valid and it is provable from the emitter rather than hoped
    /// for: `run_full` computes a round's conclusions from `triple_set` as it
    /// stood at the START of that round and inserts them only afterwards, so
    /// every premise of a line was asserted or concluded strictly earlier in
    /// the file. `oo-cert` rejects a premise that is "neither asserted nor
    /// derived earlier", so this is load-bearing and is pinned by a test.
    pub fn slice_for(&self, t: &Spelled) -> Option<Vec<usize>> {
        let root = *self.by_conclusion.get(t)?;
        let mut want: BTreeSet<usize> = BTreeSet::new();
        let mut stack = vec![root];
        while let Some(i) = stack.pop() {
            if !want.insert(i) {
                continue;
            }
            for p in &self.premises[i] {
                if self.asserted.contains(p) {
                    continue;
                }
                if let Some(&j) = self.by_conclusion.get(p)
                    && j < i
                    && !want.contains(&j)
                {
                    stack.push(j);
                }
            }
        }
        Some(want.into_iter().collect())
    }

    /// Write a sub-certificate's derivation lines.
    ///
    /// `asserted.tsv` is NOT copied: the caller passes the run's single
    /// [`asserted_path`](Self::asserted_path) to the checker, so 200 goals over
    /// a 37k-derivation run do not write 200 copies of the graph.
    pub fn write_slice(&self, lines: &[usize], out_derivations: &Path) -> anyhow::Result<()> {
        if let Some(parent) = out_derivations.parent() {
            std::fs::create_dir_all(parent)?;
        }
        let mut body = String::new();
        for &i in lines {
            body.push_str(&self.lines[i]);
            body.push('\n');
        }
        std::fs::write(out_derivations, body)?;
        Ok(())
    }
}

// ───────────────────────────────────────────────────────────────────────────
// The checker
// ───────────────────────────────────────────────────────────────────────────

/// An acceptance. The fields are private and the only constructor is
/// [`Accepted::from_run`], which takes a [`Certified`] — and that type has no
/// public constructor at all, so this struct cannot be built by a caller that
/// did not run a checker and read a zero exit code.
///
/// It serialises as the two fields it always had, flattened under the `status`
/// tag by serde's internally-tagged newtype-variant handling, so the wire
/// format is byte-for-byte what it was.
#[derive(Clone, Debug)]
pub struct Accepted {
    certified: Certified,
    stdout: String,
}

impl Accepted {
    fn from_run(certified: Certified, stdout: String) -> Accepted {
        Accepted { certified, stdout }
    }
    /// The evidence, so a downstream verdict carries the token this run
    /// earned rather than re-asserting the acceptance on its own authority.
    /// A clone, because this is where the token travels from the run that
    /// earned it to the verdict that will carry it. That is the one move the
    /// token is for, and it is now written down rather than implicit.
    pub fn certified(&self) -> Certified {
        self.certified.clone()
    }
    pub fn theorem(&self) -> &'static str {
        self.certified.theorem()
    }
    pub fn stdout(&self) -> &str {
        &self.stdout
    }
}

impl Serialize for Accepted {
    /// `{"theorem": ..., "stdout": ...}`, exactly the two fields the struct
    /// variant carried, so the tagged enum above still writes
    /// `{"status":"accepted","theorem":...,"stdout":...}`.
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        use serde::ser::SerializeStruct as _;
        let mut st = s.serialize_struct("Accepted", 2)?;
        st.serialize_field("theorem", self.certified.theorem())?;
        st.serialize_field("stdout", &self.stdout)?;
        st.end()
    }
}

#[derive(Clone, Debug, Serialize)]
#[serde(tag = "status", rename_all = "snake_case")]
pub enum CheckerStatus {
    Accepted(Accepted),
    /// Exit 1. This module built the slice, so a rejection is a defect HERE or
    /// in the emitter. It is never a downgrade to an unchecked verdict.
    Rejected { stdout: String },
    /// Exit 2: a file could not be read or parsed. Not a verdict in either
    /// direction, exactly as `lean/Main.lean` reserves the two codes.
    Unreadable { stdout: String },
    /// Skip loudly, with the install line, and report the unchecked verdict
    /// honestly. Never pass silently.
    Absent { what: String, install: &'static str },
    /// The checker was found and no goal needed it, because no preserved goal
    /// was DERIVED and a goal that is literally in the slice has no derivation
    /// to check. Its own word, because calling that `unreadable` would put a
    /// file-format failure's name on a run where nothing went wrong, and
    /// calling it `accepted` would be worse.
    NotNeeded { what: String },
}

impl CheckerStatus {
    pub fn is_absent(&self) -> bool {
        matches!(self, CheckerStatus::Absent { .. })
    }
    pub fn word(&self) -> &'static str {
        match self {
            CheckerStatus::Accepted(_) => "accepted",
            CheckerStatus::Rejected { .. } => "rejected",
            CheckerStatus::Unreadable { .. } => "unreadable",
            CheckerStatus::Absent { .. } => "absent",
            CheckerStatus::NotNeeded { .. } => "not_needed",
        }
    }
}

/// Find a Lean checker binary.
///
/// Mirrors the search every other certified path in this repository does, for
/// the reason those give: a run that quietly dropped to the engine's own
/// opinion because the checker was not built would look exactly like a run
/// where the checker had agreed.
pub fn find_checker(kind: CertKind, explicit: Option<&Path>) -> Result<PathBuf, String> {
    let name = kind.binary();
    if let Some(p) = explicit {
        return if p.exists() {
            Ok(p.to_path_buf())
        } else {
            Err(format!("{} does not exist", p.display()))
        };
    }
    let env_key = match kind {
        CertKind::OoCert => "OO_CERT",
        CertKind::OoHorn => "OO_HORN",
    };
    if let Ok(v) = std::env::var(env_key) {
        let p = PathBuf::from(&v);
        return if p.exists() { Ok(p) } else { Err(format!("${env_key} points at {v}, which does not exist")) };
    }
    let mut tried = Vec::new();
    for base in [
        PathBuf::from("."),
        PathBuf::from(env!("CARGO_MANIFEST_DIR")),
    ] {
        let p = base.join("lean").join(".lake").join("build").join("bin").join(name);
        if p.exists() {
            return Ok(p);
        }
        tried.push(p.display().to_string());
    }
    if let Ok(out) = std::process::Command::new(name).arg("--help").output() {
        // A bare invocation with no arguments prints usage and exits 2, which
        // is enough to know the binary is on PATH.
        let _ = out;
        return Ok(PathBuf::from(name));
    }
    Err(format!("{name} not found (looked at ${env_key}, {}, and $PATH)", tried.join(", ")))
}

/// Run `oo-cert ASSERTED DERIVATIONS` and turn its exit code into a verdict.
pub fn run_oo_cert(checker: Option<&Path>, asserted: &Path, derivations: &Path) -> CheckerStatus {
    run_checker(CertKind::OoCert, checker, asserted, derivations, None)
}

/// The ONE place a checked verdict is produced, and it has just read an exit
/// code off a Lean binary.
///
/// "The one place" is no longer a promise in a comment. The acceptance it
/// returns carries a [`Certified`], and [`crate::verdict::CheckerRun::spawn`]
/// is the only thing in the crate that can mint one, so a second place would
/// have to run a checker too.
pub fn run_checker(
    kind: CertKind,
    checker: Option<&Path>,
    asserted: &Path,
    derivations: &Path,
    rules: Option<&Path>,
) -> CheckerStatus {
    let bin = match find_checker(kind, checker) {
        Ok(b) => b,
        Err(why) => {
            return CheckerStatus::Absent { what: why, install: LAKE_INSTALL };
        }
    };
    let mut cmd = std::process::Command::new(&bin);
    // The files this run is about, collected in the same arm that puts them on
    // the command line so the two cannot disagree.
    let mut inputs: Vec<&Path> = Vec::new();
    match kind {
        CertKind::OoCert => {
            cmd.arg(asserted).arg(derivations);
            inputs.extend_from_slice(&[asserted, derivations]);
        }
        CertKind::OoHorn => {
            let Some(r) = rules else {
                return CheckerStatus::Absent {
                    what: "oo-horn needs the rules.tsv the run evaluated, and none was written"
                        .to_string(),
                    install: LAKE_INSTALL,
                };
            };
            cmd.arg("check").arg(r).arg(asserted).arg(derivations);
            inputs.extend_from_slice(&[r, asserted, derivations]);
        }
    }
    let run = match CheckerRun::spawn(&CheckerBinary::found_at(bin.clone()), cmd, &inputs) {
        Ok(r) => r,
        Err(e) => {
            return CheckerStatus::Absent {
                what: format!("{} could not be run: {e}", bin.display()),
                install: LAKE_INSTALL,
            };
        }
    };
    let text = run.output();
    // The theorem name is handed to the evidence rather than to the report, so
    // a status with no acceptance behind it has no way to name one. What is
    // listed here is what this call site will ACCEPT; which of them the token
    // ends up carrying is read out of the checker's own stdout.
    //
    // `oo-horn` has two. `lean/HMain.lean` earns the absolute
    // `OOCert.entails_of_builtin_horn` when the rule table is exactly the
    // built-ins, and the relativised `OOCert.horn_certificate_sound` for any
    // other table, and it prints which. Naming one literal here reported the
    // relativised statement for both, which is the safe direction to be wrong
    // in and still wrong: the field that exists to distinguish an entailment
    // from an entailment-under-supplied-rules did not distinguish them.
    let theorems: &[&'static str] = match kind {
        CertKind::OoCert => &["OOCert.certificate_sound"],
        CertKind::OoHorn => &[
            "OOCert.horn_certificate_sound",
            "OOCert.entails_of_builtin_horn",
        ],
    };
    match run.accepted_naming(theorems) {
        Some(cert) => CheckerStatus::Accepted(Accepted::from_run(cert, text)),
        // `lean/Main.lean` reserves 1 for a rejection and 2 for a file it
        // could not read. Anything else is not a verdict in either direction.
        None => match run.exit() {
            1 => CheckerStatus::Rejected { stdout: text },
            2 => CheckerStatus::Unreadable { stdout: text },
            // `{:?}` on the raw `Option`, byte for byte what this arm has
            // always printed: `None` for a signal death, `Some(n)` otherwise.
            _ => CheckerStatus::Unreadable {
                stdout: format!("{} exited with {:?}\n{text}", bin.display(), run.code()),
            },
        },
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Verdicts
// ───────────────────────────────────────────────────────────────────────────

/// The per-goal verdict.
///
/// The two CHECKED variants carry a [`Certified`], which has no public
/// constructor, so neither can be named on a path that did not run the Lean
/// checker. `Deserialize` is deliberately not implemented: reading
/// `"preserved_checked"` out of somebody else's JSON is not the same act as
/// earning it, and a derive would be a public constructor for both.
///
/// ```compile_fail
/// use open_ontologies::projection_entailment::GoalVerdict;
/// use open_ontologies::verdict::Certified;
/// let v = GoalVerdict::PreservedChecked(Certified {
///     theorem: "OOCert.certificate_sound",
///     subject: [0u8; 32],
/// });
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum GoalVerdict {
    /// `P` entails `q`, machine-checked over `P`'s own asserted graph.
    PreservedChecked(Certified),
    /// The same, but the run evaluated a SUPPLIED Horn table. True in every
    /// model of `P` that ALSO satisfies those rules. Never shortened.
    PreservedUnderSuppliedRulesChecked(Certified),
    /// `q` is literally in the slice. Verified by set membership over the
    /// canonical spelling. Not a theorem and it does not pretend to be.
    PreservedAsserted,
    /// The ENGINE derived it and no checker looked.
    PreservedUnchecked,
    /// Not derivable from `P` under this profile. Bounded by a rule table
    /// implementing 29 of OWL 2 RL's 78 rules, so it is not "P does not entail
    /// q".
    LostUnderProfileUnchecked,
    /// Neither certificate has it. The source does not derive it either, so
    /// the projection did not lose it.
    UngroundedInSource,
    /// In `P`'s certificate and not in `G`'s. A defect report rather than a
    /// verdict; see the monotonicity block.
    ProjectionOnly,
    /// The Lean checker REJECTED the sub-certificate this module assembled for
    /// the goal. A defect HERE or in the emitter, never a weaker result about
    /// the ontology, and never a downgrade to an unchecked verdict.
    CertificateRejected,
    /// Not a positive ground triple.
    Refused,
}

impl GoalVerdict {
    /// The wire word. Byte-identical to what `#[serde(rename_all =
    /// "snake_case")]` used to derive, and the single source of the string now
    /// that the two checked variants carry a payload serde would otherwise
    /// have wrapped in an object.
    pub fn word(&self) -> &'static str {
        match self {
            GoalVerdict::PreservedChecked(_) => "preserved_checked",
            GoalVerdict::PreservedUnderSuppliedRulesChecked(_) => {
                "preserved_under_supplied_rules_checked"
            }
            GoalVerdict::PreservedAsserted => "preserved_asserted",
            GoalVerdict::PreservedUnchecked => "preserved_unchecked",
            GoalVerdict::LostUnderProfileUnchecked => "lost_under_profile_unchecked",
            GoalVerdict::UngroundedInSource => "ungrounded_in_source",
            GoalVerdict::ProjectionOnly => "projection_only",
            GoalVerdict::CertificateRejected => "certificate_rejected",
            GoalVerdict::Refused => "refused",
        }
    }
    /// The theorem a verdict names, or `"none"`. A verdict with no theorem must
    /// never render a string containing "checked", and the suite asserts that
    /// over the SERIALISED report rather than over this function, because the
    /// enum is where the discipline is easy and the serialisation is where it
    /// leaks. The name now comes OUT OF THE EVIDENCE rather than out of a
    /// match arm, so a run that never ran the checker cannot name a theorem.
    pub fn warrant(&self) -> &'static str {
        match self {
            GoalVerdict::PreservedChecked(c)
            | GoalVerdict::PreservedUnderSuppliedRulesChecked(c) => c.theorem(),
            _ => "none",
        }
    }
    pub fn is_checked(&self) -> bool {
        self.warrant() != "none"
    }
    pub fn is_preserved(&self) -> bool {
        matches!(
            self,
            GoalVerdict::PreservedChecked(_)
                | GoalVerdict::PreservedUnderSuppliedRulesChecked(_)
                | GoalVerdict::PreservedAsserted
                | GoalVerdict::PreservedUnchecked
        )
    }
    pub fn means(&self) -> &'static str {
        match self {
            GoalVerdict::PreservedChecked(_) =>
                "the projection entails this goal: true in every model of the projection under the \
                 semantics in lean/OOCert/Semantics.lean. Machine-checked by oo-cert over the \
                 projection's own asserted.tsv",
            GoalVerdict::PreservedUnderSuppliedRulesChecked(_) =>
                "true in every model of the projection THAT ALSO SATISFIES the supplied rule \
                 table. The rules are assumed and never checked; a rule reading 'every supplier \
                 is compliant' produces certificates that check green for ever. Never shorten \
                 this to the plain preserved word",
            GoalVerdict::PreservedAsserted =>
                "the goal is literally in the slice, by exact-string membership in the \
                 projection's asserted.tsv. No rule fired, nothing was proved, and nothing needed \
                 to be. This is a lookup, not a theorem",
            GoalVerdict::PreservedUnchecked =>
                "the ENGINE derived it from the projection and no checker has looked. This is the \
                 engine's opinion about its own output, which is exactly what the certificate \
                 layer exists to stop being trusted",
            GoalVerdict::LostUnderProfileUnchecked =>
                "the source derives it and the projection does not, under this profile. The \
                 retrieval finding. The engine implements 29 of OWL 2 RL's 78 rules, so this is \
                 bounded by the rule table and is NOT 'the projection does not entail it'",
            GoalVerdict::UngroundedInSource =>
                "NEITHER the source nor the projection derives it. The projection did not lose \
                 it: the claim has no support in the knowledge graph under this profile, so the \
                 fix is in the generator and not the retriever. Open-world: this is not 'false'",
            GoalVerdict::ProjectionOnly =>
                "the projection derives it and the source does not. Either the projection is not \
                 a subset of the source, or OWL RL monotonicity has been violated and the engine \
                 is unsound. Read the monotonicity block; this is never a retrieval finding",
            GoalVerdict::CertificateRejected => CERTIFICATE_REJECTED_MEANS,
            GoalVerdict::Refused =>
                "not a positive ground triple, so it was never asked. Counted in the headline so \
                 a refusal cannot shrink the denominator unnoticed",
        }
    }
}

impl Serialize for GoalVerdict {
    /// A bare string, exactly as `#[serde(rename_all = "snake_case")]` wrote
    /// it before the checked variants grew a payload.
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.word())
    }
}

/// So the suite can go on asserting against the wire word without being able
/// to build a checked variant to compare with.
impl PartialEq<&str> for GoalVerdict {
    fn eq(&self, other: &&str) -> bool {
        self.word() == *other
    }
}

impl std::fmt::Display for GoalVerdict {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.word())
    }
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct GoalCertificate {
    pub dir: String,
    pub format: &'static str,
    pub steps: usize,
    pub asserted: usize,
    /// The exact command a reader can run by hand.
    pub check_with: String,
}

/// Not `Deserialize`: it carries a [`GoalVerdict`], whose checked variants
/// are evidence and not words. Reading `"preserved_checked"` out of somebody
/// else's JSON is not the same act as earning it, and a derive here would be a
/// public constructor for the certified state. Reports are read back as
/// `serde_json::Value`, which is what every caller in the tree already does.
#[derive(Clone, Debug, Serialize)]
pub struct GoalReport {
    pub id: String,
    pub as_written: String,
    /// The canonical spelling actually asked. Printed even when it equals
    /// `as_written`, because the case where it differs is the one that bites.
    pub goal: String,
    pub source: Membership,
    pub projection: Membership,
    pub verdict: GoalVerdict,
    pub warrant: &'static str,
    pub means: &'static str,
    /// Present only for a preserved-and-checked goal.
    pub certificate: Option<GoalCertificate>,
    /// True when either run stopped at the iteration cap. Every NEGATIVE
    /// verdict from such a run is a lower bound, not a fact.
    pub bounded_by_iteration_cap: bool,
    /// The goal mentions no term any seed neighbourhood reaches. Usually a
    /// retriever misconfiguration rather than a loss, so it is named separately
    /// instead of being sent to the loss pile.
    pub goal_outside_seed_neighbourhood: bool,
}

// ───────────────────────────────────────────────────────────────────────────
// Subsethood and the differential
// ───────────────────────────────────────────────────────────────────────────

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct SubsetReport {
    /// Computed, never inferred from provenance. A retriever that normalises
    /// IRIs, re-prefixes, expands an abbreviation, inlines an imported
    /// vocabulary or adds a tidy `rdf:type owl:Class` declaration produces a
    /// non-subset that looks like a faithful slice.
    pub verified: bool,
    pub decided_over: &'static str,
    pub extra_triples: Vec<String>,
    pub extra_count: usize,
    pub blank_node_bearing_source: usize,
    pub blank_node_bearing_projection: usize,
    /// True when a blank node on either side has no binding across the two
    /// graphs, so subsethood over those triples is UNDECIDED rather than false.
    pub blank_nodes_unmatched: bool,
}

#[derive(Clone, Copy, Debug)]
pub struct Guards {
    pub subset_verified: bool,
    pub blank_nodes_unmatched: bool,
    pub both_reached_fixpoint: bool,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct MonotonicityReport {
    /// `"armed"` or `"disarmed"`. A green `violations: []` under `"disarmed"`
    /// means "we did not look", and the two must never render the same.
    pub status: &'static str,
    pub reason: &'static str,
    pub violations: Vec<String>,
    pub violation_count: usize,
    pub disagreement: Option<Disagreement>,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Disagreement {
    pub severity: &'static str,
    pub what: &'static str,
    pub detail: String,
    pub means: &'static str,
}

pub const MONOTONICITY_MEANS: &str =
    "OWL RL is monotone and this projection IS a subset of the source, so every conclusion of the \
     projection must be a conclusion of the source. This one is not. That is a SOUNDNESS BUG IN \
     THE ENGINE, not a finding about the retrieval, and not something to file under 'other'. Do \
     not ship a run that reports this.";

pub const CERTIFICATE_REJECTED_MEANS: &str =
    "the Lean checker rejected a sub-certificate THIS MODULE assembled from the engine's own \
     derivation file. That is a defect in the slice extractor or in the emitter's premise order, \
     not a weaker result about the ontology. It does not downgrade to preserved_unchecked, \
     because that would turn a defect in this code into a slightly weaker verdict nobody \
     investigates.";

/// PURE, so the gate can be shown failing without an unsound engine to hand.
///
/// The engine cannot be made unsound on demand, so the only honest way to show
/// that this gate can fire is to hand it a pair of closures where the
/// projection's exceeds the source's with both guards true.
pub fn differential(
    source_closure: &HashSet<Spelled>,
    projection_closure: &HashSet<Spelled>,
    guards: Guards,
) -> MonotonicityReport {
    let disarm = if !guards.subset_verified {
        Some("projection_is_not_a_subset")
    } else if guards.blank_nodes_unmatched {
        Some("blank_nodes_unmatched")
    } else if !guards.both_reached_fixpoint {
        Some("fixpoint_not_reached")
    } else {
        None
    };
    if let Some(reason) = disarm {
        return MonotonicityReport {
            status: "disarmed",
            reason,
            violations: Vec::new(),
            violation_count: 0,
            disagreement: None,
        };
    }
    let mut extra: Vec<String> = projection_closure
        .difference(source_closure)
        .map(|t| format!("{} {} {}", t.0, t.1, t.2))
        .collect();
    extra.sort();
    let count = extra.len();
    let shown: Vec<String> = extra.into_iter().take(50).collect();
    let disagreement = if count == 0 {
        None
    } else {
        Some(Disagreement {
            severity: STOP_THE_LINE,
            what: "monotonicity_violated",
            detail: format!(
                "{count} conclusion(s) of the projection are not conclusions of the source, over a \
                 projection verified to be a subset, with both runs at a fixpoint"
            ),
            means: MONOTONICITY_MEANS,
        })
    };
    MonotonicityReport {
        status: "armed",
        reason: "",
        violations: shown,
        violation_count: count,
        disagreement,
    }
}

// ───────────────────────────────────────────────────────────────────────────
// The demoted proxy
// ───────────────────────────────────────────────────────────────────────────

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct CoverageProxy {
    /// `None` when no seeds were supplied or the slice did not parse, so
    /// "we did not compute it" can never render as "0% coverage".
    pub report: Option<ProjectionLossReport>,
    pub not_computed_because: Option<String>,
    /// Always false. A field rather than a doc comment, so a consumer reading
    /// JSON sees it without reading prose.
    pub is_a_warrant: bool,
    pub label: &'static str,
    /// Seeds whose neighbourhood hit the `LIMIT 1000` in
    /// `projection_check::neighbourhood_pairs`, so their ratio was computed on
    /// a truncated source. A truncated proxy reading 1.0 is the green-metric
    /// trap one level down.
    pub truncated_seeds: Vec<String>,
    /// The proxy is subject-only: an inbound-edge loss is invisible to it.
    /// Named here rather than fixed, because that is its own change.
    pub known_limits: &'static str,
}

const PROXY_LIMITS: &str =
    "the proxy counts a seed's OUTBOUND (predicate, object) pairs only, so a lost inbound edge is \
     invisible to it, and its SPARQL carries LIMIT 1000, so a seed with more than a thousand \
     outbound triples has its ratio computed against a truncated source. Both are pre-existing \
     and are named rather than fixed here.";

// ───────────────────────────────────────────────────────────────────────────
// Hygiene of the source side
// ───────────────────────────────────────────────────────────────────────────

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct SourceHygiene {
    /// Non-zero means an earlier `reason` run materialised into this store, so
    /// `asserted.tsv` on the source side lists the engine's own output as an
    /// axiom. Every `ungrounded_in_source` then becomes unreachable and every
    /// goal looks supported. Decision 0005 item 7 records this exact defect,
    /// found inside this repository, in a different tool.
    pub materialised_inferences_in_source: usize,
    pub source_side_unreliable: bool,
    pub means: &'static str,
}

// ───────────────────────────────────────────────────────────────────────────
// Options and the report
// ───────────────────────────────────────────────────────────────────────────

/// Where the slice came from. The arms differ in what can be PROVED about them,
/// not in convenience.
#[derive(Clone, Copy, Debug)]
pub enum Projection<'a> {
    /// Turtle text, re-parsed into a fresh store. Blank nodes are relabelled on
    /// the way in, so subsethood is decidable only over ground triples and the
    /// differential is disarmed whenever either side carries one.
    Turtle(&'a str),
    /// A named graph of the SAME store the source is read from. Blank node
    /// identity survives because nothing is re-parsed, so `P ⊆ G` is decided by
    /// set membership over every triple and the differential can be armed.
    NamedGraph(&'a str),
}

#[derive(Clone, Debug)]
pub struct Opts {
    /// ONE profile for BOTH runs. Two profiles compare two rule sets, and the
    /// differential then fires on nothing at all.
    pub profile: String,
    /// Optional supplied Horn table. Its presence changes the verdict WORD for
    /// every preserved goal.
    pub rules: Option<PathBuf>,
    /// Where the two run certificates and the per-goal slices land. Every
    /// intermediate file stays, so a run is reproducible by hand.
    pub work_dir: PathBuf,
    /// Explicit checker path. Defaults to `$OO_CERT`, then the repository's
    /// `lean/.lake/build/bin/`, then `$PATH`.
    pub checker: Option<PathBuf>,
    /// Turn an absent checker into an error instead of an honest unchecked
    /// verdict. The CI leg sets this.
    pub require_checker: bool,
    /// Seeds for the demoted coverage proxy. Independent of the goals, and
    /// never derived from them: a goal can mention IRIs no seed neighbourhood
    /// reaches, and coverage over the seeds says nothing about such a goal.
    pub seed_iris: Vec<String>,
}

impl Default for Opts {
    fn default() -> Self {
        Opts {
            profile: "owl-rl".into(),
            rules: None,
            work_dir: PathBuf::from("projection-entailment"),
            checker: None,
            require_checker: false,
            seed_iris: Vec::new(),
        }
    }
}

/// Not `Deserialize`, for the reason on [`GoalReport`].
#[derive(Clone, Debug, Serialize)]
pub struct PreservationReport {
    pub format: &'static str,
    /// One sentence a reader cannot miss, first in the JSON after the format.
    pub headline: String,
    pub profile: String,
    pub rules: Option<String>,
    pub rules_sha256: Option<String>,
    pub goals_total: usize,
    pub preserved_checked: usize,
    pub preserved_asserted: usize,
    pub preserved_unchecked: usize,
    pub lost: usize,
    pub ungrounded_in_source: usize,
    pub projection_only: usize,
    /// Goals whose sub-certificate the checker rejected. Non-zero means a
    /// defect in this module or in the emitter, so it is counted apart from
    /// everything else and always comes with a stop-the-line block.
    pub certificate_rejected: usize,
    pub refused: usize,
    pub per_goal: Vec<GoalReport>,
    pub refused_goals: Vec<RefusedGoal>,
    pub subset: SubsetReport,
    pub monotonicity: MonotonicityReport,
    /// The stop-the-line block, if one fired. Either the monotonicity
    /// violation, or a sub-certificate the checker REJECTED, which is a defect
    /// in this module or in the emitter and not a weaker result about the
    /// ontology. Kept at the top level because a rejection is not a statement
    /// about monotonicity and must not be filed inside its block.
    pub disagreement: Option<Disagreement>,
    pub coverage_proxy: CoverageProxy,
    pub checker: CheckerStatus,
    pub source_hygiene: SourceHygiene,
    pub source_fixpoint_reached: bool,
    pub projection_fixpoint_reached: bool,
    pub source_iterations: usize,
    pub projection_iterations: usize,
    pub iteration_cap: usize,
    pub work_dir: String,
    /// Known limits of what a `preserved_checked` says, in the payload rather
    /// than only in the docs.
    pub limits: &'static str,
    /// True iff nothing was lost, nothing stopped the line, and no goal was
    /// refused. `ungrounded_in_source` does NOT clear it: a claim with no
    /// support in the graph is a finding, not a pass.
    pub ok: bool,
    /// 0 clean, 1 something was lost, ungrounded or refused, 2 stop-the-line.
    pub exit_code: i32,
}

const LIMITS: &str =
    "OOCert's entailment relation is not datatype-aware: \"1\"^^xsd:int and \"1\"^^xsd:integer are \
     two distinct terms, so a preserved_checked on one says nothing about the other. A lost_* \
     verdict is an engine opinion about a NEGATIVE and carries no certificate in this layer, \
     ever. The rule table is this engine's, not W3C's: 29 of OWL 2 RL's 78 rules.";

// ───────────────────────────────────────────────────────────────────────────
// The entry point
// ───────────────────────────────────────────────────────────────────────────

struct SideRun {
    fixpoint_reached: bool,
    iterations: usize,
    rules_sha256: Option<String>,
}

fn reason_side(store: &Arc<GraphStore>, opts: &Opts, dir: &Path) -> anyhow::Result<SideRun> {
    std::fs::create_dir_all(dir)?;
    let json: serde_json::Value = if let Some(rules) = &opts.rules {
        serde_json::from_str(&Reasoner::run_horn(store, rules, dir)?)?
    } else {
        // `materialize = false` ALWAYS. `run_full` computes the closure in
        // memory and writes the certificate regardless, so false costs nothing
        // and reasoning into the store would put this run's conclusions into
        // the next run's asserted.tsv.
        serde_json::from_str(&Reasoner::run_full(
            store,
            &opts.profile,
            false,
            InferenceTarget::DefaultGraph,
            Some(dir),
        )?)?
    };
    if let Some(e) = json.get("error").and_then(|v| v.as_str()) {
        anyhow::bail!("{e}");
    }
    Ok(SideRun {
        fixpoint_reached: json["fixpoint_reached"].as_bool().unwrap_or(false),
        iterations: json["iterations"].as_u64().unwrap_or(0) as usize,
        rules_sha256: json["certificate"]["rules_tsv_sha256"].as_str().map(|s| s.to_string()),
    })
}

/// Ask whether a retrieved slice still supports the claims an answer rests on.
///
/// Runs the reasoner twice with `materialize = false` into
/// `opts.work_dir/{source,projection}`, decides every goal over the certificate
/// FILES rather than an in-memory closure the checker never sees, extracts and
/// checks a sub-certificate per preserved goal, and runs the monotonicity
/// differential.
///
/// Errors rather than returning a green report when `goals` is empty: every
/// aggregate over zero goals is trivially perfect, which is decision 0006 item
/// 8's empty-problem shape, and "all my goals were refused" is the realistic
/// way to arrive at zero.
pub fn check_entailment_preservation(
    graph: &Arc<GraphStore>,
    projection: Projection<'_>,
    goals: &[Goal],
    refused: &[RefusedGoal],
    opts: &Opts,
) -> anyhow::Result<PreservationReport> {
    if goals.is_empty() {
        anyhow::bail!(
            "no goals to ask. {} goal(s) were refused as not positive ground triples or \
             unparseable, and every aggregate over zero goals is trivially perfect, so a report \
             here would be a green run that says nothing",
            refused.len()
        );
    }
    if opts.profile == "owl-dl" {
        anyhow::bail!(
            "owl-dl emits no rule trace, so neither side could be certified and every verdict \
             would collapse to the engine's opinion while still looking like a certified run. \
             Run rdfs, owl-rl or owl-rl-ext"
        );
    }

    // ── The projection store ────────────────────────────────────────────
    let (pstore, projected_ttl, projection_kind): (Arc<GraphStore>, String, &'static str) =
        match projection {
            Projection::Turtle(ttl) => {
                let s = GraphStore::new();
                s.load_turtle(ttl, None).map_err(|e| {
                    let hint = if ttl.contains("<_:") {
                        ". The slice contains `<_:`, an angle-bracketed blank node label, which \
                         is not a legal IRI. That is what onto_segment_retrieve emits for a \
                         blank-node object; skolemise the source before retrieving"
                    } else {
                        ""
                    };
                    anyhow::anyhow!(
                        "the projection is not readable as Turtle, so there is no slice to ask \
                         about: {e}{hint}"
                    )
                })?;
                (Arc::new(s), ttl.to_string(), "turtle")
            }
            Projection::NamedGraph(name) => {
                let s = graph.graph_store(name)?;
                if s.triple_count() == 0 {
                    anyhow::bail!(
                        "named graph <{name}> holds no triples in the loaded store, so there is \
                         no slice to ask about"
                    );
                }
                let ttl = s.serialize("turtle").unwrap_or_default();
                (Arc::new(s), ttl, "named_graph")
            }
        };

    // ── Hygiene of the source side, before anything is computed from it ──
    let materialised = graph.materialised_inference_count().unwrap_or(0);
    let hygiene = SourceHygiene {
        materialised_inferences_in_source: materialised,
        source_side_unreliable: materialised > 0,
        means: if materialised > 0 {
            "an earlier reason run materialised into this store, so the source side's \
             asserted.tsv lists the engine's own output as an axiom. ungrounded_in_source becomes \
             unreachable and every goal looks supported. Reload the source from its files"
        } else {
            "no materialised inferences in the source store, so asserted.tsv is what was written"
        },
    };

    // ── Subsethood, computed rather than assumed from provenance ────────
    let src_triples: HashSet<Spelled> = graph.all_triples()?.into_iter().collect();
    let proj_triples: Vec<Spelled> = pstore.all_triples()?;
    let bn_src = src_triples.iter().filter(|t| has_blank(t)).count();
    let bn_proj = proj_triples.iter().filter(|t| has_blank(t)).count();
    let ground_only = projection_kind == "turtle" && (bn_src > 0 || bn_proj > 0);
    let mut extras: Vec<String> = Vec::new();
    let mut extra_count = 0usize;
    for t in &proj_triples {
        if ground_only && has_blank(t) {
            continue;
        }
        if !src_triples.contains(t) {
            extra_count += 1;
            if extras.len() < 25 {
                extras.push(format!("{} {} {}", t.0, t.1, t.2));
            }
        }
    }
    extras.sort();
    let subset = SubsetReport {
        verified: extra_count == 0,
        decided_over: if ground_only { "ground triples only" } else { "all triples" },
        extra_triples: extras,
        extra_count,
        blank_node_bearing_source: bn_src,
        blank_node_bearing_projection: bn_proj,
        blank_nodes_unmatched: ground_only,
    };

    // ── Two runs, one profile ───────────────────────────────────────────
    let work = &opts.work_dir;
    let src_dir = work.join("source");
    let prj_dir = work.join("projection");
    let src_run = reason_side(graph, opts, &src_dir)?;
    let prj_run = reason_side(&pstore, opts, &prj_dir)?;
    let src_cert = CertificateIndex::read(&src_dir)?;
    let prj_cert = CertificateIndex::read(&prj_dir)?;

    // ── The free differential ───────────────────────────────────────────
    let both_fixpoint = src_run.fixpoint_reached && prj_run.fixpoint_reached;
    let mono = differential(
        &src_cert.closure(),
        &prj_cert.closure(),
        Guards {
            subset_verified: subset.verified,
            blank_nodes_unmatched: subset.blank_nodes_unmatched,
            both_reached_fixpoint: both_fixpoint,
        },
    );

    // ── Seed neighbourhood, for goal_outside_seed_neighbourhood ─────────
    let seed_terms = seed_neighbourhood_terms(graph, &opts.seed_iris);

    // ── Per goal ────────────────────────────────────────────────────────
    let bounded = !both_fixpoint;
    let mut per_goal = Vec::with_capacity(goals.len());
    let mut checker_status: Option<CheckerStatus> = None;
    let mut stop_the_line: Option<Disagreement> = mono.disagreement.clone();
    for g in goals {
        let source = src_cert.membership(&g.triple);
        let projection = prj_cert.membership(&g.triple);
        let mut certificate = None;
        let verdict = match (source, projection) {
            (Membership::NotDerivable, Membership::NotDerivable) => GoalVerdict::UngroundedInSource,
            (Membership::NotDerivable, _) => GoalVerdict::ProjectionOnly,
            (_, Membership::NotDerivable) => GoalVerdict::LostUnderProfileUnchecked,
            // Asserted FIRST: see CertificateIndex::membership.
            (_, Membership::Asserted) => GoalVerdict::PreservedAsserted,
            (_, Membership::Derived) => {
                let lines = prj_cert.slice_for(&g.triple).unwrap_or_default();
                let out = work.join("goals").join(&g.id).join(prj_cert.kind().derivations_file());
                prj_cert.write_slice(&lines, &out)?;
                let rules_path = prj_cert.rules_path();
                let status = run_checker(
                    prj_cert.kind(),
                    opts.checker.as_deref(),
                    &prj_cert.asserted_path(),
                    &out,
                    if prj_cert.kind() == CertKind::OoHorn { Some(&rules_path) } else { None },
                );
                let v = match &status {
                    CheckerStatus::Accepted(a) => {
                        certificate = Some(GoalCertificate {
                            dir: out.parent().unwrap_or(&out).display().to_string(),
                            format: if prj_cert.kind() == CertKind::OoHorn { "oo-horn/1" } else { "oo-cert/1" },
                            steps: lines.len(),
                            asserted: prj_cert.asserted_count(),
                            check_with: check_command(&prj_cert, &out),
                        });
                        // The token this goal's own checker run produced. It
                        // carries the theorem, so the warrant printed beside
                        // the verdict cannot drift from the run that earned it.
                        if prj_cert.kind() == CertKind::OoHorn {
                            GoalVerdict::PreservedUnderSuppliedRulesChecked(a.certified())
                        } else {
                            GoalVerdict::PreservedChecked(a.certified())
                        }
                    }
                    CheckerStatus::Rejected { stdout } => {
                        // NOT a downgrade. This module built the slice.
                        stop_the_line.get_or_insert(Disagreement {
                            severity: STOP_THE_LINE,
                            what: "certificate_rejected",
                            detail: format!(
                                "the checker rejected the sub-certificate for goal {} ({}): {}",
                                g.id,
                                g.as_written,
                                truncate(stdout.trim(), 400)
                            ),
                            means: CERTIFICATE_REJECTED_MEANS,
                        });
                        GoalVerdict::CertificateRejected
                    }
                    CheckerStatus::Unreadable { .. }
                    | CheckerStatus::Absent { .. }
                    | CheckerStatus::NotNeeded { .. } => GoalVerdict::PreservedUnchecked,
                };
                if checker_status.is_none() || matches!(status, CheckerStatus::Rejected { .. }) {
                    checker_status = Some(status);
                }
                v
            }
        };
        let outside = !seed_terms.is_empty()
            && ![&g.triple.0, &g.triple.1, &g.triple.2].iter().any(|t| seed_terms.contains(t.as_str()));
        per_goal.push(GoalReport {
            id: g.id.clone(),
            as_written: g.as_written.clone(),
            goal: format!("{} {} {}", g.triple.0, g.triple.1, g.triple.2),
            source,
            projection,
            // All three read before the move. The verdict may carry a token,
            // and this row is the one place it belongs.
            warrant: verdict.warrant(),
            means: verdict.means(),
            certificate,
            bounded_by_iteration_cap: bounded && !verdict.is_preserved(),
            goal_outside_seed_neighbourhood: outside,
            // Last, because it MOVES: the token this verdict may carry belongs
            // to this row and to nothing after it.
            verdict,
        });
    }

    let checker = checker_status.unwrap_or_else(|| {
        // No goal needed a checker run. Say what would have happened rather
        // than imply one was consulted.
        match find_checker(prj_cert.kind(), opts.checker.as_deref()) {
            Ok(p) => CheckerStatus::NotNeeded {
                what: format!(
                    "{} was found and no goal needed it: no preserved goal was DERIVED, so there \
                     was no sub-certificate to check",
                    p.display()
                ),
            },
            Err(why) => CheckerStatus::Absent { what: why, install: LAKE_INSTALL },
        }
    });
    if opts.require_checker && checker.is_absent() {
        anyhow::bail!(
            "require_checker was set and the checker is absent: {}. {LAKE_INSTALL}",
            match &checker {
                CheckerStatus::Absent { what, .. } => what.as_str(),
                _ => "",
            }
        );
    }

    // ── The demoted proxy ───────────────────────────────────────────────
    let coverage_proxy = coverage_proxy(graph, &opts.seed_iris, &projected_ttl);

    // ── Counts and the verdict on the run ───────────────────────────────
    let count = |f: fn(&GoalVerdict) -> bool| per_goal.iter().filter(|g| f(&g.verdict)).count();
    let preserved_checked = count(|v| {
        matches!(
            v,
            GoalVerdict::PreservedChecked(_) | GoalVerdict::PreservedUnderSuppliedRulesChecked(_)
        )
    });
    let preserved_asserted = count(|v| *v == GoalVerdict::PreservedAsserted);
    let preserved_unchecked = count(|v| *v == GoalVerdict::PreservedUnchecked);
    let lost = count(|v| *v == GoalVerdict::LostUnderProfileUnchecked);
    let ungrounded = count(|v| *v == GoalVerdict::UngroundedInSource);
    let projection_only = count(|v| *v == GoalVerdict::ProjectionOnly);
    let certificate_rejected = count(|v| *v == GoalVerdict::CertificateRejected);

    let exit_code = if stop_the_line.is_some() {
        2
    } else if lost + ungrounded + projection_only + certificate_rejected + refused.len() > 0 {
        1
    } else {
        0
    };
    let ok = exit_code == 0;


    let headline = format!(
        "{preserved_checked} of {} goal(s) preserved with a machine-checked certificate, \
         {preserved_asserted} preserved by assertion, {preserved_unchecked} preserved on the \
         engine's word alone, {lost} LOST by the projection, {ungrounded} UNGROUNDED IN THE \
         SOURCE, {} refused. Monotonicity gate: {}{}. {}",
        goals.len(),
        refused.len(),
        mono.status,
        if mono.reason.is_empty() { String::new() } else { format!(" ({})", mono.reason) },
        COVERAGE_LABEL,
    );

    Ok(PreservationReport {
        format: "oo-preserve/1",
        headline,
        profile: if opts.rules.is_some() { "supplied-horn-table".into() } else { opts.profile.clone() },
        rules: opts.rules.as_ref().map(|p| p.display().to_string()),
        rules_sha256: prj_run.rules_sha256.clone().or(src_run.rules_sha256.clone()),
        goals_total: goals.len(),
        preserved_checked,
        preserved_asserted,
        preserved_unchecked,
        lost,
        ungrounded_in_source: ungrounded,
        projection_only,
        certificate_rejected,
        refused: refused.len(),
        per_goal,
        refused_goals: refused.to_vec(),
        subset,
        monotonicity: mono,
        disagreement: stop_the_line,
        coverage_proxy,
        checker,
        source_hygiene: hygiene,
        source_fixpoint_reached: src_run.fixpoint_reached,
        projection_fixpoint_reached: prj_run.fixpoint_reached,
        source_iterations: src_run.iterations,
        projection_iterations: prj_run.iterations,
        iteration_cap: crate::runtime::reasoner_max_iterations(),
        work_dir: work.display().to_string(),
        limits: LIMITS,
        ok,
        exit_code,
    })
}

fn check_command(cert: &CertificateIndex, slice: &Path) -> String {
    match cert.kind() {
        CertKind::OoCert => format!(
            "cd lean && lake exe oo-cert {} {}",
            cert.asserted_path().display(),
            slice.display()
        ),
        CertKind::OoHorn => format!(
            "cd lean && lake exe oo-horn check {} {} {}",
            cert.rules_path().display(),
            cert.asserted_path().display(),
            slice.display()
        ),
    }
}

/// Build the demoted coverage block. Always carries [`COVERAGE_LABEL`], even
/// when the number itself could not be computed.
pub fn coverage_proxy(
    graph: &Arc<GraphStore>,
    seed_iris: &[String],
    projected_ttl: &str,
) -> CoverageProxy {
    if seed_iris.is_empty() {
        return CoverageProxy {
            report: None,
            not_computed_because: Some(
                "no seed IRIs were supplied. An aggregate over zero seeds is trivially 1.0 or \
                 trivially 0.0 depending on how it is written, and neither says anything"
                    .into(),
            ),
            is_a_warrant: false,
            label: COVERAGE_LABEL,
            truncated_seeds: Vec::new(),
            known_limits: PROXY_LIMITS,
        };
    }
    match check_projection_loss(graph, seed_iris, projected_ttl) {
        Ok(r) => {
            // A seed at exactly the LIMIT is the one whose ratio was computed
            // against a truncated source.
            let truncated: Vec<String> = r
                .per_seed
                .iter()
                .filter(|s| s.source_triples >= 1000)
                .map(|s| s.seed_iri.clone())
                .collect();
            let missing = if r.projection_parses {
                None
            } else {
                Some("the slice did not parse as Turtle, so no ratio was computed".to_string())
            };
            CoverageProxy {
                report: if r.projection_parses { Some(r) } else { None },
                not_computed_because: missing,
                is_a_warrant: false,
                label: COVERAGE_LABEL,
                truncated_seeds: truncated,
                known_limits: PROXY_LIMITS,
            }
        }
        Err(e) => CoverageProxy {
            report: None,
            not_computed_because: Some(format!("the proxy could not be computed: {e}")),
            is_a_warrant: false,
            label: COVERAGE_LABEL,
            truncated_seeds: Vec::new(),
            known_limits: PROXY_LIMITS,
        },
    }
}

/// Terms any seed's outbound neighbourhood mentions, plus the seeds. Empty when
/// no seeds were given, in which case no goal is ever reported outside it.
fn seed_neighbourhood_terms(graph: &Arc<GraphStore>, seeds: &[String]) -> HashSet<String> {
    let mut terms = HashSet::new();
    for s in seeds {
        terms.insert(format!("<{s}>"));
        let q = format!("SELECT DISTINCT ?p ?o WHERE {{ <{s}> ?p ?o }} LIMIT 1000");
        let Ok(js) = graph.sparql_select(&q) else { continue };
        let Ok(v) = serde_json::from_str::<serde_json::Value>(&js) else { continue };
        if let Some(rows) = v["results"].as_array() {
            for row in rows {
                for k in ["p", "o"] {
                    if let Some(t) = row[k].as_str() {
                        terms.insert(t.to_string());
                    }
                }
            }
        }
    }
    terms
}

#[cfg(test)]
mod tests {
    use super::*;

    fn loaded(ttl: &str) -> Arc<GraphStore> {
        let g = Arc::new(GraphStore::new());
        g.load_turtle(ttl, None).expect("load");
        g
    }

    fn scratch(name: &str) -> PathBuf {
        let d = std::env::temp_dir()
            .join(format!("oo-preserve-unit-{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&d);
        std::fs::create_dir_all(&d).unwrap();
        d
    }

    const SRC: &str = r#"
        @prefix : <http://ex.org/> .
        @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
        :A rdfs:subClassOf :B . :B rdfs:subClassOf :C . :a a :A .
    "#;

    #[test]
    fn a_turtle_goal_round_trips_through_the_store_parser() {
        let (goals, refused) = parse_goals_turtle(
            "@prefix : <http://ex.org/> .\n:a a :C .\n",
        )
        .unwrap();
        assert!(refused.is_empty(), "{refused:?}");
        assert_eq!(goals.len(), 1);
        assert_eq!(
            goals[0].triple,
            (
                "<http://ex.org/a>".into(),
                "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>".into(),
                "<http://ex.org/C>".into()
            )
        );
    }

    #[test]
    fn a_blank_node_goal_is_refused_by_name() {
        let (goals, refused) =
            parse_goals_turtle("@prefix : <http://ex.org/> .\n:a :p [ :q :r ] .\n").unwrap();
        assert!(goals.is_empty(), "{goals:?}");
        assert!(refused.iter().any(|r| r.reason == GoalRefusal::BlankNode), "{refused:?}");
    }

    #[test]
    fn a_negative_claim_is_refused_and_points_at_shacl() {
        let (goals, refused) = parse_goals_tsv(
            "NOT <http://ex.org/s>\t<http://ex.org/p>\t<http://ex.org/o>\n",
            0,
        )
        .unwrap();
        assert!(goals.is_empty());
        assert_eq!(refused[0].reason, GoalRefusal::NotAPositiveGroundTriple);
        assert!(refused[0].means.contains("onto_shacl"), "{:?}", refused[0]);
    }

    #[test]
    fn a_derivations_tsv_pipes_in_with_one_skipped_column() {
        // The shape `reason --certificate` writes: the rule name, then the
        // conclusion, then the premises. Only the conclusion is a goal, so the
        // extra triples on the line must be ignored rather than read as three
        // more goals.
        let line = "rdfs9\t<http://ex.org/a>\t<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>\t                    <http://ex.org/C>\t<http://ex.org/a>\t                    <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>\t<http://ex.org/A>\n";
        let (goals, refused) = parse_goals_tsv(line, 1).unwrap();
        assert!(refused.is_empty(), "{refused:?}");
        assert_eq!(goals.len(), 1, "one line is one goal, not one per triple on it");
        assert_eq!(goals[0].triple.2, "<http://ex.org/C>");
        // And the caller's own bytes survive beside the canonical spelling.
        assert!(goals[0].as_written.contains("http://ex.org/a"));
    }

    #[test]
    fn a_short_tsv_line_is_refused_rather_than_padded() {
        let (goals, refused) = parse_goals_tsv("<http://ex.org/a>\t<http://ex.org/p>\n", 0).unwrap();
        assert!(goals.is_empty());
        assert_eq!(refused[0].reason, GoalRefusal::Unparseable);
    }

    #[test]
    fn goals_come_out_of_a_bgp_and_its_bindings_with_no_generator_trusted() {
        // The strongest goal source: the query the answer was rendered from,
        // with the answer's own bindings put back. Nothing here trusts a
        // language model with anything.
        let bgp = vec![
            ("?x".to_string(), "<http://ex.org/p>".to_string(), "<http://ex.org/o>".to_string()),
            ("?y".to_string(), "<http://ex.org/q>".to_string(), "?z".to_string()),
        ];
        let mut b = BTreeMap::new();
        b.insert("x".to_string(), "<http://ex.org/a>".to_string());
        b.insert("y".to_string(), "<http://ex.org/b>".to_string());
        let (goals, refused) = goals_from_bindings(&bgp, &b).unwrap();
        assert_eq!(goals.len(), 1, "only the fully bound pattern is askable: {goals:?}");
        assert_eq!(goals[0].triple.0, "<http://ex.org/a>");
        assert_eq!(
            refused.len(),
            1,
            "an unbound variable is refused BY NAME rather than dropped: {refused:?}"
        );
        assert_eq!(refused[0].reason, GoalRefusal::Unparseable);
        assert!(refused[0].as_written.contains("?z"), "{:?}", refused[0]);
    }

    #[test]
    fn an_empty_goal_set_is_an_error_not_a_green_report() {
        let g = loaded(SRC);
        let err = check_entailment_preservation(
            &g,
            Projection::Turtle(SRC),
            &[],
            &[],
            &Opts { work_dir: scratch("empty"), ..Default::default() },
        )
        .expect_err("zero goals must not produce a report");
        assert!(err.to_string().contains("no goals to ask"), "{err}");
    }

    #[test]
    fn the_differential_can_fire() {
        // The engine cannot be made unsound on demand, so the gate is shown
        // able to fail on the PURE function with a hand-built pair.
        let t = |s: &str| (s.to_string(), "<p>".to_string(), "<o>".to_string());
        let src: HashSet<Spelled> = [t("<a>")].into_iter().collect();
        let prj: HashSet<Spelled> = [t("<a>"), t("<ghost>")].into_iter().collect();
        let r = differential(
            &src,
            &prj,
            Guards { subset_verified: true, blank_nodes_unmatched: false, both_reached_fixpoint: true },
        );
        assert_eq!(r.status, "armed");
        assert_eq!(r.violation_count, 1);
        let d = r.disagreement.expect("a violation must produce a disagreement block");
        assert_eq!(d.severity, STOP_THE_LINE);
        assert_eq!(d.what, "monotonicity_violated");
    }

    #[test]
    fn every_guard_disarms_the_differential_with_its_own_reason() {
        let t = |s: &str| (s.to_string(), "<p>".to_string(), "<o>".to_string());
        let src: HashSet<Spelled> = HashSet::new();
        let prj: HashSet<Spelled> = [t("<ghost>")].into_iter().collect();
        for (g, why) in [
            (
                Guards { subset_verified: false, blank_nodes_unmatched: false, both_reached_fixpoint: true },
                "projection_is_not_a_subset",
            ),
            (
                Guards { subset_verified: true, blank_nodes_unmatched: true, both_reached_fixpoint: true },
                "blank_nodes_unmatched",
            ),
            (
                Guards { subset_verified: true, blank_nodes_unmatched: false, both_reached_fixpoint: false },
                "fixpoint_not_reached",
            ),
        ] {
            let r = differential(&src, &prj, g);
            assert_eq!(r.status, "disarmed", "{why}");
            assert_eq!(r.reason, why);
            assert!(r.disagreement.is_none(), "a disarmed gate must not accuse the engine");
        }
    }

    #[test]
    fn skolemising_survives_a_turtle_round_trip_and_canonicalising_would_not() {
        let g = loaded(
            r#"@prefix : <http://ex.org/> .
               @prefix owl: <http://www.w3.org/2002/07/owl#> .
               @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
               :C rdfs:subClassOf [ a owl:Restriction ; owl:onProperty :p ; owl:someValuesFrom :D ] .
               :E rdfs:subClassOf :C ."#,
        );
        let (sk, map) = skolemise(&g).unwrap();
        assert!(!map.is_empty(), "the source had blank nodes to skolemise");
        let ttl = sk.serialize("turtle").unwrap();
        let reparsed = GraphStore::new();
        reparsed.load_turtle(&ttl, None).unwrap();
        let a: BTreeSet<Spelled> = sk.all_triples().unwrap().into_iter().collect();
        let b: BTreeSet<Spelled> = reparsed.all_triples().unwrap().into_iter().collect();
        assert_eq!(a, b, "a skolemised graph must survive a Turtle round trip unchanged");
    }
}