Skip to main content

stateknot_core/
model_event.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Bounded semantic model-stream events and deterministic response assembly.
5
6use std::{collections::BTreeSet, fmt, mem};
7
8use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
9use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
10use thiserror::Error;
11
12use crate::{
13    ArtifactRef, AttemptId, BoundedJson, BoundedJsonError, ByteCount, CapabilityIdentity,
14    ContentMetadata, ContentPart, ContentSource, ExecutionCount, Extensions, JsonContent,
15    JsonLimits, LanguageTag, ModelCapabilityMismatch, ModelDescriptor, ModelFinishReason,
16    ModelOutputItem, ModelOutputItemError, ModelOutputItemKind, ModelProviderToolCallId,
17    ModelRequest, ModelResponse, ModelResponseError, ModelResponseMode, ModelResponseProvenance,
18    ModelToolCallProposal, ModelToolCallProposalError, ModelUsage, SchemaReference, TextContent,
19    TextContentError, TokenCount,
20};
21
22const KIBIBYTE: usize = 1024;
23const MAX_EVENTS_PER_ATTEMPT_VALUE: u64 = 1_048_576;
24
25/// One exact, non-empty provider-normalized stream fragment.
26///
27/// Fragments preserve UTF-8 bytes without trimming or normalization. A JSON
28/// or tool-argument fragment need not be valid JSON by itself; the accumulator
29/// parses the exact concatenation only when its output item closes. Debug
30/// output reveals only the encoded length.
31#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
32pub struct ModelStreamChunk(Box<str>);
33
34impl ModelStreamChunk {
35    /// Maximum UTF-8 byte length of one semantic delta event.
36    pub const MAX_BYTES: usize = 64 * KIBIBYTE;
37
38    /// Validates and retains an owned stream fragment.
39    ///
40    /// # Errors
41    ///
42    /// Returns [`ModelStreamChunkError`] for empty, oversized, control-bearing,
43    /// or Unicode-noncharacter input.
44    pub fn new(value: impl Into<String>) -> Result<Self, ModelStreamChunkError> {
45        let value = value.into();
46        validate_stream_chunk(&value)?;
47        Ok(Self(value.into_boxed_str()))
48    }
49
50    /// Returns the exact provider-normalized UTF-8 fragment.
51    #[must_use]
52    pub fn as_str(&self) -> &str {
53        &self.0
54    }
55
56    /// Returns the retained UTF-8 byte length without disclosing content.
57    #[must_use]
58    pub fn len_bytes(&self) -> usize {
59        self.0.len()
60    }
61
62    /// Consumes the fragment and returns its allocation.
63    #[must_use]
64    pub fn into_string(self) -> String {
65        self.0.into()
66    }
67}
68
69fn validate_stream_chunk(value: &str) -> Result<(), ModelStreamChunkError> {
70    if value.is_empty() {
71        return Err(ModelStreamChunkError::Empty);
72    }
73    if value.len() > ModelStreamChunk::MAX_BYTES {
74        return Err(ModelStreamChunkError::TooLong {
75            maximum: ModelStreamChunk::MAX_BYTES,
76            actual: value.len(),
77        });
78    }
79    if let Some((byte_index, _)) = value.char_indices().find(|(_, scalar)| {
80        (scalar.is_control() && !matches!(scalar, '\t' | '\n' | '\r'))
81            || is_unicode_noncharacter(*scalar)
82    }) {
83        return Err(ModelStreamChunkError::DisallowedCodePoint { byte_index });
84    }
85    Ok(())
86}
87
88const fn is_unicode_noncharacter(value: char) -> bool {
89    let value = value as u32;
90    (value >= 0xfdd0 && value <= 0xfdef) || (value & 0xfffe) == 0xfffe
91}
92
93impl AsRef<str> for ModelStreamChunk {
94    fn as_ref(&self) -> &str {
95        self.as_str()
96    }
97}
98
99impl fmt::Debug for ModelStreamChunk {
100    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
101        formatter
102            .debug_struct("ModelStreamChunk")
103            .field("bytes", &self.len_bytes())
104            .finish_non_exhaustive()
105    }
106}
107
108impl Serialize for ModelStreamChunk {
109    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
110    where
111        S: Serializer,
112    {
113        serializer.serialize_str(self.as_str())
114    }
115}
116
117impl<'de> Deserialize<'de> for ModelStreamChunk {
118    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
119    where
120        D: Deserializer<'de>,
121    {
122        struct Visitor;
123
124        impl de::Visitor<'_> for Visitor {
125            type Value = ModelStreamChunk;
126
127            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
128                formatter.write_str("a non-empty bounded model stream fragment")
129            }
130
131            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
132            where
133                E: de::Error,
134            {
135                ModelStreamChunk::new(value).map_err(E::custom)
136            }
137
138            fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
139            where
140                E: de::Error,
141            {
142                ModelStreamChunk::new(value).map_err(E::custom)
143            }
144        }
145
146        deserializer.deserialize_string(Visitor)
147    }
148}
149
150impl JsonSchema for ModelStreamChunk {
151    fn schema_name() -> std::borrow::Cow<'static, str> {
152        "ModelStreamChunk".into()
153    }
154
155    fn schema_id() -> std::borrow::Cow<'static, str> {
156        concat!(module_path!(), "::ModelStreamChunk").into()
157    }
158
159    fn json_schema(_: &mut SchemaGenerator) -> Schema {
160        json_schema!({
161            "type": "string",
162            "minLength": 1,
163            "maxLength": 65_536,
164            "description": "Exact UTF-8 fragment. maxLength is a necessary code-point ceiling; runtime validation separately enforces 65536 bytes and excludes disallowed controls and Unicode noncharacters."
165        })
166    }
167
168    fn inline_schema() -> bool {
169        true
170    }
171}
172
173/// Invalid semantic model-stream fragment.
174#[derive(Clone, Debug, Eq, Error, PartialEq)]
175#[non_exhaustive]
176pub enum ModelStreamChunkError {
177    /// The fragment contained no bytes.
178    #[error("model stream chunk must not be empty")]
179    Empty,
180    /// The fragment exceeded its immutable byte ceiling.
181    #[error("model stream chunk is {actual} UTF-8 bytes; maximum is {maximum}")]
182    TooLong {
183        /// Immutable maximum.
184        maximum: usize,
185        /// Observed encoded length.
186        actual: usize,
187    },
188    /// The fragment contained a control or Unicode noncharacter.
189    #[error("model stream chunk contains a disallowed Unicode scalar at byte {byte_index}")]
190    DisallowedCodePoint {
191        /// Zero-based UTF-8 offset without content disclosure.
192        byte_index: usize,
193    },
194}
195
196/// Header that fixes the type and immutable metadata of one streamed output.
197///
198/// Text, JSON, reasoning, and tool arguments arrive through subsequent deltas.
199/// Artifact bytes never cross this boundary: an artifact start carries only a
200/// complete immutable [`ArtifactRef`].
201#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
202#[serde(
203    tag = "type",
204    content = "content",
205    rename_all = "snake_case",
206    deny_unknown_fields
207)]
208pub enum ModelOutputStart {
209    /// User-visible text header.
210    Text {
211        /// Optional stable language tag for the completed text.
212        #[serde(skip_serializing_if = "Option::is_none")]
213        language: Option<LanguageTag>,
214        /// Mandatory model-source, untrusted security metadata.
215        metadata: ContentMetadata,
216    },
217    /// Structured JSON header.
218    Json {
219        /// Optional digest-pinned schema identity asserted for the completed value.
220        #[serde(skip_serializing_if = "Option::is_none")]
221        schema: Option<SchemaReference>,
222        /// Mandatory model-source, untrusted security metadata.
223        metadata: ContentMetadata,
224    },
225    /// Complete immutable artifact reference; no inline deltas are accepted.
226    Artifact(Box<ArtifactRef>),
227    /// Human-readable reasoning-summary header, never hidden chain of thought.
228    ReasoningSummary {
229        /// Optional stable language tag for the completed summary.
230        #[serde(skip_serializing_if = "Option::is_none")]
231        language: Option<LanguageTag>,
232        /// Mandatory model-source, untrusted security metadata.
233        metadata: ContentMetadata,
234    },
235    /// Complete identity header for an unapproved model tool-call proposal.
236    ToolCall {
237        /// Exact requested, owner-qualified tool identity.
238        tool: CapabilityIdentity,
239        /// Optional opaque provider correlation identifier.
240        #[serde(skip_serializing_if = "Option::is_none")]
241        provider_call_id: Option<ModelProviderToolCallId>,
242        /// Registered bounded proposal extensions.
243        extensions: Extensions,
244    },
245}
246
247impl ModelOutputStart {
248    /// Constructs a validated user-visible text header.
249    pub fn text(
250        language: Option<LanguageTag>,
251        metadata: ContentMetadata,
252    ) -> Result<Self, ModelOutputItemError> {
253        let value = Self::Text { language, metadata };
254        value.validate_intrinsic()?;
255        Ok(value)
256    }
257
258    /// Constructs a validated structured JSON header.
259    pub fn json(
260        schema: Option<SchemaReference>,
261        metadata: ContentMetadata,
262    ) -> Result<Self, ModelOutputItemError> {
263        let value = Self::Json { schema, metadata };
264        value.validate_intrinsic()?;
265        Ok(value)
266    }
267
268    /// Constructs a validated immutable artifact header.
269    pub fn artifact(artifact: ArtifactRef) -> Result<Self, ModelOutputItemError> {
270        let value = Self::Artifact(Box::new(artifact));
271        value.validate_intrinsic()?;
272        Ok(value)
273    }
274
275    /// Constructs a validated readable reasoning-summary header.
276    pub fn reasoning_summary(
277        language: Option<LanguageTag>,
278        metadata: ContentMetadata,
279    ) -> Result<Self, ModelOutputItemError> {
280        let value = Self::ReasoningSummary { language, metadata };
281        value.validate_intrinsic()?;
282        Ok(value)
283    }
284
285    /// Constructs a tool-call header whose arguments will arrive as JSON deltas.
286    #[must_use]
287    pub fn tool_call(
288        tool: CapabilityIdentity,
289        provider_call_id: Option<ModelProviderToolCallId>,
290        extensions: Extensions,
291    ) -> Self {
292        Self::ToolCall {
293            tool,
294            provider_call_id,
295            extensions,
296        }
297    }
298
299    /// Returns the final response-item classification.
300    #[must_use]
301    pub const fn kind(&self) -> ModelOutputItemKind {
302        match self {
303            Self::Text { .. } | Self::Json { .. } | Self::Artifact(_) => {
304                ModelOutputItemKind::Content
305            }
306            Self::ReasoningSummary { .. } => ModelOutputItemKind::ReasoningSummary,
307            Self::ToolCall { .. } => ModelOutputItemKind::ToolCall,
308        }
309    }
310
311    /// Returns the only accepted delta classification, or `None` for artifacts.
312    #[must_use]
313    pub const fn delta_kind(&self) -> Option<ModelOutputDeltaKind> {
314        match self {
315            Self::Text { .. } => Some(ModelOutputDeltaKind::Text),
316            Self::Json { .. } => Some(ModelOutputDeltaKind::Json),
317            Self::Artifact(_) => None,
318            Self::ReasoningSummary { .. } => Some(ModelOutputDeltaKind::ReasoningSummary),
319            Self::ToolCall { .. } => Some(ModelOutputDeltaKind::ToolArguments),
320        }
321    }
322
323    fn validate_intrinsic(&self) -> Result<(), ModelOutputItemError> {
324        match self {
325            Self::Text { metadata, .. } | Self::Json { metadata, .. } => {
326                crate::model_response::validate_output_metadata(
327                    ModelOutputItemKind::Content,
328                    metadata,
329                    ContentSource::Model,
330                )
331            }
332            Self::Artifact(artifact) => crate::model_response::validate_output_metadata(
333                ModelOutputItemKind::Content,
334                artifact.metadata(),
335                ContentSource::Artifact,
336            ),
337            Self::ReasoningSummary { metadata, .. } => {
338                crate::model_response::validate_output_metadata(
339                    ModelOutputItemKind::ReasoningSummary,
340                    metadata,
341                    ContentSource::Model,
342                )
343            }
344            Self::ToolCall { .. } => Ok(()),
345        }
346    }
347
348    fn inline_header_bytes(&self) -> usize {
349        match self {
350            Self::ToolCall { extensions, .. } => extensions.compact_bytes(),
351            Self::Text { .. }
352            | Self::Json { .. }
353            | Self::Artifact(_)
354            | Self::ReasoningSummary { .. } => 0,
355        }
356    }
357}
358
359#[derive(Deserialize)]
360#[serde(
361    tag = "type",
362    content = "content",
363    rename_all = "snake_case",
364    deny_unknown_fields
365)]
366enum ModelOutputStartWire {
367    Text {
368        #[serde(default)]
369        language: Option<LanguageTag>,
370        metadata: ContentMetadata,
371    },
372    Json {
373        #[serde(default)]
374        schema: Option<SchemaReference>,
375        metadata: ContentMetadata,
376    },
377    Artifact(Box<ArtifactRef>),
378    ReasoningSummary {
379        #[serde(default)]
380        language: Option<LanguageTag>,
381        metadata: ContentMetadata,
382    },
383    ToolCall {
384        tool: CapabilityIdentity,
385        #[serde(default)]
386        provider_call_id: Option<ModelProviderToolCallId>,
387        extensions: Extensions,
388    },
389}
390
391impl<'de> Deserialize<'de> for ModelOutputStart {
392    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
393    where
394        D: Deserializer<'de>,
395    {
396        let value = match ModelOutputStartWire::deserialize(deserializer)? {
397            ModelOutputStartWire::Text { language, metadata } => Self::Text { language, metadata },
398            ModelOutputStartWire::Json { schema, metadata } => Self::Json { schema, metadata },
399            ModelOutputStartWire::Artifact(artifact) => Self::Artifact(artifact),
400            ModelOutputStartWire::ReasoningSummary { language, metadata } => {
401                Self::ReasoningSummary { language, metadata }
402            }
403            ModelOutputStartWire::ToolCall {
404                tool,
405                provider_call_id,
406                extensions,
407            } => Self::ToolCall {
408                tool,
409                provider_call_id,
410                extensions,
411            },
412        };
413        value.validate_intrinsic().map_err(de::Error::custom)?;
414        Ok(value)
415    }
416}
417
418/// Closed classification of a semantic model-output delta.
419#[derive(
420    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
421)]
422#[non_exhaustive]
423#[serde(rename_all = "snake_case")]
424pub enum ModelOutputDeltaKind {
425    /// User-visible text bytes.
426    Text,
427    /// Partial structured-output JSON text.
428    Json,
429    /// Partial readable reasoning-summary text.
430    ReasoningSummary,
431    /// Partial tool-argument JSON text.
432    ToolArguments,
433}
434
435/// One typed exact fragment for an already-started output item.
436#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
437#[serde(
438    tag = "type",
439    content = "delta",
440    rename_all = "snake_case",
441    deny_unknown_fields
442)]
443pub enum ModelOutputDelta {
444    /// User-visible text delta.
445    Text(ModelStreamChunk),
446    /// Structured-output JSON delta.
447    Json(ModelStreamChunk),
448    /// Readable reasoning-summary delta.
449    ReasoningSummary(ModelStreamChunk),
450    /// Tool-argument JSON delta.
451    ToolArguments(ModelStreamChunk),
452}
453
454impl ModelOutputDelta {
455    /// Returns the closed fragment classification.
456    #[must_use]
457    pub const fn kind(&self) -> ModelOutputDeltaKind {
458        match self {
459            Self::Text(_) => ModelOutputDeltaKind::Text,
460            Self::Json(_) => ModelOutputDeltaKind::Json,
461            Self::ReasoningSummary(_) => ModelOutputDeltaKind::ReasoningSummary,
462            Self::ToolArguments(_) => ModelOutputDeltaKind::ToolArguments,
463        }
464    }
465
466    /// Returns the exact bounded fragment.
467    #[must_use]
468    pub const fn chunk(&self) -> &ModelStreamChunk {
469        match self {
470            Self::Text(chunk)
471            | Self::Json(chunk)
472            | Self::ReasoningSummary(chunk)
473            | Self::ToolArguments(chunk) => chunk,
474        }
475    }
476
477    fn into_chunk(self) -> ModelStreamChunk {
478        match self {
479            Self::Text(chunk)
480            | Self::Json(chunk)
481            | Self::ReasoningSummary(chunk)
482            | Self::ToolArguments(chunk) => chunk,
483        }
484    }
485}
486
487/// Provider-neutral semantic event emitted by one model attempt.
488///
489/// `sequence` starts at zero and is contiguous after provider pings, empty
490/// deltas, and transport framing have been removed. `output_index` values are
491/// registered contiguously by `output_started`, while deltas and completion of
492/// already-started outputs may interleave.
493#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
494#[serde(deny_unknown_fields)]
495pub struct ModelEvent {
496    attempt_id: AttemptId,
497    sequence: ExecutionCount,
498    event: ModelEventKind,
499}
500
501impl ModelEvent {
502    /// Maximum number of retained semantic events in one attempt stream.
503    pub const MAX_EVENTS_PER_ATTEMPT: ExecutionCount =
504        ExecutionCount::new(MAX_EVENTS_PER_ATTEMPT_VALUE);
505    /// Largest valid zero-based event sequence.
506    pub const MAX_SEQUENCE: ExecutionCount = ExecutionCount::new(MAX_EVENTS_PER_ATTEMPT_VALUE - 1);
507
508    /// Constructs and intrinsically validates one semantic event.
509    ///
510    /// # Errors
511    ///
512    /// Returns [`ModelEventError`] for an out-of-range sequence or output
513    /// index, mismatched start provenance, or invalid output-start metadata.
514    pub fn new(
515        attempt_id: AttemptId,
516        sequence: ExecutionCount,
517        event: ModelEventKind,
518    ) -> Result<Self, ModelEventError> {
519        if sequence >= Self::MAX_EVENTS_PER_ATTEMPT {
520            return Err(ModelEventError::SequenceOutOfRange {
521                maximum: Self::MAX_SEQUENCE,
522                actual: sequence,
523            });
524        }
525        if let Some(output_index) = event.output_index() {
526            let maximum_exclusive = ExecutionCount::new(ModelResponse::MAX_OUTPUT_ITEMS as u64);
527            if output_index >= maximum_exclusive {
528                return Err(ModelEventError::OutputIndexOutOfRange {
529                    maximum_exclusive,
530                    actual: output_index,
531                });
532            }
533        }
534        match &event {
535            ModelEventKind::Started { provenance } if provenance.attempt_id() != attempt_id => {
536                return Err(ModelEventError::StartedAttemptMismatch {
537                    event: attempt_id,
538                    provenance: provenance.attempt_id(),
539                });
540            }
541            ModelEventKind::OutputStarted { start, .. } => start
542                .validate_intrinsic()
543                .map_err(|error| ModelEventError::InvalidOutputStart { error })?,
544            ModelEventKind::Started { .. }
545            | ModelEventKind::OutputDelta { .. }
546            | ModelEventKind::OutputCompleted { .. }
547            | ModelEventKind::UsageUpdated { .. }
548            | ModelEventKind::Completed { .. } => {}
549        }
550        Ok(Self {
551            attempt_id,
552            sequence,
553            event,
554        })
555    }
556
557    /// Returns the exact model-attempt identity.
558    #[must_use]
559    pub const fn attempt_id(&self) -> AttemptId {
560        self.attempt_id
561    }
562
563    /// Returns the zero-based contiguous semantic sequence.
564    #[must_use]
565    pub const fn sequence(&self) -> ExecutionCount {
566        self.sequence
567    }
568
569    /// Returns the semantic event body.
570    #[must_use]
571    pub const fn event(&self) -> &ModelEventKind {
572        &self.event
573    }
574}
575
576#[derive(Deserialize)]
577#[serde(deny_unknown_fields)]
578struct ModelEventWire {
579    attempt_id: AttemptId,
580    sequence: ExecutionCount,
581    event: ModelEventKind,
582}
583
584impl<'de> Deserialize<'de> for ModelEvent {
585    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
586    where
587        D: Deserializer<'de>,
588    {
589        let wire = ModelEventWire::deserialize(deserializer)?;
590        Self::new(wire.attempt_id, wire.sequence, wire.event).map_err(de::Error::custom)
591    }
592}
593
594/// Closed semantic body of a provider-neutral model event.
595#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
596#[serde(
597    tag = "type",
598    content = "content",
599    rename_all = "snake_case",
600    deny_unknown_fields
601)]
602pub enum ModelEventKind {
603    /// Opens one attempt stream and fixes response provenance.
604    Started {
605        /// Attempt and exact model identity plus optional provider correlation IDs.
606        provenance: ModelResponseProvenance,
607    },
608    /// Registers the next ordered output item and its immutable header.
609    OutputStarted {
610        /// Zero-based final-response output position.
611        output_index: ExecutionCount,
612        /// Typed output header.
613        start: Box<ModelOutputStart>,
614    },
615    /// Appends an exact fragment to an active output item.
616    OutputDelta {
617        /// Previously registered output position.
618        output_index: ExecutionCount,
619        /// Typed non-empty fragment.
620        delta: ModelOutputDelta,
621    },
622    /// Closes and validates one active output item.
623    OutputCompleted {
624        /// Previously registered output position.
625        output_index: ExecutionCount,
626    },
627    /// Reports a complete cumulative usage snapshot observed so far.
628    UsageUpdated {
629        /// Inclusive, normalized, monotonic per-attempt token accounting.
630        usage: ModelUsage,
631    },
632    /// Terminates the stream and supplies authoritative final accounting.
633    Completed {
634        /// Portable successful or incomplete terminal reason.
635        finish_reason: ModelFinishReason,
636        /// Authoritative inclusive token accounting for the whole attempt.
637        usage: ModelUsage,
638        /// Bounded registered provider/adapter terminal metadata.
639        extensions: Extensions,
640    },
641}
642
643impl ModelEventKind {
644    fn output_index(&self) -> Option<ExecutionCount> {
645        match self {
646            Self::OutputStarted { output_index, .. }
647            | Self::OutputDelta { output_index, .. }
648            | Self::OutputCompleted { output_index } => Some(*output_index),
649            Self::Started { .. } | Self::UsageUpdated { .. } | Self::Completed { .. } => None,
650        }
651    }
652}
653
654/// Intrinsically invalid provider-neutral model event.
655#[derive(Clone, Debug, Eq, Error, PartialEq)]
656#[non_exhaustive]
657pub enum ModelEventError {
658    /// The zero-based semantic event sequence exceeded the hard ceiling.
659    #[error("model event sequence {actual} exceeds maximum {maximum}")]
660    SequenceOutOfRange {
661        /// Largest accepted sequence.
662        maximum: ExecutionCount,
663        /// Rejected sequence.
664        actual: ExecutionCount,
665    },
666    /// The zero-based output position exceeded the response item ceiling.
667    #[error("model output index {actual} must be less than {maximum_exclusive}")]
668    OutputIndexOutOfRange {
669        /// Exclusive immutable upper bound.
670        maximum_exclusive: ExecutionCount,
671        /// Rejected index.
672        actual: ExecutionCount,
673    },
674    /// The stream-start provenance named a different attempt.
675    #[error("model event attempt {event} does not match start provenance attempt {provenance}")]
676    StartedAttemptMismatch {
677        /// Attempt attached to the event envelope.
678        event: AttemptId,
679        /// Attempt asserted by start provenance.
680        provenance: AttemptId,
681    },
682    /// An output header carried invalid source or trust metadata.
683    #[error("invalid streamed model output header: {error}")]
684    InvalidOutputStart {
685        /// Intrinsic metadata failure.
686        #[source]
687        error: ModelOutputItemError,
688    },
689}
690
691/// Token-usage dimension used in monotonic stream diagnostics.
692#[derive(
693    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
694)]
695#[non_exhaustive]
696#[serde(rename_all = "snake_case")]
697pub enum ModelUsageField {
698    /// Inclusive input tokens.
699    InputTokens,
700    /// Cached-input subset.
701    CachedInputTokens,
702    /// Inclusive generated-output tokens.
703    OutputTokens,
704    /// Reasoning-output subset.
705    ReasoningTokens,
706}
707
708enum OutputSlot {
709    Active {
710        start: ModelOutputStart,
711        buffer: String,
712    },
713    Completed(ModelOutputItem),
714    Transitioning,
715}
716
717/// Fail-closed state machine that assembles one verified streaming response.
718///
719/// Any rejected event permanently poisons the accumulator, preventing callers
720/// from ignoring a gap or invalid fragment and resuming. A successful terminal
721/// event is retained and returned by [`Self::finish`]. Transport end before a
722/// terminal event is always an error.
723pub struct ModelEventAccumulator<'a> {
724    descriptor: &'a ModelDescriptor,
725    request: &'a ModelRequest,
726    attempt_id: AttemptId,
727    next_sequence: ExecutionCount,
728    started: bool,
729    poisoned: bool,
730    provenance: Option<ModelResponseProvenance>,
731    slots: Vec<OutputSlot>,
732    content_items: usize,
733    tool_calls: usize,
734    provider_call_ids: BTreeSet<ModelProviderToolCallId>,
735    retained_inline_bytes: usize,
736    last_usage: Option<ModelUsage>,
737    response: Option<ModelResponse>,
738}
739
740impl<'a> ModelEventAccumulator<'a> {
741    /// Constructs an empty state machine for one immutable attempt snapshot.
742    ///
743    /// # Errors
744    ///
745    /// Returns [`ModelEventStreamError::RequestNotStreaming`] unless the exact
746    /// request selected streaming delivery, or
747    /// [`ModelEventStreamError::CapabilityMismatch`] when the descriptor does
748    /// not satisfy every derived request requirement.
749    pub fn new(
750        attempt_id: AttemptId,
751        descriptor: &'a ModelDescriptor,
752        request: &'a ModelRequest,
753    ) -> Result<Self, ModelEventStreamError> {
754        if request.response_mode() != ModelResponseMode::Streaming {
755            return Err(ModelEventStreamError::RequestNotStreaming);
756        }
757        descriptor
758            .capabilities()
759            .satisfies(request.requirements())
760            .map_err(|mismatch| ModelEventStreamError::CapabilityMismatch { mismatch })?;
761        Ok(Self {
762            descriptor,
763            request,
764            attempt_id,
765            next_sequence: ExecutionCount::ZERO,
766            started: false,
767            poisoned: false,
768            provenance: None,
769            slots: Vec::new(),
770            content_items: 0,
771            tool_calls: 0,
772            provider_call_ids: BTreeSet::new(),
773            retained_inline_bytes: 0,
774            last_usage: None,
775            response: None,
776        })
777    }
778
779    /// Applies one event atomically to the logical stream state.
780    ///
781    /// A successful terminal event retains the final response but does not
782    /// expose it. Call [`Self::finish`] only after the transport ends. Any
783    /// rejected event, including one after terminal, poisons the state machine.
784    pub fn push(&mut self, event: ModelEvent) -> Result<(), ModelEventStreamError> {
785        if self.poisoned {
786            return Err(ModelEventStreamError::Poisoned);
787        }
788        if self.response.is_some() {
789            self.poisoned = true;
790            return Err(ModelEventStreamError::AlreadyCompleted);
791        }
792        if let Err(error) = self.try_push(event) {
793            self.poisoned = true;
794            return Err(error);
795        }
796        Ok(())
797    }
798
799    /// Returns the terminal response after a complete stream.
800    ///
801    /// # Errors
802    ///
803    /// Returns an error when a prior event poisoned the state machine or the
804    /// transport ended before a valid `completed` event.
805    pub fn finish(self) -> Result<ModelResponse, ModelEventStreamError> {
806        if self.poisoned {
807            return Err(ModelEventStreamError::Poisoned);
808        }
809        self.response.ok_or(ModelEventStreamError::UnexpectedEnd {
810            next_sequence: self.next_sequence,
811        })
812    }
813
814    /// Returns the expected attempt identity.
815    #[must_use]
816    pub const fn attempt_id(&self) -> AttemptId {
817        self.attempt_id
818    }
819
820    /// Returns the sequence required for the next event.
821    #[must_use]
822    pub const fn next_sequence(&self) -> ExecutionCount {
823        self.next_sequence
824    }
825
826    /// Returns whether the state machine accepted a valid terminal event.
827    #[must_use]
828    pub const fn is_complete(&self) -> bool {
829        self.response.is_some() && !self.poisoned
830    }
831
832    /// Returns whether a rejected event permanently invalidated this stream.
833    #[must_use]
834    pub const fn is_poisoned(&self) -> bool {
835        self.poisoned
836    }
837
838    fn try_push(&mut self, event: ModelEvent) -> Result<(), ModelEventStreamError> {
839        let ModelEvent {
840            attempt_id,
841            sequence,
842            event,
843        } = event;
844        if attempt_id != self.attempt_id {
845            return Err(ModelEventStreamError::AttemptMismatch {
846                expected: self.attempt_id,
847                actual: attempt_id,
848            });
849        }
850        if sequence != self.next_sequence {
851            return Err(ModelEventStreamError::SequenceMismatch {
852                expected: self.next_sequence,
853                actual: sequence,
854            });
855        }
856
857        let is_start = matches!(event, ModelEventKind::Started { .. });
858        if !self.started && !is_start {
859            return Err(ModelEventStreamError::EventBeforeStart);
860        }
861        if self.started && is_start {
862            return Err(ModelEventStreamError::DuplicateStart);
863        }
864
865        match event {
866            ModelEventKind::Started { provenance } => self.process_start(provenance)?,
867            ModelEventKind::OutputStarted {
868                output_index,
869                start,
870            } => self.process_output_start(output_index, *start)?,
871            ModelEventKind::OutputDelta {
872                output_index,
873                delta,
874            } => self.process_output_delta(output_index, delta)?,
875            ModelEventKind::OutputCompleted { output_index } => {
876                self.process_output_completed(output_index)?;
877            }
878            ModelEventKind::UsageUpdated { usage } => self.process_usage(usage)?,
879            ModelEventKind::Completed {
880                finish_reason,
881                usage,
882                extensions,
883            } => self.process_completed(finish_reason, usage, extensions)?,
884        }
885
886        self.next_sequence = ExecutionCount::new(
887            sequence
888                .get()
889                .checked_add(1)
890                .expect("intrinsically bounded model event sequence cannot overflow"),
891        );
892        Ok(())
893    }
894
895    fn process_start(
896        &mut self,
897        provenance: ModelResponseProvenance,
898    ) -> Result<(), ModelEventStreamError> {
899        let expected = self.descriptor.metadata().identity();
900        if provenance.model() != expected {
901            return Err(invalid_response(
902                ModelResponseError::ModelIdentityMismatch {
903                    expected: Box::new(expected.clone()),
904                    actual: Box::new(provenance.model().clone()),
905                },
906            ));
907        }
908        self.provenance = Some(provenance);
909        self.started = true;
910        Ok(())
911    }
912
913    fn process_output_start(
914        &mut self,
915        output_index: ExecutionCount,
916        start: ModelOutputStart,
917    ) -> Result<(), ModelEventStreamError> {
918        let expected = ExecutionCount::new(self.slots.len() as u64);
919        if output_index != expected {
920            return Err(ModelEventStreamError::OutputStartOutOfOrder {
921                expected,
922                actual: output_index,
923            });
924        }
925
926        match start.kind() {
927            ModelOutputItemKind::Content | ModelOutputItemKind::ReasoningSummary => {
928                if self.content_items == ModelResponse::MAX_CONTENT_ITEMS {
929                    return Err(invalid_response(ModelResponseError::TooManyContentItems {
930                        max: ModelResponse::MAX_CONTENT_ITEMS,
931                        observed: ModelResponse::MAX_CONTENT_ITEMS + 1,
932                    }));
933                }
934                self.content_items += 1;
935            }
936            ModelOutputItemKind::ToolCall => {
937                if self.tool_calls == ModelResponse::MAX_TOOL_CALLS {
938                    return Err(invalid_response(ModelResponseError::TooManyToolCalls {
939                        max: ModelResponse::MAX_TOOL_CALLS,
940                        observed: ModelResponse::MAX_TOOL_CALLS + 1,
941                    }));
942                }
943                let next_calls = self.tool_calls + 1;
944                if ExecutionCount::new(next_calls as u64)
945                    > self.request.max_tool_calls_per_response()
946                {
947                    return Err(invalid_response(
948                        ModelResponseError::ToolCallsExceedRequest {
949                            maximum: self.request.max_tool_calls_per_response(),
950                            actual: ExecutionCount::new(next_calls as u64),
951                        },
952                    ));
953                }
954                if let ModelOutputStart::ToolCall {
955                    provider_call_id: Some(provider_call_id),
956                    ..
957                } = &start
958                {
959                    if !self.provider_call_ids.insert(provider_call_id.clone()) {
960                        return Err(invalid_response(
961                            ModelResponseError::DuplicateProviderToolCallId,
962                        ));
963                    }
964                }
965                self.tool_calls = next_calls;
966            }
967        }
968
969        let observed = self
970            .retained_inline_bytes
971            .checked_add(start.inline_header_bytes())
972            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
973        validate_aggregate_payload(observed)?;
974        self.retained_inline_bytes = observed;
975        self.slots.push(OutputSlot::Active {
976            start,
977            buffer: String::new(),
978        });
979        Ok(())
980    }
981
982    fn process_output_delta(
983        &mut self,
984        output_index: ExecutionCount,
985        delta: ModelOutputDelta,
986    ) -> Result<(), ModelEventStreamError> {
987        let index = usize::try_from(output_index.get())
988            .expect("intrinsically bounded model output index fits usize");
989        let slot = self
990            .slots
991            .get_mut(index)
992            .ok_or(ModelEventStreamError::OutputNotStarted { output_index })?;
993        let (start, buffer) = match slot {
994            OutputSlot::Active { start, buffer } => (start, buffer),
995            OutputSlot::Completed(_) | OutputSlot::Transitioning => {
996                return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
997            }
998        };
999
1000        let actual_kind = delta.kind();
1001        let Some(expected_kind) = start.delta_kind() else {
1002            return Err(ModelEventStreamError::OutputDoesNotAcceptDeltas { output_index });
1003        };
1004        if actual_kind != expected_kind {
1005            return Err(ModelEventStreamError::DeltaKindMismatch {
1006                output_index,
1007                expected: expected_kind,
1008                actual: actual_kind,
1009            });
1010        }
1011
1012        let chunk = delta.into_chunk();
1013        let observed_item = buffer
1014            .len()
1015            .checked_add(chunk.len_bytes())
1016            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1017        let maximum = match expected_kind {
1018            ModelOutputDeltaKind::Text | ModelOutputDeltaKind::ReasoningSummary => {
1019                TextContent::MAX_BYTES
1020            }
1021            ModelOutputDeltaKind::Json | ModelOutputDeltaKind::ToolArguments => {
1022                JsonLimits::DEFAULT.max_bytes()
1023            }
1024        };
1025        if observed_item > maximum {
1026            return Err(ModelEventStreamError::OutputPayloadTooLarge {
1027                output_index,
1028                maximum,
1029                actual: observed_item,
1030            });
1031        }
1032        let observed_total = self
1033            .retained_inline_bytes
1034            .checked_add(chunk.len_bytes())
1035            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1036        validate_aggregate_payload(observed_total)?;
1037
1038        buffer.push_str(chunk.as_str());
1039        self.retained_inline_bytes = observed_total;
1040        Ok(())
1041    }
1042
1043    fn process_output_completed(
1044        &mut self,
1045        output_index: ExecutionCount,
1046    ) -> Result<(), ModelEventStreamError> {
1047        let index = usize::try_from(output_index.get())
1048            .expect("intrinsically bounded model output index fits usize");
1049        let slot = self
1050            .slots
1051            .get_mut(index)
1052            .ok_or(ModelEventStreamError::OutputNotStarted { output_index })?;
1053        let active = match mem::replace(slot, OutputSlot::Transitioning) {
1054            OutputSlot::Active { start, buffer } => (start, buffer),
1055            OutputSlot::Completed(item) => {
1056                *slot = OutputSlot::Completed(item);
1057                return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
1058            }
1059            OutputSlot::Transitioning => {
1060                return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
1061            }
1062        };
1063        let old_bytes = active
1064            .0
1065            .inline_header_bytes()
1066            .checked_add(active.1.len())
1067            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1068        let item = finish_output_item(output_index, active.0, active.1)?;
1069        let base = self
1070            .retained_inline_bytes
1071            .checked_sub(old_bytes)
1072            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1073        let observed = base
1074            .checked_add(item.inline_payload_bytes())
1075            .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1076        validate_aggregate_payload(observed)?;
1077        self.retained_inline_bytes = observed;
1078        *slot = OutputSlot::Completed(item);
1079        Ok(())
1080    }
1081
1082    fn process_usage(&mut self, usage: ModelUsage) -> Result<(), ModelEventStreamError> {
1083        validate_usage_progress(self.last_usage.as_ref(), &usage)?;
1084        validate_usage_limits(self.request, &usage)?;
1085        self.last_usage = Some(usage);
1086        Ok(())
1087    }
1088
1089    fn process_completed(
1090        &mut self,
1091        finish_reason: ModelFinishReason,
1092        usage: ModelUsage,
1093        extensions: Extensions,
1094    ) -> Result<(), ModelEventStreamError> {
1095        validate_usage_progress(self.last_usage.as_ref(), &usage)?;
1096        validate_usage_limits(self.request, &usage)?;
1097        if let Some((index, _)) = self
1098            .slots
1099            .iter()
1100            .enumerate()
1101            .find(|(_, slot)| !matches!(slot, OutputSlot::Completed(_)))
1102        {
1103            return Err(ModelEventStreamError::OutputStillOpen {
1104                output_index: ExecutionCount::new(index as u64),
1105            });
1106        }
1107
1108        let provenance = self
1109            .provenance
1110            .take()
1111            .expect("a terminal model event is impossible before a validated start");
1112        let output = mem::take(&mut self.slots)
1113            .into_iter()
1114            .map(|slot| match slot {
1115                OutputSlot::Completed(item) => item,
1116                OutputSlot::Active { .. } | OutputSlot::Transitioning => {
1117                    unreachable!("all streamed model outputs were checked complete")
1118                }
1119            })
1120            .collect::<Vec<_>>();
1121        let response = ModelResponse::new(
1122            provenance,
1123            self.descriptor,
1124            self.request,
1125            output,
1126            finish_reason,
1127            usage,
1128            extensions,
1129        )
1130        .map_err(invalid_response)?;
1131        debug_assert_eq!(
1132            response.inline_payload_bytes().get(),
1133            self.retained_inline_bytes as u64
1134        );
1135        self.response = Some(response);
1136        Ok(())
1137    }
1138}
1139
1140impl fmt::Debug for ModelEventAccumulator<'_> {
1141    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1142        formatter
1143            .debug_struct("ModelEventAccumulator")
1144            .field("attempt_id", &self.attempt_id)
1145            .field("next_sequence", &self.next_sequence)
1146            .field("started", &self.started)
1147            .field("poisoned", &self.poisoned)
1148            .field("output_slots", &self.slots.len())
1149            .field("content_items", &self.content_items)
1150            .field("tool_calls", &self.tool_calls)
1151            .field("retained_inline_bytes", &self.retained_inline_bytes)
1152            .field("has_usage", &self.last_usage.is_some())
1153            .field("complete", &self.is_complete())
1154            .finish_non_exhaustive()
1155    }
1156}
1157
1158fn finish_output_item(
1159    output_index: ExecutionCount,
1160    start: ModelOutputStart,
1161    buffer: String,
1162) -> Result<ModelOutputItem, ModelEventStreamError> {
1163    match start {
1164        ModelOutputStart::Text { language, metadata } => {
1165            let content =
1166                TextContent::from_string(buffer, language, metadata).map_err(|error| {
1167                    ModelEventStreamError::InvalidTextPayload {
1168                        output_index,
1169                        error,
1170                    }
1171                })?;
1172            ModelOutputItem::content(ContentPart::Text(content)).map_err(|error| {
1173                ModelEventStreamError::InvalidOutputItem {
1174                    output_index,
1175                    error,
1176                }
1177            })
1178        }
1179        ModelOutputStart::Json { schema, metadata } => {
1180            let value = BoundedJson::from_slice(buffer.as_bytes()).map_err(|error| {
1181                ModelEventStreamError::InvalidJsonPayload {
1182                    output_index,
1183                    error,
1184                }
1185            })?;
1186            ModelOutputItem::content(ContentPart::Json(JsonContent::new(value, schema, metadata)))
1187                .map_err(|error| ModelEventStreamError::InvalidOutputItem {
1188                    output_index,
1189                    error,
1190                })
1191        }
1192        ModelOutputStart::Artifact(artifact) => {
1193            debug_assert!(buffer.is_empty());
1194            ModelOutputItem::content(ContentPart::Artifact(artifact)).map_err(|error| {
1195                ModelEventStreamError::InvalidOutputItem {
1196                    output_index,
1197                    error,
1198                }
1199            })
1200        }
1201        ModelOutputStart::ReasoningSummary { language, metadata } => {
1202            let content =
1203                TextContent::from_string(buffer, language, metadata).map_err(|error| {
1204                    ModelEventStreamError::InvalidTextPayload {
1205                        output_index,
1206                        error,
1207                    }
1208                })?;
1209            ModelOutputItem::reasoning_summary(content).map_err(|error| {
1210                ModelEventStreamError::InvalidOutputItem {
1211                    output_index,
1212                    error,
1213                }
1214            })
1215        }
1216        ModelOutputStart::ToolCall {
1217            tool,
1218            provider_call_id,
1219            extensions,
1220        } => {
1221            let arguments = BoundedJson::from_slice(buffer.as_bytes()).map_err(|error| {
1222                ModelEventStreamError::InvalidJsonPayload {
1223                    output_index,
1224                    error,
1225                }
1226            })?;
1227            let proposal =
1228                ModelToolCallProposal::new(tool, provider_call_id, arguments, extensions).map_err(
1229                    |error| ModelEventStreamError::InvalidToolCall {
1230                        output_index,
1231                        error,
1232                    },
1233                )?;
1234            Ok(ModelOutputItem::tool_call(proposal))
1235        }
1236    }
1237}
1238
1239fn validate_aggregate_payload(observed: usize) -> Result<(), ModelEventStreamError> {
1240    let maximum = ModelResponse::MAX_INLINE_PAYLOAD_BYTES;
1241    if observed as u64 > maximum.get() {
1242        return Err(ModelEventStreamError::InlinePayloadTooLarge {
1243            maximum,
1244            observed: ByteCount::new(observed as u64),
1245        });
1246    }
1247    Ok(())
1248}
1249
1250fn validate_usage_limits(
1251    request: &ModelRequest,
1252    usage: &ModelUsage,
1253) -> Result<(), ModelEventStreamError> {
1254    if usage.input_tokens() > request.limits().max_input_tokens() {
1255        return Err(invalid_response(
1256            ModelResponseError::InputUsageExceedsRequest {
1257                maximum: request.limits().max_input_tokens(),
1258                actual: usage.input_tokens(),
1259            },
1260        ));
1261    }
1262    if usage.output_tokens() > request.limits().max_output_tokens() {
1263        return Err(invalid_response(
1264            ModelResponseError::OutputUsageExceedsRequest {
1265                maximum: request.limits().max_output_tokens(),
1266                actual: usage.output_tokens(),
1267            },
1268        ));
1269    }
1270    Ok(())
1271}
1272
1273fn validate_usage_progress(
1274    previous: Option<&ModelUsage>,
1275    actual: &ModelUsage,
1276) -> Result<(), ModelEventStreamError> {
1277    let Some(previous) = previous else {
1278        return Ok(());
1279    };
1280    validate_required_usage_field(
1281        ModelUsageField::InputTokens,
1282        previous.input_tokens(),
1283        actual.input_tokens(),
1284    )?;
1285    validate_optional_usage_field(
1286        ModelUsageField::CachedInputTokens,
1287        previous.cached_input_tokens(),
1288        actual.cached_input_tokens(),
1289    )?;
1290    validate_required_usage_field(
1291        ModelUsageField::OutputTokens,
1292        previous.output_tokens(),
1293        actual.output_tokens(),
1294    )?;
1295    validate_optional_usage_field(
1296        ModelUsageField::ReasoningTokens,
1297        previous.reasoning_tokens(),
1298        actual.reasoning_tokens(),
1299    )
1300}
1301
1302fn validate_required_usage_field(
1303    field: ModelUsageField,
1304    previous: TokenCount,
1305    actual: TokenCount,
1306) -> Result<(), ModelEventStreamError> {
1307    if actual < previous {
1308        return Err(ModelEventStreamError::UsageDecreased {
1309            field,
1310            previous,
1311            actual,
1312        });
1313    }
1314    Ok(())
1315}
1316
1317fn validate_optional_usage_field(
1318    field: ModelUsageField,
1319    previous: Option<TokenCount>,
1320    actual: Option<TokenCount>,
1321) -> Result<(), ModelEventStreamError> {
1322    match (previous, actual) {
1323        (Some(_), None) => Err(ModelEventStreamError::UsageBreakdownDisappeared { field }),
1324        (Some(previous), Some(actual)) => validate_required_usage_field(field, previous, actual),
1325        (None, None | Some(_)) => Ok(()),
1326    }
1327}
1328
1329fn invalid_response(error: ModelResponseError) -> ModelEventStreamError {
1330    ModelEventStreamError::InvalidResponse { error }
1331}
1332
1333/// Invalid sequence or content in one normalized model event stream.
1334#[derive(Clone, Debug, Eq, Error, PartialEq)]
1335#[non_exhaustive]
1336pub enum ModelEventStreamError {
1337    /// The accumulator was constructed for a complete-only request.
1338    #[error("model event accumulator requires a streaming model request")]
1339    RequestNotStreaming,
1340    /// The selected descriptor could not satisfy the exact request.
1341    #[error("model descriptor cannot satisfy streaming request: {mismatch}")]
1342    CapabilityMismatch {
1343        /// Deterministic set of every unmet provider-neutral requirement.
1344        #[source]
1345        mismatch: ModelCapabilityMismatch,
1346    },
1347    /// A prior rejected event permanently invalidated the stream.
1348    #[error("model event accumulator is poisoned by a prior validation failure")]
1349    Poisoned,
1350    /// An event followed an already accepted terminal event.
1351    #[error("model event stream is already complete")]
1352    AlreadyCompleted,
1353    /// An event belonged to a different attempt.
1354    #[error("model event attempt {actual} does not match expected attempt {expected}")]
1355    AttemptMismatch {
1356        /// Immutable accumulator attempt.
1357        expected: AttemptId,
1358        /// Rejected event attempt.
1359        actual: AttemptId,
1360    },
1361    /// The event sequence was duplicated, skipped, or reordered.
1362    #[error("model event sequence {actual} does not match expected sequence {expected}")]
1363    SequenceMismatch {
1364        /// Next required zero-based sequence.
1365        expected: ExecutionCount,
1366        /// Rejected event sequence.
1367        actual: ExecutionCount,
1368    },
1369    /// A non-start event appeared before stream provenance.
1370    #[error("model event stream must begin with started")]
1371    EventBeforeStart,
1372    /// A second start event attempted to replace immutable provenance.
1373    #[error("model event stream contains more than one started event")]
1374    DuplicateStart,
1375    /// Output items were not registered in contiguous provider order.
1376    #[error("model output start index {actual} does not match next index {expected}")]
1377    OutputStartOutOfOrder {
1378        /// Next required output position.
1379        expected: ExecutionCount,
1380        /// Rejected output position.
1381        actual: ExecutionCount,
1382    },
1383    /// A delta or completion named an output that had not started.
1384    #[error("model output index {output_index} has not started")]
1385    OutputNotStarted {
1386        /// Unknown zero-based output position.
1387        output_index: ExecutionCount,
1388    },
1389    /// A completed output received another delta or completion.
1390    #[error("model output index {output_index} is already complete")]
1391    OutputAlreadyCompleted {
1392        /// Closed zero-based output position.
1393        output_index: ExecutionCount,
1394    },
1395    /// An artifact reference received an inline fragment.
1396    #[error("model output index {output_index} does not accept deltas")]
1397    OutputDoesNotAcceptDeltas {
1398        /// Artifact output position.
1399        output_index: ExecutionCount,
1400    },
1401    /// A fragment type did not match its immutable output header.
1402    #[error("model output index {output_index} expected {expected:?} delta, got {actual:?}")]
1403    DeltaKindMismatch {
1404        /// Active zero-based output position.
1405        output_index: ExecutionCount,
1406        /// Fragment classification fixed by the start event.
1407        expected: ModelOutputDeltaKind,
1408        /// Rejected fragment classification.
1409        actual: ModelOutputDeltaKind,
1410    },
1411    /// One accumulated inline item exceeded its parser/content ceiling.
1412    #[error("model output index {output_index} accumulated {actual} bytes; maximum is {maximum}")]
1413    OutputPayloadTooLarge {
1414        /// Active zero-based output position.
1415        output_index: ExecutionCount,
1416        /// Immutable per-item byte ceiling.
1417        maximum: usize,
1418        /// First rejected accumulated byte count.
1419        actual: usize,
1420    },
1421    /// Payload byte accounting could not be represented.
1422    #[error("model event stream payload-byte accounting overflowed")]
1423    PayloadAccountingOverflow,
1424    /// Aggregate retained response and active-fragment bytes exceeded the hard ceiling.
1425    #[error("model event stream retains {observed} inline bytes; maximum is {maximum}")]
1426    InlinePayloadTooLarge {
1427        /// Immutable aggregate ceiling.
1428        maximum: ByteCount,
1429        /// First rejected aggregate.
1430        observed: ByteCount,
1431    },
1432    /// Completed text or reasoning bytes violated the text contract.
1433    #[error("model output index {output_index} contains invalid text: {error}")]
1434    InvalidTextPayload {
1435        /// Zero-based output position.
1436        output_index: ExecutionCount,
1437        /// Bounded text validation failure.
1438        #[source]
1439        error: TextContentError,
1440    },
1441    /// Completed JSON or tool-argument fragments did not form one bounded value.
1442    #[error("model output index {output_index} contains invalid JSON: {error}")]
1443    InvalidJsonPayload {
1444        /// Zero-based output position.
1445        output_index: ExecutionCount,
1446        /// Exact bounded-parser failure.
1447        #[source]
1448        error: BoundedJsonError,
1449    },
1450    /// Complete tool arguments were not a valid proposal object.
1451    #[error("model output index {output_index} contains an invalid tool call: {error}")]
1452    InvalidToolCall {
1453        /// Zero-based output position.
1454        output_index: ExecutionCount,
1455        /// Proposal validation failure.
1456        #[source]
1457        error: ModelToolCallProposalError,
1458    },
1459    /// A materialized output item carried invalid intrinsic metadata.
1460    #[error("model output index {output_index} is invalid: {error}")]
1461    InvalidOutputItem {
1462        /// Zero-based output position.
1463        output_index: ExecutionCount,
1464        /// Output-item validation failure.
1465        #[source]
1466        error: ModelOutputItemError,
1467    },
1468    /// A cumulative usage counter moved backwards.
1469    #[error("model usage {field:?} decreased from {previous} to {actual}")]
1470    UsageDecreased {
1471        /// Regressed normalized dimension.
1472        field: ModelUsageField,
1473        /// Last accepted cumulative count.
1474        previous: TokenCount,
1475        /// Rejected smaller cumulative count.
1476        actual: TokenCount,
1477    },
1478    /// A previously known optional usage breakdown became absent.
1479    #[error("model usage {field:?} disappeared after it was reported")]
1480    UsageBreakdownDisappeared {
1481        /// Removed optional breakdown.
1482        field: ModelUsageField,
1483    },
1484    /// The terminal event arrived while an output item was still active.
1485    #[error("model output index {output_index} is still open at stream completion")]
1486    OutputStillOpen {
1487        /// First incomplete zero-based output position.
1488        output_index: ExecutionCount,
1489    },
1490    /// The assembled terminal response violated its descriptor/request contract.
1491    #[error("invalid assembled model response: {error}")]
1492    InvalidResponse {
1493        /// Existing complete-response invariant failure.
1494        #[source]
1495        error: ModelResponseError,
1496    },
1497    /// The transport ended without an accepted semantic terminal event.
1498    #[error("model event stream ended before completion; next sequence is {next_sequence}")]
1499    UnexpectedEnd {
1500        /// Sequence that would have been required next.
1501        next_sequence: ExecutionCount,
1502    },
1503}
1504
1505#[cfg(test)]
1506mod tests {
1507    use super::*;
1508    use crate::{
1509        Instruction, ModelProviderModelId, ModelProviderResponseId, ModelRequestBuilder,
1510        ModelRequestLimits, ModelTextOutputFormat, ModelToolSelection, SecurityLabel,
1511        ToolDescriptor,
1512    };
1513    use proptest::prelude::*;
1514    use serde_json::{Value, from_value, json, to_value};
1515
1516    const MEBIBYTE: u64 = 1024 * 1024;
1517
1518    fn fixture(path: &[&str], source: &str) -> Value {
1519        let mut value = serde_json::from_str::<Value>(source).unwrap();
1520        for segment in path {
1521            value = value[*segment].clone();
1522        }
1523        value
1524    }
1525
1526    fn descriptor(name: &str) -> ModelDescriptor {
1527        let values = fixture(
1528            &["descriptors", "valid"],
1529            include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1530        );
1531        let mut value = values[0].clone();
1532        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1533        value["capabilities"] = fixture(
1534            &["capabilities", "valid"],
1535            include_str!("../tests/fixtures/core-model-capability-v1.json"),
1536        )[1]
1537        .clone();
1538        from_value(value).unwrap()
1539    }
1540
1541    fn non_streaming_descriptor(name: &str) -> ModelDescriptor {
1542        let values = fixture(
1543            &["descriptors", "valid"],
1544            include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1545        );
1546        let mut value = values[0].clone();
1547        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1548        from_value(value).unwrap()
1549    }
1550
1551    fn instruction() -> Instruction {
1552        let values = fixture(
1553            &["instructions", "valid"],
1554            include_str!("../tests/fixtures/core-message-v1.json"),
1555        );
1556        from_value(values[0].clone()).unwrap()
1557    }
1558
1559    fn tool(name: &str) -> ToolDescriptor {
1560        let values = fixture(
1561            &["descriptors", "valid"],
1562            include_str!("../tests/fixtures/core-tool-v1.json"),
1563        );
1564        let mut value = values[0].clone();
1565        value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1566        from_value(value).unwrap()
1567    }
1568
1569    fn limits() -> ModelRequestLimits {
1570        ModelRequestLimits::new(
1571            TokenCount::new(8_192),
1572            TokenCount::new(1_024),
1573            ByteCount::new(MEBIBYTE),
1574        )
1575        .unwrap()
1576    }
1577
1578    fn streaming_builder() -> ModelRequestBuilder {
1579        ModelRequest::builder(limits())
1580            .instruction(instruction())
1581            .response_mode(ModelResponseMode::Streaming)
1582    }
1583
1584    fn streaming_request() -> ModelRequest {
1585        streaming_builder().build().unwrap()
1586    }
1587
1588    fn attempt() -> AttemptId {
1589        "01912345-6789-7abc-8def-0123456789ab".parse().unwrap()
1590    }
1591
1592    fn provenance(descriptor: &ModelDescriptor) -> ModelResponseProvenance {
1593        ModelResponseProvenance::new(
1594            attempt(),
1595            descriptor.metadata().identity().clone(),
1596            Some(ModelProviderModelId::new("provider/model-v1").unwrap()),
1597            Some(ModelProviderResponseId::new("response_opaque-42").unwrap()),
1598        )
1599    }
1600
1601    fn model_metadata() -> ContentMetadata {
1602        ContentMetadata::untrusted(
1603            ContentSource::Model,
1604            SecurityLabel::new("internal/model-output").unwrap(),
1605        )
1606    }
1607
1608    fn usage(input: u64, cached: Option<u64>, output: u64, reasoning: Option<u64>) -> ModelUsage {
1609        ModelUsage::new(
1610            TokenCount::new(input),
1611            cached.map(TokenCount::new),
1612            TokenCount::new(output),
1613            reasoning.map(TokenCount::new),
1614        )
1615        .unwrap()
1616    }
1617
1618    fn event(sequence: u64, event: ModelEventKind) -> ModelEvent {
1619        ModelEvent::new(attempt(), ExecutionCount::new(sequence), event).unwrap()
1620    }
1621
1622    fn started(sequence: u64, descriptor: &ModelDescriptor) -> ModelEvent {
1623        event(
1624            sequence,
1625            ModelEventKind::Started {
1626                provenance: provenance(descriptor),
1627            },
1628        )
1629    }
1630
1631    fn text_start(sequence: u64, index: u64) -> ModelEvent {
1632        event(
1633            sequence,
1634            ModelEventKind::OutputStarted {
1635                output_index: ExecutionCount::new(index),
1636                start: Box::new(ModelOutputStart::text(None, model_metadata()).unwrap()),
1637            },
1638        )
1639    }
1640
1641    fn text_delta(sequence: u64, index: u64, value: &str) -> ModelEvent {
1642        event(
1643            sequence,
1644            ModelEventKind::OutputDelta {
1645                output_index: ExecutionCount::new(index),
1646                delta: ModelOutputDelta::Text(ModelStreamChunk::new(value).unwrap()),
1647            },
1648        )
1649    }
1650
1651    fn output_completed(sequence: u64, index: u64) -> ModelEvent {
1652        event(
1653            sequence,
1654            ModelEventKind::OutputCompleted {
1655                output_index: ExecutionCount::new(index),
1656            },
1657        )
1658    }
1659
1660    fn completed(sequence: u64, finish_reason: ModelFinishReason, usage: ModelUsage) -> ModelEvent {
1661        event(
1662            sequence,
1663            ModelEventKind::Completed {
1664                finish_reason,
1665                usage,
1666                extensions: Extensions::default(),
1667            },
1668        )
1669    }
1670
1671    #[test]
1672    fn stream_chunks_are_exact_bounded_redacted_values() {
1673        let chunk = ModelStreamChunk::new("confidential\n片段").unwrap();
1674        assert_eq!(chunk.as_str(), "confidential\n片段");
1675        assert_eq!(chunk.len_bytes(), "confidential\n片段".len());
1676        assert_eq!(to_value(&chunk).unwrap(), "confidential\n片段");
1677        assert_eq!(
1678            from_value::<ModelStreamChunk>(json!("exact"))
1679                .unwrap()
1680                .as_str(),
1681            "exact"
1682        );
1683        assert!(!format!("{chunk:?}").contains("confidential"));
1684
1685        assert_eq!(ModelStreamChunk::new(""), Err(ModelStreamChunkError::Empty));
1686        assert!(matches!(
1687            ModelStreamChunk::new("x".repeat(ModelStreamChunk::MAX_BYTES + 1)),
1688            Err(ModelStreamChunkError::TooLong { .. })
1689        ));
1690        assert!(matches!(
1691            ModelStreamChunk::new("bad\u{0000}"),
1692            Err(ModelStreamChunkError::DisallowedCodePoint { .. })
1693        ));
1694        assert!(matches!(
1695            ModelStreamChunk::new("bad\u{ffff}"),
1696            Err(ModelStreamChunkError::DisallowedCodePoint { .. })
1697        ));
1698        assert!(from_value::<ModelStreamChunk>(json!(42)).is_err());
1699
1700        let schema = to_value(schemars::schema_for!(ModelStreamChunk)).unwrap();
1701        assert_eq!(schema["minLength"], 1);
1702        assert_eq!(schema["maxLength"], ModelStreamChunk::MAX_BYTES);
1703    }
1704
1705    #[test]
1706    fn output_headers_reject_false_trust_and_wrong_sources() {
1707        let controlled = ContentMetadata::new(
1708            ContentSource::Model,
1709            crate::ContentTrust::ApplicationControlled,
1710            SecurityLabel::new("internal/model-output").unwrap(),
1711            crate::RedactionState::NotApplied,
1712        );
1713        assert!(matches!(
1714            ModelOutputStart::text(None, controlled),
1715            Err(ModelOutputItemError::InvalidTrust { .. })
1716        ));
1717
1718        let wrong = ContentMetadata::untrusted(
1719            ContentSource::User,
1720            SecurityLabel::new("internal/model-output").unwrap(),
1721        );
1722        assert!(matches!(
1723            ModelOutputStart::json(None, wrong),
1724            Err(ModelOutputItemError::InvalidSource { .. })
1725        ));
1726
1727        let mut encoded =
1728            to_value(ModelOutputStart::text(None, model_metadata()).unwrap()).unwrap();
1729        encoded["content"]["metadata"]["trust"] = Value::from("application_controlled");
1730        assert!(from_value::<ModelOutputStart>(encoded).is_err());
1731    }
1732
1733    #[test]
1734    fn event_envelopes_enforce_attempt_and_resource_bounds() {
1735        let descriptor = descriptor("models.primary");
1736        let other_attempt = "01912345-6789-7abc-8def-0123456789ac".parse().unwrap();
1737        assert!(matches!(
1738            ModelEvent::new(
1739                other_attempt,
1740                ExecutionCount::ZERO,
1741                ModelEventKind::Started {
1742                    provenance: provenance(&descriptor)
1743                }
1744            ),
1745            Err(ModelEventError::StartedAttemptMismatch { .. })
1746        ));
1747        assert!(matches!(
1748            ModelEvent::new(
1749                attempt(),
1750                ModelEvent::MAX_EVENTS_PER_ATTEMPT,
1751                ModelEventKind::UsageUpdated {
1752                    usage: usage(1, None, 0, None)
1753                }
1754            ),
1755            Err(ModelEventError::SequenceOutOfRange { .. })
1756        ));
1757        assert!(matches!(
1758            ModelEvent::new(
1759                attempt(),
1760                ExecutionCount::ZERO,
1761                ModelEventKind::OutputCompleted {
1762                    output_index: ExecutionCount::new(ModelResponse::MAX_OUTPUT_ITEMS as u64)
1763                }
1764            ),
1765            Err(ModelEventError::OutputIndexOutOfRange { .. })
1766        ));
1767
1768        let encoded = to_value(started(0, &descriptor)).unwrap();
1769        assert_eq!(encoded["sequence"], "0");
1770        assert_eq!(
1771            from_value::<ModelEvent>(encoded.clone()).unwrap(),
1772            started(0, &descriptor)
1773        );
1774        let mut unknown = encoded;
1775        unknown["unknown"] = Value::Bool(true);
1776        assert!(from_value::<ModelEvent>(unknown).is_err());
1777    }
1778
1779    #[test]
1780    fn text_stream_converges_to_one_bound_response() {
1781        let descriptor = descriptor("models.primary");
1782        let request = streaming_request();
1783        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1784        let events = [
1785            started(0, &descriptor),
1786            text_start(1, 0),
1787            text_delta(2, 0, "hel"),
1788            event(
1789                3,
1790                ModelEventKind::UsageUpdated {
1791                    usage: usage(120, Some(20), 1, None),
1792                },
1793            ),
1794            text_delta(4, 0, "lo"),
1795            output_completed(5, 0),
1796            completed(
1797                6,
1798                ModelFinishReason::Completed,
1799                usage(120, Some(20), 2, None),
1800            ),
1801        ];
1802        for event in events {
1803            accumulator.push(event).unwrap();
1804        }
1805
1806        assert!(accumulator.is_complete());
1807        let response = accumulator.finish().unwrap();
1808        assert_eq!(response.provenance(), &provenance(&descriptor));
1809        assert_eq!(response.finish_reason(), ModelFinishReason::Completed);
1810        assert_eq!(response.usage(), &usage(120, Some(20), 2, None));
1811        assert_eq!(response.inline_payload_bytes(), ByteCount::new(5));
1812        assert_eq!(
1813            response.output()[0]
1814                .as_content()
1815                .and_then(|content| match content {
1816                    ContentPart::Text(text) => Some(text.text()),
1817                    ContentPart::Json(_) | ContentPart::Artifact(_) => None,
1818                }),
1819            Some("hello")
1820        );
1821    }
1822
1823    #[test]
1824    fn json_fragments_are_parsed_once_when_the_item_closes() {
1825        let descriptor = descriptor("models.primary");
1826        let request = streaming_builder()
1827            .text_output_format(Some(ModelTextOutputFormat::json()))
1828            .build()
1829            .unwrap();
1830        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1831        let events = [
1832            started(0, &descriptor),
1833            event(
1834                1,
1835                ModelEventKind::OutputStarted {
1836                    output_index: ExecutionCount::ZERO,
1837                    start: Box::new(ModelOutputStart::json(None, model_metadata()).unwrap()),
1838                },
1839            ),
1840            event(
1841                2,
1842                ModelEventKind::OutputDelta {
1843                    output_index: ExecutionCount::ZERO,
1844                    delta: ModelOutputDelta::Json(ModelStreamChunk::new("{\"answer\":").unwrap()),
1845                },
1846            ),
1847            event(
1848                3,
1849                ModelEventKind::OutputDelta {
1850                    output_index: ExecutionCount::ZERO,
1851                    delta: ModelOutputDelta::Json(ModelStreamChunk::new("42}").unwrap()),
1852                },
1853            ),
1854            output_completed(4, 0),
1855            completed(5, ModelFinishReason::Completed, usage(10, None, 3, None)),
1856        ];
1857        for event in events {
1858            accumulator.push(event).unwrap();
1859        }
1860        let response = accumulator.finish().unwrap();
1861        let json = match response.output()[0].as_content().unwrap() {
1862            ContentPart::Json(json) => json,
1863            ContentPart::Text(_) | ContentPart::Artifact(_) => panic!("expected JSON"),
1864        };
1865        assert_eq!(json.value().as_value(), &json!({"answer": 42}));
1866    }
1867
1868    #[test]
1869    fn malformed_or_duplicate_json_poison_the_stream() {
1870        for raw in ["{", "{\"a\":1,\"a\":2}", "{} trailing"] {
1871            let descriptor = descriptor("models.primary");
1872            let request = streaming_builder()
1873                .text_output_format(Some(ModelTextOutputFormat::json()))
1874                .build()
1875                .unwrap();
1876            let mut accumulator =
1877                ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1878            accumulator.push(started(0, &descriptor)).unwrap();
1879            accumulator
1880                .push(event(
1881                    1,
1882                    ModelEventKind::OutputStarted {
1883                        output_index: ExecutionCount::ZERO,
1884                        start: Box::new(ModelOutputStart::json(None, model_metadata()).unwrap()),
1885                    },
1886                ))
1887                .unwrap();
1888            accumulator
1889                .push(event(
1890                    2,
1891                    ModelEventKind::OutputDelta {
1892                        output_index: ExecutionCount::ZERO,
1893                        delta: ModelOutputDelta::Json(ModelStreamChunk::new(raw).unwrap()),
1894                    },
1895                ))
1896                .unwrap();
1897            assert!(matches!(
1898                accumulator.push(output_completed(3, 0)),
1899                Err(ModelEventStreamError::InvalidJsonPayload { .. })
1900            ));
1901            assert_eq!(
1902                accumulator.push(completed(
1903                    3,
1904                    ModelFinishReason::Completed,
1905                    usage(1, None, 1, None)
1906                )),
1907                Err(ModelEventStreamError::Poisoned)
1908            );
1909        }
1910    }
1911
1912    #[test]
1913    fn already_started_outputs_may_interleave_without_reordering_results() {
1914        let descriptor = descriptor("models.primary");
1915        let request = streaming_builder()
1916            .reasoning_summaries(true)
1917            .build()
1918            .unwrap();
1919        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1920        let events = [
1921            started(0, &descriptor),
1922            text_start(1, 0),
1923            text_delta(2, 0, "visible "),
1924            event(
1925                3,
1926                ModelEventKind::OutputStarted {
1927                    output_index: ExecutionCount::new(1),
1928                    start: Box::new(
1929                        ModelOutputStart::reasoning_summary(None, model_metadata()).unwrap(),
1930                    ),
1931                },
1932            ),
1933            event(
1934                4,
1935                ModelEventKind::OutputDelta {
1936                    output_index: ExecutionCount::new(1),
1937                    delta: ModelOutputDelta::ReasoningSummary(
1938                        ModelStreamChunk::new("summary").unwrap(),
1939                    ),
1940                },
1941            ),
1942            text_delta(5, 0, "answer"),
1943            output_completed(6, 1),
1944            output_completed(7, 0),
1945            completed(8, ModelFinishReason::Completed, usage(10, None, 4, Some(1))),
1946        ];
1947        for event in events {
1948            accumulator.push(event).unwrap();
1949        }
1950        let response = accumulator.finish().unwrap();
1951        assert_eq!(response.output()[0].kind(), ModelOutputItemKind::Content);
1952        assert_eq!(
1953            response.output()[1].kind(),
1954            ModelOutputItemKind::ReasoningSummary
1955        );
1956    }
1957
1958    #[test]
1959    fn tool_argument_fragments_become_an_unapproved_proposal() {
1960        let descriptor = descriptor("models.primary");
1961        let requested_tool = tool("tools.lookup");
1962        let request = streaming_builder()
1963            .tool(requested_tool.clone())
1964            .tool_selection(ModelToolSelection::auto())
1965            .max_tool_calls_per_response(ExecutionCount::new(2))
1966            .build()
1967            .unwrap();
1968        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1969        let events = [
1970            started(0, &descriptor),
1971            event(
1972                1,
1973                ModelEventKind::OutputStarted {
1974                    output_index: ExecutionCount::ZERO,
1975                    start: Box::new(ModelOutputStart::tool_call(
1976                        requested_tool.metadata().identity().clone(),
1977                        Some(ModelProviderToolCallId::new("call_42").unwrap()),
1978                        Extensions::default(),
1979                    )),
1980                },
1981            ),
1982            event(
1983                2,
1984                ModelEventKind::OutputDelta {
1985                    output_index: ExecutionCount::ZERO,
1986                    delta: ModelOutputDelta::ToolArguments(
1987                        ModelStreamChunk::new("{\"incident_id\":").unwrap(),
1988                    ),
1989                },
1990            ),
1991            event(
1992                3,
1993                ModelEventKind::OutputDelta {
1994                    output_index: ExecutionCount::ZERO,
1995                    delta: ModelOutputDelta::ToolArguments(ModelStreamChunk::new("42}").unwrap()),
1996                },
1997            ),
1998            output_completed(4, 0),
1999            completed(5, ModelFinishReason::ToolCalls, usage(20, None, 8, None)),
2000        ];
2001        for event in events {
2002            accumulator.push(event).unwrap();
2003        }
2004        let response = accumulator.finish().unwrap();
2005        let proposal = response.tool_calls().next().unwrap();
2006        assert_eq!(proposal.tool(), requested_tool.metadata().identity());
2007        assert_eq!(proposal.provider_call_id().unwrap().as_str(), "call_42");
2008        assert_eq!(proposal.arguments().as_value(), &json!({"incident_id": 42}));
2009    }
2010
2011    #[test]
2012    fn duplicate_tool_ids_and_non_object_arguments_never_commit() {
2013        let descriptor = descriptor("models.primary");
2014        let requested_tool = tool("tools.lookup");
2015        let request = streaming_builder()
2016            .tool(requested_tool.clone())
2017            .tool_selection(ModelToolSelection::auto())
2018            .max_tool_calls_per_response(ExecutionCount::new(2))
2019            .build()
2020            .unwrap();
2021
2022        let start = |sequence, index| {
2023            event(
2024                sequence,
2025                ModelEventKind::OutputStarted {
2026                    output_index: ExecutionCount::new(index),
2027                    start: Box::new(ModelOutputStart::tool_call(
2028                        requested_tool.metadata().identity().clone(),
2029                        Some(ModelProviderToolCallId::new("call_duplicate").unwrap()),
2030                        Extensions::default(),
2031                    )),
2032                },
2033            )
2034        };
2035        let mut duplicate = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2036        duplicate.push(started(0, &descriptor)).unwrap();
2037        duplicate.push(start(1, 0)).unwrap();
2038        assert!(matches!(
2039            duplicate.push(start(2, 1)),
2040            Err(ModelEventStreamError::InvalidResponse {
2041                error: ModelResponseError::DuplicateProviderToolCallId
2042            })
2043        ));
2044
2045        let mut scalar = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2046        scalar.push(started(0, &descriptor)).unwrap();
2047        scalar.push(start(1, 0)).unwrap();
2048        scalar
2049            .push(event(
2050                2,
2051                ModelEventKind::OutputDelta {
2052                    output_index: ExecutionCount::ZERO,
2053                    delta: ModelOutputDelta::ToolArguments(ModelStreamChunk::new("42").unwrap()),
2054                },
2055            ))
2056            .unwrap();
2057        assert!(matches!(
2058            scalar.push(output_completed(3, 0)),
2059            Err(ModelEventStreamError::InvalidToolCall {
2060                error: ModelToolCallProposalError::ArgumentsMustBeObject,
2061                ..
2062            })
2063        ));
2064    }
2065
2066    #[test]
2067    fn noncomplete_text_may_commit_but_tool_fragments_cannot_masquerade_as_output() {
2068        let descriptor = descriptor("models.primary");
2069        let text_request = streaming_request();
2070        let mut partial =
2071            ModelEventAccumulator::new(attempt(), &descriptor, &text_request).unwrap();
2072        for event in [
2073            started(0, &descriptor),
2074            text_start(1, 0),
2075            text_delta(2, 0, "partial but typed"),
2076            output_completed(3, 0),
2077            completed(4, ModelFinishReason::OutputLimit, usage(5, None, 3, None)),
2078        ] {
2079            partial.push(event).unwrap();
2080        }
2081        let response = partial.finish().unwrap();
2082        assert_eq!(response.finish_reason(), ModelFinishReason::OutputLimit);
2083        assert_eq!(response.output().len(), 1);
2084
2085        let requested_tool = tool("tools.lookup");
2086        let tool_request = streaming_builder()
2087            .tool(requested_tool.clone())
2088            .tool_selection(ModelToolSelection::auto())
2089            .max_tool_calls_per_response(ExecutionCount::new(1))
2090            .build()
2091            .unwrap();
2092        let mut tool_stream =
2093            ModelEventAccumulator::new(attempt(), &descriptor, &tool_request).unwrap();
2094        tool_stream.push(started(0, &descriptor)).unwrap();
2095        tool_stream
2096            .push(event(
2097                1,
2098                ModelEventKind::OutputStarted {
2099                    output_index: ExecutionCount::ZERO,
2100                    start: Box::new(ModelOutputStart::tool_call(
2101                        requested_tool.metadata().identity().clone(),
2102                        None,
2103                        Extensions::default(),
2104                    )),
2105                },
2106            ))
2107            .unwrap();
2108        tool_stream
2109            .push(event(
2110                2,
2111                ModelEventKind::OutputDelta {
2112                    output_index: ExecutionCount::ZERO,
2113                    delta: ModelOutputDelta::ToolArguments(
2114                        ModelStreamChunk::new("{\"id\":").unwrap(),
2115                    ),
2116                },
2117            ))
2118            .unwrap();
2119        assert!(matches!(
2120            tool_stream.push(completed(
2121                3,
2122                ModelFinishReason::OutputLimit,
2123                usage(5, None, 3, None)
2124            )),
2125            Err(ModelEventStreamError::OutputStillOpen { .. })
2126        ));
2127    }
2128
2129    #[test]
2130    fn stream_order_attempt_and_delta_type_fail_closed() {
2131        let descriptor = descriptor("models.primary");
2132        let request = streaming_request();
2133
2134        let mut before_start =
2135            ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2136        assert_eq!(
2137            before_start.push(text_start(0, 0)),
2138            Err(ModelEventStreamError::EventBeforeStart)
2139        );
2140        assert!(before_start.is_poisoned());
2141
2142        let mut gap = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2143        gap.push(started(0, &descriptor)).unwrap();
2144        assert!(matches!(
2145            gap.push(text_start(2, 0)),
2146            Err(ModelEventStreamError::SequenceMismatch { .. })
2147        ));
2148
2149        let mut output_gap = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2150        output_gap.push(started(0, &descriptor)).unwrap();
2151        assert!(matches!(
2152            output_gap.push(text_start(1, 1)),
2153            Err(ModelEventStreamError::OutputStartOutOfOrder { .. })
2154        ));
2155
2156        let mut wrong_delta = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2157        wrong_delta.push(started(0, &descriptor)).unwrap();
2158        wrong_delta.push(text_start(1, 0)).unwrap();
2159        assert!(matches!(
2160            wrong_delta.push(event(
2161                2,
2162                ModelEventKind::OutputDelta {
2163                    output_index: ExecutionCount::ZERO,
2164                    delta: ModelOutputDelta::Json(ModelStreamChunk::new("{}").unwrap())
2165                }
2166            )),
2167            Err(ModelEventStreamError::DeltaKindMismatch { .. })
2168        ));
2169
2170        let mut wrong_attempt =
2171            ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2172        wrong_attempt.push(started(0, &descriptor)).unwrap();
2173        let other_attempt = "01912345-6789-7abc-8def-0123456789ac".parse().unwrap();
2174        let other = ModelEvent::new(
2175            other_attempt,
2176            ExecutionCount::new(1),
2177            ModelEventKind::UsageUpdated {
2178                usage: usage(1, None, 0, None),
2179            },
2180        )
2181        .unwrap();
2182        assert!(matches!(
2183            wrong_attempt.push(other),
2184            Err(ModelEventStreamError::AttemptMismatch { .. })
2185        ));
2186    }
2187
2188    #[test]
2189    fn usage_snapshots_are_cumulative_monotonic_and_bounded() {
2190        let descriptor = descriptor("models.primary");
2191        let request = streaming_request();
2192        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2193        accumulator.push(started(0, &descriptor)).unwrap();
2194        accumulator
2195            .push(event(
2196                1,
2197                ModelEventKind::UsageUpdated {
2198                    usage: usage(100, Some(20), 10, Some(2)),
2199                },
2200            ))
2201            .unwrap();
2202        assert!(matches!(
2203            accumulator.push(event(
2204                2,
2205                ModelEventKind::UsageUpdated {
2206                    usage: usage(100, Some(19), 11, Some(2))
2207                }
2208            )),
2209            Err(ModelEventStreamError::UsageDecreased {
2210                field: ModelUsageField::CachedInputTokens,
2211                ..
2212            })
2213        ));
2214
2215        let mut disappeared = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2216        disappeared.push(started(0, &descriptor)).unwrap();
2217        disappeared
2218            .push(event(
2219                1,
2220                ModelEventKind::UsageUpdated {
2221                    usage: usage(100, Some(20), 10, None),
2222                },
2223            ))
2224            .unwrap();
2225        assert!(matches!(
2226            disappeared.push(completed(
2227                2,
2228                ModelFinishReason::Completed,
2229                usage(100, None, 11, None)
2230            )),
2231            Err(ModelEventStreamError::UsageBreakdownDisappeared {
2232                field: ModelUsageField::CachedInputTokens
2233            })
2234        ));
2235
2236        let mut excessive = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2237        excessive.push(started(0, &descriptor)).unwrap();
2238        assert!(matches!(
2239            excessive.push(event(
2240                1,
2241                ModelEventKind::UsageUpdated {
2242                    usage: usage(8_193, None, 1, None)
2243                }
2244            )),
2245            Err(ModelEventStreamError::InvalidResponse {
2246                error: ModelResponseError::InputUsageExceedsRequest { .. }
2247            })
2248        ));
2249    }
2250
2251    #[test]
2252    fn open_or_truncated_streams_never_become_responses() {
2253        let descriptor = descriptor("models.primary");
2254        let request = streaming_request();
2255        let mut open = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2256        open.push(started(0, &descriptor)).unwrap();
2257        open.push(text_start(1, 0)).unwrap();
2258        open.push(text_delta(2, 0, "partial")).unwrap();
2259        assert!(matches!(
2260            open.push(completed(
2261                3,
2262                ModelFinishReason::OutputLimit,
2263                usage(4, None, 2, None)
2264            )),
2265            Err(ModelEventStreamError::OutputStillOpen { .. })
2266        ));
2267
2268        let mut truncated = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2269        truncated.push(started(0, &descriptor)).unwrap();
2270        assert_eq!(
2271            truncated.finish(),
2272            Err(ModelEventStreamError::UnexpectedEnd {
2273                next_sequence: ExecutionCount::new(1)
2274            })
2275        );
2276    }
2277
2278    #[test]
2279    fn empty_plain_completion_needs_only_start_and_terminal() {
2280        let descriptor = descriptor("models.primary");
2281        let request = streaming_request();
2282        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2283        accumulator.push(started(0, &descriptor)).unwrap();
2284        accumulator
2285            .push(completed(
2286                1,
2287                ModelFinishReason::Completed,
2288                usage(4, None, 1, None),
2289            ))
2290            .unwrap();
2291        assert!(accumulator.finish().unwrap().output().is_empty());
2292    }
2293
2294    #[test]
2295    fn trailing_events_poison_an_otherwise_complete_stream() {
2296        let descriptor = descriptor("models.primary");
2297        let request = streaming_request();
2298        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2299        accumulator.push(started(0, &descriptor)).unwrap();
2300        accumulator
2301            .push(completed(
2302                1,
2303                ModelFinishReason::Completed,
2304                usage(4, None, 1, None),
2305            ))
2306            .unwrap();
2307        assert!(accumulator.is_complete());
2308        assert_eq!(
2309            accumulator.push(event(
2310                2,
2311                ModelEventKind::UsageUpdated {
2312                    usage: usage(4, None, 1, None)
2313                }
2314            )),
2315            Err(ModelEventStreamError::AlreadyCompleted)
2316        );
2317        assert!(accumulator.is_poisoned());
2318        assert!(!accumulator.is_complete());
2319        assert_eq!(accumulator.finish(), Err(ModelEventStreamError::Poisoned));
2320    }
2321
2322    #[test]
2323    fn complete_requests_and_wrong_model_provenance_are_rejected() {
2324        let primary = descriptor("models.primary");
2325        let complete_request = ModelRequest::builder(limits())
2326            .instruction(instruction())
2327            .build()
2328            .unwrap();
2329        assert!(matches!(
2330            ModelEventAccumulator::new(attempt(), &primary, &complete_request),
2331            Err(ModelEventStreamError::RequestNotStreaming)
2332        ));
2333
2334        let request = streaming_request();
2335        let non_streaming = non_streaming_descriptor("models.primary");
2336        assert!(matches!(
2337            ModelEventAccumulator::new(attempt(), &non_streaming, &request),
2338            Err(ModelEventStreamError::CapabilityMismatch { .. })
2339        ));
2340
2341        let other = descriptor("models.other");
2342        let mut accumulator = ModelEventAccumulator::new(attempt(), &primary, &request).unwrap();
2343        assert!(matches!(
2344            accumulator.push(started(0, &other)),
2345            Err(ModelEventStreamError::InvalidResponse {
2346                error: ModelResponseError::ModelIdentityMismatch { .. }
2347            })
2348        ));
2349    }
2350
2351    #[test]
2352    fn per_item_stream_buffer_is_bounded_before_materialization() {
2353        let descriptor = descriptor("models.primary");
2354        let request = streaming_request();
2355        let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2356        accumulator.push(started(0, &descriptor)).unwrap();
2357        accumulator.push(text_start(1, 0)).unwrap();
2358        let full_chunk = "x".repeat(ModelStreamChunk::MAX_BYTES);
2359        for sequence in 2..6 {
2360            accumulator
2361                .push(text_delta(sequence, 0, &full_chunk))
2362                .unwrap();
2363        }
2364        assert!(matches!(
2365            accumulator.push(text_delta(6, 0, "x")),
2366            Err(ModelEventStreamError::OutputPayloadTooLarge {
2367                maximum: TextContent::MAX_BYTES,
2368                actual,
2369                ..
2370            }) if actual == TextContent::MAX_BYTES + 1
2371        ));
2372    }
2373
2374    #[test]
2375    fn event_schemas_close_envelopes_and_tagged_variants() {
2376        let event = to_value(schemars::schema_for!(ModelEvent)).unwrap();
2377        assert_eq!(event["type"], "object");
2378        assert_eq!(event["additionalProperties"], false);
2379        let required = event["required"].as_array().unwrap();
2380        for field in ["attempt_id", "sequence", "event"] {
2381            assert!(required.contains(&Value::from(field)));
2382        }
2383
2384        for schema in [
2385            to_value(schemars::schema_for!(ModelOutputStart)).unwrap(),
2386            to_value(schemars::schema_for!(ModelOutputDelta)).unwrap(),
2387            to_value(schemars::schema_for!(ModelEventKind)).unwrap(),
2388        ] {
2389            let variants = schema["oneOf"].as_array().unwrap();
2390            assert!(!variants.is_empty());
2391            assert!(
2392                variants
2393                    .iter()
2394                    .all(|variant| variant["additionalProperties"] == false)
2395            );
2396        }
2397    }
2398
2399    proptest! {
2400        #[test]
2401        fn safe_ascii_chunks_round_trip_exactly(value in "[ -~\\n\\r\\t]{1,4096}") {
2402            let chunk = ModelStreamChunk::new(value.clone()).unwrap();
2403            let encoded = to_value(&chunk).unwrap();
2404            let decoded = from_value::<ModelStreamChunk>(encoded).unwrap();
2405            prop_assert_eq!(decoded.as_str(), value);
2406        }
2407    }
2408}