Skip to main content

stateknot_core/
model_response.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Bounded, provider-neutral model response contracts.
5
6use std::{borrow::Borrow, collections::BTreeSet, fmt, str::FromStr};
7
8use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
9use serde::{
10    Deserialize, Deserializer, Serialize, Serializer,
11    de::{self, SeqAccess},
12};
13use thiserror::Error;
14
15use crate::{
16    ArtifactModality, AttemptId, BoundedJson, ByteCount, CapabilityIdentity, CapabilityName,
17    ContentPart, ContentSource, ContentTrust, ExecutionCount, Extensions, JsonContent,
18    ModelDescriptor, ModelModality, ModelProviderReplay, ModelRequest, ModelTextOutputFormat,
19    ModelToolSelection, SchemaReference, TextContent, TokenCount,
20};
21
22const MEBIBYTE: u64 = 1024 * 1024;
23const PROVIDER_IDENTIFIER_PATTERN: &str = "^[!-~]+$";
24
25/// Validation failure for an opaque provider identifier.
26#[derive(Clone, Debug, Eq, Error, PartialEq)]
27#[non_exhaustive]
28pub enum ModelProviderIdentifierError {
29    /// The identifier contained no bytes.
30    #[error("model provider identifier must not be empty")]
31    Empty,
32    /// The identifier exceeded the immutable byte ceiling.
33    #[error("model provider identifier is {actual} bytes; maximum is {max}")]
34    TooLong {
35        /// Maximum accepted encoded length.
36        max: usize,
37        /// Observed encoded length.
38        actual: usize,
39    },
40    /// The identifier contained whitespace, a control, or non-ASCII data.
41    #[error("model provider identifier contains an invalid byte at offset {index}")]
42    InvalidByte {
43        /// Zero-based byte offset of the first invalid byte.
44        index: usize,
45    },
46}
47
48fn validate_provider_identifier(
49    value: &str,
50    maximum: usize,
51) -> Result<(), ModelProviderIdentifierError> {
52    if value.is_empty() {
53        return Err(ModelProviderIdentifierError::Empty);
54    }
55    if value.len() > maximum {
56        return Err(ModelProviderIdentifierError::TooLong {
57            max: maximum,
58            actual: value.len(),
59        });
60    }
61    if let Some((index, _)) = value
62        .bytes()
63        .enumerate()
64        .find(|(_, byte)| !(b'!'..=b'~').contains(byte))
65    {
66        return Err(ModelProviderIdentifierError::InvalidByte { index });
67    }
68    Ok(())
69}
70
71macro_rules! define_provider_identifier {
72    ($name:ident, $visitor:ident, $schema_name:literal, $documentation:literal) => {
73        #[doc = $documentation]
74        ///
75        /// The exact visible-ASCII value is retained without trimming or
76        /// normalization and redacted from `Debug` output.
77        #[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
78        pub struct $name(Box<str>);
79
80        impl $name {
81            /// Maximum encoded identifier length in bytes.
82            pub const MAX_BYTES: usize = 512;
83
84            /// Validates and constructs an identifier without copying an owned string.
85            ///
86            /// # Errors
87            ///
88            /// Returns [`ModelProviderIdentifierError`] when the value is empty,
89            /// oversized, or not entirely visible ASCII without spaces.
90            pub fn new(value: impl Into<String>) -> Result<Self, ModelProviderIdentifierError> {
91                let value = value.into();
92                validate_provider_identifier(&value, Self::MAX_BYTES)?;
93                Ok(Self(value.into_boxed_str()))
94            }
95
96            /// Returns the exact provider value.
97            #[must_use]
98            pub fn as_str(&self) -> &str {
99                &self.0
100            }
101
102            /// Returns the encoded length without disclosing the identifier.
103            #[must_use]
104            pub fn len_bytes(&self) -> usize {
105                self.0.len()
106            }
107        }
108
109        impl AsRef<str> for $name {
110            fn as_ref(&self) -> &str {
111                self.as_str()
112            }
113        }
114
115        impl Borrow<str> for $name {
116            fn borrow(&self) -> &str {
117                self.as_str()
118            }
119        }
120
121        impl fmt::Debug for $name {
122            fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
123                formatter
124                    .debug_struct(stringify!($name))
125                    .field("bytes", &self.len_bytes())
126                    .finish_non_exhaustive()
127            }
128        }
129
130        impl FromStr for $name {
131            type Err = ModelProviderIdentifierError;
132
133            fn from_str(value: &str) -> Result<Self, Self::Err> {
134                Self::new(value)
135            }
136        }
137
138        impl TryFrom<String> for $name {
139            type Error = ModelProviderIdentifierError;
140
141            fn try_from(value: String) -> Result<Self, Self::Error> {
142                Self::new(value)
143            }
144        }
145
146        impl TryFrom<&str> for $name {
147            type Error = ModelProviderIdentifierError;
148
149            fn try_from(value: &str) -> Result<Self, Self::Error> {
150                Self::new(value)
151            }
152        }
153
154        impl Serialize for $name {
155            fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
156            where
157                S: Serializer,
158            {
159                serializer.serialize_str(self.as_str())
160            }
161        }
162
163        impl<'de> Deserialize<'de> for $name {
164            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
165            where
166                D: Deserializer<'de>,
167            {
168                deserializer.deserialize_string($visitor)
169            }
170        }
171
172        struct $visitor;
173
174        impl de::Visitor<'_> for $visitor {
175            type Value = $name;
176
177            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
178                formatter.write_str("an opaque visible-ASCII model provider identifier")
179            }
180
181            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
182            where
183                E: de::Error,
184            {
185                $name::try_from(value).map_err(E::custom)
186            }
187
188            fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
189            where
190                E: de::Error,
191            {
192                $name::try_from(value).map_err(E::custom)
193            }
194        }
195
196        impl JsonSchema for $name {
197            fn schema_name() -> std::borrow::Cow<'static, str> {
198                $schema_name.into()
199            }
200
201            fn schema_id() -> std::borrow::Cow<'static, str> {
202                concat!(module_path!(), "::", $schema_name).into()
203            }
204
205            fn json_schema(_: &mut SchemaGenerator) -> Schema {
206                json_schema!({
207                    "type": "string",
208                    "minLength": 1,
209                    "maxLength": 512,
210                    "pattern": PROVIDER_IDENTIFIER_PATTERN
211                })
212            }
213
214            fn inline_schema() -> bool {
215                true
216            }
217        }
218    };
219}
220
221define_provider_identifier!(
222    ModelProviderModelId,
223    ModelProviderModelIdVisitor,
224    "ModelProviderModelId",
225    "An opaque model identifier reported by the selected provider binding."
226);
227define_provider_identifier!(
228    ModelProviderRequestId,
229    ModelProviderRequestIdVisitor,
230    "ModelProviderRequestId",
231    "An opaque request correlation identifier reported or recognized by a model provider."
232);
233define_provider_identifier!(
234    ModelProviderResponseId,
235    ModelProviderResponseIdVisitor,
236    "ModelProviderResponseId",
237    "An opaque response identifier reported by a model provider."
238);
239define_provider_identifier!(
240    ModelProviderToolCallId,
241    ModelProviderToolCallIdVisitor,
242    "ModelProviderToolCallId",
243    "An opaque provider correlation identifier for one proposed tool call."
244);
245
246/// Portable reason why model generation stopped.
247///
248/// Adapters must reject unknown, malformed, cancelled, or failed provider
249/// terminal states instead of mapping them to a successful response.
250#[derive(
251    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
252)]
253#[non_exhaustive]
254#[serde(rename_all = "snake_case")]
255pub enum ModelFinishReason {
256    /// Normal generation completed without an executable tool proposal.
257    Completed,
258    /// Generation yielded one or more complete tool-call proposals.
259    ToolCalls,
260    /// The configured generated-output limit ended generation.
261    OutputLimit,
262    /// The provider's model context limit ended generation.
263    ContextLimit,
264    /// The model explicitly refused the request.
265    Refused,
266    /// Provider safety, policy, or guardrail filtering stopped generation.
267    ContentFiltered,
268    /// The provider requires a continuation before a final result is available.
269    Paused,
270}
271
272/// Stable and provider-reported identity for one model attempt response.
273///
274/// Provider identifiers are diagnostic correlation values, not registry keys,
275/// authorization claims, or safe replay tokens.
276#[derive(Clone, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
277#[serde(deny_unknown_fields)]
278pub struct ModelResponseProvenance {
279    attempt_id: AttemptId,
280    model: CapabilityIdentity,
281    #[serde(skip_serializing_if = "Option::is_none")]
282    provider_model_id: Option<ModelProviderModelId>,
283    #[serde(skip_serializing_if = "Option::is_none")]
284    provider_request_id: Option<ModelProviderRequestId>,
285    #[serde(skip_serializing_if = "Option::is_none")]
286    provider_response_id: Option<ModelProviderResponseId>,
287}
288
289impl ModelResponseProvenance {
290    /// Constructs response provenance from validated components.
291    #[must_use]
292    pub fn new(
293        attempt_id: AttemptId,
294        model: CapabilityIdentity,
295        provider_model_id: Option<ModelProviderModelId>,
296        provider_response_id: Option<ModelProviderResponseId>,
297    ) -> Self {
298        Self {
299            attempt_id,
300            model,
301            provider_model_id,
302            provider_request_id: None,
303            provider_response_id,
304        }
305    }
306
307    /// Attaches the provider's request-correlation identifier.
308    ///
309    /// This value is diagnostic evidence only. It is not an authorization,
310    /// replay, deduplication, or idempotency key.
311    #[must_use]
312    pub fn with_provider_request_id(mut self, provider_request_id: ModelProviderRequestId) -> Self {
313        self.provider_request_id = Some(provider_request_id);
314        self
315    }
316
317    /// Returns the exact execution-attempt identifier.
318    #[must_use]
319    pub const fn attempt_id(&self) -> AttemptId {
320        self.attempt_id
321    }
322
323    /// Returns the stable, owner-qualified model identity.
324    #[must_use]
325    pub const fn model(&self) -> &CapabilityIdentity {
326        &self.model
327    }
328
329    /// Returns the optional opaque provider model identifier.
330    #[must_use]
331    pub const fn provider_model_id(&self) -> Option<&ModelProviderModelId> {
332        self.provider_model_id.as_ref()
333    }
334
335    /// Returns the optional opaque provider request identifier.
336    #[must_use]
337    pub const fn provider_request_id(&self) -> Option<&ModelProviderRequestId> {
338        self.provider_request_id.as_ref()
339    }
340
341    /// Returns the optional opaque provider response identifier.
342    #[must_use]
343    pub const fn provider_response_id(&self) -> Option<&ModelProviderResponseId> {
344        self.provider_response_id.as_ref()
345    }
346}
347
348impl fmt::Debug for ModelResponseProvenance {
349    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
350        formatter
351            .debug_struct("ModelResponseProvenance")
352            .field("attempt_id", &self.attempt_id)
353            .field("model", &self.model)
354            .field("provider_model_id", &self.provider_model_id)
355            .field("provider_request_id", &self.provider_request_id)
356            .field("provider_response_id", &self.provider_response_id)
357            .finish_non_exhaustive()
358    }
359}
360
361/// Normalized token accounting for exactly one model attempt.
362///
363/// Input and output counts are inclusive. A present cached-input count is a
364/// subset of input; a present reasoning count is a subset of output. Missing
365/// optional breakdowns mean the provider did not report them and must never be
366/// converted to zero. Adapters normalize Anthropic cache categories into input
367/// and Gemini thought tokens into output before construction.
368#[allow(clippy::struct_field_names)]
369#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
370#[serde(deny_unknown_fields)]
371pub struct ModelUsage {
372    input_tokens: TokenCount,
373    #[serde(skip_serializing_if = "Option::is_none")]
374    cached_input_tokens: Option<TokenCount>,
375    output_tokens: TokenCount,
376    #[serde(skip_serializing_if = "Option::is_none")]
377    reasoning_tokens: Option<TokenCount>,
378}
379
380impl ModelUsage {
381    /// Constructs normalized usage and validates inclusive-subset arithmetic.
382    ///
383    /// # Errors
384    ///
385    /// Returns [`ModelUsageError`] when a reported breakdown exceeds its
386    /// inclusive total or input plus output overflows.
387    pub const fn new(
388        input_tokens: TokenCount,
389        cached_input_tokens: Option<TokenCount>,
390        output_tokens: TokenCount,
391        reasoning_tokens: Option<TokenCount>,
392    ) -> Result<Self, ModelUsageError> {
393        if let Some(cached) = cached_input_tokens {
394            if cached.get() > input_tokens.get() {
395                return Err(ModelUsageError::CachedInputExceedsInput {
396                    input_tokens,
397                    cached_input_tokens: cached,
398                });
399            }
400        }
401        if let Some(reasoning) = reasoning_tokens {
402            if reasoning.get() > output_tokens.get() {
403                return Err(ModelUsageError::ReasoningExceedsOutput {
404                    output_tokens,
405                    reasoning_tokens: reasoning,
406                });
407            }
408        }
409        if input_tokens.checked_add(output_tokens).is_none() {
410            return Err(ModelUsageError::TotalTokensOverflow);
411        }
412        Ok(Self {
413            input_tokens,
414            cached_input_tokens,
415            output_tokens,
416            reasoning_tokens,
417        })
418    }
419
420    /// Returns inclusive normalized input tokens.
421    #[must_use]
422    pub const fn input_tokens(&self) -> TokenCount {
423        self.input_tokens
424    }
425
426    /// Returns the provider-reported cached-input subset when available.
427    #[must_use]
428    pub const fn cached_input_tokens(&self) -> Option<TokenCount> {
429        self.cached_input_tokens
430    }
431
432    /// Returns inclusive normalized generated-output tokens.
433    #[must_use]
434    pub const fn output_tokens(&self) -> TokenCount {
435        self.output_tokens
436    }
437
438    /// Returns the provider-reported reasoning subset when available.
439    #[must_use]
440    pub const fn reasoning_tokens(&self) -> Option<TokenCount> {
441        self.reasoning_tokens
442    }
443
444    /// Returns checked input plus output tokens.
445    #[must_use]
446    pub fn total_tokens(&self) -> TokenCount {
447        self.input_tokens
448            .checked_add(self.output_tokens)
449            .expect("validated model usage cannot overflow")
450    }
451}
452
453#[derive(Deserialize)]
454#[serde(deny_unknown_fields)]
455#[allow(clippy::struct_field_names)]
456struct ModelUsageWire {
457    input_tokens: TokenCount,
458    #[serde(default)]
459    cached_input_tokens: Option<TokenCount>,
460    output_tokens: TokenCount,
461    #[serde(default)]
462    reasoning_tokens: Option<TokenCount>,
463}
464
465impl<'de> Deserialize<'de> for ModelUsage {
466    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
467    where
468        D: Deserializer<'de>,
469    {
470        let wire = ModelUsageWire::deserialize(deserializer)?;
471        Self::new(
472            wire.input_tokens,
473            wire.cached_input_tokens,
474            wire.output_tokens,
475            wire.reasoning_tokens,
476        )
477        .map_err(de::Error::custom)
478    }
479}
480
481/// Invalid normalized model-attempt usage.
482#[derive(Clone, Debug, Eq, Error, PartialEq)]
483#[non_exhaustive]
484pub enum ModelUsageError {
485    /// Cached input was larger than inclusive input.
486    #[error(
487        "cached input tokens {cached_input_tokens} exceed inclusive input tokens {input_tokens}"
488    )]
489    CachedInputExceedsInput {
490        /// Inclusive input total.
491        input_tokens: TokenCount,
492        /// Invalid cached-input subset.
493        cached_input_tokens: TokenCount,
494    },
495    /// Reasoning output was larger than inclusive output.
496    #[error("reasoning tokens {reasoning_tokens} exceed inclusive output tokens {output_tokens}")]
497    ReasoningExceedsOutput {
498        /// Inclusive output total.
499        output_tokens: TokenCount,
500        /// Invalid reasoning subset.
501        reasoning_tokens: TokenCount,
502    },
503    /// Inclusive input plus output could not be represented.
504    #[error("model usage input and output tokens overflow total tokens")]
505    TotalTokensOverflow,
506}
507
508/// A complete, unapproved tool-call proposal emitted by a model.
509///
510/// This value intentionally has no [`crate::InvocationId`]. Before assigning
511/// one, the runtime resolves the exact descriptor from the tenant registry,
512/// validates arguments against its digest-pinned schema, and applies policy,
513/// budget, approval, and ledger checks. The provider call identifier is only a
514/// correlation value; when absent, attempt ID plus ordered output index is the
515/// durable proposal identity.
516#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
517#[serde(deny_unknown_fields)]
518pub struct ModelToolCallProposal {
519    tool: CapabilityIdentity,
520    #[serde(skip_serializing_if = "Option::is_none")]
521    provider_call_id: Option<ModelProviderToolCallId>,
522    arguments: BoundedJson,
523    extensions: Extensions,
524}
525
526impl ModelToolCallProposal {
527    /// Constructs a structurally valid, unapproved proposal.
528    ///
529    /// # Errors
530    ///
531    /// Returns [`ModelToolCallProposalError`] unless arguments are a JSON
532    /// object. This constructor does not perform tool-schema validation.
533    pub fn new(
534        tool: CapabilityIdentity,
535        provider_call_id: Option<ModelProviderToolCallId>,
536        arguments: BoundedJson,
537        extensions: Extensions,
538    ) -> Result<Self, ModelToolCallProposalError> {
539        if !arguments.as_value().is_object() {
540            return Err(ModelToolCallProposalError::ArgumentsMustBeObject);
541        }
542        Ok(Self {
543            tool,
544            provider_call_id,
545            arguments,
546            extensions,
547        })
548    }
549
550    /// Returns the exact requested tool identity claimed by the model adapter.
551    #[must_use]
552    pub const fn tool(&self) -> &CapabilityIdentity {
553        &self.tool
554    }
555
556    /// Returns the optional opaque provider correlation identifier.
557    #[must_use]
558    pub const fn provider_call_id(&self) -> Option<&ModelProviderToolCallId> {
559        self.provider_call_id.as_ref()
560    }
561
562    /// Returns bounded, untrusted JSON object arguments.
563    #[must_use]
564    pub const fn arguments(&self) -> &BoundedJson {
565        &self.arguments
566    }
567
568    /// Returns registered opaque provider/adapter extension data.
569    #[must_use]
570    pub const fn extensions(&self) -> &Extensions {
571        &self.extensions
572    }
573}
574
575impl fmt::Debug for ModelToolCallProposal {
576    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
577        formatter
578            .debug_struct("ModelToolCallProposal")
579            .field("tool", &self.tool)
580            .field("provider_call_id", &self.provider_call_id)
581            .field("arguments", &self.arguments)
582            .field("extensions", &self.extensions)
583            .finish_non_exhaustive()
584    }
585}
586
587#[derive(Deserialize)]
588#[serde(deny_unknown_fields)]
589struct ModelToolCallProposalWire {
590    tool: CapabilityIdentity,
591    #[serde(default)]
592    provider_call_id: Option<ModelProviderToolCallId>,
593    arguments: BoundedJson,
594    extensions: Extensions,
595}
596
597impl<'de> Deserialize<'de> for ModelToolCallProposal {
598    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
599    where
600        D: Deserializer<'de>,
601    {
602        let wire = ModelToolCallProposalWire::deserialize(deserializer)?;
603        Self::new(
604            wire.tool,
605            wire.provider_call_id,
606            wire.arguments,
607            wire.extensions,
608        )
609        .map_err(de::Error::custom)
610    }
611}
612
613/// Invalid model-produced tool-call proposal.
614#[derive(Clone, Debug, Eq, Error, PartialEq)]
615#[non_exhaustive]
616pub enum ModelToolCallProposalError {
617    /// Complete tool arguments were not a JSON object.
618    #[error("model tool-call arguments must be a JSON object")]
619    ArgumentsMustBeObject,
620}
621
622/// Classification of one ordered model output item.
623#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
624#[non_exhaustive]
625pub enum ModelOutputItemKind {
626    /// User-visible model content.
627    Content,
628    /// Human-readable reasoning summary, never hidden chain of thought.
629    ReasoningSummary,
630    /// Complete but unapproved tool-call proposal.
631    ToolCall,
632}
633
634/// One item in provider order from a model response.
635///
636/// Content and summaries must be marked untrusted. Inline text and JSON use a
637/// model source; artifact references retain their artifact source. These
638/// invariants are rechecked by [`ModelResponse`] even for directly constructed
639/// enum variants.
640#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
641#[serde(
642    tag = "type",
643    content = "content",
644    rename_all = "snake_case",
645    deny_unknown_fields
646)]
647pub enum ModelOutputItem {
648    /// User-visible model output content.
649    Content(ContentPart),
650    /// Provider-supplied readable reasoning summary.
651    ReasoningSummary(TextContent),
652    /// Complete, unapproved tool-call proposal.
653    ToolCall(Box<ModelToolCallProposal>),
654}
655
656impl ModelOutputItem {
657    /// Constructs model output content with strict source and trust metadata.
658    ///
659    /// # Errors
660    ///
661    /// Returns [`ModelOutputItemError`] for invalid source or trust metadata.
662    pub fn content(content: ContentPart) -> Result<Self, ModelOutputItemError> {
663        let item = Self::Content(content);
664        item.validate_intrinsic()?;
665        Ok(item)
666    }
667
668    /// Constructs a readable reasoning summary with strict model metadata.
669    ///
670    /// # Errors
671    ///
672    /// Returns [`ModelOutputItemError`] for invalid source or trust metadata.
673    pub fn reasoning_summary(summary: TextContent) -> Result<Self, ModelOutputItemError> {
674        let item = Self::ReasoningSummary(summary);
675        item.validate_intrinsic()?;
676        Ok(item)
677    }
678
679    /// Constructs an ordered tool-call proposal item.
680    #[must_use]
681    pub fn tool_call(proposal: ModelToolCallProposal) -> Self {
682        Self::ToolCall(Box::new(proposal))
683    }
684
685    /// Returns the closed item classification.
686    #[must_use]
687    pub const fn kind(&self) -> ModelOutputItemKind {
688        match self {
689            Self::Content(_) => ModelOutputItemKind::Content,
690            Self::ReasoningSummary(_) => ModelOutputItemKind::ReasoningSummary,
691            Self::ToolCall(_) => ModelOutputItemKind::ToolCall,
692        }
693    }
694
695    /// Returns user-visible content when this is a content item.
696    #[must_use]
697    pub const fn as_content(&self) -> Option<&ContentPart> {
698        match self {
699            Self::Content(content) => Some(content),
700            Self::ReasoningSummary(_) | Self::ToolCall(_) => None,
701        }
702    }
703
704    /// Returns readable reasoning text when this is a summary item.
705    #[must_use]
706    pub const fn as_reasoning_summary(&self) -> Option<&TextContent> {
707        match self {
708            Self::ReasoningSummary(summary) => Some(summary),
709            Self::Content(_) | Self::ToolCall(_) => None,
710        }
711    }
712
713    /// Returns the unapproved proposal when this is a tool-call item.
714    #[must_use]
715    pub const fn as_tool_call(&self) -> Option<&ModelToolCallProposal> {
716        match self {
717            Self::ToolCall(proposal) => Some(proposal),
718            Self::Content(_) | Self::ReasoningSummary(_) => None,
719        }
720    }
721
722    pub(crate) fn validate_intrinsic(&self) -> Result<(), ModelOutputItemError> {
723        match self {
724            Self::Content(content) => {
725                let expected_source = match content {
726                    ContentPart::Text(_) | ContentPart::Json(_) => ContentSource::Model,
727                    ContentPart::Artifact(_) => ContentSource::Artifact,
728                };
729                validate_output_metadata(self.kind(), content.metadata(), expected_source)
730            }
731            Self::ReasoningSummary(summary) => {
732                validate_output_metadata(self.kind(), summary.metadata(), ContentSource::Model)
733            }
734            Self::ToolCall(_) => Ok(()),
735        }
736    }
737
738    pub(crate) fn inline_payload_bytes(&self) -> usize {
739        match self {
740            Self::Content(content) => content.inline_payload_bytes(),
741            Self::ReasoningSummary(summary) => summary.text().len(),
742            Self::ToolCall(proposal) => {
743                proposal.arguments().stats().compact_bytes() + proposal.extensions().compact_bytes()
744            }
745        }
746    }
747}
748
749pub(crate) fn validate_output_metadata(
750    kind: ModelOutputItemKind,
751    metadata: &crate::ContentMetadata,
752    expected_source: ContentSource,
753) -> Result<(), ModelOutputItemError> {
754    if metadata.source() != expected_source {
755        return Err(ModelOutputItemError::InvalidSource {
756            kind,
757            expected: expected_source,
758            actual: metadata.source(),
759        });
760    }
761    if metadata.trust() != ContentTrust::Untrusted {
762        return Err(ModelOutputItemError::InvalidTrust {
763            kind,
764            actual: metadata.trust(),
765        });
766    }
767    Ok(())
768}
769
770impl fmt::Debug for ModelOutputItem {
771    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
772        match self {
773            Self::Content(content) => formatter
774                .debug_tuple("ModelOutputItem::Content")
775                .field(content)
776                .finish(),
777            Self::ReasoningSummary(summary) => formatter
778                .debug_tuple("ModelOutputItem::ReasoningSummary")
779                .field(summary)
780                .finish(),
781            Self::ToolCall(proposal) => formatter
782                .debug_tuple("ModelOutputItem::ToolCall")
783                .field(proposal)
784                .finish(),
785        }
786    }
787}
788
789#[derive(Deserialize)]
790#[serde(
791    tag = "type",
792    content = "content",
793    rename_all = "snake_case",
794    deny_unknown_fields
795)]
796enum ModelOutputItemWire {
797    Content(ContentPart),
798    ReasoningSummary(TextContent),
799    ToolCall(Box<ModelToolCallProposal>),
800}
801
802impl<'de> Deserialize<'de> for ModelOutputItem {
803    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
804    where
805        D: Deserializer<'de>,
806    {
807        let item = match ModelOutputItemWire::deserialize(deserializer)? {
808            ModelOutputItemWire::Content(content) => Self::Content(content),
809            ModelOutputItemWire::ReasoningSummary(summary) => Self::ReasoningSummary(summary),
810            ModelOutputItemWire::ToolCall(proposal) => Self::ToolCall(proposal),
811        };
812        item.validate_intrinsic().map_err(de::Error::custom)?;
813        Ok(item)
814    }
815}
816
817/// Invalid intrinsic metadata on an ordered model output item.
818#[derive(Clone, Debug, Eq, Error, PartialEq)]
819#[non_exhaustive]
820pub enum ModelOutputItemError {
821    /// Content was attributed to the wrong immediate domain source.
822    #[error("model output {kind:?} source must be {expected:?}, got {actual:?}")]
823    InvalidSource {
824        /// Output item classification.
825        kind: ModelOutputItemKind,
826        /// Required immediate source.
827        expected: ContentSource,
828        /// Rejected asserted source.
829        actual: ContentSource,
830    },
831    /// Model output was incorrectly marked application-controlled.
832    #[error("model output {kind:?} must be untrusted, got {actual:?}")]
833    InvalidTrust {
834        /// Output item classification.
835        kind: ModelOutputItemKind,
836        /// Rejected asserted trust.
837        actual: ContentTrust,
838    },
839}
840
841#[derive(Clone, Eq, PartialEq)]
842struct ModelOutputItems {
843    values: Box<[ModelOutputItem]>,
844    content_items: usize,
845    tool_calls: usize,
846    inline_payload_bytes: ByteCount,
847    modalities: crate::ModelModalities,
848}
849
850impl ModelOutputItems {
851    const MAX_CONTENT_ITEMS: usize = 256;
852    const MAX_TOOL_CALLS: usize = 1024;
853    const MAX_ITEMS: usize = Self::MAX_CONTENT_ITEMS + Self::MAX_TOOL_CALLS;
854    const MAX_INLINE_PAYLOAD_BYTES: ByteCount = ByteCount::new(64 * MEBIBYTE);
855
856    fn try_new<I>(values: I) -> Result<Self, ModelResponseError>
857    where
858        I: IntoIterator<Item = ModelOutputItem>,
859    {
860        let mut output = Vec::new();
861        let mut content_items = 0;
862        let mut tool_calls = 0;
863        let mut inline_payload_bytes = ByteCount::ZERO;
864        let mut modalities = BTreeSet::new();
865        let mut provider_call_ids = BTreeSet::new();
866        for value in values {
867            push_output_item(
868                &mut output,
869                &mut content_items,
870                &mut tool_calls,
871                &mut inline_payload_bytes,
872                &mut modalities,
873                &mut provider_call_ids,
874                value,
875            )?;
876        }
877        Ok(Self {
878            values: output.into_boxed_slice(),
879            content_items,
880            tool_calls,
881            inline_payload_bytes,
882            modalities: crate::ModelModalities::try_new(modalities)
883                .expect("closed output modality set is always valid"),
884        })
885    }
886
887    fn as_slice(&self) -> &[ModelOutputItem] {
888        &self.values
889    }
890}
891
892impl fmt::Debug for ModelOutputItems {
893    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
894        formatter
895            .debug_struct("ModelOutputItems")
896            .field("items", &self.values.len())
897            .field("content_items", &self.content_items)
898            .field("tool_calls", &self.tool_calls)
899            .field("inline_payload_bytes", &self.inline_payload_bytes)
900            .field("modalities", &self.modalities)
901            .finish_non_exhaustive()
902    }
903}
904
905impl Serialize for ModelOutputItems {
906    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
907    where
908        S: Serializer,
909    {
910        self.values.serialize(serializer)
911    }
912}
913
914impl<'de> Deserialize<'de> for ModelOutputItems {
915    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
916    where
917        D: Deserializer<'de>,
918    {
919        deserializer.deserialize_seq(ModelOutputItemsVisitor)
920    }
921}
922
923struct ModelOutputItemsVisitor;
924
925impl<'de> de::Visitor<'de> for ModelOutputItemsVisitor {
926    type Value = ModelOutputItems;
927
928    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
929        write!(
930            formatter,
931            "an ordered array containing at most {} bounded model output items",
932            ModelOutputItems::MAX_ITEMS
933        )
934    }
935
936    fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
937    where
938        A: SeqAccess<'de>,
939    {
940        let mut values = Vec::with_capacity(
941            sequence
942                .size_hint()
943                .unwrap_or_default()
944                .min(ModelOutputItems::MAX_ITEMS),
945        );
946        let mut content_items = 0;
947        let mut tool_calls = 0;
948        let mut inline_payload_bytes = ByteCount::ZERO;
949        let mut modalities = BTreeSet::new();
950        let mut provider_call_ids = BTreeSet::new();
951        while let Some(value) = sequence.next_element::<ModelOutputItem>()? {
952            push_output_item(
953                &mut values,
954                &mut content_items,
955                &mut tool_calls,
956                &mut inline_payload_bytes,
957                &mut modalities,
958                &mut provider_call_ids,
959                value,
960            )
961            .map_err(de::Error::custom)?;
962        }
963        Ok(ModelOutputItems {
964            values: values.into_boxed_slice(),
965            content_items,
966            tool_calls,
967            inline_payload_bytes,
968            modalities: crate::ModelModalities::try_new(modalities).map_err(de::Error::custom)?,
969        })
970    }
971}
972
973impl JsonSchema for ModelOutputItems {
974    fn schema_name() -> std::borrow::Cow<'static, str> {
975        "ModelResponseOutput".into()
976    }
977
978    fn schema_id() -> std::borrow::Cow<'static, str> {
979        concat!(module_path!(), "::ModelOutputItems").into()
980    }
981
982    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
983        json_schema!({
984            "type": "array",
985            "items": generator.subschema_for::<ModelOutputItem>(),
986            "maxItems": 1280,
987            "description": "Provider-ordered output. Runtime additionally permits at most 256 content/summary items, at most 1024 tool proposals, unique present provider call IDs, and at most 67108864 aggregate inline content, argument, and per-proposal extension bytes."
988        })
989    }
990}
991
992#[allow(clippy::too_many_arguments)]
993fn push_output_item(
994    values: &mut Vec<ModelOutputItem>,
995    content_items: &mut usize,
996    tool_calls: &mut usize,
997    inline_payload_bytes: &mut ByteCount,
998    modalities: &mut BTreeSet<ModelModality>,
999    provider_call_ids: &mut BTreeSet<ModelProviderToolCallId>,
1000    value: ModelOutputItem,
1001) -> Result<(), ModelResponseError> {
1002    if values.len() == ModelOutputItems::MAX_ITEMS {
1003        return Err(ModelResponseError::TooManyOutputItems {
1004            max: ModelOutputItems::MAX_ITEMS,
1005            observed: ModelOutputItems::MAX_ITEMS + 1,
1006        });
1007    }
1008    value
1009        .validate_intrinsic()
1010        .map_err(|error| ModelResponseError::InvalidOutputItem {
1011            index: values.len(),
1012            error,
1013        })?;
1014
1015    match &value {
1016        ModelOutputItem::Content(content) => {
1017            if *content_items == ModelOutputItems::MAX_CONTENT_ITEMS {
1018                return Err(ModelResponseError::TooManyContentItems {
1019                    max: ModelOutputItems::MAX_CONTENT_ITEMS,
1020                    observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
1021                });
1022            }
1023            *content_items += 1;
1024            let modality = content_modality(content).ok_or_else(|| {
1025                ModelResponseError::UnsupportedArtifactModality {
1026                    index: values.len(),
1027                    modality: match content {
1028                        ContentPart::Artifact(artifact) => artifact.representation().modality(),
1029                        ContentPart::Text(_) | ContentPart::Json(_) => {
1030                            unreachable!("inline content always has a portable modality")
1031                        }
1032                    },
1033                }
1034            })?;
1035            modalities.insert(modality);
1036        }
1037        ModelOutputItem::ReasoningSummary(_) => {
1038            if *content_items == ModelOutputItems::MAX_CONTENT_ITEMS {
1039                return Err(ModelResponseError::TooManyContentItems {
1040                    max: ModelOutputItems::MAX_CONTENT_ITEMS,
1041                    observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
1042                });
1043            }
1044            *content_items += 1;
1045        }
1046        ModelOutputItem::ToolCall(proposal) => {
1047            if *tool_calls == ModelOutputItems::MAX_TOOL_CALLS {
1048                return Err(ModelResponseError::TooManyToolCalls {
1049                    max: ModelOutputItems::MAX_TOOL_CALLS,
1050                    observed: ModelOutputItems::MAX_TOOL_CALLS + 1,
1051                });
1052            }
1053            if let Some(provider_call_id) = proposal.provider_call_id() {
1054                if !provider_call_ids.insert(provider_call_id.clone()) {
1055                    return Err(ModelResponseError::DuplicateProviderToolCallId);
1056                }
1057            }
1058            *tool_calls += 1;
1059        }
1060    }
1061
1062    let additional = ByteCount::new(value.inline_payload_bytes() as u64);
1063    let Some(observed) = inline_payload_bytes.checked_add(additional) else {
1064        return Err(ModelResponseError::InlinePayloadBytesOverflow);
1065    };
1066    if observed > ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES {
1067        return Err(ModelResponseError::InlinePayloadTooLarge {
1068            maximum: ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES,
1069            observed,
1070        });
1071    }
1072    *inline_payload_bytes = observed;
1073    values.push(value);
1074    Ok(())
1075}
1076
1077const fn content_modality(content: &ContentPart) -> Option<ModelModality> {
1078    match content {
1079        ContentPart::Text(_) | ContentPart::Json(_) => Some(ModelModality::Text),
1080        ContentPart::Artifact(artifact) => match artifact.representation().modality() {
1081            ArtifactModality::Text => Some(ModelModality::Text),
1082            ArtifactModality::Image => Some(ModelModality::Image),
1083            ArtifactModality::Audio => Some(ModelModality::Audio),
1084            ArtifactModality::Video => Some(ModelModality::Video),
1085            ArtifactModality::Document => Some(ModelModality::Document),
1086            ArtifactModality::StructuredData
1087            | ArtifactModality::Archive
1088            | ArtifactModality::Binary => None,
1089        },
1090    }
1091}
1092
1093/// Immutable, fully normalized result of one model attempt.
1094///
1095/// Deserialization enforces intrinsic resource, metadata, usage, and finish
1096/// invariants, but serialized model/tool identities remain unauthenticated
1097/// claims. Call [`Self::validate_for`] against the attempt's immutable descriptor
1098/// and request snapshot before consuming a durable or remote value. Adapter
1099/// code should prefer [`Self::new`], which performs both validation layers.
1100#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
1101#[serde(deny_unknown_fields)]
1102pub struct ModelResponse {
1103    provenance: ModelResponseProvenance,
1104    output: ModelOutputItems,
1105    finish_reason: ModelFinishReason,
1106    usage: ModelUsage,
1107    extensions: Extensions,
1108    #[serde(skip_serializing_if = "Option::is_none")]
1109    provider_replay: Option<ModelProviderReplay>,
1110}
1111
1112impl ModelResponse {
1113    /// Maximum user-visible content and reasoning-summary items in one response.
1114    pub const MAX_CONTENT_ITEMS: usize = ModelOutputItems::MAX_CONTENT_ITEMS;
1115    /// Maximum complete tool proposals in one response.
1116    pub const MAX_TOOL_CALLS: usize = ModelOutputItems::MAX_TOOL_CALLS;
1117    /// Maximum total ordered output items in one response.
1118    pub const MAX_OUTPUT_ITEMS: usize = ModelOutputItems::MAX_ITEMS;
1119    /// Maximum aggregate normalized output plus opaque provider replay bytes.
1120    pub const MAX_INLINE_PAYLOAD_BYTES: ByteCount = ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES;
1121
1122    /// Constructs and binds one response to an immutable descriptor and request.
1123    ///
1124    /// # Errors
1125    ///
1126    /// Returns [`ModelResponseError`] for any structural, resource, finish,
1127    /// capability-identity, request-limit, output-format, modality, or tool
1128    /// mismatch. Referenced JSON Schemas still require trusted registry
1129    /// resolution and validation by the adapter before construction.
1130    pub fn new<I>(
1131        provenance: ModelResponseProvenance,
1132        descriptor: &ModelDescriptor,
1133        request: &ModelRequest,
1134        output: I,
1135        finish_reason: ModelFinishReason,
1136        usage: ModelUsage,
1137        extensions: Extensions,
1138    ) -> Result<Self, ModelResponseError>
1139    where
1140        I: IntoIterator<Item = ModelOutputItem>,
1141    {
1142        let response = Self::from_parts(
1143            provenance,
1144            ModelOutputItems::try_new(output)?,
1145            finish_reason,
1146            usage,
1147            extensions,
1148        )?;
1149        response.validate_for(descriptor, request)?;
1150        Ok(response)
1151    }
1152
1153    fn from_parts(
1154        provenance: ModelResponseProvenance,
1155        output: ModelOutputItems,
1156        finish_reason: ModelFinishReason,
1157        usage: ModelUsage,
1158        extensions: Extensions,
1159    ) -> Result<Self, ModelResponseError> {
1160        match (finish_reason, output.tool_calls) {
1161            (ModelFinishReason::ToolCalls, 0) => {
1162                return Err(ModelResponseError::ToolCallsFinishRequiresProposal);
1163            }
1164            (ModelFinishReason::ToolCalls, _) => {}
1165            (reason, calls) if calls > 0 => {
1166                return Err(ModelResponseError::FinishForbidsToolCalls {
1167                    finish_reason: reason,
1168                    tool_calls: ExecutionCount::new(calls as u64),
1169                });
1170            }
1171            _ => {}
1172        }
1173        Ok(Self {
1174            provenance,
1175            output,
1176            finish_reason,
1177            usage,
1178            extensions,
1179            provider_replay: None,
1180        })
1181    }
1182
1183    /// Attaches exact provider continuation evidence to a tool-calling response.
1184    ///
1185    /// # Errors
1186    ///
1187    /// Returns [`ModelResponseError::ProviderReplayWithoutToolCalls`] when the
1188    /// response does not require a tool-result continuation.
1189    pub fn with_provider_replay(
1190        mut self,
1191        provider_replay: ModelProviderReplay,
1192    ) -> Result<Self, ModelResponseError> {
1193        if self.finish_reason != ModelFinishReason::ToolCalls {
1194            return Err(ModelResponseError::ProviderReplayWithoutToolCalls);
1195        }
1196        let observed = self
1197            .output
1198            .inline_payload_bytes
1199            .checked_add(provider_replay.payload_bytes())
1200            .ok_or(ModelResponseError::InlinePayloadBytesOverflow)?;
1201        if observed > Self::MAX_INLINE_PAYLOAD_BYTES {
1202            return Err(ModelResponseError::InlinePayloadTooLarge {
1203                maximum: Self::MAX_INLINE_PAYLOAD_BYTES,
1204                observed,
1205            });
1206        }
1207        self.provider_replay = Some(provider_replay);
1208        Ok(self)
1209    }
1210
1211    /// Revalidates request- and registry-dependent response invariants.
1212    ///
1213    /// # Errors
1214    ///
1215    /// Returns [`ModelResponseError`] when provenance, usage, output modality,
1216    /// reasoning summaries, final text format, or tool proposals do not match
1217    /// the exact descriptor and request snapshot.
1218    pub fn validate_for(
1219        &self,
1220        descriptor: &ModelDescriptor,
1221        request: &ModelRequest,
1222    ) -> Result<(), ModelResponseError> {
1223        let expected_model = descriptor.metadata().identity();
1224        if self.provenance.model() != expected_model {
1225            return Err(ModelResponseError::ModelIdentityMismatch {
1226                expected: Box::new(expected_model.clone()),
1227                actual: Box::new(self.provenance.model().clone()),
1228            });
1229        }
1230        if self.usage.input_tokens() > request.limits().max_input_tokens() {
1231            return Err(ModelResponseError::InputUsageExceedsRequest {
1232                maximum: request.limits().max_input_tokens(),
1233                actual: self.usage.input_tokens(),
1234            });
1235        }
1236        if self.usage.output_tokens() > request.limits().max_output_tokens() {
1237            return Err(ModelResponseError::OutputUsageExceedsRequest {
1238                maximum: request.limits().max_output_tokens(),
1239                actual: self.usage.output_tokens(),
1240            });
1241        }
1242
1243        for (index, item) in self.output.values.iter().enumerate() {
1244            match item {
1245                ModelOutputItem::Content(content) => {
1246                    let modality = content_modality(content).ok_or_else(|| {
1247                        ModelResponseError::UnsupportedArtifactModality {
1248                            index,
1249                            modality: match content {
1250                                ContentPart::Artifact(artifact) => {
1251                                    artifact.representation().modality()
1252                                }
1253                                ContentPart::Text(_) | ContentPart::Json(_) => {
1254                                    unreachable!("inline content always has a portable modality")
1255                                }
1256                            },
1257                        }
1258                    })?;
1259                    if !request.output_modalities().contains(modality) {
1260                        return Err(ModelResponseError::OutputModalityNotRequested {
1261                            index,
1262                            modality,
1263                        });
1264                    }
1265                }
1266                ModelOutputItem::ReasoningSummary(_) => {
1267                    if !request.requires_reasoning_summaries() {
1268                        return Err(ModelResponseError::ReasoningSummaryNotRequested { index });
1269                    }
1270                }
1271                ModelOutputItem::ToolCall(proposal) => {
1272                    validate_tool_proposal(index, proposal, request)?;
1273                }
1274            }
1275        }
1276
1277        let actual_calls = ExecutionCount::new(self.output.tool_calls as u64);
1278        if actual_calls > request.max_tool_calls_per_response() {
1279            return Err(ModelResponseError::ToolCallsExceedRequest {
1280                maximum: request.max_tool_calls_per_response(),
1281                actual: actual_calls,
1282            });
1283        }
1284
1285        if self.finish_reason == ModelFinishReason::Completed
1286            && matches!(
1287                request.tool_selection(),
1288                ModelToolSelection::Required {} | ModelToolSelection::Specific { .. }
1289            )
1290        {
1291            return Err(ModelResponseError::RequiredToolCallMissing);
1292        }
1293
1294        if self.finish_reason == ModelFinishReason::Completed {
1295            validate_completed_text_format(&self.output, request.text_output_format())?;
1296        }
1297        Ok(())
1298    }
1299
1300    /// Returns attempt and model identity provenance.
1301    #[must_use]
1302    pub const fn provenance(&self) -> &ModelResponseProvenance {
1303        &self.provenance
1304    }
1305
1306    /// Returns all output items in exact provider order.
1307    #[must_use]
1308    pub fn output(&self) -> &[ModelOutputItem] {
1309        self.output.as_slice()
1310    }
1311
1312    /// Iterates complete, unapproved tool-call proposals in provider order.
1313    pub fn tool_calls(&self) -> impl Iterator<Item = &ModelToolCallProposal> {
1314        self.output
1315            .values
1316            .iter()
1317            .filter_map(ModelOutputItem::as_tool_call)
1318    }
1319
1320    /// Returns the exact number of complete, unapproved tool proposals.
1321    #[must_use]
1322    pub const fn tool_call_count(&self) -> usize {
1323        self.output.tool_calls
1324    }
1325
1326    /// Returns the normalized portable finish reason.
1327    #[must_use]
1328    pub const fn finish_reason(&self) -> ModelFinishReason {
1329        self.finish_reason
1330    }
1331
1332    /// Returns normalized per-attempt token usage.
1333    #[must_use]
1334    pub const fn usage(&self) -> &ModelUsage {
1335        &self.usage
1336    }
1337
1338    /// Returns registered opaque provider/adapter extension values.
1339    #[must_use]
1340    pub const fn extensions(&self) -> &Extensions {
1341        &self.extensions
1342    }
1343
1344    /// Returns exact provider continuation evidence for a tool-calling turn.
1345    #[must_use]
1346    pub const fn provider_replay(&self) -> Option<&ModelProviderReplay> {
1347        self.provider_replay.as_ref()
1348    }
1349
1350    /// Returns aggregate normalized output and provider replay bytes retained.
1351    #[must_use]
1352    pub fn inline_payload_bytes(&self) -> ByteCount {
1353        self.provider_replay
1354            .as_ref()
1355            .map_or(self.output.inline_payload_bytes, |replay| {
1356                self.output
1357                    .inline_payload_bytes
1358                    .checked_add(replay.payload_bytes())
1359                    .expect("provider replay attachment validated byte accounting")
1360            })
1361    }
1362}
1363
1364impl fmt::Debug for ModelResponse {
1365    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1366        formatter
1367            .debug_struct("ModelResponse")
1368            .field("provenance", &self.provenance)
1369            .field("output", &self.output)
1370            .field("finish_reason", &self.finish_reason)
1371            .field("usage", &self.usage)
1372            .field("extensions", &self.extensions)
1373            .field("provider_replay", &self.provider_replay)
1374            .finish_non_exhaustive()
1375    }
1376}
1377
1378#[derive(Deserialize)]
1379#[serde(deny_unknown_fields)]
1380struct ModelResponseWire {
1381    provenance: ModelResponseProvenance,
1382    output: ModelOutputItems,
1383    finish_reason: ModelFinishReason,
1384    usage: ModelUsage,
1385    extensions: Extensions,
1386    #[serde(default)]
1387    provider_replay: Option<ModelProviderReplay>,
1388}
1389
1390impl<'de> Deserialize<'de> for ModelResponse {
1391    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1392    where
1393        D: Deserializer<'de>,
1394    {
1395        let wire = ModelResponseWire::deserialize(deserializer)?;
1396        let mut response = Self::from_parts(
1397            wire.provenance,
1398            wire.output,
1399            wire.finish_reason,
1400            wire.usage,
1401            wire.extensions,
1402        )
1403        .map_err(de::Error::custom)?;
1404        if let Some(provider_replay) = wire.provider_replay {
1405            response = response
1406                .with_provider_replay(provider_replay)
1407                .map_err(de::Error::custom)?;
1408        }
1409        Ok(response)
1410    }
1411}
1412
1413fn validate_tool_proposal(
1414    index: usize,
1415    proposal: &ModelToolCallProposal,
1416    request: &ModelRequest,
1417) -> Result<(), ModelResponseError> {
1418    let Some(expected) = request.tool(proposal.tool().name()) else {
1419        return Err(ModelResponseError::ToolNotRequested {
1420            index,
1421            tool: Box::new(proposal.tool().clone()),
1422        });
1423    };
1424    let expected_identity = expected.metadata().identity();
1425    if proposal.tool() != expected_identity {
1426        return Err(ModelResponseError::ToolIdentityMismatch {
1427            index,
1428            expected: Box::new(expected_identity.clone()),
1429            actual: Box::new(proposal.tool().clone()),
1430        });
1431    }
1432    if let ModelToolSelection::Specific { name } = request.tool_selection() {
1433        if proposal.tool().name() != name {
1434            return Err(ModelResponseError::SpecificToolMismatch {
1435                index,
1436                expected: name.clone(),
1437                actual: proposal.tool().name().clone(),
1438            });
1439        }
1440    }
1441    Ok(())
1442}
1443
1444fn validate_completed_text_format(
1445    output: &ModelOutputItems,
1446    format: Option<&ModelTextOutputFormat>,
1447) -> Result<(), ModelResponseError> {
1448    let Some(format) = format else {
1449        return Ok(());
1450    };
1451
1452    let textual = output
1453        .values
1454        .iter()
1455        .enumerate()
1456        .filter_map(|(index, item)| match item {
1457            ModelOutputItem::Content(ContentPart::Text(_)) => {
1458                Some((index, CompletedTextItem::Text))
1459            }
1460            ModelOutputItem::Content(ContentPart::Json(content)) => {
1461                Some((index, CompletedTextItem::Json(content)))
1462            }
1463            ModelOutputItem::Content(ContentPart::Artifact(artifact))
1464                if artifact.representation().modality() == ArtifactModality::Text =>
1465            {
1466                Some((index, CompletedTextItem::Artifact))
1467            }
1468            ModelOutputItem::Content(ContentPart::Artifact(_))
1469            | ModelOutputItem::ReasoningSummary(_)
1470            | ModelOutputItem::ToolCall(_) => None,
1471        })
1472        .collect::<Vec<_>>();
1473
1474    match format {
1475        ModelTextOutputFormat::Text {} => {
1476            if let Some((index, _)) = textual
1477                .iter()
1478                .find(|(_, item)| matches!(item, CompletedTextItem::Json(_)))
1479            {
1480                return Err(ModelResponseError::PlainTextCompletionContainsJson { index: *index });
1481            }
1482        }
1483        ModelTextOutputFormat::Json {} | ModelTextOutputFormat::JsonSchema { .. } => {
1484            if let Some((index, _)) = textual
1485                .iter()
1486                .find(|(_, item)| !matches!(item, CompletedTextItem::Json(_)))
1487            {
1488                return Err(ModelResponseError::StructuredCompletionContainsText { index: *index });
1489            }
1490            let json = textual
1491                .iter()
1492                .filter_map(|(index, item)| match item {
1493                    CompletedTextItem::Json(content) => Some((*index, *content)),
1494                    CompletedTextItem::Text | CompletedTextItem::Artifact => None,
1495                })
1496                .collect::<Vec<_>>();
1497            if json.len() != 1 {
1498                return Err(ModelResponseError::StructuredCompletionJsonCount {
1499                    actual: json.len(),
1500                });
1501            }
1502            let (index, content) = json[0];
1503            match format {
1504                ModelTextOutputFormat::Json {} if content.schema().is_some() => {
1505                    return Err(ModelResponseError::UnexpectedOutputSchema { index });
1506                }
1507                ModelTextOutputFormat::JsonSchema { schema }
1508                    if content.schema() != Some(schema) =>
1509                {
1510                    return Err(ModelResponseError::OutputSchemaMismatch {
1511                        index,
1512                        expected: Box::new(schema.clone()),
1513                        actual: content.schema().cloned().map(Box::new),
1514                    });
1515                }
1516                ModelTextOutputFormat::Json {}
1517                | ModelTextOutputFormat::JsonSchema { .. }
1518                | ModelTextOutputFormat::Text {} => {}
1519            }
1520        }
1521    }
1522    Ok(())
1523}
1524
1525enum CompletedTextItem<'a> {
1526    Text,
1527    Json(&'a JsonContent),
1528    Artifact,
1529}
1530
1531/// Invalid provider-neutral model response.
1532#[derive(Clone, Debug, Eq, Error, PartialEq)]
1533#[non_exhaustive]
1534pub enum ModelResponseError {
1535    /// The ordered output exceeded its total hard ceiling.
1536    #[error("model response contains at least {observed} output items; maximum is {max}")]
1537    TooManyOutputItems {
1538        /// Immutable v1 maximum.
1539        max: usize,
1540        /// Minimum count observed before validation stopped.
1541        observed: usize,
1542    },
1543    /// User-visible content plus summaries exceeded their hard ceiling.
1544    #[error("model response contains at least {observed} content items; maximum is {max}")]
1545    TooManyContentItems {
1546        /// Immutable v1 maximum.
1547        max: usize,
1548        /// Minimum count observed before validation stopped.
1549        observed: usize,
1550    },
1551    /// Tool proposals exceeded their hard ceiling.
1552    #[error("model response contains at least {observed} tool calls; maximum is {max}")]
1553    TooManyToolCalls {
1554        /// Immutable v1 maximum.
1555        max: usize,
1556        /// Minimum count observed before validation stopped.
1557        observed: usize,
1558    },
1559    /// An ordered item carried invalid intrinsic metadata.
1560    #[error("model response output item {index} is invalid: {error}")]
1561    InvalidOutputItem {
1562        /// Zero-based provider-order index.
1563        index: usize,
1564        /// Intrinsic item validation failure.
1565        error: ModelOutputItemError,
1566    },
1567    /// Two proposals carried the same present provider correlation identifier.
1568    #[error("model response provider tool-call identifiers must be unique when present")]
1569    DuplicateProviderToolCallId,
1570    /// Inline payload accounting could not be represented.
1571    #[error("model response inline payload-byte accounting overflowed")]
1572    InlinePayloadBytesOverflow,
1573    /// Aggregate retained inline payload exceeded the hard ceiling.
1574    #[error("model response inline payload is {observed} bytes; maximum is {maximum}")]
1575    InlinePayloadTooLarge {
1576        /// Immutable v1 maximum.
1577        maximum: ByteCount,
1578        /// First observed aggregate beyond the maximum.
1579        observed: ByteCount,
1580    },
1581    /// A tool-call terminal state had no complete proposal.
1582    #[error("model response tool_calls finish requires at least one complete proposal")]
1583    ToolCallsFinishRequiresProposal,
1584    /// Replay evidence was attached to a response that needs no tool continuation.
1585    #[error("model provider replay is only valid on a tool-calling response")]
1586    ProviderReplayWithoutToolCalls,
1587    /// A non-tool terminal state carried executable proposals.
1588    #[error("model response finish {finish_reason:?} forbids {tool_calls} tool calls")]
1589    FinishForbidsToolCalls {
1590        /// Rejected portable terminal state.
1591        finish_reason: ModelFinishReason,
1592        /// Number of complete proposals present.
1593        tool_calls: ExecutionCount,
1594    },
1595    /// An output artifact had no portable model modality.
1596    #[error("model response output item {index} has unsupported artifact modality {modality:?}")]
1597    UnsupportedArtifactModality {
1598        /// Zero-based provider-order index.
1599        index: usize,
1600        /// Rejected artifact modality.
1601        modality: ArtifactModality,
1602    },
1603    /// The response claimed a different stable model binding.
1604    #[error("model response identity {actual:?} does not match descriptor {expected:?}")]
1605    ModelIdentityMismatch {
1606        /// Exact immutable descriptor identity.
1607        expected: Box<CapabilityIdentity>,
1608        /// Rejected response claim.
1609        actual: Box<CapabilityIdentity>,
1610    },
1611    /// Provider input accounting exceeded the request ceiling.
1612    #[error("model response input usage {actual} exceeds request maximum {maximum}")]
1613    InputUsageExceedsRequest {
1614        /// Request input-token ceiling.
1615        maximum: TokenCount,
1616        /// Provider-reported normalized input.
1617        actual: TokenCount,
1618    },
1619    /// Provider output accounting exceeded the request ceiling.
1620    #[error("model response output usage {actual} exceeds request maximum {maximum}")]
1621    OutputUsageExceedsRequest {
1622        /// Request generated-output ceiling.
1623        maximum: TokenCount,
1624        /// Provider-reported normalized output.
1625        actual: TokenCount,
1626    },
1627    /// A user-visible output modality was not requested.
1628    #[error("model response output item {index} uses unrequested modality {modality:?}")]
1629    OutputModalityNotRequested {
1630        /// Zero-based provider-order index.
1631        index: usize,
1632        /// Unrequested modality.
1633        modality: ModelModality,
1634    },
1635    /// A reasoning summary was returned without explicit opt-in.
1636    #[error("model response output item {index} is an unrequested reasoning summary")]
1637    ReasoningSummaryNotRequested {
1638        /// Zero-based provider-order index.
1639        index: usize,
1640    },
1641    /// Tool-call count exceeded the request-specific ceiling.
1642    #[error("model response has {actual} tool calls; request maximum is {maximum}")]
1643    ToolCallsExceedRequest {
1644        /// Request-specific call ceiling.
1645        maximum: ExecutionCount,
1646        /// Complete proposal count.
1647        actual: ExecutionCount,
1648    },
1649    /// A proposal named no tool in the request snapshot.
1650    #[error("model response output item {index} proposes unrequested tool {tool:?}")]
1651    ToolNotRequested {
1652        /// Zero-based provider-order index.
1653        index: usize,
1654        /// Rejected identity claim.
1655        tool: Box<CapabilityIdentity>,
1656    },
1657    /// A proposal reused a requested name with a different owner or version.
1658    #[error("model response output item {index} tool {actual:?} does not match {expected:?}")]
1659    ToolIdentityMismatch {
1660        /// Zero-based provider-order index.
1661        index: usize,
1662        /// Exact identity from the request snapshot.
1663        expected: Box<CapabilityIdentity>,
1664        /// Rejected model claim.
1665        actual: Box<CapabilityIdentity>,
1666    },
1667    /// A specific-tool request received a different proposed name.
1668    #[error(
1669        "model response output item {index} proposes {actual}; expected specific tool {expected}"
1670    )]
1671    SpecificToolMismatch {
1672        /// Zero-based provider-order index.
1673        index: usize,
1674        /// Requested exact tool name.
1675        expected: CapabilityName,
1676        /// Rejected proposed name.
1677        actual: CapabilityName,
1678    },
1679    /// A nominal completion violated required or specific tool selection.
1680    #[error("model response completed without the required tool call")]
1681    RequiredToolCallMissing,
1682    /// A nominal plain-text completion returned typed JSON content.
1683    #[error("model response plain-text completion contains JSON at output item {index}")]
1684    PlainTextCompletionContainsJson {
1685        /// Zero-based provider-order index.
1686        index: usize,
1687    },
1688    /// A nominal structured completion returned text or a text artifact.
1689    #[error("model response structured completion contains text at output item {index}")]
1690    StructuredCompletionContainsText {
1691        /// Zero-based provider-order index.
1692        index: usize,
1693    },
1694    /// A nominal structured completion did not contain exactly one JSON value.
1695    #[error(
1696        "model response structured completion contains {actual} JSON values; expected exactly one"
1697    )]
1698    StructuredCompletionJsonCount {
1699        /// Observed typed JSON item count.
1700        actual: usize,
1701    },
1702    /// Generic JSON output asserted an unrequested schema binding.
1703    #[error("model response JSON output item {index} has an unrequested schema")]
1704    UnexpectedOutputSchema {
1705        /// Zero-based provider-order index.
1706        index: usize,
1707    },
1708    /// Schema-constrained output did not retain the exact requested binding.
1709    #[error("model response JSON output item {index} schema does not match the requested schema")]
1710    OutputSchemaMismatch {
1711        /// Zero-based provider-order index.
1712        index: usize,
1713        /// Exact digest-pinned requested schema.
1714        expected: Box<SchemaReference>,
1715        /// Missing or different response claim.
1716        actual: Option<Box<SchemaReference>>,
1717    },
1718}
1719
1720#[cfg(test)]
1721mod tests {
1722    use super::*;
1723    use crate::{
1724        ArtifactRef, ContentMetadata, Instruction, ModelRequestBuilder, ModelRequestLimits,
1725        RedactionState, SecurityLabel, ToolDescriptor,
1726    };
1727    use proptest::prelude::*;
1728    use serde_json::{Value, from_value, json, to_value};
1729
1730    fn fixture(path: &[&str], source: &str) -> Value {
1731        let mut value = serde_json::from_str::<Value>(source).unwrap();
1732        for segment in path {
1733            value = value[*segment].clone();
1734        }
1735        value
1736    }
1737
1738    fn descriptor(name: &str) -> ModelDescriptor {
1739        let values = fixture(
1740            &["descriptors", "valid"],
1741            include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1742        );
1743        let mut value = values[0].clone();
1744        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1745        from_value(value).unwrap()
1746    }
1747
1748    fn instruction() -> Instruction {
1749        let values = fixture(
1750            &["instructions", "valid"],
1751            include_str!("../tests/fixtures/core-message-v1.json"),
1752        );
1753        from_value(values[0].clone()).unwrap()
1754    }
1755
1756    fn tool(name: &str) -> ToolDescriptor {
1757        let values = fixture(
1758            &["descriptors", "valid"],
1759            include_str!("../tests/fixtures/core-tool-v1.json"),
1760        );
1761        let mut value = values[0].clone();
1762        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1763        from_value(value).unwrap()
1764    }
1765
1766    fn artifact(modality: ArtifactModality) -> ArtifactRef {
1767        let values = fixture(
1768            &["artifact_refs", "valid"],
1769            include_str!("../tests/fixtures/core-artifact-v1.json"),
1770        );
1771        let mut value = values[0].clone();
1772        value["representation"]["modality"] = to_value(modality).unwrap();
1773        from_value(value).unwrap()
1774    }
1775
1776    fn limits() -> ModelRequestLimits {
1777        ModelRequestLimits::new(
1778            TokenCount::new(8_192),
1779            TokenCount::new(1_024),
1780            ByteCount::new(MEBIBYTE),
1781        )
1782        .unwrap()
1783    }
1784
1785    fn base_builder() -> ModelRequestBuilder {
1786        ModelRequest::builder(limits()).instruction(instruction())
1787    }
1788
1789    fn base_request() -> ModelRequest {
1790        base_builder().build().unwrap()
1791    }
1792
1793    fn provenance(descriptor: &ModelDescriptor) -> ModelResponseProvenance {
1794        ModelResponseProvenance::new(
1795            "01912345-6789-7abc-8def-0123456789ab".parse().unwrap(),
1796            descriptor.metadata().identity().clone(),
1797            Some(ModelProviderModelId::new("provider/model-v1").unwrap()),
1798            Some(ModelProviderResponseId::new("response_opaque-42").unwrap()),
1799        )
1800    }
1801
1802    fn model_metadata() -> ContentMetadata {
1803        ContentMetadata::untrusted(
1804            ContentSource::Model,
1805            SecurityLabel::new("internal/model-output").unwrap(),
1806        )
1807    }
1808
1809    fn text_item(text: &str) -> ModelOutputItem {
1810        ModelOutputItem::content(
1811            TextContent::new(text, None, model_metadata())
1812                .unwrap()
1813                .into(),
1814        )
1815        .unwrap()
1816    }
1817
1818    fn json_item(value: Value, schema: Option<SchemaReference>) -> ModelOutputItem {
1819        ModelOutputItem::content(
1820            JsonContent::new(
1821                BoundedJson::try_from_value(value).unwrap(),
1822                schema,
1823                model_metadata(),
1824            )
1825            .into(),
1826        )
1827        .unwrap()
1828    }
1829
1830    fn usage() -> ModelUsage {
1831        ModelUsage::new(
1832            TokenCount::new(120),
1833            Some(TokenCount::new(20)),
1834            TokenCount::new(30),
1835            Some(TokenCount::new(5)),
1836        )
1837        .unwrap()
1838    }
1839
1840    fn proposal(
1841        descriptor: &ToolDescriptor,
1842        provider_call_id: Option<&str>,
1843    ) -> ModelToolCallProposal {
1844        ModelToolCallProposal::new(
1845            descriptor.metadata().identity().clone(),
1846            provider_call_id.map(|value| ModelProviderToolCallId::new(value).unwrap()),
1847            BoundedJson::try_from_value(json!({"incident_id": 42})).unwrap(),
1848            Extensions::default(),
1849        )
1850        .unwrap()
1851    }
1852
1853    #[test]
1854    fn provider_identifiers_are_exact_bounded_and_redacted() {
1855        let value = ModelProviderResponseId::new("resp/abc:def_42.v1").unwrap();
1856        assert_eq!(value.as_str(), "resp/abc:def_42.v1");
1857        assert_eq!(to_value(&value).unwrap(), "resp/abc:def_42.v1");
1858        assert_eq!(
1859            from_value::<ModelProviderResponseId>(json!(value.as_str())).unwrap(),
1860            value
1861        );
1862        assert!(!format!("{value:?}").contains("resp/abc"));
1863
1864        for invalid in ["", "has space", "line\nbreak", "响应"] {
1865            assert!(ModelProviderResponseId::new(invalid).is_err());
1866        }
1867        assert_eq!(
1868            ModelProviderResponseId::new("x".repeat(ModelProviderResponseId::MAX_BYTES + 1)),
1869            Err(ModelProviderIdentifierError::TooLong {
1870                max: ModelProviderResponseId::MAX_BYTES,
1871                actual: ModelProviderResponseId::MAX_BYTES + 1,
1872            })
1873        );
1874        assert!(from_value::<ModelProviderResponseId>(json!(42)).is_err());
1875    }
1876
1877    #[test]
1878    fn finish_reasons_have_closed_canonical_wire_forms() {
1879        for (reason, expected) in [
1880            (ModelFinishReason::Completed, "completed"),
1881            (ModelFinishReason::ToolCalls, "tool_calls"),
1882            (ModelFinishReason::OutputLimit, "output_limit"),
1883            (ModelFinishReason::ContextLimit, "context_limit"),
1884            (ModelFinishReason::Refused, "refused"),
1885            (ModelFinishReason::ContentFiltered, "content_filtered"),
1886            (ModelFinishReason::Paused, "paused"),
1887        ] {
1888            assert_eq!(to_value(reason).unwrap(), expected);
1889            assert_eq!(
1890                from_value::<ModelFinishReason>(json!(expected)).unwrap(),
1891                reason
1892            );
1893        }
1894        assert!(from_value::<ModelFinishReason>(json!("provider_other")).is_err());
1895        assert!(from_value::<ModelFinishReason>(Value::Null).is_err());
1896    }
1897
1898    #[test]
1899    fn usage_requires_inclusive_checked_accounting() {
1900        assert_eq!(usage().total_tokens(), TokenCount::new(150));
1901        assert_eq!(
1902            ModelUsage::new(
1903                TokenCount::new(2),
1904                Some(TokenCount::new(3)),
1905                TokenCount::ZERO,
1906                None,
1907            ),
1908            Err(ModelUsageError::CachedInputExceedsInput {
1909                input_tokens: TokenCount::new(2),
1910                cached_input_tokens: TokenCount::new(3),
1911            })
1912        );
1913        assert_eq!(
1914            ModelUsage::new(
1915                TokenCount::ZERO,
1916                None,
1917                TokenCount::new(2),
1918                Some(TokenCount::new(3)),
1919            ),
1920            Err(ModelUsageError::ReasoningExceedsOutput {
1921                output_tokens: TokenCount::new(2),
1922                reasoning_tokens: TokenCount::new(3),
1923            })
1924        );
1925        assert_eq!(
1926            ModelUsage::new(TokenCount::MAX, None, TokenCount::new(1), None),
1927            Err(ModelUsageError::TotalTokensOverflow)
1928        );
1929
1930        let known_zero = ModelUsage::new(
1931            TokenCount::ZERO,
1932            Some(TokenCount::ZERO),
1933            TokenCount::ZERO,
1934            Some(TokenCount::ZERO),
1935        )
1936        .unwrap();
1937        assert!(
1938            to_value(known_zero)
1939                .unwrap()
1940                .get("cached_input_tokens")
1941                .is_some()
1942        );
1943        let unknown = ModelUsage::new(TokenCount::ZERO, None, TokenCount::ZERO, None).unwrap();
1944        let encoded = to_value(unknown).unwrap();
1945        assert!(encoded.get("cached_input_tokens").is_none());
1946        assert!(encoded.get("reasoning_tokens").is_none());
1947        assert!(from_value::<ModelUsage>(json!({"input_tokens":"0"})).is_err());
1948    }
1949
1950    #[test]
1951    fn output_items_enforce_untrusted_source_metadata() {
1952        let controlled = ContentMetadata::new(
1953            ContentSource::Model,
1954            ContentTrust::ApplicationControlled,
1955            SecurityLabel::new("internal/model-output").unwrap(),
1956            RedactionState::NotApplied,
1957        );
1958        let invalid = TextContent::new("unsafe", None, controlled).unwrap();
1959        assert!(matches!(
1960            ModelOutputItem::content(invalid.into()),
1961            Err(ModelOutputItemError::InvalidTrust { .. })
1962        ));
1963
1964        let wrong_source = ContentMetadata::untrusted(
1965            ContentSource::User,
1966            SecurityLabel::new("internal/model-output").unwrap(),
1967        );
1968        let invalid = TextContent::new("unsafe", None, wrong_source).unwrap();
1969        assert!(matches!(
1970            ModelOutputItem::content(invalid.into()),
1971            Err(ModelOutputItemError::InvalidSource { .. })
1972        ));
1973
1974        let summary = TextContent::new("Reason summary", None, model_metadata()).unwrap();
1975        assert_eq!(
1976            ModelOutputItem::reasoning_summary(summary).unwrap().kind(),
1977            ModelOutputItemKind::ReasoningSummary
1978        );
1979    }
1980
1981    #[test]
1982    fn completed_text_response_round_trips_and_redacts_debug() {
1983        let descriptor = descriptor("models.primary");
1984        let request = base_request();
1985        let response = ModelResponse::new(
1986            provenance(&descriptor),
1987            &descriptor,
1988            &request,
1989            [text_item("confidential model result")],
1990            ModelFinishReason::Completed,
1991            usage(),
1992            Extensions::default(),
1993        )
1994        .unwrap();
1995
1996        assert_eq!(response.output().len(), 1);
1997        assert_eq!(response.tool_call_count(), 0);
1998        assert_eq!(response.inline_payload_bytes(), ByteCount::new(25));
1999        assert_eq!(response.finish_reason(), ModelFinishReason::Completed);
2000        let encoded = to_value(&response).unwrap();
2001        let decoded = from_value::<ModelResponse>(encoded.clone()).unwrap();
2002        assert_eq!(decoded, response);
2003        decoded.validate_for(&descriptor, &request).unwrap();
2004        let debug = format!("{response:?}");
2005        assert!(!debug.contains("confidential model result"));
2006        assert!(!debug.contains("provider/model-v1"));
2007        assert!(!debug.contains("response_opaque-42"));
2008
2009        let mut unknown = encoded;
2010        unknown["provider"] = Value::from("openai");
2011        assert!(from_value::<ModelResponse>(unknown).is_err());
2012    }
2013
2014    #[test]
2015    fn empty_plain_text_completion_is_valid_but_usage_stays_required() {
2016        let descriptor = descriptor("models.primary");
2017        let request = base_request();
2018        let response = ModelResponse::new(
2019            provenance(&descriptor),
2020            &descriptor,
2021            &request,
2022            [],
2023            ModelFinishReason::Completed,
2024            ModelUsage::new(TokenCount::new(4), None, TokenCount::new(1), None).unwrap(),
2025            Extensions::default(),
2026        )
2027        .unwrap();
2028        assert!(response.output().is_empty());
2029
2030        let mut encoded = to_value(response).unwrap();
2031        encoded.as_object_mut().unwrap().remove("usage");
2032        assert!(from_value::<ModelResponse>(encoded).is_err());
2033    }
2034
2035    #[test]
2036    fn provenance_and_usage_are_bound_to_the_attempt_snapshot() {
2037        let primary_descriptor = descriptor("models.primary");
2038        let other = descriptor("models.other");
2039        let request = base_request();
2040        let response = ModelResponse::new(
2041            provenance(&primary_descriptor),
2042            &primary_descriptor,
2043            &request,
2044            [text_item("ok")],
2045            ModelFinishReason::Completed,
2046            usage(),
2047            Extensions::default(),
2048        )
2049        .unwrap();
2050        assert!(matches!(
2051            response.validate_for(&other, &request),
2052            Err(ModelResponseError::ModelIdentityMismatch { .. })
2053        ));
2054
2055        let excessive =
2056            ModelUsage::new(TokenCount::new(8_193), None, TokenCount::new(1), None).unwrap();
2057        assert!(matches!(
2058            ModelResponse::new(
2059                provenance(&primary_descriptor),
2060                &primary_descriptor,
2061                &request,
2062                [text_item("ok")],
2063                ModelFinishReason::Completed,
2064                excessive,
2065                Extensions::default(),
2066            ),
2067            Err(ModelResponseError::InputUsageExceedsRequest { .. })
2068        ));
2069    }
2070
2071    #[test]
2072    fn structured_completions_are_typed_and_schema_bound() {
2073        let descriptor = descriptor("models.primary");
2074        let generic_request = base_builder()
2075            .text_output_format(Some(ModelTextOutputFormat::json()))
2076            .build()
2077            .unwrap();
2078        ModelResponse::new(
2079            provenance(&descriptor),
2080            &descriptor,
2081            &generic_request,
2082            [json_item(json!({"status": "ok"}), None)],
2083            ModelFinishReason::Completed,
2084            usage(),
2085            Extensions::default(),
2086        )
2087        .unwrap();
2088        assert!(matches!(
2089            ModelResponse::new(
2090                provenance(&descriptor),
2091                &descriptor,
2092                &generic_request,
2093                [text_item("{\"status\":\"ok\"}")],
2094                ModelFinishReason::Completed,
2095                usage(),
2096                Extensions::default(),
2097            ),
2098            Err(ModelResponseError::StructuredCompletionContainsText { .. })
2099        ));
2100        assert!(matches!(
2101            ModelResponse::new(
2102                provenance(&descriptor),
2103                &descriptor,
2104                &generic_request,
2105                [],
2106                ModelFinishReason::Completed,
2107                usage(),
2108                Extensions::default(),
2109            ),
2110            Err(ModelResponseError::StructuredCompletionJsonCount { actual: 0 })
2111        ));
2112
2113        let schema = tool("incidents.lookup").input_schema().clone();
2114        let schema_request = base_builder()
2115            .text_output_format(Some(ModelTextOutputFormat::json_schema(schema.clone())))
2116            .build()
2117            .unwrap();
2118        ModelResponse::new(
2119            provenance(&descriptor),
2120            &descriptor,
2121            &schema_request,
2122            [json_item(json!({"incident_id": 42}), Some(schema.clone()))],
2123            ModelFinishReason::Completed,
2124            usage(),
2125            Extensions::default(),
2126        )
2127        .unwrap();
2128        assert!(matches!(
2129            ModelResponse::new(
2130                provenance(&descriptor),
2131                &descriptor,
2132                &schema_request,
2133                [json_item(json!({"incident_id": 42}), None)],
2134                ModelFinishReason::Completed,
2135                usage(),
2136                Extensions::default(),
2137            ),
2138            Err(ModelResponseError::OutputSchemaMismatch { .. })
2139        ));
2140
2141        ModelResponse::new(
2142            provenance(&descriptor),
2143            &descriptor,
2144            &schema_request,
2145            [text_item("partial JSON")],
2146            ModelFinishReason::OutputLimit,
2147            usage(),
2148            Extensions::default(),
2149        )
2150        .unwrap();
2151    }
2152
2153    #[test]
2154    fn tool_calls_are_unapproved_ordered_and_request_bound() {
2155        let descriptor = descriptor("models.primary");
2156        let first = tool("incidents.lookup");
2157        let second = tool("incidents.update");
2158        let request = base_builder()
2159            .tool(first.clone())
2160            .tool(second.clone())
2161            .tool_selection(ModelToolSelection::specific(
2162                CapabilityName::new("incidents.lookup").unwrap(),
2163            ))
2164            .max_tool_calls_per_response(ExecutionCount::new(2))
2165            .build()
2166            .unwrap();
2167        let response = ModelResponse::new(
2168            provenance(&descriptor),
2169            &descriptor,
2170            &request,
2171            [
2172                text_item("I will inspect the incident."),
2173                ModelOutputItem::tool_call(proposal(&first, Some("call_1"))),
2174            ],
2175            ModelFinishReason::ToolCalls,
2176            usage(),
2177            Extensions::default(),
2178        )
2179        .unwrap();
2180        assert_eq!(response.tool_call_count(), 1);
2181        assert_eq!(response.tool_calls().count(), 1);
2182        assert_eq!(response.output()[0].kind(), ModelOutputItemKind::Content);
2183        assert_eq!(response.output()[1].kind(), ModelOutputItemKind::ToolCall);
2184
2185        assert!(matches!(
2186            ModelResponse::new(
2187                provenance(&descriptor),
2188                &descriptor,
2189                &request,
2190                [ModelOutputItem::tool_call(proposal(
2191                    &second,
2192                    Some("call_2")
2193                ))],
2194                ModelFinishReason::ToolCalls,
2195                usage(),
2196                Extensions::default(),
2197            ),
2198            Err(ModelResponseError::SpecificToolMismatch { .. })
2199        ));
2200        assert!(matches!(
2201            ModelResponse::new(
2202                provenance(&descriptor),
2203                &descriptor,
2204                &request,
2205                [ModelOutputItem::tool_call(proposal(&first, Some("call_3")))],
2206                ModelFinishReason::Completed,
2207                usage(),
2208                Extensions::default(),
2209            ),
2210            Err(ModelResponseError::FinishForbidsToolCalls { .. })
2211        ));
2212        assert!(matches!(
2213            ModelResponse::new(
2214                provenance(&descriptor),
2215                &descriptor,
2216                &request,
2217                [],
2218                ModelFinishReason::ToolCalls,
2219                usage(),
2220                Extensions::default(),
2221            ),
2222            Err(ModelResponseError::ToolCallsFinishRequiresProposal)
2223        ));
2224    }
2225
2226    #[test]
2227    fn disabled_tool_definitions_cannot_authorize_a_new_call() {
2228        let descriptor = descriptor("models.primary");
2229        let selected = tool("incidents.lookup");
2230        let request = base_builder().tool(selected.clone()).build().unwrap();
2231        assert!(matches!(
2232            ModelResponse::new(
2233                provenance(&descriptor),
2234                &descriptor,
2235                &request,
2236                [ModelOutputItem::tool_call(proposal(
2237                    &selected,
2238                    Some("forbidden")
2239                ))],
2240                ModelFinishReason::ToolCalls,
2241                usage(),
2242                Extensions::default(),
2243            ),
2244            Err(ModelResponseError::ToolCallsExceedRequest {
2245                maximum: ExecutionCount::ZERO,
2246                ..
2247            })
2248        ));
2249    }
2250
2251    #[test]
2252    fn tool_argument_and_correlation_invariants_fail_closed() {
2253        let descriptor = descriptor("models.primary");
2254        let selected = tool("incidents.lookup");
2255        assert_eq!(
2256            ModelToolCallProposal::new(
2257                selected.metadata().identity().clone(),
2258                None,
2259                BoundedJson::try_from_value(json!([1, 2])).unwrap(),
2260                Extensions::default(),
2261            ),
2262            Err(ModelToolCallProposalError::ArgumentsMustBeObject)
2263        );
2264
2265        let request = base_builder()
2266            .tool(selected.clone())
2267            .tool_selection(ModelToolSelection::auto())
2268            .max_tool_calls_per_response(ExecutionCount::new(2))
2269            .build()
2270            .unwrap();
2271        assert!(matches!(
2272            ModelResponse::new(
2273                provenance(&descriptor),
2274                &descriptor,
2275                &request,
2276                [
2277                    ModelOutputItem::tool_call(proposal(&selected, Some("duplicate"))),
2278                    ModelOutputItem::tool_call(proposal(&selected, Some("duplicate"))),
2279                ],
2280                ModelFinishReason::ToolCalls,
2281                usage(),
2282                Extensions::default(),
2283            ),
2284            Err(ModelResponseError::DuplicateProviderToolCallId)
2285        ));
2286
2287        let one_call_request = base_builder()
2288            .tool(selected.clone())
2289            .tool_selection(ModelToolSelection::auto())
2290            .max_tool_calls_per_response(ExecutionCount::new(1))
2291            .build()
2292            .unwrap();
2293        assert!(matches!(
2294            ModelResponse::new(
2295                provenance(&descriptor),
2296                &descriptor,
2297                &one_call_request,
2298                [
2299                    ModelOutputItem::tool_call(proposal(&selected, Some("one"))),
2300                    ModelOutputItem::tool_call(proposal(&selected, Some("two"))),
2301                ],
2302                ModelFinishReason::ToolCalls,
2303                usage(),
2304                Extensions::default(),
2305            ),
2306            Err(ModelResponseError::ToolCallsExceedRequest { .. })
2307        ));
2308    }
2309
2310    #[test]
2311    fn required_tools_and_reasoning_opt_in_are_enforced() {
2312        let descriptor = descriptor("models.primary");
2313        let selected = tool("incidents.lookup");
2314        let required = base_builder()
2315            .tool(selected)
2316            .tool_selection(ModelToolSelection::required())
2317            .max_tool_calls_per_response(ExecutionCount::new(1))
2318            .build()
2319            .unwrap();
2320        assert!(matches!(
2321            ModelResponse::new(
2322                provenance(&descriptor),
2323                &descriptor,
2324                &required,
2325                [text_item("done")],
2326                ModelFinishReason::Completed,
2327                usage(),
2328                Extensions::default(),
2329            ),
2330            Err(ModelResponseError::RequiredToolCallMissing)
2331        ));
2332
2333        let summary = ModelOutputItem::reasoning_summary(
2334            TextContent::new("Readable summary", None, model_metadata()).unwrap(),
2335        )
2336        .unwrap();
2337        assert!(matches!(
2338            ModelResponse::new(
2339                provenance(&descriptor),
2340                &descriptor,
2341                &base_request(),
2342                [summary.clone(), text_item("done")],
2343                ModelFinishReason::Completed,
2344                usage(),
2345                Extensions::default(),
2346            ),
2347            Err(ModelResponseError::ReasoningSummaryNotRequested { index: 0 })
2348        ));
2349        let requested = base_builder().reasoning_summaries(true).build().unwrap();
2350        ModelResponse::new(
2351            provenance(&descriptor),
2352            &descriptor,
2353            &requested,
2354            [summary, text_item("done")],
2355            ModelFinishReason::Completed,
2356            usage(),
2357            Extensions::default(),
2358        )
2359        .unwrap();
2360    }
2361
2362    #[test]
2363    fn artifact_modalities_are_portable_requested_and_externally_bounded() {
2364        let descriptor = descriptor("models.primary");
2365        let document =
2366            ModelOutputItem::content(artifact(ArtifactModality::Document).into()).unwrap();
2367        assert!(matches!(
2368            ModelResponse::new(
2369                provenance(&descriptor),
2370                &descriptor,
2371                &base_request(),
2372                [document.clone()],
2373                ModelFinishReason::Completed,
2374                usage(),
2375                Extensions::default(),
2376            ),
2377            Err(ModelResponseError::OutputModalityNotRequested {
2378                modality: ModelModality::Document,
2379                ..
2380            })
2381        ));
2382
2383        let document_request = base_builder()
2384            .output_modalities(crate::ModelModalities::try_new([ModelModality::Document]).unwrap())
2385            .text_output_format(None)
2386            .build()
2387            .unwrap();
2388        let response = ModelResponse::new(
2389            provenance(&descriptor),
2390            &descriptor,
2391            &document_request,
2392            [document],
2393            ModelFinishReason::Completed,
2394            usage(),
2395            Extensions::default(),
2396        )
2397        .unwrap();
2398        assert_eq!(response.inline_payload_bytes(), ByteCount::ZERO);
2399
2400        let unsupported =
2401            ModelOutputItem::Content(ContentPart::from(artifact(ArtifactModality::Archive)));
2402        assert!(matches!(
2403            ModelResponse::new(
2404                provenance(&descriptor),
2405                &descriptor,
2406                &document_request,
2407                [unsupported],
2408                ModelFinishReason::Completed,
2409                usage(),
2410                Extensions::default(),
2411            ),
2412            Err(ModelResponseError::UnsupportedArtifactModality {
2413                modality: ArtifactModality::Archive,
2414                ..
2415            })
2416        ));
2417    }
2418
2419    #[test]
2420    fn collection_and_inline_resource_ceilings_stop_at_first_excess() {
2421        let content = text_item("x");
2422        assert_eq!(
2423            ModelOutputItems::try_new(std::iter::repeat_n(
2424                content,
2425                ModelOutputItems::MAX_CONTENT_ITEMS + 1
2426            )),
2427            Err(ModelResponseError::TooManyContentItems {
2428                max: ModelOutputItems::MAX_CONTENT_ITEMS,
2429                observed: ModelOutputItems::MAX_CONTENT_ITEMS + 1,
2430            })
2431        );
2432
2433        let selected = tool("incidents.lookup");
2434        let proposal = ModelOutputItem::tool_call(proposal(&selected, None));
2435        assert_eq!(
2436            ModelOutputItems::try_new(std::iter::repeat_n(
2437                proposal,
2438                ModelOutputItems::MAX_TOOL_CALLS + 1
2439            )),
2440            Err(ModelResponseError::TooManyToolCalls {
2441                max: ModelOutputItems::MAX_TOOL_CALLS,
2442                observed: ModelOutputItems::MAX_TOOL_CALLS + 1,
2443            })
2444        );
2445
2446        let mut values = Vec::new();
2447        let mut content_items = 0;
2448        let mut tool_calls = 0;
2449        let mut bytes = ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES;
2450        let mut modalities = BTreeSet::new();
2451        let mut provider_call_ids = BTreeSet::new();
2452        assert_eq!(
2453            push_output_item(
2454                &mut values,
2455                &mut content_items,
2456                &mut tool_calls,
2457                &mut bytes,
2458                &mut modalities,
2459                &mut provider_call_ids,
2460                text_item("x"),
2461            ),
2462            Err(ModelResponseError::InlinePayloadTooLarge {
2463                maximum: ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES,
2464                observed: ByteCount::new(ModelOutputItems::MAX_INLINE_PAYLOAD_BYTES.get() + 1),
2465            })
2466        );
2467    }
2468
2469    #[test]
2470    fn response_schemas_publish_closed_objects_and_hard_bounds() {
2471        for schema in [
2472            to_value(schemars::schema_for!(ModelUsage)).unwrap(),
2473            to_value(schemars::schema_for!(ModelToolCallProposal)).unwrap(),
2474            to_value(schemars::schema_for!(ModelResponseProvenance)).unwrap(),
2475            to_value(schemars::schema_for!(ModelResponse)).unwrap(),
2476        ] {
2477            assert_eq!(schema["type"], "object");
2478            assert_eq!(schema["additionalProperties"], false);
2479        }
2480
2481        let response = to_value(schemars::schema_for!(ModelResponse)).unwrap();
2482        assert_eq!(
2483            response["$defs"]["ModelResponseOutput"]["maxItems"],
2484            ModelResponse::MAX_OUTPUT_ITEMS
2485        );
2486        let provider_id = to_value(schemars::schema_for!(ModelProviderResponseId)).unwrap();
2487        assert_eq!(provider_id["maxLength"], ModelProviderResponseId::MAX_BYTES);
2488        assert_eq!(provider_id["pattern"], PROVIDER_IDENTIFIER_PATTERN);
2489    }
2490
2491    proptest! {
2492        #[test]
2493        fn valid_usage_round_trips_without_losing_known_breakdowns(
2494            input in 0_u64..=1_000_000,
2495            output in 0_u64..=1_000_000,
2496            cached_fraction in 0_u64..=1_000_000,
2497            reasoning_fraction in 0_u64..=1_000_000,
2498        ) {
2499            let cached = TokenCount::new(cached_fraction.min(input));
2500            let reasoning = TokenCount::new(reasoning_fraction.min(output));
2501            let usage = ModelUsage::new(
2502                TokenCount::new(input),
2503                Some(cached),
2504                TokenCount::new(output),
2505                Some(reasoning),
2506            ).unwrap();
2507            let encoded = serde_json::to_vec(&usage).unwrap();
2508            prop_assert_eq!(serde_json::from_slice::<ModelUsage>(&encoded).unwrap(), usage);
2509        }
2510
2511        #[test]
2512        fn visible_ascii_provider_identifiers_round_trip(bytes in prop::collection::vec(33_u8..127, 1..100)) {
2513            let text = String::from_utf8(bytes).unwrap();
2514            let id = ModelProviderToolCallId::new(text.clone()).unwrap();
2515            let encoded = serde_json::to_vec(&id).unwrap();
2516            prop_assert_eq!(serde_json::from_slice::<ModelProviderToolCallId>(&encoded).unwrap(), id.clone());
2517            prop_assert_eq!(id.as_str(), text);
2518        }
2519    }
2520}