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}