Skip to main content

logit_loom_core/
structured.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Backend-neutral contracts for bounded structured projection.
4
5use serde::{Deserialize, Serialize};
6
7use crate::{
8    CandidateMode, CoreError, Digest, GenerationFinish, GenerationPlanV2, GenerationReceipt,
9    TokenId,
10};
11
12/// Maximum UTF-8 bytes in one caller-defined projection scope.
13pub const MAX_STRUCTURED_SCOPE_BYTES: usize = 256;
14/// Maximum caller-explicit attempts retained by one projection controller.
15pub const MAX_STRUCTURED_ATTEMPTS: u32 = 64;
16/// Maximum generated bytes accepted by one feedback implementation.
17pub const MAX_STRUCTURED_OUTPUT_BYTES: u32 = 1024 * 1024;
18/// Maximum generated-token decisions accepted by one feedback implementation.
19pub const MAX_STRUCTURED_STEPS: u32 = 65_536;
20/// Maximum model vocabulary accepted by structured byte feedback.
21pub const MAX_STRUCTURED_CANDIDATES: u32 = 1_000_000;
22
23const OUTPUT_DOMAIN: &str = "structured-projection-output-v1";
24
25/// Content identities for one installed compiler, validator, or feedback
26/// implementation and its exact configuration.
27#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(deny_unknown_fields)]
29pub struct StructuredMechanicIdentityV1 {
30    /// Caller-defined implementation identity.
31    pub implementation: Digest,
32    /// Exact implementation-configuration identity.
33    pub configuration: Digest,
34}
35
36impl StructuredMechanicIdentityV1 {
37    /// Returns the complete component identity.
38    ///
39    /// # Errors
40    ///
41    /// Returns a deterministic serialization error.
42    pub fn digest(&self) -> Result<Digest, CoreError> {
43        Digest::of_serializable("structured-mechanic-identity-v1", self)
44    }
45}
46
47/// Exact byte-feedback implementation and resource bounds.
48#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
49#[serde(deny_unknown_fields)]
50pub struct ByteFeedbackSpecV1 {
51    /// Installed implementation and configuration.
52    pub mechanic: StructuredMechanicIdentityV1,
53    /// Candidate exposure supplied at each sampling decision.
54    pub mode: CandidateMode,
55    /// Maximum decisions in one attempt.
56    pub max_steps: u32,
57    /// Maximum admitted output bytes in one attempt.
58    pub max_output_bytes: u32,
59}
60
61impl ByteFeedbackSpecV1 {
62    /// Validates candidate and resource bounds.
63    ///
64    /// # Errors
65    ///
66    /// Returns an error for an invalid candidate mode or zero/excessive
67    /// decision or output bounds.
68    pub fn validate(&self) -> Result<(), CoreError> {
69        self.mode.validate()?;
70        if !(1..=MAX_STRUCTURED_STEPS).contains(&self.max_steps)
71            || !(1..=MAX_STRUCTURED_OUTPUT_BYTES).contains(&self.max_output_bytes)
72        {
73            return Err(CoreError::invalid(
74                "structured byte feedback",
75                "step and output-byte bounds must be positive and within public maxima",
76            ));
77        }
78        Ok(())
79    }
80
81    /// Returns the complete byte-feedback identity.
82    ///
83    /// # Errors
84    ///
85    /// Returns a validation or serialization error.
86    pub fn digest(&self) -> Result<Digest, CoreError> {
87        self.validate()?;
88        Digest::of_serializable("byte-feedback-spec-v1", self)
89    }
90}
91
92/// Complete compiled mechanics for one structured projection controller.
93///
94/// Semantic compilers and validators remain caller supplied. This plan binds
95/// their exact identities to native grammar, byte feedback, ordinary
96/// transforms/observers, generation mechanics, and explicit attempt bounds.
97#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
98#[serde(deny_unknown_fields)]
99pub struct StructuredProjectionPlanV1 {
100    /// Open caller-defined name for the projection.
101    pub scope: String,
102    /// Exact target model/topology identity expected by the native adapter.
103    pub target_topology: Digest,
104    /// Exact source schema or constraint identity.
105    pub constraints: Digest,
106    /// Compiler that produced the native grammar and feedback configuration.
107    pub compiler: StructuredMechanicIdentityV1,
108    /// Authoritative post-generation validator.
109    pub validator: StructuredMechanicIdentityV1,
110    /// Incremental exact-byte feedback implementation.
111    pub feedback: ByteFeedbackSpecV1,
112    /// Complete generation mechanics, including one eager or lazy grammar.
113    pub generation: GenerationPlanV2,
114    /// Ordered ordinary transform-pipeline identity, when installed.
115    #[serde(default, skip_serializing_if = "Option::is_none")]
116    pub transform_pipeline: Option<Digest>,
117    /// Ordered admitted-token observer identity, when installed.
118    #[serde(default, skip_serializing_if = "Option::is_none")]
119    pub observer_set: Option<Digest>,
120    /// Maximum number of calls the caller may explicitly make.
121    pub maximum_attempts: u32,
122}
123
124impl StructuredProjectionPlanV1 {
125    /// Validates complete projection mechanics and resource bounds.
126    ///
127    /// # Errors
128    ///
129    /// Returns an error for an empty/excessive scope, absent grammar, invalid
130    /// feedback/generation mechanics, or inconsistent attempt/token bounds.
131    pub fn validate(&self) -> Result<(), CoreError> {
132        if self.scope.trim().is_empty()
133            || self.scope.len() > MAX_STRUCTURED_SCOPE_BYTES
134            || self.scope.contains('\0')
135        {
136            return Err(CoreError::invalid(
137                "structured projection scope",
138                format!(
139                    "must be non-empty, NUL-free, and at most {MAX_STRUCTURED_SCOPE_BYTES} bytes"
140                ),
141            ));
142        }
143        self.compiler.digest()?;
144        self.validator.digest()?;
145        self.feedback.validate()?;
146        self.generation.validate()?;
147        if self.generation.grammar.is_none() {
148            return Err(CoreError::invalid(
149                "structured projection grammar",
150                "one explicit eager or lazy grammar is required",
151            ));
152        }
153        if self.generation.generation.max_tokens > self.feedback.max_steps {
154            return Err(CoreError::invalid(
155                "structured projection generation",
156                "generation token bound exceeds byte-feedback step capacity",
157            ));
158        }
159        if !(1..=MAX_STRUCTURED_ATTEMPTS).contains(&self.maximum_attempts) {
160            return Err(CoreError::invalid(
161                "structured projection attempts",
162                format!("must be in 1..={MAX_STRUCTURED_ATTEMPTS}"),
163            ));
164        }
165        Ok(())
166    }
167
168    /// Returns the complete compiled plan identity.
169    ///
170    /// # Errors
171    ///
172    /// Returns a validation or serialization error.
173    pub fn digest(&self) -> Result<Digest, CoreError> {
174        self.validate()?;
175        Digest::of_serializable("structured-projection-plan-v1", self)
176    }
177}
178
179/// Evidence that an identified compiler produced one complete projection
180/// plan.
181#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
182#[serde(deny_unknown_fields)]
183pub struct StructuredCompilationReceiptV1 {
184    /// Exact source schema or constraint identity.
185    pub constraints: Digest,
186    /// Complete compiler identity.
187    pub compiler: Digest,
188    /// Exact emitted eager/lazy grammar identity.
189    pub grammar: Digest,
190    /// Exact emitted byte-feedback identity.
191    pub feedback: Digest,
192    /// Complete resulting projection-plan identity.
193    pub plan: Digest,
194}
195
196impl StructuredCompilationReceiptV1 {
197    /// Validates compilation evidence against its compiler output.
198    ///
199    /// # Errors
200    ///
201    /// Returns an error when any source, compiler, grammar, feedback, or plan
202    /// identity differs.
203    pub fn validate_for(&self, plan: &StructuredProjectionPlanV1) -> Result<(), CoreError> {
204        plan.validate()?;
205        let grammar = plan.generation.grammar.as_ref().ok_or_else(|| {
206            CoreError::invalid("structured compilation", "compiled grammar is absent")
207        })?;
208        if self.constraints != plan.constraints
209            || self.compiler != plan.compiler.digest()?
210            || self.grammar != grammar.digest()?
211            || self.feedback != plan.feedback.digest()?
212            || self.plan != plan.digest()?
213        {
214            return Err(CoreError::invalid(
215                "structured compilation receipt",
216                "compiler input or output identity differs from the plan",
217            ));
218        }
219        Ok(())
220    }
221
222    /// Returns the exact validated compilation identity.
223    ///
224    /// # Errors
225    ///
226    /// Returns a validation or serialization error.
227    pub fn digest_for(&self, plan: &StructuredProjectionPlanV1) -> Result<Digest, CoreError> {
228        self.validate_for(plan)?;
229        Digest::of_serializable("structured-compilation-receipt-v1", self)
230    }
231}
232
233/// Exact symbolic decision before one native sampling operation.
234#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
235#[serde(deny_unknown_fields)]
236pub struct ByteFeedbackStepReceiptV1 {
237    /// Contiguous zero-based sampling step.
238    pub step: u32,
239    /// Tokens admitted before this decision.
240    pub accepted_tokens: u32,
241    /// Output bytes admitted before this decision.
242    pub output_bytes: u32,
243    /// Exact output prefix identity.
244    pub output_prefix: Digest,
245    /// Exact implementation-local symbolic-state identity.
246    pub state: Digest,
247    /// Candidate tokens copied into the feedback boundary.
248    pub candidate_tokens: u32,
249    /// Candidates eligible after preceding transforms; negative infinity is
250    /// already suppressed and NaN is invalid.
251    pub eligible_candidates: u32,
252    /// Eligible candidates retained by feedback.
253    pub allowed_candidates: u32,
254    /// Eligible candidates suppressed by feedback.
255    pub rejected_candidates: u32,
256    /// Ordered allowed token-ID identity.
257    pub allowed_tokens: Digest,
258    /// Ordered rejected token-ID identity.
259    pub rejected_tokens: Digest,
260}
261
262impl ByteFeedbackStepReceiptV1 {
263    fn validate_for(&self, specification: &ByteFeedbackSpecV1) -> Result<(), CoreError> {
264        if self.step >= specification.max_steps
265            || self.accepted_tokens > specification.max_steps
266            || self.output_bytes > specification.max_output_bytes
267            || self.candidate_tokens == 0
268            || self.eligible_candidates > self.candidate_tokens
269            || self.allowed_candidates == 0
270            || self.allowed_candidates > self.eligible_candidates
271            || self
272                .allowed_candidates
273                .checked_add(self.rejected_candidates)
274                != Some(self.eligible_candidates)
275        {
276            return Err(CoreError::invalid(
277                "byte-feedback step",
278                "step, output, or candidate accounting is inconsistent",
279            ));
280        }
281        Ok(())
282    }
283}
284
285/// Complete exact-byte feedback execution for one projection attempt.
286#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
287#[serde(deny_unknown_fields)]
288pub struct ByteFeedbackReceiptV1 {
289    /// Exact feedback specification identity.
290    pub feedback: Digest,
291    /// Complete ordered tokenizer token/piece/EOG-table identity.
292    pub tokenizer: Digest,
293    /// Exact causal token history at attempt start.
294    pub initial_tokens: Digest,
295    /// Initial causal token count.
296    pub initial_token_count: u64,
297    /// Exact generated output identity.
298    pub output: Digest,
299    /// Generated output byte count.
300    pub output_bytes: u32,
301    /// Generated non-EOG tokens accepted by feedback.
302    pub accepted_tokens: u32,
303    /// Ordered decision receipts.
304    pub steps: Vec<ByteFeedbackStepReceiptV1>,
305    /// Final feedback-state identity.
306    pub final_state: Digest,
307    /// Whether the final bytes form a complete symbolic artifact.
308    pub complete: bool,
309}
310
311impl ByteFeedbackReceiptV1 {
312    /// Validates exact-byte feedback identity and monotonic accounting.
313    ///
314    /// # Errors
315    ///
316    /// Returns an error for a mismatched specification, excessive bounds,
317    /// noncontiguous steps, or nonmonotonic prefix accounting.
318    pub fn validate_for(&self, specification: &ByteFeedbackSpecV1) -> Result<(), CoreError> {
319        specification.validate()?;
320        if self.feedback != specification.digest()?
321            || self.output_bytes > specification.max_output_bytes
322            || self.accepted_tokens > specification.max_steps
323            || self.steps.len() > usize::try_from(specification.max_steps).unwrap_or(usize::MAX)
324        {
325            return Err(CoreError::invalid(
326                "byte-feedback receipt",
327                "specification, output, or step accounting differs",
328            ));
329        }
330        let mut prior_tokens = 0;
331        let mut prior_bytes = 0;
332        for (expected, step) in (0_u32..).zip(&self.steps) {
333            step.validate_for(specification)?;
334            if step.step != expected
335                || step.accepted_tokens < prior_tokens
336                || step.output_bytes < prior_bytes
337                || step.accepted_tokens > self.accepted_tokens
338                || step.output_bytes > self.output_bytes
339            {
340                return Err(CoreError::invalid(
341                    "byte-feedback step order",
342                    "steps or output prefixes are not contiguous and monotonic",
343                ));
344            }
345            prior_tokens = step.accepted_tokens;
346            prior_bytes = step.output_bytes;
347        }
348        Ok(())
349    }
350
351    /// Returns the exact validated feedback-execution identity.
352    ///
353    /// # Errors
354    ///
355    /// Returns a validation or serialization error.
356    pub fn digest_for(&self, specification: &ByteFeedbackSpecV1) -> Result<Digest, CoreError> {
357        self.validate_for(specification)?;
358        Digest::of_serializable("byte-feedback-receipt-v1", self)
359    }
360}
361
362/// Authoritative post-generation validation result.
363#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
364#[serde(rename_all = "snake_case")]
365pub enum StructuredValidationStatusV1 {
366    /// Output parsed and conformed to the caller's constraint.
367    Conforms,
368    /// Output was mechanically rejected.
369    Rejected,
370}
371
372/// Content-free evidence from one installed authoritative validator.
373#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
374#[serde(deny_unknown_fields)]
375pub struct StructuredValidationReceiptV1 {
376    /// Complete validator identity.
377    pub validator: Digest,
378    /// Exact source schema or constraint identity.
379    pub constraints: Digest,
380    /// Exact generated source identity.
381    pub source: Digest,
382    /// Canonical parsed-artifact identity, when produced.
383    #[serde(default, skip_serializing_if = "Option::is_none")]
384    pub canonical_artifact: Option<Digest>,
385    /// Deterministic validation-report identity, when produced.
386    #[serde(default, skip_serializing_if = "Option::is_none")]
387    pub validation_report: Option<Digest>,
388    /// Authoritative mechanical disposition.
389    pub status: StructuredValidationStatusV1,
390    /// Number of constraint violations.
391    pub violations: u32,
392    /// Number of bounded parse or validation diagnostics.
393    pub diagnostics: u32,
394}
395
396impl StructuredValidationReceiptV1 {
397    /// Validates this result against the plan and exact output bytes.
398    ///
399    /// # Errors
400    ///
401    /// Returns an error for a mismatched validator, constraints, source, or
402    /// internally inconsistent conformance accounting.
403    pub fn validate_for(
404        &self,
405        plan: &StructuredProjectionPlanV1,
406        output: &Digest,
407    ) -> Result<(), CoreError> {
408        let valid_status = match self.status {
409            StructuredValidationStatusV1::Conforms => self.violations == 0 && self.diagnostics == 0,
410            StructuredValidationStatusV1::Rejected => self.violations > 0 || self.diagnostics > 0,
411        };
412        if self.validator != plan.validator.digest()?
413            || self.constraints != plan.constraints
414            || self.source != *output
415            || !valid_status
416        {
417            return Err(CoreError::invalid(
418                "structured validation receipt",
419                "validator, source, constraints, or disposition accounting differs",
420            ));
421        }
422        Ok(())
423    }
424
425    /// Returns the exact validated result identity.
426    ///
427    /// # Errors
428    ///
429    /// Returns a validation or serialization error.
430    pub fn digest_for(
431        &self,
432        plan: &StructuredProjectionPlanV1,
433        output: &Digest,
434    ) -> Result<Digest, CoreError> {
435        self.validate_for(plan, output)?;
436        Digest::of_serializable("structured-validation-receipt-v1", self)
437    }
438}
439
440/// Effect of one caller-explicit projection attempt.
441#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
442#[serde(rename_all = "snake_case")]
443pub enum StructuredAttemptDispositionV1 {
444    /// Cooperative cancellation restored the exact boundary.
445    Cancelled,
446    /// Authoritative validation rejected output and restored the boundary.
447    Rejected,
448    /// Conforming output remains admitted.
449    Selected,
450}
451
452/// One generated, incrementally constrained, and validated projection
453/// attempt.
454#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
455#[serde(deny_unknown_fields)]
456pub struct StructuredAttemptReceiptV1 {
457    /// Contiguous caller-explicit attempt number.
458    pub attempt: u32,
459    /// Exact generated output identity.
460    pub output: Digest,
461    /// Native generation mechanics.
462    pub generation: GenerationReceipt,
463    /// Exact byte-feedback execution.
464    pub feedback: ByteFeedbackReceiptV1,
465    /// Authoritative validation, absent only for cancellation.
466    #[serde(default, skip_serializing_if = "Option::is_none")]
467    pub validation: Option<StructuredValidationReceiptV1>,
468    /// Causal-state disposition.
469    pub disposition: StructuredAttemptDispositionV1,
470    /// Exact common checkpoint at attempt start.
471    pub boundary_state: Digest,
472    /// Exact selected or restored terminal checkpoint.
473    pub terminal_state: Digest,
474}
475
476impl StructuredAttemptReceiptV1 {
477    /// Validates one attempt and returns its exact identity.
478    ///
479    /// # Errors
480    ///
481    /// Returns an error for mismatched generation/feedback/validation
482    /// evidence or a disposition inconsistent with retained causal state.
483    pub fn digest_for(&self, plan: &StructuredProjectionPlanV1) -> Result<Digest, CoreError> {
484        self.generation.digest()?;
485        self.feedback.validate_for(&plan.feedback)?;
486        if self.generation.plan != plan.generation.digest()?
487            || self.output != self.feedback.output
488            || u64::from(self.feedback.output_bytes) != self.generation.admitted_bytes
489            || self.feedback.accepted_tokens != self.generation.admitted_tokens
490            || self.generation.transform_receipt.is_some() != plan.transform_pipeline.is_some()
491            || self.generation.observer_receipts.is_empty() == plan.observer_set.is_some()
492        {
493            return Err(CoreError::invalid(
494                "structured projection attempt",
495                "generation, output, or feedback accounting differs from the plan",
496            ));
497        }
498        if let Some(validation) = &self.validation {
499            validation.validate_for(plan, &self.output)?;
500        }
501        match self.disposition {
502            StructuredAttemptDispositionV1::Cancelled => {
503                if !matches!(self.generation.finish, GenerationFinish::ObserverStop)
504                    || self.validation.is_some()
505                    || self.terminal_state != self.boundary_state
506                {
507                    return Err(CoreError::invalid(
508                        "cancelled structured attempt",
509                        "cancellation must be unvalidated and restore the boundary",
510                    ));
511                }
512            }
513            StructuredAttemptDispositionV1::Rejected => {
514                if matches!(self.generation.finish, GenerationFinish::ObserverStop)
515                    || self.validation.as_ref().is_none_or(|validation| {
516                        validation.status != StructuredValidationStatusV1::Rejected
517                    })
518                    || self.terminal_state != self.boundary_state
519                {
520                    return Err(CoreError::invalid(
521                        "rejected structured attempt",
522                        "rejection requires authoritative nonconformance and boundary restore",
523                    ));
524                }
525            }
526            StructuredAttemptDispositionV1::Selected => {
527                if matches!(self.generation.finish, GenerationFinish::ObserverStop)
528                    || self.validation.as_ref().is_none_or(|validation| {
529                        validation.status != StructuredValidationStatusV1::Conforms
530                    })
531                    || self.terminal_state == self.boundary_state
532                    || !self.feedback.complete
533                {
534                    return Err(CoreError::invalid(
535                        "selected structured attempt",
536                        "selection requires complete conforming output retained in causal state",
537                    ));
538                }
539            }
540        }
541        Digest::of_serializable("structured-attempt-receipt-v1", self)
542    }
543}
544
545/// Terminal evidence for a projection selected after zero or more explicit
546/// cancelled/rejected attempts.
547#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
548#[serde(deny_unknown_fields)]
549pub struct StructuredProjectionReceiptV1 {
550    /// Complete projection plan identity.
551    pub plan: Digest,
552    /// Exact compiler execution identity.
553    pub compilation: Digest,
554    /// Shared initial checkpoint identity.
555    pub boundary_state: Digest,
556    /// Ordered caller-explicit attempts.
557    pub attempts: Vec<StructuredAttemptReceiptV1>,
558    /// Selected terminal attempt.
559    pub selected_attempt: u32,
560    /// Final selected causal-state identity.
561    pub final_state: Digest,
562}
563
564impl StructuredProjectionReceiptV1 {
565    /// Validates complete retry and selected-state lineage.
566    ///
567    /// # Errors
568    ///
569    /// Returns an error for a mismatched plan/compiler, empty/excessive
570    /// attempts, noncontiguous attempt order, inconsistent boundary lineage,
571    /// or a selected attempt that is not uniquely terminal.
572    pub fn validate_for(
573        &self,
574        plan: &StructuredProjectionPlanV1,
575        compilation: &StructuredCompilationReceiptV1,
576    ) -> Result<(), CoreError> {
577        if self.plan != plan.digest()?
578            || self.compilation != compilation.digest_for(plan)?
579            || self.attempts.is_empty()
580            || self.attempts.len() > usize::try_from(plan.maximum_attempts).unwrap_or(usize::MAX)
581        {
582            return Err(CoreError::invalid(
583                "structured projection receipt",
584                "plan, compilation, or attempt bounds differ",
585            ));
586        }
587        let mut selected = None;
588        for (expected, attempt) in (0_u32..).zip(&self.attempts) {
589            attempt.digest_for(plan)?;
590            if attempt.attempt != expected || attempt.boundary_state != self.boundary_state {
591                return Err(CoreError::invalid(
592                    "structured projection attempt lineage",
593                    "attempt order or common boundary differs",
594                ));
595            }
596            if attempt.disposition == StructuredAttemptDispositionV1::Selected
597                && selected.replace(attempt).is_some()
598            {
599                return Err(CoreError::invalid(
600                    "structured projection selection",
601                    "more than one attempt was selected",
602                ));
603            }
604        }
605        let Some(selected) = selected else {
606            return Err(CoreError::invalid(
607                "structured projection selection",
608                "one selected terminal attempt is required",
609            ));
610        };
611        if selected.attempt != self.selected_attempt
612            || selected.attempt.checked_add(1) != u32::try_from(self.attempts.len()).ok()
613            || selected.terminal_state != self.final_state
614        {
615            return Err(CoreError::invalid(
616                "structured projection selection",
617                "the selected attempt must be last and bind the final state",
618            ));
619        }
620        Ok(())
621    }
622
623    /// Returns the complete terminal projection identity.
624    ///
625    /// # Errors
626    ///
627    /// Returns a validation or serialization error.
628    pub fn digest_for(
629        &self,
630        plan: &StructuredProjectionPlanV1,
631        compilation: &StructuredCompilationReceiptV1,
632    ) -> Result<Digest, CoreError> {
633        self.validate_for(plan, compilation)?;
634        Digest::of_serializable("structured-projection-receipt-v1", self)
635    }
636}
637
638/// Returns the stable identity used for exact generated projection bytes.
639#[must_use]
640pub fn structured_output_digest(bytes: &[u8]) -> Digest {
641    Digest::of_bytes(OUTPUT_DOMAIN, bytes)
642}
643
644/// Returns the stable identity used for a complete ordered token-ID sequence.
645///
646/// # Errors
647///
648/// Returns a deterministic serialization error.
649pub fn structured_tokens_digest(tokens: &[TokenId]) -> Result<Digest, CoreError> {
650    Digest::of_serializable("structured-projection-tokens-v1", tokens)
651}
652
653#[cfg(test)]
654mod tests {
655    use super::*;
656    use crate::{
657        GenerationPlan, Grammar, GrammarActivationV2, GrammarPlanV2, SamplingPlan,
658        StructuredValidationStatusV1,
659    };
660
661    fn digest(label: &str) -> Digest {
662        Digest::of_bytes("structured-contract-test-v1", label.as_bytes())
663    }
664
665    fn mechanic(label: &str) -> StructuredMechanicIdentityV1 {
666        StructuredMechanicIdentityV1 {
667            implementation: digest(label),
668            configuration: digest(&format!("{label}-configuration")),
669        }
670    }
671
672    fn plan() -> StructuredProjectionPlanV1 {
673        StructuredProjectionPlanV1 {
674            scope: "mechanical-json".to_owned(),
675            target_topology: digest("target-topology"),
676            constraints: digest("constraints"),
677            compiler: mechanic("compiler"),
678            validator: mechanic("validator"),
679            feedback: ByteFeedbackSpecV1 {
680                mechanic: mechanic("feedback"),
681                mode: CandidateMode::FullVocabulary,
682                max_steps: 4,
683                max_output_bytes: 128,
684            },
685            generation: GenerationPlanV2 {
686                generation: GenerationPlan {
687                    sampling: SamplingPlan::default(),
688                    max_tokens: 4,
689                    biases: Vec::new(),
690                    grammar: None,
691                    stops: Vec::new(),
692                },
693                grammar: Some(GrammarPlanV2 {
694                    grammar: Grammar {
695                        source: "root ::= \"{}\"".to_owned(),
696                        root: "root".to_owned(),
697                    },
698                    activation: GrammarActivationV2::Eager,
699                }),
700            },
701            transform_pipeline: None,
702            observer_set: None,
703            maximum_attempts: 2,
704        }
705    }
706
707    fn compilation(plan: &StructuredProjectionPlanV1) -> StructuredCompilationReceiptV1 {
708        StructuredCompilationReceiptV1 {
709            constraints: plan.constraints.clone(),
710            compiler: plan.compiler.digest().unwrap(),
711            grammar: plan.generation.grammar.as_ref().unwrap().digest().unwrap(),
712            feedback: plan.feedback.digest().unwrap(),
713            plan: plan.digest().unwrap(),
714        }
715    }
716
717    fn feedback(plan: &StructuredProjectionPlanV1) -> ByteFeedbackReceiptV1 {
718        ByteFeedbackReceiptV1 {
719            feedback: plan.feedback.digest().unwrap(),
720            tokenizer: digest("tokenizer"),
721            initial_tokens: digest("initial-tokens"),
722            initial_token_count: 3,
723            output: structured_output_digest(b"{}"),
724            output_bytes: 2,
725            accepted_tokens: 1,
726            steps: vec![ByteFeedbackStepReceiptV1 {
727                step: 0,
728                accepted_tokens: 0,
729                output_bytes: 0,
730                output_prefix: structured_output_digest(b""),
731                state: digest("state"),
732                candidate_tokens: 16,
733                eligible_candidates: 8,
734                allowed_candidates: 2,
735                rejected_candidates: 6,
736                allowed_tokens: digest("allowed"),
737                rejected_tokens: digest("rejected"),
738            }],
739            final_state: digest("final-feedback"),
740            complete: true,
741        }
742    }
743
744    fn selected_attempt(plan: &StructuredProjectionPlanV1) -> StructuredAttemptReceiptV1 {
745        let feedback = feedback(plan);
746        StructuredAttemptReceiptV1 {
747            attempt: 0,
748            output: feedback.output.clone(),
749            generation: GenerationReceipt {
750                plan: plan.generation.digest().unwrap(),
751                initial_position: 3,
752                admitted_tokens: 1,
753                admitted_bytes: 2,
754                final_position: 4,
755                finish: GenerationFinish::TokenLimit,
756                transform_receipt: None,
757                observer_receipts: Vec::new(),
758            },
759            feedback,
760            validation: Some(StructuredValidationReceiptV1 {
761                validator: plan.validator.digest().unwrap(),
762                constraints: plan.constraints.clone(),
763                source: structured_output_digest(b"{}"),
764                canonical_artifact: Some(digest("canonical")),
765                validation_report: None,
766                status: StructuredValidationStatusV1::Conforms,
767                violations: 0,
768                diagnostics: 0,
769            }),
770            disposition: StructuredAttemptDispositionV1::Selected,
771            boundary_state: digest("boundary"),
772            terminal_state: digest("selected"),
773        }
774    }
775
776    #[test]
777    fn compiled_plan_binds_grammar_feedback_and_attempt_bounds() {
778        let valid = plan();
779        valid.validate().unwrap();
780        compilation(&valid).validate_for(&valid).unwrap();
781
782        let mut no_grammar = valid.clone();
783        no_grammar.generation.grammar = None;
784        assert!(no_grammar.validate().is_err());
785
786        let mut excessive_generation = valid;
787        excessive_generation.generation.generation.max_tokens = 5;
788        assert!(excessive_generation.validate().is_err());
789    }
790
791    #[test]
792    fn projection_requires_one_final_selected_attempt() {
793        let plan = plan();
794        let compilation = compilation(&plan);
795        let selected = selected_attempt(&plan);
796        let receipt = StructuredProjectionReceiptV1 {
797            plan: plan.digest().unwrap(),
798            compilation: compilation.digest_for(&plan).unwrap(),
799            boundary_state: digest("boundary"),
800            attempts: vec![selected.clone()],
801            selected_attempt: 0,
802            final_state: digest("selected"),
803        };
804        receipt.validate_for(&plan, &compilation).unwrap();
805
806        let mut not_terminal = receipt;
807        let mut rejected = selected;
808        rejected.attempt = 1;
809        rejected.disposition = StructuredAttemptDispositionV1::Rejected;
810        rejected.terminal_state = digest("boundary");
811        rejected.validation.as_mut().unwrap().status = StructuredValidationStatusV1::Rejected;
812        rejected.validation.as_mut().unwrap().violations = 1;
813        not_terminal.attempts.push(rejected);
814        assert!(not_terminal.validate_for(&plan, &compilation).is_err());
815    }
816}