Skip to main content

logit_loom_core/
transform.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Logit-transform specifications and mechanical receipts.
4
5use serde::{Deserialize, Serialize};
6
7use crate::{CandidateMode, CoreError, Digest};
8
9/// Maximum stages in one ordered transform pipeline.
10pub const MAX_PIPELINE_STAGES: usize = 32;
11
12/// One content-identified transform contract.
13#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
14pub struct TransformSpec {
15    /// Caller-defined implementation identity.
16    pub implementation: Digest,
17    /// Candidate exposure used for every invocation.
18    pub mode: CandidateMode,
19    /// Maximum transform invocations in one call.
20    pub max_steps: u32,
21}
22
23impl TransformSpec {
24    /// Creates and validates a transform contract.
25    ///
26    /// # Errors
27    ///
28    /// Returns an error for an invalid mode or zero step bound.
29    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    /// Validates the bounded transform contract.
44    ///
45    /// # Errors
46    ///
47    /// Returns an error for an invalid mode or zero step bound.
48    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    /// Returns a content identity for this exact contract.
60    ///
61    /// # Errors
62    ///
63    /// Returns a validation or serialization error.
64    pub fn digest(&self) -> Result<Digest, CoreError> {
65        self.validate()?;
66        Digest::of_serializable("transform-spec-v1", self)
67    }
68}
69
70/// Ordered transform contracts sharing one candidate exposure.
71#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
72pub struct PipelineSpec {
73    /// Stages in exact execution order.
74    pub stages: Vec<TransformSpec>,
75}
76
77impl PipelineSpec {
78    /// Validates the stage bound and common candidate mode.
79    ///
80    /// # Errors
81    ///
82    /// Returns an error unless one to 32 compatible stages are present.
83    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    /// Returns the common candidate mode.
104    ///
105    /// # Errors
106    ///
107    /// Returns an error when the pipeline is invalid.
108    pub fn mode(&self) -> Result<CandidateMode, CoreError> {
109        self.validate()?;
110        Ok(self.stages[0].mode)
111    }
112
113    /// Returns a content identity for this exact ordered pipeline.
114    ///
115    /// # Errors
116    ///
117    /// Returns a validation or serialization error.
118    pub fn digest(&self) -> Result<Digest, CoreError> {
119        self.validate()?;
120        Digest::of_serializable("transform-pipeline-spec-v1", self)
121    }
122}
123
124/// Callback phase that produced a contained failure.
125#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
126#[serde(rename_all = "snake_case")]
127pub enum CallbackPhase {
128    /// Per-call implementation reset.
129    Reset,
130    /// Per-step logit transformation.
131    Apply,
132    /// Notification of a causally admitted token.
133    Accept,
134    /// Pre-sampling observer poll.
135    Poll,
136    /// Admitted-token observation.
137    Observe,
138    /// Prefill-boundary observation.
139    Prefill,
140}
141
142/// Complete error or panic isolated at a callback boundary.
143#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
144pub struct CallbackFailure {
145    /// Callback phase.
146    pub phase: CallbackPhase,
147    /// Whether the callback unwound and was contained.
148    pub panicked: bool,
149    /// Complete human-readable detail.
150    pub message: String,
151}
152
153impl CallbackFailure {
154    /// Creates a failure description without discarding any detail.
155    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/// Mechanical accounting for one transform stage.
165#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
166pub struct StageReceipt {
167    /// Exact stage contract.
168    pub specification: TransformSpec,
169    /// Reset invocations.
170    pub resets: u32,
171    /// Apply invocations.
172    pub invocations: u32,
173    /// Candidate values presented across all invocations.
174    pub candidates_seen: u64,
175    /// Candidate logits changed by this stage.
176    pub logits_changed: u64,
177    /// Causally admitted tokens reported to this stage.
178    pub accepted_tokens: u32,
179    /// First contained failure, if any.
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub failure: Option<CallbackFailure>,
182}
183
184/// Aggregate accounting for an ordered transform pipeline.
185#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
186pub struct PipelineReceipt {
187    /// Exact ordered pipeline contract.
188    pub specification: PipelineSpec,
189    /// Pipeline identity.
190    pub pipeline: Digest,
191    /// Begin invocations.
192    pub begins: u32,
193    /// Complete pipeline apply invocations.
194    pub invocations: u32,
195    /// Candidate values copied into the pipeline boundary.
196    pub candidates_copied: u64,
197    /// Candidate values committed after every stage succeeded.
198    pub candidates_committed: u64,
199    /// First failed stage index, if any.
200    #[serde(default, skip_serializing_if = "Option::is_none")]
201    pub failed_stage: Option<u32>,
202    /// Per-stage accounting in execution order.
203    pub stages: Vec<StageReceipt>,
204}
205
206impl PipelineReceipt {
207    /// Validates structural accounting against the pipeline specification.
208    ///
209    /// # Errors
210    ///
211    /// Returns an error when identities, stage accounting, or failure
212    /// attribution are inconsistent.
213    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    /// Returns a content identity for validated mechanical accounting.
287    ///
288    /// # Errors
289    ///
290    /// Returns a validation or serialization error.
291    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}