serde_saphyr/de/

deserializer.rs

use std::collections::{HashSet, VecDeque};
use std::{borrow::Cow, fmt};

use granit_parser::ScalarStyle;
use serde_core::de::{self, Deserializer as _, IntoDeserializer, Visitor};

use super::base64::decode_base64_yaml;
use super::cfg::Cfg;
#[cfg(feature = "comments")]
use super::commented_deser;
use super::error::{Error, MissingFieldLocationGuard, TransformReason};
use super::events::{
    Ev, Events, RecordedEvents, ReplayEvents, attach_alias_locations_if_missing, eof_with_loc,
    with_deferred_recursive_aliases,
};
use super::key_nodes::{
    KeyFingerprint, KeyNode, PendingEntry, apply_duplicate_key_policy_to_entries,
    capture_node_with_legacy_octal, capture_simple_tagged_node_as_map_events,
    is_empty_mapping_key_fingerprint, is_merge_key, pending_entries_from_live_events,
    simple_tagged_enum_name, validate_no_merge_keys_in_node_events,
};
#[cfg(feature = "properties")]
use super::options::PropertySyntax;
use super::options::{DuplicateKeyPolicy, MergeKeyPolicy, NonFiniteFloatPolicy};
#[cfg(any(feature = "garde", feature = "validator"))]
use super::path_map::PathRecorder;
#[cfg(feature = "properties")]
use super::properties::{interpolate_compose_style_with_limits, is_sole_unset_reference};
use super::properties_redaction::{
    ScalarRedactionCtx, ScalarRedactionGuard, with_interp_redaction_scope,
};
use super::spanned_deser;
use super::tagged_deser;
use super::tags::SfTag;
use crate::anchor_store::{self, AnchorKind};
#[cfg(feature = "properties")]
use crate::budget::BudgetBreach;
#[cfg(feature = "properties")]
use crate::de_error::budget_error;
use crate::location::Location;
#[cfg(any(feature = "garde", feature = "validator"))]
use crate::location::Locations;
use crate::parse_scalars::{
    leading_zero_decimal, maybe_not_string, parse_int_signed, parse_int_unsigned,
    parse_yaml11_bool, parse_yaml12_bool, parse_yaml12_float, scalar_is_null, scalar_is_nullish,
    try_parse_float_incl_overflow, yaml_trim,
};

struct TupleLenExpected {
    len: usize,
}

impl fmt::Display for TupleLenExpected {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "a tuple of size {}", self.len)
    }
}

impl de::Expected for TupleLenExpected {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, formatter)
    }
}

struct TupleLenVisitor<V> {
    inner: V,
    len: usize,
}

impl<'de, V> Visitor<'de> for TupleLenVisitor<V>
where
    V: Visitor<'de>,
{
    type Value = V::Value;

    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.inner.expecting(formatter)
    }

    fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
    where
        A: de::SeqAccess<'de>,
    {
        let mut consumed = 0usize;
        let value = self.inner.visit_seq(CountingSeqAccess {
            inner: &mut seq,
            consumed: &mut consumed,
        })?;

        if seq.next_element::<de::IgnoredAny>()?.is_some() {
            return Err(<A::Error as de::Error>::invalid_length(
                consumed + 1,
                &TupleLenExpected { len: self.len },
            ));
        }

        Ok(value)
    }
}

struct CountingSeqAccess<'a, A> {
    inner: &'a mut A,
    consumed: &'a mut usize,
}

impl<'de, A> de::SeqAccess<'de> for CountingSeqAccess<'_, A>
where
    A: de::SeqAccess<'de>,
{
    type Error = A::Error;

    fn next_element_seed<T>(&mut self, seed: T) -> Result<Option<T::Value>, Self::Error>
    where
        T: de::DeserializeSeed<'de>,
    {
        let value = self.inner.next_element_seed(seed)?;
        if value.is_some() {
            *self.consumed += 1;
        }
        Ok(value)
    }

    fn size_hint(&self) -> Option<usize> {
        self.inner.size_hint()
    }
}

fn skip_one_node_from_events(ev: &mut dyn Events<'_>) -> Result<(), Error> {
    let mut depth;
    match ev.next()? {
        Some(Ev::RecursiveAlias { location, .. }) => {
            return Err(Error::RecursiveReferencesRequireWeakTypes { location });
        }
        Some(Ev::Scalar { .. }) => return Ok(()),
        Some(Ev::SeqStart { .. } | Ev::MapStart { .. }) => depth = 1usize,
        Some(Ev::SeqEnd { location } | Ev::MapEnd { location }) => {
            return Err(Error::UnexpectedContainerEndWhileSkippingNode { location });
        }
        Some(Ev::Taken { location }) => {
            return Err(Error::unexpected("consumed event").with_location(location));
        }
        None => return Err(eof_with_loc(ev)),
    }

    while depth != 0 {
        match ev.next()? {
            Some(Ev::RecursiveAlias { location, .. }) => {
                return Err(Error::RecursiveReferencesRequireWeakTypes { location });
            }
            Some(Ev::SeqStart { .. } | Ev::MapStart { .. }) => depth += 1,
            Some(Ev::SeqEnd { .. } | Ev::MapEnd { .. }) => depth -= 1,
            Some(Ev::Scalar { .. }) => {}
            Some(Ev::Taken { location }) => {
                return Err(Error::unexpected("consumed event").with_location(location));
            }
            None => return Err(eof_with_loc(ev)),
        }
    }

    Ok(())
}

fn drain_remaining_sequence(ev: &mut dyn Events<'_>) -> Result<(), Error> {
    loop {
        match ev.peek()? {
            Some(Ev::SeqEnd { .. }) => {
                let _ = ev.next()?;
                return Ok(());
            }
            Some(_) => skip_one_node_from_events(ev)?,
            None => return Err(eof_with_loc(ev)),
        }
    }
}

/// Whether a mapping must remember the keys it has seen: duplicate-key policies and merge
/// expansion read them back, but passing duplicates through without merging never does.
fn remembers_seen_keys(cfg: &Cfg) -> bool {
    !matches!(cfg.dup_policy, DuplicateKeyPolicy::PassThrough)
        || cfg.merge_keys == MergeKeyPolicy::Merge
}

/// Whether `V` is Serde's private visitor for buffering an arbitrary value as
/// `Content`, as used by `#[serde(untagged)]` and `#[serde(flatten)]`.
///
/// This intentionally does not match every visitor in Serde's private
/// deserialization module. In particular, internally tagged enums use
/// `TaggedContentVisitor`, whose input mapping must remain unchanged.
fn is_serde_content_buffer<V>() -> bool {
    let name = std::any::type_name::<V>();
    // Recent rustc versions include the visitor's unused lifetime as `<'_>`;
    // older versions omit it from `type_name`.
    let bare_name = name
        .split_once('<')
        .map_or(name, |(bare_name, _)| bare_name);
    name.contains("::private::de::") && bare_name.ends_with("::ContentVisitor")
}

/// The streaming Serde deserializer.
///
/// ## Important: this deserializer *borrows* and is only available in a closure
///
/// `YamlDeserializer` borrows from the YAML input processing state, so you generally
/// cannot construct and return it as a standalone value.
///
/// Instead, obtain it through the `with_deserializer_from_*` helpers, which provide a
/// [`crate::Deserializer`] (an alias for `YamlDeserializer`) **inside a closure**.
///
/// This is useful when you want to wrap the deserializer (for example, to collect
/// ignored fields or to add error context) while still deserializing into your target type.
///
/// ## Example
///
/// ```rust
/// use serde::Deserialize;
///
/// #[derive(Debug, Deserialize)]
/// struct Config {
///     host: String,
///     port: u16,
/// }
///
/// let yaml = "host: localhost\nport: 8080\n";
///
/// let cfg: Config = serde_saphyr::with_deserializer_from_str(yaml,
///     |de: serde_saphyr::Deserializer| {
///         Config::deserialize(de)
/// })?;
///
/// assert_eq!(cfg.port, 8080);
/// # Ok::<(), serde_saphyr::Error>(())
/// ```
///
/// This type is *stateless* with respect to ownership: it borrows the underlying input
/// state (`'e`) and forwards Serde requests into it, translating YAML shapes into Serde calls.
// Where do values come from: From an `Events` stream (typically [`LiveEvents`])
// that yields simplified YAML events.
// Where do values go: Into a Serde `Visitor` provided by the caller's
// `T: Deserialize`, which drives how we walk the event stream and construct `T`.
pub struct YamlDeserializer<'de, 'e> {
    pub(super) ev: &'e mut dyn Events<'de>,
    pub(super) cfg: Cfg,
    /// True when deserializing a map key.
    in_key: bool,
    /// True when Serde entered through `deserialize_struct`.
    ///
    /// Derived struct visitors reject repeated fields themselves, so `LastWins`
    /// needs duplicate fields collapsed before they reach Serde.
    struct_mode: bool,
    /// True when the recorded key node was exactly an empty mapping (`MapStart` followed by `MapEnd`).
    key_empty_map_node: bool,
    /// Comments that the parent mapping associated with this value.
    pub(super) pending_comments: Vec<Cow<'de, str>>,
    /// Same-line comments after the parent container separator (`key:` or `-`).
    pub(super) pending_value_separator_comments: Vec<Cow<'de, str>>,
    /// Comments that appeared above the value node itself.
    pub(super) pending_value_comments: Vec<Cow<'de, str>>,

    #[cfg(any(feature = "garde", feature = "validator"))]
    pub(super) garde: Option<&'e mut PathRecorder>,
}

#[derive(Clone)]
struct ScalarView<'de> {
    raw: Cow<'de, str>,
    effective: Cow<'de, str>,
    tag: SfTag,
    style: ScalarStyle,
    location: Location,
    interpolated: bool,
}

type EffectiveScalar<'de> = (Cow<'de, str>, SfTag, ScalarStyle, Location);

impl ScalarView<'_> {
    fn redaction_ctx(&self) -> Option<ScalarRedactionCtx> {
        self.interpolated.then(|| ScalarRedactionCtx {
            raw: self.raw.as_ref().to_owned(),
            effective: self.effective.as_ref().to_owned(),
        })
    }
}

fn with_scalar_redaction<T>(
    ctx: Option<ScalarRedactionCtx>,
    f: impl FnOnce() -> Result<T, Error>,
) -> Result<T, Error> {
    let _guard = ctx.map(ScalarRedactionGuard::new);
    f()
}

/// Runs one nested deserialize boundary inside its own subtree redaction scope while also
/// seeding that scope with the immediate scalar context when available.
///
/// Called from sequence/map seed boundaries and enum newtype payload accessors so any error
/// raised after child deserialization can still redact interpolated values seen within that
/// subtree.
fn with_subtree_redaction<T>(
    ctx: Option<ScalarRedactionCtx>,
    f: impl FnOnce() -> Result<T, Error>,
) -> Result<T, Error> {
    with_interp_redaction_scope(|| with_scalar_redaction(ctx, f))
}

#[cfg(feature = "properties")]
pub(crate) fn with_root_redaction<'de, 'e, T>(
    mut de: YamlDeserializer<'de, 'e>,
    f: impl FnOnce(YamlDeserializer<'de, 'e>) -> Result<T, Error>,
) -> Result<T, Error> {
    let redaction_ctx = de.peek_scalar_redaction_ctx()?;
    with_subtree_redaction(redaction_ctx, || f(de))
}

#[cfg(not(feature = "properties"))]
pub(crate) fn with_root_redaction<'de, 'e, T>(
    de: YamlDeserializer<'de, 'e>,
    f: impl FnOnce(YamlDeserializer<'de, 'e>) -> Result<T, Error>,
) -> Result<T, Error> {
    f(de)
}

/// Deserialize a document unless its root denotes a null document.
///
/// Share the root scalar view between null detection and redaction so probing a document
/// does not add an interpolation pass. Application tags must reach the target's dispatch.
#[cfg_attr(not(feature = "properties"), allow(unused_mut))]
pub(crate) fn with_root_redaction_unless_null<'de, 'e, T>(
    mut de: YamlDeserializer<'de, 'e>,
    f: impl FnOnce(YamlDeserializer<'de, 'e>) -> Result<T, Error>,
) -> Result<Option<T>, Error> {
    if let Some(Ev::Scalar {
        value, tag, style, ..
    }) = de.ev.peek()?
    {
        let keep_tagged = *tag == SfTag::Other;
        if !keep_tagged && scalar_is_null(tag, value, style) {
            let _ = de.ev.next()?;
            return Ok(None);
        }

        #[cfg(feature = "properties")]
        {
            let (tag, style) = (*tag, *style);
            if de.interpolation_possible(tag, style) {
                let Some(view) = de.peek_scalar_view()? else {
                    return Err(eof_with_loc(de.ev));
                };
                if !keep_tagged
                    && de.ev.property_interpolation().syntax()
                        == PropertySyntax::DockerComposeWithNulls
                    && view.tag == SfTag::Null
                {
                    let _ = de.ev.next()?;
                    return Ok(None);
                }
                return with_subtree_redaction(view.redaction_ctx(), || f(de)).map(Some);
            }
        }
    }

    with_root_redaction(de, f).map(Some)
}

struct EnumScalarId<'de> {
    raw: Cow<'de, str>,
    effective: Cow<'de, str>,
    interpolated: bool,
    location: Location,
}

impl<'de> EnumScalarId<'de> {
    fn from_view(view: ScalarView<'de>) -> Self {
        Self {
            raw: view.raw,
            effective: view.effective,
            interpolated: view.interpolated,
            location: view.location,
        }
    }

