Skip to main content

qualia_core_db/q42/species_corpus/
builder.rs

1//! Assembles one species `.q42` from ingest provenance and evidenced assertions.
2//!
3//! Conflicts are not resolved here. Every assertion is kept, and [`SpeciesCorpus::conflicts`]
4//! lists properties whose evidence disagrees across independent sources. A caller that names
5//! an expected property with no assertion records that absence as a gap.
6
7use qualia_cooperative_core::contextual_evidence::EvidencedAssertion;
8
9use super::model::{
10    CorpusSource, KnowledgeGap, KnowledgeGroup, SpeciesCorpus, MAX_CORPUS_ASSERTIONS,
11};
12use crate::q42_volume::IngestProvenanceRecord;
13
14/// Collects sources, assertions and gaps, then validates them as one corpus.
15#[derive(Debug, Clone)]
16pub struct SpeciesCorpusBuilder {
17    corpus: SpeciesCorpus,
18}
19
20impl SpeciesCorpusBuilder {
21    pub fn new(corpus_iri: &str, taxon_concept_iri: &str, species_id: &str, revision: &str) -> Self {
22        Self {
23            corpus: SpeciesCorpus::new(corpus_iri, taxon_concept_iri, species_id, revision),
24        }
25    }
26
27    pub fn source(mut self, source: CorpusSource) -> Self {
28        self.corpus.sources.push(source);
29        self
30    }
31
32    /// Adds a source whose integrity fields come from an ingest provenance record.
33    pub fn source_from_ingest(
34        self,
35        id: &str,
36        title: &str,
37        record: &IngestProvenanceRecord,
38    ) -> Self {
39        self.source(CorpusSource::from_ingest(id, title, record))
40    }
41
42    pub fn assertion(mut self, assertion: EvidencedAssertion) -> Self {
43        self.corpus.assertions.push(assertion);
44        self
45    }
46
47    pub fn gap(mut self, gap: KnowledgeGap) -> Self {
48        self.corpus.gaps.push(gap);
49        self
50    }
51
52    /// Records a gap when no assertion covers `property_iri` (and `part_iri`, when set).
53    pub fn gap_if_missing(
54        self,
55        id: &str,
56        group: KnowledgeGroup,
57        property_iri: &str,
58        part_iri: Option<&str>,
59        reason: &str,
60    ) -> Self {
61        let covered = self.corpus.assertions.iter().any(|a| {
62            a.evidence.property_iri == property_iri
63                && part_iri.map_or(true, |p| a.evidence.scope.part_iri.as_deref() == Some(p))
64        });
65        if covered {
66            self
67        } else {
68            self.gap(KnowledgeGap {
69                id: id.to_string(),
70                group,
71                property_iri: property_iri.to_string(),
72                part_iri: part_iri.map(str::to_string),
73                reason: reason.to_string(),
74            })
75        }
76    }
77
78    /// Validates the collected corpus. Disagreement between sources is kept, not rejected.
79    pub fn build(self) -> Result<SpeciesCorpus, String> {
80        if self.corpus.assertions.len() > MAX_CORPUS_ASSERTIONS {
81            return Err(format!("species corpus exceeds {MAX_CORPUS_ASSERTIONS} assertions"));
82        }
83        self.corpus.validate()?;
84        Ok(self.corpus)
85    }
86}