Skip to main content

qualia_core_db/nlp/coref/
validate.rs

1//! Preflight mention validation. Fail before grouping or antecedent search.
2
3use super::error::CorefError;
4use super::limits::CorefLimits;
5use super::{CorefMention, MentionKind, ValidatedMention};
6
7/// Checked conversion from a host `u64` offset.
8pub fn offset_from_u64(value: u64) -> Result<u32, CorefError> {
9    u32::try_from(value).map_err(|_| CorefError::OffsetOverflow)
10}
11
12/// Checked conversion from a host `i64` offset. Negative values never wrap.
13pub fn offset_from_i64(value: i64) -> Result<u32, CorefError> {
14    if value < 0 {
15        return Err(CorefError::NegativeOffset);
16    }
17    u32::try_from(value).map_err(|_| CorefError::OffsetOverflow)
18}
19
20/// Parse a supported mention kind. Unknown strings fail; they are not coerced.
21pub fn mention_kind_from_label(label: &str) -> Result<MentionKind, CorefError> {
22    match label {
23        "pronoun" => Ok(MentionKind::Pronoun),
24        "proper" => Ok(MentionKind::Proper),
25        "common" => Ok(MentionKind::Common),
26        _ => Err(CorefError::InvalidKind),
27    }
28}
29
30/// Reject oversize source/list/text before any grouping work.
31pub fn preflight_counts(
32    source: &str,
33    mention_count: usize,
34    mention_text_bytes: usize,
35    limits: &CorefLimits,
36) -> Result<(), CorefError> {
37    if source.len() > limits.max_source_bytes {
38        return Err(limits.source_too_large(source.len()));
39    }
40    if mention_count > limits.max_mentions {
41        return Err(CorefError::TooManyMentions {
42            count: mention_count,
43            max: limits.max_mentions,
44        });
45    }
46    if mention_text_bytes > limits.max_mention_text_bytes {
47        return Err(CorefError::MentionTextTooLarge {
48            bytes: mention_text_bytes,
49            max: limits.max_mention_text_bytes,
50        });
51    }
52    Ok(())
53}
54
55/// Sum mention-text bytes with saturating arithmetic, failing at the cap.
56pub fn aggregate_mention_text_bytes(
57    mentions: &[CorefMention],
58    max_bytes: usize,
59) -> Result<usize, CorefError> {
60    let mut total = 0usize;
61    for mention in mentions {
62        total = total.saturating_add(mention.text.len());
63        if total > max_bytes {
64            return Err(CorefError::MentionTextTooLarge {
65                bytes: total,
66                max: max_bytes,
67            });
68        }
69    }
70    Ok(total)
71}
72
73/// Validate one mention against the immutable source. `prev` enforces document order.
74pub fn validate_mention(
75    source: &str,
76    mention: &CorefMention,
77    prev: Option<&ValidatedMention>,
78) -> Result<ValidatedMention, CorefError> {
79    let start = mention.span.start_utf8 as usize;
80    let end = mention.span.end_utf8 as usize;
81    if start >= end {
82        return Err(CorefError::SpanEmpty);
83    }
84    if end > source.len() {
85        return Err(CorefError::SpanOutOfRange);
86    }
87    if !source.is_char_boundary(start) || !source.is_char_boundary(end) {
88        return Err(CorefError::SpanNotUtf8Boundary);
89    }
90    if &source[start..end] != mention.text.as_str() {
91        return Err(CorefError::TextMismatch);
92    }
93    if let Some(prev) = prev {
94        if mention.span.start_utf8 < prev.start
95            || (mention.span.start_utf8 == prev.start && mention.span.end_utf8 < prev.end)
96        {
97            return Err(CorefError::UnsortedMentions);
98        }
99    }
100    Ok(ValidatedMention {
101        start: mention.span.start_utf8,
102        end: mention.span.end_utf8,
103        kind: mention.kind,
104    })
105}
106
107/// Validate every mention after the count/byte preflight has passed.
108pub fn validate_mentions(
109    source: &str,
110    mentions: &[CorefMention],
111    out: &mut [ValidatedMention],
112) -> Result<usize, CorefError> {
113    if out.len() < mentions.len() {
114        return Err(CorefError::OutputBufferFull);
115    }
116    let mut prev = None;
117    for (index, mention) in mentions.iter().enumerate() {
118        let validated = validate_mention(source, mention, prev.as_ref())?;
119        out[index] = validated;
120        prev = Some(validated);
121    }
122    Ok(mentions.len())
123}