    fn redaction_ctx(&self) -> Option<ScalarRedactionCtx> {
        self.interpolated.then(|| ScalarRedactionCtx {
            raw: self.raw.as_ref().to_owned(),
            effective: self.effective.as_ref().to_owned(),
        })
    }
}

impl<'de> IntoDeserializer<'de, Error> for EnumScalarId<'de> {
    type Deserializer = Self;

    fn into_deserializer(self) -> Self::Deserializer {
        self
    }
}

impl<'de> de::Deserializer<'de> for EnumScalarId<'de> {
    type Error = Error;

    fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        self.deserialize_identifier(visitor)
    }

    fn deserialize_identifier<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        let ctx = self.redaction_ctx();
        let location = self.location;
        let effective = self.effective;
        with_scalar_redaction(ctx, move || match effective {
            Cow::Borrowed(value) => visitor.visit_borrowed_str(value),
            Cow::Owned(value) => visitor.visit_string(value),
        })
        .map_err(|err| err.with_location(location))
    }

    serde_core::forward_to_deserialize_any! {
        bool i8 i16 i32 i64 i128 u8 u16 u32 u64 u128 f32 f64 char str string bytes byte_buf
        option unit unit_struct newtype_struct seq tuple tuple_struct map struct enum
        ignored_any
    }
}

impl<'de, 'e> YamlDeserializer<'de, 'e> {
    /// Check whether an explicit tag is compatible with a scalar target.
    ///
    /// `tag` is the node's resolved tag, `expected` is the target's scalar tag,
    /// `ty` names the target in diagnostics, and `location` identifies the node.
    /// Returns an error for incompatible tags or disabled robotics conversions.
    fn validate_scalar_tag(
        &self,
        tag: SfTag,
        expected: SfTag,
        ty: &'static str,
        location: Location,
    ) -> Result<(), Error> {
        let compatible = tag == expected
            || match tag {
                SfTag::None
                | SfTag::Other
                | SfTag::Include
                | SfTag::Merge
                | SfTag::Value
                | SfTag::NonSpecific => true,
                tag if tag.is_robotics() => {
                    expected == SfTag::Float
                        && cfg!(feature = "robotics")
                        && self.cfg.angle_conversions
                }
                _ => false,
            };
        if compatible {
            Ok(())
        } else {
            Err(Error::InvalidScalar { ty, location })
        }
    }

    /// Construct a new streaming deserializer over an `Events` source.
    ///
    /// Arguments:
    /// - `ev`: the event source (e.g., `LiveEvents` or `ReplayEvents`).
    /// - `cfg`: small by-copy configuration affecting parsing policies.
    ///
    /// Returns:
    /// - `Deser` ready to be handed to Serde.
    ///
    /// Called by:
    /// - Top-level entry points and recursively for nested values.
    pub(crate) fn new(ev: &'e mut dyn Events<'de>, cfg: Cfg) -> Self {
        Self {
            ev,
            cfg,
            in_key: false,
            struct_mode: false,
            key_empty_map_node: false,
            pending_comments: Vec::new(),
            pending_value_separator_comments: Vec::new(),
            pending_value_comments: Vec::new(),

            #[cfg(any(feature = "garde", feature = "validator"))]
            garde: None,
        }
    }

    fn quoting_required_for_scalar(view: &ScalarView<'de>) -> Error {
        Error::quoting_required(view.raw.as_ref(), view.interpolated).with_location(view.location)
    }

    #[cfg(feature = "properties")]
    fn interpolation_possible(&self, tag: SfTag, style: ScalarStyle) -> bool {
        if self.in_key || tag == SfTag::Binary {
            return false;
        }

        let properties = self.ev.property_interpolation();
        if properties.property_map().is_none() {
            return false;
        }

        match properties.syntax() {
            syntax if syntax.is_docker_compose() => tag.can_parse_into_string(),
            _ => style == ScalarStyle::Plain,
        }
    }

    #[cfg(not(feature = "properties"))]
    fn interpolation_possible(&self, _tag: SfTag, _style: ScalarStyle) -> bool {
        false
    }

    #[cfg(feature = "properties")]
    fn peek_scalar_redaction_ctx(&mut self) -> Result<Option<ScalarRedactionCtx>, Error> {
        let Some((tag, style)) = (match self.ev.peek()? {
            Some(Ev::Scalar { tag, style, .. }) => Some((*tag, *style)),
            _ => None,
        }) else {
            return Ok(None);
        };

        if !self.interpolation_possible(tag, style) {
            return Ok(None);
        }

        Ok(self
            .peek_scalar_view()?
            .and_then(|view| view.redaction_ctx()))
    }

    #[cfg(not(feature = "properties"))]
    fn peek_scalar_redaction_ctx(&mut self) -> Result<Option<ScalarRedactionCtx>, Error> {
        Ok(None)
    }

    #[cfg(any(feature = "garde", feature = "validator"))]
    pub(crate) fn new_with_path_recorder(
        ev: &'e mut dyn Events<'de>,
        cfg: Cfg,
        garde: &'e mut PathRecorder,
    ) -> Self {
        Self {
            ev,
            cfg,
            in_key: false,
            struct_mode: false,
            key_empty_map_node: false,
            pending_comments: Vec::new(),
            pending_value_separator_comments: Vec::new(),
            pending_value_comments: Vec::new(),
            garde: Some(garde),
        }
    }

    /// Consume the next scalar event and return `(value, tag, location)`.
    ///
    /// Returns:
    /// - `Ok((String, Option<String>, Location))` on scalar,
    /// - `Err(Error)` otherwise.
    ///
    /// Called by:
    /// - Numeric/bool/char parsers and `take_string_scalar`.
    fn take_scalar_event(&mut self) -> Result<(String, SfTag, Location), Error> {
        let view = self.take_scalar_view()?;
        Ok((view.effective.into_owned(), view.tag, view.location))
    }

    /// Consume the next scalar event and return it without allocating a new `String` (if possible).
    ///
    /// This keeps the scalar text in its existing `Cow` container, which is cheap to clone
    /// and allows primitive parsers (bool/int/float/char) to work directly on `&str`.
    fn take_scalar_cow_event(&mut self) -> Result<(Cow<'de, str>, SfTag, Location), Error> {
        let view = self.take_scalar_view()?;
        Ok((view.effective, view.tag, view.location))
    }

    fn take_scalar_view(&mut self) -> Result<ScalarView<'de>, Error> {
        match self.ev.next()? {
            Some(Ev::Scalar {
                value,
                tag,
                style,
                location,
                ..
            }) => self.scalar_view_from_parts(value, tag, style, location),
            Some(other) => Err(Error::unexpected("string scalar").with_location(other.location())),
            None => Err(eof_with_loc(self.ev)),
        }
    }

    fn take_peeked_scalar_view(&mut self, view: ScalarView<'de>) -> Result<ScalarView<'de>, Error> {
        match self.ev.next()? {
            Some(Ev::Scalar { .. }) => Ok(view),
            Some(other) => Err(Error::unexpected("string scalar").with_location(other.location())),
            None => Err(eof_with_loc(self.ev)),
        }
    }

    /// Read a scalar as `String`, decoding `!!binary` into UTF-8 text if needed.
    ///
    /// Errors if the tag is incompatible with strings or if the binary payload
    /// is not valid UTF-8.
    fn take_string_scalar(&mut self) -> Result<String, Error> {
        let (value, tag, location) = self.take_scalar_event()?;

        // Special-case binary: decode base64 and require valid UTF-8.
        if tag == SfTag::Binary && !self.cfg.ignore_binary_tag_for_string {
            let data = decode_base64_yaml(&value).map_err(|err| err.with_location(location))?;
            let text = String::from_utf8(data).map_err(|_| Error::BinaryNotUtf8 { location })?;
            return Ok(text);
        }

        // For non-binary, ensure the tag allows string deserialization.
        if !(tag.can_parse_into_string()
            || self.cfg.ignore_binary_tag_for_string && tag == SfTag::Binary)
        {
            return Err(Error::TaggedScalarCannotDeserializeIntoString { location });
        }

        Ok(value)
    }

    /// Deliver a float to a typeless visitor, applying the configured non-finite policy.
    fn visit_typeless_float<V: Visitor<'de>>(
        &self,
        value: f64,
        raw: String,
        location: Location,
        visitor: V,
    ) -> Result<V::Value, Error> {
        if value.is_finite() {
            return visitor.visit_f64(value);
        }
        match self.cfg.non_finite_float_policy {
            NonFiniteFloatPolicy::PassThrough => visitor.visit_f64(value),
            // Cfg resolves the compatibility default; an unconfigured policy otherwise
            // has the same behavior as Reject.
            NonFiniteFloatPolicy::Default | NonFiniteFloatPolicy::Reject => {
                Err(Error::NonFiniteFloat {
                    value: raw,
                    location,
                })
            }
            NonFiniteFloatPolicy::AsString => {
                let canonical = if value.is_nan() {
                    ".nan"
                } else if value.is_sign_negative() {
                    "-.inf"
                } else {
                    ".inf"
                };
                visitor.visit_string(canonical.to_owned())
            }
        }
    }

    /// Expect a sequence start and consume it, or error otherwise.
    fn expect_seq_start(&mut self) -> Result<(), Error> {
        match self.ev.next()? {
            Some(Ev::SeqStart { .. }) => Ok(()),
            Some(other) => Err(Error::unexpected("sequence start").with_location(other.location())),
            None => Err(eof_with_loc(self.ev)),
        }
    }

    /// Expect a mapping start and consume it, or error otherwise.
    fn expect_map_start(&mut self) -> Result<(), Error> {
        match self.ev.next()? {
            Some(Ev::MapStart { .. }) => Ok(()),
            Some(other) => Err(Error::unexpected("mapping start").with_location(other.location())),
            None => Err(eof_with_loc(self.ev)),
        }
    }

    fn peek_effective_scalar(&mut self) -> Result<Option<EffectiveScalar<'de>>, Error> {
        let Some(view) = self.peek_scalar_view()? else {
            return Ok(None);
        };
        Ok(Some((view.effective, view.tag, view.style, view.location)))
    }

    /// Check for a null scalar without consuming it.
    ///
    /// Structural consumers historically inspect the raw event. Only the opt-in Compose
    /// null mode also resolves an eligible interpolation here; other modes keep that behavior.
    pub(super) fn peek_null_value(&mut self) -> Result<bool, Error> {
        match self.ev.peek()? {
            Some(Ev::Scalar {
                value, tag, style, ..
            }) => {
                if scalar_is_null(tag, value, style) {
                    return Ok(true);
                }

                #[cfg(feature = "properties")]
                {
                    let (tag, style) = (*tag, *style);
                    if self.ev.property_interpolation().syntax()
                        == PropertySyntax::DockerComposeWithNulls
                        && !tag.forces_string()
                        && self.interpolation_possible(tag, style)
                    {
                        return Ok(self
                            .peek_scalar_view()?
                            .is_some_and(|view| view.tag == SfTag::Null));
                    }
                }

                Ok(false)
            }
            _ => Ok(false),
        }
    }

    fn peek_scalar_view(&mut self) -> Result<Option<ScalarView<'de>>, Error> {
        let (value, tag, style, location) = match self.ev.peek()? {
            Some(Ev::Scalar {
                value,
                tag,
                style,
                location,
                ..
            }) => (value.clone(), *tag, *style, *location),
            _ => return Ok(None),
        };

        Ok(Some(
            self.scalar_view_from_parts(value, tag, style, location)?,
        ))
    }

    fn scalar_view_from_parts(
        &self,
        raw: Cow<'de, str>,
        tag: SfTag,
        style: ScalarStyle,
        location: Location,
    ) -> Result<ScalarView<'de>, Error> {
        let can_interpolate = self.interpolation_possible(tag, style);
        let effective = if can_interpolate {
            self.effective_scalar_value(raw.clone(), location)?
        } else {
            raw.clone()
        };
        let interpolated = can_interpolate && raw.as_ref() != effective.as_ref();
        #[cfg(feature = "properties")]
        let tag = if interpolated {
            self.compose_expansion_tag(&raw, &effective, tag)
        } else {
            tag
        };
        Ok(ScalarView {
            raw,
            effective,
            tag,
            style,
            location,
            interpolated,
        })
    }

    /// How an interpolated scalar is resolved under the Compose syntaxes.
    ///
    /// Compose parses YAML before interpolation. An expanded string stays a string even
    /// when its contents look like null, a boolean, or a number. The non-specific tag
    /// preserves this for generic visitors while still allowing explicitly requested
    /// numeric types to parse the result.
    ///
    /// [`PropertySyntax::DockerComposeWithNulls`] instead tags a value that should be null
    /// (see its docs) as `!!null`, so every target treats it exactly like a literal null.
    /// Explicit and string-forcing tags are left alone by both modes.
    #[cfg(feature = "properties")]
    fn compose_expansion_tag(&self, raw: &str, effective: &str, tag: SfTag) -> SfTag {
        let properties = self.ev.property_interpolation();
        let syntax = properties.syntax();
        if !syntax.is_docker_compose() || !tag.can_parse_into_string() || tag.forces_string() {
            return tag;
        }
        let becomes_null = syntax == PropertySyntax::DockerComposeWithNulls
            && (matches!(effective, "~" | "null" | "Null" | "NULL")
                || properties
                    .property_map()
                    .is_some_and(|vars| is_sole_unset_reference(raw, vars, syntax)));
        if becomes_null {
            SfTag::Null
        } else {
            SfTag::NonSpecific
        }
    }

    /// Expand properties after the caller has checked scalar interpolation eligibility.
    #[cfg(feature = "properties")]
    fn effective_scalar_value(
        &self,
        value: Cow<'de, str>,
        location: Location,
    ) -> Result<Cow<'de, str>, Error> {
        let properties = self.ev.property_interpolation();
        let Some(vars) = properties.property_map() else {
            return Ok(value);
        };
        let vars = vars.as_ref();
        let syntax = properties.syntax();

        match interpolate_compose_style_with_limits(
            value,
            vars,
            syntax,
            properties.max_expansion_depth(),
            properties.max_total_work(),
            properties.total_work(),
        ) {
            Ok(value) => Ok(value),
            Err(crate::properties::PropertyError::Unresolved(name)) => {
                Err(Error::UnresolvedProperty { name, location })
            }
            Err(crate::properties::PropertyError::InvalidName(name)) => {
                Err(Error::InvalidPropertyName { name, location })
            }
            Err(crate::properties::PropertyError::RequiredButUnset { name, message }) => {
                Err(Error::PropertyRequiredButUnset {
                    name,
                    message,
                    location,
                })
            }
            Err(crate::properties::PropertyError::RequiredButEmpty { name, message }) => {
                Err(Error::PropertyRequiredButEmpty {
                    name,
                    message,
                    location,
                })
            }
            Err(crate::properties::PropertyError::ExpansionDepthLimitExceeded {
                depth,
                max_depth,
            }) => {
                let breach = BudgetBreach::PropertyExpansionDepth { depth, max_depth };
                properties.record_breach(breach.clone());
                Err(budget_error(breach).with_location(location))
            }
            Err(crate::properties::PropertyError::ExpansionWorkLimitExceeded {
                work,
                max_work,
            }) => {
                let breach = BudgetBreach::PropertyInterpolationWork { work, max_work };
                properties.record_breach(breach.clone());
                Err(budget_error(breach).with_location(location))
            }
        }
    }

    #[cfg(not(feature = "properties"))]
    fn effective_scalar_value(
        &self,
        value: Cow<'de, str>,
        _location: Location,
    ) -> Result<Cow<'de, str>, Error> {
        Ok(value)
    }

    /// Peek at the next event's anchor id, if any (0 indicates no anchor).
    fn peek_anchor_id(&mut self) -> Result<Option<usize>, Error> {
        match self.ev.peek()? {
            Some(
                Ev::Scalar { anchor, .. }
                | Ev::SeqStart { anchor, .. }
                | Ev::MapStart { anchor, .. },
            ) => {
                if *anchor == 0 {
                    Ok(None)
                } else {
                    Ok(Some(*anchor))
                }
            }
            _ => Ok(None),
        }
    }
}

