Skip to main content

logit_loom/
transform.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Ordered, transactional logit-transform pipelines.
4
5use std::any::Any;
6use std::collections::HashSet;
7use std::panic::{AssertUnwindSafe, catch_unwind};
8
9use logit_loom_core::{
10    CallbackFailure, CallbackPhase, CandidateMode, MAX_PIPELINE_STAGES, PipelineReceipt,
11    PipelineSpec, StageReceipt, TokenId, TransformSpec,
12};
13
14use crate::{PipelineError, TransformError};
15
16/// Borrowed state supplied to one Rust logit-transform invocation.
17pub struct TransformContext<'a> {
18    step: u32,
19    causal_tokens: &'a [TokenId],
20    candidate_tokens: &'a [TokenId],
21    logits: &'a mut [f32],
22}
23
24impl<'a> TransformContext<'a> {
25    /// Creates a validated borrowed candidate view.
26    ///
27    /// # Errors
28    ///
29    /// Returns an error when token and logit lengths disagree.
30    pub fn new(
31        step: u32,
32        causal_tokens: &'a [TokenId],
33        candidate_tokens: &'a [TokenId],
34        logits: &'a mut [f32],
35    ) -> Result<Self, PipelineError> {
36        if candidate_tokens.len() != logits.len() || candidate_tokens.is_empty() {
37            return Err(PipelineError::InvalidCandidates(
38                "token and logit arrays must be non-empty and equal in length".to_owned(),
39            ));
40        }
41        Ok(Self {
42            step,
43            causal_tokens,
44            candidate_tokens,
45            logits,
46        })
47    }
48
49    /// Zero-based sampling step.
50    pub const fn step(&self) -> u32 {
51        self.step
52    }
53
54    /// Exact prompt and previously admitted generation tokens.
55    pub const fn causal_tokens(&self) -> &[TokenId] {
56        self.causal_tokens
57    }
58
59    /// Immutable candidate token identifiers.
60    pub const fn candidate_tokens(&self) -> &[TokenId] {
61        self.candidate_tokens
62    }
63
64    /// Mutable candidate logits corresponding one-for-one with token IDs.
65    pub fn logits_mut(&mut self) -> &mut [f32] {
66        self.logits
67    }
68
69    /// Iterates token/logit pairs without permitting token-ID mutation.
70    pub fn candidates_mut(&mut self) -> impl Iterator<Item = (TokenId, &mut f32)> {
71        self.candidate_tokens
72            .iter()
73            .copied()
74            .zip(self.logits.iter_mut())
75    }
76}
77
78/// Safe, synchronous implementation of one per-step logit transformation.
79pub trait LogitTransform {
80    /// Resets implementation-local state for a fresh generation call.
81    ///
82    /// # Errors
83    ///
84    /// Returns an implementation-defined reset failure.
85    fn reset(&mut self, _causal_tokens: &[TokenId]) -> Result<(), TransformError> {
86        Ok(())
87    }
88
89    /// Mutates one candidate-logit view.
90    ///
91    /// # Errors
92    ///
93    /// Returns an implementation-defined transformation failure.
94    fn apply(&mut self, context: TransformContext<'_>) -> Result<(), TransformError>;
95
96    /// Observes a token after the backend has admitted it to causal state.
97    ///
98    /// # Errors
99    ///
100    /// Returns an implementation-defined token-admission failure.
101    fn accept(&mut self, _token: TokenId) -> Result<(), TransformError> {
102        Ok(())
103    }
104}
105
106/// One identified implementation in an ordered pipeline.
107pub struct Stage {
108    specification: TransformSpec,
109    implementation: Box<dyn LogitTransform>,
110}
111
112impl Stage {
113    /// Wraps a safe Rust transform with its mechanical contract.
114    ///
115    /// # Errors
116    ///
117    /// Returns an error when the specification is invalid.
118    pub fn new(
119        specification: TransformSpec,
120        implementation: impl LogitTransform + 'static,
121    ) -> Result<Self, PipelineError> {
122        specification.validate()?;
123        Ok(Self {
124            specification,
125            implementation: Box::new(implementation),
126        })
127    }
128
129    /// Returns the stage contract.
130    pub const fn specification(&self) -> &TransformSpec {
131        &self.specification
132    }
133}
134
135/// Ordered, call-scoped transform pipeline.
136///
137/// Candidate changes are committed to the backend view only after every stage
138/// succeeds. A returned error therefore cannot expose a partially transformed
139/// vocabulary, although implementation-local state in stages that already ran
140/// may have changed. Begin a fresh call before retrying.
141pub struct Pipeline {
142    specification: PipelineSpec,
143    stages: Vec<Stage>,
144    receipt: PipelineReceipt,
145    begun: bool,
146    failed: bool,
147}
148
149impl Pipeline {
150    /// Creates an ordered pipeline of one to 32 compatible stages.
151    ///
152    /// # Errors
153    ///
154    /// Returns an error for an invalid stage count or incompatible modes.
155    pub fn new(stages: Vec<Stage>) -> Result<Self, PipelineError> {
156        let specification = PipelineSpec {
157            stages: stages
158                .iter()
159                .take(MAX_PIPELINE_STAGES + 1)
160                .map(|stage| stage.specification.clone())
161                .collect(),
162        };
163        specification.validate()?;
164        let receipt = empty_receipt(&specification)?;
165        Ok(Self {
166            specification,
167            stages,
168            receipt,
169            begun: false,
170            failed: false,
171        })
172    }
173
174    /// Returns the immutable ordered specification.
175    pub const fn specification(&self) -> &PipelineSpec {
176        &self.specification
177    }
178
179    /// Returns current mechanical accounting.
180    pub fn receipt(&self) -> PipelineReceipt {
181        self.receipt.clone()
182    }
183
184    /// Returns whether a callback has failed since the last begin.
185    pub const fn is_failed(&self) -> bool {
186        self.failed
187    }
188
189    /// Resets every stage for a new generation call.
190    ///
191    /// # Errors
192    ///
193    /// Returns a contained callback failure. Calling `begin` again constructs
194    /// fresh accounting and asks every stage to reset again.
195    pub fn begin(&mut self, causal_tokens: &[TokenId]) -> Result<(), PipelineError> {
196        self.receipt = empty_receipt(&self.specification)?;
197        self.receipt.begins = 1;
198        self.begun = true;
199        self.failed = false;
200        for index in 0..self.stages.len() {
201            self.receipt.stages[index].resets = 1;
202            let result = catch_unwind(AssertUnwindSafe(|| {
203                self.stages[index].implementation.reset(causal_tokens)
204            }));
205            if let Some(failure) = callback_result(CallbackPhase::Reset, result) {
206                return Err(self.record_failure(index, failure));
207            }
208        }
209        Ok(())
210    }
211
212    /// Applies the pipeline to a complete vocabulary-logit slice.
213    ///
214    /// Sparse pipelines select the highest finite raw logits, breaking ties by
215    /// ascending token ID. Full pipelines expose tokenizer order. Candidate
216    /// output containing NaN is rejected before write-back; infinity remains a
217    /// valid explicit suppression or promotion value. Except for a terminal
218    /// selection, the prior successful step must be matched by [`Self::accept`]
219    /// before the next step begins.
220    ///
221    /// # Errors
222    ///
223    /// Returns an error when the call has not begun, bounds are exceeded, the
224    /// vocabulary is invalid, lifecycle order is violated, or a callback
225    /// fails.
226    pub fn apply_to_vocabulary(
227        &mut self,
228        step: u32,
229        causal_tokens: &[TokenId],
230        vocabulary_logits: &mut [f32],
231    ) -> Result<(), PipelineError> {
232        self.require_ready()?;
233        let maximum_vocabulary = usize::try_from(i32::MAX).unwrap_or(usize::MAX);
234        if vocabulary_logits.is_empty() || vocabulary_logits.len() > maximum_vocabulary {
235            return Err(PipelineError::InvalidCandidates(
236                "vocabulary must fit non-negative i32 token identifiers".to_owned(),
237            ));
238        }
239        let mode = self.specification.mode()?;
240        let indices = selected_indices(mode, vocabulary_logits);
241        if indices.is_empty() {
242            return Err(PipelineError::InvalidCandidates(
243                "candidate exposure selected no finite logits".to_owned(),
244            ));
245        }
246        let candidate_tokens = indices
247            .iter()
248            .map(|index| {
249                TokenId::new(i32::try_from(*index).map_err(|_| {
250                    PipelineError::InvalidCandidates("token identifier overflowed".to_owned())
251                })?)
252                .map_err(PipelineError::from)
253            })
254            .collect::<Result<Vec<_>, _>>()?;
255        let mut candidate_logits = indices
256            .iter()
257            .map(|index| vocabulary_logits[*index])
258            .collect::<Vec<_>>();
259        self.apply_working_candidates(
260            step,
261            causal_tokens,
262            &candidate_tokens,
263            &mut candidate_logits,
264        )?;
265
266        for (index, value) in indices.into_iter().zip(candidate_logits) {
267            vocabulary_logits[index] = value;
268        }
269        Ok(())
270    }
271
272    /// Applies the pipeline to a candidate view selected by a backend adapter.
273    ///
274    /// This entry point is for adapters whose native sampler has already copied
275    /// token IDs and logits into an owned scratch view. The adapter remains
276    /// responsible for proving that a full-mode view covers the vocabulary and
277    /// that sparse candidates were selected according to its declared native
278    /// boundary. Logit Loom enforces shape, sparse bounds, stage limits, panic
279    /// containment, NaN rejection, and transactional write-back to this slice.
280    ///
281    /// # Errors
282    ///
283    /// Returns an error when the call has not begun, candidate arrays are empty
284    /// or mismatched, token identifiers repeat, a sparse view exceeds its
285    /// limit, lifecycle order is violated, or a callback fails.
286    pub fn apply_to_candidates(
287        &mut self,
288        step: u32,
289        causal_tokens: &[TokenId],
290        candidate_tokens: &[TokenId],
291        logits: &mut [f32],
292    ) -> Result<(), PipelineError> {
293        self.require_ready()?;
294        self.validate_candidate_view(candidate_tokens, logits)?;
295        let mut working_logits = logits.to_vec();
296        self.apply_working_candidates(step, causal_tokens, candidate_tokens, &mut working_logits)?;
297        logits.copy_from_slice(&working_logits);
298        Ok(())
299    }
300
301    fn apply_working_candidates(
302        &mut self,
303        step: u32,
304        causal_tokens: &[TokenId],
305        candidate_tokens: &[TokenId],
306        candidate_logits: &mut [f32],
307    ) -> Result<(), PipelineError> {
308        self.require_ready()?;
309        if self
310            .receipt
311            .stages
312            .iter()
313            .any(|stage| stage.accepted_tokens < self.receipt.invocations)
314        {
315            return Err(PipelineError::AdmissionPending);
316        }
317        if step != self.receipt.invocations {
318            return Err(PipelineError::InvalidStep {
319                expected: self.receipt.invocations,
320                actual: step,
321            });
322        }
323        let candidate_count = u64::try_from(candidate_logits.len())
324            .map_err(|_| PipelineError::AccountingOverflow("candidate count"))?;
325        self.receipt.candidates_copied = self
326            .receipt
327            .candidates_copied
328            .checked_add(candidate_count)
329            .ok_or(PipelineError::AccountingOverflow("candidates copied"))?;
330
331        for index in 0..self.stages.len() {
332            if step >= self.stages[index].specification.max_steps
333                || self.receipt.stages[index].invocations
334                    >= self.stages[index].specification.max_steps
335            {
336                let failure = CallbackFailure::new(
337                    CallbackPhase::Apply,
338                    false,
339                    format!(
340                        "step {step} exceeds stage bound {}",
341                        self.stages[index].specification.max_steps
342                    ),
343                );
344                return Err(self.record_failure(index, failure));
345            }
346            let before = candidate_logits
347                .iter()
348                .map(|value| value.to_bits())
349                .collect::<Vec<_>>();
350            let context =
351                TransformContext::new(step, causal_tokens, candidate_tokens, candidate_logits)?;
352            self.receipt.stages[index].invocations = self.receipt.stages[index]
353                .invocations
354                .checked_add(1)
355                .ok_or(PipelineError::AccountingOverflow("stage invocations"))?;
356            self.receipt.stages[index].candidates_seen = self.receipt.stages[index]
357                .candidates_seen
358                .checked_add(candidate_count)
359                .ok_or(PipelineError::AccountingOverflow("stage candidates seen"))?;
360            let result = catch_unwind(AssertUnwindSafe(|| {
361                self.stages[index].implementation.apply(context)
362            }));
363            if let Some(failure) = callback_result(CallbackPhase::Apply, result) {
364                return Err(self.record_failure(index, failure));
365            }
366            if candidate_logits.iter().any(|value| value.is_nan()) {
367                let failure = CallbackFailure::new(
368                    CallbackPhase::Apply,
369                    false,
370                    "transform produced a NaN logit",
371                );
372                return Err(self.record_failure(index, failure));
373            }
374            let changed = before
375                .iter()
376                .zip(candidate_logits.iter())
377                .filter(|(before, after)| **before != after.to_bits())
378                .count();
379            let changed = u64::try_from(changed)
380                .map_err(|_| PipelineError::AccountingOverflow("changed logits"))?;
381            self.receipt.stages[index].logits_changed = self.receipt.stages[index]
382                .logits_changed
383                .checked_add(changed)
384                .ok_or(PipelineError::AccountingOverflow("stage logits changed"))?;
385        }
386
387        self.receipt.invocations = self
388            .receipt
389            .invocations
390            .checked_add(1)
391            .ok_or(PipelineError::AccountingOverflow("pipeline invocations"))?;
392        self.receipt.candidates_committed = self
393            .receipt
394            .candidates_committed
395            .checked_add(candidate_count)
396            .ok_or(PipelineError::AccountingOverflow("candidates committed"))?;
397        Ok(())
398    }
399
400    fn validate_candidate_view(
401        &self,
402        candidate_tokens: &[TokenId],
403        logits: &[f32],
404    ) -> Result<(), PipelineError> {
405        if candidate_tokens.is_empty() || candidate_tokens.len() != logits.len() {
406            return Err(PipelineError::InvalidCandidates(
407                "token and logit arrays must be non-empty and equal in length".to_owned(),
408            ));
409        }
410        let maximum_candidates = usize::try_from(i32::MAX).unwrap_or(usize::MAX);
411        if candidate_tokens.len() > maximum_candidates {
412            return Err(PipelineError::InvalidCandidates(
413                "candidate count exceeds non-negative i32 token space".to_owned(),
414            ));
415        }
416        let unique_tokens = candidate_tokens.iter().copied().collect::<HashSet<_>>();
417        if unique_tokens.len() != candidate_tokens.len() {
418            return Err(PipelineError::InvalidCandidates(
419                "candidate token identifiers must be unique".to_owned(),
420            ));
421        }
422        if let CandidateMode::Sparse { limit } = self.specification.mode()?
423            && candidate_tokens.len() > usize::try_from(limit).unwrap_or(usize::MAX)
424        {
425            return Err(PipelineError::InvalidCandidates(format!(
426                "candidate view exceeds sparse limit {limit}"
427            )));
428        }
429        Ok(())
430    }
431
432    /// Reports one token after causal admission.
433    ///
434    /// Each admission must correspond to an unmatched successful transform
435    /// invocation from the current call.
436    ///
437    /// # Errors
438    ///
439    /// Returns a contained callback failure or a lifecycle error.
440    pub fn accept(&mut self, token: TokenId) -> Result<(), PipelineError> {
441        self.require_ready()?;
442        if self
443            .receipt
444            .stages
445            .iter()
446            .any(|stage| stage.accepted_tokens >= self.receipt.invocations)
447        {
448            return Err(PipelineError::UnexpectedAdmission);
449        }
450        for index in 0..self.stages.len() {
451            self.receipt.stages[index].accepted_tokens = self.receipt.stages[index]
452                .accepted_tokens
453                .checked_add(1)
454                .ok_or(PipelineError::AccountingOverflow("accepted tokens"))?;
455            let result = catch_unwind(AssertUnwindSafe(|| {
456                self.stages[index].implementation.accept(token)
457            }));
458            if let Some(failure) = callback_result(CallbackPhase::Accept, result) {
459                return Err(self.record_failure(index, failure));
460            }
461        }
462        Ok(())
463    }
464
465    fn require_ready(&self) -> Result<(), PipelineError> {
466        if !self.begun {
467            return Err(PipelineError::NotBegun);
468        }
469        if self.failed {
470            return Err(PipelineError::Failed);
471        }
472        Ok(())
473    }
474
475    fn record_failure(&mut self, index: usize, failure: CallbackFailure) -> PipelineError {
476        self.failed = true;
477        self.receipt.failed_stage = Some(u32::try_from(index).unwrap_or(u32::MAX));
478        self.receipt.stages[index].failure = Some(failure.clone());
479        PipelineError::Callback {
480            stage: index,
481            failure,
482        }
483    }
484}
485
486fn empty_receipt(specification: &PipelineSpec) -> Result<PipelineReceipt, PipelineError> {
487    Ok(PipelineReceipt {
488        specification: specification.clone(),
489        pipeline: specification.digest()?,
490        begins: 0,
491        invocations: 0,
492        candidates_copied: 0,
493        candidates_committed: 0,
494        failed_stage: None,
495        stages: specification
496            .stages
497            .iter()
498            .cloned()
499            .map(|specification| StageReceipt {
500                specification,
501                resets: 0,
502                invocations: 0,
503                candidates_seen: 0,
504                logits_changed: 0,
505                accepted_tokens: 0,
506                failure: None,
507            })
508            .collect(),
509    })
510}
511
512fn selected_indices(mode: CandidateMode, logits: &[f32]) -> Vec<usize> {
513    match mode {
514        CandidateMode::FullVocabulary => (0..logits.len()).collect(),
515        CandidateMode::Sparse { limit } => {
516            let mut indices = logits
517                .iter()
518                .enumerate()
519                .filter(|(_, value)| value.is_finite())
520                .map(|(index, _)| index)
521                .collect::<Vec<_>>();
522            indices.sort_unstable_by(|left, right| {
523                logits[*right]
524                    .total_cmp(&logits[*left])
525                    .then_with(|| left.cmp(right))
526            });
527            indices.truncate(usize::try_from(limit).unwrap_or(usize::MAX));
528            indices
529        }
530    }
531}
532
533fn callback_result(
534    phase: CallbackPhase,
535    result: Result<Result<(), TransformError>, Box<dyn Any + Send>>,
536) -> Option<CallbackFailure> {
537    match result {
538        Ok(Ok(())) => None,
539        Ok(Err(error)) => Some(CallbackFailure::new(phase, false, error.to_string())),
540        Err(payload) => Some(CallbackFailure::new(phase, true, panic_message(&*payload))),
541    }
542}
543
544fn panic_message(payload: &(dyn Any + Send)) -> String {
545    payload.downcast_ref::<&str>().map_or_else(
546        || {
547            payload
548                .downcast_ref::<String>()
549                .cloned()
550                .unwrap_or_else(|| "non-string panic payload".to_owned())
551        },
552        |message| (*message).to_owned(),
553    )
554}
555
556#[cfg(test)]
557mod tests {
558    use logit_loom_core::Digest;
559
560    use super::*;
561
562    struct Add(f32);
563
564    impl LogitTransform for Add {
565        fn apply(&mut self, mut context: TransformContext<'_>) -> Result<(), TransformError> {
566            for value in context.logits_mut() {
567                *value += self.0;
568            }
569            Ok(())
570        }
571    }
572
573    struct Panic;
574
575    impl LogitTransform for Panic {
576        fn apply(&mut self, _context: TransformContext<'_>) -> Result<(), TransformError> {
577            panic!("contained")
578        }
579    }
580
581    struct MakeNan;
582
583    impl LogitTransform for MakeNan {
584        fn apply(&mut self, mut context: TransformContext<'_>) -> Result<(), TransformError> {
585            context.logits_mut()[0] = f32::NAN;
586            Ok(())
587        }
588    }
589
590    struct ResetPanics;
591
592    impl LogitTransform for ResetPanics {
593        fn reset(&mut self, _causal_tokens: &[TokenId]) -> Result<(), TransformError> {
594            panic!("reset panic is contained")
595        }
596
597        fn apply(&mut self, _context: TransformContext<'_>) -> Result<(), TransformError> {
598            Ok(())
599        }
600    }
601
602    struct AcceptFails;
603
604    impl LogitTransform for AcceptFails {
605        fn apply(&mut self, _context: TransformContext<'_>) -> Result<(), TransformError> {
606            Ok(())
607        }
608
609        fn accept(&mut self, _token: TokenId) -> Result<(), TransformError> {
610            Err(TransformError::new("accept failure"))
611        }
612    }
613
614    fn spec(name: &str, mode: CandidateMode) -> TransformSpec {
615        TransformSpec::new(Digest::of_bytes("test", name.as_bytes()), mode, 4).unwrap()
616    }
617
618    #[test]
619    fn ordered_pipeline_commits_only_after_every_stage() {
620        let mut pipeline = Pipeline::new(vec![
621            Stage::new(spec("one", CandidateMode::FullVocabulary), Add(1.0)).unwrap(),
622            Stage::new(spec("two", CandidateMode::FullVocabulary), Add(2.0)).unwrap(),
623        ])
624        .unwrap();
625        pipeline.begin(&[]).unwrap();
626        let mut logits = [0.0, 1.0];
627        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
628        assert_eq!(
629            logits.map(f32::to_bits),
630            [3.0_f32.to_bits(), 4.0_f32.to_bits()]
631        );
632        assert_eq!(pipeline.receipt().stages[0].logits_changed, 2);
633        assert_eq!(pipeline.receipt().stages[1].logits_changed, 2);
634    }
635
636    #[test]
637    fn callback_panic_does_not_commit_partial_logits() {
638        let mut pipeline = Pipeline::new(vec![
639            Stage::new(spec("one", CandidateMode::FullVocabulary), Add(1.0)).unwrap(),
640            Stage::new(spec("panic", CandidateMode::FullVocabulary), Panic).unwrap(),
641        ])
642        .unwrap();
643        pipeline.begin(&[]).unwrap();
644        let mut logits = [0.0, 1.0];
645        assert!(pipeline.apply_to_vocabulary(0, &[], &mut logits).is_err());
646        assert_eq!(
647            logits.map(f32::to_bits),
648            [0.0_f32.to_bits(), 1.0_f32.to_bits()]
649        );
650        assert!(pipeline.is_failed());
651        assert!(
652            pipeline.receipt().stages[1]
653                .failure
654                .as_ref()
655                .unwrap()
656                .panicked
657        );
658    }
659
660    #[test]
661    fn sparse_mode_exposes_ranked_candidates_and_writes_back_by_token() {
662        let mut pipeline = Pipeline::new(vec![
663            Stage::new(spec("sparse", CandidateMode::Sparse { limit: 2 }), Add(1.0)).unwrap(),
664        ])
665        .unwrap();
666        pipeline.begin(&[]).unwrap();
667        let mut logits = [0.0, 3.0, 2.0, 1.0];
668        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
669        assert_eq!(
670            logits.map(f32::to_bits),
671            [
672                0.0_f32.to_bits(),
673                4.0_f32.to_bits(),
674                3.0_f32.to_bits(),
675                1.0_f32.to_bits(),
676            ]
677        );
678    }
679
680    #[test]
681    fn sparse_ties_break_by_ascending_token_identifier() {
682        let mut pipeline = Pipeline::new(vec![
683            Stage::new(spec("ties", CandidateMode::Sparse { limit: 2 }), Add(1.0)).unwrap(),
684        ])
685        .unwrap();
686        pipeline.begin(&[]).unwrap();
687        let mut logits = [0.0, 2.0, 2.0, 2.0];
688        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
689        assert_eq!(
690            logits.map(f32::to_bits),
691            [
692                0.0_f32.to_bits(),
693                3.0_f32.to_bits(),
694                3.0_f32.to_bits(),
695                2.0_f32.to_bits(),
696            ]
697        );
698    }
699
700    #[test]
701    fn backend_selected_candidate_view_is_bounded_and_transactional() {
702        let mut pipeline = Pipeline::new(vec![
703            Stage::new(
704                spec("selected", CandidateMode::Sparse { limit: 2 }),
705                Add(1.0),
706            )
707            .unwrap(),
708        ])
709        .unwrap();
710        let causal = [TokenId::new(7).unwrap()];
711        let candidates = [TokenId::new(41).unwrap(), TokenId::new(3).unwrap()];
712        pipeline.begin(&causal).unwrap();
713        let mut logits = [2.0, 1.0];
714        pipeline
715            .apply_to_candidates(0, &causal, &candidates, &mut logits)
716            .unwrap();
717        assert_eq!(
718            logits.map(f32::to_bits),
719            [3.0_f32.to_bits(), 2.0_f32.to_bits()]
720        );
721        let receipt = pipeline.receipt();
722        assert_eq!(receipt.candidates_copied, 2);
723        assert_eq!(receipt.candidates_committed, 2);
724
725        let mut oversized = [0.0, 1.0, 2.0];
726        let oversized_tokens = [
727            TokenId::new(1).unwrap(),
728            TokenId::new(2).unwrap(),
729            TokenId::new(3).unwrap(),
730        ];
731        assert!(
732            pipeline
733                .apply_to_candidates(1, &causal, &oversized_tokens, &mut oversized)
734                .is_err()
735        );
736        assert_eq!(
737            oversized.map(f32::to_bits),
738            [0.0_f32.to_bits(), 1.0_f32.to_bits(), 2.0_f32.to_bits()]
739        );
740    }
741
742    #[test]
743    fn nan_output_fails_without_writeback() {
744        let mut pipeline = Pipeline::new(vec![
745            Stage::new(spec("nan", CandidateMode::FullVocabulary), MakeNan).unwrap(),
746        ])
747        .unwrap();
748        pipeline.begin(&[]).unwrap();
749        let mut logits = [1.0, 2.0];
750        assert!(pipeline.apply_to_vocabulary(0, &[], &mut logits).is_err());
751        assert_eq!(
752            logits.map(f32::to_bits),
753            [1.0_f32.to_bits(), 2.0_f32.to_bits()]
754        );
755        assert!(pipeline.is_failed());
756    }
757
758    #[test]
759    fn sampling_steps_are_zero_based_and_sequential() {
760        let mut pipeline = Pipeline::new(vec![
761            Stage::new(spec("sequence", CandidateMode::FullVocabulary), Add(1.0)).unwrap(),
762        ])
763        .unwrap();
764        pipeline.begin(&[]).unwrap();
765        let mut logits = [0.0];
766        assert!(matches!(
767            pipeline.apply_to_vocabulary(1, &[], &mut logits),
768            Err(PipelineError::InvalidStep {
769                expected: 0,
770                actual: 1
771            })
772        ));
773        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
774        pipeline.accept(TokenId::new(1).unwrap()).unwrap();
775        assert!(matches!(
776            pipeline.apply_to_vocabulary(0, &[], &mut logits),
777            Err(PipelineError::InvalidStep {
778                expected: 1,
779                actual: 0
780            })
781        ));
782    }
783
784    #[test]
785    fn candidate_views_reject_duplicate_token_identifiers() {
786        let mut pipeline = Pipeline::new(vec![
787            Stage::new(spec("duplicates", CandidateMode::FullVocabulary), Add(1.0)).unwrap(),
788        ])
789        .unwrap();
790        pipeline.begin(&[]).unwrap();
791        let token = TokenId::new(3).unwrap();
792        let mut logits = [1.0, 2.0];
793        assert!(
794            pipeline
795                .apply_to_candidates(0, &[], &[token, token], &mut logits)
796                .is_err()
797        );
798        assert_eq!(
799            logits.map(f32::to_bits),
800            [1.0_f32.to_bits(), 2.0_f32.to_bits()]
801        );
802    }
803
804    #[test]
805    fn invocation_bound_cannot_be_bypassed_with_repeated_steps() {
806        let specification = TransformSpec::new(
807            Digest::of_bytes("test", b"one-step"),
808            CandidateMode::FullVocabulary,
809            1,
810        )
811        .unwrap();
812        let mut pipeline =
813            Pipeline::new(vec![Stage::new(specification, Add(1.0)).unwrap()]).unwrap();
814        pipeline.begin(&[]).unwrap();
815        let mut logits = [0.0];
816        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
817        assert!(pipeline.apply_to_vocabulary(0, &[], &mut logits).is_err());
818        assert_eq!(pipeline.receipt().invocations, 1);
819    }
820
821    #[test]
822    fn admission_requires_an_unmatched_successful_step() {
823        let mut pipeline = Pipeline::new(vec![
824            Stage::new(spec("admission", CandidateMode::FullVocabulary), Add(1.0)).unwrap(),
825        ])
826        .unwrap();
827        pipeline.begin(&[]).unwrap();
828        let token = TokenId::new(1).unwrap();
829        assert!(matches!(
830            pipeline.accept(token),
831            Err(PipelineError::UnexpectedAdmission)
832        ));
833
834        let mut logits = [0.0];
835        pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
836        assert!(matches!(
837            pipeline.apply_to_vocabulary(1, &[], &mut logits),
838            Err(PipelineError::AdmissionPending)
839        ));
840        pipeline.accept(token).unwrap();
841        assert!(matches!(
842            pipeline.accept(token),
843            Err(PipelineError::UnexpectedAdmission)
844        ));
845    }
846
847    #[test]
848    fn reset_and_admission_failures_are_contained_and_accounted() {
849        let mut reset = Pipeline::new(vec![
850            Stage::new(
851                spec("reset-panic", CandidateMode::FullVocabulary),
852                ResetPanics,
853            )
854            .unwrap(),
855        ])
856        .unwrap();
857        assert!(reset.begin(&[]).is_err());
858        let failure = reset.receipt().stages[0].failure.clone().unwrap();
859        assert!(failure.panicked);
860        assert_eq!(failure.phase, CallbackPhase::Reset);
861
862        let mut accept = Pipeline::new(vec![
863            Stage::new(
864                spec("accept-error", CandidateMode::FullVocabulary),
865                AcceptFails,
866            )
867            .unwrap(),
868        ])
869        .unwrap();
870        accept.begin(&[]).unwrap();
871        let mut logits = [0.0];
872        accept.apply_to_vocabulary(0, &[], &mut logits).unwrap();
873        assert!(accept.accept(TokenId::new(0).unwrap()).is_err());
874        let failure = accept.receipt().stages[0].failure.clone().unwrap();
875        assert!(!failure.panicked);
876        assert_eq!(failure.phase, CallbackPhase::Accept);
877    }
878}