Skip to main content

stateknot_core/
model_request.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Bounded, provider-neutral model request contracts.
5
6use std::{
7    collections::{BTreeMap, BTreeSet, btree_map},
8    fmt,
9};
10
11use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
12use serde::{
13    Deserialize, Deserializer, Serialize, Serializer,
14    de::{self, SeqAccess},
15};
16use thiserror::Error;
17
18use crate::{
19    ArtifactModality, ByteCount, CapabilityIdentity, CapabilityLifecycleState, CapabilityName,
20    ContentPart, ExecutionCount, Extensions, Instruction, InstructionContent, InstructionIdentity,
21    Message, MessageId, ModelModalities, ModelModality, ModelRequirements, ModelRequirementsError,
22    ModelStructuredOutputLevel, ModelToolChoice, ModelToolChoices, ModelToolRequirements,
23    ModelTranscript, SchemaReference, TokenCount, ToolDescriptor,
24};
25
26const MEBIBYTE: u64 = 1024 * 1024;
27
28/// How a model invocation delivers its response.
29#[derive(
30    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
31)]
32#[serde(rename_all = "snake_case")]
33pub enum ModelResponseMode {
34    /// One complete response is returned after generation terminates.
35    Complete,
36    /// Validated semantic events are emitted incrementally.
37    Streaming,
38}
39
40/// Tool-selection behavior for one model request.
41#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
42#[serde(tag = "mode", rename_all = "snake_case", deny_unknown_fields)]
43pub enum ModelToolSelection {
44    /// No tool call may be emitted. Definitions may be retained for history.
45    None {},
46    /// The model decides whether and which supplied tool to call.
47    Auto {},
48    /// At least one of the supplied tools must be called.
49    Required {},
50    /// One exact supplied tool must be called.
51    Specific {
52        /// Registry-local tool name exposed to the model.
53        name: CapabilityName,
54    },
55}
56
57impl ModelToolSelection {
58    /// Constructs disabled tool selection.
59    #[must_use]
60    pub const fn none() -> Self {
61        Self::None {}
62    }
63
64    /// Constructs automatic tool selection.
65    #[must_use]
66    pub const fn auto() -> Self {
67        Self::Auto {}
68    }
69
70    /// Constructs required tool selection.
71    #[must_use]
72    pub const fn required() -> Self {
73        Self::Required {}
74    }
75
76    /// Constructs selection of one named tool.
77    #[must_use]
78    pub const fn specific(name: CapabilityName) -> Self {
79        Self::Specific { name }
80    }
81
82    /// Returns the capability-negotiation choice class.
83    #[must_use]
84    pub const fn choice(&self) -> ModelToolChoice {
85        match self {
86            Self::None {} => ModelToolChoice::None,
87            Self::Auto {} => ModelToolChoice::Auto,
88            Self::Required {} => ModelToolChoice::Required,
89            Self::Specific { .. } => ModelToolChoice::Specific,
90        }
91    }
92
93    /// Returns the selected name for specific selection.
94    #[must_use]
95    pub const fn specific_name(&self) -> Option<&CapabilityName> {
96        match self {
97            Self::Specific { name } => Some(name),
98            Self::None {} | Self::Auto {} | Self::Required {} => None,
99        }
100    }
101}
102
103/// Requested format for the text portion of a model response.
104#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
105#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
106pub enum ModelTextOutputFormat {
107    /// Unstructured validated text.
108    Text {},
109    /// Syntactically valid JSON without a schema guarantee.
110    Json {},
111    /// JSON constrained by one digest-pinned schema.
112    JsonSchema {
113        /// Exact output schema resolved from the trusted local registry.
114        schema: SchemaReference,
115    },
116}
117
118impl ModelTextOutputFormat {
119    /// Constructs plain-text output.
120    #[must_use]
121    pub const fn text() -> Self {
122        Self::Text {}
123    }
124
125    /// Constructs valid-JSON output.
126    #[must_use]
127    pub const fn json() -> Self {
128        Self::Json {}
129    }
130
131    /// Constructs JSON Schema-constrained output.
132    #[must_use]
133    pub const fn json_schema(schema: SchemaReference) -> Self {
134        Self::JsonSchema { schema }
135    }
136
137    /// Returns the corresponding capability requirement level.
138    #[must_use]
139    pub const fn required_level(&self) -> ModelStructuredOutputLevel {
140        match self {
141            Self::Text {} => ModelStructuredOutputLevel::Unsupported,
142            Self::Json {} => ModelStructuredOutputLevel::Json,
143            Self::JsonSchema { .. } => ModelStructuredOutputLevel::JsonSchema,
144        }
145    }
146
147    /// Returns the requested JSON Schema identity when applicable.
148    #[must_use]
149    pub const fn schema(&self) -> Option<&SchemaReference> {
150        match self {
151            Self::JsonSchema { schema } => Some(schema),
152            Self::Text {} | Self::Json {} => None,
153        }
154    }
155}
156
157/// Finite, provider-neutral ceilings for one model request.
158///
159/// Input and output token ceilings are both positive. Their checked sum is the
160/// minimum total context capacity used during model negotiation. Content bytes
161/// cover inline text/JSON plus every referenced instruction/message artifact;
162/// tool-schema bytes are governed by the trusted schema registry profile.
163#[allow(clippy::struct_field_names)]
164#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
165#[serde(deny_unknown_fields)]
166pub struct ModelRequestLimits {
167    max_input_tokens: TokenCount,
168    max_output_tokens: TokenCount,
169    max_content_bytes: ByteCount,
170}
171
172impl ModelRequestLimits {
173    /// Immutable v1 ceiling for resolved instruction and message bytes.
174    pub const HARD_MAX_CONTENT_BYTES: ByteCount = ByteCount::new(64 * MEBIBYTE);
175
176    /// Constructs finite request ceilings.
177    ///
178    /// # Errors
179    ///
180    /// Returns [`ModelRequestLimitsError`] for zero token/byte capacity, a
181    /// content ceiling above the hard resource limit, or token-sum overflow.
182    pub const fn new(
183        max_input_tokens: TokenCount,
184        max_output_tokens: TokenCount,
185        max_content_bytes: ByteCount,
186    ) -> Result<Self, ModelRequestLimitsError> {
187        if max_input_tokens.get() == 0 {
188            return Err(ModelRequestLimitsError::ZeroInputTokens);
189        }
190        if max_output_tokens.get() == 0 {
191            return Err(ModelRequestLimitsError::ZeroOutputTokens);
192        }
193        if max_content_bytes.get() == 0 {
194            return Err(ModelRequestLimitsError::ZeroContentBytes);
195        }
196        if max_content_bytes.get() > Self::HARD_MAX_CONTENT_BYTES.get() {
197            return Err(ModelRequestLimitsError::ContentBytesAboveHardMaximum {
198                maximum: Self::HARD_MAX_CONTENT_BYTES,
199                actual: max_content_bytes,
200            });
201        }
202        if max_input_tokens.checked_add(max_output_tokens).is_none() {
203            return Err(ModelRequestLimitsError::ContextTokensOverflow);
204        }
205        Ok(Self {
206            max_input_tokens,
207            max_output_tokens,
208            max_content_bytes,
209        })
210    }
211
212    /// Returns the local input-token ceiling used for preflight and selection.
213    #[must_use]
214    pub const fn max_input_tokens(&self) -> TokenCount {
215        self.max_input_tokens
216    }
217
218    /// Returns the inclusive generated output-token ceiling.
219    #[must_use]
220    pub const fn max_output_tokens(&self) -> TokenCount {
221        self.max_output_tokens
222    }
223
224    /// Returns the maximum resolved instruction and message bytes.
225    #[must_use]
226    pub const fn max_content_bytes(&self) -> ByteCount {
227        self.max_content_bytes
228    }
229
230    /// Returns the checked total context capacity required by this request.
231    #[must_use]
232    pub fn required_context_tokens(&self) -> TokenCount {
233        self.max_input_tokens
234            .checked_add(self.max_output_tokens)
235            .expect("validated model request token ceilings cannot overflow")
236    }
237}
238
239#[derive(Deserialize)]
240#[serde(deny_unknown_fields)]
241#[allow(clippy::struct_field_names)]
242struct ModelRequestLimitsWire {
243    max_input_tokens: TokenCount,
244    max_output_tokens: TokenCount,
245    max_content_bytes: ByteCount,
246}
247
248impl<'de> Deserialize<'de> for ModelRequestLimits {
249    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
250    where
251        D: Deserializer<'de>,
252    {
253        let wire = ModelRequestLimitsWire::deserialize(deserializer)?;
254        Self::new(
255            wire.max_input_tokens,
256            wire.max_output_tokens,
257            wire.max_content_bytes,
258        )
259        .map_err(de::Error::custom)
260    }
261}
262
263/// Invalid finite request limits.
264#[derive(Clone, Debug, Eq, Error, PartialEq)]
265#[non_exhaustive]
266pub enum ModelRequestLimitsError {
267    /// No input-token capacity was available.
268    #[error("model request max input tokens must be greater than zero")]
269    ZeroInputTokens,
270    /// No generated token could be returned.
271    #[error("model request max output tokens must be greater than zero")]
272    ZeroOutputTokens,
273    /// No request content could be supplied.
274    #[error("model request max content bytes must be greater than zero")]
275    ZeroContentBytes,
276    /// The caller tried to widen the immutable content resource bound.
277    #[error("model request content ceiling {actual} exceeds hard maximum {maximum}")]
278    ContentBytesAboveHardMaximum {
279        /// Immutable v1 maximum.
280        maximum: ByteCount,
281        /// Rejected caller ceiling.
282        actual: ByteCount,
283    },
284    /// Input and output token ceilings could not form one total context bound.
285    #[error("model request input and output token ceilings overflow total context capacity")]
286    ContextTokensOverflow,
287}
288
289#[derive(Clone, Eq, PartialEq)]
290struct RequestInstructions {
291    values: Box<[Instruction]>,
292    content_bytes: ByteCount,
293}
294
295impl RequestInstructions {
296    const MAX_LEN: usize = 32;
297    const MAX_CONTENT_BYTES: ByteCount = ByteCount::new(8 * MEBIBYTE);
298
299    fn as_slice(&self) -> &[Instruction] {
300        &self.values
301    }
302
303    fn len(&self) -> usize {
304        self.values.len()
305    }
306
307    fn is_empty(&self) -> bool {
308        self.values.is_empty()
309    }
310}
311
312impl fmt::Debug for RequestInstructions {
313    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
314        formatter
315            .debug_struct("RequestInstructions")
316            .field("count", &self.len())
317            .field("content_bytes", &self.content_bytes)
318            .finish_non_exhaustive()
319    }
320}
321
322impl Serialize for RequestInstructions {
323    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
324    where
325        S: Serializer,
326    {
327        self.values.serialize(serializer)
328    }
329}
330
331impl<'de> Deserialize<'de> for RequestInstructions {
332    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
333    where
334        D: Deserializer<'de>,
335    {
336        deserializer.deserialize_seq(RequestInstructionsVisitor)
337    }
338}
339
340struct RequestInstructionsVisitor;
341
342impl<'de> de::Visitor<'de> for RequestInstructionsVisitor {
343    type Value = RequestInstructions;
344
345    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
346        write!(
347            formatter,
348            "an array containing at most {} unique trusted instructions",
349            RequestInstructions::MAX_LEN
350        )
351    }
352
353    fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
354    where
355        A: SeqAccess<'de>,
356    {
357        let mut values = Vec::new();
358        let mut content_bytes = ByteCount::ZERO;
359        while let Some(value) = sequence.next_element::<Instruction>()? {
360            push_instruction(&mut values, &mut content_bytes, value).map_err(de::Error::custom)?;
361        }
362        Ok(RequestInstructions {
363            values: values.into_boxed_slice(),
364            content_bytes,
365        })
366    }
367}
368
369impl JsonSchema for RequestInstructions {
370    fn schema_name() -> std::borrow::Cow<'static, str> {
371        "ModelRequestInstructions".into()
372    }
373
374    fn schema_id() -> std::borrow::Cow<'static, str> {
375        concat!(module_path!(), "::RequestInstructions").into()
376    }
377
378    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
379        json_schema!({
380            "type": "array",
381            "items": generator.subschema_for::<Instruction>(),
382            "maxItems": 32,
383            "uniqueItems": true,
384            "description": "Ordered application-controlled instructions; adapters preserve this precedence order. Runtime additionally rejects duplicate instruction identities and enforces an 8388608-byte resolved-content ceiling."
385        })
386    }
387}
388
389fn push_instruction(
390    values: &mut Vec<Instruction>,
391    content_bytes: &mut ByteCount,
392    value: Instruction,
393) -> Result<(), ModelRequestError> {
394    if values.len() == RequestInstructions::MAX_LEN {
395        return Err(ModelRequestError::TooManyInstructions {
396            max: RequestInstructions::MAX_LEN,
397            observed: RequestInstructions::MAX_LEN + 1,
398        });
399    }
400    if values
401        .iter()
402        .any(|existing| existing.identity() == value.identity())
403    {
404        return Err(ModelRequestError::DuplicateInstruction {
405            identity: value.identity().clone(),
406        });
407    }
408
409    let additional = match value.content() {
410        InstructionContent::Text(text) => ByteCount::new(text.text().len() as u64),
411        InstructionContent::Artifact(artifact) => {
412            let modality = artifact.representation().modality();
413            if modality != ArtifactModality::Text {
414                return Err(ModelRequestError::UnsupportedInstructionArtifact {
415                    index: values.len(),
416                    modality,
417                });
418            }
419            artifact.representation().byte_length()
420        }
421    };
422    *content_bytes = checked_content_add(
423        *content_bytes,
424        additional,
425        RequestInstructions::MAX_CONTENT_BYTES,
426        ModelContentCollection::Instructions,
427    )?;
428    values.push(value);
429    Ok(())
430}
431
432#[derive(Clone, Eq, PartialEq)]
433struct RequestMessages {
434    values: Box<[Message]>,
435    content_bytes: ByteCount,
436    modalities: ModelModalities,
437}
438
439impl RequestMessages {
440    const MAX_LEN: usize = 256;
441    const MAX_CONTENT_BYTES: ByteCount = ModelRequestLimits::HARD_MAX_CONTENT_BYTES;
442
443    fn as_slice(&self) -> &[Message] {
444        &self.values
445    }
446
447    fn len(&self) -> usize {
448        self.values.len()
449    }
450
451    fn is_empty(&self) -> bool {
452        self.values.is_empty()
453    }
454}
455
456impl fmt::Debug for RequestMessages {
457    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
458        formatter
459            .debug_struct("RequestMessages")
460            .field("count", &self.len())
461            .field("content_bytes", &self.content_bytes)
462            .field("modalities", &self.modalities)
463            .finish_non_exhaustive()
464    }
465}
466
467impl Serialize for RequestMessages {
468    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
469    where
470        S: Serializer,
471    {
472        self.values.serialize(serializer)
473    }
474}
475
476impl<'de> Deserialize<'de> for RequestMessages {
477    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
478    where
479        D: Deserializer<'de>,
480    {
481        deserializer.deserialize_seq(RequestMessagesVisitor)
482    }
483}
484
485struct RequestMessagesVisitor;
486
487impl<'de> de::Visitor<'de> for RequestMessagesVisitor {
488    type Value = RequestMessages;
489
490    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
491        write!(
492            formatter,
493            "an array containing at most {} unique durable messages",
494            RequestMessages::MAX_LEN
495        )
496    }
497
498    fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
499    where
500        A: SeqAccess<'de>,
501    {
502        let mut values = Vec::new();
503        let mut content_bytes = ByteCount::ZERO;
504        let mut modalities = BTreeSet::new();
505        while let Some(value) = sequence.next_element::<Message>()? {
506            push_message(&mut values, &mut content_bytes, &mut modalities, value)
507                .map_err(de::Error::custom)?;
508        }
509        Ok(RequestMessages {
510            values: values.into_boxed_slice(),
511            content_bytes,
512            modalities: ModelModalities::try_new(modalities).map_err(de::Error::custom)?,
513        })
514    }
515}
516
517impl JsonSchema for RequestMessages {
518    fn schema_name() -> std::borrow::Cow<'static, str> {
519        "ModelRequestMessages".into()
520    }
521
522    fn schema_id() -> std::borrow::Cow<'static, str> {
523        concat!(module_path!(), "::RequestMessages").into()
524    }
525
526    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
527        json_schema!({
528            "type": "array",
529            "items": generator.subschema_for::<Message>(),
530            "maxItems": 256,
531            "uniqueItems": true,
532            "description": "Ordered durable messages. Runtime additionally rejects duplicate message IDs, unsupported artifact modalities, and more than 67108864 resolved content bytes."
533        })
534    }
535}
536
537fn push_message(
538    values: &mut Vec<Message>,
539    content_bytes: &mut ByteCount,
540    modalities: &mut BTreeSet<ModelModality>,
541    value: Message,
542) -> Result<(), ModelRequestError> {
543    if values.len() == RequestMessages::MAX_LEN {
544        return Err(ModelRequestError::TooManyMessages {
545            max: RequestMessages::MAX_LEN,
546            observed: RequestMessages::MAX_LEN + 1,
547        });
548    }
549    if values
550        .iter()
551        .any(|existing| existing.message_id() == value.message_id())
552    {
553        return Err(ModelRequestError::DuplicateMessage {
554            message_id: value.message_id(),
555        });
556    }
557
558    for (part_index, part) in value.parts().iter().enumerate() {
559        let additional = match part {
560            ContentPart::Text(text) => {
561                modalities.insert(ModelModality::Text);
562                ByteCount::new(text.text().len() as u64)
563            }
564            ContentPart::Json(json) => {
565                modalities.insert(ModelModality::Text);
566                ByteCount::new(json.value().stats().compact_bytes() as u64)
567            }
568            ContentPart::Artifact(artifact) => {
569                let artifact_modality = artifact.representation().modality();
570                let model_modality = map_artifact_modality(artifact_modality).ok_or(
571                    ModelRequestError::UnsupportedMessageArtifact {
572                        message_index: values.len(),
573                        part_index,
574                        modality: artifact_modality,
575                    },
576                )?;
577                modalities.insert(model_modality);
578                artifact.representation().byte_length()
579            }
580        };
581        *content_bytes = checked_content_add(
582            *content_bytes,
583            additional,
584            RequestMessages::MAX_CONTENT_BYTES,
585            ModelContentCollection::Messages,
586        )?;
587    }
588    values.push(value);
589    Ok(())
590}
591
592const fn map_artifact_modality(modality: ArtifactModality) -> Option<ModelModality> {
593    match modality {
594        ArtifactModality::Text => Some(ModelModality::Text),
595        ArtifactModality::Image => Some(ModelModality::Image),
596        ArtifactModality::Audio => Some(ModelModality::Audio),
597        ArtifactModality::Video => Some(ModelModality::Video),
598        ArtifactModality::Document => Some(ModelModality::Document),
599        ArtifactModality::StructuredData | ArtifactModality::Archive | ArtifactModality::Binary => {
600            None
601        }
602    }
603}
604
605#[derive(Clone, Eq, PartialEq)]
606struct RequestTools(BTreeMap<CapabilityName, ToolDescriptor>);
607
608impl RequestTools {
609    // Keep this wire/container bound equal to
610    // `ModelRequest::MAX_TOOL_DEFINITIONS`.
611    const MAX_LEN: usize = 128;
612
613    fn len(&self) -> usize {
614        self.0.len()
615    }
616
617    fn is_empty(&self) -> bool {
618        self.0.is_empty()
619    }
620
621    fn get(&self, name: &CapabilityName) -> Option<&ToolDescriptor> {
622        self.0.get(name)
623    }
624
625    fn iter(&self) -> btree_map::Values<'_, CapabilityName, ToolDescriptor> {
626        self.0.values()
627    }
628}
629
630impl fmt::Debug for RequestTools {
631    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
632        formatter
633            .debug_struct("RequestTools")
634            .field("count", &self.len())
635            .finish_non_exhaustive()
636    }
637}
638
639impl Serialize for RequestTools {
640    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
641    where
642        S: Serializer,
643    {
644        serializer.collect_seq(self.iter())
645    }
646}
647
648impl<'de> Deserialize<'de> for RequestTools {
649    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
650    where
651        D: Deserializer<'de>,
652    {
653        deserializer.deserialize_seq(RequestToolsVisitor)
654    }
655}
656
657struct RequestToolsVisitor;
658
659impl<'de> de::Visitor<'de> for RequestToolsVisitor {
660    type Value = RequestTools;
661
662    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
663        write!(
664            formatter,
665            "an array containing at most {} active or deprecated tools with unique names",
666            RequestTools::MAX_LEN
667        )
668    }
669
670    fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
671    where
672        A: SeqAccess<'de>,
673    {
674        let mut values = BTreeMap::new();
675        while let Some(value) = sequence.next_element::<ToolDescriptor>()? {
676            insert_tool(&mut values, value).map_err(de::Error::custom)?;
677        }
678        Ok(RequestTools(values))
679    }
680}
681
682impl JsonSchema for RequestTools {
683    fn schema_name() -> std::borrow::Cow<'static, str> {
684        "ModelRequestTools".into()
685    }
686
687    fn schema_id() -> std::borrow::Cow<'static, str> {
688        concat!(module_path!(), "::RequestTools").into()
689    }
690
691    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
692        json_schema!({
693            "type": "array",
694            "items": generator.subschema_for::<ToolDescriptor>(),
695            "maxItems": 128,
696            "uniqueItems": true,
697            "description": "Tools serialize in registry-local name order. Runtime rejects duplicate names across owners or versions and retired descriptors."
698        })
699    }
700}
701
702fn insert_tool(
703    values: &mut BTreeMap<CapabilityName, ToolDescriptor>,
704    value: ToolDescriptor,
705) -> Result<(), ModelRequestError> {
706    let name = value.metadata().identity().capability().name().clone();
707    if values.contains_key(&name) {
708        return Err(ModelRequestError::DuplicateToolName { name });
709    }
710    if values.len() == RequestTools::MAX_LEN {
711        return Err(ModelRequestError::TooManyTools {
712            max: RequestTools::MAX_LEN,
713            observed: RequestTools::MAX_LEN + 1,
714        });
715    }
716    if value.metadata().lifecycle().state() == CapabilityLifecycleState::Retired {
717        return Err(ModelRequestError::RetiredTool { name });
718    }
719    values.insert(name, value);
720    Ok(())
721}
722
723#[derive(Clone, Copy, Debug, Eq, PartialEq)]
724enum ModelContentCollection {
725    Instructions,
726    Messages,
727}
728
729fn checked_content_add(
730    current: ByteCount,
731    additional: ByteCount,
732    maximum: ByteCount,
733    collection: ModelContentCollection,
734) -> Result<ByteCount, ModelRequestError> {
735    let Some(actual) = current.checked_add(additional) else {
736        return Err(match collection {
737            ModelContentCollection::Instructions => {
738                ModelRequestError::InstructionContentBytesOverflow
739            }
740            ModelContentCollection::Messages => ModelRequestError::MessageContentBytesOverflow,
741        });
742    };
743    if actual > maximum {
744        return Err(match collection {
745            ModelContentCollection::Instructions => ModelRequestError::InstructionContentTooLarge {
746                maximum,
747                observed: actual,
748            },
749            ModelContentCollection::Messages => ModelRequestError::MessageContentTooLarge {
750                maximum,
751                observed: actual,
752            },
753        });
754    }
755    Ok(actual)
756}
757
758/// Immutable, fully normalized request passed to a model adapter.
759///
760/// Construction derives input modalities and every provider-neutral capability
761/// requirement from the supplied content and controls. Adapters must validate
762/// registered extensions and referenced schemas before provider I/O; unsupported
763/// extensions are errors and are never silently dropped. Provider-side history,
764/// automatic truncation, storage, background execution, and multi-candidate
765/// generation are intentionally outside this durable core request.
766///
767/// Structural validation does not authenticate serialized instruction owners or
768/// tool descriptors. Public protocol/API adapters must resolve those values from
769/// an authenticated tenant registry instead of accepting caller-supplied claims.
770#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
771#[serde(deny_unknown_fields)]
772pub struct ModelRequest {
773    instructions: RequestInstructions,
774    messages: RequestMessages,
775    #[serde(default, skip_serializing_if = "ModelTranscript::is_empty")]
776    transcript: ModelTranscript,
777    tools: RequestTools,
778    tool_selection: ModelToolSelection,
779    max_tool_calls_per_response: ExecutionCount,
780    strict_tool_arguments: bool,
781    output_modalities: ModelModalities,
782    #[serde(skip_serializing_if = "Option::is_none")]
783    text_output_format: Option<ModelTextOutputFormat>,
784    response_mode: ModelResponseMode,
785    reasoning_summaries: bool,
786    limits: ModelRequestLimits,
787    extensions: Extensions,
788    requirements: ModelRequirements,
789}
790
791impl ModelRequest {
792    /// Maximum tool definitions accepted by one provider-neutral request.
793    pub const MAX_TOOL_DEFINITIONS: ExecutionCount = ExecutionCount::new(128);
794
795    /// Maximum tool calls accepted from one model response.
796    pub const MAX_TOOL_CALLS_PER_RESPONSE: ExecutionCount = ExecutionCount::new(1024);
797
798    /// Starts a bounded request builder with explicit finite limits.
799    #[must_use]
800    pub fn builder(limits: ModelRequestLimits) -> ModelRequestBuilder {
801        ModelRequestBuilder::new(limits)
802    }
803
804    #[allow(clippy::too_many_arguments)]
805    fn from_parts(
806        instructions: RequestInstructions,
807        messages: RequestMessages,
808        transcript: ModelTranscript,
809        tools: RequestTools,
810        tool_selection: ModelToolSelection,
811        max_tool_calls_per_response: ExecutionCount,
812        strict_tool_arguments: bool,
813        output_modalities: ModelModalities,
814        text_output_format: Option<ModelTextOutputFormat>,
815        response_mode: ModelResponseMode,
816        reasoning_summaries: bool,
817        limits: ModelRequestLimits,
818        extensions: Extensions,
819        wire_requirements: Option<&ModelRequirements>,
820    ) -> Result<Self, ModelRequestError> {
821        if instructions.is_empty() && messages.is_empty() && transcript.is_empty() {
822            return Err(ModelRequestError::EmptyInput);
823        }
824        if output_modalities.is_empty() {
825            return Err(ModelRequestError::EmptyOutputModalities);
826        }
827        let has_text_output = output_modalities.contains(ModelModality::Text);
828        match (has_text_output, text_output_format.is_some()) {
829            (true, false) => return Err(ModelRequestError::MissingTextOutputFormat),
830            (false, true) => return Err(ModelRequestError::UnexpectedTextOutputFormat),
831            _ => {}
832        }
833
834        validate_tool_controls(
835            &tools,
836            &tool_selection,
837            max_tool_calls_per_response,
838            strict_tool_arguments,
839        )?;
840        validate_transcript_tools(&transcript, &tools)?;
841
842        let content_bytes = instructions
843            .content_bytes
844            .checked_add(messages.content_bytes)
845            .and_then(|bytes| bytes.checked_add(transcript.payload_bytes()))
846            .ok_or(ModelRequestError::TranscriptContentBytesOverflow)?;
847        if content_bytes > limits.max_content_bytes() {
848            return Err(ModelRequestError::RequestContentTooLarge {
849                maximum: limits.max_content_bytes(),
850                observed: content_bytes,
851            });
852        }
853
854        let mut input_modalities = BTreeSet::new();
855        if !instructions.is_empty() {
856            input_modalities.insert(ModelModality::Text);
857        }
858        input_modalities.extend(messages.modalities.iter().copied());
859        if !transcript.is_empty() {
860            input_modalities.insert(ModelModality::Text);
861        }
862        let input_modalities = ModelModalities::try_new(input_modalities)
863            .expect("a BTreeSet of closed modalities is valid");
864
865        let tool_requirements = if tools.is_empty() {
866            ModelToolRequirements::none()
867        } else {
868            ModelToolRequirements::new(
869                ExecutionCount::new(tools.len() as u64),
870                max_tool_calls_per_response,
871                ModelToolChoices::try_new([tool_selection.choice()])
872                    .expect("one closed tool choice is valid"),
873                strict_tool_arguments,
874            )
875            .map_err(ModelRequestError::InvalidToolRequirements)?
876        };
877        let structured_output = text_output_format
878            .as_ref()
879            .map_or(ModelStructuredOutputLevel::Unsupported, |format| {
880                format.required_level()
881            });
882        let requirements = ModelRequirements::new(
883            input_modalities,
884            output_modalities.clone(),
885            response_mode == ModelResponseMode::Streaming,
886            tool_requirements,
887            structured_output,
888            reasoning_summaries,
889            Some(limits.required_context_tokens()),
890            Some(limits.max_input_tokens()),
891            Some(limits.max_output_tokens()),
892        )
893        .map_err(ModelRequestError::InvalidRequirements)?;
894
895        if wire_requirements.is_some_and(|wire| wire != &requirements) {
896            return Err(ModelRequestError::RequirementsMismatch);
897        }
898
899        Ok(Self {
900            instructions,
901            messages,
902            transcript,
903            tools,
904            tool_selection,
905            max_tool_calls_per_response,
906            strict_tool_arguments,
907            output_modalities,
908            text_output_format,
909            response_mode,
910            reasoning_summaries,
911            limits,
912            extensions,
913            requirements,
914        })
915    }
916
917    /// Returns ordered application-owned instructions.
918    #[must_use]
919    pub fn instructions(&self) -> &[Instruction] {
920        self.instructions.as_slice()
921    }
922
923    /// Returns ordered durable conversation messages.
924    #[must_use]
925    pub fn messages(&self) -> &[Message] {
926        self.messages.as_slice()
927    }
928
929    /// Returns ordered durable prior model/tool turns.
930    #[must_use]
931    pub const fn transcript(&self) -> &ModelTranscript {
932        &self.transcript
933    }
934
935    /// Iterates available tool descriptors in canonical name order.
936    pub fn tools(&self) -> impl ExactSizeIterator<Item = &ToolDescriptor> {
937        self.tools.iter()
938    }
939
940    /// Returns one available tool by registry-local name.
941    #[must_use]
942    pub fn tool(&self, name: &CapabilityName) -> Option<&ToolDescriptor> {
943        self.tools.get(name)
944    }
945
946    /// Returns the requested tool-selection behavior.
947    #[must_use]
948    pub const fn tool_selection(&self) -> &ModelToolSelection {
949        &self.tool_selection
950    }
951
952    /// Returns the finite tool-call ceiling for one response.
953    #[must_use]
954    pub const fn max_tool_calls_per_response(&self) -> ExecutionCount {
955        self.max_tool_calls_per_response
956    }
957
958    /// Returns whether every complete tool argument must be provider-constrained.
959    #[must_use]
960    pub const fn requires_strict_tool_arguments(&self) -> bool {
961        self.strict_tool_arguments
962    }
963
964    /// Returns requested output modalities.
965    #[must_use]
966    pub const fn output_modalities(&self) -> &ModelModalities {
967        &self.output_modalities
968    }
969
970    /// Returns text output format, absent for non-text-only output.
971    #[must_use]
972    pub const fn text_output_format(&self) -> Option<&ModelTextOutputFormat> {
973        self.text_output_format.as_ref()
974    }
975
976    /// Returns complete or streaming response delivery.
977    #[must_use]
978    pub const fn response_mode(&self) -> ModelResponseMode {
979        self.response_mode
980    }
981
982    /// Returns whether a readable provider reasoning summary was requested.
983    #[must_use]
984    pub const fn requires_reasoning_summaries(&self) -> bool {
985        self.reasoning_summaries
986    }
987
988    /// Returns finite request limits.
989    #[must_use]
990    pub const fn limits(&self) -> &ModelRequestLimits {
991        &self.limits
992    }
993
994    /// Returns bounded registered provider/adapter extension values.
995    #[must_use]
996    pub const fn extensions(&self) -> &Extensions {
997        &self.extensions
998    }
999
1000    /// Returns normalized requirements derived from this exact request.
1001    #[must_use]
1002    pub const fn requirements(&self) -> &ModelRequirements {
1003        &self.requirements
1004    }
1005
1006    /// Returns resolved instruction and message content bytes.
1007    #[must_use]
1008    pub fn content_bytes(&self) -> ByteCount {
1009        self.instructions
1010            .content_bytes
1011            .checked_add(self.messages.content_bytes)
1012            .and_then(|bytes| bytes.checked_add(self.transcript.payload_bytes()))
1013            .expect("validated model request content bytes cannot overflow")
1014    }
1015}
1016
1017fn validate_tool_controls(
1018    tools: &RequestTools,
1019    selection: &ModelToolSelection,
1020    max_calls: ExecutionCount,
1021    strict_arguments: bool,
1022) -> Result<(), ModelRequestError> {
1023    if tools.is_empty() {
1024        if selection.choice() != ModelToolChoice::None {
1025            return Err(ModelRequestError::ToolSelectionWithoutTools {
1026                selection: selection.choice(),
1027            });
1028        }
1029        if max_calls.get() != 0 {
1030            return Err(ModelRequestError::ToolCallsWithoutTools { actual: max_calls });
1031        }
1032        if strict_arguments {
1033            return Err(ModelRequestError::StrictArgumentsWithoutTools);
1034        }
1035        return Ok(());
1036    }
1037
1038    if selection.choice() == ModelToolChoice::None {
1039        if max_calls != ExecutionCount::ZERO || strict_arguments {
1040            return Err(ModelRequestError::DisabledToolControls);
1041        }
1042        return Ok(());
1043    }
1044    if max_calls.get() == 0 {
1045        return Err(ModelRequestError::ZeroToolCalls);
1046    }
1047    if max_calls > ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE {
1048        return Err(ModelRequestError::TooManyToolCalls {
1049            maximum: ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE,
1050            actual: max_calls,
1051        });
1052    }
1053    if let Some(name) = selection.specific_name() {
1054        if tools.get(name).is_none() {
1055            return Err(ModelRequestError::SpecificToolNotFound { name: name.clone() });
1056        }
1057    }
1058    Ok(())
1059}
1060
1061fn validate_transcript_tools(
1062    transcript: &ModelTranscript,
1063    tools: &RequestTools,
1064) -> Result<(), ModelRequestError> {
1065    for (turn_index, turn) in transcript.iter().enumerate() {
1066        for (call_index, proposal) in turn.response().tool_calls().enumerate() {
1067            let Some(descriptor) = tools.get(proposal.tool().name()) else {
1068                return Err(ModelRequestError::TranscriptToolNotAvailable {
1069                    turn_index,
1070                    call_index,
1071                    tool: Box::new(proposal.tool().clone()),
1072                });
1073            };
1074            let expected = descriptor.metadata().identity();
1075            if proposal.tool() != expected {
1076                return Err(ModelRequestError::TranscriptToolIdentityMismatch {
1077                    turn_index,
1078                    call_index,
1079                    expected: Box::new(expected.clone()),
1080                    actual: Box::new(proposal.tool().clone()),
1081                });
1082            }
1083        }
1084    }
1085    Ok(())
1086}
1087
1088impl fmt::Debug for ModelRequest {
1089    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1090        formatter
1091            .debug_struct("ModelRequest")
1092            .field("instructions", &self.instructions)
1093            .field("messages", &self.messages)
1094            .field("transcript", &self.transcript)
1095            .field("tools", &self.tools)
1096            .field("tool_selection", &self.tool_selection)
1097            .field(
1098                "max_tool_calls_per_response",
1099                &self.max_tool_calls_per_response,
1100            )
1101            .field("strict_tool_arguments", &self.strict_tool_arguments)
1102            .field("output_modalities", &self.output_modalities)
1103            .field("text_output_format", &self.text_output_format)
1104            .field("response_mode", &self.response_mode)
1105            .field("reasoning_summaries", &self.reasoning_summaries)
1106            .field("limits", &self.limits)
1107            .field("extensions", &self.extensions)
1108            .field("requirements", &self.requirements)
1109            .finish_non_exhaustive()
1110    }
1111}
1112
1113#[derive(Deserialize)]
1114#[serde(deny_unknown_fields)]
1115struct ModelRequestWire {
1116    instructions: RequestInstructions,
1117    messages: RequestMessages,
1118    #[serde(default)]
1119    transcript: ModelTranscript,
1120    tools: RequestTools,
1121    tool_selection: ModelToolSelection,
1122    max_tool_calls_per_response: ExecutionCount,
1123    strict_tool_arguments: bool,
1124    output_modalities: ModelModalities,
1125    #[serde(default)]
1126    text_output_format: Option<ModelTextOutputFormat>,
1127    response_mode: ModelResponseMode,
1128    reasoning_summaries: bool,
1129    limits: ModelRequestLimits,
1130    extensions: Extensions,
1131    requirements: ModelRequirements,
1132}
1133
1134impl<'de> Deserialize<'de> for ModelRequest {
1135    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1136    where
1137        D: Deserializer<'de>,
1138    {
1139        let wire = ModelRequestWire::deserialize(deserializer)?;
1140        Self::from_parts(
1141            wire.instructions,
1142            wire.messages,
1143            wire.transcript,
1144            wire.tools,
1145            wire.tool_selection,
1146            wire.max_tool_calls_per_response,
1147            wire.strict_tool_arguments,
1148            wire.output_modalities,
1149            wire.text_output_format,
1150            wire.response_mode,
1151            wire.reasoning_summaries,
1152            wire.limits,
1153            wire.extensions,
1154            Some(&wire.requirements),
1155        )
1156        .map_err(de::Error::custom)
1157    }
1158}
1159
1160/// Fluent, fail-closed builder for [`ModelRequest`].
1161///
1162/// Collection methods retain the first validation error and stop accepting
1163/// further collection values, so fluent construction cannot grow beyond hard
1164/// limits before [`Self::build`] reports the error.
1165pub struct ModelRequestBuilder {
1166    instructions: Vec<Instruction>,
1167    instruction_content_bytes: ByteCount,
1168    messages: Vec<Message>,
1169    message_content_bytes: ByteCount,
1170    message_modalities: BTreeSet<ModelModality>,
1171    transcript: ModelTranscript,
1172    tools: BTreeMap<CapabilityName, ToolDescriptor>,
1173    tool_selection: ModelToolSelection,
1174    max_tool_calls_per_response: ExecutionCount,
1175    strict_tool_arguments: bool,
1176    output_modalities: ModelModalities,
1177    text_output_format: Option<ModelTextOutputFormat>,
1178    response_mode: ModelResponseMode,
1179    reasoning_summaries: bool,
1180    limits: ModelRequestLimits,
1181    extensions: Extensions,
1182    error: Option<ModelRequestError>,
1183}
1184
1185impl ModelRequestBuilder {
1186    fn new(limits: ModelRequestLimits) -> Self {
1187        Self {
1188            instructions: Vec::new(),
1189            instruction_content_bytes: ByteCount::ZERO,
1190            messages: Vec::new(),
1191            message_content_bytes: ByteCount::ZERO,
1192            message_modalities: BTreeSet::new(),
1193            transcript: ModelTranscript::empty(),
1194            tools: BTreeMap::new(),
1195            tool_selection: ModelToolSelection::none(),
1196            max_tool_calls_per_response: ExecutionCount::ZERO,
1197            strict_tool_arguments: false,
1198            output_modalities: ModelModalities::try_new([ModelModality::Text])
1199                .expect("one closed modality is valid"),
1200            text_output_format: Some(ModelTextOutputFormat::text()),
1201            response_mode: ModelResponseMode::Complete,
1202            reasoning_summaries: false,
1203            limits,
1204            extensions: Extensions::default(),
1205            error: None,
1206        }
1207    }
1208
1209    /// Appends one ordered trusted instruction.
1210    #[must_use]
1211    pub fn instruction(mut self, instruction: Instruction) -> Self {
1212        if self.error.is_none() {
1213            if let Err(error) = push_instruction(
1214                &mut self.instructions,
1215                &mut self.instruction_content_bytes,
1216                instruction,
1217            ) {
1218                self.error = Some(error);
1219            }
1220        }
1221        self
1222    }
1223
1224    /// Appends one ordered durable message.
1225    #[must_use]
1226    pub fn message(mut self, message: Message) -> Self {
1227        if self.error.is_none() {
1228            if let Err(error) = push_message(
1229                &mut self.messages,
1230                &mut self.message_content_bytes,
1231                &mut self.message_modalities,
1232                message,
1233            ) {
1234                self.error = Some(error);
1235            }
1236        }
1237        self
1238    }
1239
1240    /// Replaces the complete ordered prior model/tool transcript.
1241    #[must_use]
1242    pub fn transcript(mut self, transcript: ModelTranscript) -> Self {
1243        self.transcript = transcript;
1244        self
1245    }
1246
1247    /// Adds one tool descriptor under its registry-local name.
1248    #[must_use]
1249    pub fn tool(mut self, tool: ToolDescriptor) -> Self {
1250        if self.error.is_none() {
1251            if let Err(error) = insert_tool(&mut self.tools, tool) {
1252                self.error = Some(error);
1253            }
1254        }
1255        self
1256    }
1257
1258    /// Sets tool-selection behavior.
1259    #[must_use]
1260    pub fn tool_selection(mut self, selection: ModelToolSelection) -> Self {
1261        self.tool_selection = selection;
1262        self
1263    }
1264
1265    /// Sets the finite per-response tool-call ceiling.
1266    #[must_use]
1267    pub const fn max_tool_calls_per_response(mut self, maximum: ExecutionCount) -> Self {
1268        self.max_tool_calls_per_response = maximum;
1269        self
1270    }
1271
1272    /// Requires provider-constrained complete tool arguments.
1273    #[must_use]
1274    pub const fn strict_tool_arguments(mut self, required: bool) -> Self {
1275        self.strict_tool_arguments = required;
1276        self
1277    }
1278
1279    /// Replaces requested output modalities.
1280    #[must_use]
1281    pub fn output_modalities(mut self, modalities: ModelModalities) -> Self {
1282        self.output_modalities = modalities;
1283        self
1284    }
1285
1286    /// Sets text output format, or removes it for non-text-only output.
1287    #[must_use]
1288    pub fn text_output_format(mut self, format: Option<ModelTextOutputFormat>) -> Self {
1289        self.text_output_format = format;
1290        self
1291    }
1292
1293    /// Selects complete or streaming response delivery.
1294    #[must_use]
1295    pub const fn response_mode(mut self, mode: ModelResponseMode) -> Self {
1296        self.response_mode = mode;
1297        self
1298    }
1299
1300    /// Requests or disables a readable provider reasoning summary.
1301    #[must_use]
1302    pub const fn reasoning_summaries(mut self, required: bool) -> Self {
1303        self.reasoning_summaries = required;
1304        self
1305    }
1306
1307    /// Replaces bounded registered extension values.
1308    #[must_use]
1309    pub fn extensions(mut self, extensions: Extensions) -> Self {
1310        self.extensions = extensions;
1311        self
1312    }
1313
1314    /// Validates cross-field invariants and derives normalized requirements.
1315    ///
1316    /// # Errors
1317    ///
1318    /// Returns [`ModelRequestError`] for the first resource, identity, modality,
1319    /// tool-control, output-format, or derived-requirement violation.
1320    pub fn build(self) -> Result<ModelRequest, ModelRequestError> {
1321        if let Some(error) = self.error {
1322            return Err(error);
1323        }
1324        ModelRequest::from_parts(
1325            RequestInstructions {
1326                values: self.instructions.into_boxed_slice(),
1327                content_bytes: self.instruction_content_bytes,
1328            },
1329            RequestMessages {
1330                values: self.messages.into_boxed_slice(),
1331                content_bytes: self.message_content_bytes,
1332                modalities: ModelModalities::try_new(self.message_modalities)
1333                    .expect("a BTreeSet of closed modalities is valid"),
1334            },
1335            self.transcript,
1336            RequestTools(self.tools),
1337            self.tool_selection,
1338            self.max_tool_calls_per_response,
1339            self.strict_tool_arguments,
1340            self.output_modalities,
1341            self.text_output_format,
1342            self.response_mode,
1343            self.reasoning_summaries,
1344            self.limits,
1345            self.extensions,
1346            None,
1347        )
1348    }
1349}
1350
1351impl fmt::Debug for ModelRequestBuilder {
1352    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1353        formatter
1354            .debug_struct("ModelRequestBuilder")
1355            .field("instruction_count", &self.instructions.len())
1356            .field("instruction_content_bytes", &self.instruction_content_bytes)
1357            .field("message_count", &self.messages.len())
1358            .field("message_content_bytes", &self.message_content_bytes)
1359            .field("transcript", &self.transcript)
1360            .field("tool_count", &self.tools.len())
1361            .field("tool_selection", &self.tool_selection)
1362            .field(
1363                "max_tool_calls_per_response",
1364                &self.max_tool_calls_per_response,
1365            )
1366            .field("strict_tool_arguments", &self.strict_tool_arguments)
1367            .field("output_modalities", &self.output_modalities)
1368            .field("text_output_format", &self.text_output_format)
1369            .field("response_mode", &self.response_mode)
1370            .field("reasoning_summaries", &self.reasoning_summaries)
1371            .field("limits", &self.limits)
1372            .field("extensions", &self.extensions)
1373            .field("has_error", &self.error.is_some())
1374            .finish_non_exhaustive()
1375    }
1376}
1377
1378/// Invalid provider-neutral model request.
1379#[derive(Clone, Debug, Eq, Error, PartialEq)]
1380#[non_exhaustive]
1381pub enum ModelRequestError {
1382    /// No trusted instruction, durable message, or prior transcript was supplied.
1383    #[error("model request requires at least one instruction, message, or transcript turn")]
1384    EmptyInput,
1385    /// Trusted instruction count exceeded its hard ceiling.
1386    #[error("model request contains at least {observed} instructions; maximum is {max}")]
1387    TooManyInstructions {
1388        /// Immutable v1 maximum.
1389        max: usize,
1390        /// Minimum observed count before validation stopped.
1391        observed: usize,
1392    },
1393    /// One instruction identity appeared more than once.
1394    #[error("model request repeats instruction identity {identity:?}")]
1395    DuplicateInstruction {
1396        /// Repeated identity.
1397        identity: InstructionIdentity,
1398    },
1399    /// A non-text artifact was used as a trusted model instruction.
1400    #[error("model request instruction {index} has unsupported artifact modality {modality:?}")]
1401    UnsupportedInstructionArtifact {
1402        /// Zero-based instruction index.
1403        index: usize,
1404        /// Rejected artifact modality.
1405        modality: ArtifactModality,
1406    },
1407    /// Durable message count exceeded its hard ceiling.
1408    #[error("model request contains at least {observed} messages; maximum is {max}")]
1409    TooManyMessages {
1410        /// Immutable v1 maximum.
1411        max: usize,
1412        /// Minimum observed count before validation stopped.
1413        observed: usize,
1414    },
1415    /// One durable message ID appeared more than once.
1416    #[error("model request repeats message ID {message_id}")]
1417    DuplicateMessage {
1418        /// Repeated durable ID.
1419        message_id: MessageId,
1420    },
1421    /// A message artifact has no portable model modality mapping.
1422    #[error(
1423        "model request message {message_index} part {part_index} has unsupported artifact modality {modality:?}"
1424    )]
1425    UnsupportedMessageArtifact {
1426        /// Zero-based message index.
1427        message_index: usize,
1428        /// Zero-based content-part index.
1429        part_index: usize,
1430        /// Rejected artifact modality.
1431        modality: ArtifactModality,
1432    },
1433    /// Resolved instruction content exceeded its hard ceiling.
1434    #[error("model request instruction content is {observed} bytes; maximum is {maximum}")]
1435    InstructionContentTooLarge {
1436        /// Immutable instruction-content maximum.
1437        maximum: ByteCount,
1438        /// First observed aggregate above the maximum.
1439        observed: ByteCount,
1440    },
1441    /// Resolved message content exceeded its hard ceiling.
1442    #[error("model request message content is {observed} bytes; maximum is {maximum}")]
1443    MessageContentTooLarge {
1444        /// Immutable message-content maximum.
1445        maximum: ByteCount,
1446        /// First observed aggregate above the maximum.
1447        observed: ByteCount,
1448    },
1449    /// Instruction content byte accounting could not be represented.
1450    #[error("model request instruction content-byte accounting overflowed")]
1451    InstructionContentBytesOverflow,
1452    /// Message content byte accounting could not be represented.
1453    #[error("model request message content-byte accounting overflowed")]
1454    MessageContentBytesOverflow,
1455    /// Combined transcript content byte accounting could not be represented.
1456    #[error("model request transcript content-byte accounting overflowed")]
1457    TranscriptContentBytesOverflow,
1458    /// Combined instruction and message bytes exceeded the caller ceiling.
1459    #[error("model request content is {observed} bytes; configured maximum is {maximum}")]
1460    RequestContentTooLarge {
1461        /// Configured finite ceiling.
1462        maximum: ByteCount,
1463        /// Resolved content bytes.
1464        observed: ByteCount,
1465    },
1466    /// Tool count exceeded its hard ceiling.
1467    #[error("model request contains at least {observed} tools; maximum is {max}")]
1468    TooManyTools {
1469        /// Immutable v1 maximum.
1470        max: usize,
1471        /// Minimum observed count before validation stopped.
1472        observed: usize,
1473    },
1474    /// Two descriptors exposed the same provider-visible name.
1475    #[error("model request contains duplicate tool name {name}")]
1476    DuplicateToolName {
1477        /// Colliding registry-local name.
1478        name: CapabilityName,
1479    },
1480    /// A retired descriptor was selected for new execution.
1481    #[error("model request cannot select retired tool {name}")]
1482    RetiredTool {
1483        /// Retired tool name.
1484        name: CapabilityName,
1485    },
1486    /// A prior turn proposed a tool absent from the current immutable request.
1487    #[error(
1488        "model transcript turn {turn_index} call {call_index} references unavailable tool {tool:?}"
1489    )]
1490    TranscriptToolNotAvailable {
1491        /// Zero-based transcript turn position.
1492        turn_index: usize,
1493        /// Zero-based tool proposal position within the turn.
1494        call_index: usize,
1495        /// Unavailable owner-qualified tool identity.
1496        tool: Box<CapabilityIdentity>,
1497    },
1498    /// A prior turn's registry-local tool name resolved to another version.
1499    #[error(
1500        "model transcript turn {turn_index} call {call_index} tool identity does not match the request snapshot"
1501    )]
1502    TranscriptToolIdentityMismatch {
1503        /// Zero-based transcript turn position.
1504        turn_index: usize,
1505        /// Zero-based tool proposal position within the turn.
1506        call_index: usize,
1507        /// Exact current descriptor identity.
1508        expected: Box<CapabilityIdentity>,
1509        /// Rejected historical claim.
1510        actual: Box<CapabilityIdentity>,
1511    },
1512    /// Tool selection was active without any definitions.
1513    #[error("model request tool selection {selection:?} requires at least one tool")]
1514    ToolSelectionWithoutTools {
1515        /// Invalid active selection.
1516        selection: ModelToolChoice,
1517    },
1518    /// A call ceiling was present without tool definitions.
1519    #[error("model request without tools cannot allow {actual} tool calls")]
1520    ToolCallsWithoutTools {
1521        /// Invalid non-zero call ceiling.
1522        actual: ExecutionCount,
1523    },
1524    /// Strict arguments were requested without tools.
1525    #[error("model request without tools cannot require strict tool arguments")]
1526    StrictArgumentsWithoutTools,
1527    /// Disabled tool selection cannot allow calls or require strict arguments.
1528    #[error("disabled tool selection requires zero calls and non-strict arguments")]
1529    DisabledToolControls,
1530    /// Active tools had no possible response call capacity.
1531    #[error("model request with tools requires a positive tool-call ceiling")]
1532    ZeroToolCalls,
1533    /// The per-response call ceiling exceeded the immutable resource limit.
1534    #[error("model request tool-call ceiling {actual} exceeds maximum {maximum}")]
1535    TooManyToolCalls {
1536        /// Immutable v1 maximum.
1537        maximum: ExecutionCount,
1538        /// Rejected caller ceiling.
1539        actual: ExecutionCount,
1540    },
1541    /// Specific selection named no supplied descriptor.
1542    #[error("model request selected unavailable tool {name}")]
1543    SpecificToolNotFound {
1544        /// Missing provider-visible name.
1545        name: CapabilityName,
1546    },
1547    /// No response modality was requested.
1548    #[error("model request requires at least one output modality")]
1549    EmptyOutputModalities,
1550    /// Text output lacked an explicit format.
1551    #[error("model request with text output requires an explicit text output format")]
1552    MissingTextOutputFormat,
1553    /// A text format was attached to non-text-only output.
1554    #[error("model request without text output cannot declare a text output format")]
1555    UnexpectedTextOutputFormat,
1556    /// Internal normalized tool requirements were not coherent.
1557    #[error("model request could not derive coherent tool requirements: {0}")]
1558    InvalidToolRequirements(crate::ModelToolRequirementsError),
1559    /// Internal normalized model requirements were not coherent.
1560    #[error("model request could not derive coherent requirements: {0}")]
1561    InvalidRequirements(ModelRequirementsError),
1562    /// Serialized derived requirements did not match request fields.
1563    #[error("model request serialized requirements do not match normalized request fields")]
1564    RequirementsMismatch,
1565}
1566
1567#[cfg(test)]
1568mod tests {
1569    use super::*;
1570    use crate::{ArtifactRef, MessageParts};
1571    use proptest::prelude::*;
1572    use serde_json::{Value, from_value, json, to_value};
1573
1574    fn fixture(path: &[&str], source: &str) -> Value {
1575        let mut value = serde_json::from_str::<Value>(source).unwrap();
1576        for segment in path {
1577            value = value[*segment].clone();
1578        }
1579        value
1580    }
1581
1582    fn instruction() -> Instruction {
1583        let values = fixture(
1584            &["instructions", "valid"],
1585            include_str!("../tests/fixtures/core-message-v1.json"),
1586        );
1587        from_value(values[0].clone()).unwrap()
1588    }
1589
1590    fn message() -> Message {
1591        let values = fixture(
1592            &["messages", "valid"],
1593            include_str!("../tests/fixtures/core-message-v1.json"),
1594        );
1595        from_value(values[0].clone()).unwrap()
1596    }
1597
1598    fn tool_value(name: &str) -> Value {
1599        let values = fixture(
1600            &["descriptors", "valid"],
1601            include_str!("../tests/fixtures/core-tool-v1.json"),
1602        );
1603        let mut value = values[0].clone();
1604        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1605        value
1606    }
1607
1608    fn tool(name: &str) -> ToolDescriptor {
1609        from_value(tool_value(name)).unwrap()
1610    }
1611
1612    fn artifact(
1613        modality: ArtifactModality,
1614        byte_length: ByteCount,
1615        application_controlled: bool,
1616    ) -> ArtifactRef {
1617        let values = fixture(
1618            &["artifact_refs", "valid"],
1619            include_str!("../tests/fixtures/core-artifact-v1.json"),
1620        );
1621        let mut value = values[0].clone();
1622        value["representation"]["modality"] = to_value(modality).unwrap();
1623        value["representation"]["byte_length"] = Value::from(byte_length.get().to_string());
1624        if application_controlled {
1625            value["metadata"]["trust"] = Value::from("application_controlled");
1626        }
1627        from_value(value).unwrap()
1628    }
1629
1630    fn instruction_artifact(modality: ArtifactModality, byte_length: ByteCount) -> Instruction {
1631        let base = instruction();
1632        Instruction::new(
1633            base.identity().clone(),
1634            artifact(modality, byte_length, true).into(),
1635            base.provenance().clone(),
1636        )
1637        .unwrap()
1638    }
1639
1640    fn message_artifact(modality: ArtifactModality, byte_length: ByteCount) -> Message {
1641        let base = message();
1642        Message::new(
1643            base.message_id(),
1644            base.role(),
1645            MessageParts::try_new([ContentPart::from(artifact(modality, byte_length, false))])
1646                .unwrap(),
1647            base.provenance().clone(),
1648        )
1649        .unwrap()
1650    }
1651
1652    fn retired_tool(name: &str) -> ToolDescriptor {
1653        let mut value = tool_value(name);
1654        value["metadata"]["lifecycle"] = json!({
1655            "status": "retired",
1656            "retired_at": "2027-02-28T00:00:00.000001Z",
1657            "notice": "Retained only for durable history."
1658        });
1659        from_value(value).unwrap()
1660    }
1661
1662    fn limits() -> ModelRequestLimits {
1663        ModelRequestLimits::new(
1664            TokenCount::new(8_192),
1665            TokenCount::new(1_024),
1666            ByteCount::new(MEBIBYTE),
1667        )
1668        .unwrap()
1669    }
1670
1671    fn modalities(values: impl IntoIterator<Item = ModelModality>) -> ModelModalities {
1672        ModelModalities::try_new(values).unwrap()
1673    }
1674
1675    fn base_builder() -> ModelRequestBuilder {
1676        ModelRequest::builder(limits()).instruction(instruction())
1677    }
1678
1679    fn base_request() -> ModelRequest {
1680        base_builder().message(message()).build().unwrap()
1681    }
1682
1683    #[test]
1684    fn request_control_enums_have_closed_canonical_wire_forms() {
1685        assert_eq!(to_value(ModelResponseMode::Complete).unwrap(), "complete");
1686        assert_eq!(to_value(ModelResponseMode::Streaming).unwrap(), "streaming");
1687        assert!(from_value::<ModelResponseMode>(json!("incremental")).is_err());
1688
1689        assert_eq!(
1690            to_value(ModelToolSelection::none()).unwrap(),
1691            json!({"mode": "none"})
1692        );
1693        assert_eq!(
1694            to_value(ModelToolSelection::auto()).unwrap(),
1695            json!({"mode": "auto"})
1696        );
1697        assert_eq!(
1698            to_value(ModelToolSelection::required()).unwrap(),
1699            json!({"mode": "required"})
1700        );
1701        let name = CapabilityName::new("payments.capture").unwrap();
1702        let specific = ModelToolSelection::specific(name.clone());
1703        assert_eq!(specific.choice(), ModelToolChoice::Specific);
1704        assert_eq!(specific.specific_name(), Some(&name));
1705        assert_eq!(
1706            to_value(specific).unwrap(),
1707            json!({"mode": "specific", "name": "payments.capture"})
1708        );
1709        assert!(from_value::<ModelToolSelection>(json!({"mode": "none", "name": "x"})).is_err());
1710
1711        assert_eq!(
1712            to_value(ModelTextOutputFormat::text()).unwrap(),
1713            json!({"type": "text"})
1714        );
1715        assert_eq!(
1716            to_value(ModelTextOutputFormat::json()).unwrap(),
1717            json!({"type": "json"})
1718        );
1719        assert!(from_value::<ModelTextOutputFormat>(json!({"type": "xml"})).is_err());
1720    }
1721
1722    #[test]
1723    fn limits_are_positive_bounded_checked_and_closed() {
1724        assert_eq!(limits().required_context_tokens(), TokenCount::new(9_216));
1725        assert_eq!(
1726            ModelRequestLimits::new(TokenCount::ZERO, TokenCount::new(1), ByteCount::new(1)),
1727            Err(ModelRequestLimitsError::ZeroInputTokens)
1728        );
1729        assert_eq!(
1730            ModelRequestLimits::new(TokenCount::new(1), TokenCount::ZERO, ByteCount::new(1)),
1731            Err(ModelRequestLimitsError::ZeroOutputTokens)
1732        );
1733        assert_eq!(
1734            ModelRequestLimits::new(TokenCount::new(1), TokenCount::new(1), ByteCount::ZERO),
1735            Err(ModelRequestLimitsError::ZeroContentBytes)
1736        );
1737        assert_eq!(
1738            ModelRequestLimits::new(
1739                TokenCount::new(1),
1740                TokenCount::new(1),
1741                ByteCount::new(ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get() + 1)
1742            ),
1743            Err(ModelRequestLimitsError::ContentBytesAboveHardMaximum {
1744                maximum: ModelRequestLimits::HARD_MAX_CONTENT_BYTES,
1745                actual: ByteCount::new(ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get() + 1),
1746            })
1747        );
1748        assert_eq!(
1749            ModelRequestLimits::new(TokenCount::MAX, TokenCount::new(1), ByteCount::new(1)),
1750            Err(ModelRequestLimitsError::ContextTokensOverflow)
1751        );
1752
1753        let encoded = to_value(limits()).unwrap();
1754        assert_eq!(
1755            from_value::<ModelRequestLimits>(encoded.clone()).unwrap(),
1756            limits()
1757        );
1758        let mut unknown = encoded;
1759        unknown["unlimited"] = Value::Bool(true);
1760        assert!(from_value::<ModelRequestLimits>(unknown).is_err());
1761    }
1762
1763    #[test]
1764    fn default_request_derives_exact_requirements_and_redacts_payloads() {
1765        let request = base_request();
1766        assert_eq!(request.instructions(), &[instruction()]);
1767        assert_eq!(request.messages(), &[message()]);
1768        assert_eq!(request.tools().len(), 0);
1769        assert_eq!(request.tool_selection(), &ModelToolSelection::none());
1770        assert_eq!(request.max_tool_calls_per_response(), ExecutionCount::ZERO);
1771        assert!(!request.requires_strict_tool_arguments());
1772        assert_eq!(request.response_mode(), ModelResponseMode::Complete);
1773        assert_eq!(
1774            request.text_output_format(),
1775            Some(&ModelTextOutputFormat::text())
1776        );
1777
1778        let requirements = request.requirements();
1779        assert!(
1780            requirements
1781                .input_modalities()
1782                .contains(ModelModality::Text)
1783        );
1784        assert!(
1785            requirements
1786                .output_modalities()
1787                .contains(ModelModality::Text)
1788        );
1789        assert!(!requirements.requires_streaming());
1790        assert!(!requirements.tools().requires_tool_calling());
1791        assert_eq!(
1792            requirements.structured_output(),
1793            ModelStructuredOutputLevel::Unsupported
1794        );
1795        assert!(!requirements.requires_reasoning_summaries());
1796        assert_eq!(
1797            requirements.min_context_tokens(),
1798            Some(TokenCount::new(9_216))
1799        );
1800        assert_eq!(
1801            requirements.min_input_tokens(),
1802            Some(TokenCount::new(8_192))
1803        );
1804        assert_eq!(
1805            requirements.min_output_tokens(),
1806            Some(TokenCount::new(1_024))
1807        );
1808        assert!(request.content_bytes().get() > 0);
1809
1810        let encoded = to_value(&request).unwrap();
1811        assert_eq!(from_value::<ModelRequest>(encoded).unwrap(), request);
1812        let debug = format!("{request:?}");
1813        assert!(!debug.contains("Return a typed incident summary"));
1814        assert!(!debug.contains("Investigate incident 42"));
1815    }
1816
1817    #[test]
1818    fn tools_are_canonical_and_derive_exact_selection_requirements() {
1819        let selected = CapabilityName::new("alpha.lookup").unwrap();
1820        let request = base_builder()
1821            .tool(tool("zeta.lookup"))
1822            .tool(tool("alpha.lookup"))
1823            .tool_selection(ModelToolSelection::specific(selected.clone()))
1824            .max_tool_calls_per_response(ExecutionCount::new(4))
1825            .strict_tool_arguments(true)
1826            .build()
1827            .unwrap();
1828
1829        let names = request
1830            .tools()
1831            .map(|descriptor| {
1832                descriptor
1833                    .metadata()
1834                    .identity()
1835                    .capability()
1836                    .name()
1837                    .as_str()
1838            })
1839            .collect::<Vec<_>>();
1840        assert_eq!(names, ["alpha.lookup", "zeta.lookup"]);
1841        assert!(request.tool(&selected).is_some());
1842        let requirements = request.requirements().tools();
1843        assert_eq!(requirements.min_definitions(), ExecutionCount::new(2));
1844        assert_eq!(
1845            requirements.min_calls_per_response(),
1846            ExecutionCount::new(4)
1847        );
1848        assert!(requirements.choices().contains(ModelToolChoice::Specific));
1849        assert!(requirements.requires_strict_arguments());
1850    }
1851
1852    #[test]
1853    fn disabled_tools_retain_definitions_and_require_explicit_provider_support() {
1854        let request = base_builder()
1855            .tool(tool("payments.capture"))
1856            .build()
1857            .unwrap();
1858        assert_eq!(request.tools().len(), 1);
1859        assert_eq!(request.max_tool_calls_per_response(), ExecutionCount::ZERO);
1860        assert!(
1861            request
1862                .requirements()
1863                .tools()
1864                .choices()
1865                .contains(ModelToolChoice::None)
1866        );
1867        assert_eq!(
1868            request.requirements().tools().min_definitions(),
1869            ExecutionCount::new(1)
1870        );
1871        assert_eq!(
1872            request.requirements().tools().min_calls_per_response(),
1873            ExecutionCount::ZERO
1874        );
1875        let wire = serde_json::to_value(&request).unwrap();
1876        assert_eq!(
1877            serde_json::from_value::<ModelRequest>(wire.clone()).unwrap(),
1878            request
1879        );
1880        let mut tampered = wire;
1881        tampered["max_tool_calls_per_response"] = serde_json::json!("1");
1882        assert!(serde_json::from_value::<ModelRequest>(tampered).is_err());
1883        assert_eq!(
1884            base_builder()
1885                .tool(tool("payments.capture"))
1886                .strict_tool_arguments(true)
1887                .build(),
1888            Err(ModelRequestError::DisabledToolControls)
1889        );
1890    }
1891
1892    #[test]
1893    fn tool_controls_and_registry_names_fail_closed() {
1894        assert_eq!(
1895            base_builder()
1896                .tool_selection(ModelToolSelection::auto())
1897                .build(),
1898            Err(ModelRequestError::ToolSelectionWithoutTools {
1899                selection: ModelToolChoice::Auto,
1900            })
1901        );
1902        assert_eq!(
1903            base_builder()
1904                .max_tool_calls_per_response(ExecutionCount::new(1))
1905                .build(),
1906            Err(ModelRequestError::ToolCallsWithoutTools {
1907                actual: ExecutionCount::new(1),
1908            })
1909        );
1910        assert_eq!(
1911            base_builder().strict_tool_arguments(true).build(),
1912            Err(ModelRequestError::StrictArgumentsWithoutTools)
1913        );
1914        assert_eq!(
1915            base_builder()
1916                .tool(tool("payments.capture"))
1917                .max_tool_calls_per_response(ExecutionCount::new(1))
1918                .build(),
1919            Err(ModelRequestError::DisabledToolControls)
1920        );
1921        assert_eq!(
1922            base_builder()
1923                .tool(tool("payments.capture"))
1924                .tool_selection(ModelToolSelection::auto())
1925                .build(),
1926            Err(ModelRequestError::ZeroToolCalls)
1927        );
1928        assert_eq!(
1929            base_builder()
1930                .tool(tool("payments.capture"))
1931                .tool_selection(ModelToolSelection::auto())
1932                .max_tool_calls_per_response(ExecutionCount::new(1_025))
1933                .build(),
1934            Err(ModelRequestError::TooManyToolCalls {
1935                maximum: ModelRequest::MAX_TOOL_CALLS_PER_RESPONSE,
1936                actual: ExecutionCount::new(1_025),
1937            })
1938        );
1939
1940        let missing = CapabilityName::new("missing.tool").unwrap();
1941        assert_eq!(
1942            base_builder()
1943                .tool(tool("payments.capture"))
1944                .tool_selection(ModelToolSelection::specific(missing.clone()))
1945                .max_tool_calls_per_response(ExecutionCount::new(1))
1946                .build(),
1947            Err(ModelRequestError::SpecificToolNotFound { name: missing })
1948        );
1949        assert_eq!(
1950            base_builder()
1951                .tool(tool("payments.capture"))
1952                .tool(tool("payments.capture"))
1953                .build(),
1954            Err(ModelRequestError::DuplicateToolName {
1955                name: CapabilityName::new("payments.capture").unwrap(),
1956            })
1957        );
1958        assert_eq!(
1959            base_builder().tool(retired_tool("retired.tool")).build(),
1960            Err(ModelRequestError::RetiredTool {
1961                name: CapabilityName::new("retired.tool").unwrap(),
1962            })
1963        );
1964    }
1965
1966    #[test]
1967    fn output_controls_derive_structured_streaming_and_reasoning_requirements() {
1968        let schema = tool("payments.capture").input_schema().clone();
1969        let request = base_builder()
1970            .text_output_format(Some(ModelTextOutputFormat::json_schema(schema.clone())))
1971            .response_mode(ModelResponseMode::Streaming)
1972            .reasoning_summaries(true)
1973            .build()
1974            .unwrap();
1975        assert_eq!(
1976            request
1977                .text_output_format()
1978                .and_then(ModelTextOutputFormat::schema),
1979            Some(&schema)
1980        );
1981        assert!(request.requirements().requires_streaming());
1982        assert!(request.requirements().requires_reasoning_summaries());
1983        assert_eq!(
1984            request.requirements().structured_output(),
1985            ModelStructuredOutputLevel::JsonSchema
1986        );
1987
1988        assert_eq!(
1989            base_builder()
1990                .output_modalities(ModelModalities::empty())
1991                .text_output_format(None)
1992                .build(),
1993            Err(ModelRequestError::EmptyOutputModalities)
1994        );
1995        assert_eq!(
1996            base_builder().text_output_format(None).build(),
1997            Err(ModelRequestError::MissingTextOutputFormat)
1998        );
1999        assert_eq!(
2000            base_builder()
2001                .output_modalities(modalities([ModelModality::Image]))
2002                .build(),
2003            Err(ModelRequestError::UnexpectedTextOutputFormat)
2004        );
2005
2006        let image = base_builder()
2007            .output_modalities(modalities([ModelModality::Image]))
2008            .text_output_format(None)
2009            .build()
2010            .unwrap();
2011        assert_eq!(image.text_output_format(), None);
2012        assert!(
2013            image
2014                .requirements()
2015                .output_modalities()
2016                .contains(ModelModality::Image)
2017        );
2018    }
2019
2020    #[test]
2021    fn duplicate_inputs_and_request_content_limits_are_enforced() {
2022        let duplicate_instruction = instruction();
2023        assert_eq!(
2024            ModelRequest::builder(limits())
2025                .instruction(duplicate_instruction.clone())
2026                .instruction(duplicate_instruction.clone())
2027                .build(),
2028            Err(ModelRequestError::DuplicateInstruction {
2029                identity: duplicate_instruction.identity().clone(),
2030            })
2031        );
2032
2033        let duplicate_message = message();
2034        assert_eq!(
2035            ModelRequest::builder(limits())
2036                .message(duplicate_message.clone())
2037                .message(duplicate_message.clone())
2038                .build(),
2039            Err(ModelRequestError::DuplicateMessage {
2040                message_id: duplicate_message.message_id(),
2041            })
2042        );
2043
2044        let tiny =
2045            ModelRequestLimits::new(TokenCount::new(1), TokenCount::new(1), ByteCount::new(1))
2046                .unwrap();
2047        assert!(matches!(
2048            ModelRequest::builder(tiny)
2049                .instruction(instruction())
2050                .build(),
2051            Err(ModelRequestError::RequestContentTooLarge { .. })
2052        ));
2053        assert_eq!(
2054            ModelRequest::builder(limits()).build(),
2055            Err(ModelRequestError::EmptyInput)
2056        );
2057    }
2058
2059    #[test]
2060    fn collection_count_ceilings_stop_at_the_first_excess_value() {
2061        let instruction_wire = to_value(instruction()).unwrap();
2062        let mut instruction_builder = ModelRequest::builder(limits());
2063        for index in 0..=RequestInstructions::MAX_LEN {
2064            let mut value = instruction_wire.clone();
2065            value["identity"]["name"] = Value::from(format!("policy.{index}"));
2066            instruction_builder = instruction_builder.instruction(from_value(value).unwrap());
2067        }
2068        assert_eq!(
2069            instruction_builder.build(),
2070            Err(ModelRequestError::TooManyInstructions {
2071                max: RequestInstructions::MAX_LEN,
2072                observed: RequestInstructions::MAX_LEN + 1,
2073            })
2074        );
2075
2076        let message_wire = to_value(message()).unwrap();
2077        let mut message_builder = ModelRequest::builder(limits());
2078        for index in 0..=RequestMessages::MAX_LEN {
2079            let mut value = message_wire.clone();
2080            value["message_id"] = Value::from(format!("01912345-6789-7abc-8def-{index:012x}"));
2081            message_builder = message_builder.message(from_value(value).unwrap());
2082        }
2083        assert_eq!(
2084            message_builder.build(),
2085            Err(ModelRequestError::TooManyMessages {
2086                max: RequestMessages::MAX_LEN,
2087                observed: RequestMessages::MAX_LEN + 1,
2088            })
2089        );
2090
2091        let tool_wire = to_value(tool("bounded.tool")).unwrap();
2092        let mut tool_builder = base_builder();
2093        for index in 0..=RequestTools::MAX_LEN {
2094            let mut value = tool_wire.clone();
2095            value["metadata"]["identity"]["capability"]["name"] =
2096                Value::from(format!("tool.{index}"));
2097            tool_builder = tool_builder.tool(from_value(value).unwrap());
2098        }
2099        assert_eq!(
2100            tool_builder.build(),
2101            Err(ModelRequestError::TooManyTools {
2102                max: RequestTools::MAX_LEN,
2103                observed: RequestTools::MAX_LEN + 1,
2104            })
2105        );
2106    }
2107
2108    #[test]
2109    fn artifact_modalities_and_resolved_byte_bounds_fail_closed() {
2110        for (artifact_modality, model_modality) in [
2111            (ArtifactModality::Text, ModelModality::Text),
2112            (ArtifactModality::Image, ModelModality::Image),
2113            (ArtifactModality::Audio, ModelModality::Audio),
2114            (ArtifactModality::Video, ModelModality::Video),
2115            (ArtifactModality::Document, ModelModality::Document),
2116        ] {
2117            let request = ModelRequest::builder(limits())
2118                .message(message_artifact(artifact_modality, ByteCount::new(12)))
2119                .build()
2120                .unwrap();
2121            assert!(
2122                request
2123                    .requirements()
2124                    .input_modalities()
2125                    .contains(model_modality)
2126            );
2127        }
2128
2129        for modality in [
2130            ArtifactModality::StructuredData,
2131            ArtifactModality::Archive,
2132            ArtifactModality::Binary,
2133        ] {
2134            assert!(matches!(
2135                ModelRequest::builder(limits())
2136                    .message(message_artifact(modality, ByteCount::new(12)))
2137                    .build(),
2138                Err(ModelRequestError::UnsupportedMessageArtifact {
2139                    message_index: 0,
2140                    part_index: 0,
2141                    modality: actual,
2142                }) if actual == modality
2143            ));
2144        }
2145
2146        assert_eq!(
2147            ModelRequest::builder(limits())
2148                .instruction(instruction_artifact(
2149                    ArtifactModality::Image,
2150                    ByteCount::new(12),
2151                ))
2152                .build(),
2153            Err(ModelRequestError::UnsupportedInstructionArtifact {
2154                index: 0,
2155                modality: ArtifactModality::Image,
2156            })
2157        );
2158        assert!(matches!(
2159            ModelRequest::builder(limits())
2160                .instruction(instruction_artifact(
2161                    ArtifactModality::Text,
2162                    ByteCount::new(RequestInstructions::MAX_CONTENT_BYTES.get() + 1),
2163                ))
2164                .build(),
2165            Err(ModelRequestError::InstructionContentTooLarge { .. })
2166        ));
2167        assert!(matches!(
2168            ModelRequest::builder(limits())
2169                .message(message_artifact(
2170                    ArtifactModality::Document,
2171                    ByteCount::new(RequestMessages::MAX_CONTENT_BYTES.get() + 1),
2172                ))
2173                .build(),
2174            Err(ModelRequestError::MessageContentTooLarge { .. })
2175        ));
2176    }
2177
2178    #[test]
2179    fn derived_wire_requirements_and_closed_fields_cannot_be_tampered() {
2180        let request = base_request();
2181        let mut tampered = to_value(&request).unwrap();
2182        tampered["requirements"]["streaming"] = Value::Bool(true);
2183        assert!(from_value::<ModelRequest>(tampered).is_err());
2184
2185        let mut unknown = to_value(&request).unwrap();
2186        unknown["store"] = Value::Bool(true);
2187        assert!(from_value::<ModelRequest>(unknown).is_err());
2188
2189        let encoded = serde_json::to_string(&request).unwrap();
2190        let duplicate = encoded.replacen(
2191            "\"response_mode\":\"complete\"",
2192            "\"response_mode\":\"complete\",\"response_mode\":\"streaming\"",
2193            1,
2194        );
2195        assert_ne!(duplicate, encoded);
2196        assert!(serde_json::from_str::<ModelRequest>(&duplicate).is_err());
2197    }
2198
2199    #[test]
2200    fn request_schemas_publish_closed_objects_and_resource_bounds() {
2201        for schema in [
2202            to_value(schemars::schema_for!(ModelRequestLimits)).unwrap(),
2203            to_value(schemars::schema_for!(ModelRequest)).unwrap(),
2204        ] {
2205            assert_eq!(schema["type"], "object");
2206            assert_eq!(schema["additionalProperties"], false);
2207        }
2208
2209        let request = to_value(schemars::schema_for!(ModelRequest)).unwrap();
2210        let definitions = request["$defs"].as_object().unwrap();
2211        assert_eq!(
2212            definitions["ModelRequestInstructions"]["maxItems"],
2213            RequestInstructions::MAX_LEN
2214        );
2215        assert_eq!(
2216            definitions["ModelRequestMessages"]["maxItems"],
2217            RequestMessages::MAX_LEN
2218        );
2219        assert_eq!(
2220            definitions["ModelRequestTools"]["maxItems"],
2221            RequestTools::MAX_LEN
2222        );
2223    }
2224
2225    proptest! {
2226        #[test]
2227        fn every_valid_request_limit_tuple_and_derived_request_round_trip(
2228            input in 1_u64..=1_000_000,
2229            output in 1_u64..=1_000_000,
2230            bytes in 1_u64..=ModelRequestLimits::HARD_MAX_CONTENT_BYTES.get(),
2231        ) {
2232            let limits = ModelRequestLimits::new(
2233                TokenCount::new(input),
2234                TokenCount::new(output),
2235                ByteCount::new(bytes),
2236            ).unwrap();
2237            let encoded = serde_json::to_vec(&limits).unwrap();
2238            prop_assert_eq!(
2239                serde_json::from_slice::<ModelRequestLimits>(&encoded).unwrap(),
2240                limits.clone()
2241            );
2242            prop_assert_eq!(limits.required_context_tokens(), TokenCount::new(input + output));
2243
2244            if bytes >= 31 {
2245                let request = ModelRequest::builder(limits).instruction(instruction()).build().unwrap();
2246                let encoded = serde_json::to_vec(&request).unwrap();
2247                prop_assert_eq!(serde_json::from_slice::<ModelRequest>(&encoded).unwrap(), request);
2248            }
2249        }
2250    }
2251}