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 {}