Skip to main content

logit_loom_core/
observe.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Observer, cancellation, and prefill accounting contracts.
4
5use serde::{Deserialize, Serialize};
6
7use crate::{CallbackFailure, CoreError, Digest};
8
9/// Cooperative action returned at a documented safe execution boundary.
10#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "snake_case")]
12pub enum ControlFlow {
13    /// Continue the bounded operation.
14    #[default]
15    Continue,
16    /// Stop after retaining all causal work admitted before this boundary.
17    Stop,
18}
19
20/// Mechanical accounting for one generated-token observer.
21#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
22pub struct ObserverReceipt {
23    /// Caller-defined observer implementation identity.
24    pub implementation: Digest,
25    /// Native position before generation began.
26    pub initial_position: u64,
27    /// Maximum generated-token budget.
28    pub requested_tokens: u32,
29    /// Pre-sampling polls.
30    pub polls: u32,
31    /// Causally admitted tokens delivered to the observer.
32    pub observed_tokens: u32,
33    /// Exact bytes delivered across all token pieces.
34    pub observed_bytes: u64,
35    /// Final causal position observed by Rust.
36    pub final_position: u64,
37    /// Whether this observer requested a stop.
38    pub stop_requested: bool,
39    /// First contained callback failure, if any.
40    #[serde(default, skip_serializing_if = "Option::is_none")]
41    pub failure: Option<CallbackFailure>,
42}
43
44impl ObserverReceipt {
45    /// Returns a content identity for this accounting.
46    ///
47    /// # Errors
48    ///
49    /// Returns a validation or serialization error.
50    pub fn digest(&self) -> Result<Digest, CoreError> {
51        let expected_position = self
52            .initial_position
53            .checked_add(u64::from(self.observed_tokens))
54            .ok_or_else(|| CoreError::invalid("observer receipt", "causal position overflowed"))?;
55        if self.requested_tokens == 0
56            || self.observed_tokens > self.requested_tokens
57            || self.polls < self.observed_tokens
58            || self.polls > self.requested_tokens
59            || self.final_position != expected_position
60        {
61            return Err(CoreError::invalid(
62                "observer receipt",
63                "token and position accounting is inconsistent",
64            ));
65        }
66        Digest::of_serializable("token-observer-receipt-v1", self)
67    }
68}
69
70/// Progress at one complete text-prefill boundary.
71#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
72pub struct PrefillProgress {
73    /// Position before this prefill operation.
74    pub initial_position: u64,
75    /// Total tokens requested by the operation.
76    pub requested_tokens: u64,
77    /// Complete tokens admitted so far.
78    pub admitted_tokens: u64,
79    /// Complete chunks admitted so far.
80    pub admitted_chunks: u32,
81    /// Current causal position.
82    pub position: u64,
83}
84
85impl PrefillProgress {
86    /// Validates monotonic token and position accounting.
87    ///
88    /// # Errors
89    ///
90    /// Returns an error when progress exceeds the request or disagrees with
91    /// the initial position.
92    pub fn validate(self) -> Result<(), CoreError> {
93        let expected_position = self
94            .initial_position
95            .checked_add(self.admitted_tokens)
96            .ok_or_else(|| CoreError::invalid("prefill progress", "causal position overflowed"))?;
97        if self.requested_tokens == 0
98            || self.admitted_tokens > self.requested_tokens
99            || u64::from(self.admitted_chunks) > self.admitted_tokens
100            || self.position != expected_position
101        {
102            return Err(CoreError::invalid(
103                "prefill progress",
104                "token and position accounting is inconsistent",
105            ));
106        }
107        Ok(())
108    }
109}
110
111/// Current or terminal disposition of one controlled prefill operation.
112#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(rename_all = "snake_case")]
114pub enum PrefillFinish {
115    /// The monitor has begun and no terminal disposition is recorded yet.
116    InProgress,
117    /// Every requested token was admitted.
118    Complete,
119    /// An observer stopped at a complete chunk boundary.
120    Stopped,
121}
122
123/// Mechanical accounting for controlled prefill.
124#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
125pub struct PrefillReceipt {
126    /// Observer implementation identity.
127    pub implementation: Digest,
128    /// Current or final progress.
129    pub progress: PrefillProgress,
130    /// Current or terminal disposition.
131    pub finish: PrefillFinish,
132    /// Observer polls.
133    pub polls: u32,
134    /// Complete chunk callbacks.
135    pub chunks: u32,
136    /// First contained callback failure, if any.
137    #[serde(default, skip_serializing_if = "Option::is_none")]
138    pub failure: Option<CallbackFailure>,
139}
140
141impl PrefillReceipt {
142    /// Returns a content identity for exact prefill accounting.
143    ///
144    /// # Errors
145    ///
146    /// Returns a validation or serialization error.
147    pub fn digest(&self) -> Result<Digest, CoreError> {
148        self.progress.validate()?;
149        let maximum_polls = self
150            .chunks
151            .checked_add(1)
152            .ok_or_else(|| CoreError::invalid("prefill receipt", "poll count overflowed"))?;
153        if self.chunks != self.progress.admitted_chunks
154            || self.polls < self.chunks
155            || self.polls > maximum_polls
156            || (self.finish == PrefillFinish::Complete && self.polls != self.chunks)
157        {
158            return Err(CoreError::invalid(
159                "prefill receipt",
160                "callback and chunk accounting is inconsistent",
161            ));
162        }
163        match self.finish {
164            PrefillFinish::Complete
165                if self.progress.admitted_tokens != self.progress.requested_tokens =>
166            {
167                return Err(CoreError::invalid(
168                    "prefill receipt",
169                    "complete prefill did not admit every token",
170                ));
171            }
172            PrefillFinish::Stopped
173                if self.progress.admitted_tokens == self.progress.requested_tokens =>
174            {
175                return Err(CoreError::invalid(
176                    "prefill receipt",
177                    "stopped prefill admitted every requested token",
178                ));
179            }
180            PrefillFinish::InProgress | PrefillFinish::Complete | PrefillFinish::Stopped => {}
181        }
182        Digest::of_serializable("prefill-receipt-v2", self)
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    fn implementation() -> Digest {
191        Digest::of_bytes("test-observer", b"accounting")
192    }
193
194    #[test]
195    fn observer_receipts_reject_position_overflow() {
196        let receipt = ObserverReceipt {
197            implementation: implementation(),
198            initial_position: u64::MAX,
199            requested_tokens: 1,
200            polls: 1,
201            observed_tokens: 1,
202            observed_bytes: 1,
203            final_position: u64::MAX,
204            stop_requested: false,
205            failure: None,
206        };
207        assert!(receipt.digest().is_err());
208    }
209
210    #[test]
211    fn observer_receipts_reject_polls_beyond_the_token_budget() {
212        let receipt = ObserverReceipt {
213            implementation: implementation(),
214            initial_position: 0,
215            requested_tokens: 1,
216            polls: 2,
217            observed_tokens: 0,
218            observed_bytes: 0,
219            final_position: 0,
220            stop_requested: false,
221            failure: None,
222        };
223        assert!(receipt.digest().is_err());
224    }
225
226    #[test]
227    fn prefill_progress_rejects_position_overflow() {
228        let progress = PrefillProgress {
229            initial_position: u64::MAX,
230            requested_tokens: 1,
231            admitted_tokens: 1,
232            admitted_chunks: 1,
233            position: u64::MAX,
234        };
235        assert!(progress.validate().is_err());
236    }
237
238    #[test]
239    fn prefill_progress_rejects_more_chunks_than_tokens() {
240        let progress = PrefillProgress {
241            initial_position: 0,
242            requested_tokens: 1,
243            admitted_tokens: 1,
244            admitted_chunks: 2,
245            position: 1,
246        };
247        assert!(progress.validate().is_err());
248    }
249
250    #[test]
251    fn prefill_progress_requires_requested_tokens() {
252        let progress = PrefillProgress {
253            initial_position: 0,
254            requested_tokens: 0,
255            admitted_tokens: 0,
256            admitted_chunks: 0,
257            position: 0,
258        };
259        assert!(progress.validate().is_err());
260    }
261
262    #[test]
263    fn prefill_finish_must_match_admitted_work() {
264        let progress = PrefillProgress {
265            initial_position: 3,
266            requested_tokens: 2,
267            admitted_tokens: 1,
268            admitted_chunks: 1,
269            position: 4,
270        };
271        let receipt = PrefillReceipt {
272            implementation: implementation(),
273            progress,
274            finish: PrefillFinish::Complete,
275            polls: 1,
276            chunks: 1,
277            failure: None,
278        };
279        assert!(receipt.digest().is_err());
280    }
281
282    #[test]
283    fn complete_prefill_requires_one_poll_per_chunk() {
284        let progress = PrefillProgress {
285            initial_position: 0,
286            requested_tokens: 1,
287            admitted_tokens: 1,
288            admitted_chunks: 1,
289            position: 1,
290        };
291        let receipt = PrefillReceipt {
292            implementation: implementation(),
293            progress,
294            finish: PrefillFinish::Complete,
295            polls: 2,
296            chunks: 1,
297            failure: None,
298        };
299        assert!(receipt.digest().is_err());
300    }
301
302    #[test]
303    fn in_progress_prefill_uses_the_v2_digest_domain() {
304        let receipt = PrefillReceipt {
305            implementation: implementation(),
306            progress: PrefillProgress {
307                initial_position: 0,
308                requested_tokens: 1,
309                admitted_tokens: 0,
310                admitted_chunks: 0,
311                position: 0,
312            },
313            finish: PrefillFinish::InProgress,
314            polls: 0,
315            chunks: 0,
316            failure: None,
317        };
318        assert_eq!(
319            receipt.digest().unwrap(),
320            Digest::of_serializable("prefill-receipt-v2", &receipt).unwrap()
321        );
322    }
323}