Skip to main content

qualia_core_db/text_span/
mod.rs

1//! Byte-span annotations for document → Quin provenance (P6).
2//!
3//! UTF-8 offsets are canonical. Content hash is FNV-1a 60-bit (lexicon).
4
5use crate::lexicon::generate_60bit_token;
6use crate::NQuin;
7
8/// Inclusive-exclusive UTF-8 byte range into a source document.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub struct TextSpan {
11    pub start_utf8: u32,
12    pub end_utf8: u32,
13    pub content_hash: u64,
14}
15
16impl TextSpan {
17    /// Builds `TextSpan` from `source`.
18    pub fn from_source(source: &str, start_utf8: u32, end_utf8: u32) -> Option<Self> {
19        let start = start_utf8 as usize;
20        let end = end_utf8 as usize;
21        if start > end || end > source.len() {
22            return None;
23        }
24        if !source.is_char_boundary(start) || !source.is_char_boundary(end) {
25            return None;
26        }
27        Some(Self {
28            start_utf8,
29            end_utf8,
30            content_hash: generate_60bit_token(source[start..end].as_bytes()),
31        })
32    }
33
34    /// Slice view.
35    pub fn slice<'a>(&self, source: &'a str) -> Option<&'a str> {
36        let start = self.start_utf8 as usize;
37        let end = self.end_utf8 as usize;
38        if start <= end && end <= source.len() {
39            Some(&source[start..end])
40        } else {
41            None
42        }
43    }
44}
45
46/// Predicate for "this Quin is an annotation of a source span".
47pub const SPAN_ANNOTATES: &str = "https://qualiadb.org/schema/annotatesSpan";
48
49/// Build a sealed annotation Quin: subject = term, predicate = annotatesSpan,
50/// object packs start<<32|end (fits documents under 4 GiB), context = content hash.
51pub fn annotation_quin(term_iri: &str, span: TextSpan, source_hash: u64) -> NQuin {
52    let subject = generate_60bit_token(term_iri.as_bytes());
53    let predicate = generate_60bit_token(SPAN_ANNOTATES.as_bytes());
54    let object = ((span.start_utf8 as u64) << 32) | (span.end_utf8 as u64);
55    let context = span.content_hash ^ source_hash;
56    let metadata = 0;
57    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
58    NQuin {
59        subject,
60        predicate,
61        object,
62        context,
63        metadata,
64        parity,
65    }
66}
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71
72    #[test]
73    fn span_rejects_bad_range() {
74        assert!(TextSpan::from_source("hi", 0, 5).is_none());
75        assert!(TextSpan::from_source("hi", 2, 1).is_none());
76    }
77
78    #[test]
79    fn annotation_quin_has_valid_parity() {
80        let src = "North Spring is the reference site.";
81        let span = TextSpan::from_source(src, 0, 12).unwrap();
82        assert_eq!(span.slice(src), Some("North Spring"));
83        let q = annotation_quin("https://qualiadb.org/clinic/NorthSpring", span, 1);
84        assert!(q.verify_ecc_parity());
85        assert_ne!(q.parity, 0);
86    }
87}