Skip to main content

logit_loom/
observer.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Generated-token and prefill observation with cooperative cancellation.
4
5use std::any::Any;
6use std::panic::{AssertUnwindSafe, catch_unwind};
7use std::sync::Arc;
8use std::sync::atomic::{AtomicBool, Ordering};
9
10use logit_loom_core::{
11    CallbackFailure, CallbackPhase, ControlFlow, Digest, ObserverReceipt, PrefillFinish,
12    PrefillProgress, PrefillReceipt, TokenId,
13};
14
15use crate::{ObserverError, PrefillObserverError};
16
17/// Maximum observers sharing one ordered fan-out.
18pub const MAX_OBSERVERS: usize = 16;
19
20/// One token already admitted to backend causal state.
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub struct ObservedToken<'a> {
23    /// Tokenizer identifier.
24    pub token: TokenId,
25    /// Exact, potentially non-UTF-8 token-piece bytes.
26    pub piece: &'a [u8],
27    /// Causal position after token admission.
28    pub position: u64,
29}
30
31/// Safe synchronous observer for generated-token boundaries.
32pub trait Observer {
33    /// Resets local state for a new call.
34    ///
35    /// # Errors
36    ///
37    /// Returns an implementation-defined reset failure.
38    fn reset(&mut self, _initial_position: u64) -> Result<(), ObserverError> {
39        Ok(())
40    }
41
42    /// Polls immediately before one sampling decision.
43    ///
44    /// # Errors
45    ///
46    /// Returns an implementation-defined polling failure.
47    fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
48        Ok(ControlFlow::Continue)
49    }
50
51    /// Observes one token after causal admission.
52    ///
53    /// # Errors
54    ///
55    /// Returns an implementation-defined observation failure.
56    fn on_token(&mut self, token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError>;
57}
58
59struct ObserverEntry {
60    implementation: Digest,
61    observer: Box<dyn Observer>,
62    receipt: ObserverReceipt,
63}
64
65/// Ordered observer fan-out behind one backend callback point.
66pub struct ObserverSet {
67    entries: Vec<ObserverEntry>,
68    begun: bool,
69    failed: bool,
70}
71
72impl ObserverSet {
73    /// Creates a non-empty bounded observer set.
74    ///
75    /// # Errors
76    ///
77    /// Returns an error unless one to 16 observers are supplied and identities
78    /// are unique.
79    pub fn new(
80        observers: impl IntoIterator<Item = (Digest, Box<dyn Observer>)>,
81    ) -> Result<Self, ObserverError> {
82        let entries = observers
83            .into_iter()
84            .take(MAX_OBSERVERS + 1)
85            .map(|(implementation, observer)| ObserverEntry {
86                receipt: empty_observer_receipt(implementation.clone()),
87                implementation,
88                observer,
89            })
90            .collect::<Vec<_>>();
91        if !(1..=MAX_OBSERVERS).contains(&entries.len()) {
92            return Err(ObserverError::new(format!(
93                "observer set requires 1..={MAX_OBSERVERS} entries"
94            )));
95        }
96        let mut identities = entries
97            .iter()
98            .map(|entry| entry.implementation.clone())
99            .collect::<Vec<_>>();
100        identities.sort();
101        identities.dedup();
102        if identities.len() != entries.len() {
103            return Err(ObserverError::new(
104                "observer implementation identities must be unique",
105            ));
106        }
107        Ok(Self {
108            entries,
109            begun: false,
110            failed: false,
111        })
112    }
113
114    /// Convenience constructor for one observer.
115    pub fn single(implementation: Digest, observer: impl Observer + 'static) -> Self {
116        Self {
117            entries: vec![ObserverEntry {
118                receipt: empty_observer_receipt(implementation.clone()),
119                implementation,
120                observer: Box::new(observer),
121            }],
122            begun: false,
123            failed: false,
124        }
125    }
126
127    /// Returns the identity of the exact ordered observer implementations.
128    ///
129    /// # Errors
130    ///
131    /// Returns an error when identity serialization fails.
132    pub fn identity(&self) -> Result<Digest, ObserverError> {
133        let implementations = self
134            .entries
135            .iter()
136            .map(|entry| &entry.implementation)
137            .collect::<Vec<_>>();
138        Digest::of_serializable("observer-set-v1", &implementations)
139            .map_err(|error| ObserverError::new(error.to_string()))
140    }
141
142    /// Resets every observer for a new generation call.
143    ///
144    /// # Errors
145    ///
146    /// Returns a bounded error or panic from one observer.
147    pub fn begin(
148        &mut self,
149        initial_position: u64,
150        requested_tokens: u32,
151    ) -> Result<(), ObserverError> {
152        if requested_tokens == 0 {
153            return Err(ObserverError::new(
154                "requested token bound must be greater than zero",
155            ));
156        }
157        if initial_position
158            .checked_add(u64::from(requested_tokens))
159            .is_none()
160        {
161            return Err(ObserverError::new(
162                "requested token range overflows causal position",
163            ));
164        }
165        self.begun = true;
166        self.failed = false;
167        for entry in &mut self.entries {
168            entry.receipt = ObserverReceipt {
169                implementation: entry.implementation.clone(),
170                initial_position,
171                requested_tokens,
172                polls: 0,
173                observed_tokens: 0,
174                observed_bytes: 0,
175                final_position: initial_position,
176                stop_requested: false,
177                failure: None,
178            };
179            let result = catch_unwind(AssertUnwindSafe(|| entry.observer.reset(initial_position)));
180            if let Some(failure) = observer_result(CallbackPhase::Reset, result) {
181                entry.receipt.failure = Some(failure.clone());
182                self.failed = true;
183                return Err(ObserverError::new(failure.message));
184            }
185        }
186        Ok(())
187    }
188
189    /// Polls every observer in order before one sampling decision.
190    ///
191    /// All observers run even after an earlier observer requests a stop. This
192    /// gives every sink the same pre-sampling boundary. Poll count cannot
193    /// exceed the token bound supplied to [`Self::begin`].
194    ///
195    /// # Errors
196    ///
197    /// Returns a lifecycle or contained callback failure.
198    pub fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
199        self.require_ready()?;
200        if self
201            .entries
202            .iter()
203            .any(|entry| entry.receipt.polls >= entry.receipt.requested_tokens)
204        {
205            self.failed = true;
206            return Err(ObserverError::new(
207                "observer polls exceed the requested token bound",
208            ));
209        }
210        let mut control = ControlFlow::Continue;
211        for entry in &mut self.entries {
212            entry.receipt.polls += 1;
213            let result = catch_unwind(AssertUnwindSafe(|| entry.observer.poll()));
214            match observer_control_result(CallbackPhase::Poll, result) {
215                Ok(ControlFlow::Continue) => {}
216                Ok(ControlFlow::Stop) => {
217                    entry.receipt.stop_requested = true;
218                    control = ControlFlow::Stop;
219                }
220                Err(failure) => {
221                    entry.receipt.failure = Some(failure.clone());
222                    self.failed = true;
223                    return Err(ObserverError::new(failure.message));
224                }
225            }
226        }
227        Ok(control)
228    }
229
230    /// Delivers one causally admitted token to every observer in order.
231    ///
232    /// A successful poll must precede delivery, and delivery cannot exceed the
233    /// token bound supplied to [`Self::begin`].
234    ///
235    /// # Errors
236    ///
237    /// Returns a lifecycle or contained callback failure.
238    pub fn observe(&mut self, token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
239        self.require_ready()?;
240        let Some(first) = self.entries.first() else {
241            self.failed = true;
242            return Err(ObserverError::new("observer set is empty"));
243        };
244        if first.receipt.polls <= first.receipt.observed_tokens {
245            self.failed = true;
246            return Err(ObserverError::new(
247                "poll every observer before delivering the next token",
248            ));
249        }
250        if first.receipt.observed_tokens >= first.receipt.requested_tokens {
251            self.failed = true;
252            return Err(ObserverError::new(
253                "observed token count exceeds the requested bound",
254            ));
255        }
256        let next_observed_tokens = first
257            .receipt
258            .observed_tokens
259            .checked_add(1)
260            .ok_or_else(|| ObserverError::new("observed token count overflowed"))?;
261        let expected_position = first
262            .receipt
263            .initial_position
264            .checked_add(u64::from(next_observed_tokens))
265            .ok_or_else(|| ObserverError::new("observed causal position overflowed"))?;
266        if token.position != expected_position {
267            self.failed = true;
268            return Err(ObserverError::new(format!(
269                "observed position {} does not equal expected {expected_position}",
270                token.position
271            )));
272        }
273        let piece_bytes = u64::try_from(token.piece.len())
274            .map_err(|_| ObserverError::new("observed byte count overflowed"))?;
275        let next_observed_bytes = first
276            .receipt
277            .observed_bytes
278            .checked_add(piece_bytes)
279            .ok_or_else(|| ObserverError::new("observed byte count overflowed"))?;
280        let mut control = ControlFlow::Continue;
281        for entry in &mut self.entries {
282            entry.receipt.observed_tokens = next_observed_tokens;
283            entry.receipt.observed_bytes = next_observed_bytes;
284            entry.receipt.final_position = token.position;
285            let result = catch_unwind(AssertUnwindSafe(|| entry.observer.on_token(token)));
286            match observer_control_result(CallbackPhase::Observe, result) {
287                Ok(ControlFlow::Continue) => {}
288                Ok(ControlFlow::Stop) => {
289                    entry.receipt.stop_requested = true;
290                    control = ControlFlow::Stop;
291                }
292                Err(failure) => {
293                    entry.receipt.failure = Some(failure.clone());
294                    self.failed = true;
295                    return Err(ObserverError::new(failure.message));
296                }
297            }
298        }
299        Ok(control)
300    }
301
302    /// Returns current per-observer accounting in dispatch order.
303    pub fn receipts(&self) -> Vec<ObserverReceipt> {
304        self.entries
305            .iter()
306            .map(|entry| entry.receipt.clone())
307            .collect()
308    }
309
310    /// Returns one observer receipt by dispatch index.
311    pub fn receipt(&self, index: usize) -> Option<&ObserverReceipt> {
312        self.entries.get(index).map(|entry| &entry.receipt)
313    }
314
315    fn require_ready(&self) -> Result<(), ObserverError> {
316        if !self.begun {
317            return Err(ObserverError::new("observer set has not begun"));
318        }
319        if self.failed {
320            return Err(ObserverError::new(
321                "observer set is failed; call begin before reuse",
322            ));
323        }
324        if self
325            .entries
326            .iter()
327            .any(|entry| entry.receipt.stop_requested)
328        {
329            return Err(ObserverError::new(
330                "observer set requested a stop; call begin before reuse",
331            ));
332        }
333        Ok(())
334    }
335}
336
337/// Safe synchronous observer for complete prefill chunks.
338pub trait PrefillObserver {
339    /// Resets implementation-local state for a new prefill call.
340    ///
341    /// # Errors
342    ///
343    /// Returns an implementation-defined reset failure.
344    fn reset(&mut self, _progress: PrefillProgress) -> Result<(), PrefillObserverError> {
345        Ok(())
346    }
347
348    /// Polls before one native chunk is submitted.
349    ///
350    /// # Errors
351    ///
352    /// Returns an implementation-defined polling failure.
353    fn poll(&mut self, _progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError> {
354        Ok(ControlFlow::Continue)
355    }
356
357    /// Observes one complete chunk after causal admission.
358    ///
359    /// # Errors
360    ///
361    /// Returns an implementation-defined observation failure.
362    fn on_chunk(&mut self, progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError>;
363}
364
365/// Panic-containing wrapper around one controlled-prefill observer.
366pub struct PrefillMonitor {
367    implementation: Digest,
368    observer: Box<dyn PrefillObserver>,
369    receipt: Option<PrefillReceipt>,
370    failed: bool,
371    stop_requested: bool,
372    finished: bool,
373}
374
375impl PrefillMonitor {
376    /// Creates one identified prefill observer.
377    pub fn new(implementation: Digest, observer: impl PrefillObserver + 'static) -> Self {
378        Self {
379            implementation,
380            observer: Box::new(observer),
381            receipt: None,
382            failed: false,
383            stop_requested: false,
384            finished: false,
385        }
386    }
387
388    /// Returns current accounting, including a contained failure when present.
389    pub const fn receipt(&self) -> Option<&PrefillReceipt> {
390        self.receipt.as_ref()
391    }
392
393    /// Begins a prefill operation at zero admitted tokens.
394    ///
395    /// # Errors
396    ///
397    /// Returns a validation or contained reset failure.
398    pub fn begin(&mut self, progress: PrefillProgress) -> Result<(), PrefillObserverError> {
399        progress
400            .validate()
401            .map_err(|error| PrefillObserverError::new(error.to_string()))?;
402        if progress.requested_tokens == 0
403            || progress.admitted_tokens != 0
404            || progress.admitted_chunks != 0
405        {
406            return Err(PrefillObserverError::new(
407                "initial prefill progress requires requested tokens and no admitted work",
408            ));
409        }
410        self.failed = false;
411        self.stop_requested = false;
412        self.finished = false;
413        self.receipt = Some(PrefillReceipt {
414            implementation: self.implementation.clone(),
415            progress,
416            finish: PrefillFinish::InProgress,
417            polls: 0,
418            chunks: 0,
419            failure: None,
420        });
421        let result = catch_unwind(AssertUnwindSafe(|| self.observer.reset(progress)));
422        if let Some(failure) = prefill_result(CallbackPhase::Reset, result) {
423            self.fail(failure.clone());
424            return Err(PrefillObserverError::new(failure.message));
425        }
426        Ok(())
427    }
428
429    /// Polls before a chunk.
430    ///
431    /// # Errors
432    ///
433    /// Returns a lifecycle or contained callback failure.
434    pub fn poll(&mut self, progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError> {
435        self.require_continuable()?;
436        progress
437            .validate()
438            .map_err(|error| PrefillObserverError::new(error.to_string()))?;
439        let Some(receipt) = &self.receipt else {
440            return Err(PrefillObserverError::new("prefill monitor has not begun"));
441        };
442        if progress != receipt.progress {
443            return Err(PrefillObserverError::new(
444                "polled prefill progress does not match admitted work",
445            ));
446        }
447        if receipt.polls != receipt.chunks {
448            return Err(PrefillObserverError::new(
449                "each prefill chunk requires exactly one preceding poll",
450            ));
451        }
452        let next_poll = receipt
453            .polls
454            .checked_add(1)
455            .ok_or_else(|| PrefillObserverError::new("prefill poll count overflowed"))?;
456        if let Some(receipt) = &mut self.receipt {
457            receipt.polls = next_poll;
458        }
459        let result = catch_unwind(AssertUnwindSafe(|| self.observer.poll(progress)));
460        match prefill_control_result(CallbackPhase::Poll, result) {
461            Ok(control) => {
462                if control == ControlFlow::Stop {
463                    self.stop_requested = true;
464                }
465                Ok(control)
466            }
467            Err(failure) => {
468                self.fail(failure.clone());
469                Err(PrefillObserverError::new(failure.message))
470            }
471        }
472    }
473
474    /// Observes a complete admitted chunk.
475    ///
476    /// # Errors
477    ///
478    /// Returns a lifecycle or contained callback failure.
479    pub fn observe_chunk(
480        &mut self,
481        progress: PrefillProgress,
482    ) -> Result<ControlFlow, PrefillObserverError> {
483        self.require_continuable()?;
484        progress
485            .validate()
486            .map_err(|error| PrefillObserverError::new(error.to_string()))?;
487        let Some(receipt) = &mut self.receipt else {
488            return Err(PrefillObserverError::new("prefill monitor has not begun"));
489        };
490        let previous = receipt.progress;
491        let expected_chunks = previous
492            .admitted_chunks
493            .checked_add(1)
494            .ok_or_else(|| PrefillObserverError::new("prefill chunk count overflowed"))?;
495        let expected_polls = receipt
496            .chunks
497            .checked_add(1)
498            .ok_or_else(|| PrefillObserverError::new("prefill poll count overflowed"))?;
499        if progress.initial_position != previous.initial_position
500            || progress.requested_tokens != previous.requested_tokens
501            || progress.admitted_tokens <= previous.admitted_tokens
502            || progress.admitted_chunks != expected_chunks
503            || receipt.polls != expected_polls
504        {
505            return Err(PrefillObserverError::new(
506                "admitted prefill chunks must follow polled progress monotonically",
507            ));
508        }
509        receipt.progress = progress;
510        receipt.chunks = expected_chunks;
511        let result = catch_unwind(AssertUnwindSafe(|| self.observer.on_chunk(progress)));
512        match prefill_control_result(CallbackPhase::Prefill, result) {
513            Ok(control) => {
514                if control == ControlFlow::Stop {
515                    self.stop_requested = true;
516                }
517                Ok(control)
518            }
519            Err(failure) => {
520                self.fail(failure.clone());
521                Err(PrefillObserverError::new(failure.message))
522            }
523        }
524    }
525
526    /// Marks successful complete or stopped prefill and returns its receipt.
527    ///
528    /// `Stopped` requires a stop returned by the wrapped observer. A successful
529    /// finish is terminal until [`Self::begin`] starts another call.
530    ///
531    /// # Errors
532    ///
533    /// Returns an error when the monitor failed or has not begun.
534    pub fn finish(
535        &mut self,
536        finish: PrefillFinish,
537    ) -> Result<PrefillReceipt, PrefillObserverError> {
538        self.require_ready()?;
539        if finish == PrefillFinish::InProgress {
540            return Err(PrefillObserverError::new(
541                "in-progress prefill is not a terminal finish",
542            ));
543        }
544        if finish == PrefillFinish::Stopped && !self.stop_requested {
545            return Err(PrefillObserverError::new(
546                "stopped prefill requires an observer stop request",
547            ));
548        }
549        let Some(mut receipt) = self.receipt.clone() else {
550            return Err(PrefillObserverError::new("prefill monitor has not begun"));
551        };
552        receipt.finish = finish;
553        receipt
554            .digest()
555            .map_err(|error| PrefillObserverError::new(error.to_string()))?;
556        self.receipt = Some(receipt.clone());
557        self.finished = true;
558        Ok(receipt)
559    }
560
561    fn require_ready(&self) -> Result<(), PrefillObserverError> {
562        if self.receipt.is_none() {
563            return Err(PrefillObserverError::new("prefill monitor has not begun"));
564        }
565        if self.failed {
566            return Err(PrefillObserverError::new(
567                "prefill monitor is failed; call begin before reuse",
568            ));
569        }
570        if self.finished {
571            return Err(PrefillObserverError::new(
572                "prefill monitor has finished; call begin before reuse",
573            ));
574        }
575        Ok(())
576    }
577
578    fn require_continuable(&self) -> Result<(), PrefillObserverError> {
579        self.require_ready()?;
580        if self.stop_requested {
581            return Err(PrefillObserverError::new(
582                "prefill observer requested a stop; finish before reuse",
583            ));
584        }
585        Ok(())
586    }
587
588    fn fail(&mut self, failure: CallbackFailure) {
589        self.failed = true;
590        if let Some(receipt) = &mut self.receipt {
591            receipt.failure = Some(failure);
592        }
593    }
594}
595
596/// Cloneable one-shot cooperative cancellation signal.
597#[derive(Clone, Debug, Default)]
598pub struct CancellationToken {
599    stopped: Arc<AtomicBool>,
600}
601
602impl CancellationToken {
603    /// Creates a signal in the running state.
604    pub fn new() -> Self {
605        Self::default()
606    }
607
608    /// Requests cancellation and reports whether this call changed the state.
609    pub fn cancel(&self) -> bool {
610        !self.stopped.swap(true, Ordering::AcqRel)
611    }
612
613    /// Returns whether cancellation has been requested.
614    pub fn is_cancelled(&self) -> bool {
615        self.stopped.load(Ordering::Acquire)
616    }
617
618    fn control(&self) -> ControlFlow {
619        if self.is_cancelled() {
620            ControlFlow::Stop
621        } else {
622            ControlFlow::Continue
623        }
624    }
625}
626
627impl Observer for CancellationToken {
628    fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
629        Ok(self.control())
630    }
631
632    fn on_token(&mut self, _token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
633        Ok(self.control())
634    }
635}
636
637impl PrefillObserver for CancellationToken {
638    fn poll(&mut self, _progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError> {
639        Ok(self.control())
640    }
641
642    fn on_chunk(
643        &mut self,
644        _progress: PrefillProgress,
645    ) -> Result<ControlFlow, PrefillObserverError> {
646        Ok(self.control())
647    }
648}
649
650fn empty_observer_receipt(implementation: Digest) -> ObserverReceipt {
651    ObserverReceipt {
652        implementation,
653        initial_position: 0,
654        requested_tokens: 1,
655        polls: 0,
656        observed_tokens: 0,
657        observed_bytes: 0,
658        final_position: 0,
659        stop_requested: false,
660        failure: None,
661    }
662}
663
664fn observer_result(
665    phase: CallbackPhase,
666    result: Result<Result<(), ObserverError>, Box<dyn Any + Send>>,
667) -> Option<CallbackFailure> {
668    match result {
669        Ok(Ok(())) => None,
670        Ok(Err(error)) => Some(CallbackFailure::new(phase, false, error.to_string())),
671        Err(payload) => Some(CallbackFailure::new(phase, true, panic_message(&*payload))),
672    }
673}
674
675fn observer_control_result(
676    phase: CallbackPhase,
677    result: Result<Result<ControlFlow, ObserverError>, Box<dyn Any + Send>>,
678) -> Result<ControlFlow, CallbackFailure> {
679    match result {
680        Ok(Ok(control)) => Ok(control),
681        Ok(Err(error)) => Err(CallbackFailure::new(phase, false, error.to_string())),
682        Err(payload) => Err(CallbackFailure::new(phase, true, panic_message(&*payload))),
683    }
684}
685
686fn prefill_result(
687    phase: CallbackPhase,
688    result: Result<Result<(), PrefillObserverError>, Box<dyn Any + Send>>,
689) -> Option<CallbackFailure> {
690    match result {
691        Ok(Ok(())) => None,
692        Ok(Err(error)) => Some(CallbackFailure::new(phase, false, error.to_string())),
693        Err(payload) => Some(CallbackFailure::new(phase, true, panic_message(&*payload))),
694    }
695}
696
697fn prefill_control_result(
698    phase: CallbackPhase,
699    result: Result<Result<ControlFlow, PrefillObserverError>, Box<dyn Any + Send>>,
700) -> Result<ControlFlow, CallbackFailure> {
701    match result {
702        Ok(Ok(control)) => Ok(control),
703        Ok(Err(error)) => Err(CallbackFailure::new(phase, false, error.to_string())),
704        Err(payload) => Err(CallbackFailure::new(phase, true, panic_message(&*payload))),
705    }
706}
707
708fn panic_message(payload: &(dyn Any + Send)) -> String {
709    payload.downcast_ref::<&str>().map_or_else(
710        || {
711            payload
712                .downcast_ref::<String>()
713                .cloned()
714                .unwrap_or_else(|| "non-string panic payload".to_owned())
715        },
716        |message| (*message).to_owned(),
717    )
718}
719
720#[cfg(test)]
721mod tests {
722    use std::thread;
723
724    use super::*;
725
726    struct Recorder(Vec<Vec<u8>>);
727
728    impl Observer for Recorder {
729        fn on_token(&mut self, token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
730            self.0.push(token.piece.to_vec());
731            Ok(ControlFlow::Continue)
732        }
733    }
734
735    struct PollStopper;
736
737    impl Observer for PollStopper {
738        fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
739            Ok(ControlFlow::Stop)
740        }
741
742        fn on_token(&mut self, _token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
743            Ok(ControlFlow::Continue)
744        }
745    }
746
747    struct PollPanics;
748
749    impl Observer for PollPanics {
750        fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
751            panic!("observer panic is contained")
752        }
753
754        fn on_token(&mut self, _token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
755            Ok(ControlFlow::Continue)
756        }
757    }
758
759    struct TokenPanics;
760
761    impl Observer for TokenPanics {
762        fn on_token(&mut self, _token: ObservedToken<'_>) -> Result<ControlFlow, ObserverError> {
763            panic!("token observer panic is contained")
764        }
765    }
766
767    struct ChunkRecorder;
768
769    impl PrefillObserver for ChunkRecorder {
770        fn on_chunk(
771            &mut self,
772            _progress: PrefillProgress,
773        ) -> Result<ControlFlow, PrefillObserverError> {
774            Ok(ControlFlow::Continue)
775        }
776    }
777
778    struct PrefillStopper;
779
780    impl PrefillObserver for PrefillStopper {
781        fn poll(
782            &mut self,
783            _progress: PrefillProgress,
784        ) -> Result<ControlFlow, PrefillObserverError> {
785            Ok(ControlFlow::Stop)
786        }
787
788        fn on_chunk(
789            &mut self,
790            _progress: PrefillProgress,
791        ) -> Result<ControlFlow, PrefillObserverError> {
792            Ok(ControlFlow::Continue)
793        }
794    }
795
796    struct PrefillPanics;
797
798    impl PrefillObserver for PrefillPanics {
799        fn on_chunk(
800            &mut self,
801            _progress: PrefillProgress,
802        ) -> Result<ControlFlow, PrefillObserverError> {
803            panic!("prefill observer panic is contained")
804        }
805    }
806
807    #[test]
808    fn observer_accepts_non_utf8_piece_bytes() {
809        let id = Digest::of_bytes("test-observer", b"bytes");
810        let mut set = ObserverSet::single(id, Recorder(Vec::new()));
811        set.begin(7, 2).unwrap();
812        set.poll().unwrap();
813        let token = TokenId::new(4).unwrap();
814        assert_eq!(
815            set.observe(ObservedToken {
816                token,
817                piece: &[0xff, 0x00],
818                position: 8,
819            })
820            .unwrap(),
821            ControlFlow::Continue
822        );
823        assert_eq!(set.receipts()[0].observed_bytes, 2);
824    }
825
826    #[test]
827    fn cancellation_propagates_between_threads() {
828        let token = CancellationToken::new();
829        let remote = token.clone();
830        assert!(thread::spawn(move || remote.cancel()).join().unwrap());
831        assert!(token.is_cancelled());
832        assert!(!token.cancel());
833    }
834
835    #[test]
836    fn polling_fans_out_after_a_stop_request() {
837        let first = Digest::of_bytes("test-observer", b"stop");
838        let second = Digest::of_bytes("test-observer", b"continue");
839        let mut set = ObserverSet::new([
840            (first, Box::new(PollStopper) as Box<dyn Observer>),
841            (second, Box::new(Recorder(Vec::new())) as Box<dyn Observer>),
842        ])
843        .unwrap();
844        set.begin(0, 1).unwrap();
845        assert_eq!(set.poll().unwrap(), ControlFlow::Stop);
846        let receipts = set.receipts();
847        assert_eq!(receipts[0].polls, 1);
848        assert_eq!(receipts[1].polls, 1);
849        assert!(receipts[0].stop_requested);
850        assert!(!receipts[1].stop_requested);
851    }
852
853    #[test]
854    fn observer_panic_is_retained_and_fails_the_set() {
855        let id = Digest::of_bytes("test-observer", b"panic");
856        let mut set = ObserverSet::single(id, PollPanics);
857        set.begin(0, 1).unwrap();
858        assert!(set.poll().is_err());
859        let failure = set.receipts()[0].failure.clone().unwrap();
860        assert!(failure.panicked);
861        assert_eq!(failure.phase, CallbackPhase::Poll);
862        assert!(set.poll().is_err());
863    }
864
865    #[test]
866    fn admitted_token_panic_is_retained_after_accounting() {
867        let id = Digest::of_bytes("test-observer", b"token-panic");
868        let mut set = ObserverSet::single(id, TokenPanics);
869        set.begin(3, 1).unwrap();
870        set.poll().unwrap();
871        assert!(
872            set.observe(ObservedToken {
873                token: TokenId::new(1).unwrap(),
874                piece: b"x",
875                position: 4,
876            })
877            .is_err()
878        );
879        let receipt = set.receipt(0).unwrap();
880        assert_eq!(receipt.observed_tokens, 1);
881        assert_eq!(receipt.final_position, 4);
882        let failure = receipt.failure.as_ref().unwrap();
883        assert!(failure.panicked);
884        assert_eq!(failure.phase, CallbackPhase::Observe);
885    }
886
887    #[test]
888    fn prefill_cancellation_finishes_at_zero_admissions() {
889        let cancellation = CancellationToken::new();
890        cancellation.cancel();
891        let id = Digest::of_bytes("test-prefill-observer", b"cancel");
892        let mut monitor = PrefillMonitor::new(id, cancellation);
893        let progress = PrefillProgress {
894            initial_position: 0,
895            requested_tokens: 4,
896            admitted_tokens: 0,
897            admitted_chunks: 0,
898            position: 0,
899        };
900        monitor.begin(progress).unwrap();
901        assert_eq!(monitor.poll(progress).unwrap(), ControlFlow::Stop);
902        let receipt = monitor.finish(PrefillFinish::Stopped).unwrap();
903        assert_eq!(receipt.progress.admitted_tokens, 0);
904        assert!(receipt.digest().is_ok());
905    }
906
907    #[test]
908    fn observer_set_bounds_iterator_consumption() {
909        let observers = (0_u32..).map(|index| {
910            (
911                Digest::of_bytes("test-observer", &index.to_le_bytes()),
912                Box::new(Recorder(Vec::new())) as Box<dyn Observer>,
913            )
914        });
915        assert!(ObserverSet::new(observers).is_err());
916    }
917
918    #[test]
919    fn observer_set_identity_binds_dispatch_order() {
920        let first = Digest::of_bytes("test-observer", b"first");
921        let second = Digest::of_bytes("test-observer", b"second");
922        let forward = ObserverSet::new([
923            (
924                first.clone(),
925                Box::new(Recorder(Vec::new())) as Box<dyn Observer>,
926            ),
927            (
928                second.clone(),
929                Box::new(Recorder(Vec::new())) as Box<dyn Observer>,
930            ),
931        ])
932        .unwrap();
933        let reverse = ObserverSet::new([
934            (second, Box::new(Recorder(Vec::new())) as Box<dyn Observer>),
935            (first, Box::new(Recorder(Vec::new())) as Box<dyn Observer>),
936        ])
937        .unwrap();
938        assert_ne!(forward.identity().unwrap(), reverse.identity().unwrap());
939    }
940
941    #[test]
942    fn observer_requires_polling_and_enforces_token_budget() {
943        let id = Digest::of_bytes("test-observer", b"lifecycle");
944        let token = TokenId::new(4).unwrap();
945        let mut set = ObserverSet::single(id, Recorder(Vec::new()));
946        set.begin(0, 1).unwrap();
947        assert!(
948            set.observe(ObservedToken {
949                token,
950                piece: b"x",
951                position: 1,
952            })
953            .is_err()
954        );
955
956        set.begin(0, 1).unwrap();
957        set.poll().unwrap();
958        set.observe(ObservedToken {
959            token,
960            piece: b"x",
961            position: 1,
962        })
963        .unwrap();
964        assert!(set.poll().is_err());
965    }
966
967    #[test]
968    fn observer_begin_rejects_position_overflow() {
969        let id = Digest::of_bytes("test-observer", b"overflow");
970        let mut set = ObserverSet::single(id, Recorder(Vec::new()));
971        assert!(set.begin(u64::MAX, 1).is_err());
972    }
973
974    #[test]
975    fn prefill_monitor_rejects_unpolled_or_nonmonotonic_chunks() {
976        let id = Digest::of_bytes("test-prefill-observer", b"sequence");
977        let mut monitor = PrefillMonitor::new(id, ChunkRecorder);
978        let initial = PrefillProgress {
979            initial_position: 3,
980            requested_tokens: 4,
981            admitted_tokens: 0,
982            admitted_chunks: 0,
983            position: 3,
984        };
985        let first = PrefillProgress {
986            admitted_tokens: 2,
987            admitted_chunks: 1,
988            position: 5,
989            ..initial
990        };
991        monitor.begin(initial).unwrap();
992        assert!(monitor.observe_chunk(first).is_err());
993
994        monitor.poll(initial).unwrap();
995        monitor.observe_chunk(first).unwrap();
996        assert!(monitor.poll(initial).is_err());
997
998        let skipped = PrefillProgress {
999            admitted_tokens: 4,
1000            admitted_chunks: 3,
1001            position: 7,
1002            ..initial
1003        };
1004        monitor.poll(first).unwrap();
1005        assert!(monitor.observe_chunk(skipped).is_err());
1006    }
1007
1008    #[test]
1009    fn prefill_stop_is_explicit_and_terminal() {
1010        let initial = PrefillProgress {
1011            initial_position: 0,
1012            requested_tokens: 1,
1013            admitted_tokens: 0,
1014            admitted_chunks: 0,
1015            position: 0,
1016        };
1017        let id = Digest::of_bytes("test-prefill-observer", b"finish");
1018        let mut monitor = PrefillMonitor::new(id, ChunkRecorder);
1019        monitor.begin(initial).unwrap();
1020        assert_eq!(monitor.receipt().unwrap().finish, PrefillFinish::InProgress);
1021        assert!(monitor.finish(PrefillFinish::InProgress).is_err());
1022        assert!(monitor.finish(PrefillFinish::Stopped).is_err());
1023
1024        let id = Digest::of_bytes("test-prefill-observer", b"stop");
1025        let mut monitor = PrefillMonitor::new(id, PrefillStopper);
1026        monitor.begin(initial).unwrap();
1027        assert_eq!(monitor.poll(initial).unwrap(), ControlFlow::Stop);
1028        assert!(monitor.poll(initial).is_err());
1029        monitor.finish(PrefillFinish::Stopped).unwrap();
1030        assert!(monitor.finish(PrefillFinish::Stopped).is_err());
1031    }
1032
1033    #[test]
1034    fn prefill_panic_is_retained_after_chunk_accounting() {
1035        let initial = PrefillProgress {
1036            initial_position: 0,
1037            requested_tokens: 2,
1038            admitted_tokens: 0,
1039            admitted_chunks: 0,
1040            position: 0,
1041        };
1042        let admitted = PrefillProgress {
1043            admitted_tokens: 1,
1044            admitted_chunks: 1,
1045            position: 1,
1046            ..initial
1047        };
1048        let id = Digest::of_bytes("test-prefill-observer", b"panic");
1049        let mut monitor = PrefillMonitor::new(id, PrefillPanics);
1050        monitor.begin(initial).unwrap();
1051        monitor.poll(initial).unwrap();
1052        assert!(monitor.observe_chunk(admitted).is_err());
1053        let receipt = monitor.receipt().unwrap();
1054        assert_eq!(receipt.progress, admitted);
1055        let failure = receipt.failure.as_ref().unwrap();
1056        assert!(failure.panicked);
1057        assert_eq!(failure.phase, CallbackPhase::Prefill);
1058    }
1059}