Skip to main content

qualia_core_db/nlp/
budget.rs

1//! Shared NLP host resource budgets.
2//!
3//! Transport cap ≠ processing guarantee. [`MAX_SOURCE_BYTES`] is an ingress
4//! bound, equal to [`crate::nlp::coref::DEFAULT_MAX_SOURCE_BYTES`] — not a
5//! second 256 KiB and not a latency, quality, or expansion claim. Accepting a
6//! document at this cap does not mean tokenize, gazetteer, or frame work stays
7//! within an SLA, nor that intermediates stay under the Sentinel after
8//! construction.
9//!
10//! The 42 MiB [`SENTINEL_BYTES`] ceiling still applies. These host adapters are
11//! **cold** (they may allocate). They must still refuse oversize input so
12//! borrowed source plus adapter workspace cannot walk past that envelope.
13
14use crate::nlp::coref::DEFAULT_MAX_SOURCE_BYTES;
15use core::fmt;
16
17/// 42 MiB Sentinel ceiling. Re-exported from coreference limits so NLP hosts
18/// do not invent a second constant.
19pub use crate::nlp::coref::SENTINEL_BYTES;
20
21/// Shared source cap. Equal to [`DEFAULT_MAX_SOURCE_BYTES`].
22pub const MAX_SOURCE_BYTES: usize = DEFAULT_MAX_SOURCE_BYTES;
23
24/// GraphRAG query-string cap (transport-sized, not a retrieval-quality claim).
25pub const MAX_GRAPHRAG_QUERY_BYTES: usize = 64 * 1024;
26
27/// GraphRAG triple-list cap, checked before index construction.
28pub const MAX_TRIPLES: usize = 4096;
29
30/// FST lookup-word cap, checked before dictionary construction.
31pub const MAX_FST_WORD_BYTES: usize = 4 * 1024;
32
33/// FST dictionary entry-list cap, checked before host construction.
34pub const MAX_FST_ENTRIES: usize = 4096;
35
36/// Resource-budget failure. Host adapters map every variant to `E400`.
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub enum NlpBudgetError {
39    SourceTooLarge { bytes: usize, max: usize },
40    QueryTooLarge { bytes: usize, max: usize },
41    TooManyTriples { count: usize, max: usize },
42    TooManyFstEntries { count: usize, max: usize },
43    FstWordTooLarge { bytes: usize, max: usize },
44}
45
46impl NlpBudgetError {
47    /// All budget errors are resource failures (host `E400`).
48    pub fn is_resource_error(self) -> bool {
49        true
50    }
51}
52
53impl fmt::Display for NlpBudgetError {
54    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
55        match *self {
56            Self::SourceTooLarge { bytes, max } => {
57                write!(f, "nlp source is {bytes} bytes; max is {max}")
58            }
59            Self::QueryTooLarge { bytes, max } => {
60                write!(f, "nlp GraphRAG query is {bytes} bytes; max is {max}")
61            }
62            Self::TooManyTriples { count, max } => {
63                write!(f, "nlp GraphRAG received {count} triples; max is {max}")
64            }
65            Self::TooManyFstEntries { count, max } => {
66                write!(f, "nlp FST received {count} entries; max is {max}")
67            }
68            Self::FstWordTooLarge { bytes, max } => {
69                write!(f, "nlp FST word is {bytes} bytes; max is {max}")
70            }
71        }
72    }
73}
74
75impl std::error::Error for NlpBudgetError {}
76
77/// Reject an oversize source before any clone or kernel work.
78pub fn reject_source(len: usize) -> Result<(), NlpBudgetError> {
79    if len > MAX_SOURCE_BYTES {
80        Err(NlpBudgetError::SourceTooLarge {
81            bytes: len,
82            max: MAX_SOURCE_BYTES,
83        })
84    } else {
85        Ok(())
86    }
87}
88
89/// Reject an oversize GraphRAG query string before index construction.
90pub fn reject_query(len: usize) -> Result<(), NlpBudgetError> {
91    if len > MAX_GRAPHRAG_QUERY_BYTES {
92        Err(NlpBudgetError::QueryTooLarge {
93            bytes: len,
94            max: MAX_GRAPHRAG_QUERY_BYTES,
95        })
96    } else {
97        Ok(())
98    }
99}
100
101/// Reject an oversize triple list before cloning or indexing.
102pub fn reject_triples(count: usize) -> Result<(), NlpBudgetError> {
103    if count > MAX_TRIPLES {
104        Err(NlpBudgetError::TooManyTriples {
105            count,
106            max: MAX_TRIPLES,
107        })
108    } else {
109        Ok(())
110    }
111}
112
113/// Reject an oversize FST lookup word before dictionary construction.
114pub fn reject_fst_word(len: usize) -> Result<(), NlpBudgetError> {
115    if len > MAX_FST_WORD_BYTES {
116        Err(NlpBudgetError::FstWordTooLarge {
117            bytes: len,
118            max: MAX_FST_WORD_BYTES,
119        })
120    } else {
121        Ok(())
122    }
123}
124
125/// Reject an oversize FST entries list before cloning or dictionary build.
126pub fn reject_fst_entries(count: usize) -> Result<(), NlpBudgetError> {
127    if count > MAX_FST_ENTRIES {
128        Err(NlpBudgetError::TooManyFstEntries {
129            count,
130            max: MAX_FST_ENTRIES,
131        })
132    } else {
133        Ok(())
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140    use crate::nlp::coref::CorefLimits;
141
142    #[test]
143    fn max_source_bytes_is_the_coref_default() {
144        assert_eq!(MAX_SOURCE_BYTES, DEFAULT_MAX_SOURCE_BYTES);
145        assert_eq!(MAX_SOURCE_BYTES, CorefLimits::DEFAULT.max_source_bytes);
146    }
147
148    #[test]
149    fn reject_source_accepts_the_cap() {
150        assert!(reject_source(0).is_ok());
151        assert!(reject_source(MAX_SOURCE_BYTES).is_ok());
152    }
153
154    #[test]
155    fn reject_source_rejects_oversize() {
156        let err = reject_source(MAX_SOURCE_BYTES + 1).unwrap_err();
157        assert_eq!(
158            err,
159            NlpBudgetError::SourceTooLarge {
160                bytes: MAX_SOURCE_BYTES + 1,
161                max: MAX_SOURCE_BYTES,
162            }
163        );
164        assert!(err.is_resource_error());
165        assert!(err.to_string().contains(&MAX_SOURCE_BYTES.to_string()));
166    }
167
168    #[test]
169    fn reject_triples_rejects_oversize() {
170        assert!(reject_triples(MAX_TRIPLES).is_ok());
171        let err = reject_triples(MAX_TRIPLES + 1).unwrap_err();
172        assert_eq!(
173            err,
174            NlpBudgetError::TooManyTriples {
175                count: MAX_TRIPLES + 1,
176                max: MAX_TRIPLES,
177            }
178        );
179        assert!(err.is_resource_error());
180    }
181
182    #[test]
183    fn reject_query_rejects_oversize() {
184        assert!(reject_query(MAX_GRAPHRAG_QUERY_BYTES).is_ok());
185        let err = reject_query(MAX_GRAPHRAG_QUERY_BYTES + 1).unwrap_err();
186        assert_eq!(
187            err,
188            NlpBudgetError::QueryTooLarge {
189                bytes: MAX_GRAPHRAG_QUERY_BYTES + 1,
190                max: MAX_GRAPHRAG_QUERY_BYTES,
191            }
192        );
193    }
194
195    #[test]
196    fn reject_fst_entries_rejects_oversize() {
197        assert!(reject_fst_entries(MAX_FST_ENTRIES).is_ok());
198        assert!(reject_fst_entries(MAX_FST_ENTRIES + 1).is_err());
199    }
200
201    #[test]
202    fn sentinel_is_forty_two_mib() {
203        assert_eq!(SENTINEL_BYTES, 42 * 1024 * 1024);
204        assert!(MAX_SOURCE_BYTES < SENTINEL_BYTES);
205        assert!(MAX_GRAPHRAG_QUERY_BYTES < SENTINEL_BYTES);
206    }
207}