1use serde::{Deserialize, Serialize};
6
7use crate::{CallbackFailure, CoreError, Digest};
8
9#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "snake_case")]
12pub enum ControlFlow {
13 #[default]
15 Continue,
16 Stop,
18}
19
20#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
22pub struct ObserverReceipt {
23 pub implementation: Digest,
25 pub initial_position: u64,
27 pub requested_tokens: u32,
29 pub polls: u32,
31 pub observed_tokens: u32,
33 pub observed_bytes: u64,
35 pub final_position: u64,
37 pub stop_requested: bool,
39 #[serde(default, skip_serializing_if = "Option::is_none")]
41 pub failure: Option<CallbackFailure>,
42}
43
44impl ObserverReceipt {
45 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
72pub struct PrefillProgress {
73 pub initial_position: u64,
75 pub requested_tokens: u64,
77 pub admitted_tokens: u64,
79 pub admitted_chunks: u32,
81 pub position: u64,
83}
84
85impl PrefillProgress {
86 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(rename_all = "snake_case")]
114pub enum PrefillFinish {
115 InProgress,
117 Complete,
119 Stopped,
121}
122
123#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
125pub struct PrefillReceipt {
126 pub implementation: Digest,
128 pub progress: PrefillProgress,
130 pub finish: PrefillFinish,
132 pub polls: u32,
134 pub chunks: u32,
136 #[serde(default, skip_serializing_if = "Option::is_none")]
138 pub failure: Option<CallbackFailure>,
139}
140
141impl PrefillReceipt {
142 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}