Skip to main content

typesayer_parser/
event.rs

1// Copyright 2026 Thomas Santerre and Moderately AI Inc.
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! Typed events emitted by [`super::parser::ChatStreamParser`].
6//!
7//! Each variant corresponds to a step in progressively building the
8//! structured output tree from a streaming LM response. Paths are
9//! JSON-Pointer strings (RFC 6901) addressing nodes within the schema
10//! tree, so clients can route events to UI components per path.
11//!
12//! The variant set is matched 1:1 to [`FieldType`]
13//! taxonomy — adding a new `FieldType` variant grows this enum (and
14//! the corresponding [`super::field_parsers`] dispatch); existing
15//! variants stay stable.
16
17use typesayer_types::field::{FieldType, FieldValue};
18
19/// One event produced by the streaming parser.
20///
21/// Variants are emitted in the order content arrives from the LM.
22/// Consumers can rebuild the full structured output from the sequence,
23/// OR react to specific events (`FieldComplete` for "field X is done",
24/// `StreamComplete` for "everything is done", `ValueAppend` for chat-UI
25/// typing).
26#[derive(Debug, Clone, PartialEq)]
27pub enum ParseEvent {
28    /// First event, always. Carries an opaque hash of the output
29    /// signature so clients can sanity-check they were rendering
30    /// against the right schema. The full schema is fetched separately
31    /// via the existing application endpoints (kept out of the
32    /// stream-start payload to bound the on-open size).
33    StreamStart { output_schema_hash: String },
34
35    /// A declared output field's `[[ ## name ## ]]` marker arrived.
36    /// Path is `/<field_name>`; field_type is the declared type for
37    /// the field so clients know what value-event variants to expect.
38    FieldStart { path: String, field_type: FieldType },
39
40    /// Incremental text content for a [`FieldType::String`] field.
41    /// `delta` is the new content since the previous event for this
42    /// path; clients concatenate to render progressively (chat-UI
43    /// typing). Only emitted for `String` fields; structured fields
44    /// use `ElementAdded` / `EntryAdded` instead.
45    ValueAppend { path: String, delta: String },
46
47    /// Atomic value emitted when a non-string scalar finishes
48    /// parsing (`Int`, `Float`, `Bool`, `Enum`, `Nullable<scalar>`).
49    /// Reserved for future per-FieldType-variant expansion — not
50    /// emitted by the initial-step parser (which supports `String`
51    /// and `List<String>` only).
52    ValueSet { path: String, value: FieldValue },
53
54    /// A [`FieldType::List`] field's content opened — the LM emitted
55    /// `[`. Path identifies the field; clients can render an empty
56    /// list shell before elements arrive.
57    ListOpen { path: String },
58
59    /// One element of a [`FieldType::List`] finished parsing.
60    /// `index` is the element's position in the list; `value` is its
61    /// typed value.
62    ElementAdded {
63        path: String,
64        index: usize,
65        value: FieldValue,
66    },
67
68    /// A [`FieldType::List`] field's content closed — the LM emitted
69    /// `]`. `value` is the complete parsed list for clients that
70    /// didn't accumulate from `ElementAdded` events.
71    ListClose { path: String, value: FieldValue },
72
73    /// A [`FieldType::Map`] or [`FieldType::Object`] field's content
74    /// opened — the LM emitted `{`. Reserved for future expansion.
75    ObjectOpen { path: String },
76
77    /// One key-value pair of a [`FieldType::Map`] / [`FieldType::Object`]
78    /// finished parsing. Reserved for future expansion.
79    EntryAdded {
80        path: String,
81        key: String,
82        value: FieldValue,
83    },
84
85    /// A [`FieldType::Map`] / [`FieldType::Object`] field's content
86    /// closed — the LM emitted `}`. Reserved for future expansion.
87    ObjectClose { path: String, value: FieldValue },
88
89    /// A field's marker boundary arrived; the prior field is fully
90    /// done. Carries the full parsed value for clients that didn't
91    /// accumulate from per-value events. Always emitted at field-
92    /// completion, after any `ListClose` / `ObjectClose` /
93    /// `ValueAppend` events for the field.
94    FieldComplete { path: String, value: FieldValue },
95
96    /// The `[[ ## completed ## ]]` sentinel arrived. `output` is the
97    /// full structured output as a [`FieldValue::Object`] map of
98    /// field-name → field-value, mirroring `Adapter::parse`.
99    StreamComplete { output: FieldValue },
100
101    /// Mid-stream parse or deserialization failure. `path` is the
102    /// node where the error occurred (may be `None` for errors
103    /// between fields). Streaming halts after this event; the
104    /// consumer returns a non-retryable error.
105    StreamError {
106        path: Option<String>,
107        message: String,
108    },
109}
110
111impl ParseEvent {
112    /// Stable event-type identifier for wire serialization. Mirrors
113    /// the snake-case identifier the streaming consumer uses
114    /// when declaring schemas via `StreamingEventDef`.
115    #[must_use]
116    pub const fn event_type(&self) -> &'static str {
117        match self {
118            Self::StreamStart { .. } => "stream_start",
119            Self::FieldStart { .. } => "field_start",
120            Self::ValueAppend { .. } => "value_append",
121            Self::ValueSet { .. } => "value_set",
122            Self::ListOpen { .. } => "list_open",
123            Self::ElementAdded { .. } => "element_added",
124            Self::ListClose { .. } => "list_close",
125            Self::ObjectOpen { .. } => "object_open",
126            Self::EntryAdded { .. } => "entry_added",
127            Self::ObjectClose { .. } => "object_close",
128            Self::FieldComplete { .. } => "field_complete",
129            Self::StreamComplete { .. } => "stream_complete",
130            Self::StreamError { .. } => "stream_error",
131        }
132    }
133
134    /// Whether this event variant should be durable (WAL-persisted)
135    /// for late-subscriber replay. Boundary events (start / open /
136    /// close / complete / error) are durable because they reconstruct
137    /// the schema's structure; per-value events (`value_append`,
138    /// `value_set`, `element_added`, `entry_added`) are volatile —
139    /// late subscribers fetch the final structured output via the
140    /// existing execution endpoint and only need structural events
141    /// for skeleton rendering.
142    #[must_use]
143    pub const fn is_durable(&self) -> bool {
144        match self {
145            Self::ValueAppend { .. }
146            | Self::ValueSet { .. }
147            | Self::ElementAdded { .. }
148            | Self::EntryAdded { .. } => false,
149            Self::StreamStart { .. }
150            | Self::FieldStart { .. }
151            | Self::ListOpen { .. }
152            | Self::ListClose { .. }
153            | Self::ObjectOpen { .. }
154            | Self::ObjectClose { .. }
155            | Self::FieldComplete { .. }
156            | Self::StreamComplete { .. }
157            | Self::StreamError { .. } => true,
158        }
159    }
160}
161
162#[cfg(test)]
163mod tests {
164    use super::*;
165
166    #[test]
167    fn event_type_distinct_per_variant() {
168        let events = [
169            ParseEvent::StreamStart {
170                output_schema_hash: String::new(),
171            },
172            ParseEvent::FieldStart {
173                path: "/x".into(),
174                field_type: FieldType::String,
175            },
176            ParseEvent::ValueAppend {
177                path: "/x".into(),
178                delta: String::new(),
179            },
180            ParseEvent::ValueSet {
181                path: "/x".into(),
182                value: FieldValue::Null,
183            },
184            ParseEvent::ListOpen { path: "/x".into() },
185            ParseEvent::ElementAdded {
186                path: "/x".into(),
187                index: 0,
188                value: FieldValue::Null,
189            },
190            ParseEvent::ListClose {
191                path: "/x".into(),
192                value: FieldValue::List(vec![]),
193            },
194            ParseEvent::ObjectOpen { path: "/x".into() },
195            ParseEvent::EntryAdded {
196                path: "/x".into(),
197                key: String::new(),
198                value: FieldValue::Null,
199            },
200            ParseEvent::ObjectClose {
201                path: "/x".into(),
202                value: FieldValue::Object(std::collections::BTreeMap::new()),
203            },
204            ParseEvent::FieldComplete {
205                path: "/x".into(),
206                value: FieldValue::Null,
207            },
208            ParseEvent::StreamComplete {
209                output: FieldValue::Object(std::collections::BTreeMap::new()),
210            },
211            ParseEvent::StreamError {
212                path: None,
213                message: String::new(),
214            },
215        ];
216        let types: std::collections::HashSet<_> =
217            events.iter().map(ParseEvent::event_type).collect();
218        assert_eq!(
219            types.len(),
220            events.len(),
221            "every variant must have a unique event_type"
222        );
223    }
224
225    #[test]
226    fn durability_split_matches_design() {
227        // Value events are volatile.
228        assert!(
229            !ParseEvent::ValueAppend {
230                path: "/x".into(),
231                delta: String::new()
232            }
233            .is_durable()
234        );
235        assert!(
236            !ParseEvent::ValueSet {
237                path: "/x".into(),
238                value: FieldValue::Null
239            }
240            .is_durable()
241        );
242        assert!(
243            !ParseEvent::ElementAdded {
244                path: "/x".into(),
245                index: 0,
246                value: FieldValue::Null
247            }
248            .is_durable()
249        );
250        assert!(
251            !ParseEvent::EntryAdded {
252                path: "/x".into(),
253                key: String::new(),
254                value: FieldValue::Null,
255            }
256            .is_durable()
257        );
258
259        // Boundary events are durable.
260        for ev in [
261            ParseEvent::StreamStart {
262                output_schema_hash: String::new(),
263            },
264            ParseEvent::FieldStart {
265                path: "/x".into(),
266                field_type: FieldType::String,
267            },
268            ParseEvent::ListOpen { path: "/x".into() },
269            ParseEvent::ListClose {
270                path: "/x".into(),
271                value: FieldValue::List(vec![]),
272            },
273            ParseEvent::ObjectOpen { path: "/x".into() },
274            ParseEvent::ObjectClose {
275                path: "/x".into(),
276                value: FieldValue::Object(std::collections::BTreeMap::new()),
277            },
278            ParseEvent::FieldComplete {
279                path: "/x".into(),
280                value: FieldValue::Null,
281            },
282            ParseEvent::StreamComplete {
283                output: FieldValue::Object(std::collections::BTreeMap::new()),
284            },
285            ParseEvent::StreamError {
286                path: None,
287                message: String::new(),
288            },
289        ] {
290            assert!(ev.is_durable(), "expected durable: {ev:?}");
291        }
292    }
293}