Skip to main content

qualia_core_db/inference/
sampler.rs

1//! W2 — exact CPU sampling chain for decode.
2//!
3//! The native decode loop selects tokens by pure greedy argmax, which is prone to the
4//! repetition collapse documented across the bench probes. This module adds a full,
5//! llama.cpp-compatible sampling chain that runs on the CPU over the full logit vector
6//! (read back once per token — acceptable at the W1 one-fence-per-token cost):
7//!
8//!   repetition/frequency/presence penalties → temperature → top-k → top-p → seeded draw
9//!
10//! Design invariants:
11//! - **Greedy is a hard short-circuit.** `temperature <= 0` returns the argmax BEFORE any
12//!   penalty or filter is applied, so greedy decode is bit-identical to the pre-W2 path and
13//!   the a1a/a1c/a1d guarantees are untouched.
14//! - **Deterministic.** The draw uses a self-contained SplitMix64 PRNG seeded from the config;
15//!   the same seed + same logits + same context reproduce the same token, on native and wasm
16//!   (no `rand`, no float transcendentals in the RNG, no platform entropy).
17//! - **Exact, not top-K-approximated.** The chain runs over the whole vocabulary; top-k / top-p
18//!   are applied as masks, never as a lossy pre-reduction on the GPU.
19//! - **Pure + zero-GPU.** Everything here is testable without a device or a model.
20
21/// Sampling parameters. `temperature <= 0.0` ⇒ greedy argmax (all other fields ignored).
22///
23/// The canonical wire form is a CBOR map (the project's CBOR-first payload substrate) — see
24/// [`SamplerConfig::to_cbor`] / [`SamplerConfig::from_cbor`]. Transports that are JSON-enveloped
25/// (e.g. the MCP boundary) carry it as a hex-encoded CBOR blob, decoded via the existing JSON
26/// string helper — no ad-hoc per-field JSON float parsing.
27#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
28pub struct SamplerConfig {
29    /// Softmax temperature. `<= 0.0` selects greedy argmax (the pre-W2 default behaviour).
30    pub temperature: f32,
31    /// Keep only the `top_k` highest-logit tokens (`0` ⇒ no top-k limit).
32    pub top_k: u32,
33    /// Nucleus threshold in `(0.0, 1.0]`; keep the smallest set whose cumulative prob ≥ `top_p`
34    /// (`>= 1.0` ⇒ no top-p limit).
35    pub top_p: f32,
36    /// Multiplicative penalty on logits of tokens present in the penalty window (`1.0` ⇒ none).
37    pub repeat_penalty: f32,
38    /// Additive penalty per prior occurrence in the window (subtracted from the logit).
39    pub freq_penalty: f32,
40    /// Additive penalty for any presence in the window (subtracted once).
41    pub presence_penalty: f32,
42    /// Number of most-recent context tokens the penalties consider (`0` ⇒ whole context).
43    pub penalty_window: u32,
44    /// PRNG seed — fixed seed ⇒ reproducible draws.
45    pub seed: u64,
46}
47
48impl Default for SamplerConfig {
49    fn default() -> Self {
50        // Default is GREEDY (temperature 0) so an unconfigured caller gets the pre-W2 behaviour.
51        Self {
52            temperature: 0.0,
53            top_k: 0,
54            top_p: 1.0,
55            repeat_penalty: 1.0,
56            freq_penalty: 0.0,
57            presence_penalty: 0.0,
58            penalty_window: 64,
59            seed: 0,
60        }
61    }
62}
63
64impl SamplerConfig {
65    /// True when this config selects the greedy argmax short-circuit.
66    #[inline]
67    pub fn is_greedy(&self) -> bool {
68        !(self.temperature > 0.0)
69    }
70
71    /// Encode as a CBOR map (the canonical payload form). Infallible for this fixed scalar schema.
72    pub fn to_cbor(&self) -> Vec<u8> {
73        let mut buf = Vec::new();
74        // ciborium only fails here on an allocator/writer error, which `Vec` never raises.
75        let _ = ciborium::into_writer(self, &mut buf);
76        buf
77    }
78
79    /// Decode from a CBOR map payload. Returns `None` on malformed CBOR or a schema mismatch —
80    /// the caller then keeps greedy decode rather than sampling on a bad config.
81    pub fn from_cbor(bytes: &[u8]) -> Option<Self> {
82        ciborium::from_reader(bytes).ok()
83    }
84
85    /// A sensible default for interactive chat / instruct generation: enough randomness to avoid the
86    /// greedy repetition-collapse, plus a light repeat penalty, while staying reproducible (fixed
87    /// seed). Benchmarks and determinism tests must NOT install this — the unconfigured global stays
88    /// greedy, preserving the bit-exact a1a/a6a guarantees.
89    pub fn chat_default() -> Self {
90        Self {
91            temperature: 0.7,
92            top_k: 40,
93            top_p: 0.95,
94            repeat_penalty: 1.1,
95            freq_penalty: 0.0,
96            presence_penalty: 0.0,
97            penalty_window: 64,
98            seed: 0,
99        }
100    }
101}
102
103/// Stateful sampler: owns the PRNG stream so successive tokens advance it deterministically.
104#[derive(Debug, Clone)]
105pub struct SamplerState {
106    pub cfg: SamplerConfig,
107    rng: u64,
108}
109
110/// SplitMix64 — tiny, allocation-free, platform-independent PRNG (Steele et al. 2014).
111#[inline]
112fn splitmix64(state: &mut u64) -> u64 {
113    *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
114    let mut z = *state;
115    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
116    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
117    z ^ (z >> 31)
118}
119
120impl SamplerState {
121    /// Creates a default `SamplerState`.
122    pub fn new(cfg: SamplerConfig) -> Self {
123        // Avoid the all-zero SplitMix64 fixed point; mix the seed once.
124        let mut rng = cfg.seed ^ 0x2545_F491_4F6C_DD1D;
125        let _ = splitmix64(&mut rng);
126        Self { cfg, rng }
127    }
128
129    /// Uniform f32 in `[0, 1)` from the PRNG stream (53-bit mantissa precision).
130    #[inline]
131    fn next_unit(&mut self) -> f32 {
132        let bits = splitmix64(&mut self.rng) >> 11; // 53 bits
133        (bits as f64 * (1.0 / (1u64 << 53) as f64)) as f32
134    }
135
136    /// Argmax with lowest-token-id tie-break — identical selection rule to the CPU argmax path.
137    #[inline]
138    fn argmax(logits: &[f32]) -> u32 {
139        let mut best_i = 0u32;
140        let mut best_v = f32::NEG_INFINITY;
141        for (i, &v) in logits.iter().enumerate() {
142            if v > best_v {
143                best_v = v;
144                best_i = i as u32;
145            }
146        }
147        best_i
148    }
149
150    /// Sample the next token id. `logits` is the full vocab (mutated in place as a scratch buffer);
151    /// `ctx` is the running token history (prompt + generated) for the penalty window.
152    ///
153    /// Greedy (`temperature <= 0`) returns the argmax with no mutation of selection semantics.
154    pub fn sample(&mut self, logits: &mut [f32], ctx: &[u32]) -> u32 {
155        if logits.is_empty() {
156            return 0;
157        }
158        if self.cfg.is_greedy() {
159            return Self::argmax(logits);
160        }
161        let vocab = logits.len();
162
163        // 1) Penalties over the penalty window (most-recent N context tokens).
164        let (rp, fp, pp) = (
165            self.cfg.repeat_penalty,
166            self.cfg.freq_penalty,
167            self.cfg.presence_penalty,
168        );
169        if rp != 1.0 || fp != 0.0 || pp != 0.0 {
170            let window = if self.cfg.penalty_window == 0 {
171                ctx.len()
172            } else {
173                (self.cfg.penalty_window as usize).min(ctx.len())
174            };
175            // Count occurrences of each in-window token id (only ids within vocab matter).
176            // A small hashmap-free pass: walk the window, apply per occurrence.
177            let start = ctx.len() - window;
178            // presence needs "seen at least once" — track via first-touch using freq accumulation.
179            for &tok in &ctx[start..] {
180                let t = tok as usize;
181                if t >= vocab {
182                    continue;
183                }
184                let l = logits[t];
185                // repeat_penalty: divide positive logits, multiply negative (llama.cpp convention).
186                if rp != 1.0 {
187                    logits[t] = if l > 0.0 { l / rp } else { l * rp };
188                }
189                if fp != 0.0 {
190                    logits[t] -= fp; // per-occurrence frequency penalty
191                }
192            }
193            if pp != 0.0 {
194                // presence: subtract once per DISTINCT in-window id. Second pass with a seen-guard
195                // built from the window (bounded, no alloc beyond a small local set is avoided by
196                // re-scanning — window is small, and this keeps the module alloc-free).
197                for (rel, &tok) in ctx[start..].iter().enumerate() {
198                    let t = tok as usize;
199                    if t >= vocab {
200                        continue;
201                    }
202                    // apply only on first occurrence within the window
203                    let first = ctx[start..start + rel].iter().all(|&p| p != tok);
204                    if first {
205                        logits[t] -= pp;
206                    }
207                }
208            }
209        }
210
211        // 2) Temperature scale.
212        let inv_t = 1.0 / self.cfg.temperature;
213        for l in logits.iter_mut() {
214            *l *= inv_t;
215        }
216
217        // 3) Build an index list sorted by logit desc (stable tie-break by id) for top-k / top-p.
218        //    Vocab is ~50k; one sort/token is cheap next to a forward pass.
219        let mut order: Vec<u32> = (0..vocab as u32).collect();
220        order.sort_unstable_by(|&a, &b| {
221            let (la, lb) = (logits[a as usize], logits[b as usize]);
222            lb.partial_cmp(&la)
223                .unwrap_or(std::cmp::Ordering::Equal)
224                .then(a.cmp(&b))
225        });
226
227        // 4) top-k truncation.
228        let mut keep = if self.cfg.top_k > 0 {
229            (self.cfg.top_k as usize).min(vocab)
230        } else {
231            vocab
232        };
233
234        // 5) Softmax over the kept prefix (numerically stable), then top-p nucleus truncation.
235        let max_l = logits[order[0] as usize];
236        let mut probs: Vec<f32> = Vec::with_capacity(keep);
237        let mut sum = 0.0f32;
238        for &id in &order[..keep] {
239            let p = (logits[id as usize] - max_l).exp();
240            probs.push(p);
241            sum += p;
242        }
243        if sum <= 0.0 || !sum.is_finite() {
244            return order[0]; // degenerate — fall back to the top logit
245        }
246        if self.cfg.top_p < 1.0 && self.cfg.top_p > 0.0 {
247            let mut cum = 0.0f32;
248            let mut nucleus = keep;
249            for (i, p) in probs.iter().enumerate() {
250                cum += p / sum;
251                if cum >= self.cfg.top_p {
252                    nucleus = i + 1;
253                    break;
254                }
255            }
256            keep = nucleus.max(1);
257            probs.truncate(keep);
258            sum = probs.iter().sum();
259        }
260
261        // 6) Seeded categorical draw over the kept nucleus.
262        let r = self.next_unit() * sum;
263        let mut acc = 0.0f32;
264        for (i, p) in probs.iter().enumerate() {
265            acc += *p;
266            if r < acc {
267                return order[i];
268            }
269        }
270        order[keep - 1]
271    }
272
273    /// Sample with a DOMINO constrained-decoding mask applied first.
274    ///
275    /// This is the R9 integration point: the decode loop calls this instead
276    /// of [`sample`](Self::sample) when a `DominoMasker()` is active. The
277    /// masker sets disallowed token logits to `-inf` before the sampling
278    /// chain runs, so the sampler can only select grammar-valid tokens.
279    ///
280    /// When the masker is inactive (`!is_active()`), this is equivalent to
281    /// calling `sample` directly — the mask is a no-op.
282    ///
283    /// After sampling, the chosen token's bytes should be fed back into the
284    /// masker via `DominoMasker::feed_token()` so the grammar state advances.
285    pub fn sample_constrained(
286        &mut self,
287        logits: &mut [f32],
288        ctx: &[u32],
289        masker: &mut crate::inference::speculative_decode::DominoMasker,
290    ) -> u32 {
291        masker.apply_mask_preserving(logits);
292        let token = self.sample(logits, ctx);
293        // Feed the token bytes back into the grammar state. The caller is
294        // responsible for looking up the token bytes in the vocabulary and
295        // calling `feed_token` if they want the grammar to advance. We do
296        // NOT do that here because we don't have the vocabulary mapping.
297        // The caller should call `masker.feed_token_id(token, &vocab)`
298        // after this returns.
299        token
300    }
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306
307    fn logits(vals: &[f32]) -> Vec<f32> {
308        vals.to_vec()
309    }
310
311    #[test]
312    fn t1_greedy_returns_argmax() {
313        let cfg = SamplerConfig::default(); // temperature 0 ⇒ greedy
314        let mut s = SamplerState::new(cfg);
315        let mut l = logits(&[0.1, 0.9, 0.3, 0.9]); // tie between id 1 and 3 → lowest id wins
316        assert_eq!(s.sample(&mut l, &[]), 1);
317    }
318
319    #[test]
320    fn t2_same_seed_same_sequence() {
321        let cfg = SamplerConfig {
322            temperature: 1.0,
323            seed: 42,
324            ..Default::default()
325        };
326        let base = [2.0f32, 1.0, 0.5, 0.2, -1.0, 3.0, 0.0, 1.5];
327        let draw = |seed: u64| {
328            let mut s = SamplerState::new(SamplerConfig { seed, ..cfg });
329            (0..100)
330                .map(|_| s.sample(&mut base.to_vec(), &[]))
331                .collect::<Vec<_>>()
332        };
333        assert_eq!(draw(42), draw(42), "same seed must reproduce the sequence");
334    }
335
336    #[test]
337    fn t3_different_seed_diverges() {
338        let cfg = SamplerConfig {
339            temperature: 1.5,
340            seed: 1,
341            ..Default::default()
342        };
343        let base = [1.0f32, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]; // uniform ⇒ draws depend only on rng
344        let seq = |seed: u64| {
345            let mut s = SamplerState::new(SamplerConfig { seed, ..cfg });
346            (0..100)
347                .map(|_| s.sample(&mut base.to_vec(), &[]))
348                .collect::<Vec<_>>()
349        };
350        assert_ne!(
351            seq(1),
352            seq(999),
353            "different seeds should diverge on a uniform dist"
354        );
355    }
356
357    #[test]
358    fn t4_top_k_1_is_argmax_any_temperature() {
359        for temp in [0.5f32, 1.0, 2.0, 5.0] {
360            let cfg = SamplerConfig {
361                temperature: temp,
362                top_k: 1,
363                seed: 7,
364                ..Default::default()
365            };
366            let mut s = SamplerState::new(cfg);
367            let mut l = logits(&[0.2, 0.1, 2.5, 0.4, 2.5]); // argmax id 2 (tie→lowest)
368            assert_eq!(
369                s.sample(&mut l, &[]),
370                2,
371                "top_k=1 must equal argmax at T={temp}"
372            );
373        }
374    }
375
376    #[test]
377    fn t5_repeat_penalty_suppresses_repeat() {
378        // id 0 is the clear argmax; with a strong repeat penalty and it in-context, it must lose.
379        let cfg = SamplerConfig {
380            temperature: 1.0,
381            top_k: 1, // deterministic: pick the post-penalty argmax
382            repeat_penalty: 100.0,
383            penalty_window: 8,
384            seed: 3,
385            ..Default::default()
386        };
387        let mut s = SamplerState::new(cfg);
388        let mut l = logits(&[5.0, 4.0, 3.0, 2.0]);
389        let picked = s.sample(&mut l, &[0, 0, 0]); // id 0 heavily penalized
390        assert_ne!(
391            picked, 0,
392            "repeated token should be suppressed below the runner-up"
393        );
394        assert_eq!(picked, 1);
395    }
396
397    #[test]
398    fn t6_top_p_head_only() {
399        // One dominant token; top_p=0.5 must keep only it, so the draw is deterministic.
400        let cfg = SamplerConfig {
401            temperature: 1.0,
402            top_p: 0.5,
403            seed: 11,
404            ..Default::default()
405        };
406        let mut s = SamplerState::new(cfg);
407        // softmax([10,0,0,0]) ≈ [0.9999,...]; nucleus 0.5 keeps just id 0.
408        let l = logits(&[10.0, 0.0, 0.0, 0.0]);
409        for _ in 0..20 {
410            assert_eq!(s.sample(&mut l.clone(), &[]), 0);
411        }
412    }
413
414    #[test]
415    fn t7_greedy_ignores_penalties() {
416        // Greedy short-circuits BEFORE penalties — proves the a1a/a1c/a1d greedy contract holds.
417        let cfg = SamplerConfig {
418            temperature: 0.0,
419            repeat_penalty: 100.0,
420            presence_penalty: 100.0,
421            seed: 5,
422            ..Default::default()
423        };
424        let mut s = SamplerState::new(cfg);
425        let mut l = logits(&[5.0, 4.0, 3.0]);
426        assert_eq!(
427            s.sample(&mut l, &[0, 0, 0]),
428            0,
429            "greedy must ignore penalties and return argmax"
430        );
431    }
432
433    #[test]
434    fn t9_cbor_round_trip() {
435        let cfg = SamplerConfig {
436            temperature: 0.8,
437            top_k: 40,
438            top_p: 0.95,
439            repeat_penalty: 1.1,
440            freq_penalty: 0.2,
441            presence_penalty: 0.1,
442            penalty_window: 128,
443            seed: 0xDEAD_BEEF,
444        };
445        let bytes = cfg.to_cbor();
446        let back = SamplerConfig::from_cbor(&bytes).expect("cbor round-trip");
447        assert_eq!(back.temperature, cfg.temperature);
448        assert_eq!(back.top_k, cfg.top_k);
449        assert_eq!(back.top_p, cfg.top_p);
450        assert_eq!(back.repeat_penalty, cfg.repeat_penalty);
451        assert_eq!(back.freq_penalty, cfg.freq_penalty);
452        assert_eq!(back.presence_penalty, cfg.presence_penalty);
453        assert_eq!(back.penalty_window, cfg.penalty_window);
454        assert_eq!(back.seed, cfg.seed);
455        // Malformed CBOR ⇒ None (caller falls back to greedy, never samples on garbage).
456        assert!(SamplerConfig::from_cbor(&[0xFF, 0x00, 0x13, 0x37]).is_none());
457    }
458
459    #[test]
460    fn t8_presence_once_per_distinct() {
461        // presence penalty applies once per distinct id regardless of count.
462        let cfg = SamplerConfig {
463            temperature: 1.0,
464            top_k: 1,
465            presence_penalty: 1.5,
466            penalty_window: 16,
467            seed: 2,
468            ..Default::default()
469        };
470        let mut s = SamplerState::new(cfg);
471        // id0 logit 5, id1 logit 4. presence -1.5 to id0 (appears 3x, once applied) → 3.5 < 4 → id1.
472        let mut l = logits(&[5.0, 4.0, 0.0]);
473        assert_eq!(s.sample(&mut l, &[0, 0, 0]), 1);
474    }
475
476    #[test]
477    fn t10_chat_default_is_non_greedy_reproducible() {
478        let cfg = SamplerConfig::chat_default();
479        assert!(
480            !cfg.is_greedy(),
481            "chat default must sample, not fall back to greedy"
482        );
483        assert!(cfg.temperature > 0.0 && cfg.top_p <= 1.0 && cfg.repeat_penalty > 1.0);
484        // Seeded ⇒ reproducible: the same config reproduces the same draw sequence.
485        let base = [2.0f32, 1.0, 0.5, 3.0, 0.2, 1.5];
486        let run = || {
487            let mut s = SamplerState::new(SamplerConfig::chat_default());
488            (0..50)
489                .map(|_| s.sample(&mut base.to_vec(), &[]))
490                .collect::<Vec<_>>()
491        };
492        assert_eq!(
493            run(),
494            run(),
495            "chat default must be reproducible for a fixed seed"
496        );
497    }
498
499    // ── R9: DOMINO sampler integration ──────────────────────────────────
500
501    fn domino_vocab() -> Vec<(u32, String)> {
502        vec![
503            (0, "=".to_string()),
504            (1, " ".to_string()),
505            (2, "\n".to_string()),
506            (3, "module".to_string()),
507            (4, "import".to_string()),
508            (5, "fn".to_string()),
509            (6, "let".to_string()),
510            (7, "return".to_string()),
511            (8, "x".to_string()),
512            (9, "42".to_string()),
513            (10, ";".to_string()),
514            (11, "{".to_string()),
515            (12, "}".to_string()),
516            (13, "(".to_string()),
517            (14, ")".to_string()),
518            (15, "1".to_string()),
519            (16, "2".to_string()),
520            (17, "test".to_string()),
521            (18, "abc".to_string()),
522        ]
523    }
524
525    #[test]
526    fn r9_constrained_sample_inactive_equals_plain() {
527        // When the masker is inactive, sample_constrained == sample.
528        // Use two separate sampler states with the same seed so the PRNG
529        // streams are identical.
530        let cfg = SamplerConfig {
531            temperature: 1.0,
532            seed: 7,
533            ..Default::default()
534        };
535        let vocab = domino_vocab();
536        let mut masker = crate::inference::speculative_decode::DominoMasker::new(&vocab);
537        // Masker is inactive by default.
538        assert!(!masker.is_active());
539
540        let mut s1 = SamplerState::new(cfg);
541        let mut s2 = SamplerState::new(cfg);
542        let base: Vec<f32> = (0..vocab.len() as i32).map(|i| i as f32 * 0.1).collect();
543
544        let mut l1 = base.clone();
545        let mut l2 = base.clone();
546        let t1 = s1.sample(&mut l1, &[]);
547        let t2 = s2.sample_constrained(&mut l2, &[], &mut masker);
548        assert_eq!(t1, t2, "inactive masker must not change sampling");
549    }
550
551    #[test]
552    fn r9_constrained_sample_only_returns_valid_tokens() {
553        // When the masker is active, the sampled token must be in the
554        // grammar-valid set. At Start state, only tokens starting with
555        // '=', whitespace, or alpha are valid — digits and braces are not.
556        let cfg = SamplerConfig {
557            temperature: 1.0,
558            top_k: 0, // no truncation — let the mask do the work
559            top_p: 1.0,
560            seed: 99,
561            ..Default::default()
562        };
563        let vocab = domino_vocab();
564        let mut masker = crate::inference::speculative_decode::DominoMasker::new(&vocab);
565        masker.enable();
566        assert!(masker.is_active());
567
568        let mut s = SamplerState::new(cfg);
569
570        // Give digit tokens (15="1", 16="2", 9="42") very high logits.
571        // If the mask works, they should be masked to -inf and never sampled.
572        let mut logits = vec![0.1f32; vocab.len()];
573        logits[15] = 100.0; // "1" — invalid at Start
574        logits[16] = 99.0; // "2" — invalid at Start
575        logits[9] = 98.0; // "42" — invalid at Start
576        logits[8] = 1.0; // "x" — valid at Start
577
578        // Sample many times — should never return a digit token.
579        for _ in 0..100 {
580            let mut l = logits.clone();
581            let token = s.sample_constrained(&mut l, &[], &mut masker);
582            // Token 9 ("42"), 15 ("1"), 16 ("2") should never be sampled.
583            assert_ne!(token, 9, "digit token '42' should be masked");
584            assert_ne!(token, 15, "digit token '1' should be masked");
585            assert_ne!(token, 16, "digit token '2' should be masked");
586            // Reset grammar state for the next iteration (we're not feeding
587            // tokens here, just testing the mask at Start state).
588            masker.reset();
589        }
590    }
591
592    #[test]
593    fn r9_constrained_sample_greedy_with_mask() {
594        // Greedy + mask: the argmax should be the highest-logit VALID token,
595        // not the highest-logit token overall.
596        let cfg = SamplerConfig::default(); // greedy (temperature 0)
597        let vocab = domino_vocab();
598        let mut masker = crate::inference::speculative_decode::DominoMasker::new(&vocab);
599        masker.enable();
600
601        let mut s = SamplerState::new(cfg);
602
603        // Token 15 ("1") has the highest logit but is invalid at Start.
604        // Token 8 ("x") has a lower logit but is valid.
605        let mut logits = vec![0.1f32; vocab.len()];
606        logits[15] = 100.0; // "1" — invalid
607        logits[8] = 50.0; // "x" — valid
608
609        let token = s.sample_constrained(&mut logits, &[], &mut masker);
610        // Greedy should pick the highest VALID token, not the highest overall.
611        // "1" is masked to -inf, so "x" (id 8) should win.
612        // But we need to check: are there other valid tokens with higher logits?
613        // At Start, valid tokens are: 0 ("="), 1 (" "), 2 ("\n"), 3 ("module"),
614        // 4 ("import"), 5 ("fn"), 6 ("let"), 7 ("return"), 8 ("x"), 17 ("test"),
615        // 18 ("abc"). Token 8 has logit 50.0, all others have 0.1. So 8 wins.
616        assert_eq!(token, 8, "greedy + mask should pick highest valid token");
617    }
618
619    #[test]
620    fn r9_constrained_sample_preserves_logit_values() {
621        // The apply_mask_preserving method should keep original logit values
622        // for valid tokens, not zero them out.
623        let cfg = SamplerConfig {
624            temperature: 1.0,
625            seed: 3,
626            ..Default::default()
627        };
628        let vocab = domino_vocab();
629        let mut masker = crate::inference::speculative_decode::DominoMasker::new(&vocab);
630        masker.enable();
631
632        let mut s = SamplerState::new(cfg);
633        let mut logits = vec![0.0f32; vocab.len()];
634        logits[8] = 5.0; // "x" — valid at Start
635        logits[3] = 3.0; // "module" — valid at Start
636        logits[15] = 10.0; // "1" — invalid at Start
637
638        // The sampler should be able to distinguish between valid tokens
639        // based on their original logit values (not just pick any valid one).
640        // With temperature 1.0 and seed 3, token 8 (logit 5.0) should be
641        // sampled more often than token 3 (logit 3.0).
642        let mut count_8 = 0;
643        let mut count_3 = 0;
644        for _ in 0..1000 {
645            let mut l = logits.clone();
646            let token = s.sample_constrained(&mut l, &[], &mut masker);
647            if token == 8 {
648                count_8 += 1;
649            } else if token == 3 {
650                count_3 += 1;
651            }
652            masker.reset();
653        }
654        // Token 8 has higher logit → should be sampled more often.
655        assert!(
656            count_8 > count_3,
657            "higher-logit valid token should be sampled more often (8: {count_8}, 3: {count_3})"
658        );
659    }
660}