Skip to main content

reef_core/value/
content.rs

1//! Owned, provider-neutral content values.
2
3use std::collections::{BTreeMap, btree_map};
4use std::fmt::{self, Debug, Formatter};
5
6use crate::opaque::{Envelope, Payload};
7use crate::redact;
8
9/// A known portable interpretation of a [`PartKind`].
10#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
11#[non_exhaustive]
12pub enum KnownPartKind {
13    /// Ordinary text.
14    Text,
15    /// Image content.
16    Image,
17    /// File content.
18    File,
19    /// Model-facing tool-result content.
20    ToolResult,
21    /// Reasoning or thinking replayed to the model.
22    Thinking,
23}
24
25impl KnownPartKind {
26    /// Returns the canonical numeric kind carrying this interpretation.
27    ///
28    /// The inverse of [`PartKind::known`], and the supported way to spell one of
29    /// the five as a [`PartKind`]. It introduces no second representation: the
30    /// value is the one [`PartKind::from_i64`] would have produced, so
31    /// `kind.as_part_kind().known()` is `Some(kind)` for every variant.
32    #[must_use]
33    pub const fn as_part_kind(self) -> PartKind {
34        PartKind::from_i64(match self {
35            Self::Text => 0,
36            Self::Image => 1,
37            Self::File => 2,
38            Self::ToolResult => 3,
39            Self::Thinking => 4,
40        })
41    }
42}
43
44/// The canonical, open numeric kind of a [`Part`].
45///
46/// Every `i64` round-trips, while only values zero through four have a known
47/// portable interpretation.
48///
49/// ```compile_fail
50/// use reef_core::value::content;
51/// let _forged = content::PartKind(0);
52/// ```
53///
54/// # Kinds this crate cannot name
55///
56/// A producer is free to mint its own. [`PartKind::from_i64`] keeps every `i64`,
57/// and transcript records, user input and ephemeral input all propagate an
58/// unrecognised kind losslessly together with its complete [`PartFields`]. Two
59/// boundaries narrow, and each says so where it is defined: a system-instruction
60/// part must be a known [`KnownPartKind::Text`], and
61/// [`tool_call::ToolPart::try_from_part`](crate::value::tool_call::ToolPart::try_from_part)
62/// refuses a kind this crate cannot name, because the model acts on a tool
63/// result.
64///
65/// What these numbers do not come with is an allocation authority. There is no
66/// registry and no reserved range, so two independently written producers can
67/// choose the same integer for different concepts, or different integers for the
68/// same one, and this crate can neither prevent that nor notice it. A number
69/// outside 0-4 therefore identifies a kind only between parties that already
70/// agree — typically a codec and the consumer written against it.
71///
72/// When something has to be recognised by a party that did not choose the number,
73/// name it in the [`Metadata`] on the same part: its keys are strings, so a
74/// producer can qualify its own vocabulary the way [`Envelope`] does with
75/// `(namespace, kind)` for provider data elsewhere in the crate. A `Part` carries
76/// no `Envelope` of its own — [`PartFields::raw_payload`] is unnamespaced bytes —
77/// so the metadata tree is where that naming goes.
78#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
79pub struct PartKind(i64);
80
81impl PartKind {
82    /// Creates a kind while preserving the numeric value exactly.
83    #[must_use]
84    pub const fn from_i64(value: i64) -> Self {
85        Self(value)
86    }
87
88    /// Returns the original numeric value.
89    #[must_use]
90    pub const fn as_i64(self) -> i64 {
91        self.0
92    }
93
94    /// Returns the known portable interpretation, if one exists.
95    ///
96    /// [`KnownPartKind::as_part_kind`] is the inverse.
97    #[must_use]
98    pub const fn known(self) -> Option<KnownPartKind> {
99        match self.0 {
100            0 => Some(KnownPartKind::Text),
101            1 => Some(KnownPartKind::Image),
102            2 => Some(KnownPartKind::File),
103            3 => Some(KnownPartKind::ToolResult),
104            4 => Some(KnownPartKind::Thinking),
105            _ => None,
106        }
107    }
108}
109
110/// An owned, callback-free metadata object.
111///
112/// # Ordering
113///
114/// Iteration — through [`Metadata::iter`] or [`IntoIterator`] — yields entries in
115/// **ascending key order**. This is a guarantee, not an artefact of the current
116/// storage: ADR-004's determinism for wire codecs depends on it, so a later
117/// storage change has to preserve it.
118///
119/// ```
120/// use reef_core::value::content;
121/// let values = vec![
122///     content::MetadataValue::Null, content::MetadataValue::Bool(true), content::MetadataValue::Signed(-1),
123///     content::MetadataValue::Unsigned(1), content::MetadataValue::Float(1.5),
124///     content::MetadataValue::String("text".into()), content::MetadataValue::Bytes(vec![1].into_boxed_slice()),
125///     content::MetadataValue::Array(vec![]), content::MetadataValue::Object(content::Metadata::new()),
126/// ];
127/// let mut metadata = content::Metadata::new();
128/// metadata.insert("values".into(), content::MetadataValue::Array(values));
129/// assert!(matches!(metadata.get("values"), Some(content::MetadataValue::Array(values)) if values.len() == 9));
130/// assert_eq!(metadata.iter().len(), 1);
131/// assert_eq!(metadata.into_iter().count(), 1);
132/// ```
133///
134/// ```compile_fail
135/// use reef_core::value::content;
136/// let callback = Box::new(|| {});
137/// let _invalid = content::Metadata::from_iter([("callback".to_owned(), callback)]);
138/// ```
139#[derive(Clone)]
140pub struct Metadata(BTreeMap<String, MetadataValue>);
141
142impl Debug for Metadata {
143    /// States how many entries exist and stops there.
144    ///
145    /// Not iterating is what makes this implementation safe as well as
146    /// discreet: keys and values are model-visible, and a
147    /// [`MetadataValue`] tree nests without any depth limit, so a formatter
148    /// that descended would overflow the stack on the same values
149    /// `Clone` and `Drop` already survive iteratively.
150    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
151        formatter
152            .debug_struct("Metadata")
153            .field("entries", &self.0.len())
154            .finish()
155    }
156}
157
158#[expect(
159    clippy::new_without_default,
160    reason = "ADR-004 freezes Metadata::new as the sole empty constructor"
161)]
162impl Metadata {
163    /// Creates an empty, present metadata object.
164    #[must_use]
165    pub const fn new() -> Self {
166        Self(BTreeMap::new())
167    }
168
169    /// Returns the value associated with `key`.
170    #[must_use]
171    pub fn get(&self, key: &str) -> Option<&MetadataValue> {
172        self.0.get(key)
173    }
174
175    /// Associates `value` with `key`, returning whatever `key` already held.
176    pub fn insert(&mut self, key: String, value: MetadataValue) -> Option<MetadataValue> {
177        self.0.insert(key, value)
178    }
179
180    /// Iterates over entries in ascending key order.
181    #[must_use]
182    pub fn iter(&self) -> MetadataIter<'_> {
183        MetadataIter(self.0.iter())
184    }
185}
186
187impl FromIterator<(String, MetadataValue)> for Metadata {
188    /// Collects entries; a repeated key keeps the last value supplied.
189    fn from_iter<I: IntoIterator<Item = (String, MetadataValue)>>(entries: I) -> Self {
190        Self(entries.into_iter().collect())
191    }
192}
193
194impl IntoIterator for Metadata {
195    type Item = (String, MetadataValue);
196    type IntoIter = MetadataIntoIter;
197
198    /// Transfers every entry in ascending key order.
199    fn into_iter(self) -> Self::IntoIter {
200        MetadataIntoIter(self.0.into_iter())
201    }
202}
203
204impl<'a> IntoIterator for &'a Metadata {
205    type Item = (&'a str, &'a MetadataValue);
206    type IntoIter = MetadataIter<'a>;
207
208    fn into_iter(self) -> Self::IntoIter {
209        self.iter()
210    }
211}
212
213/// Borrowing iterator over [`Metadata`] entries in ascending key order.
214///
215/// The concrete storage stays hidden: this type names the iterator so
216/// `Metadata`'s representation can change without changing its API.
217pub struct MetadataIter<'a>(btree_map::Iter<'a, String, MetadataValue>);
218
219impl Debug for MetadataIter<'_> {
220    /// States how many entries are still to come, not what they are.
221    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
222        formatter
223            .debug_struct("MetadataIter")
224            .field("remaining", &self.0.len())
225            .finish()
226    }
227}
228
229impl<'a> Iterator for MetadataIter<'a> {
230    type Item = (&'a str, &'a MetadataValue);
231
232    fn next(&mut self) -> Option<Self::Item> {
233        self.0.next().map(|(key, value)| (key.as_str(), value))
234    }
235
236    fn size_hint(&self) -> (usize, Option<usize>) {
237        self.0.size_hint()
238    }
239}
240
241impl ExactSizeIterator for MetadataIter<'_> {
242    fn len(&self) -> usize {
243        self.0.len()
244    }
245}
246
247/// Owning iterator over [`Metadata`] entries in ascending key order.
248pub struct MetadataIntoIter(btree_map::IntoIter<String, MetadataValue>);
249
250impl Debug for MetadataIntoIter {
251    /// States how many entries are still to come, not what they are.
252    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
253        formatter
254            .debug_struct("MetadataIntoIter")
255            .field("remaining", &self.0.len())
256            .finish()
257    }
258}
259
260impl Iterator for MetadataIntoIter {
261    type Item = (String, MetadataValue);
262
263    fn next(&mut self) -> Option<Self::Item> {
264        self.0.next()
265    }
266
267    fn size_hint(&self) -> (usize, Option<usize>) {
268        self.0.size_hint()
269    }
270}
271
272impl ExactSizeIterator for MetadataIntoIter {
273    fn len(&self) -> usize {
274        self.0.len()
275    }
276}
277
278/// A value in the closed, portable metadata tree.
279///
280/// # Nesting depth
281///
282/// A value nests without any limit in memory, which is why [`Clone`] and
283/// [`Drop`] are implemented iteratively here. Serialization is the one place
284/// that cannot follow suit: serde expresses nesting through nested calls and
285/// consumes each level's compound serializer by value, so no work stack can hold
286/// the intermediates. With the `serde` feature enabled, a value nested more than
287/// **128** levels deep is therefore refused in both directions with a typed
288/// error — never truncated, and never allowed to overflow the stack. 128 is
289/// `serde_json`'s own default recursion limit, so reef's bound is not the first
290/// one a JSON caller meets; realistic metadata is under ten levels deep.
291pub enum MetadataValue {
292    /// A null value.
293    Null,
294    /// A boolean value.
295    Bool(bool),
296    /// A signed integer.
297    Signed(i64),
298    /// An unsigned integer.
299    Unsigned(u64),
300    /// A floating-point value, including every `f64` bit pattern.
301    Float(f64),
302    /// A UTF-8 string.
303    String(String),
304    /// Owned arbitrary bytes.
305    Bytes(Box<[u8]>),
306    /// An ordered array.
307    Array(Vec<MetadataValue>),
308    /// A nested string-keyed object.
309    Object(Metadata),
310}
311
312/// A borrowed view of every closed [`MetadataValue`] variant.
313///
314/// This view preserves exhaustive observation even though `MetadataValue` has a
315/// custom destructor and therefore cannot expose owned fields through by-value
316/// pattern matching.
317#[derive(Clone, Copy)]
318pub enum MetadataValueRef<'a> {
319    /// A null value.
320    Null,
321    /// A boolean value.
322    Bool(bool),
323    /// A signed integer.
324    Signed(i64),
325    /// An unsigned integer.
326    Unsigned(u64),
327    /// A floating-point value, including every `f64` bit pattern.
328    Float(f64),
329    /// A borrowed UTF-8 string.
330    String(&'a str),
331    /// Borrowed arbitrary bytes.
332    Bytes(&'a [u8]),
333    /// A borrowed ordered array.
334    Array(&'a [MetadataValue]),
335    /// A borrowed string-keyed object.
336    Object(&'a Metadata),
337}
338
339impl MetadataValue {
340    /// Borrows this value without losing its closed variant or payload.
341    #[must_use]
342    pub fn as_borrowed(&self) -> MetadataValueRef<'_> {
343        match self {
344            Self::Null => MetadataValueRef::Null,
345            Self::Bool(value) => MetadataValueRef::Bool(*value),
346            Self::Signed(value) => MetadataValueRef::Signed(*value),
347            Self::Unsigned(value) => MetadataValueRef::Unsigned(*value),
348            Self::Float(value) => MetadataValueRef::Float(*value),
349            Self::String(value) => MetadataValueRef::String(value.as_str()),
350            Self::Bytes(value) => MetadataValueRef::Bytes(value),
351            Self::Array(value) => MetadataValueRef::Array(value),
352            Self::Object(value) => MetadataValueRef::Object(value),
353        }
354    }
355}
356
357// The two metadata values render identically because they are the same value
358// seen from two sides; a reader should never have to know which one produced a
359// line of output. Both keep the discriminant, which is what makes the rendering
360// useful, and neither descends: `Array` and `Object` report a length, so no
361// formatter in this crate can walk a metadata tree.
362fn debug_metadata_value(formatter: &mut Formatter<'_>, value: MetadataValueRef<'_>) -> fmt::Result {
363    match value {
364        MetadataValueRef::Null => formatter.write_str("Null"),
365        // A scalar has no size to report, and reporting the scalar itself would
366        // emit content: ADR-018 names a PIN and a "boolean-ish answer" as
367        // exactly the low-entropy secrets a redaction must not hand back.
368        MetadataValueRef::Bool(_) => formatter.write_str("Bool(..)"),
369        MetadataValueRef::Signed(_) => formatter.write_str("Signed(..)"),
370        MetadataValueRef::Unsigned(_) => formatter.write_str("Unsigned(..)"),
371        MetadataValueRef::Float(_) => formatter.write_str("Float(..)"),
372        MetadataValueRef::String(text) => formatter
373            .debug_tuple("String")
374            .field(&redact::Bytes(text.len()))
375            .finish(),
376        MetadataValueRef::Bytes(bytes) => formatter
377            .debug_tuple("Bytes")
378            .field(&redact::Bytes(bytes.len()))
379            .finish(),
380        MetadataValueRef::Array(values) => formatter
381            .debug_tuple("Array")
382            .field(&redact::Items(values.len()))
383            .finish(),
384        MetadataValueRef::Object(metadata) => {
385            formatter.debug_tuple("Object").field(metadata).finish()
386        }
387    }
388}
389
390impl Debug for MetadataValue {
391    /// Names the variant and sizes the payload, without descending.
392    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
393        debug_metadata_value(formatter, self.as_borrowed())
394    }
395}
396
397impl Debug for MetadataValueRef<'_> {
398    /// Renders exactly as the owned value it borrows.
399    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
400        debug_metadata_value(formatter, *self)
401    }
402}
403
404impl Clone for MetadataValue {
405    fn clone(&self) -> Self {
406        enum Task<'a> {
407            Clone(&'a MetadataValue),
408            FinishArray(usize),
409            FinishObject(Vec<String>),
410        }
411
412        let mut tasks = vec![Task::Clone(self)];
413        let mut completed = Vec::new();
414
415        while let Some(task) = tasks.pop() {
416            match task {
417                Task::Clone(value) => match value {
418                    Self::Null => completed.push(Self::Null),
419                    Self::Bool(value) => completed.push(Self::Bool(*value)),
420                    Self::Signed(value) => completed.push(Self::Signed(*value)),
421                    Self::Unsigned(value) => completed.push(Self::Unsigned(*value)),
422                    Self::Float(value) => completed.push(Self::Float(*value)),
423                    Self::String(value) => completed.push(Self::String(value.clone())),
424                    Self::Bytes(value) => completed.push(Self::Bytes(value.clone())),
425                    Self::Array(values) => {
426                        tasks.push(Task::FinishArray(values.len()));
427                        tasks.extend(values.iter().rev().map(Task::Clone));
428                    }
429                    Self::Object(metadata) => {
430                        tasks.push(Task::FinishObject(metadata.0.keys().cloned().collect()));
431                        tasks.extend(metadata.0.values().rev().map(Task::Clone));
432                    }
433                },
434                Task::FinishArray(length) => {
435                    let values = completed.split_off(completed.len() - length);
436                    completed.push(Self::Array(values));
437                }
438                Task::FinishObject(keys) => {
439                    let values = completed.split_off(completed.len() - keys.len());
440                    completed.push(Self::Object(keys.into_iter().zip(values).collect()));
441                }
442            }
443        }
444
445        completed.remove(0)
446    }
447}
448
449impl Drop for MetadataValue {
450    fn drop(&mut self) {
451        let mut pending = Vec::new();
452        take_nested_values(self, &mut pending);
453        while let Some(mut value) = pending.pop() {
454            take_nested_values(&mut value, &mut pending);
455        }
456    }
457}
458
459fn take_nested_values(value: &mut MetadataValue, pending: &mut Vec<MetadataValue>) {
460    match value {
461        MetadataValue::Array(values) => pending.append(values),
462        MetadataValue::Object(metadata) => {
463            pending.extend(std::mem::take(&mut metadata.0).into_values());
464        }
465        MetadataValue::Null
466        | MetadataValue::Bool(_)
467        | MetadataValue::Signed(_)
468        | MetadataValue::Unsigned(_)
469        | MetadataValue::Float(_)
470        | MetadataValue::String(_)
471        | MetadataValue::Bytes(_) => {}
472    }
473}
474
475/// The complete owned field set of a [`Part`].
476///
477/// Fields are independent of kind. `None` and `Some(empty)` remain distinct.
478///
479/// ```
480/// use reef_core::opaque;
481/// use reef_core::value::content;
482/// let fields = content::PartFields::new(
483///     "body".into(), "text/custom".into(), Some(Vec::new().into_boxed_slice()),
484///     "ref".into(), Some(content::Metadata::new()), Some(opaque::Payload::from_vec(vec![])),
485/// );
486/// let part = content::Part::new(content::PartKind::from_i64(77), fields);
487/// assert_eq!(part.kind().as_i64(), 77);
488/// assert_eq!(part.fields().text(), "body");
489/// assert_eq!(part.fields().data(), Some([].as_slice()));
490/// ```
491#[derive(Clone)]
492pub struct PartFields {
493    text: String,
494    mime: String,
495    data: Option<Box<[u8]>>,
496    reference: String,
497    metadata: Option<Metadata>,
498    raw: Option<Payload>,
499}
500
501impl Debug for PartFields {
502    /// Sizes every model-visible field and keeps every presence distinction.
503    ///
504    /// `None`, `Some(<0 bytes>)` and `Some(<7 bytes>)` stay three different
505    /// renderings, because the distinction between absent and present-empty is
506    /// the thing this type exists to carry.
507    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
508        formatter
509            .debug_struct("PartFields")
510            .field("text", &redact::Bytes(self.text.len()))
511            .field("mime", &redact::Bytes(self.mime.len()))
512            .field(
513                "data",
514                &self.data.as_deref().map(|data| redact::Bytes(data.len())),
515            )
516            .field("reference", &redact::Bytes(self.reference.len()))
517            .field("metadata", &self.metadata)
518            .field("raw", &self.raw)
519            .finish()
520    }
521}
522
523impl PartFields {
524    /// Creates the complete field set without kind-dependent rewriting.
525    #[must_use]
526    pub const fn new(
527        text: String,
528        mime: String,
529        data: Option<Box<[u8]>>,
530        reference: String,
531        metadata: Option<Metadata>,
532        raw: Option<Payload>,
533    ) -> Self {
534        Self {
535            text,
536            mime,
537            data,
538            reference,
539            metadata,
540            raw,
541        }
542    }
543
544    /// Returns the text field.
545    #[must_use]
546    pub fn text(&self) -> &str {
547        &self.text
548    }
549
550    /// Returns the media-type field.
551    #[must_use]
552    pub fn mime(&self) -> &str {
553        &self.mime
554    }
555
556    /// Returns the optional byte data while retaining its presence state.
557    #[must_use]
558    pub fn data(&self) -> Option<&[u8]> {
559        self.data.as_deref()
560    }
561
562    /// Returns the external-reference field.
563    #[must_use]
564    pub fn reference(&self) -> &str {
565        &self.reference
566    }
567
568    /// Returns the optional metadata object.
569    #[must_use]
570    pub const fn metadata(&self) -> Option<&Metadata> {
571        self.metadata.as_ref()
572    }
573
574    /// Returns the optional opaque provider payload.
575    #[must_use]
576    pub const fn raw_payload(&self) -> Option<&Payload> {
577        self.raw.as_ref()
578    }
579}
580
581/// One field-complete message part with an open canonical kind.
582///
583/// ```compile_fail
584/// use reef_core::value::content;
585/// let _forged = content::Part { kind: content::PartKind::from_i64(0), fields: panic!() };
586/// ```
587#[derive(Clone, Debug)]
588pub struct Part {
589    kind: PartKind,
590    fields: PartFields,
591}
592
593impl Part {
594    /// Creates a part without rejecting or dropping cross-kind fields.
595    #[must_use]
596    pub const fn new(kind: PartKind, fields: PartFields) -> Self {
597        Self { kind, fields }
598    }
599
600    /// Creates ordinary text with every other field empty or absent.
601    #[must_use]
602    pub const fn text(text: String) -> Self {
603        Self::new(
604            KnownPartKind::Text.as_part_kind(),
605            PartFields::new(text, String::new(), None, String::new(), None, None),
606        )
607    }
608
609    /// Returns the canonical kind.
610    #[must_use]
611    pub const fn kind(&self) -> PartKind {
612        self.kind
613    }
614
615    /// Returns every field as one immutable value.
616    #[must_use]
617    pub const fn fields(&self) -> &PartFields {
618        &self.fields
619    }
620
621    /// Transfers the canonical kind and complete field set.
622    #[must_use]
623    pub fn into_parts(self) -> (PartKind, PartFields) {
624        (self.kind, self.fields)
625    }
626}
627
628// Validation is a predicate so accepted field-complete Parts are never rebuilt.
629pub(crate) fn is_valid_system_instruction(parts: &[Part]) -> bool {
630    parts.iter().all(|part| {
631        part.kind().known() == Some(KnownPartKind::Text) && !part.fields().text().is_empty()
632    })
633}
634
635/// Opaque extensions shared by every [`Segment`] variant.
636#[derive(Clone)]
637pub struct SegmentExtensions {
638    signature: String,
639    raw: Option<Payload>,
640    provider_data: Option<Vec<Envelope>>,
641    item_id: Option<String>,
642}
643
644impl Debug for SegmentExtensions {
645    /// Reports the signature's presence and withholds even its length.
646    ///
647    /// The signature is the crate's one credential-shaped value: a
648    /// provider-issued token reef neither produces nor interprets, whose only
649    /// job is to be replayed verbatim. Signature lengths are provider-stable, so
650    /// a byte count would fingerprint the provider and the reasoning mode behind
651    /// a transcript while helping nobody — a signature is debugged by whether it
652    /// survived a round trip, which [`SegmentExtensions::signature`] answers.
653    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
654        formatter
655            .debug_struct("SegmentExtensions")
656            .field("signature", &redact::Presence(!self.signature.is_empty()))
657            .field("raw", &self.raw)
658            .field("provider_data", &self.provider_data)
659            // Verbatim, like every other identifier in the crate. It is a
660            // provider-assigned label for a content item, carries none of the
661            // content, and is useless for correlating anything outside the one
662            // generation that minted it.
663            .field("item_id", &self.item_id)
664            .finish()
665    }
666}
667
668impl SegmentExtensions {
669    /// Creates extensions while preserving raw and collection presence.
670    ///
671    /// The item identity is not an argument, because a provider adapter does not
672    /// supply it here: reef stamps it from the identity the adapter already
673    /// declared on `model::Event::ContentFinal`. See
674    /// [`with_item_id`](Self::with_item_id).
675    #[must_use]
676    pub const fn new(
677        signature: String,
678        raw: Option<Payload>,
679        provider_data: Option<Vec<Envelope>>,
680    ) -> Self {
681        Self {
682            signature,
683            raw,
684            provider_data,
685            item_id: None,
686        }
687    }
688
689    /// Attaches the provider's identity for the content item this segment is.
690    ///
691    /// Reef calls this itself, with the `id` of the
692    /// `model::Event::ContentFinal` the segment was built from, which is why an
693    /// adapter never has to: the identity a provider declares on the stream is
694    /// the identity the record keeps. Setting it here twice is not a way to
695    /// disagree with the stream — reef overwrites whatever is present, because
696    /// `model::StreamGrammar` tracks exactly one identity per item and a second
697    /// place to say it would be a second thing to believe.
698    ///
699    /// An adapter that wants a different identity in the record declares a
700    /// different one on the stream. A registration that wants to rewrite it
701    /// after the fact does so in
702    /// [`ModelHooks::after_model`](crate::runtime::hook::ModelHooks::after_model),
703    /// which is handed the whole `item::Assistant` before it is committed and
704    /// whose replacement is what both the transcript and the outward
705    /// `Text`/`Thinking` events then report.
706    #[must_use]
707    pub fn with_item_id(mut self, id: String) -> Self {
708        self.item_id = Some(id);
709        self
710    }
711
712    /// Returns the provider's identity for this content item, when one is known.
713    ///
714    /// `None` for a segment no provider stream produced — one a hook composed,
715    /// or one restored from a record written before the identity was carried.
716    #[must_use]
717    pub fn item_id(&self) -> Option<&str> {
718        self.item_id.as_deref()
719    }
720
721    /// Returns the opaque reasoning-continuity signature.
722    #[must_use]
723    pub fn signature(&self) -> &str {
724        &self.signature
725    }
726
727    /// Returns the optional raw provider payload.
728    #[must_use]
729    pub const fn raw_payload(&self) -> Option<&Payload> {
730        self.raw.as_ref()
731    }
732
733    /// Returns ordered provider envelopes while retaining collection presence.
734    #[must_use]
735    pub fn provider_data(&self) -> Option<&[Envelope]> {
736        self.provider_data.as_deref()
737    }
738
739    /// Transfers all extension fields.
740    #[must_use]
741    pub fn into_parts(
742        self,
743    ) -> (
744        String,
745        Option<Payload>,
746        Option<Vec<Envelope>>,
747        Option<String>,
748    ) {
749        (self.signature, self.raw, self.provider_data, self.item_id)
750    }
751}
752
753/// One ordered, producer-valid assistant-content segment.
754///
755/// The enum excludes text/thinking segments with calls and call segments without
756/// calls. Public variants are the complete construction and observation API.
757///
758/// ```
759/// use reef_core::opaque;
760/// use reef_core::value::{content, tool_call};
761/// let extensions = || content::SegmentExtensions::new(String::new(), None, Some(vec![]));
762/// let segments = [
763///     content::Segment::Text { text: "answer".into(), extensions: extensions() },
764///     content::Segment::Thinking { text: "reason".into(), extensions: extensions() },
765///     content::Segment::ToolCall {
766///         call: tool_call::ToolCall::new(tool_call::Id::new("id".into()), tool_call::Name::new("tool".into()), opaque::Payload::from_vec(vec![])),
767///         extensions: extensions(),
768///     },
769/// ];
770/// assert!(matches!(&segments[0], content::Segment::Text { text, extensions } if text == "answer" && extensions.provider_data().is_some_and(<[_]>::is_empty)));
771/// assert!(matches!(&segments[1], content::Segment::Thinking { text, .. } if text == "reason"));
772/// assert!(matches!(&segments[2], content::Segment::ToolCall { call, .. } if call.id().as_str() == "id"));
773/// ```
774#[derive(Clone)]
775pub enum Segment {
776    /// Model-visible answer text.
777    Text {
778        /// The text exactly as produced.
779        text: String,
780        /// Opaque provider extensions attached to this segment.
781        extensions: SegmentExtensions,
782    },
783    /// Reasoning or thinking content.
784    Thinking {
785        /// The reasoning text exactly as produced.
786        text: String,
787        /// Opaque provider extensions attached to this segment.
788        extensions: SegmentExtensions,
789    },
790    /// A model-initiated tool invocation.
791    ToolCall {
792        /// The complete tool invocation.
793        call: super::tool_call::ToolCall,
794        /// Opaque provider extensions attached to this segment.
795        extensions: SegmentExtensions,
796    },
797}
798
799impl Debug for Segment {
800    /// Keeps the variant and sizes the text, in both content lanes alike.
801    ///
802    /// Reasoning is not a stricter tier than answer text. Tier 2 already emits
803    /// zero content bytes, so "stricter" could only mean "emit nothing" — and a
804    /// provider is free to deliver reasoning inside [`Segment::Text`] anyway, so
805    /// a thinking-only rule would be a guarantee the data can walk around. What
806    /// a compliance-minded operator needs survives: the discriminant states
807    /// *that* the model reasoned and the size states *how much*.
808    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
809        match self {
810            Self::Text { text, extensions } => formatter
811                .debug_struct("Text")
812                .field("text", &redact::Bytes(text.len()))
813                .field("extensions", extensions)
814                .finish(),
815            Self::Thinking { text, extensions } => formatter
816                .debug_struct("Thinking")
817                .field("text", &redact::Bytes(text.len()))
818                .field("extensions", extensions)
819                .finish(),
820            Self::ToolCall { call, extensions } => formatter
821                .debug_struct("ToolCall")
822                .field("call", call)
823                .field("extensions", extensions)
824                .finish(),
825        }
826    }
827}
828
829/// Joins the text-bearing blocks of one record with a single newline.
830///
831/// Every plain-text rendering in this crate separates two blocks with one `\n`
832/// and adds nothing else, so the convention lives here rather than once per
833/// caller: a record with one block renders exactly that block, and a block with
834/// no text contributes nothing instead of an empty line.
835pub(crate) fn join_blocks<'a>(blocks: impl Iterator<Item = &'a str>) -> String {
836    let mut rendered = String::new();
837    for block in blocks.filter(|block| !block.is_empty()) {
838        if !rendered.is_empty() {
839            rendered.push('\n');
840        }
841        rendered.push_str(block);
842    }
843    rendered
844}
845
846/// The serialized form of the content value tree (ADR-019 D5).
847///
848/// Three shapes are worth naming before reading the code.
849///
850/// **`PartKind` is a bare integer.** ADR-004's own fixtures already show it that
851/// way, and the newtype is a Rust representation detail rather than something the
852/// wire should learn about. The same is true of the byte payloads: they travel as
853/// serde byte strings, never base64, because core may not re-encode bytes it
854/// never parsed.
855///
856/// **Nothing is omitted.** `None` is written as the format's null and
857/// `Some(empty)` as an empty string, array or object, so the absent-versus-
858/// present-empty distinction that [`PartFields`] exists to carry survives a round
859/// trip. `PartFields::reference` is spelled `reference` in full; abbreviating it
860/// to `ref` for some other wire is a separate adapter's business.
861///
862/// **[`MetadataValue`] carries a depth.** Every nested value is serialized
863/// through a private wrapper that knows how deep it is and refuses to go past
864/// [`MAX_METADATA_DEPTH`], in both directions. See that constant for why a bound
865/// is the only available answer here.
866#[cfg(feature = "serde")]
867mod serde_impl {
868    use std::fmt::{self, Formatter};
869
870    use serde_core::de::{
871        Deserialize, DeserializeSeed, Deserializer, EnumAccess, Error as DeError, MapAccess,
872        SeqAccess, VariantAccess, Visitor,
873    };
874    use serde_core::ser::{
875        Error as SerError, Serialize, SerializeMap, SerializeSeq, SerializeStruct,
876        SerializeStructVariant, Serializer,
877    };
878
879    use super::{Metadata, MetadataValue, Part, PartFields, PartKind, Segment, SegmentExtensions};
880    use crate::opaque::{Envelope, Payload};
881    use crate::wire::{self, ByteBuf, Bytes, IdentifierSeed};
882
883    /// The nesting depth beyond which a [`MetadataValue`] is refused.
884    ///
885    /// `MetadataValue`'s own documentation states the bound and why serde is the
886    /// one traversal in this crate that cannot be made iterative; this is where
887    /// the bound is enforced.
888    pub(super) const MAX_METADATA_DEPTH: usize = 128;
889
890    const VALUE_NAME: &str = "MetadataValue";
891    const VALUE_VARIANTS: &[&str] = &[
892        "null", "bool", "signed", "unsigned", "float", "string", "bytes", "array", "object",
893    ];
894    const PART_FIELDS: &[&str] = &["kind", "fields"];
895    const FIELDS_FIELDS: &[&str] = &["text", "mime", "data", "reference", "metadata", "raw"];
896    const EXTENSIONS_FIELDS: &[&str] = &["signature", "raw", "provider_data", "item_id"];
897    const SEGMENT_NAME: &str = "Segment";
898    const SEGMENT_VARIANTS: &[&str] = &["text", "thinking", "tool_call"];
899    const TEXT_SEGMENT_FIELDS: &[&str] = &["text", "extensions"];
900    const TOOL_CALL_SEGMENT_FIELDS: &[&str] = &["call", "extensions"];
901
902    /// Names the depth bound in the one sentence a caller can act on.
903    struct TooDeep;
904
905    impl fmt::Display for TooDeep {
906        fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
907            write!(
908                formatter,
909                "metadata value nests deeper than the {MAX_METADATA_DEPTH}-level serialization limit"
910            )
911        }
912    }
913
914    // -- PartKind ------------------------------------------------------------
915
916    impl Serialize for PartKind {
917        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
918        where
919            S: Serializer,
920        {
921            serializer.serialize_i64(self.0)
922        }
923    }
924
925    impl<'de> Deserialize<'de> for PartKind {
926        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
927        where
928            D: Deserializer<'de>,
929        {
930            i64::deserialize(deserializer).map(Self::from_i64)
931        }
932    }
933
934    // -- MetadataValue and Metadata ------------------------------------------
935
936    /// One metadata value that knows how deeply it is nested.
937    struct DepthValue<'a>(&'a MetadataValue, usize);
938
939    /// Array elements whose own nesting depth is one below their array's.
940    struct DepthElements<'a>(&'a [MetadataValue], usize);
941
942    /// Object entries whose values' nesting depth is one below their object's.
943    struct DepthEntries<'a>(&'a Metadata, usize);
944
945    impl Serialize for DepthValue<'_> {
946        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
947        where
948            S: Serializer,
949        {
950            if self.1 > MAX_METADATA_DEPTH {
951                return Err(S::Error::custom(TooDeep));
952            }
953            let nested = self.1 + 1;
954            match self.0 {
955                MetadataValue::Null => serializer.serialize_unit_variant(VALUE_NAME, 0, "null"),
956                MetadataValue::Bool(value) => {
957                    serializer.serialize_newtype_variant(VALUE_NAME, 1, "bool", value)
958                }
959                MetadataValue::Signed(value) => {
960                    serializer.serialize_newtype_variant(VALUE_NAME, 2, "signed", value)
961                }
962                MetadataValue::Unsigned(value) => {
963                    serializer.serialize_newtype_variant(VALUE_NAME, 3, "unsigned", value)
964                }
965                MetadataValue::Float(value) => {
966                    serializer.serialize_newtype_variant(VALUE_NAME, 4, "float", value)
967                }
968                MetadataValue::String(value) => {
969                    serializer.serialize_newtype_variant(VALUE_NAME, 5, "string", value)
970                }
971                MetadataValue::Bytes(value) => {
972                    serializer.serialize_newtype_variant(VALUE_NAME, 6, "bytes", &Bytes(value))
973                }
974                MetadataValue::Array(values) => serializer.serialize_newtype_variant(
975                    VALUE_NAME,
976                    7,
977                    "array",
978                    &DepthElements(values, nested),
979                ),
980                MetadataValue::Object(metadata) => serializer.serialize_newtype_variant(
981                    VALUE_NAME,
982                    8,
983                    "object",
984                    &DepthEntries(metadata, nested),
985                ),
986            }
987        }
988    }
989
990    impl Serialize for DepthElements<'_> {
991        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
992        where
993            S: Serializer,
994        {
995            let mut sequence = serializer.serialize_seq(Some(self.0.len()))?;
996            for value in self.0 {
997                sequence.serialize_element(&DepthValue(value, self.1))?;
998            }
999            sequence.end()
1000        }
1001    }
1002
1003    impl Serialize for DepthEntries<'_> {
1004        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1005        where
1006            S: Serializer,
1007        {
1008            let mut entries = serializer.serialize_map(Some(self.0.iter().len()))?;
1009            for (key, value) in self.0 {
1010                entries.serialize_entry(key, &DepthValue(value, self.1))?;
1011            }
1012            entries.end()
1013        }
1014    }
1015
1016    impl Serialize for MetadataValue {
1017        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1018        where
1019            S: Serializer,
1020        {
1021            DepthValue(self, 1).serialize(serializer)
1022        }
1023    }
1024
1025    impl Serialize for Metadata {
1026        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1027        where
1028            S: Serializer,
1029        {
1030            DepthEntries(self, 1).serialize(serializer)
1031        }
1032    }
1033
1034    /// Reads one metadata value, refusing to descend past the depth bound.
1035    struct ValueSeed(usize);
1036
1037    impl<'de> DeserializeSeed<'de> for ValueSeed {
1038        type Value = MetadataValue;
1039
1040        fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
1041        where
1042            D: Deserializer<'de>,
1043        {
1044            if self.0 > MAX_METADATA_DEPTH {
1045                return Err(D::Error::custom(TooDeep));
1046            }
1047            deserializer.deserialize_enum(VALUE_NAME, VALUE_VARIANTS, ValueVisitor(self.0))
1048        }
1049    }
1050
1051    struct ValueVisitor(usize);
1052
1053    impl<'de> Visitor<'de> for ValueVisitor {
1054        type Value = MetadataValue;
1055
1056        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1057            formatter.write_str("a metadata value")
1058        }
1059
1060        fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
1061        where
1062            A: EnumAccess<'de>,
1063        {
1064            let (tag, variant) = data.variant_seed(IdentifierSeed(VALUE_VARIANTS))?;
1065            let nested = self.0 + 1;
1066            match tag.0.as_str() {
1067                "null" => {
1068                    variant.unit_variant()?;
1069                    Ok(MetadataValue::Null)
1070                }
1071                "bool" => variant.newtype_variant().map(MetadataValue::Bool),
1072                "signed" => variant.newtype_variant().map(MetadataValue::Signed),
1073                "unsigned" => variant.newtype_variant().map(MetadataValue::Unsigned),
1074                "float" => variant.newtype_variant().map(MetadataValue::Float),
1075                "string" => variant.newtype_variant().map(MetadataValue::String),
1076                "bytes" => variant
1077                    .newtype_variant::<ByteBuf>()
1078                    .map(|buffer| MetadataValue::Bytes(buffer.0)),
1079                "array" => variant
1080                    .newtype_variant_seed(ElementsSeed(nested))
1081                    .map(MetadataValue::Array),
1082                "object" => variant
1083                    .newtype_variant_seed(EntriesSeed(nested))
1084                    .map(MetadataValue::Object),
1085                unknown => Err(A::Error::unknown_variant(unknown, VALUE_VARIANTS)),
1086            }
1087        }
1088    }
1089
1090    struct ElementsSeed(usize);
1091
1092    impl<'de> DeserializeSeed<'de> for ElementsSeed {
1093        type Value = Vec<MetadataValue>;
1094
1095        fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
1096        where
1097            D: Deserializer<'de>,
1098        {
1099            deserializer.deserialize_seq(ElementsVisitor(self.0))
1100        }
1101    }
1102
1103    struct ElementsVisitor(usize);
1104
1105    impl<'de> Visitor<'de> for ElementsVisitor {
1106        type Value = Vec<MetadataValue>;
1107
1108        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1109            formatter.write_str("an array of metadata values")
1110        }
1111
1112        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1113        where
1114            A: SeqAccess<'de>,
1115        {
1116            let mut values = Vec::new();
1117            while let Some(value) = sequence.next_element_seed(ValueSeed(self.0))? {
1118                values.push(value);
1119            }
1120            Ok(values)
1121        }
1122    }
1123
1124    struct EntriesSeed(usize);
1125
1126    impl<'de> DeserializeSeed<'de> for EntriesSeed {
1127        type Value = Metadata;
1128
1129        fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
1130        where
1131            D: Deserializer<'de>,
1132        {
1133            deserializer.deserialize_map(EntriesVisitor(self.0))
1134        }
1135    }
1136
1137    struct EntriesVisitor(usize);
1138
1139    impl<'de> Visitor<'de> for EntriesVisitor {
1140        type Value = Metadata;
1141
1142        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1143            formatter.write_str("a metadata object")
1144        }
1145
1146        /// Builds through the public constructor, so a repeated key keeps the
1147        /// last value exactly as [`Metadata::from_iter`] documents.
1148        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1149        where
1150            A: MapAccess<'de>,
1151        {
1152            let mut metadata = Metadata::new();
1153            while let Some(key) = entries.next_key::<String>()? {
1154                let value = entries.next_value_seed(ValueSeed(self.0))?;
1155                drop(metadata.insert(key, value));
1156            }
1157            Ok(metadata)
1158        }
1159    }
1160
1161    impl<'de> Deserialize<'de> for MetadataValue {
1162        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1163        where
1164            D: Deserializer<'de>,
1165        {
1166            ValueSeed(1).deserialize(deserializer)
1167        }
1168    }
1169
1170    impl<'de> Deserialize<'de> for Metadata {
1171        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1172        where
1173            D: Deserializer<'de>,
1174        {
1175            EntriesSeed(1).deserialize(deserializer)
1176        }
1177    }
1178
1179    // -- PartFields ----------------------------------------------------------
1180
1181    impl Serialize for PartFields {
1182        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1183        where
1184            S: Serializer,
1185        {
1186            let mut record = serializer.serialize_struct("PartFields", 6)?;
1187            record.serialize_field("text", &self.text)?;
1188            record.serialize_field("mime", &self.mime)?;
1189            record.serialize_field("data", &self.data.as_deref().map(Bytes))?;
1190            record.serialize_field("reference", &self.reference)?;
1191            record.serialize_field("metadata", &self.metadata)?;
1192            record.serialize_field("raw", &self.raw)?;
1193            record.end()
1194        }
1195    }
1196
1197    impl<'de> Deserialize<'de> for PartFields {
1198        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1199        where
1200            D: Deserializer<'de>,
1201        {
1202            deserializer.deserialize_struct("PartFields", FIELDS_FIELDS, FieldsVisitor)
1203        }
1204    }
1205
1206    struct FieldsVisitor;
1207
1208    impl<'de> Visitor<'de> for FieldsVisitor {
1209        type Value = PartFields;
1210
1211        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1212            formatter.write_str("a complete part field set")
1213        }
1214
1215        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1216        where
1217            A: SeqAccess<'de>,
1218        {
1219            let text = wire::element(&mut sequence, 0)?;
1220            let mime = wire::element(&mut sequence, 1)?;
1221            let data = wire::element::<Option<ByteBuf>, _>(&mut sequence, 2)?;
1222            let reference = wire::element(&mut sequence, 3)?;
1223            let metadata = wire::element(&mut sequence, 4)?;
1224            let raw = wire::element(&mut sequence, 5)?;
1225            wire::end(&mut sequence, 6)?;
1226            Ok(PartFields::new(
1227                text,
1228                mime,
1229                ByteBuf::into_optional(data),
1230                reference,
1231                metadata,
1232                raw,
1233            ))
1234        }
1235
1236        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1237        where
1238            A: MapAccess<'de>,
1239        {
1240            let mut text = None;
1241            let mut mime = None;
1242            let mut data = None::<Option<ByteBuf>>;
1243            let mut reference = None;
1244            let mut metadata = None;
1245            let mut raw = None;
1246            while let Some(field) = entries.next_key_seed(IdentifierSeed(FIELDS_FIELDS))? {
1247                match field.0.as_str() {
1248                    "text" => wire::accept(&mut text, entries.next_value()?, "text")?,
1249                    "mime" => wire::accept(&mut mime, entries.next_value()?, "mime")?,
1250                    "data" => wire::accept(&mut data, entries.next_value()?, "data")?,
1251                    "reference" => {
1252                        wire::accept(&mut reference, entries.next_value()?, "reference")?;
1253                    }
1254                    "metadata" => wire::accept(&mut metadata, entries.next_value()?, "metadata")?,
1255                    "raw" => wire::accept(&mut raw, entries.next_value()?, "raw")?,
1256                    unknown => return Err(A::Error::unknown_field(unknown, FIELDS_FIELDS)),
1257                }
1258            }
1259            Ok(PartFields::new(
1260                wire::require(text, "text")?,
1261                wire::require(mime, "mime")?,
1262                ByteBuf::into_optional(wire::require(data, "data")?),
1263                wire::require(reference, "reference")?,
1264                wire::require(metadata, "metadata")?,
1265                wire::require(raw, "raw")?,
1266            ))
1267        }
1268    }
1269
1270    // -- Part ----------------------------------------------------------------
1271
1272    impl Serialize for Part {
1273        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1274        where
1275            S: Serializer,
1276        {
1277            let mut record = serializer.serialize_struct("Part", 2)?;
1278            record.serialize_field("kind", &self.kind)?;
1279            record.serialize_field("fields", &self.fields)?;
1280            record.end()
1281        }
1282    }
1283
1284    impl<'de> Deserialize<'de> for Part {
1285        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1286        where
1287            D: Deserializer<'de>,
1288        {
1289            deserializer.deserialize_struct("Part", PART_FIELDS, PartVisitor)
1290        }
1291    }
1292
1293    struct PartVisitor;
1294
1295    impl<'de> Visitor<'de> for PartVisitor {
1296        type Value = Part;
1297
1298        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1299            formatter.write_str("a message part")
1300        }
1301
1302        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1303        where
1304            A: SeqAccess<'de>,
1305        {
1306            let kind = wire::element(&mut sequence, 0)?;
1307            let fields = wire::element(&mut sequence, 1)?;
1308            wire::end(&mut sequence, 2)?;
1309            Ok(Part::new(kind, fields))
1310        }
1311
1312        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1313        where
1314            A: MapAccess<'de>,
1315        {
1316            let mut kind = None;
1317            let mut fields = None;
1318            while let Some(field) = entries.next_key_seed(IdentifierSeed(PART_FIELDS))? {
1319                match field.0.as_str() {
1320                    "kind" => wire::accept(&mut kind, entries.next_value()?, "kind")?,
1321                    "fields" => wire::accept(&mut fields, entries.next_value()?, "fields")?,
1322                    unknown => return Err(A::Error::unknown_field(unknown, PART_FIELDS)),
1323                }
1324            }
1325            Ok(Part::new(
1326                wire::require(kind, "kind")?,
1327                wire::require(fields, "fields")?,
1328            ))
1329        }
1330    }
1331
1332    // -- SegmentExtensions ---------------------------------------------------
1333
1334    /// Rebuilds extensions from the complete field set, identity included.
1335    ///
1336    /// `SegmentExtensions::new` deliberately takes no identity, because a
1337    /// provider adapter does not supply one there. Reading a record is the one
1338    /// place that has to restore every field it wrote, so it goes through the
1339    /// builder rather than through a constructor an adapter would misread.
1340    fn extensions(
1341        signature: String,
1342        raw: Option<Payload>,
1343        provider_data: Option<Vec<Envelope>>,
1344        item_id: Option<String>,
1345    ) -> SegmentExtensions {
1346        let extensions = SegmentExtensions::new(signature, raw, provider_data);
1347        match item_id {
1348            Some(id) => extensions.with_item_id(id),
1349            None => extensions,
1350        }
1351    }
1352
1353    impl Serialize for SegmentExtensions {
1354        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1355        where
1356            S: Serializer,
1357        {
1358            let mut record = serializer.serialize_struct("SegmentExtensions", 4)?;
1359            record.serialize_field("signature", &self.signature)?;
1360            record.serialize_field("raw", &self.raw)?;
1361            record.serialize_field("provider_data", &self.provider_data)?;
1362            record.serialize_field("item_id", &self.item_id)?;
1363            record.end()
1364        }
1365    }
1366
1367    impl<'de> Deserialize<'de> for SegmentExtensions {
1368        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1369        where
1370            D: Deserializer<'de>,
1371        {
1372            deserializer.deserialize_struct(
1373                "SegmentExtensions",
1374                EXTENSIONS_FIELDS,
1375                ExtensionsVisitor,
1376            )
1377        }
1378    }
1379
1380    struct ExtensionsVisitor;
1381
1382    impl<'de> Visitor<'de> for ExtensionsVisitor {
1383        type Value = SegmentExtensions;
1384
1385        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1386            formatter.write_str("segment extensions")
1387        }
1388
1389        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1390        where
1391            A: SeqAccess<'de>,
1392        {
1393            let signature = wire::element(&mut sequence, 0)?;
1394            let raw = wire::element(&mut sequence, 1)?;
1395            let provider_data = wire::element(&mut sequence, 2)?;
1396            let item_id = wire::element(&mut sequence, 3)?;
1397            wire::end(&mut sequence, 4)?;
1398            Ok(extensions(signature, raw, provider_data, item_id))
1399        }
1400
1401        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1402        where
1403            A: MapAccess<'de>,
1404        {
1405            let mut signature = None;
1406            let mut raw = None;
1407            let mut provider_data = None;
1408            let mut item_id = None;
1409            while let Some(field) = entries.next_key_seed(IdentifierSeed(EXTENSIONS_FIELDS))? {
1410                match field.0.as_str() {
1411                    "signature" => {
1412                        wire::accept(&mut signature, entries.next_value()?, "signature")?;
1413                    }
1414                    "raw" => wire::accept(&mut raw, entries.next_value()?, "raw")?,
1415                    "provider_data" => {
1416                        wire::accept(&mut provider_data, entries.next_value()?, "provider_data")?;
1417                    }
1418                    "item_id" => wire::accept(&mut item_id, entries.next_value()?, "item_id")?,
1419                    unknown => return Err(A::Error::unknown_field(unknown, EXTENSIONS_FIELDS)),
1420                }
1421            }
1422            Ok(extensions(
1423                wire::require(signature, "signature")?,
1424                wire::require(raw, "raw")?,
1425                wire::require(provider_data, "provider_data")?,
1426                wire::require(item_id, "item_id")?,
1427            ))
1428        }
1429    }
1430
1431    // -- Segment -------------------------------------------------------------
1432
1433    const fn text_segment(text: String, extensions: SegmentExtensions) -> Segment {
1434        Segment::Text { text, extensions }
1435    }
1436
1437    const fn thinking_segment(text: String, extensions: SegmentExtensions) -> Segment {
1438        Segment::Thinking { text, extensions }
1439    }
1440
1441    impl Serialize for Segment {
1442        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1443        where
1444            S: Serializer,
1445        {
1446            match self {
1447                Self::Text { text, extensions } => {
1448                    let mut record =
1449                        serializer.serialize_struct_variant(SEGMENT_NAME, 0, "text", 2)?;
1450                    record.serialize_field("text", text)?;
1451                    record.serialize_field("extensions", extensions)?;
1452                    record.end()
1453                }
1454                Self::Thinking { text, extensions } => {
1455                    let mut record =
1456                        serializer.serialize_struct_variant(SEGMENT_NAME, 1, "thinking", 2)?;
1457                    record.serialize_field("text", text)?;
1458                    record.serialize_field("extensions", extensions)?;
1459                    record.end()
1460                }
1461                Self::ToolCall { call, extensions } => {
1462                    let mut record =
1463                        serializer.serialize_struct_variant(SEGMENT_NAME, 2, "tool_call", 2)?;
1464                    record.serialize_field("call", call)?;
1465                    record.serialize_field("extensions", extensions)?;
1466                    record.end()
1467                }
1468            }
1469        }
1470    }
1471
1472    impl<'de> Deserialize<'de> for Segment {
1473        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1474        where
1475            D: Deserializer<'de>,
1476        {
1477            deserializer.deserialize_enum(SEGMENT_NAME, SEGMENT_VARIANTS, SegmentVisitor)
1478        }
1479    }
1480
1481    struct SegmentVisitor;
1482
1483    impl<'de> Visitor<'de> for SegmentVisitor {
1484        type Value = Segment;
1485
1486        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1487            formatter.write_str("an assistant content segment")
1488        }
1489
1490        fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
1491        where
1492            A: EnumAccess<'de>,
1493        {
1494            let (tag, variant) = data.variant_seed(IdentifierSeed(SEGMENT_VARIANTS))?;
1495            match tag.0.as_str() {
1496                "text" => variant.struct_variant(TEXT_SEGMENT_FIELDS, TextVisitor(text_segment)),
1497                "thinking" => {
1498                    variant.struct_variant(TEXT_SEGMENT_FIELDS, TextVisitor(thinking_segment))
1499                }
1500                "tool_call" => {
1501                    variant.struct_variant(TOOL_CALL_SEGMENT_FIELDS, ToolCallSegmentVisitor)
1502                }
1503                unknown => Err(A::Error::unknown_variant(unknown, SEGMENT_VARIANTS)),
1504            }
1505        }
1506    }
1507
1508    /// Reads the two text-bearing segment variants, which differ only in which
1509    /// one they build.
1510    struct TextVisitor(fn(String, SegmentExtensions) -> Segment);
1511
1512    impl<'de> Visitor<'de> for TextVisitor {
1513        type Value = Segment;
1514
1515        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1516            formatter.write_str("a text-bearing segment")
1517        }
1518
1519        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1520        where
1521            A: SeqAccess<'de>,
1522        {
1523            let text = wire::element(&mut sequence, 0)?;
1524            let extensions = wire::element(&mut sequence, 1)?;
1525            wire::end(&mut sequence, 2)?;
1526            Ok((self.0)(text, extensions))
1527        }
1528
1529        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1530        where
1531            A: MapAccess<'de>,
1532        {
1533            let mut text = None;
1534            let mut extensions = None;
1535            while let Some(field) = entries.next_key_seed(IdentifierSeed(TEXT_SEGMENT_FIELDS))? {
1536                match field.0.as_str() {
1537                    "text" => wire::accept(&mut text, entries.next_value()?, "text")?,
1538                    "extensions" => {
1539                        wire::accept(&mut extensions, entries.next_value()?, "extensions")?;
1540                    }
1541                    unknown => return Err(A::Error::unknown_field(unknown, TEXT_SEGMENT_FIELDS)),
1542                }
1543            }
1544            Ok((self.0)(
1545                wire::require(text, "text")?,
1546                wire::require(extensions, "extensions")?,
1547            ))
1548        }
1549    }
1550
1551    struct ToolCallSegmentVisitor;
1552
1553    impl<'de> Visitor<'de> for ToolCallSegmentVisitor {
1554        type Value = Segment;
1555
1556        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
1557            formatter.write_str("a tool-call segment")
1558        }
1559
1560        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
1561        where
1562            A: SeqAccess<'de>,
1563        {
1564            let call = wire::element(&mut sequence, 0)?;
1565            let extensions = wire::element(&mut sequence, 1)?;
1566            wire::end(&mut sequence, 2)?;
1567            Ok(Segment::ToolCall { call, extensions })
1568        }
1569
1570        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
1571        where
1572            A: MapAccess<'de>,
1573        {
1574            let mut call = None;
1575            let mut extensions = None;
1576            while let Some(field) =
1577                entries.next_key_seed(IdentifierSeed(TOOL_CALL_SEGMENT_FIELDS))?
1578            {
1579                match field.0.as_str() {
1580                    "call" => wire::accept(&mut call, entries.next_value()?, "call")?,
1581                    "extensions" => {
1582                        wire::accept(&mut extensions, entries.next_value()?, "extensions")?;
1583                    }
1584                    unknown => {
1585                        return Err(A::Error::unknown_field(unknown, TOOL_CALL_SEGMENT_FIELDS));
1586                    }
1587                }
1588            }
1589            Ok(Segment::ToolCall {
1590                call: wire::require(call, "call")?,
1591                extensions: wire::require(extensions, "extensions")?,
1592            })
1593        }
1594    }
1595}