Skip to main content

qualia_core_db/inference/
neuro_symbolic_sieve.rs

1//! Grammar-constrained FSM sieve for neuro-symbolic LLM output (zero-heap hot path).
2
3use crate::q_hash;
4use crate::NQuin;
5
6/// Max allowed token IDs per FSM state (stack-only mask).
7pub const MAX_SIEVE_ALLOW: usize = 16;
8
9/// One lexicon-bound token slot in a state mask.
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub struct SieveSlot {
12    pub token_id: u32,
13    pub lexicon_hash: u64,
14}
15
16/// Stack mask: linear scan during chunked argmax (no `HashMap` / `Vec`).
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct SieveStateMask {
19    pub slots: [SieveSlot; MAX_SIEVE_ALLOW],
20    pub len: u8,
21}
22
23impl SieveStateMask {
24    pub const EMPTY: Self = Self {
25        slots: [SieveSlot {
26            token_id: 0,
27            lexicon_hash: 0,
28        }; MAX_SIEVE_ALLOW],
29        len: 0,
30    };
31
32    #[inline]
33    /// `true` when `token_id` is permitted in the current sieve state.
34    pub fn allows(&self, token_id: u32) -> bool {
35        if self.len == 0 {
36            return true;
37        }
38        for i in 0..self.len as usize {
39            if self.slots[i].token_id == token_id {
40                return true;
41            }
42        }
43        false
44    }
45
46    #[inline]
47    /// Lexicon hash bound to `token_id`, or `None`.
48    pub fn lexicon_hash_for(&self, token_id: u32) -> Option<u64> {
49        for i in 0..self.len as usize {
50            if self.slots[i].token_id == token_id {
51                return Some(self.slots[i].lexicon_hash);
52            }
53        }
54        None
55    }
56
57    /// Appends a token_id/lexicon_hash pair to the mask table.
58    pub(crate) fn push(&mut self, token_id: u32, lexicon_hash: u64) {
59        let n = self.len as usize;
60        if n >= MAX_SIEVE_ALLOW {
61            return;
62        }
63        for i in 0..n {
64            if self.slots[i].token_id == token_id {
65                return;
66            }
67        }
68        self.slots[n] = SieveSlot {
69            token_id,
70            lexicon_hash,
71        };
72        self.len += 1;
73    }
74}
75
76/// FSM states for Subject → Predicate → Object graph emission.
77#[derive(Debug, Clone, Copy, PartialEq, Eq)]
78pub enum SieveState {
79    ExpectSubject = 0,
80    ExpectPredicate = 1,
81    ExpectObject = 2,
82    Complete = 3,
83}
84
85/// Sieve exhausted: no allowed token had finite logit mass.
86#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87pub enum SieveError {
88    Misaligned,
89    AlreadyComplete,
90}
91
92/// Stack-only IRI hash lists for dynamic `.q42.lex` mask population (cold path).
93#[derive(Debug, Clone, Copy)]
94pub struct SieveLexSpec {
95    pub subjects: [u64; MAX_SIEVE_ALLOW],
96    pub subjects_len: u8,
97    pub predicates: [u64; MAX_SIEVE_ALLOW],
98    pub predicates_len: u8,
99    pub objects: [u64; MAX_SIEVE_ALLOW],
100    pub objects_len: u8,
101}
102
103impl SieveLexSpec {
104    pub const EMPTY: Self = Self {
105        subjects: [0; MAX_SIEVE_ALLOW],
106        subjects_len: 0,
107        predicates: [0; MAX_SIEVE_ALLOW],
108        predicates_len: 0,
109        objects: [0; MAX_SIEVE_ALLOW],
110        objects_len: 0,
111    };
112
113    /// Appends a subject hash to the lex spec.
114    pub fn push_subject(&mut self, hash: u64) {
115        let n = self.subjects_len as usize;
116        if n < MAX_SIEVE_ALLOW {
117            self.subjects[n] = hash;
118            self.subjects_len += 1;
119        }
120    }
121
122    /// Appends a predicate hash.
123    pub fn push_predicate(&mut self, hash: u64) {
124        let n = self.predicates_len as usize;
125        if n < MAX_SIEVE_ALLOW {
126            self.predicates[n] = hash;
127            self.predicates_len += 1;
128        }
129    }
130
131    /// Appends an object hash.
132    pub fn push_object(&mut self, hash: u64) {
133        let n = self.objects_len as usize;
134        if n < MAX_SIEVE_ALLOW {
135            self.objects[n] = hash;
136            self.objects_len += 1;
137        }
138    }
139
140    /// Default graph-mutation triple for clinical / conduct intents.
141    pub fn graph_mutation_default() -> Self {
142        let mut s = Self::EMPTY;
143        s.push_subject(q_hash("schema:Patient"));
144        s.push_subject(q_hash("q42:subject"));
145        s.push_predicate(q_hash("snomed:hasFever"));
146        s.push_predicate(q_hash("q42:conductViolation"));
147        s.push_predicate(q_hash("q42:hasGuardian"));
148        s.push_object(q_hash("xsd:true"));
149        s.push_object(q_hash("q42:entity"));
150        s
151    }
152
153    /// Fever observation triple used by the e2e WAL pipeline test.
154    pub fn fever_observation() -> Self {
155        let mut s = Self::EMPTY;
156        s.push_subject(q_hash("Patient"));
157        s.push_predicate(q_hash("fever"));
158        s.push_object(q_hash("True"));
159        s
160    }
161}
162
163/// Neuro-symbolic grammar sieve (masks built once from tokenizer + lex — cold path may alloc).
164#[derive(Debug, Clone)]
165pub struct NeuroSymbolicSieve {
166    masks: [SieveStateMask; 3],
167    state: SieveState,
168    subject_hash: u64,
169    predicate_hash: u64,
170    object_hash: u64,
171    emitted_tokens: [u32; 3],
172    emitted_len: u8,
173}
174
175impl NeuroSymbolicSieve {
176    /// Exact initial owned mask/state identity after cold lexicon resolution.
177    /// Execution mutates only this private request's state, never the lex file.
178    #[allow(dead_code)]
179    pub(crate) fn prepared_digest(&self) -> [u8; 32] {
180        use sha2::{Digest, Sha256};
181        let mut hash = Sha256::new();
182        hash.update(b"qualia:prepared-sieve:v1\0");
183        hash.update([self.state as u8, self.emitted_len]);
184        for mask in &self.masks {
185            hash.update([mask.len]);
186            for slot in &mask.slots {
187                hash.update(slot.token_id.to_le_bytes());
188                hash.update(slot.lexicon_hash.to_le_bytes());
189            }
190        }
191        for value in [self.subject_hash, self.predicate_hash, self.object_hash] {
192            hash.update(value.to_le_bytes());
193        }
194        for value in self.emitted_tokens {
195            hash.update(value.to_le_bytes());
196        }
197        hash.finalize().into()
198    }
199
200    /// Build masks from a memory-mapped `.q42.lex` view and GGUF tokenizer (load-time only).
201    #[cfg(not(target_arch = "wasm32"))]
202    pub fn from_lex_and_tokenizer(
203        lex: &crate::q42_lex::Q42LexMmap<'_>,
204        tok: &crate::gguf_sharder::GgufTokenizer,
205        spec: &SieveLexSpec,
206    ) -> Self {
207        let mut sieve = Self::empty_fsm();
208        fill_mask_from_lex(
209            &mut sieve.masks[0],
210            lex,
211            tok,
212            &spec.subjects[..spec.subjects_len as usize],
213        );
214        fill_mask_from_lex(
215            &mut sieve.masks[1],
216            lex,
217            tok,
218            &spec.predicates[..spec.predicates_len as usize],
219        );
220        fill_mask_from_lex(
221            &mut sieve.masks[2],
222            lex,
223            tok,
224            &spec.objects[..spec.objects_len as usize],
225        );
226        sieve
227    }
228
229    /// Tokenizer-only fallback when no `.q42.lex` sidecar is loaded (dev / tests).
230    pub fn from_gguf_tokenizer(tok: &crate::gguf_sharder::GgufTokenizer) -> Self {
231        let mut sieve = Self::empty_fsm();
232        const SUBJECTS: &[(&str, u64)] = &[
233            ("Webizen", q_hash("q42:webizenAgent")),
234            ("Agent", q_hash("q42:agent")),
235            ("Subject", q_hash("q42:subject")),
236        ];
237        const PREDICATES: &[(&str, u64)] = &[
238            ("conductViolation", q_hash("q42:conductViolation")),
239            ("hasGuardian", q_hash("q42:hasGuardian")),
240            ("violation", q_hash("q42:conductViolation")),
241            ("Guardian", q_hash("q42:hasGuardian")),
242        ];
243        const OBJECTS: &[(&str, u64)] = &[
244            ("guardian", q_hash("q42:guardianEntity")),
245            ("Entity", q_hash("q42:entity")),
246            ("Object", q_hash("q42:object")),
247        ];
248        fill_mask_literal(&mut sieve.masks[0], tok, SUBJECTS);
249        fill_mask_literal(&mut sieve.masks[1], tok, PREDICATES);
250        fill_mask_literal(&mut sieve.masks[2], tok, OBJECTS);
251        sieve
252    }
253
254    /// Creates a sieve in the empty FSM state.
255    pub(crate) fn empty_fsm() -> Self {
256        Self {
257            masks: [SieveStateMask::EMPTY; 3],
258            state: SieveState::ExpectSubject,
259            subject_hash: 0,
260            predicate_hash: 0,
261            object_hash: 0,
262            emitted_tokens: [0; 3],
263            emitted_len: 0,
264        }
265    }
266
267    #[inline]
268    /// Current sieve FSM state.
269    pub fn state(&self) -> SieveState {
270        self.state
271    }
272
273    #[inline]
274    /// `true` when the sieve reached a complete state.
275    pub fn is_complete(&self) -> bool {
276        self.state == SieveState::Complete
277    }
278
279    #[inline]
280    /// Length of the emitted-token buffer.
281    pub fn emitted_len(&self) -> u8 {
282        self.emitted_len
283    }
284
285    #[inline]
286    /// The current state's token mask.
287    pub fn current_mask(&self) -> &SieveStateMask {
288        match self.state {
289            SieveState::ExpectSubject => &self.masks[0],
290            SieveState::ExpectPredicate => &self.masks[1],
291            SieveState::ExpectObject => &self.masks[2],
292            SieveState::Complete => &SieveStateMask::EMPTY,
293        }
294    }
295
296    /// Apply a sieve-selected token and advance the FSM.
297    pub fn apply_token(&mut self, token_id: u32) -> Result<(), SieveError> {
298        if self.state == SieveState::Complete {
299            return Err(SieveError::AlreadyComplete);
300        }
301        let mask = self.current_mask();
302        if mask.len == 0 {
303            return Err(SieveError::Misaligned);
304        }
305        let hash = mask
306            .lexicon_hash_for(token_id)
307            .ok_or(SieveError::Misaligned)?;
308        match self.state {
309            SieveState::ExpectSubject => {
310                self.subject_hash = hash;
311                self.state = SieveState::ExpectPredicate;
312            }
313            SieveState::ExpectPredicate => {
314                self.predicate_hash = hash;
315                self.state = SieveState::ExpectObject;
316            }
317            SieveState::ExpectObject => {
318                self.object_hash = hash;
319                self.state = SieveState::Complete;
320            }
321            SieveState::Complete => return Err(SieveError::AlreadyComplete),
322        }
323        let n = self.emitted_len as usize;
324        if n < 3 {
325            self.emitted_tokens[n] = token_id;
326            self.emitted_len += 1;
327        }
328        Ok(())
329    }
330
331    /// Assemble the 48-byte `NQuin` from constrained emissions (stack only).
332    pub fn assemble_quin(&self, context_hash: u64) -> NQuin {
333        let mut quin = NQuin {
334            subject: self.subject_hash,
335            predicate: self.predicate_hash,
336            object: self.object_hash,
337            context: context_hash,
338            metadata: 0,
339            parity: 0,
340        };
341        quin.parity = quin.subject ^ quin.predicate ^ quin.object ^ quin.context;
342        quin
343    }
344
345    /// `true` when masks for all states have been provisioned.
346    pub fn masks_ready(&self) -> bool {
347        self.masks[0].len > 0 && self.masks[1].len > 0 && self.masks[2].len > 0
348    }
349
350    /// First resolved token ID per FSM slot (cold-path / test helper).
351    pub fn resolved_token_triple(&self) -> Option<(u32, u32, u32)> {
352        if !self.masks_ready() {
353            return None;
354        }
355        Some((
356            self.masks[0].slots[0].token_id,
357            self.masks[1].slots[0].token_id,
358            self.masks[2].slots[0].token_id,
359        ))
360    }
361}
362
363fn fill_mask_literal(
364    mask: &mut SieveStateMask,
365    tok: &crate::gguf_sharder::GgufTokenizer,
366    entries: &[(&str, u64)],
367) {
368    for &(text, hash) in entries {
369        let ids = tok.encode(text);
370        if let Some(&id) = ids.first() {
371            mask.push(id, hash);
372        }
373    }
374}
375
376#[cfg(not(target_arch = "wasm32"))]
377fn fill_mask_from_lex(
378    mask: &mut SieveStateMask,
379    lex: &crate::q42_lex::Q42LexMmap<'_>,
380    tok: &crate::gguf_sharder::GgufTokenizer,
381    hashes: &[u64],
382) {
383    let mut term = String::new();
384    for &hash in hashes {
385        if lex.resolve_term_into(hash, &mut term) {
386            let ids = tok.encode(&term);
387            if let Some(&id) = ids.first() {
388                mask.push(id, hash);
389            }
390        }
391    }
392}
393
394#[cfg(test)]
395mod tests {
396    use super::*;
397
398    fn write_lex_bytes(entries: &[(u64, &str)]) -> Vec<u8> {
399        let mut sorted: Vec<(u64, &str)> = entries.to_vec();
400        sorted.sort_unstable_by_key(|(h, _)| *h);
401        let entry_count = sorted.len() as u64;
402        let strings_offset = 32 + entry_count * 16;
403        let mut blob = Vec::new();
404        let mut index = Vec::new();
405        for (hash, text) in &sorted {
406            let str_off = blob.len() as u64;
407            let b = text.as_bytes();
408            let len = b.len().min(65535) as u16;
409            // Q42LEX string payload format: [LEX_TAG_STRING=0x01][len_lo][len_hi][utf8...]
410            // Must match Q42LexMmap::read_string_at which checks the tag byte first.
411            blob.push(0x01u8); // LEX_TAG_STRING
412            blob.extend_from_slice(&len.to_le_bytes());
413            blob.extend_from_slice(&b[..len as usize]);
414            index.extend_from_slice(&hash.to_le_bytes());
415            index.extend_from_slice(&str_off.to_le_bytes());
416        }
417        let mut out = Vec::new();
418        out.extend_from_slice(b"Q42LEX\0\0");
419        out.extend_from_slice(&entry_count.to_le_bytes());
420        out.extend_from_slice(&strings_offset.to_le_bytes());
421        out.extend_from_slice(&1u64.to_le_bytes());
422        out.extend_from_slice(&index);
423        out.extend_from_slice(&blob);
424        out
425    }
426
427    #[test]
428    fn sieve_mask_allows_linear_scan() {
429        let mut m = SieveStateMask::EMPTY;
430        m.push(42, q_hash("a"));
431        m.push(99, q_hash("b"));
432        assert!(m.allows(42));
433        assert!(!m.allows(1));
434        assert_eq!(m.lexicon_hash_for(99), Some(q_hash("b")));
435    }
436
437    #[test]
438    fn sieve_fsm_transitions_to_complete() {
439        let mut s = NeuroSymbolicSieve::empty_fsm();
440        s.masks[0].push(10, q_hash("sub"));
441        s.masks[1].push(20, q_hash("pred"));
442        s.masks[2].push(30, q_hash("obj"));
443        assert!(s.apply_token(10).is_ok());
444        assert!(s.apply_token(20).is_ok());
445        assert!(s.apply_token(30).is_ok());
446        assert!(s.is_complete());
447        let q = s.assemble_quin(q_hash("ctx"));
448        assert_eq!(q.subject, q_hash("sub"));
449        assert_eq!(q.predicate, q_hash("pred"));
450        assert_eq!(q.object, q_hash("obj"));
451    }
452
453    #[test]
454    fn sieve_builds_masks_from_mmap_lex() {
455        let h_sub = q_hash("Patient");
456        let h_pred = q_hash("fever");
457        let h_obj = q_hash("True");
458        let bytes = write_lex_bytes(&[(h_sub, "Patient"), (h_pred, "fever"), (h_obj, "True")]);
459        let lex = crate::q42_lex::Q42LexMmap::from_bytes(&bytes).unwrap();
460        let tok = crate::gguf_sharder::GgufTokenizer::default();
461        let spec = SieveLexSpec::fever_observation();
462        let sieve = NeuroSymbolicSieve::from_lex_and_tokenizer(&lex, &tok, &spec);
463        assert!(sieve.masks_ready());
464    }
465}