impl<'de> de::Deserializer<'de> for YamlDeserializer<'de, '_> {
    type Error = Error;

    /// Fallback entry point when the caller's type has no specific expectation.
    ///
    /// When does Serde call this?
    /// - When the caller (Serde) does not know the exact Rust type to deserialize yet and
    ///   wants the format to "do the best it can" from the data. This happens, for example,
    ///   inside some enum deserialization strategies, in erased/typeless positions (e.g. Value-like
    ///   seeds), or when visitor-based APIs defer the concrete type decision.
    /// - Even for structs/enums, Serde may call `deserialize_any` for individual field values
    ///   when the driving logic cannot or does not specify a concrete numeric/bool/char method.
    ///
    /// Can we force Serde to call the typed methods (`deserialize_u8`, `deserialize_bool`, ...)?
    /// - Not from within a format Deserializer. Serde chooses which method to call based on the
    ///   Rust type information it has via the caller’s `Deserialize`/`DeserializeSeed` logic.
    ///   Implementing the typed methods (which we do) ensures Serde will use them whenever it knows
    ///   the target type; otherwise, it falls back to `deserialize_any`.
    ///
    /// Can we learn the target field’s Rust type from here?
    /// - No. Serde does not expose type reflection to Deserializers. The only hint we get is which
    ///   method Serde chose to call. Field names are available in `deserialize_struct`, but not the
    ///   field types.
    ///
    /// Our policy:
    /// - Explicit core scalar tags and enabled robotics tags select the corresponding type
    ///   regardless of scalar style.
    ///   Plain, untagged scalars are inferred (null-like → bool → int → float) before falling
    ///   back to string. Quoted scalars without a core type tag remain strings, and !!binary
    ///   scalars are decoded as strings according to the configured binary-tag policy.
    ///
    /// Flow: We inspect the next event; scalars are parsed with the heuristic above; containers
    /// delegate to `deserialize_seq`/`deserialize_map`.
    fn deserialize_any<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        // Only Serde's generic Content buffer needs tagged nodes represented as
        // synthetic maps. General untyped visitors discard YAML tags, while other
        // private Serde visitors may attach their own meaning to the original map.
        if is_serde_content_buffer::<V>()
            && let Some(events) = capture_simple_tagged_node_as_map_events(self.ev)?
        {
            let mut replay = ReplayEvents::new(
                events,
                #[cfg(feature = "properties")]
                self.ev.property_interpolation().clone(),
            );
            return YamlDeserializer::new(&mut replay, self.cfg).deserialize_map(visitor);
        }

        if let Some((value, tag, style, location)) = self.peek_effective_scalar()? {
            // Explicit scalar types take precedence over implicit null and string inference,
            // including for quoted and block scalars buffered by Serde's flatten support.
            match tag {
                SfTag::Null => {
                    let _ = self.take_scalar_event()?;
                    return visitor.visit_unit();
                }
                SfTag::Bool => return self.deserialize_bool(visitor),
                SfTag::Int if yaml_trim(&value).starts_with('-') => {
                    return self.deserialize_i64(visitor);
                }
                SfTag::Int => return self.deserialize_u64(visitor),
                SfTag::Float | SfTag::Time | SfTag::Degrees | SfTag::Radians => {
                    self.validate_scalar_tag(tag, SfTag::Float, "floating point", location)?;
                    let view = self.take_scalar_view()?;
                    let value = try_parse_float_incl_overflow(
                        &view.effective,
                        view.location,
                        view.tag,
                        self.cfg.angle_conversions,
                    )
                    .ok_or(Error::InvalidScalar {
                        ty: "floating point",
                        location: view.location,
                    })?;
                    return self.visit_typeless_float(
                        value,
                        view.raw.into_owned(),
                        view.location,
                        visitor,
                    );
                }
                _ => {}
            }
            let is_plain = matches!(style, ScalarStyle::Plain);
            // String tags (!!str and !) preserve null-like text (null, ~, empty).
            if scalar_is_null(&tag, &value, &style) {
                let _ = self.ev.next()?; // consume
                return visitor.visit_unit();
            }
            if !is_plain
                || !tag.can_parse_into_string()
                || tag == SfTag::Binary
                || tag.forces_string()
            {
                // For string-ish scalars, rely on the parser's own zero-copy capability:
                // if the scalar is returned as `Cow::Borrowed`, we can pass it through.
                // Otherwise we fall back to owning.
                if tag == SfTag::Binary && !self.cfg.ignore_binary_tag_for_string {
                    return visitor.visit_string(self.take_string_scalar()?);
                }
                if !(tag.can_parse_into_string()
                    || self.cfg.ignore_binary_tag_for_string && tag == SfTag::Binary)
                {
                    return Err(Error::TaggedScalarCannotDeserializeIntoString { location });
                }

                let (cow, _tag2, _location) = self.take_scalar_cow_event()?;
                return match cow {
                    Cow::Borrowed(b) => visitor.visit_borrowed_str(b),
                    Cow::Owned(s) => visitor.visit_string(s),
                };
            }

            // Consume the scalar and attempt typed parses in order: bool -> int -> float.
            // Parse the effective value, but keep the raw source text for diagnostics.
            let view = self.take_scalar_view()?;
            let effective = view.effective;
            let location = view.location;

            // Try booleans.
            if self.cfg.strict_booleans {
                if let Some(b) = parse_yaml12_bool(&effective) {
                    return visitor.visit_bool(b);
                }
            } else if let Some(b) = parse_yaml11_bool(&effective) {
                return visitor.visit_bool(b);
            }

            let t = yaml_trim(&effective);
            // Preserve selected spellings before either numeric parser can consume
            // them. Explicit numeric tags have already dispatched above.
            if (self.cfg.leading_zero_numbers_as_strings && leading_zero_decimal(t))
                || (self.cfg.underscored_numbers_as_strings && t.contains('_'))
            {
                return match effective {
                    Cow::Borrowed(b) => visitor.visit_borrowed_str(b),
                    Cow::Owned(s) => visitor.visit_string(s),
                };
            }

            // Try integers: signed if leading '-', else unsigned, using 64-bit visitors.
            if t.starts_with('-') {
                if (!leading_zero_decimal(t) || self.cfg.legacy_octal_numbers)
                    && let Ok(v) =
                        parse_int_signed::<i64>(t, "i64", location, self.cfg.legacy_octal_numbers)
                {
                    return visitor.visit_i64(v);
                }
            } else {
                if let Ok(v) =
                    parse_int_unsigned::<u64>(t, "u64", location, self.cfg.legacy_octal_numbers)
                {
                    return visitor.visit_u64(v);
                }
            }

            // Try float per YAML 1.2 forms, treating an f64-overflowing literal (e.g.
            // `1e999`) as non-finite too, so both shapes are handled consistently below.
            if let Some(v) = try_parse_float_incl_overflow(
                &effective,
                location,
                view.tag,
                self.cfg.angle_conversions,
            ) {
                return self.visit_typeless_float(v, view.raw.into_owned(), location, visitor);
            }

            // Fallback: treat as string as-is, preserving zero-copy borrowing when the
            // parser handed us a slice of the original input.
            return match effective {
                Cow::Borrowed(b) => visitor.visit_borrowed_str(b),
                Cow::Owned(s) => visitor.visit_string(s),
            };
        }

