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}