1use 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
17pub const MAX_OBSERVERS: usize = 16;
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub struct ObservedToken<'a> {
23 pub token: TokenId,
25 pub piece: &'a [u8],
27 pub position: u64,
29}
30
31pub trait Observer {
33 fn reset(&mut self, _initial_position: u64) -> Result<(), ObserverError> {
39 Ok(())
40 }
41
42 fn poll(&mut self) -> Result<ControlFlow, ObserverError> {
48 Ok(ControlFlow::Continue)
49 }
50
51 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
65pub struct ObserverSet {
67 entries: Vec<ObserverEntry>,
68 begun: bool,
69 failed: bool,
70}
71
72impl ObserverSet {
73 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 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 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 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 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 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 pub fn receipts(&self) -> Vec<ObserverReceipt> {
304 self.entries
305 .iter()
306 .map(|entry| entry.receipt.clone())
307 .collect()
308 }
309
310 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
337pub trait PrefillObserver {
339 fn reset(&mut self, _progress: PrefillProgress) -> Result<(), PrefillObserverError> {
345 Ok(())
346 }
347
348 fn poll(&mut self, _progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError> {
354 Ok(ControlFlow::Continue)
355 }
356
357 fn on_chunk(&mut self, progress: PrefillProgress) -> Result<ControlFlow, PrefillObserverError>;
363}
364
365pub 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 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 pub const fn receipt(&self) -> Option<&PrefillReceipt> {
390 self.receipt.as_ref()
391 }
392
393 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 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 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 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#[derive(Clone, Debug, Default)]
598pub struct CancellationToken {
599 stopped: Arc<AtomicBool>,
600}
601
602impl CancellationToken {
603 pub fn new() -> Self {
605 Self::default()
606 }
607
608 pub fn cancel(&self) -> bool {
610 !self.stopped.swap(true, Ordering::AcqRel)
611 }
612
613 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}