        match self.ev.peek()? {
            Some(Ev::SeqStart { .. }) => self.deserialize_seq(visitor),
            Some(Ev::MapStart { .. }) => self.deserialize_map(visitor),
            Some(Ev::RecursiveAlias { location, .. }) => {
                Err(Error::RecursiveReferencesRequireWeakTypes {
                    location: *location,
                })
            }
            Some(Ev::SeqEnd { location }) => Err(Error::UnexpectedSequenceEnd {
                location: *location,
            }),
            Some(Ev::MapEnd { location }) => Err(Error::UnexpectedMappingEnd {
                location: *location,
            }),
            None => {
                // When deserializing typeless positions (for example
                // `serde_json::Value`) exhausted input is treated as null.
                visitor.visit_unit()
            }
            Some(Ev::Taken { location }) => {
                Err(Error::unexpected("consumed event").with_location(*location))
            }
            Some(Ev::Scalar { location, .. }) => {
                Err(Error::unexpected("scalar").with_location(*location))
            }
        }
    }

    /// Parse a boolean literal according to `strict_booleans`.
    ///
    /// Caller: Serde when target expects `bool`.
    /// Flow: scalar text → `Visitor::visit_bool`.
    fn deserialize_bool<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Bool, "boolean", location)?;
        let s = s.as_ref();
        let b: bool = if self.cfg.strict_booleans {
            parse_yaml12_bool(s).ok_or(Error::InvalidBooleanStrict { location })?
        } else {
            parse_yaml11_bool(s).ok_or(Error::InvalidScalar {
                ty: "boolean",
                location,
            })?
        };
        visitor.visit_bool(b)
    }

    /// Parse a signed 8-bit integer.
    fn deserialize_i8<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "i8", location)?;
        let v: i8 = parse_int_signed(s.as_ref(), "i8", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_i8(v)
    }
    /// Parse a signed 16-bit integer.
    fn deserialize_i16<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "i16", location)?;
        let v: i16 = parse_int_signed(s.as_ref(), "i16", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_i16(v)
    }
    /// Parse a signed 32-bit integer.
    fn deserialize_i32<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "i32", location)?;
        let v: i32 = parse_int_signed(s.as_ref(), "i32", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_i32(v)
    }
    /// Parse a signed 64-bit integer.
    fn deserialize_i64<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "i64", location)?;
        let v: i64 = parse_int_signed(s.as_ref(), "i64", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_i64(v)
    }
    /// Parse a signed 128-bit integer.
    fn deserialize_i128<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "i128", location)?;
        let v: i128 =
            parse_int_signed(s.as_ref(), "i128", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_i128(v)
    }

    /// Parse an unsigned 8-bit integer.
    fn deserialize_u8<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "u8", location)?;
        let v: u8 = parse_int_unsigned(s.as_ref(), "u8", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_u8(v)
    }
    /// Parse an unsigned 16-bit integer.
    fn deserialize_u16<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "u16", location)?;
        let v: u16 =
            parse_int_unsigned(s.as_ref(), "u16", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_u16(v)
    }
    /// Parse an unsigned 32-bit integer.
    fn deserialize_u32<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "u32", location)?;
        let v: u32 =
            parse_int_unsigned(s.as_ref(), "u32", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_u32(v)
    }
    /// Parse an unsigned 64-bit integer.
    fn deserialize_u64<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "u64", location)?;
        let v: u64 =
            parse_int_unsigned(s.as_ref(), "u64", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_u64(v)
    }
    /// Parse an unsigned 128-bit integer.
    fn deserialize_u128<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Int, "u128", location)?;
        let v: u128 =
            parse_int_unsigned(s.as_ref(), "u128", location, self.cfg.legacy_octal_numbers)?;
        visitor.visit_u128(v)
    }

    /// Parse a 32-bit float (supports YAML 1.2 `+.inf`, `-.inf`, `.nan`).
    fn deserialize_f32<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Float, "floating point", location)?;
        let v: f32 = parse_yaml12_float(s.as_ref(), location, tag, self.cfg.angle_conversions)?;
        visitor.visit_f32(v)
    }
    /// Parse a 64-bit float (supports YAML 1.2 `+.inf`, `-.inf`, `.nan`).
    fn deserialize_f64<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::Float, "floating point", location)?;
        let v: f64 = parse_yaml12_float(s.as_ref(), location, tag, self.cfg.angle_conversions)?;
        visitor.visit_f64(v)
    }

    /// Parse a single Unicode scalar value (`char`).
    ///
    /// Null semantics:
    /// - Tagged null or plain null-like scalars (empty, `~`, `null`, `Null`, or `NULL`) are not valid `char`.
    ///   Quoted forms are treated as normal strings and validated for length 1.
    /// - In `no_schema` mode, plain scalars that look like non-strings (numbers, bools, etc.)
    ///   must be quoted; this check uses scalar style to avoid flagging quoted scalars.
    fn deserialize_char<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        // Mirror deserialize_string pre-checks to leverage tag/style and maybe_not_string.
        if let Some(view) = self.peek_scalar_view()?
            && !view.tag.forces_string()
        {
            // Reject YAML null for char (allow quoted values like "null").
            if view.tag == SfTag::Null || scalar_is_nullish(&view.effective, &view.style) {
                let (_value, _tag, location) = self.take_scalar_event()?;
                return Err(Error::InvalidCharNull { location });
            } else if self.cfg.no_schema
                && maybe_not_string(&view.effective, &view.style, self.cfg.strict_booleans)
            {
                // Require quoting for ambiguous plain scalars in no_schema mode.
                let view = self.take_scalar_view()?;
                return Err(Self::quoting_required_for_scalar(&view));
            }
        }

        // Now consume the scalar and validate it contains exactly one Unicode scalar value.
        let (s, tag, location) = self.take_scalar_cow_event()?;
        self.validate_scalar_tag(tag, SfTag::String, "char", location)?;
        let mut it = s.as_ref().chars();
        match (it.next(), it.next()) {
            (Some(c), None) => visitor.visit_char(c),
            _ => Err(Error::InvalidCharNotSingleScalar { location }),
        }
    }

    /// Deserialize a borrowed string.
    ///
    /// When the scalar exists verbatim in the original input, this method uses
    /// `Visitor::visit_borrowed_str`.
    ///
    /// Borrowing is only possible for in-memory inputs (e.g. `from_str` / `from_slice`) and only
    /// when no transformation is required (no escape processing, folding, chomping/indent handling,
    /// or multi-line normalization).
    ///
    /// If borrowing is not possible, this method falls back to `Visitor::visit_string`.
    /// When the target type requires `&str`, that fallback produces a helpful error suggesting
    /// `String` or `Cow<str>`, with a [`TransformReason`] describing why borrowing was impossible.
    fn deserialize_str<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        let view = match self.peek_scalar_view()? {
            Some(view) => {
                // Check for null - not valid for string deserialization. A deliberately
                // substituted ${...} that resolved to "" stays a string, not null.
                if (view.tag == SfTag::Null
                    || (!view.interpolated && scalar_is_nullish(&view.effective, &view.style)))
                    && !view.tag.forces_string()
                {
                    let loc = view.location;
                    let _ = self.ev.next()?;
                    return Err(Error::NullIntoString { location: loc });
                } else if self.cfg.no_schema
                    && maybe_not_string(&view.effective, &view.style, self.cfg.strict_booleans)
                    && !view.tag.forces_string()
                {
                    let view = self.take_scalar_view()?;
                    return Err(Self::quoting_required_for_scalar(&view));
                }

                if view.tag == SfTag::Binary && !self.cfg.ignore_binary_tag_for_string {
                    let res: Result<V::Value, Self::Error> =
                        visitor.visit_string(self.take_string_scalar()?);
                    return match res {
                        Ok(v) => Ok(v),
                        Err(err) if err.to_string().contains("expected a borrowed string") => Err(
                            Error::cannot_borrow_transformed(TransformReason::ParserReturnedOwned)
                                .with_location(view.location),
                        ),
                        Err(err) => Err(err),
                    };
                }
                if !(view.tag.can_parse_into_string()
                    || self.cfg.ignore_binary_tag_for_string && view.tag == SfTag::Binary)
                {
                    return Err(Error::TaggedScalarCannotDeserializeIntoString {
                        location: view.location,
                    });
                }

                view
            }
            // Not a scalar: report what was found (or EOF), as `deserialize_string` does.
            None => {
                return Err(self
                    .take_scalar_view()
                    .err()
                    .unwrap_or_else(|| eof_with_loc(self.ev)));
            }
        };

        let location = view.location;
        let redaction_ctx = view.redaction_ctx();
        let cannot_borrow_reason = if view.interpolated {
            TransformReason::VariableInterpolation
        } else if self.ev.input_for_borrowing().is_none() {
            TransformReason::InputNotBorrowable
        } else {
            TransformReason::ParserReturnedOwned
        };

        let view = self.take_peeked_scalar_view(view)?;
        if let Cow::Borrowed(b) = view.effective {
            return visitor.visit_borrowed_str(b);
        }

        let res: Result<V::Value, Self::Error> = with_scalar_redaction(redaction_ctx, || {
            visitor.visit_string(view.effective.into_owned())
        });
        match res {
            Ok(v) => Ok(v),
            Err(err) => {
                let msg = err.to_string();
                if msg.contains("expected a borrowed string") {
                    return Err(Error::cannot_borrow_transformed(cannot_borrow_reason)
                        .with_location(location));
                }
                Err(err)
            }
        }
    }

    /// Deserialize an owned string (with `!!binary` UTF-8 support).
    ///
    /// Null semantics:
    /// - Tagged null or plain null-like scalars (empty, `~`, `null`, `Null`, or `NULL`) are not valid `String`.
    ///   Suggest using `Option<String>` for such YAML values.
    /// - Quoted "null" and quoted empty strings are treated as normal strings and allowed.
    ///
    /// **From/To:** scalar text (or base64-decoded bytes) → `Visitor::visit_string`.
    fn deserialize_string<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        // Reject YAML null when deserializing into String. Allow quoted forms.
        let view = if let Some(view) = self.peek_scalar_view()? {
            // If explicitly tagged as null, or plain null-like, this is not a valid String.
            // A ${...} that the user deliberately substituted to "" is a legitimate string.
            if (view.tag == SfTag::Null
                || (!view.interpolated && scalar_is_nullish(&view.effective, &view.style)))
                && !view.tag.forces_string()
            {
                // Consume the scalar to anchor the error at the correct location.
                let (_value, _tag, location) = self.take_scalar_event()?;
                return Err(Error::NullIntoString { location });
            } else if self.cfg.no_schema
                && maybe_not_string(&view.effective, &view.style, self.cfg.strict_booleans)
                && !view.tag.forces_string()
            {
                // Consume the scalar to anchor the error at the correct location.
                let view = self.take_scalar_view()?;
                return Err(Self::quoting_required_for_scalar(&view));
            }
            if view.tag == SfTag::Binary && !self.cfg.ignore_binary_tag_for_string {
                return visitor.visit_string(self.take_string_scalar()?);
            }
            if !(view.tag.can_parse_into_string()
                || self.cfg.ignore_binary_tag_for_string && view.tag == SfTag::Binary)
            {
                return Err(Error::TaggedScalarCannotDeserializeIntoString {
                    location: view.location,
                });
            }

            view
        } else {
            // Let take_string_scalar handle the error if it's not a scalar
            return visitor.visit_string(self.take_string_scalar()?);
        };

        let redaction_ctx = view.redaction_ctx();
        let view = self.take_peeked_scalar_view(view)?;
        match view.effective {
            Cow::Borrowed(b) => {
                with_scalar_redaction(redaction_ctx, || visitor.visit_borrowed_str(b))
            }
            Cow::Owned(s) => with_scalar_redaction(redaction_ctx, || visitor.visit_string(s)),
        }
    }

    /// Deserialize bytes either from `!!binary` or from a sequence of integers (0..=255).
    ///
    /// **From/To:**
    /// - Tagged scalar → base64-decoded `Vec<u8>` into `Visitor::visit_byte_buf`.
    /// - Sequence of integers → packed into `Vec<u8>` and visited.
    fn deserialize_bytes<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        if let Some((_value, tag, _style, location)) = self.peek_effective_scalar()? {
            if tag == SfTag::Binary {
                let (value, data_location) = match self.ev.next()? {
                    Some(Ev::Scalar {
                        value, location, ..
                    }) => (value, location),
                    Some(other) => {
                        return Err(
                            Error::unexpected("binary scalar").with_location(other.location())
                        );
                    }
                    None => return Err(eof_with_loc(self.ev)),
                };
                let data =
                    decode_base64_yaml(&value).map_err(|err| err.with_location(data_location))?;
                return visitor.visit_byte_buf(data);
            }
            return Err(Error::BytesNotSupportedMissingBinaryTag { location });
        }

        match self.ev.peek()? {
            // Untagged → expect a sequence of YAML integers (0..=255) and pack into bytes
            Some(Ev::SeqStart { .. }) => {
                self.expect_seq_start()?;
                let mut out = Vec::new();
                loop {
                    match self.ev.peek()? {
                        Some(Ev::SeqEnd { .. }) => {
                            let _ = self.ev.next()?; // consume end
                            break;
                        }
                        Some(_) => {
                            // Deserialize each element as u8 using our own Deser
                            let b: u8 = <u8 as serde_core::Deserialize>::deserialize(
                                YamlDeserializer::new(&mut *self.ev, self.cfg),
                            )?;
                            out.push(b);
                        }
                        None => return Err(eof_with_loc(self.ev)),
                    }
                }
                visitor.visit_byte_buf(out)
            }

            // Anything else is unexpected here
            Some(other) => Err(
                Error::unexpected("scalar (!!binary) or sequence of 0..=255")
                    .with_location(other.location()),
            ),
            None => Err(eof_with_loc(self.ev)),
        }
    }

    /// Deserialize owned bytes; same semantics as `deserialize_bytes`.
    fn deserialize_byte_buf<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, Self::Error> {
        self.deserialize_bytes(visitor)
    }

    /// Deserialize an `Option<T>`.
    ///
    /// **What is treated as `None`?** End-of-input, container end, an explicitly
    /// tagged null, or a plain empty / `~` / `null` scalar permitting implicit null resolution.
    /// Explicit non-null core, binary, timestamp, and robotics tags are passed to the inner
    /// value's deserializer.
    fn deserialize_option<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        // Only when Serde asks for Option<T> do we interpret YAML null-like scalars as None.
        // Special-case for map keys: treat an explicit empty key captured as an empty mapping node
        // as None when the target is Option<T>. This is scoped strictly to key position to avoid
        // conflating a literal empty mapping `{}` with null for non-Option targets.
        if self.in_key && self.key_empty_map_node {
            // Recorded key is an empty mapping: treat as None for Option<T> in key position
            match self.ev.next()? {
                Some(Ev::MapStart { .. }) => {}
                Some(other) => {
                    return Err(
                        Error::unexpected("empty mapping start").with_location(other.location())
                    );
                }
                None => return Err(eof_with_loc(self.ev)),
            }
            match self.ev.next()? {
                Some(Ev::MapEnd { .. }) => {}
                Some(other) => {
                    return Err(
                        Error::unexpected("empty mapping end").with_location(other.location())
                    );
                }
                None => return Err(eof_with_loc(self.ev)),
            }
            return visitor.visit_none();
        }

        if let Some((value, tag, style, _location)) = self.peek_effective_scalar()?
            && scalar_is_null(&tag, &value, &style)
        {
            let _ = self.ev.next()?; // consume the scalar
            return visitor.visit_none();
        }

        match self.ev.peek()? {
            // End of input or an immediate container end both represent a missing value.
            None | Some(Ev::MapEnd { .. } | Ev::SeqEnd { .. }) => visitor.visit_none(),

            // Otherwise there is a value → Some(...)
            Some(_) => visitor.visit_some(self),
        }
    }

    /// Deserialize the unit type `()`.
    ///
    /// **What is “unit” here?** Rust's `()` indicates “no value”. In Serde it
    /// commonly appears in unit structs/variants or fields intentionally
    /// ignored.  
    /// **Accepted YAML forms:** end-of-input, container end, or a null-like
    /// scalar in plain style (`""`, `~`, `null`).
    fn deserialize_unit<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        if let Some((value, tag, style, _location)) = self.peek_effective_scalar()?
            && scalar_is_null(&tag, &value, &style)
        {
            let _ = self.ev.next()?; // consume the scalar
            return visitor.visit_unit();
        }

        match self.ev.peek()? {
            // Treat absence or a container end where a value was expected as unit.
            None | Some(Ev::MapEnd { .. } | Ev::SeqEnd { .. }) => visitor.visit_unit(),
            // Anything else isn't a unit value
            Some(other) => Err(Error::UnexpectedValueForUnit {
                location: other.location(),
            }),
        }
    }

    /// Deserialize a unit struct.
    ///
    /// **Delegation:** Struct unit forms are handled by allowing an **empty mapping**
    /// (`{}`) as the YAML representation, or by deferring to the same null-like
    /// forms accepted by `deserialize_unit`.  
    /// `Visitor` origin: Serde generates a visitor when
    /// deserializing the target unit struct type (via `derive(Deserialize)` or a
    /// manual impl). That visitor expects us to call `Visitor::visit_unit`.
    fn deserialize_unit_struct<V: Visitor<'de>>(
        self,
        _name: &'static str,
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        match self.ev.peek()? {
            // Allow empty mapping `{}` as a unit struct
            Some(Ev::MapStart { .. }) => {
                let _ = self.ev.next()?; // consume MapStart
                match self.ev.peek()? {
                    Some(Ev::MapEnd { .. }) => {
                        let _ = self.ev.next()?; // consume MapEnd
                        visitor.visit_unit()
                    }
                    Some(other) => Err(Error::ExpectedEmptyMappingForUnitStruct {
                        location: other.location(),
                    }),
                    None => Err(eof_with_loc(self.ev)),
                }
            }
            // Otherwise, delegate to unit handling (null, ~, empty scalar, EOF, etc.)
            _ => self.deserialize_unit(visitor),
        }
    }

    /// Deserialize a newtype struct (`struct Wrapper(T);`) by delegating to its inner value.
    ///
    /// Why is this needed: Serde distinguishes *newtype structs* from their
    /// inner `T` so that attributes (like `#[serde(transparent)]`) and coherence
    /// rules are preserved. Even though YAML has no distinct “newtype” shape,
    /// Serde will invoke this method when the target is a newtype struct.  
    /// What do we do: Hand our own deserializer (`self`) to
    /// `Visitor::visit_newtype_struct`, which in turn will deserialize `T`
    /// using the same YAML event stream.
    fn deserialize_newtype_struct<V: Visitor<'de>>(
        mut self,
        n: &'static str,
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        match n {
            // Internal wrapper types use `__yaml_*` names (see `__yaml_rc_anchor`, etc.).
            "__yaml_spanned" => spanned_deser::deserialize_yaml_spanned(self, visitor),
            #[cfg(feature = "comments")]
            "__yaml_commented" => commented_deser::deserialize_yaml_commented(self, visitor),
            "__yaml_tagged" => tagged_deser::deserialize_yaml_tagged(self, visitor),
            "__yaml_rc_anchor" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::Rc, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_arc_anchor" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::Arc, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_rc_recursive" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::RcRecursive, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_arc_recursive" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::ArcRecursive, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_rc_weak_anchor" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::Rc, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_arc_weak_anchor" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::Arc, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_rc_recursion" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::RcRecursive, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            "__yaml_arc_recursion" => {
                let anchor = self.peek_anchor_id()?;
                anchor_store::with_anchor_context(AnchorKind::ArcRecursive, anchor, || {
                    visitor.visit_newtype_struct(self)
                })
            }
            _ => visitor.visit_newtype_struct(self),
        }
    }

    /// Deserialize a YAML sequence into a Serde sequence.
    ///
    /// Flow: We provide a `SeqAccess` that repeatedly feeds nested
    /// `Deser` instances back into Serde for each element. Also supports a
    /// `!!binary` scalar as a byte *sequence* view when the caller expects a
    /// sequence of u8.
    fn deserialize_seq<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        if self.ev.take_empty_stream()? {
            return visitor.visit_seq(de::value::SeqDeserializer::<_, Error>::new(
                std::iter::empty::<()>(),
            ));
        }
        if let Some((_, SfTag::Binary, _, _)) = self.peek_effective_scalar()? {
            let (scalar, data_location) = match self.ev.next()? {
                Some(Ev::Scalar {
                    value, location, ..
                }) => (value, location),
                Some(other) => {
                    return Err(Error::unexpected("binary scalar").with_location(other.location()));
                }
                None => return Err(eof_with_loc(self.ev)),
            };
            let data =
                decode_base64_yaml(&scalar).map_err(|err| err.with_location(data_location))?;
            /// `SeqAccess` that iterates over bytes from a decoded `!!binary`.
            struct ByteSeq {
                data: Vec<u8>,
                idx: usize,
            }
            impl<'de> de::SeqAccess<'de> for ByteSeq {
                type Error = Error;
                fn next_element_seed<T>(&mut self, seed: T) -> Result<Option<T::Value>, Error>
                where
                    T: de::DeserializeSeed<'de>,
                {
                    if self.idx >= self.data.len() {
                        return Ok(None);
                    }
                    let b = self.data[self.idx];
                    self.idx += 1;
                    let deser = serde_core::de::value::U8Deserializer::<Error>::new(b);
                    seed.deserialize(deser).map(Some)
                }
            }
            return visitor.visit_seq(ByteSeq { data, idx: 0 });
        }
        // Comments passed in from the parent value slot belong to the first item
        // of the sequence. If this sequence is reached through a nested alias,
        // alias replay exposes the anchored sequence start here, so the same
        // rule applies to comments written above the alias token.
        let mut seq_start_comments = std::mem::take(&mut self.pending_value_comments);
        seq_start_comments.extend(self.ev.take_leading_comments_for_next_node()?);
        let seq_location = match self.ev.peek()? {
            Some(ev) => ev.location(),
            None => self.ev.last_location(),
        };
        let child_cfg = self.cfg.enter_container(seq_location)?;
        self.expect_seq_start()?;
        /// Streaming `SeqAccess` over the underlying `Events`.
        struct SA<'de, 'e> {
            ev: &'e mut dyn Events<'de>,
            cfg: Cfg,
            pending_first_element_comments: Vec<Cow<'de, str>>,

            #[cfg(any(feature = "garde", feature = "validator"))]
            garde: Option<&'e mut PathRecorder>,
            #[cfg(any(feature = "garde", feature = "validator"))]
            idx: usize,
        }
        impl<'de> de::SeqAccess<'de> for SA<'de, '_> {
            type Error = Error;
            /// Produce the next element by recursively deserializing from the same event source.
            fn next_element_seed<T>(&mut self, seed: T) -> Result<Option<T::Value>, Error>
            where
                T: de::DeserializeSeed<'de>,
            {
                let (is_end, defined_location) = {
                    let peeked = self.ev.peek()?;
                    match peeked {
                        Some(Ev::SeqEnd { .. }) => (true, Location::UNKNOWN),
                        Some(ev) => (false, ev.location()),
                        None => return Err(eof_with_loc(self.ev)),
                    }
                };

                if is_end {
                    return Ok(None);
                }

                // The peek borrow is now released, so it's safe to query other cursor state.
                let reference_location = self.ev.reference_location();
                let alias_reference_location = self.ev.alias_reference_location();
                let _missing_field_guard = MissingFieldLocationGuard::new(reference_location);
                let mut item_comments = std::mem::take(&mut self.pending_first_element_comments);
                item_comments.extend(self.ev.take_leading_comments_for_next_node()?);
                let value_separator_comments = self
                    .ev
                    .take_separator_comments_before_sequence_item_value()?;

                #[cfg(any(feature = "garde", feature = "validator"))]
                {
                    if let Some(garde_ref) = self.garde.as_mut() {
                        let recorder: &mut PathRecorder = garde_ref;

                        let prev = recorder.current.take();
                        let now = prev.clone().join(self.idx);
                        recorder.current = now.clone();
                        recorder.map.insert(
                            now,
                            Locations {
                                reference_location,
                                defined_location,
                            },
                        );

                        let mut de =
                            YamlDeserializer::new_with_path_recorder(self.ev, self.cfg, recorder);
                        de.pending_comments = item_comments;
                        de.pending_value_separator_comments = value_separator_comments;
                        let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                        let res = with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
                            .map(Some)
                            .map_err(|e| {
                                attach_alias_locations_if_missing(
                                    e,
                                    alias_reference_location,
                                    defined_location,
                                )
                            });

                        recorder.current = prev;
                        self.idx += 1;
                        return res;
                    }
                }

                let mut de = YamlDeserializer::new(self.ev, self.cfg);
                de.pending_comments = item_comments;
                de.pending_value_separator_comments = value_separator_comments;
                let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
                    .map(Some)
                    .map_err(|e| {
                        attach_alias_locations_if_missing(
                            e,
                            alias_reference_location,
                            defined_location,
                        )
                    })
            }
        }

        #[cfg(any(feature = "garde", feature = "validator"))]
        let garde = self.garde;

        let result = visitor.visit_seq(SA {
            ev: self.ev,
            cfg: child_cfg,
            pending_first_element_comments: seq_start_comments,

            #[cfg(any(feature = "garde", feature = "validator"))]
            garde,
            #[cfg(any(feature = "garde", feature = "validator"))]
            idx: 0,
        })?;
        drain_remaining_sequence(self.ev)?;
        Ok(result)
    }

    /// Deserialize a tuple; identical mechanics to sequences (fixed length checked by caller).
    fn deserialize_tuple<V: Visitor<'de>>(
        self,
        len: usize,
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        self.deserialize_seq(TupleLenVisitor {
            inner: visitor,
            len,
        })
    }

    /// Deserialize a tuple struct; identical mechanics to sequences.
    fn deserialize_tuple_struct<V: Visitor<'de>>(
        self,
        _name: &'static str,
        len: usize,
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        self.deserialize_seq(TupleLenVisitor {
            inner: visitor,
            len,
        })
    }

    /// Deserialize a YAML mapping into a Serde map/struct field stream.
    ///
    /// Flow: We expose a `MapAccess` implementation (`MA`) that:
    /// - Captures key/value nodes (able to replay them),
    /// - Applies duplicate-key policy,
    /// - Expands YAML merge keys (`<<`) in the correct precedence order.
    ///
    /// Caller: Serde field visitors for maps and for Rust structs
    /// (which Serde also requests via `deserialize_map`).
    fn deserialize_map<V: Visitor<'de>>(mut self, visitor: V) -> Result<V::Value, Self::Error> {
        if self.ev.take_empty_stream()? {
            struct EmptyMap {
                location: Location,
            }
            impl<'de> de::MapAccess<'de> for EmptyMap {
                type Error = Error;

                fn next_key_seed<K>(&mut self, _seed: K) -> Result<Option<K::Value>, Error>
                where
                    K: de::DeserializeSeed<'de>,
                {
                    Ok(None)
                }

                fn next_value_seed<V>(&mut self, _seed: V) -> Result<V::Value, Error>
                where
                    V: de::DeserializeSeed<'de>,
                {
                    Err(Error::ValueRequestedBeforeKey {
                        location: self.location,
                    })
                }
            }
            return visitor.visit_map(EmptyMap {
                location: self.ev.last_location(),
            });
        }
        // Same-line separator comments on the parent field belong to this mapping node.
        // `Commented<Container>` consumes those comments before this point; a plain map
        // must not reattach them to the first child key.
        let _map_node_comments = std::mem::take(&mut self.pending_value_separator_comments);
        // Comments already inside the map, before the first key, remain first-key
        // comments. `Commented<Container>` defers these instead of capturing them.
        // If this map is reached through a nested alias, alias replay exposes the
        // anchored map start here; comments above the alias follow the same rule.
        let mut map_start_comments = std::mem::take(&mut self.pending_value_comments);
        map_start_comments.extend(self.ev.take_leading_comments_for_next_node()?);
        let map_location = match self.ev.peek()? {
            Some(ev) => ev.location(),
            None => self.ev.last_location(),
        };
        let map_reference_location = self.ev.reference_location();
        let child_cfg = self.cfg.enter_container(map_location)?;
        self.expect_map_start()?;

        // Ensure "missing field" errors (which have no natural span) get attributed to the
        // current container.
        let _missing_field_guard = MissingFieldLocationGuard::new(map_reference_location);

        #[cfg(any(feature = "garde", feature = "validator"))]
        if let Some(recorder) = self.garde.as_mut() {
            // Record the container itself, not just its leaf scalars, so that missing-field
            // errors can fall back to a parent structure.
            let path = recorder.current.clone();
            recorder.map.insert(
                path,
                Locations {
                    reference_location: map_reference_location,
                    defined_location: map_location,
                },
            );
        }

        fn collect_last_wins_entries<'de>(
            ev: &mut dyn Events<'de>,
            mut first_key_comments: Vec<Cow<'de, str>>,
            cfg: Cfg,
            mut first_key: Option<KeyNode<'de>>,
            prior_seen: &HashSet<KeyFingerprint<'de>>,
            mut merge_batches: VecDeque<Vec<PendingEntry<'de>>>,
        ) -> Result<VecDeque<PendingEntry<'de>>, Error> {
            with_deferred_recursive_aliases(ev, |ev| {
                let mut explicit_entries = Vec::new();

                loop {
                    let (key, field_comments) = if let Some(key) = first_key.take() {
                        (key, std::mem::take(&mut first_key_comments))
                    } else {
                        match ev.peek()? {
                            Some(Ev::MapEnd { .. }) => {
                                let _ = ev.next()?;
                                break;
                            }
                            Some(_) => {
                                let mut key_comments = std::mem::take(&mut first_key_comments);
                                key_comments.extend(ev.take_leading_comments_for_next_node()?);
                                let key =
                                    capture_node_with_legacy_octal(ev, cfg.legacy_octal_numbers)?;
                                (key, key_comments)
                            }
                            None => return Err(eof_with_loc(ev)),
                        }
                    };

                    if is_merge_key(&key) {
                        match cfg.merge_keys {
                            MergeKeyPolicy::Merge => {
                                let _ = ev.peek()?;
                                let merge_ref_loc = ev.reference_location();
                                let entries =
                                    pending_entries_from_live_events(ev, merge_ref_loc, cfg)?;
                                if !entries.is_empty() {
                                    merge_batches.push_back(entries);
                                }
                                continue;
                            }
                            MergeKeyPolicy::AsOrdinary => {}
                            MergeKeyPolicy::Error => {
                                return Err(Error::MergeKeyNotAllowed {
                                    location: key.location(),
                                });
                            }
                        }
                    }

                    if cfg.reject_tagged_field_names {
                        key.validate_field_name_tag()?;
                    }
                    let value_separator_comments =
                        ev.take_separator_comments_before_mapping_value()?;
                    let value_comments = ev.take_leading_comments_for_next_node()?;
                    // Comment hooks need not fill lookahead, so locate the value explicitly
                    // before recording its use site for replay.
                    let _ = ev.peek()?;
                    let reference_location = ev.reference_location();
                    let value = capture_node_with_legacy_octal(ev, cfg.legacy_octal_numbers)?;
                    explicit_entries.push(PendingEntry {
                        key,
                        value,
                        reference_location,
                        field_comments,
                        value_separator_comments,
                        value_comments,
                    });
                }

                let mut explicit_entries = apply_duplicate_key_policy_to_entries(
                    explicit_entries,
                    cfg.dup_policy,
                    cfg.merge_keys,
                )?;
                let mut seen = prior_seen.clone();
                seen.reserve(explicit_entries.len());
                for entry in &explicit_entries {
                    seen.insert(entry.key.fingerprint().into_owned());
                }

                let mut merge_entries = Vec::new();
                for batch in merge_batches {
                    for entry in batch {
                        let fingerprint = entry.key.fingerprint().into_owned();
                        if seen.insert(fingerprint) {
                            merge_entries.push(entry);
                        }
                    }
                }

                explicit_entries.extend(merge_entries);
                Ok(explicit_entries.into_iter().collect())
            })
        }

        /// Streaming `MapAccess` over the underlying `Events`.
        struct MA<'de, 'e> {
            ev: &'e mut dyn Events<'de>,
            cfg: Cfg,
            struct_mode: bool,
            have_key: bool,

            // Persist a best-effort “current location” across `next_key_seed` returning to Serde.
            // This allows Serde-produced structural/type errors (e.g. `unknown_field`) to carry
            // a useful span even though they are raised outside of this deserializer’s call stack.
            fallback_guard: Option<MissingFieldLocationGuard>,

            #[cfg(any(feature = "garde", feature = "validator"))]
            garde: Option<&'e mut PathRecorder>,
            #[cfg(any(feature = "garde", feature = "validator"))]
            pending_path_segment: Option<String>,

            // For duplicate-key detection for arbitrary keys.
            seen: HashSet<KeyFingerprint<'de>>,
            pending: VecDeque<PendingEntry<'de>>,
            merge_stack: VecDeque<Vec<PendingEntry<'de>>>,
            flushing_merges: bool,
            live_done: bool,
            pending_value: Option<Box<(RecordedEvents<'de>, Location)>>,
            pending_field_comments: Vec<Cow<'de, str>>,
            pending_value_separator_comments: Vec<Cow<'de, str>>,
            pending_value_comments: Vec<Cow<'de, str>>,
            pending_first_key_comments: Vec<Cow<'de, str>>,
        }

        impl<'de> MA<'de, '_> {
            /// Skip exactly one YAML node (scalar/sequence/mapping) in the live stream.
            ///
            /// Used by:
            /// - `DuplicateKeyPolicy::FirstWins` to discard a later value.
            fn skip_one_node(&mut self) -> Result<(), Error> {
                if self.cfg.merge_keys == MergeKeyPolicy::Error {
                    let node =
                        capture_node_with_legacy_octal(self.ev, self.cfg.legacy_octal_numbers)?;
                    return validate_no_merge_keys_in_node_events(node.events());
                }

                let mut depth; // assigned later
                match self.ev.next()? {
                    Some(Ev::RecursiveAlias { location, .. }) => {
                        return Err(Error::RecursiveReferencesRequireWeakTypes { location });
                    }
                    Some(Ev::Scalar { .. }) => return Ok(()),
                    Some(Ev::SeqStart { .. } | Ev::MapStart { .. }) => depth = 1,
                    Some(Ev::SeqEnd { location } | Ev::MapEnd { location }) => {
                        return Err(Error::UnexpectedContainerEndWhileSkippingNode { location });
                    }
                    Some(Ev::Taken { location }) => {
                        return Err(Error::unexpected("consumed event").with_location(location));
                    }
                    None => return Err(eof_with_loc(self.ev)),
                }
                while depth != 0 {
                    match self.ev.next()? {
                        Some(Ev::RecursiveAlias { location, .. }) => {
                            return Err(Error::RecursiveReferencesRequireWeakTypes { location });
                        }
                        Some(Ev::SeqStart { .. } | Ev::MapStart { .. }) => depth += 1,
                        Some(Ev::SeqEnd { .. } | Ev::MapEnd { .. }) => depth -= 1,
                        Some(Ev::Scalar { .. }) => {}
                        Some(Ev::Taken { location }) => {
                            return Err(Error::unexpected("consumed event").with_location(location));
                        }
                        None => return Err(eof_with_loc(self.ev)),
                    }
                }
                Ok(())
            }

            fn validate_skipped_node(&self, node: &KeyNode<'_>) -> Result<(), Error> {
                if self.cfg.merge_keys == MergeKeyPolicy::Error {
                    validate_no_merge_keys_in_node_events(node.events())?;
                }
                Ok(())
            }

            /// Deserialize a recorded key using a temporary `ReplayEvents`.
            ///
            /// Arguments:
            /// - `seed`: Serde seed for the key type.
            /// - `events`: recorded node events for the key.
            fn deserialize_recorded_key<'de2, K>(
                &mut self,
                seed: K,
                events: RecordedEvents<'de2>,
                kemn: bool,
            ) -> Result<K::Value, Error>
            where
                K: de::DeserializeSeed<'de2>,
            {
                let mut replay = ReplayEvents::new(
                    events,
                    #[cfg(feature = "properties")]
                    self.ev.property_interpolation().for_key(),
                );

                // Get location from replay events for error reporting.
                let location = replay.reference_location();

                let de = YamlDeserializer::<'de2, '_> {
                    ev: &mut replay,
                    cfg: self.cfg,
                    in_key: true,
                    struct_mode: false,
                    key_empty_map_node: kemn,
                    pending_comments: Vec::new(),
                    pending_value_separator_comments: Vec::new(),
                    pending_value_comments: Vec::new(),

                    #[cfg(any(feature = "garde", feature = "validator"))]
                    garde: None,
                };
                seed.deserialize(de).map_err(|e| {
                    if e.location().is_none() {
                        e.with_location(location)
                    } else {
                        e
                    }
                })
            }

            /// Push a batch of entries to the front of the pending queue in order.
            fn enqueue_entries(&mut self, entries: Vec<PendingEntry<'de>>) {
                self.pending.reserve(entries.len());
                for entry in entries.into_iter().rev() {
                    self.pending.push_front(entry);
                }
            }

            /// Pop the next merge batch and enqueue its entries; return whether anything was queued.
            fn enqueue_next_merge_batch(&mut self) -> bool {
                while let Some(entries) = self.merge_stack.pop_front() {
                    if entries.is_empty() {
                        continue;
                    }
                    self.enqueue_entries(entries);
                    return true;
                }
                false
            }

            /// Consume this mapping's end if its visitor returned without asking for it.
            ///
            /// typetag's externally tagged visitor reads its one key/value pair
            /// and returns without polling `next_key` again. Poll once on the visitor's behalf so
            /// the closing event is consumed, while still rejecting an unexpected extra entry.
            fn finish(&mut self) -> Result<(), Error> {
                if self.have_key {
                    return Err(
                        Error::unexpected("mapping end").with_location(self.ev.last_location())
                    );
                }

                if de::MapAccess::next_key::<de::IgnoredAny>(self)?.is_some() {
                    return Err(
                        Error::unexpected("mapping end").with_location(self.ev.last_location())
                    );
                }

                Ok(())
            }
        }

        impl<'de> de::MapAccess<'de> for MA<'de, '_> {
            type Error = Error;

            /// Produce the next key for the visitor, honoring duplicate policy and merges.
            fn next_key_seed<K>(&mut self, seed: K) -> Result<Option<K::Value>, Error>
            where
                K: de::DeserializeSeed<'de>,
            {
                let mut seed = Some(seed);

                loop {
                    if let Some(entry) = self.pending.pop_front() {
                        let PendingEntry {
                            mut key,
                            mut value,
                            reference_location,
                            field_comments,
                            value_separator_comments,
                            value_comments,
                        } = entry;
                        let fingerprint = key.take_fingerprint();
                        let location = key.location();

                        let is_duplicate = self.seen.contains(&fingerprint);
                        if self.flushing_merges {
                            if is_duplicate {
                                self.validate_skipped_node(&value)?;
                                continue;
                            }
                        } else {
                            match self.cfg.dup_policy {
                                DuplicateKeyPolicy::Error => {
                                    if is_duplicate {
                                        let key = key.stringy_scalar_value().map(|s| s.to_owned());
                                        return Err(Error::DuplicateMappingKey { key, location });
                                    }
                                }
                                DuplicateKeyPolicy::FirstWins => {
                                    if is_duplicate {
                                        self.validate_skipped_node(&value)?;
                                        continue;
                                    }
                                }
                                DuplicateKeyPolicy::LastWins | DuplicateKeyPolicy::PassThrough => {}
                            }
                        }

                        #[cfg(any(feature = "garde", feature = "validator"))]
                        let key_path_segment = key.stringy_scalar_value().map(ToOwned::to_owned);
                        let events = key.take_events();
                        let value_events = value.take_events();
                        let kemn = is_empty_mapping_key_fingerprint(&fingerprint);
                        let Some(key_seed) = seed.take() else {
                            return Err(Error::InternalSeedReusedForMapKey { location });
                        };

                        // Set the fallback location to the key span *before* deserializing the key.
                        // Serde can raise `unknown_field` (and similar structural errors) during key
                        // deserialization itself; if we set the guard only after deserialization,
                        // those errors will incorrectly fall back to the container start.
                        match &mut self.fallback_guard {
                            Some(guard) => guard.replace_location(location),
                            None => {
                                self.fallback_guard =
                                    Some(MissingFieldLocationGuard::new(location));
                            }
                        }

                        let key_value = self.deserialize_recorded_key(key_seed, events, kemn)?;
                        self.have_key = true;
                        self.pending_field_comments = field_comments;
                        self.pending_value_separator_comments = value_separator_comments;
                        self.pending_value_comments = value_comments;
                        self.pending_value = Some(Box::new((value_events, reference_location)));

                        #[cfg(any(feature = "garde", feature = "validator"))]
                        {
                            self.pending_path_segment = key_path_segment;
                        }

                        if remembers_seen_keys(&self.cfg) {
                            self.seen.insert(fingerprint);
                        }
                        return Ok(Some(key_value));
                    }

                    if self.live_done {
                        return Ok(None);
                    }

                    if self.flushing_merges {
                        if self.enqueue_next_merge_batch() {
                            continue;
                        }
                        self.flushing_merges = false;
                        self.live_done = true;
                        return Ok(None);
                    }

                    match self.ev.peek()? {
                        Some(Ev::MapEnd { .. }) => {
                            let _ = self.ev.next()?; // consume end
                            if self.merge_stack.is_empty() {
                                self.live_done = true;
                                return Ok(None);
                            }
                            self.flushing_merges = true;
                            if self.enqueue_next_merge_batch() {
                                continue;
                            }
                            self.flushing_merges = false;
                            self.live_done = true;
                            return Ok(None);
                        }
                        Some(_) => {
                            let mut key_comments =
                                std::mem::take(&mut self.pending_first_key_comments);
                            key_comments.extend(self.ev.take_leading_comments_for_next_node()?);
                            let mut key_node = capture_node_with_legacy_octal(
                                self.ev,
                                self.cfg.legacy_octal_numbers,
                            )?;
                            if is_merge_key(&key_node) {
                                match self.cfg.merge_keys {
                                    MergeKeyPolicy::Merge => {
                                        // Preserve where the merge value is *referenced* (use-site).
                                        // For alias merges (`<<: *m`), `key_node`/`value_node`
                                        // locations will point at the anchored mapping, but we want
                                        // `referenced` to point at the alias token.
                                        let _ = self.ev.peek()?;
                                        let merge_ref_loc = self.ev.reference_location();
                                        let entries = pending_entries_from_live_events(
                                            self.ev,
                                            merge_ref_loc,
                                            Cfg {
                                                reject_tagged_field_names: self.struct_mode
                                                    && self.cfg.reject_tagged_field_names,
                                                ..self.cfg
                                            },
                                        )?;
                                        if !entries.is_empty() {
                                            self.merge_stack.push_back(entries);
                                        }
                                        continue;
                                    }
                                    MergeKeyPolicy::AsOrdinary => {}
                                    MergeKeyPolicy::Error => {
                                        return Err(Error::MergeKeyNotAllowed {
                                            location: key_node.location(),
                                        });
                                    }
                                }
                            }

                            if self.struct_mode && self.cfg.reject_tagged_field_names {
                                key_node.validate_field_name_tag()?;
                            }

                            if matches!(self.cfg.dup_policy, DuplicateKeyPolicy::LastWins)
                                && key_node.fingerprint().contains_integer()
                            {
                                // Integer identity can differ from the key's spelling in the
                                // target map, so select the winning YAML entries before Serde.
                                self.pending = collect_last_wins_entries(
                                    self.ev,
                                    key_comments,
                                    Cfg {
                                        reject_tagged_field_names: self.struct_mode
                                            && self.cfg.reject_tagged_field_names,
                                        ..self.cfg
                                    },
                                    Some(key_node),
                                    &self.seen,
                                    std::mem::take(&mut self.merge_stack),
                                )?;
                                self.live_done = true;
                                continue;
                            }

                            let fingerprint = key_node.fingerprint();
                            let is_duplicate = self.seen.contains(&fingerprint);
                            match self.cfg.dup_policy {
                                DuplicateKeyPolicy::Error => {
                                    if is_duplicate {
                                        let location = key_node.location();
                                        let key =
                                            key_node.stringy_scalar_value().map(|s| s.to_owned());
                                        return Err(Error::DuplicateMappingKey { key, location });
                                    }
                                }
                                DuplicateKeyPolicy::FirstWins => {
                                    if is_duplicate {
                                        self.skip_one_node()?;
                                        continue;
                                    }
                                }
                                DuplicateKeyPolicy::LastWins | DuplicateKeyPolicy::PassThrough => {}
                            }

                            let kemn_direct =
                                is_empty_mapping_key_fingerprint(fingerprint.as_ref());
                            // Deserialize the key from recorded events and read the value live.
                            let fingerprint =
                                remembers_seen_keys(&self.cfg).then(|| fingerprint.into_owned());
                            let location = key_node.location();
                            #[cfg(any(feature = "garde", feature = "validator"))]
                            let key_path_segment =
                                key_node.stringy_scalar_value().map(ToOwned::to_owned);
                            let events = key_node.take_events();
                            let Some(key_seed) = seed.take() else {
                                return Err(Error::InternalSeedReusedForMapKey { location });
                            };

                            // Same reasoning as the buffered path above: set key-span fallback
                            // before key deserialization so errors during key parsing are
                            // attributed to this key.
                            match &mut self.fallback_guard {
                                Some(guard) => guard.replace_location(location),
                                None => {
                                    self.fallback_guard =
                                        Some(MissingFieldLocationGuard::new(location));
                                }
                            }

                            let key_value =
                                self.deserialize_recorded_key(key_seed, events, kemn_direct)?;
                            self.have_key = true;
                            self.pending_field_comments = key_comments;
                            self.pending_value = None; // value will be read live

                            #[cfg(any(feature = "garde", feature = "validator"))]
                            {
                                self.pending_path_segment = key_path_segment;
                            }

                            if let Some(fingerprint) = fingerprint {
                                self.seen.insert(fingerprint);
                            }
                            return Ok(Some(key_value));
                        }
                        None => return Err(eof_with_loc(self.ev)),
                    }
                }
            }

            /// Provide the value corresponding to the most recently yielded key.
            fn next_value_seed<Vv>(&mut self, seed: Vv) -> Result<Vv::Value, Error>
            where
                Vv: de::DeserializeSeed<'de>,
            {
                if !self.have_key {
                    return Err(Error::ValueRequestedBeforeKey {
                        location: self.ev.last_location(),
                    });
                }
                self.have_key = false;

                #[cfg(any(feature = "garde", feature = "validator"))]
                let pending_segment = self.pending_path_segment.take();

                let field_comments = std::mem::take(&mut self.pending_field_comments);
                let mut value_separator_comments =
                    std::mem::take(&mut self.pending_value_separator_comments);
                let mut value_comments = std::mem::take(&mut self.pending_value_comments);

                if let Some(events) = self.pending_value.take() {
                    let (events, fallback_reference_location) = *events;
                    // Each captured node retains its own origin. Fixing the reference to
                    // the outer value would mistake ordinary descendants for aliases.
                    let mut replay = ReplayEvents::new(
                        events,
                        #[cfg(feature = "properties")]
                        self.ev.property_interpolation().clone(),
                    );

                    // Definition-site location: where the node is defined in the YAML.
                    // For aliases, this will point at the anchor definition.
                    let defined_location = match replay.peek()? {
                        Some(ev) => ev.location(),
                        None => replay.last_location(),
                    };
                    let alias_reference_location = replay.alias_reference_location();
                    #[cfg(any(feature = "garde", feature = "validator"))]
                    let reference_location = if defined_location == Location::UNKNOWN {
                        fallback_reference_location
                    } else {
                        replay.reference_location()
                    };
                    #[cfg(not(any(feature = "garde", feature = "validator")))]
                    let _ = fallback_reference_location;

                    #[cfg(any(feature = "garde", feature = "validator"))]
                    {
                        if let (Some(seg), Some(garde_ref)) = (pending_segment, self.garde.as_mut())
                        {
                            let recorder: &mut PathRecorder = garde_ref;

                            let prev = recorder.current.take();
                            let now = prev.clone().join(seg.as_str());
                            recorder.current = now.clone();
                            recorder.map.insert(
                                now,
                                Locations {
                                    reference_location,
                                    defined_location,
                                },
                            );

                            let mut de = YamlDeserializer::new_with_path_recorder(
                                &mut replay,
                                self.cfg,
                                recorder,
                            );
                            de.pending_comments = field_comments;
                            de.pending_value_separator_comments = value_separator_comments;
                            de.pending_value_comments = value_comments;
                            let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                            let res =
                                with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
                                    .map_err(|e| {
                                        attach_alias_locations_if_missing(
                                            e,
                                            alias_reference_location,
                                            defined_location,
                                        )
                                    });
                            recorder.current = prev;
                            return res;
                        }
                    }

                    let mut de = YamlDeserializer::new(&mut replay, self.cfg);
                    de.pending_comments = field_comments;
                    de.pending_value_separator_comments = value_separator_comments;
                    de.pending_value_comments = value_comments;
                    let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                    with_subtree_redaction(redaction_ctx, || seed.deserialize(de)).map_err(|e| {
                        attach_alias_locations_if_missing(
                            e,
                            alias_reference_location,
                            defined_location,
                        )
                    })
                } else {
                    value_separator_comments
                        .extend(self.ev.take_separator_comments_before_mapping_value()?);
                    value_comments.extend(self.ev.take_leading_comments_for_next_node()?);

                    // Live stream: get both locations for potential alias error reporting.
                    let defined_location = match self.ev.peek()? {
                        Some(ev) => ev.location(),
                        None => self.ev.last_location(),
                    };

                    #[cfg(any(feature = "garde", feature = "validator"))]
                    let reference_location = self.ev.reference_location();
                    let alias_reference_location = self.ev.alias_reference_location();

                    #[cfg(any(feature = "garde", feature = "validator"))]
                    {
                        if let (Some(seg), Some(garde_ref)) = (pending_segment, self.garde.as_mut())
                        {
                            let recorder: &mut PathRecorder = garde_ref;
                            let prev = recorder.current.take();
                            let now = prev.clone().join(seg.as_str());
                            recorder.current = now.clone();
                            recorder.map.insert(
                                now,
                                Locations {
                                    reference_location,
                                    defined_location,
                                },
                            );

                            let mut de = YamlDeserializer::new_with_path_recorder(
                                self.ev, self.cfg, recorder,
                            );
                            de.pending_comments = field_comments;
                            de.pending_value_separator_comments = value_separator_comments;
                            de.pending_value_comments = value_comments;
                            let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                            let res =
                                with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
                                    .map_err(|e| {
                                        attach_alias_locations_if_missing(
                                            e,
                                            alias_reference_location,
                                            defined_location,
                                        )
                                    });
                            recorder.current = prev;
                            return res;
                        }
                    }

                    let mut de = YamlDeserializer::new(self.ev, self.cfg);
                    de.pending_comments = field_comments;
                    de.pending_value_separator_comments = value_separator_comments;
                    de.pending_value_comments = value_comments;
                    let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                    with_scalar_redaction(redaction_ctx, || seed.deserialize(de)).map_err(|e| {
                        attach_alias_locations_if_missing(
                            e,
                            alias_reference_location,
                            defined_location,
                        )
                    })
                }
            }
        }

        let (pending, pending_first_key_comments, live_done) =
            if self.struct_mode && matches!(self.cfg.dup_policy, DuplicateKeyPolicy::LastWins) {
                (
                    collect_last_wins_entries(
                        self.ev,
                        map_start_comments,
                        self.cfg,
                        None,
                        &HashSet::new(),
                        VecDeque::new(),
                    )?,
                    Vec::new(),
                    true,
                )
            } else {
                (VecDeque::new(), map_start_comments, false)
            };

        #[cfg(any(feature = "garde", feature = "validator"))]
        let garde = self.garde;

        let mut access = MA {
            ev: self.ev,
            cfg: child_cfg,
            struct_mode: self.struct_mode,
            have_key: false,

            fallback_guard: None,

            #[cfg(any(feature = "garde", feature = "validator"))]
            garde,
            #[cfg(any(feature = "garde", feature = "validator"))]
            pending_path_segment: None,

            seen: if remembers_seen_keys(&child_cfg) {
                HashSet::with_capacity(8)
            } else {
                HashSet::new()
            },
            pending,
            merge_stack: VecDeque::new(),
            flushing_merges: false,
            live_done,
            pending_value: None,
            pending_field_comments: Vec::new(),
            pending_value_separator_comments: Vec::new(),
            pending_value_comments: Vec::new(),
            pending_first_key_comments,
        };
        let result = visitor.visit_map(&mut access)?;
        access.finish()?;
        Ok(result)
    }

    /// **Delegates struct deserialization** to the same machinery as mappings.
    ///
    /// `Visitor` origin: From Serde for the caller’s
    /// Rust struct type (usually generated by `#[derive(Deserialize)]`). That
    /// visitor expects a `MapAccess` yielding field names/values.  
    /// **Where does it go?** We call `visitor.visit_map(..)` via `deserialize_map`,
    /// which streams YAML mapping pairs as struct fields.
    fn deserialize_struct<V: Visitor<'de>>(
        self,
        _name: &'static str,
        _fields: &'static [&'static str],
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        let mut de = self;
        de.struct_mode = true;
        de.deserialize_map(visitor)
    }

    /// Deserialize an externally-tagged enum in either `Variant` or `{ Variant: value }` form.
    ///
    /// `Visitor` origin: From Serde for the target enum type.
    /// Flow: We surface an `EnumAccess` (`EA`) that provides the variant
    /// name, and a `VariantAccess` (`VA`) that reads the payload (unit/newtype/tuple/struct).
    fn deserialize_enum<V: Visitor<'de>>(
        mut self,
        name: &'static str,
        variants: &'static [&'static str],
        visitor: V,
    ) -> Result<V::Value, Self::Error> {
        enum Mode<'de, 'a> {
            Unit(EnumScalarId<'de>),
            Map(String, Location),
            /// Tag selects the variant, scalar value is the newtype payload.
            TaggedNewtype(EnumScalarId<'de>, RecordedEvents<'a>),
        }

        let mut tagged_enum = None;

        let peeked_ev = self.ev.peek()?.cloned();
        let mode = match peeked_ev {
            Some(Ev::RecursiveAlias { location, .. }) => {
                return Err(Error::RecursiveReferencesRequireWeakTypes { location });
            }
            Some(Ev::Scalar {
                tag,
                style,
                value: _,
                raw_tag,
                location,
                ..
            }) => {
                if let Some(tag_name) = simple_tagged_enum_name(&raw_tag, &tag) {
                    tagged_enum = Some((tag_name, location));
                }
                // A matching application tag selects the variant. Resolve and validate the
                // scalar as its payload, which may be null or a non-string in no_schema mode.
                if let Some((ref tag_name, tag_loc)) = tagged_enum
                    && variants.contains(&tag_name.as_str())
                {
                    let variant_name = EnumScalarId {
                        raw: Cow::Owned(tag_name.clone()),
                        effective: Cow::Owned(tag_name.clone()),
                        interpolated: false,
                        location: tag_loc,
                    };
                    // Consume the scalar and re-emit it without the tag for payload deserialization.
                    let origin = self.ev.node_origin();
                    let Some(mut ev) = self.ev.next()? else {
                        return Err(eof_with_loc(self.ev));
                    };
                    ev.strip_node_tag();
                    let replay = RecordedEvents::from_event(ev, origin);
                    tagged_enum = None; // prevent mismatch check
                    Mode::TaggedNewtype(variant_name, replay)
                } else {
                    let Some(view) = self.peek_scalar_view()? else {
                        return Err(eof_with_loc(self.ev));
                    };
                    self.validate_scalar_tag(
                        view.tag,
                        SfTag::String,
                        "enum variant",
                        view.location,
                    )?;
                    if self.cfg.no_schema
                        && !view.tag.forces_string()
                        && maybe_not_string(&view.effective, &style, self.cfg.strict_booleans)
                    {
                        let view = self.take_scalar_view()?;
                        return Err(Self::quoting_required_for_scalar(&view));
                    }
                    let view = self.take_scalar_view()?;
                    Mode::Unit(EnumScalarId::from_view(view))
                }
            }
            Some(Ev::MapStart {
                tag,
                raw_tag,
                location,
                ..
            }) => {
                // `!map` is classified as `SfTag::Map` for compatibility when used as
                // an ordinary mapping tag. In a typed enum context it may instead select
                // a renamed `map` variant. Resolved core forms (`!!map`, verbatim tags,
                // and directive-expanded handles) have a different `raw_tag` and remain
                // YAML type annotations.
                let tag_name = simple_tagged_enum_name(&raw_tag, &tag).or_else(|| {
                    (tag == SfTag::Map && raw_tag.as_deref() == Some("!map"))
                        .then(|| "map".to_owned())
                });
                if let Some(tag_name) = tag_name
                    && variants.contains(&tag_name.as_str())
                {
                    self.ev.strip_peeked_node_tag()?;
                    return visitor.visit_enum(EA {
                        ev: self.ev,
                        cfg: self.cfg,
                        variant: EnumScalarId {
                            raw: Cow::Owned(tag_name.clone()),
                            effective: Cow::Owned(tag_name),
                            interpolated: false,
                            location,
                        },
                        map_mode: false,
                        tagged_payload: true,
                    });
                }

                self.expect_map_start()?;
                let mut key_de = YamlDeserializer::new(&mut *self.ev, self.cfg);
                key_de.in_key = true;
                if let Some(view) = key_de.peek_scalar_view()? {
                    key_de.validate_scalar_tag(
                        view.tag,
                        SfTag::String,
                        "enum variant",
                        view.location,
                    )?;
                    if self.cfg.no_schema
                        && !view.tag.forces_string()
                        && maybe_not_string(&view.raw, &view.style, self.cfg.strict_booleans)
                    {
                        let view = key_de.take_scalar_view()?;
                        return Err(Self::quoting_required_for_scalar(&view));
                    }
                    let view = key_de.take_scalar_view()?;
                    Mode::Map(view.raw.into_owned(), view.location)
                } else {
                    match self.ev.next()? {
                        Some(other) => {
                            return Err(Error::ExpectedStringKeyForExternallyTaggedEnum {
                                location: other.location(),
                            });
                        }
                        None => return Err(eof_with_loc(self.ev)),
                    }
                }
            }
            Some(Ev::SeqStart {
                tag,
                raw_tag,
                location,
                ..
            }) => {
                if let Some(tag_name) = simple_tagged_enum_name(&raw_tag, &tag)
                    && variants.contains(&tag_name.as_str())
                {
                    // Consume the SeqStart, collect all events until SeqEnd, replay as untagged sequence
                    let origin = self.ev.node_origin();
                    let Some(seq_start) = self.ev.next()? else {
                        return Err(eof_with_loc(self.ev));
                    };
                    let start_loc = seq_start.location();
                    let mut replay_events = RecordedEvents::new();
                    // Re-emit SeqStart without tag
                    if let Ev::SeqStart {
                        anchor, location, ..
                    } = seq_start
                    {
                        replay_events.push(
                            Ev::SeqStart {
                                anchor,
                                tag: SfTag::None,
                                raw_tag: None,
                                location,
                            },
                            origin,
                        );
                    }
                    let mut depth = 1usize;
                    while depth > 0 {
                        let _ = self.ev.peek()?;
                        let origin = self.ev.node_origin();
                        match self.ev.next()? {
                            Some(ev @ (Ev::SeqStart { .. } | Ev::MapStart { .. })) => {
                                depth += 1;
                                replay_events.push(ev, origin);
                            }
                            Some(ev @ (Ev::SeqEnd { .. } | Ev::MapEnd { .. })) => {
                                depth -= 1;
                                replay_events.push(ev, origin);
                            }
                            Some(ev) => {
                                replay_events.push(ev, origin);
                            }
                            None => return Err(eof_with_loc(self.ev)),
                        }
                    }
                    let replay = Box::new(ReplayEvents::new(
                        replay_events,
                        #[cfg(feature = "properties")]
                        self.ev.property_interpolation().clone(),
                    ));
                    return visitor.visit_enum(TaggedEA {
                        replay,
                        cfg: self.cfg,
                        variant: EnumScalarId {
                            raw: Cow::Owned(tag_name.clone()),
                            effective: Cow::Owned(tag_name),
                            interpolated: false,
                            location: start_loc,
                        },
                    });
                }
                return Err(Error::ExternallyTaggedEnumExpectedScalarOrMapping { location });
            }
            Some(Ev::SeqEnd { location }) => {
                return Err(Error::UnexpectedSequenceEnd { location });
            }
            Some(Ev::MapEnd { location }) => {
                return Err(Error::UnexpectedMappingEnd { location });
            }
            Some(Ev::Taken { location }) => {
                return Err(Error::unexpected("consumed event").with_location(location));
            }
            None => return Err(eof_with_loc(self.ev)),
        };

        if let Some((tag_name, location)) = tagged_enum
            && tag_name != name
        {
            return Err(Error::TaggedEnumMismatch {
                tagged: tag_name,
                target: name,
                location,
            });
        }

        struct EA<'de, 'e> {
            ev: &'e mut dyn Events<'de>,
            cfg: Cfg,
            variant: EnumScalarId<'de>,
            map_mode: bool,
            tagged_payload: bool,
        }

        impl<'de, 'e> de::EnumAccess<'de> for EA<'de, 'e> {
            type Error = Error;
            type Variant = VA<'de, 'e>;

            /// Provide the variant identifier to Serde and return a `VariantAccess`.
            fn variant_seed<Vv>(self, seed: Vv) -> Result<(Vv::Value, Self::Variant), Error>
            where
                Vv: de::DeserializeSeed<'de>,
            {
                let EA {
                    ev,
                    cfg,
                    variant,
                    map_mode,
                    tagged_payload,
                } = self;
                let v = seed.deserialize(variant.into_deserializer())?;
                Ok((
                    v,
                    VA {
                        ev,
                        cfg,
                        map_mode,
                        tagged_payload,
                    },
                ))
            }
        }

        struct VA<'de, 'e> {
            ev: &'e mut dyn Events<'de>,
            cfg: Cfg,
            map_mode: bool,
            tagged_payload: bool,
        }

        impl VA<'_, '_> {
            /// In map mode (`{ Variant: ... }`) ensure the closing `}` is present.
            fn expect_map_end(&mut self) -> Result<(), Error> {
                match self.ev.next()? {
                    Some(Ev::MapEnd { .. }) => Ok(()),
                    Some(other) => Err(Error::ExpectedMappingEndAfterEnumVariantValue {
                        location: other.location(),
                    }),
                    None => Err(eof_with_loc(self.ev)),
                }
            }
        }

        impl<'de> de::VariantAccess<'de> for VA<'de, '_> {
            type Error = Error;

            /// Handle unit variants: `Variant` or `{ Variant: null/~ }`.
            fn unit_variant(mut self) -> Result<(), Error> {
                if self.map_mode {
                    if YamlDeserializer::new(self.ev, self.cfg).peek_null_value()? {
                        let _ = self.ev.next()?; // consume the null-like scalar
                        return self.expect_map_end();
                    }
                    match self.ev.peek()? {
                        Some(Ev::MapEnd { .. }) => {
                            let _ = self.ev.next()?;
                            Ok(())
                        }
                        Some(other) => Err(Error::UnexpectedValueForUnitEnumVariant {
                            location: other.location(),
                        }),
                        None => Err(eof_with_loc(self.ev)),
                    }
                } else if self.tagged_payload {
                    de::Deserialize::deserialize(YamlDeserializer::new(self.ev, self.cfg))
                } else {
                    Ok(())
                }
            }

            /// Handle newtype variants by delegating into `Deser`.
            fn newtype_variant_seed<T>(mut self, seed: T) -> Result<T::Value, Error>
            where
                T: de::DeserializeSeed<'de>,
            {
                // Get locations for error reporting before deserializing.
                let defined_location = match self.ev.peek()? {
                    Some(ev) => ev.location(),
                    None => self.ev.last_location(),
                };
                let alias_reference_location = self.ev.alias_reference_location();

                let mut de = YamlDeserializer::new(self.ev, self.cfg);
                let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                let value = with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
                    .map_err(|e| {
                        attach_alias_locations_if_missing(
                            e,
                            alias_reference_location,
                            defined_location,
                        )
                    })?;
                if self.map_mode {
                    self.expect_map_end()?;
                }
                Ok(value)
            }

            /// Handle tuple variants via `deserialize_tuple`.
            fn tuple_variant<Vv>(mut self, len: usize, visitor: Vv) -> Result<Vv::Value, Error>
            where
                Vv: Visitor<'de>,
            {
                let result =
                    YamlDeserializer::new(self.ev, self.cfg).deserialize_tuple(len, visitor)?;
                if self.map_mode {
                    self.expect_map_end()?;
                }
                Ok(result)
            }

            /// Handle struct variants via `deserialize_struct`.
            fn struct_variant<Vv>(
                mut self,
                fields: &'static [&'static str],
                visitor: Vv,
            ) -> Result<Vv::Value, Error>
            where
                Vv: Visitor<'de>,
            {
                let result = YamlDeserializer::new(self.ev, self.cfg)
                    .deserialize_struct("", fields, visitor)?;
                if self.map_mode {
                    self.expect_map_end()?;
                }
                Ok(result)
            }
        }

        struct TaggedEA<'de> {
            replay: Box<ReplayEvents<'de>>,
            cfg: Cfg,
            variant: EnumScalarId<'de>,
        }

        impl<'de> de::EnumAccess<'de> for TaggedEA<'de> {
            type Error = Error;
            type Variant = TaggedVA<'de>;

            fn variant_seed<Vv>(self, seed: Vv) -> Result<(Vv::Value, Self::Variant), Error>
            where
                Vv: de::DeserializeSeed<'de>,
            {
                let v = seed.deserialize(self.variant.into_deserializer())?;
                Ok((
                    v,
                    TaggedVA {
                        replay: self.replay,
                        cfg: self.cfg,
                    },
                ))
            }
        }

        struct TaggedVA<'de> {
            replay: Box<ReplayEvents<'de>>,
            cfg: Cfg,
        }

        impl<'de> de::VariantAccess<'de> for TaggedVA<'de> {
            type Error = Error;

            fn unit_variant(mut self) -> Result<(), Error> {
                de::Deserialize::deserialize(YamlDeserializer::new(&mut *self.replay, self.cfg))
            }

            fn newtype_variant_seed<T>(mut self, seed: T) -> Result<T::Value, Error>
            where
                T: de::DeserializeSeed<'de>,
            {
                let mut de = YamlDeserializer::new(&mut *self.replay, self.cfg);
                let redaction_ctx = de.peek_scalar_redaction_ctx()?;
                with_subtree_redaction(redaction_ctx, || seed.deserialize(de))
            }

            fn tuple_variant<Vv>(mut self, len: usize, visitor: Vv) -> Result<Vv::Value, Error>
            where
                Vv: Visitor<'de>,
            {
                YamlDeserializer::new(&mut *self.replay, self.cfg).deserialize_tuple(len, visitor)
            }

            fn struct_variant<Vv>(
                mut self,
                fields: &'static [&'static str],
                visitor: Vv,
            ) -> Result<Vv::Value, Error>
            where
                Vv: Visitor<'de>,
            {
                YamlDeserializer::new(&mut *self.replay, self.cfg)
                    .deserialize_struct("", fields, visitor)
            }
        }

        let access = match mode {
            Mode::Unit(variant) => EA {
                ev: self.ev,
                cfg: self.cfg,
                variant,
                map_mode: false,
                tagged_payload: false,
            },
            Mode::Map(variant, variant_location) => EA {
                ev: self.ev,
                cfg: self.cfg,
                variant: EnumScalarId {
                    raw: Cow::Owned(variant.clone()),
                    effective: Cow::Owned(variant),
                    interpolated: false,
                    location: variant_location,
                },
                map_mode: true,
                tagged_payload: false,
            },
            Mode::TaggedNewtype(variant, replay_buf) => {
                let replay = Box::new(ReplayEvents::new(
                    replay_buf,
                    #[cfg(feature = "properties")]
                    self.ev.property_interpolation().clone(),
                ));
                // We need to use a replay source for the payload
                return visitor.visit_enum(TaggedEA {
                    replay,
                    cfg: self.cfg,
                    variant,
                });
            }
        };

        visitor.visit_enum(access)
    }

    /// Deserialize an identifier (e.g., struct field name); treated as string.
    fn deserialize_identifier<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, Self::Error> {
        self.deserialize_str(visitor)
    }

    /// Deserialize a value that the caller intends to ignore.
    ///
    /// Use the same tag validation and conversions as other untyped reads.
    fn deserialize_ignored_any<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, Self::Error> {
        self.deserialize_any(visitor)
    }
}

#[cfg(all(test, feature = "properties"))]
mod tests {
    use super::super::events::PropertyInterpolation;
    use super::super::options::{Options, PropertySyntax};
    use super::*;

    #[test]
    fn effective_scalar_value_without_property_map_returns_original_scalar() {
        let budget = crate::Budget::default();
        let mut events = ReplayEvents::new(
            Vec::new(),
            PropertyInterpolation::new(None, PropertySyntax::Braced, Some(&budget)),
        );
        let de = YamlDeserializer::new(&mut events, Cfg::from_options(&Options::default()));

        let value = de
            .effective_scalar_value(Cow::Borrowed("${MISSING}"), Location::new(1, 1))
            .expect("missing property map should not be treated as interpolation");

        assert_eq!(value, Cow::Borrowed("${MISSING}"));
    }
}