Skip to main content

qualia_core_db/inference/speculative_decode/
prepared.rs

1//! Private evolving grammar with a frozen initial grammar/trie identity.
2#![allow(dead_code)]
3use super::*;
4use sha2::{Digest, Sha256};
5
6#[derive(Clone, Copy)]
7pub struct DominoPreparationBudget {
8    pub owned_bytes: usize,
9    pub text_bytes: usize,
10    pub stack_depth: usize,
11}
12pub struct PreparedDomino {
13    masker: DominoMasker,
14    digest: [u8; 32],
15    text_limit: usize,
16    stack_limit: usize,
17    valid: bool,
18    admitted_text: usize,
19    admitted_stack: usize,
20}
21impl DominoMasker {
22    /// Cold clone admits every trie node, map/vector capacity and grammar buffer
23    /// before cloning. Trie depth is structurally capped at MAX_TRIE_DEPTH.
24    pub fn prepare_owned(
25        &self,
26        budget: DominoPreparationBudget,
27    ) -> Result<PreparedDomino, &'static str> {
28        let mut charged = std::mem::size_of::<Self>();
29        let mut hash = Sha256::new();
30        hash.update(b"qualia:prepared-domino-trie:v1\0");
31        hash.update((self.trie.vocab_size as u64).to_le_bytes());
32        hash.update([u8::from(self.active)]);
33        let mut stack: [Option<(&TrieNode, u16)>; MAX_TRIE_DEPTH + 1] = [None; MAX_TRIE_DEPTH + 1];
34        stack[0] = Some((&self.trie.root, 0));
35        let mut depth = 0usize;
36        loop {
37            let (node, next) = stack[depth].ok_or("invalid DOMINO traversal")?;
38            if next == 0 {
39                charged = charged
40                    .checked_add(
41                        node.children
42                            .capacity()
43                            .checked_mul(std::mem::size_of::<(u8, TrieNode)>() * 2)
44                            .ok_or("DOMINO budget overflow")?,
45                    )
46                    .and_then(|value| value.checked_add(node.token_ids.capacity().checked_mul(4)?))
47                    .ok_or("DOMINO budget overflow")?;
48                if charged > budget.owned_bytes {
49                    return Err("DOMINO owned budget exceeded");
50                }
51                hash.update((node.token_ids.len() as u64).to_le_bytes());
52                for token in &node.token_ids {
53                    hash.update(token.to_le_bytes());
54                }
55            }
56            if let Some((key, child)) = (next..256)
57                .find_map(|key| node.children.get(&(key as u8)).map(|child| (key, child)))
58            {
59                if depth == MAX_TRIE_DEPTH {
60                    return Err("DOMINO trie depth exceeds contract");
61                }
62                hash.update([1, key as u8]);
63                stack[depth] = Some((node, key + 1));
64                depth += 1;
65                stack[depth] = Some((child, 0));
66            } else {
67                hash.update([0]);
68                if depth == 0 {
69                    break;
70                }
71                depth -= 1;
72            }
73        }
74        let scratch = budget
75            .text_bytes
76            .checked_add(
77                budget
78                    .stack_depth
79                    .checked_mul(std::mem::size_of::<GrammarState>())
80                    .ok_or("DOMINO budget overflow")?,
81            )
82            .and_then(|value| value.checked_add(self.trie.vocab_size.checked_mul(4)?))
83            .ok_or("DOMINO budget overflow")?;
84        // Clone scratch/transient metadata is charged too, before allocation.
85        if charged
86            .checked_add(scratch)
87            .and_then(|value| value.checked_add(self.grammar.text.capacity()))
88            .and_then(|value| {
89                value.checked_add(
90                    self.grammar
91                        .stack
92                        .capacity()
93                        .checked_mul(std::mem::size_of::<GrammarState>())?,
94                )
95            })
96            .and_then(|value| value.checked_add(self.valid_buf.capacity().checked_mul(4)?))
97            .is_none_or(|value| value > budget.owned_bytes)
98        {
99            return Err("DOMINO preparation budget exceeded");
100        }
101        let mut masker = self.clone();
102        masker.reset();
103        masker
104            .grammar
105            .text
106            .reserve_exact(budget.text_bytes.saturating_sub(masker.grammar.text.len()));
107        masker.grammar.stack.reserve_exact(
108            budget
109                .stack_depth
110                .saturating_sub(masker.grammar.stack.len()),
111        );
112        masker.valid_buf.reserve_exact(
113            masker
114                .trie
115                .vocab_size
116                .saturating_sub(masker.valid_buf.len()),
117        );
118        // Initial grammar is reset by the actual prepared object before hashing.
119        hash.update((masker.grammar.state as u32).to_le_bytes());
120        hash.update((masker.grammar.whitespace_parent as u32).to_le_bytes());
121        hash.update((budget.text_bytes as u64).to_le_bytes());
122        hash.update((budget.stack_depth as u64).to_le_bytes());
123        Ok(PreparedDomino {
124            masker,
125            digest: hash.finalize().into(),
126            text_limit: budget.text_bytes,
127            stack_limit: budget.stack_depth,
128            valid: true,
129            admitted_text: 0,
130            admitted_stack: 0,
131        })
132    }
133}
134impl PreparedDomino {
135    /// Reserve before publication, including display UTF-8 replacement and the
136    /// legacy byte-to-char grammar expansion. Reservations are cumulative over
137    /// speculative batches whose feeds run after their decisions.
138    pub(crate) fn admit_raw_piece(&mut self, bytes: usize) -> bool {
139        if !self.masker.active {
140            return self.valid;
141        }
142        let text = self.admitted_text.checked_add(bytes.saturating_mul(6));
143        let stack = self.admitted_stack.checked_add(bytes.saturating_mul(3));
144        if text.is_none_or(|n| n > self.text_limit) || stack.is_none_or(|n| n > self.stack_limit) {
145            self.valid = false;
146            return false;
147        }
148        self.admitted_text = text.unwrap();
149        self.admitted_stack = stack.unwrap();
150        self.valid
151    }
152    pub fn digest(&self) -> [u8; 32] {
153        self.digest
154    }
155    pub fn valid(&self) -> bool {
156        self.valid
157    }
158    pub(crate) fn active(&self) -> bool {
159        self.valid && self.masker.is_active()
160    }
161    pub(crate) fn sample(
162        &mut self,
163        sampler: &mut crate::sampler::SamplerState,
164        logits: &mut [f32],
165        ctx: &[u32],
166    ) -> Option<u32> {
167        if !self.active() {
168            return None;
169        }
170        if logits.len() > self.masker.valid_buf.capacity() {
171            self.valid = false;
172            return None;
173        }
174        Some(sampler.sample_constrained(logits, ctx, &mut self.masker))
175    }
176    pub(crate) fn feed(&mut self, bytes: &[u8]) {
177        if !self.valid {
178            return;
179        }
180        let text_bytes = bytes
181            .iter()
182            .map(|&byte| (byte as char).len_utf8())
183            .sum::<usize>();
184        if self
185            .masker
186            .grammar
187            .text
188            .len()
189            .checked_add(text_bytes)
190            .is_none_or(|n| n > self.text_limit)
191            || self
192                .masker
193                .grammar
194                .stack
195                .len()
196                .checked_add(bytes.len())
197                .is_none_or(|n| n > self.stack_limit)
198        {
199            self.valid = false;
200            return;
201        }
202        self.masker.feed_token(bytes);
203    }
204    pub(crate) fn reset(&mut self) {
205        self.masker.reset();
206        self.admitted_text = 0;
207        self.admitted_stack = 0;
208    }
209}