Skip to main content

qualia_core_db/nlp/coref/
limits.rs

1//! Default resource budgets and work counters for coreference.
2
3use super::error::CorefError;
4use core::sync::atomic::{AtomicBool, AtomicU64, Ordering};
5
6/// 42 MiB Sentinel ceiling. This operation's workspace must stay under it
7/// together with the borrowed source.
8pub const SENTINEL_BYTES: usize = 42 * 1024 * 1024;
9
10/// Default source cap (transport-sized, not a latency claim).
11pub const DEFAULT_MAX_SOURCE_BYTES: usize = 256 * 1024;
12/// Default mention-list cap.
13pub const DEFAULT_MAX_MENTIONS: usize = 4096;
14/// Default aggregate supplied mention-text cap.
15pub const DEFAULT_MAX_MENTION_TEXT_BYTES: usize = 1024 * 1024;
16/// Default emitted-chain cap.
17pub const DEFAULT_MAX_CHAINS: usize = 4096;
18/// Proper-noun candidates inspected per pronoun (search window).
19pub const DEFAULT_MAX_ANTECEDENTS_PER_PRONOUN: usize = 64;
20/// Total Proper-noun antecedent inspections per call (non-Proper mentions
21/// are skipped without charging this counter).
22pub const DEFAULT_MAX_ANTECEDENT_CHECKS: u64 = 65_536;
23/// Default caller workspace for this operation.
24pub const DEFAULT_MAX_WORKSPACE_BYTES: usize = 2 * 1024 * 1024;
25/// Default folded-key byte budget.
26pub const DEFAULT_MAX_NORMALIZATION_BYTES: u64 = 1024 * 1024;
27/// Default byte-comparison budget, including long shared prefixes.
28pub const DEFAULT_MAX_COMPARISON_BYTES: u64 = 8 * 1024 * 1024;
29
30/// FNV-1a 64-bit over already-normalized key bytes.
31pub fn fnv1a64(bytes: &[u8]) -> u64 {
32    const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
33    const PRIME: u64 = 0x0100_0000_01b3;
34    let mut hash = OFFSET;
35    for &byte in bytes {
36        hash ^= u64::from(byte);
37        hash = hash.wrapping_mul(PRIME);
38    }
39    hash
40}
41
42/// Caller-visible limits. Lower them in tests; raising defaults needs measured
43/// resource evidence recorded in the NLP plan.
44#[derive(Clone, Copy)]
45pub struct CorefLimits {
46    pub max_source_bytes: usize,
47    pub max_mentions: usize,
48    pub max_mention_text_bytes: usize,
49    pub max_chains: usize,
50    pub max_antecedents_per_pronoun: usize,
51    pub max_antecedent_checks: u64,
52    pub max_workspace_bytes: usize,
53    pub max_normalization_bytes: u64,
54    pub max_comparison_bytes: u64,
55    /// Hash of folded keys. Production uses [`fnv1a64`]; tests may force collisions.
56    pub key_hash: fn(&[u8]) -> u64,
57}
58
59impl CorefLimits {
60    pub const DEFAULT: Self = Self {
61        max_source_bytes: DEFAULT_MAX_SOURCE_BYTES,
62        max_mentions: DEFAULT_MAX_MENTIONS,
63        max_mention_text_bytes: DEFAULT_MAX_MENTION_TEXT_BYTES,
64        max_chains: DEFAULT_MAX_CHAINS,
65        max_antecedents_per_pronoun: DEFAULT_MAX_ANTECEDENTS_PER_PRONOUN,
66        max_antecedent_checks: DEFAULT_MAX_ANTECEDENT_CHECKS,
67        max_workspace_bytes: DEFAULT_MAX_WORKSPACE_BYTES,
68        max_normalization_bytes: DEFAULT_MAX_NORMALIZATION_BYTES,
69        max_comparison_bytes: DEFAULT_MAX_COMPARISON_BYTES,
70        key_hash: fnv1a64,
71    };
72
73    /// `true` when source exceeds the coref budget.
74    pub fn source_too_large(self, bytes: usize) -> CorefError {
75        CorefError::SourceTooLarge {
76            bytes,
77            max: self.max_source_bytes,
78        }
79    }
80}
81
82impl Default for CorefLimits {
83    fn default() -> Self {
84        Self::DEFAULT
85    }
86}
87
88/// Cooperative cancellation. Polls are cheap; a zero `cancel_after_polls`
89/// disables auto-cancel (the production default).
90#[derive(Debug)]
91pub struct CancellationToken {
92    cancelled: AtomicBool,
93    polls: AtomicU64,
94    cancel_after_polls: u64,
95}
96
97impl CancellationToken {
98    /// Creates a default `CancellationToken`.
99    pub const fn new() -> Self {
100        Self {
101            cancelled: AtomicBool::new(false),
102            polls: AtomicU64::new(0),
103            cancel_after_polls: 0,
104        }
105    }
106
107    /// Cancels the coref job.
108    pub fn cancel(&self) {
109        self.cancelled.store(true, Ordering::Relaxed);
110    }
111
112    /// Test helper: become cancelled after `n` polls (n >= 1).
113    pub fn cancel_after_polls(n: u64) -> Self {
114        Self {
115            cancelled: AtomicBool::new(false),
116            polls: AtomicU64::new(0),
117            cancel_after_polls: n,
118        }
119    }
120
121    /// `true` when `cancelled`.
122    pub fn is_cancelled(&self) -> bool {
123        if self.cancelled.load(Ordering::Relaxed) {
124            return true;
125        }
126        if self.cancel_after_polls == 0 {
127            return false;
128        }
129        let polls = self.polls.fetch_add(1, Ordering::Relaxed).saturating_add(1);
130        if polls >= self.cancel_after_polls {
131            self.cancelled.store(true, Ordering::Relaxed);
132            true
133        } else {
134            false
135        }
136    }
137}
138
139impl Default for CancellationToken {
140    fn default() -> Self {
141        Self::new()
142    }
143}
144
145/// Instrumented work. These are counters, not wall-clock claims.
146#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
147pub struct CorefWorkStats {
148    pub mention_count: u32,
149    pub chain_count: u32,
150    pub normalization_bytes: u64,
151    pub comparison_bytes: u64,
152    pub key_comparisons: u64,
153    pub antecedent_candidates: u64,
154    pub antecedent_checks: u64,
155    pub workspace_bytes: usize,
156}
157
158/// Bytes for `n` mention work records plus two `u32` permutations plus `norm`.
159/// Cold adapters also allocate `validated`/`heads`/`ids`; those are not part
160/// of this hot workspace figure and stay well under the 42 MiB Sentinel.
161pub fn workspace_bytes_required(mention_count: usize, norm_bytes: usize) -> usize {
162    mention_count
163        .saturating_mul(core::mem::size_of::<super::MentionWork>())
164        .saturating_add(
165            mention_count
166                .saturating_mul(core::mem::size_of::<u32>())
167                .saturating_mul(2),
168        )
169        .saturating_add(norm_bytes)
170}