Skip to main content

qualia_core_db/q42/species_corpus/
model.rs

1//! Species knowledge corpus: sources, evidenced assertions and recorded gaps for one taxon
2//! concept at a stated revision. Stored natively as a unified `.q42` volume (see [`super::codec`]);
3//! CBOR-LD is the interchange projection.
4
5use std::collections::{BTreeMap, BTreeSet};
6
7use qualia_cooperative_core::contextual_evidence::{ClaimBasis, EvidenceValue, EvidencedAssertion};
8use serde::{Deserialize, Serialize};
9
10use crate::q42_volume::IngestProvenanceRecord;
11
12pub const SPECIES_CORPUS_CONTEXT: &str = "https://webizen.org/ns/qualia/species-corpus/v1";
13pub const SPECIES_CORPUS_TYPE: &str = "QualiaSpeciesCorpus";
14pub const SPECIES_CORPUS_FORMAT: &str = "qualia.q42.species-corpus.v1";
15pub const MAX_CORPUS_ASSERTIONS: usize = 1_000_000;
16
17/// One acquired source. Integrity fields mirror [`IngestProvenanceRecord`].
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub struct CorpusSource {
20    pub id: String,
21    pub title: String,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub citation: Option<String>,
24    #[serde(default, skip_serializing_if = "Option::is_none")]
25    pub retrieved_at: Option<String>,
26    pub access_policy: String,
27    pub source_sha256: String,
28    pub mapping_version: String,
29    #[serde(default, skip_serializing_if = "Option::is_none")]
30    pub licence_iri: Option<String>,
31}
32
33impl CorpusSource {
34    /// Builds a source entry from an existing ingest provenance record.
35    pub fn from_ingest(id: &str, title: &str, record: &IngestProvenanceRecord) -> Self {
36        Self {
37            id: id.to_string(),
38            title: title.to_string(),
39            citation: None,
40            retrieved_at: None,
41            access_policy: record.access_policy.clone(),
42            source_sha256: record.source_sha256.clone(),
43            mapping_version: record.mapping_version.clone(),
44            licence_iri: None,
45        }
46    }
47}
48
49/// Knowledge group from the species embodiment specification.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
51#[serde(rename_all = "snake_case")]
52pub enum KnowledgeGroup {
53    IdentifiersTaxonomy,
54    MorphologyAnatomy,
55    DevelopmentReproduction,
56    PhysiologyBehaviour,
57    Ecology,
58    DistributionObservations,
59    MolecularCellular,
60    ConservationHumanRelations,
61    RepresentationsMedia,
62    ProvenanceOperation,
63}
64
65/// A known absence: the corpus does not hold evidence for this property/scope.
66#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67pub struct KnowledgeGap {
68    pub id: String,
69    pub group: KnowledgeGroup,
70    pub property_iri: String,
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    pub part_iri: Option<String>,
73    pub reason: String,
74}
75
76/// One active or inactive fact, flattened so callers do not depend on the evidence enum.
77#[derive(Debug, Clone, PartialEq)]
78pub struct CorpusFact<'a> {
79    pub assertion_id: &'a str,
80    pub property_iri: &'a str,
81    pub basis: &'a str,
82    pub active: bool,
83    pub min: Option<f64>,
84    pub max: Option<f64>,
85    pub unit_iri: Option<&'a str>,
86    pub text: Option<&'a str>,
87}
88
89/// Assertions for one property and scope whose values disagree across independent sources.
90#[derive(Debug, Clone, PartialEq, Eq)]
91pub struct CorpusConflict {
92    pub property_iri: String,
93    pub scope_key: String,
94    pub assertion_ids: Vec<String>,
95}
96
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98pub struct SpeciesCorpus {
99    #[serde(rename = "@context")]
100    pub context: String,
101    #[serde(rename = "@type")]
102    pub type_: String,
103    pub format: String,
104    pub corpus_iri: String,
105    pub taxon_concept_iri: String,
106    pub species_id: String,
107    pub revision: String,
108    #[serde(default)]
109    pub sources: Vec<CorpusSource>,
110    #[serde(default)]
111    pub assertions: Vec<EvidencedAssertion>,
112    #[serde(default)]
113    pub gaps: Vec<KnowledgeGap>,
114}
115
116fn require(v: &str, what: &str) -> Result<(), String> {
117    if v.trim().is_empty() {
118        Err(format!("species corpus {what} is empty"))
119    } else {
120        Ok(())
121    }
122}
123
124fn unique<'a>(ids: impl Iterator<Item = &'a str>, what: &str) -> Result<BTreeSet<&'a str>, String> {
125    let mut seen = BTreeSet::new();
126    for id in ids {
127        require(id, &format!("{what} id"))?;
128        if !seen.insert(id) {
129            return Err(format!("duplicate {what} id '{id}'"));
130        }
131    }
132    Ok(seen)
133}
134
135impl SpeciesCorpus {
136    pub fn new(corpus_iri: &str, taxon_concept_iri: &str, species_id: &str, revision: &str) -> Self {
137        Self {
138            context: SPECIES_CORPUS_CONTEXT.to_string(),
139            type_: SPECIES_CORPUS_TYPE.to_string(),
140            format: SPECIES_CORPUS_FORMAT.to_string(),
141            corpus_iri: corpus_iri.to_string(),
142            taxon_concept_iri: taxon_concept_iri.to_string(),
143            species_id: species_id.to_string(),
144            revision: revision.to_string(),
145            sources: Vec::new(),
146            assertions: Vec::new(),
147            gaps: Vec::new(),
148        }
149    }
150
151    /// Decodes a JSON-LD document of this shape and validates it.
152    pub fn from_json_value(value: serde_json::Value) -> Result<Self, String> {
153        let corpus: Self =
154            serde_json::from_value(value).map_err(|e| format!("species corpus json: {e}"))?;
155        corpus.validate()?;
156        Ok(corpus)
157    }
158
159    /// Checks identity, unique ids, per-assertion evidence, source references and taxon binding.
160    pub fn validate(&self) -> Result<(), String> {
161        if self.context != SPECIES_CORPUS_CONTEXT || self.format != SPECIES_CORPUS_FORMAT {
162            return Err("not a species corpus v1 document".into());
163        }
164        require(&self.corpus_iri, "corpus_iri")?;
165        require(&self.taxon_concept_iri, "taxon_concept_iri")?;
166        require(&self.species_id, "species_id")?;
167        require(&self.revision, "revision")?;
168        if self.assertions.len() > MAX_CORPUS_ASSERTIONS {
169            return Err(format!("species corpus exceeds {MAX_CORPUS_ASSERTIONS} assertions"));
170        }
171        let source_ids = unique(self.sources.iter().map(|s| s.id.as_str()), "source")?;
172        unique(self.assertions.iter().map(|a| a.assertion.id.as_str()), "assertion")?;
173        unique(self.gaps.iter().map(|g| g.id.as_str()), "gap")?;
174        for s in &self.sources {
175            require(&s.title, &format!("source '{}' title", s.id))?;
176            if s.source_sha256.len() != 64 || !s.source_sha256.bytes().all(|b| b.is_ascii_hexdigit()) {
177                return Err(format!("source '{}' source_sha256 must be 64 hex digits", s.id));
178            }
179        }
180        for ea in &self.assertions {
181            let id = &ea.assertion.id;
182            ea.validate().map_err(|e| format!("assertion '{id}': {e}"))?;
183            let root = ea.assertion.root_source_id.as_str();
184            if !root.is_empty() && !source_ids.contains(root) {
185                return Err(format!("assertion '{id}' cites unknown source '{root}'"));
186            }
187            if let Some(t) = &ea.evidence.scope.taxon_concept_iri {
188                if t != &self.taxon_concept_iri {
189                    return Err(format!(
190                        "assertion '{id}' is scoped to taxon '{t}', not the corpus taxon"
191                    ));
192                }
193            }
194        }
195        for g in &self.gaps {
196            require(&g.property_iri, &format!("gap '{}' property_iri", g.id))?;
197            require(&g.reason, &format!("gap '{}' reason", g.id))?;
198        }
199        Ok(())
200    }
201
202    /// Flattens every assertion into a fact a production reader can use without the evidence crate.
203    pub fn facts(&self) -> Vec<CorpusFact<'_>> {
204        use qualia_cooperative_core::contextual_assertion::AssertionStatus;
205        use qualia_cooperative_core::contextual_evidence::EvidenceValue;
206        self.assertions
207            .iter()
208            .map(|a| {
209                let (min, max, unit_iri, text) = match &a.evidence.value {
210                    Some(EvidenceValue::Quantity { value, unit_iri }) => {
211                        (Some(*value), Some(*value), Some(unit_iri.as_str()), None)
212                    }
213                    Some(EvidenceValue::Range { min, max, unit_iri }) => {
214                        (Some(*min), Some(*max), Some(unit_iri.as_str()), None)
215                    }
216                    Some(EvidenceValue::Text { text, .. }) => (None, None, None, Some(text.as_str())),
217                    Some(EvidenceValue::Iri { iri }) => (None, None, None, Some(iri.as_str())),
218                    None => (None, None, None, None),
219                };
220                CorpusFact {
221                    assertion_id: a.assertion.id.as_str(),
222                    property_iri: a.evidence.property_iri.as_str(),
223                    basis: a.evidence.basis.as_str(),
224                    active: a.assertion.assertion_status == AssertionStatus::Active,
225                    min,
226                    max,
227                    unit_iri,
228                    text,
229                }
230            })
231            .collect()
232    }
233
234    /// Active assertions for `property_iri`, optionally restricted to a part.
235    pub fn assertions_for<'a>(
236        &'a self,
237        property_iri: &'a str,
238        part_iri: Option<&'a str>,
239    ) -> impl Iterator<Item = &'a EvidencedAssertion> + 'a {
240        use qualia_cooperative_core::contextual_assertion::AssertionStatus;
241        self.assertions.iter().filter(move |a| {
242            a.evidence.property_iri == property_iri
243                && a.assertion.assertion_status == AssertionStatus::Active
244                && part_iri.map_or(true, |p| a.evidence.scope.part_iri.as_deref() == Some(p))
245        })
246    }
247
248    /// Finds properties whose evidence-basis values disagree across independent root sources.
249    /// Model assumptions, artistic choices and unknowns are not evidence and are excluded.
250    pub fn conflicts(&self) -> Vec<CorpusConflict> {
251        let mut groups: BTreeMap<(String, String), Vec<&EvidencedAssertion>> = BTreeMap::new();
252        for a in &self.assertions {
253            if matches!(
254                a.evidence.basis,
255                ClaimBasis::ModelAssumption | ClaimBasis::ArtisticChoice | ClaimBasis::Unknown
256            ) || a.evidence.value.is_none()
257            {
258                continue;
259            }
260            let s = &a.evidence.scope;
261            let scope_key = format!(
262                "{}|{}|{}|{}|{}",
263                s.part_iri.as_deref().unwrap_or(""),
264                s.life_stage_iri.as_deref().unwrap_or(""),
265                s.sex_iri.as_deref().unwrap_or(""),
266                s.population_iri.as_deref().unwrap_or(""),
267                s.individual_iri.as_deref().unwrap_or("")
268            );
269            groups
270                .entry((a.evidence.property_iri.clone(), scope_key))
271                .or_default()
272                .push(a);
273        }
274        let mut out = Vec::new();
275        for ((property_iri, scope_key), items) in groups {
276            let roots: BTreeSet<&str> =
277                items.iter().map(|a| a.assertion.root_source_id.as_str()).collect();
278            if roots.len() < 2 {
279                continue;
280            }
281            let first = items[0].evidence.value.as_ref();
282            if items.iter().any(|a| !values_compatible(first, a.evidence.value.as_ref())) {
283                out.push(CorpusConflict {
284                    property_iri,
285                    scope_key,
286                    assertion_ids: items.iter().map(|a| a.assertion.id.clone()).collect(),
287                });
288            }
289        }
290        out
291    }
292}
293
294/// Values agree when equal, or for numeric values when their ranges overlap in the same unit.
295fn values_compatible(a: Option<&EvidenceValue>, b: Option<&EvidenceValue>) -> bool {
296    fn span(v: &EvidenceValue) -> Option<(f64, f64, &str)> {
297        match v {
298            EvidenceValue::Quantity { value, unit_iri } => Some((*value, *value, unit_iri)),
299            EvidenceValue::Range { min, max, unit_iri } => Some((*min, *max, unit_iri)),
300            _ => None,
301        }
302    }
303    match (a, b) {
304        (Some(x), Some(y)) => match (span(x), span(y)) {
305            (Some((a0, a1, ua)), Some((b0, b1, ub))) => ua == ub && a0 <= b1 && b0 <= a1,
306            _ => x == y,
307        },
308        _ => true,
309    }
310}