Skip to main content

qualia_core_db/q42/chebi_map/
map.rs

1//! ChEBI record → evidence-preserving Quin projection (AST-04).
2//!
3//! # Predicate IRIs (via [`crate::q_hash`], 60-bit)
4//!
5//! | Role | IRI |
6//! |------|-----|
7//! | Type | `rdf:type` → class `chebi:Compound` |
8//! | Accession | `chebi:accession` → 60-bit hash of accession string |
9//! | Name | `chebi:hasName` → 60-bit hash of display name |
10//! | Parent | `chebi:hasParent` → 60-bit hash of `CHEBI:{parent_id}` |
11//! | Provenance | `chebi:fromRelease` → 60-bit hash of `release_label`; `metadata` low 32 bits = `source_line` |
12//!
13//! # Layout per accepted record
14//!
15//! Always emits **4** Quins (type, accession, hasName, fromRelease). When
16//! `parent_id` is `Some`, emits one more (`hasParent`). Subject for all is
17//! `q_hash(accession)`. Graph `context` is `q_hash(release_label)`.
18//!
19//! Parity is the AGENTS.md XOR fold: `subject ^ predicate ^ object ^ context`.
20//! Object IRI/name hashes use the same 60-bit mask as `q_hash` (top 4 bits free
21//! for inline tags — not set here).
22//!
23//! Duplicate `id` or `accession` in one batch → [`MapConflict`], first mapping
24//! retained (no silent overwrite).
25
26use crate::q42::chebi_parse::ChebiRecord;
27use crate::{q_hash, NQuin};
28
29use super::report::{LexiconEntry, MapBudgets, MapConflict, MapError, MapReport};
30
31/// Quins emitted for every mapped record (type, accession, name, provenance).
32pub const QUINS_PER_RECORD_BASE: usize = 4;
33
34/// Predicate: RDF typing.
35pub const PRED_RDF_TYPE: &str = "rdf:type";
36/// Object class for a ChEBI compound.
37pub const CLASS_CHEBI_COMPOUND: &str = "chebi:Compound";
38/// Predicate: accession string evidence.
39pub const PRED_ACCESSION: &str = "chebi:accession";
40/// Predicate: display name (hashed; surface in lexicon note).
41pub const PRED_HAS_NAME: &str = "chebi:hasName";
42/// Predicate: parent compound accession hash.
43pub const PRED_HAS_PARENT: &str = "chebi:hasParent";
44/// Predicate: release provenance; source_line in metadata.
45pub const PRED_FROM_RELEASE: &str = "chebi:fromRelease";
46
47/// How many Quins one record would emit (including optional parent).
48#[inline]
49pub fn quins_for_record(record: &ChebiRecord) -> usize {
50    QUINS_PER_RECORD_BASE + usize::from(record.parent_id.is_some())
51}
52
53/// Format `CHEBI:{id}` into a caller stack buffer; returns the UTF-8 prefix used.
54fn format_chebi_accession(id: u64, buf: &mut [u8; 32]) -> &str {
55    const PREFIX: &[u8] = b"CHEBI:";
56    buf[..PREFIX.len()].copy_from_slice(PREFIX);
57    let mut n = id;
58    let mut digits = [0u8; 20];
59    let mut dlen = 0usize;
60    if n == 0 {
61        digits[0] = b'0';
62        dlen = 1;
63    } else {
64        while n > 0 {
65            digits[dlen] = b'0' + (n % 10) as u8;
66            dlen += 1;
67            n /= 10;
68        }
69        digits[..dlen].reverse();
70    }
71    let total = PREFIX.len() + dlen;
72    debug_assert!(total <= buf.len());
73    buf[PREFIX.len()..total].copy_from_slice(&digits[..dlen]);
74    // SAFETY: PREFIX + ASCII digits are always valid UTF-8.
75    core::str::from_utf8(&buf[..total]).unwrap_or("CHEBI:0")
76}
77
78#[inline]
79fn parity_fold(q: &NQuin) -> u64 {
80    q.subject ^ q.predicate ^ q.object ^ q.context
81}
82
83#[inline]
84fn write_quin(
85    out: &mut [NQuin],
86    idx: usize,
87    subject: u64,
88    predicate: u64,
89    object: u64,
90    context: u64,
91    metadata: u64,
92) {
93    let mut q = NQuin {
94        subject,
95        predicate,
96        object,
97        context,
98        metadata,
99        parity: 0,
100    };
101    q.parity = parity_fold(&q);
102    out[idx] = q;
103}
104
105fn push_lexicon(lexicon: &mut Vec<LexiconEntry>, hash: u64, surface: &str, kind: &'static str) {
106    lexicon.push(LexiconEntry {
107        hash,
108        surface: surface.to_owned(),
109        kind,
110    });
111}
112
113fn push_conflict(
114    conflicts: &mut Vec<MapConflict>,
115    budgets: MapBudgets,
116    accession: &str,
117    reason: &'static str,
118) -> Result<(), MapError> {
119    if conflicts.len() >= budgets.max_conflicts {
120        return Err(MapError::ConflictBudgetExceeded {
121            used: conflicts.len(),
122            max: budgets.max_conflicts,
123        });
124    }
125    conflicts.push(MapConflict {
126        accession: accession.to_owned(),
127        reason,
128    });
129    Ok(())
130}
131
132/// Project accepted ChEBI records into caller-buffered Quins.
133///
134/// Hot projection writes only into `out`. The returned [`MapReport`] is cold
135/// (heap) and carries conflicts, lexicon notes, and counts. On
136/// [`MapError::OutputFull`] / [`MapError::ConflictBudgetExceeded`], Quins already
137/// written remain in `out` up to the last successful record.
138pub fn map_records_into(
139    records: &[ChebiRecord],
140    release_label: &str,
141    budgets: MapBudgets,
142    out: &mut [NQuin],
143) -> Result<MapReport, MapError> {
144    let budgets = budgets.validate()?;
145    let capacity = out.len().min(budgets.max_quins);
146
147    let pred_type = q_hash(PRED_RDF_TYPE);
148    let class_compound = q_hash(CLASS_CHEBI_COMPOUND);
149    let pred_accession = q_hash(PRED_ACCESSION);
150    let pred_has_name = q_hash(PRED_HAS_NAME);
151    let pred_has_parent = q_hash(PRED_HAS_PARENT);
152    let pred_from_release = q_hash(PRED_FROM_RELEASE);
153    let context = q_hash(release_label);
154    let release_hash = context;
155
156    let mut written = 0usize;
157    let mut records_mapped = 0usize;
158    let mut conflicts: Vec<MapConflict> = Vec::new();
159    let mut lexicon: Vec<LexiconEntry> = Vec::new();
160
161    // Seen keys for this batch only (cold construction).
162    let mut seen_accessions: Vec<String> = Vec::new();
163    let mut seen_ids: Vec<u64> = Vec::new();
164
165    push_lexicon(&mut lexicon, release_hash, release_label, "release");
166
167    for record in records {
168        let needed = quins_for_record(record);
169
170        // Identifier collision: never overwrite an earlier mapping.
171        let dup_acc = seen_accessions.iter().any(|a| a == &record.accession);
172        let dup_id = seen_ids.iter().any(|&id| id == record.id);
173        if dup_acc || dup_id {
174            let reason = if dup_acc && dup_id {
175                "duplicate_accession_and_id"
176            } else if dup_acc {
177                "duplicate_accession"
178            } else {
179                "duplicate_id"
180            };
181            push_conflict(&mut conflicts, budgets, &record.accession, reason)?;
182            continue;
183        }
184
185        if written + needed > capacity {
186            return Err(MapError::OutputFull {
187                written,
188                needed,
189                capacity,
190            });
191        }
192
193        let subject = q_hash(&record.accession);
194        let accession_obj = subject; // accession string hash == subject identity
195        let name_obj = q_hash(&record.name);
196
197        // 1. Identity / type
198        write_quin(out, written, subject, pred_type, class_compound, context, 0);
199        written += 1;
200
201        // 2. Accession evidence
202        write_quin(
203            out,
204            written,
205            subject,
206            pred_accession,
207            accession_obj,
208            context,
209            0,
210        );
211        written += 1;
212
213        // 3. Name (hash + lexicon note)
214        write_quin(out, written, subject, pred_has_name, name_obj, context, 0);
215        written += 1;
216
217        // 4. Optional parent
218        if let Some(parent_id) = record.parent_id {
219            let mut parent_buf = [0u8; 32];
220            let parent_acc = format_chebi_accession(parent_id, &mut parent_buf);
221            let parent_obj = q_hash(parent_acc);
222            write_quin(
223                out,
224                written,
225                subject,
226                pred_has_parent,
227                parent_obj,
228                context,
229                0,
230            );
231            written += 1;
232            push_lexicon(&mut lexicon, parent_obj, parent_acc, "parent");
233        }
234
235        // 5. Provenance: release hash + source_line in metadata low 32 bits
236        let metadata = record.source_line & 0xFFFF_FFFF;
237        write_quin(
238            out,
239            written,
240            subject,
241            pred_from_release,
242            release_hash,
243            context,
244            metadata,
245        );
246        written += 1;
247
248        push_lexicon(&mut lexicon, accession_obj, &record.accession, "accession");
249        push_lexicon(&mut lexicon, name_obj, &record.name, "name");
250
251        seen_accessions.push(record.accession.clone());
252        seen_ids.push(record.id);
253        records_mapped += 1;
254    }
255
256    Ok(MapReport {
257        quins_written: written,
258        records_mapped,
259        conflicts,
260        lexicon,
261        release_label: release_label.to_owned(),
262    })
263}
264
265/// True when Quin parity matches the AGENTS.md XOR fold.
266#[inline]
267pub fn quin_parity_valid(q: &NQuin) -> bool {
268    q.parity == parity_fold(q)
269}
270
271#[cfg(test)]
272mod tests {
273    use super::*;
274    use crate::q42::chebi_parse::ChebiRecord;
275
276    fn rec(
277        id: u64,
278        accession: &str,
279        name: &str,
280        parent_id: Option<u64>,
281        source_line: u64,
282    ) -> ChebiRecord {
283        ChebiRecord {
284            id,
285            status: "C".into(),
286            accession: accession.into(),
287            source: String::new(),
288            parent_id,
289            name: name.into(),
290            definition: String::new(),
291            source_line,
292        }
293    }
294
295    fn budgets(max_quins: usize, max_conflicts: usize) -> MapBudgets {
296        MapBudgets {
297            max_quins,
298            max_conflicts,
299        }
300    }
301
302    #[test]
303    fn two_records_expected_count_and_parity() {
304        let records = [
305            rec(1, "CHEBI:1", "water", None, 2),
306            rec(2, "CHEBI:2", "ethanol", Some(1), 3),
307        ];
308        // 4 + (4+1) = 9
309        let mut out = [NQuin::default(); 16];
310        let report =
311            map_records_into(&records, "chebi-test-2026", budgets(16, 8), &mut out).expect("map");
312        assert_eq!(report.records_mapped, 2);
313        assert_eq!(report.quins_written, 9);
314        assert!(report.conflicts.is_empty());
315        for q in &out[..report.quins_written] {
316            assert!(quin_parity_valid(q), "parity invalid: {q:?}");
317        }
318        // Lexicon includes release + per-record accession/name + one parent
319        assert!(report.lexicon.iter().any(|e| e.kind == "release"));
320        assert!(report.lexicon.iter().any(|e| e.kind == "parent"));
321        assert_eq!(
322            report
323                .lexicon
324                .iter()
325                .filter(|e| e.kind == "accession")
326                .count(),
327            2
328        );
329    }
330
331    #[test]
332    fn duplicate_accession_reports_conflict_keeps_first() {
333        let records = [
334            rec(10, "CHEBI:10", "first", None, 2),
335            rec(10, "CHEBI:10", "second-overwrite-attempt", None, 3),
336        ];
337        let mut out = [NQuin::default(); 16];
338        let report = map_records_into(&records, "rel", budgets(16, 8), &mut out).expect("map");
339        assert_eq!(report.records_mapped, 1);
340        assert_eq!(report.quins_written, QUINS_PER_RECORD_BASE);
341        assert_eq!(report.conflicts.len(), 1);
342        assert_eq!(report.conflicts[0].accession, "CHEBI:10");
343        assert_eq!(report.conflicts[0].reason, "duplicate_accession_and_id");
344
345        let name_pred = q_hash(PRED_HAS_NAME);
346        let name_quin = out[..report.quins_written]
347            .iter()
348            .find(|q| q.predicate == name_pred)
349            .expect("name quin");
350        assert_eq!(name_quin.object, q_hash("first"));
351        assert_ne!(name_quin.object, q_hash("second-overwrite-attempt"));
352    }
353
354    #[test]
355    fn parent_relationship_when_parent_id_set() {
356        let records = [rec(99, "CHEBI:99", "child", Some(7), 5)];
357        let mut out = [NQuin::default(); 8];
358        let report = map_records_into(&records, "rel-p", budgets(8, 4), &mut out).expect("map");
359        assert_eq!(report.quins_written, 5);
360        let parent_pred = q_hash(PRED_HAS_PARENT);
361        let parent_q = out[..report.quins_written]
362            .iter()
363            .find(|q| q.predicate == parent_pred)
364            .expect("parent quin");
365        assert_eq!(parent_q.object, q_hash("CHEBI:7"));
366        assert_eq!(parent_q.subject, q_hash("CHEBI:99"));
367    }
368
369    #[test]
370    fn output_buffer_too_small_errors() {
371        let records = [
372            rec(1, "CHEBI:1", "a", None, 2),
373            rec(2, "CHEBI:2", "b", None, 3),
374        ];
375        // First record needs 4; buffer of 4 succeeds first then fails on second.
376        let mut out = [NQuin::default(); 4];
377        let err = map_records_into(&records, "rel", budgets(64, 8), &mut out).unwrap_err();
378        assert_eq!(
379            err,
380            MapError::OutputFull {
381                written: 4,
382                needed: 4,
383                capacity: 4,
384            }
385        );
386    }
387
388    #[test]
389    fn empty_input_writes_zero() {
390        let mut out = [NQuin::default(); 4];
391        let report = map_records_into(&[], "rel", budgets(4, 1), &mut out).expect("map");
392        assert_eq!(report.quins_written, 0);
393        assert_eq!(report.records_mapped, 0);
394        assert!(report.conflicts.is_empty());
395        // Release lexicon note still recorded for provenance of the pass.
396        assert_eq!(report.lexicon.len(), 1);
397        assert_eq!(report.lexicon[0].kind, "release");
398    }
399
400    #[test]
401    fn deterministic_same_records_same_quin_bytes() {
402        let records = [
403            rec(3, "CHEBI:3", "glucose", Some(2), 10),
404            rec(4, "CHEBI:4", "fructose", None, 11),
405        ];
406        let mut a = [NQuin::default(); 16];
407        let mut b = [NQuin::default(); 16];
408        let ra = map_records_into(&records, "chebi-det", budgets(16, 4), &mut a).unwrap();
409        let rb = map_records_into(&records, "chebi-det", budgets(16, 4), &mut b).unwrap();
410        assert_eq!(ra.quins_written, rb.quins_written);
411        for i in 0..ra.quins_written {
412            assert_eq!(a[i], b[i], "quin {i} differs");
413        }
414    }
415
416    #[test]
417    fn provenance_encodes_source_line_and_release() {
418        let records = [rec(5, "CHEBI:5", "named", None, 42)];
419        let mut out = [NQuin::default(); 8];
420        let report =
421            map_records_into(&records, "release-label-x", budgets(8, 2), &mut out).unwrap();
422        let pred = q_hash(PRED_FROM_RELEASE);
423        let q = out[..report.quins_written]
424            .iter()
425            .find(|q| q.predicate == pred)
426            .expect("provenance");
427        assert_eq!(q.object, q_hash("release-label-x"));
428        assert_eq!(q.metadata & 0xFFFF_FFFF, 42);
429        assert_eq!(q.context, q_hash("release-label-x"));
430    }
431
432    #[test]
433    fn duplicate_id_different_accession_conflicts() {
434        let records = [
435            rec(1, "CHEBI:1", "one", None, 2),
436            rec(1, "CHEBI:999", "spoof", None, 3),
437        ];
438        let mut out = [NQuin::default(); 16];
439        let report = map_records_into(&records, "rel", budgets(16, 4), &mut out).unwrap();
440        assert_eq!(report.records_mapped, 1);
441        assert_eq!(report.conflicts.len(), 1);
442        assert_eq!(report.conflicts[0].reason, "duplicate_id");
443        assert_eq!(report.conflicts[0].accession, "CHEBI:999");
444    }
445
446    #[test]
447    fn predicate_hashes_are_sixty_bit() {
448        for iri in [
449            PRED_RDF_TYPE,
450            CLASS_CHEBI_COMPOUND,
451            PRED_ACCESSION,
452            PRED_HAS_NAME,
453            PRED_HAS_PARENT,
454            PRED_FROM_RELEASE,
455        ] {
456            let h = q_hash(iri);
457            assert_eq!(h & !0x0FFF_FFFF_FFFF_FFFF, 0, "{iri}");
458        }
459    }
460
461    #[test]
462    fn format_chebi_accession_matches_string() {
463        let mut buf = [0u8; 32];
464        assert_eq!(format_chebi_accession(15377, &mut buf), "CHEBI:15377");
465        assert_eq!(format_chebi_accession(0, &mut buf), "CHEBI:0");
466    }
467}