Skip to main content

qualia_core_db/q42/chebi_map/
report.rs

1//! Validation / mapping report types for ChEBI → Quin (AST-04).
2//!
3//! Cold construction: heap `String` / `Vec` fields are intentional. The hot
4//! projection path writes only into the caller-supplied `&mut [NQuin]` buffer.
5
6use std::fmt;
7
8/// Caller ceilings for one mapping pass.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub struct MapBudgets {
11    /// Maximum Quins this pass may write (also limited by `out.len()`).
12    pub max_quins: usize,
13    /// Maximum conflicts retained in the report before fail-closed.
14    pub max_conflicts: usize,
15}
16
17impl MapBudgets {
18    /// Reject zero ceilings (fail closed before any work).
19    pub fn validate(self) -> Result<Self, MapError> {
20        if self.max_quins == 0 || self.max_conflicts == 0 {
21            return Err(MapError::InvalidBudgets);
22        }
23        Ok(self)
24    }
25}
26
27/// One identifier collision or mapping refusal inside a batch.
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub struct MapConflict {
30    /// Accession string involved (may be empty when only numeric id collided).
31    pub accession: String,
32    /// Stable reason code (no formatted heap strings).
33    pub reason: &'static str,
34}
35
36/// Bounded lexicon / hash note for a surface string projected as a 60-bit object.
37///
38/// Names and accessions are stored as `q_hash` / 60-bit tokens in Quin fields;
39/// this cold side-table preserves the original surface for evidence display.
40#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct LexiconEntry {
42    /// 60-bit token written into a Quin field.
43    pub hash: u64,
44    /// Original surface text.
45    pub surface: String,
46    /// Role: `"accession"`, `"name"`, `"release"`, or `"parent"`.
47    pub kind: &'static str,
48}
49
50/// Result of a successful (possibly partially conflicted) mapping pass.
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct MapReport {
53    pub quins_written: usize,
54    pub records_mapped: usize,
55    pub conflicts: Vec<MapConflict>,
56    pub lexicon: Vec<LexiconEntry>,
57    pub release_label: String,
58}
59
60/// Fail-closed errors for ChEBI Quin mapping.
61#[derive(Debug, Clone, PartialEq, Eq)]
62pub enum MapError {
63    /// Budget fields must be strictly positive.
64    InvalidBudgets,
65    /// Caller buffer / `max_quins` cannot hold the next record's Quins.
66    OutputFull {
67        written: usize,
68        needed: usize,
69        capacity: usize,
70    },
71    /// Conflict list would exceed [`MapBudgets::max_conflicts`].
72    ConflictBudgetExceeded { used: usize, max: usize },
73}
74
75impl fmt::Display for MapError {
76    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77        match self {
78            Self::InvalidBudgets => write!(f, "map budgets must be positive"),
79            Self::OutputFull {
80                written,
81                needed,
82                capacity,
83            } => write!(
84                f,
85                "quin output full (written={written}, needed={needed}, capacity={capacity})"
86            ),
87            Self::ConflictBudgetExceeded { used, max } => {
88                write!(f, "conflict budget exceeded (used={used}, max={max})")
89            }
90        }
91    }
92}
93
94impl std::error::Error for MapError {}