1use serde::{Deserialize, Serialize};
6
7use crate::{CandidateMode, CoreError, Digest};
8
9pub const MAX_PIPELINE_STAGES: usize = 32;
11
12#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
14pub struct TransformSpec {
15 pub implementation: Digest,
17 pub mode: CandidateMode,
19 pub max_steps: u32,
21}
22
23impl TransformSpec {
24 pub fn new(
30 implementation: Digest,
31 mode: CandidateMode,
32 max_steps: u32,
33 ) -> Result<Self, CoreError> {
34 let specification = Self {
35 implementation,
36 mode,
37 max_steps,
38 };
39 specification.validate()?;
40 Ok(specification)
41 }
42
43 pub fn validate(&self) -> Result<(), CoreError> {
49 self.mode.validate()?;
50 if self.max_steps == 0 {
51 return Err(CoreError::invalid(
52 "transform max steps",
53 "must be greater than zero",
54 ));
55 }
56 Ok(())
57 }
58
59 pub fn digest(&self) -> Result<Digest, CoreError> {
65 self.validate()?;
66 Digest::of_serializable("transform-spec-v1", self)
67 }
68}
69
70#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
72pub struct PipelineSpec {
73 pub stages: Vec<TransformSpec>,
75}
76
77impl PipelineSpec {
78 pub fn validate(&self) -> Result<(), CoreError> {
84 if !(1..=MAX_PIPELINE_STAGES).contains(&self.stages.len()) {
85 return Err(CoreError::invalid(
86 "pipeline stages",
87 format!("requires 1..={MAX_PIPELINE_STAGES} stages"),
88 ));
89 }
90 let mode = self.stages[0].mode;
91 for stage in &self.stages {
92 stage.validate()?;
93 if stage.mode != mode {
94 return Err(CoreError::invalid(
95 "pipeline stages",
96 "all stages must use the same candidate mode",
97 ));
98 }
99 }
100 Ok(())
101 }
102
103 pub fn mode(&self) -> Result<CandidateMode, CoreError> {
109 self.validate()?;
110 Ok(self.stages[0].mode)
111 }
112
113 pub fn digest(&self) -> Result<Digest, CoreError> {
119 self.validate()?;
120 Digest::of_serializable("transform-pipeline-spec-v1", self)
121 }
122}
123
124#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
126#[serde(rename_all = "snake_case")]
127pub enum CallbackPhase {
128 Reset,
130 Apply,
132 Accept,
134 Poll,
136 Observe,
138 Prefill,
140}
141
142#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
144pub struct CallbackFailure {
145 pub phase: CallbackPhase,
147 pub panicked: bool,
149 pub message: String,
151}
152
153impl CallbackFailure {
154 pub fn new(phase: CallbackPhase, panicked: bool, message: impl Into<String>) -> Self {
156 Self {
157 phase,
158 panicked,
159 message: message.into(),
160 }
161 }
162}
163
164#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
166pub struct StageReceipt {
167 pub specification: TransformSpec,
169 pub resets: u32,
171 pub invocations: u32,
173 pub candidates_seen: u64,
175 pub logits_changed: u64,
177 pub accepted_tokens: u32,
179 #[serde(default, skip_serializing_if = "Option::is_none")]
181 pub failure: Option<CallbackFailure>,
182}
183
184#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
186pub struct PipelineReceipt {
187 pub specification: PipelineSpec,
189 pub pipeline: Digest,
191 pub begins: u32,
193 pub invocations: u32,
195 pub candidates_copied: u64,
197 pub candidates_committed: u64,
199 #[serde(default, skip_serializing_if = "Option::is_none")]
201 pub failed_stage: Option<u32>,
202 pub stages: Vec<StageReceipt>,
204}
205
206impl PipelineReceipt {
207 pub fn validate(&self) -> Result<(), CoreError> {
214 self.specification.validate()?;
215 if self.pipeline != self.specification.digest()?
216 || self.begins > 1
217 || self.candidates_committed > self.candidates_copied
218 || self.stages.len() != self.specification.stages.len()
219 {
220 return Err(CoreError::invalid(
221 "pipeline receipt",
222 "pipeline identity or aggregate accounting is inconsistent",
223 ));
224 }
225
226 let maximum_stage_invocations = self.invocations.saturating_add(1);
227 let failed_stage = self
228 .failed_stage
229 .map(usize::try_from)
230 .transpose()
231 .map_err(|_| CoreError::invalid("pipeline receipt", "failed stage exceeds usize"))?;
232 if failed_stage.is_some_and(|index| index >= self.stages.len()) {
233 return Err(CoreError::invalid(
234 "pipeline receipt",
235 "failed stage is outside the pipeline",
236 ));
237 }
238
239 let mut recorded_failure = None;
240 for (index, (stage, specification)) in self
241 .stages
242 .iter()
243 .zip(&self.specification.stages)
244 .enumerate()
245 {
246 if stage.specification != *specification
247 || stage.resets > self.begins
248 || stage.invocations < self.invocations
249 || stage.invocations > maximum_stage_invocations
250 || stage.invocations > stage.specification.max_steps
251 || stage.accepted_tokens > self.invocations
252 || stage.candidates_seen > self.candidates_copied
253 || stage.logits_changed > stage.candidates_seen
254 {
255 return Err(CoreError::invalid(
256 "pipeline receipt",
257 "per-stage accounting is inconsistent",
258 ));
259 }
260 if stage.failure.is_some() && recorded_failure.replace(index).is_some() {
261 return Err(CoreError::invalid(
262 "pipeline receipt",
263 "more than one stage records a failure",
264 ));
265 }
266 }
267 if recorded_failure != failed_stage {
268 return Err(CoreError::invalid(
269 "pipeline receipt",
270 "failure attribution is inconsistent",
271 ));
272 }
273 if self.begins == 0
274 && (self.invocations != 0
275 || self.candidates_copied != 0
276 || self.candidates_committed != 0)
277 {
278 return Err(CoreError::invalid(
279 "pipeline receipt",
280 "unbegun pipeline contains execution accounting",
281 ));
282 }
283 Ok(())
284 }
285
286 pub fn digest(&self) -> Result<Digest, CoreError> {
292 self.validate()?;
293 Digest::of_serializable("transform-pipeline-receipt-v1", self)
294 }
295}
296
297#[cfg(test)]
298mod tests {
299 use super::*;
300
301 #[test]
302 fn callback_messages_are_retained_complete() {
303 let message = "🧶".repeat(1_024);
304 let failure = CallbackFailure::new(CallbackPhase::Apply, false, message.clone());
305 assert_eq!(failure.message, message);
306 }
307
308 #[test]
309 fn pipeline_receipts_validate_identity_and_stage_accounting() {
310 let specification = PipelineSpec {
311 stages: vec![
312 TransformSpec::new(
313 Digest::of_bytes("test-transform", b"one"),
314 CandidateMode::FullVocabulary,
315 2,
316 )
317 .unwrap(),
318 ],
319 };
320 let mut receipt = PipelineReceipt {
321 pipeline: specification.digest().unwrap(),
322 specification: specification.clone(),
323 begins: 1,
324 invocations: 1,
325 candidates_copied: 2,
326 candidates_committed: 2,
327 failed_stage: None,
328 stages: vec![StageReceipt {
329 specification: specification.stages[0].clone(),
330 resets: 1,
331 invocations: 1,
332 candidates_seen: 2,
333 logits_changed: 1,
334 accepted_tokens: 1,
335 failure: None,
336 }],
337 };
338 assert!(receipt.digest().is_ok());
339
340 receipt.stages[0].accepted_tokens = 2;
341 assert!(receipt.digest().is_err());
342 receipt.stages[0].accepted_tokens = 1;
343 receipt.pipeline = Digest::of_bytes("test-pipeline", b"wrong");
344 assert!(receipt.digest().is_err());
345 }
346}