1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Logit-transform specifications and mechanical receipts.
use serde::{Deserialize, Serialize};
use crate::{CandidateMode, CoreError, Digest};
/// Maximum stages in one ordered transform pipeline.
pub const MAX_PIPELINE_STAGES: usize = 32;
/// One content-identified transform contract.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct TransformSpec {
/// Caller-defined implementation identity.
pub implementation: Digest,
/// Candidate exposure used for every invocation.
pub mode: CandidateMode,
/// Maximum transform invocations in one call.
pub max_steps: u32,
}
impl TransformSpec {
/// Creates and validates a transform contract.
///
/// # Errors
///
/// Returns an error for an invalid mode or zero step bound.
pub fn new(
implementation: Digest,
mode: CandidateMode,
max_steps: u32,
) -> Result<Self, CoreError> {
let specification = Self {
implementation,
mode,
max_steps,
};
specification.validate()?;
Ok(specification)
}
/// Validates the bounded transform contract.
///
/// # Errors
///
/// Returns an error for an invalid mode or zero step bound.
pub fn validate(&self) -> Result<(), CoreError> {
self.mode.validate()?;
if self.max_steps == 0 {
return Err(CoreError::invalid(
"transform max steps",
"must be greater than zero",
));
}
Ok(())
}
/// Returns a content identity for this exact contract.
///
/// # Errors
///
/// Returns a validation or serialization error.
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("transform-spec-v1", self)
}
}
/// Ordered transform contracts sharing one candidate exposure.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct PipelineSpec {
/// Stages in exact execution order.
pub stages: Vec<TransformSpec>,
}
impl PipelineSpec {
/// Validates the stage bound and common candidate mode.
///
/// # Errors
///
/// Returns an error unless one to 32 compatible stages are present.
pub fn validate(&self) -> Result<(), CoreError> {
if !(1..=MAX_PIPELINE_STAGES).contains(&self.stages.len()) {
return Err(CoreError::invalid(
"pipeline stages",
format!("requires 1..={MAX_PIPELINE_STAGES} stages"),
));
}
let mode = self.stages[0].mode;
for stage in &self.stages {
stage.validate()?;
if stage.mode != mode {
return Err(CoreError::invalid(
"pipeline stages",
"all stages must use the same candidate mode",
));
}
}
Ok(())
}
/// Returns the common candidate mode.
///
/// # Errors
///
/// Returns an error when the pipeline is invalid.
pub fn mode(&self) -> Result<CandidateMode, CoreError> {
self.validate()?;
Ok(self.stages[0].mode)
}
/// Returns a content identity for this exact ordered pipeline.
///
/// # Errors
///
/// Returns a validation or serialization error.
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("transform-pipeline-spec-v1", self)
}
}
/// Callback phase that produced a contained failure.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CallbackPhase {
/// Per-call implementation reset.
Reset,
/// Per-step logit transformation.
Apply,
/// Notification of a causally admitted token.
Accept,
/// Pre-sampling observer poll.
Poll,
/// Admitted-token observation.
Observe,
/// Prefill-boundary observation.
Prefill,
}
/// Complete error or panic isolated at a callback boundary.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallbackFailure {
/// Callback phase.
pub phase: CallbackPhase,
/// Whether the callback unwound and was contained.
pub panicked: bool,
/// Complete human-readable detail.
pub message: String,
}
impl CallbackFailure {
/// Creates a failure description without discarding any detail.
pub fn new(phase: CallbackPhase, panicked: bool, message: impl Into<String>) -> Self {
Self {
phase,
panicked,
message: message.into(),
}
}
}
/// Mechanical accounting for one transform stage.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct StageReceipt {
/// Exact stage contract.
pub specification: TransformSpec,
/// Reset invocations.
pub resets: u32,
/// Apply invocations.
pub invocations: u32,
/// Candidate values presented across all invocations.
pub candidates_seen: u64,
/// Candidate logits changed by this stage.
pub logits_changed: u64,
/// Causally admitted tokens reported to this stage.
pub accepted_tokens: u32,
/// First contained failure, if any.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub failure: Option<CallbackFailure>,
}
/// Aggregate accounting for an ordered transform pipeline.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct PipelineReceipt {
/// Exact ordered pipeline contract.
pub specification: PipelineSpec,
/// Pipeline identity.
pub pipeline: Digest,
/// Begin invocations.
pub begins: u32,
/// Complete pipeline apply invocations.
pub invocations: u32,
/// Candidate values copied into the pipeline boundary.
pub candidates_copied: u64,
/// Candidate values committed after every stage succeeded.
pub candidates_committed: u64,
/// First failed stage index, if any.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub failed_stage: Option<u32>,
/// Per-stage accounting in execution order.
pub stages: Vec<StageReceipt>,
}
impl PipelineReceipt {
/// Validates structural accounting against the pipeline specification.
///
/// # Errors
///
/// Returns an error when identities, stage accounting, or failure
/// attribution are inconsistent.
pub fn validate(&self) -> Result<(), CoreError> {
self.specification.validate()?;
if self.pipeline != self.specification.digest()?
|| self.begins > 1
|| self.candidates_committed > self.candidates_copied
|| self.stages.len() != self.specification.stages.len()
{
return Err(CoreError::invalid(
"pipeline receipt",
"pipeline identity or aggregate accounting is inconsistent",
));
}
let maximum_stage_invocations = self.invocations.saturating_add(1);
let failed_stage = self
.failed_stage
.map(usize::try_from)
.transpose()
.map_err(|_| CoreError::invalid("pipeline receipt", "failed stage exceeds usize"))?;
if failed_stage.is_some_and(|index| index >= self.stages.len()) {
return Err(CoreError::invalid(
"pipeline receipt",
"failed stage is outside the pipeline",
));
}
let mut recorded_failure = None;
for (index, (stage, specification)) in self
.stages
.iter()
.zip(&self.specification.stages)
.enumerate()
{
if stage.specification != *specification
|| stage.resets > self.begins
|| stage.invocations < self.invocations
|| stage.invocations > maximum_stage_invocations
|| stage.invocations > stage.specification.max_steps
|| stage.accepted_tokens > self.invocations
|| stage.candidates_seen > self.candidates_copied
|| stage.logits_changed > stage.candidates_seen
{
return Err(CoreError::invalid(
"pipeline receipt",
"per-stage accounting is inconsistent",
));
}
if stage.failure.is_some() && recorded_failure.replace(index).is_some() {
return Err(CoreError::invalid(
"pipeline receipt",
"more than one stage records a failure",
));
}
}
if recorded_failure != failed_stage {
return Err(CoreError::invalid(
"pipeline receipt",
"failure attribution is inconsistent",
));
}
if self.begins == 0
&& (self.invocations != 0
|| self.candidates_copied != 0
|| self.candidates_committed != 0)
{
return Err(CoreError::invalid(
"pipeline receipt",
"unbegun pipeline contains execution accounting",
));
}
Ok(())
}
/// Returns a content identity for validated mechanical accounting.
///
/// # Errors
///
/// Returns a validation or serialization error.
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("transform-pipeline-receipt-v1", self)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn callback_messages_are_retained_complete() {
let message = "🧶".repeat(1_024);
let failure = CallbackFailure::new(CallbackPhase::Apply, false, message.clone());
assert_eq!(failure.message, message);
}
#[test]
fn pipeline_receipts_validate_identity_and_stage_accounting() {
let specification = PipelineSpec {
stages: vec![
TransformSpec::new(
Digest::of_bytes("test-transform", b"one"),
CandidateMode::FullVocabulary,
2,
)
.unwrap(),
],
};
let mut receipt = PipelineReceipt {
pipeline: specification.digest().unwrap(),
specification: specification.clone(),
begins: 1,
invocations: 1,
candidates_copied: 2,
candidates_committed: 2,
failed_stage: None,
stages: vec![StageReceipt {
specification: specification.stages[0].clone(),
resets: 1,
invocations: 1,
candidates_seen: 2,
logits_changed: 1,
accepted_tokens: 1,
failure: None,
}],
};
assert!(receipt.digest().is_ok());
receipt.stages[0].accepted_tokens = 2;
assert!(receipt.digest().is_err());
receipt.stages[0].accepted_tokens = 1;
receipt.pipeline = Digest::of_bytes("test-pipeline", b"wrong");
assert!(receipt.digest().is_err());
}
}