1use serde::{Deserialize, Serialize};
6
7use crate::{
8 CandidateMode, CoreError, Digest, GenerationFinish, GenerationPlanV2, GenerationReceipt,
9 TokenId,
10};
11
12pub const MAX_STRUCTURED_SCOPE_BYTES: usize = 256;
14pub const MAX_STRUCTURED_ATTEMPTS: u32 = 64;
16pub const MAX_STRUCTURED_OUTPUT_BYTES: u32 = 1024 * 1024;
18pub const MAX_STRUCTURED_STEPS: u32 = 65_536;
20pub const MAX_STRUCTURED_CANDIDATES: u32 = 1_000_000;
22
23const OUTPUT_DOMAIN: &str = "structured-projection-output-v1";
24
25#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(deny_unknown_fields)]
29pub struct StructuredMechanicIdentityV1 {
30 pub implementation: Digest,
32 pub configuration: Digest,
34}
35
36impl StructuredMechanicIdentityV1 {
37 pub fn digest(&self) -> Result<Digest, CoreError> {
43 Digest::of_serializable("structured-mechanic-identity-v1", self)
44 }
45}
46
47#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
49#[serde(deny_unknown_fields)]
50pub struct ByteFeedbackSpecV1 {
51 pub mechanic: StructuredMechanicIdentityV1,
53 pub mode: CandidateMode,
55 pub max_steps: u32,
57 pub max_output_bytes: u32,
59}
60
61impl ByteFeedbackSpecV1 {
62 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 pub fn digest(&self) -> Result<Digest, CoreError> {
87 self.validate()?;
88 Digest::of_serializable("byte-feedback-spec-v1", self)
89 }
90}
91
92#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
98#[serde(deny_unknown_fields)]
99pub struct StructuredProjectionPlanV1 {
100 pub scope: String,
102 pub target_topology: Digest,
104 pub constraints: Digest,
106 pub compiler: StructuredMechanicIdentityV1,
108 pub validator: StructuredMechanicIdentityV1,
110 pub feedback: ByteFeedbackSpecV1,
112 pub generation: GenerationPlanV2,
114 #[serde(default, skip_serializing_if = "Option::is_none")]
116 pub transform_pipeline: Option<Digest>,
117 #[serde(default, skip_serializing_if = "Option::is_none")]
119 pub observer_set: Option<Digest>,
120 pub maximum_attempts: u32,
122}
123
124impl StructuredProjectionPlanV1 {
125 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 pub fn digest(&self) -> Result<Digest, CoreError> {
174 self.validate()?;
175 Digest::of_serializable("structured-projection-plan-v1", self)
176 }
177}
178
179#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
182#[serde(deny_unknown_fields)]
183pub struct StructuredCompilationReceiptV1 {
184 pub constraints: Digest,
186 pub compiler: Digest,
188 pub grammar: Digest,
190 pub feedback: Digest,
192 pub plan: Digest,
194}
195
196impl StructuredCompilationReceiptV1 {
197 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 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
235#[serde(deny_unknown_fields)]
236pub struct ByteFeedbackStepReceiptV1 {
237 pub step: u32,
239 pub accepted_tokens: u32,
241 pub output_bytes: u32,
243 pub output_prefix: Digest,
245 pub state: Digest,
247 pub candidate_tokens: u32,
249 pub eligible_candidates: u32,
252 pub allowed_candidates: u32,
254 pub rejected_candidates: u32,
256 pub allowed_tokens: Digest,
258 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
287#[serde(deny_unknown_fields)]
288pub struct ByteFeedbackReceiptV1 {
289 pub feedback: Digest,
291 pub tokenizer: Digest,
293 pub initial_tokens: Digest,
295 pub initial_token_count: u64,
297 pub output: Digest,
299 pub output_bytes: u32,
301 pub accepted_tokens: u32,
303 pub steps: Vec<ByteFeedbackStepReceiptV1>,
305 pub final_state: Digest,
307 pub complete: bool,
309}
310
311impl ByteFeedbackReceiptV1 {
312 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 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
364#[serde(rename_all = "snake_case")]
365pub enum StructuredValidationStatusV1 {
366 Conforms,
368 Rejected,
370}
371
372#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
374#[serde(deny_unknown_fields)]
375pub struct StructuredValidationReceiptV1 {
376 pub validator: Digest,
378 pub constraints: Digest,
380 pub source: Digest,
382 #[serde(default, skip_serializing_if = "Option::is_none")]
384 pub canonical_artifact: Option<Digest>,
385 #[serde(default, skip_serializing_if = "Option::is_none")]
387 pub validation_report: Option<Digest>,
388 pub status: StructuredValidationStatusV1,
390 pub violations: u32,
392 pub diagnostics: u32,
394}
395
396impl StructuredValidationReceiptV1 {
397 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 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
442#[serde(rename_all = "snake_case")]
443pub enum StructuredAttemptDispositionV1 {
444 Cancelled,
446 Rejected,
448 Selected,
450}
451
452#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
455#[serde(deny_unknown_fields)]
456pub struct StructuredAttemptReceiptV1 {
457 pub attempt: u32,
459 pub output: Digest,
461 pub generation: GenerationReceipt,
463 pub feedback: ByteFeedbackReceiptV1,
465 #[serde(default, skip_serializing_if = "Option::is_none")]
467 pub validation: Option<StructuredValidationReceiptV1>,
468 pub disposition: StructuredAttemptDispositionV1,
470 pub boundary_state: Digest,
472 pub terminal_state: Digest,
474}
475
476impl StructuredAttemptReceiptV1 {
477 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
548#[serde(deny_unknown_fields)]
549pub struct StructuredProjectionReceiptV1 {
550 pub plan: Digest,
552 pub compilation: Digest,
554 pub boundary_state: Digest,
556 pub attempts: Vec<StructuredAttemptReceiptV1>,
558 pub selected_attempt: u32,
560 pub final_state: Digest,
562}
563
564impl StructuredProjectionReceiptV1 {
565 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 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#[must_use]
640pub fn structured_output_digest(bytes: &[u8]) -> Digest {
641 Digest::of_bytes(OUTPUT_DOMAIN, bytes)
642}
643
644pub 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}