Skip to main content

qualia_core_db/inference/
domino_gbnf.rs

1//! DOMINO GBNF Constrained LLM Decoding for VibeScript.
2//!
3//! Provides deterministic grammar-constrained logit masking (GBNF) for local autoregressive
4//! model inference. Guarantees that tokens generated by the Phase 8 LLM decode loop strictly
5//! conform to valid VibeScript grammar rules (functions, hooks, expressions, control flow).
6
7/// Grammar rule type in the GBNF State Machine.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum GrammarRule {
10    Root,
11    Program,
12    Item,
13    FunctionDecl,
14    HookDecl,
15    ConstDecl,
16    Params,
17    Param,
18    Block,
19    Statement,
20    LetStmt,
21    MutStmt,
22    AssignStmt,
23    ReturnStmt,
24    IfStmt,
25    WhileStmt,
26    ForStmt,
27    MatchStmt,
28    Expr,
29    BinaryExpr,
30    UnaryExpr,
31    PrimaryExpr,
32    Literal,
33    Ident,
34    TypeExpr,
35}
36
37/// A DFA state tracking current grammar match progress.
38#[derive(Debug, Clone)]
39pub struct DominoGrammarState {
40    /// Active grammar rules stack (depth <= 32 for zero-heap stack guarantee).
41    rule_stack: [GrammarRule; 32],
42    stack_depth: usize,
43    /// Partial text buffer matching the current rule.
44    partial_match: [u8; 128],
45    partial_len: usize,
46    /// Whether the parser is inside a string literal.
47    in_string: bool,
48    /// Current brace nesting level.
49    brace_depth: usize,
50    /// Current paren nesting level.
51    paren_depth: usize,
52    /// Whether the generation has completed a valid top-level AST item.
53    item_complete: bool,
54}
55
56impl Default for DominoGrammarState {
57    fn default() -> Self {
58        Self::new()
59    }
60}
61
62impl DominoGrammarState {
63    /// Create a new grammar state starting at the `Program` root.
64    pub const fn new() -> Self {
65        let mut stack = [GrammarRule::Root; 32];
66        stack[0] = GrammarRule::Program;
67        Self {
68            rule_stack: stack,
69            stack_depth: 1,
70            partial_match: [0u8; 128],
71            partial_len: 0,
72            in_string: false,
73            brace_depth: 0,
74            paren_depth: 0,
75            item_complete: false,
76        }
77    }
78
79    /// Reset state to initial program root.
80    pub fn reset(&mut self) {
81        self.stack_depth = 1;
82        self.rule_stack[0] = GrammarRule::Program;
83        self.partial_len = 0;
84        self.in_string = false;
85        self.brace_depth = 0;
86        self.paren_depth = 0;
87        self.item_complete = false;
88    }
89
90    /// Check if a byte sequence is a valid continuation of the current grammar state.
91    pub fn is_valid_continuation(&self, bytes: &[u8]) -> bool {
92        if bytes.is_empty() {
93            return true;
94        }
95
96        let mut simulated = self.clone();
97        for &b in bytes {
98            if !simulated.feed_byte(b) {
99                return false;
100            }
101        }
102        true
103    }
104
105    /// Feed a single byte into the grammar DFA state. Returns false if rejected by grammar.
106    pub fn feed_byte(&mut self, b: u8) -> bool {
107        // String literal handling
108        if self.in_string {
109            if b == b'"' {
110                self.in_string = false;
111            }
112            return true;
113        }
114
115        if b == b'"' {
116            self.in_string = true;
117            return true;
118        }
119
120        // Bracket depth tracking
121        match b {
122            b'{' => self.brace_depth += 1,
123            b'}' => {
124                if self.brace_depth == 0 {
125                    return false;
126                }
127                self.brace_depth -= 1;
128                if self.brace_depth == 0 {
129                    self.item_complete = true;
130                }
131            }
132            b'(' => self.paren_depth += 1,
133            b')' => {
134                if self.paren_depth == 0 {
135                    return false;
136                }
137                self.paren_depth -= 1;
138            }
139            b';' => {
140                if self.brace_depth == 0 {
141                    self.item_complete = true;
142                }
143            }
144            _ => {}
145        }
146
147        if self.partial_len < 127 {
148            self.partial_match[self.partial_len] = b;
149            self.partial_len += 1;
150        }
151
152        true
153    }
154
155    /// Accept a full token string and transition the grammar state.
156    pub fn accept_token(&mut self, token_str: &str) -> bool {
157        for b in token_str.as_bytes() {
158            if !self.feed_byte(*b) {
159                return false;
160            }
161        }
162        true
163    }
164
165    /// Apply grammar constraint mask to raw model output logits.
166    /// Invalid tokens that violate VibeScript syntax are masked to -INFINITY.
167    pub fn mask_logits(&self, logits: &mut [f32], vocab: &[&str]) {
168        for (token_id, &token_str) in vocab.iter().enumerate() {
169            if token_id < logits.len() && !self.is_valid_continuation(token_str.as_bytes()) {
170                logits[token_id] = -f32::INFINITY;
171            }
172        }
173    }
174}
175
176/// High-level VibeScript GBNF Decoder wrapper.
177#[derive(Debug, Clone)]
178pub struct DominoVibeDecoder {
179    state: DominoGrammarState,
180}
181
182impl DominoVibeDecoder {
183    /// Creates a default `DominoVibeDecoder`.
184    pub const fn new() -> Self {
185        Self {
186            state: DominoGrammarState::new(),
187        }
188    }
189
190    /// Filter next token logits according to VibeScript grammar.
191    pub fn filter_logits(&self, logits: &mut [f32], vocab: &[&str]) {
192        self.state.mask_logits(logits, vocab);
193    }
194
195    /// Advance decoder state with the selected token.
196    pub fn step(&mut self, token_str: &str) -> bool {
197        self.state.accept_token(token_str)
198    }
199
200    /// Reset decoder state.
201    pub fn reset(&mut self) {
202        self.state.reset();
203    }
204}
205
206impl Default for DominoVibeDecoder {
207    fn default() -> Self {
208        Self::new()
209    }
210}
211
212#[cfg(test)]
213mod tests {
214    use super::*;
215
216    #[test]
217    fn test_valid_bracket_nesting() {
218        let mut state = DominoGrammarState::new();
219        assert!(state.accept_token("fn main() { return 1; }"));
220        assert_eq!(state.brace_depth, 0);
221        assert_eq!(state.paren_depth, 0);
222    }
223
224    #[test]
225    fn test_rejects_unbalanced_closing_brace() {
226        let mut state = DominoGrammarState::new();
227        assert!(!state.accept_token("}"));
228    }
229
230    #[test]
231    fn test_masks_invalid_token() {
232        let state = DominoGrammarState::new();
233        let vocab = ["fn", "{", "}", "let"];
234        let mut logits = vec![0.0f32; 4];
235
236        state.mask_logits(&mut logits, &vocab);
237
238        // '}' is invalid at root level because brace_depth == 0
239        assert_eq!(logits[2], -f32::INFINITY);
240        // 'fn' and 'let' are valid continuations
241        assert_eq!(logits[0], 0.0);
242        assert_eq!(logits[3], 0.0);
243    }
244}