qubit-value 0.13.1

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Canonical Serde payload adapters for value variants.

#[cfg(feature = "url")]
use ::url::Url;
#[cfg(any(feature = "chrono", feature = "url"))]
use serde::Deserialize;
#[cfg(any(feature = "chrono", feature = "url"))]
use serde::Deserializer;
#[cfg(feature = "chrono")]
use serde::Serializer;
#[cfg(any(feature = "chrono", feature = "url"))]
use serde::de::Error as _;

#[cfg(feature = "big-decimal")]
use self::internal::BigDecimalPayload;
use self::internal::DurationPayload;
#[cfg(any(feature = "chrono", feature = "url"))]
use self::internal::ValidatedSequenceVisitor;
#[cfg(feature = "chrono")]
use crate::ValueWireEncodeError;

/// Validates the UTC year accepted by the V1 instant representation.
///
/// # Parameters
///
/// * `year` - UTC calendar year to validate.
///
/// # Returns
///
/// `Ok(())` when `year` is within the inclusive four-digit range.
///
/// # Errors
///
/// Returns [`crate::ValueWireEncodeError::InstantYearOutOfRange`] when `year`
/// is outside `0..=9999`.
#[cfg(feature = "chrono")]
#[inline]
pub(crate) fn validate_instant_year(year: i32) -> Result<(), ValueWireEncodeError> {
    if (0..=9999).contains(&year) {
        Ok(())
    } else {
        Err(ValueWireEncodeError::InstantYearOutOfRange { year })
    }
}

pub(crate) use crate::finite_float::float32;
pub(crate) use crate::finite_float::float32_vec;
pub(crate) use crate::finite_float::float64;
pub(crate) use crate::finite_float::float64_vec;
pub(crate) use crate::wide_integer::int128;
pub(crate) use crate::wide_integer::int128_vec;
pub(crate) use crate::wide_integer::uint128;
pub(crate) use crate::wide_integer::uint128_vec;

/// Canonical scalar string-map payload adapter.
pub(crate) mod string_map;
/// Canonical string-map collection payload adapter.
pub(crate) mod string_map_vec;

/// Serializes JSON values by recursively ordering every object key.
#[cfg(feature = "json")]
pub(crate) mod json;

/// Serializes JSON collections by recursively ordering every object key.
#[cfg(feature = "json")]
pub(crate) mod json_vec;

/// Shared canonical decimal string conversions.
#[cfg(feature = "big-integer")]
mod decimal;

/// Private payload validation and representation types.
mod internal;

/// Largest decimal exponent magnitude accepted by the V1 wire format.
#[cfg(feature = "big-decimal")]
pub(crate) const MAX_BIG_DECIMAL_ABSOLUTE_SCALE: i64 = 150_000;

/// Returns whether a decimal exponent is representable by the bounded V1
/// format.
///
/// # Parameters
///
/// * `scale` - Signed decimal scale to compare with the V1 bound.
///
/// # Returns
///
/// `true` when the absolute scale is within the inclusive V1 limit.
#[must_use]
#[cfg(feature = "big-decimal")]
#[inline(always)]
pub(crate) const fn is_valid_big_decimal_scale(scale: i64) -> bool {
    scale.unsigned_abs() <= MAX_BIG_DECIMAL_ABSOLUTE_SCALE as u64
}

/// Serializes and validates canonical scalar string payloads.
///
/// # Type Parameters
///
/// * `S` - Destination serializer type.
/// * `T` - Source value type.
/// * `F` - Canonical formatter type.
///
/// # Parameters
///
/// * `value` - Source value to format.
/// * `serializer` - Destination serializer.
/// * `format` - Formatter producing the canonical V1 string.
///
/// # Returns
///
/// The destination serializer's result.
///
/// # Errors
///
/// Returns `S::Error` when the serializer rejects the canonical string.
#[cfg(feature = "chrono")]
fn serialize_canonical<S, T, F>(value: &T, serializer: S, format: F) -> Result<S::Ok, S::Error>
where
    S: Serializer,
    F: FnOnce(&T) -> String,
{
    serializer.serialize_str(&format(value))
}

/// Deserializes a scalar string only when it is already in canonical form.
///
/// # Type Parameters
///
/// * `D` - Source deserializer type.
/// * `T` - Decoded value type.
/// * `P` - Parser type.
/// * `F` - Canonical formatter type.
///
/// # Parameters
///
/// * `deserializer` - Source deserializer.
/// * `parse` - Parser converting source text into `T`.
/// * `format` - Formatter reproducing canonical text from `T`.
///
/// # Returns
///
/// The decoded value when its input text is canonical.
///
/// # Errors
///
/// Returns `D::Error` for deserialization, parsing, or non-canonical text.
#[cfg(any(feature = "chrono", feature = "url"))]
fn deserialize_canonical<'de, D, T, P, F>(
    deserializer: D,
    parse: P,
    format: F,
) -> Result<T, D::Error>
where
    D: Deserializer<'de>,
    P: FnOnce(&str) -> Result<T, String>,
    F: FnOnce(&T) -> String,
{
    let input = String::deserialize(deserializer)?;
    let value = parse(&input).map_err(D::Error::custom)?;
    if format(&value) != input {
        return Err(D::Error::custom("non-canonical V1 string payload"));
    }
    Ok(value)
}

/// Serializes a collection through a canonical scalar formatter.
///
/// # Type Parameters
///
/// * `S` - Destination serializer type.
/// * `T` - Source element type.
/// * `F` - Canonical formatter type.
///
/// # Parameters
///
/// * `values` - Source elements to serialize in order.
/// * `serializer` - Destination serializer.
/// * `format` - Formatter producing each canonical V1 string.
///
/// # Returns
///
/// The destination serializer's sequence result.
///
/// # Errors
///
/// Returns `S::Error` when sequence serialization fails.
#[cfg(feature = "chrono")]
#[inline]
fn serialize_canonical_vec<S, T, F>(
    values: &[T],
    serializer: S,
    format: F,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
    F: Fn(&T) -> String,
{
    serializer.collect_seq(values.iter().map(format))
}

/// Deserializes canonical string collection payloads.
///
/// # Type Parameters
///
/// * `D` - Source deserializer type.
/// * `T` - Decoded element type.
/// * `P` - Parser type.
/// * `F` - Canonical formatter type.
///
/// # Parameters
///
/// * `deserializer` - Source deserializer.
/// * `parse` - Parser converting each source string into `T`.
/// * `format` - Formatter reproducing canonical text from `T`.
///
/// # Returns
///
/// Decoded elements in their source order.
///
/// # Errors
///
/// Returns `D::Error` for deserialization, parsing, or non-canonical text.
#[cfg(any(feature = "chrono", feature = "url"))]
fn deserialize_canonical_vec<'de, D, T, P, F>(
    deserializer: D,
    parse: P,
    format: F,
) -> Result<Vec<T>, D::Error>
where
    D: Deserializer<'de>,
    P: Fn(&str) -> Result<T, String>,
    F: Fn(&T) -> String,
{
    ValidatedSequenceVisitor::<String, T, _>::new(|input: String| {
        let value = parse(&input)?;
        if format(&value) != input {
            return Err("non-canonical V1 string payload".to_owned());
        }
        Ok(value)
    })
    .deserialize(deserializer)
}

/// Defines canonical scalar and vector wire adapters for one chrono type.
#[cfg(feature = "chrono")]
macro_rules! define_chrono_wire {
    ($scalar:ident, $vector:ident, [$($import:path),+], $type:ty, $parse:expr, $format:expr $(, $validation_error:path => $validate:expr)?) => {
        /// Canonical scalar wire adapter generated for one chrono type.
        pub(crate) mod $scalar {
            $(use $import;)+
            use serde::Deserializer;
            use serde::Serializer;
            $(use $validation_error as _;)?

            /// Serializes the chrono value through the crate-owned V1 format.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `value` - Chrono value to serialize.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when serialization fails.
            #[inline]
            pub(crate) fn serialize<S>(value: &$type, serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                $(
                    {
                        ($validate)(value).map_err(S::Error::custom)?;
                    }
                )?
                super::serialize_canonical(value, serializer, $format)
            }

            /// Deserializes the chrono value only from its canonical V1 format.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// The decoded chrono value.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for malformed or non-canonical input.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<$type, D::Error>
            where
                D: Deserializer<'de>,
            {
                super::deserialize_canonical(deserializer, $parse, $format)
            }
        }

        /// Canonical collection wire adapter generated for one chrono type.
        pub(crate) mod $vector {
            $(use $import;)+
            use serde::Deserializer;
            use serde::Serializer;
            $(use $validation_error as _;)?

            /// Serializes chrono values through the crate-owned V1 format.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `values` - Chrono values to serialize in order.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's sequence result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when sequence serialization fails.
            pub(crate) fn serialize<S>(values: &[$type], serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                $(
                    {
                        for value in values {
                            ($validate)(value).map_err(S::Error::custom)?;
                        }
                    }
                )?
                super::serialize_canonical_vec(values, serializer, $format)
            }

            /// Deserializes chrono values only from their canonical V1 format.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// Decoded chrono values in source order.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for malformed or non-canonical input.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<$type>, D::Error>
            where
                D: Deserializer<'de>,
            {
                super::deserialize_canonical_vec(deserializer, $parse, $format)
            }
        }
    };
}

#[cfg(feature = "chrono")]
define_chrono_wire!(
    date,
    date_vec,
    [chrono::NaiveDate],
    NaiveDate,
    |input| NaiveDate::parse_from_str(input, "%F").map_err(|error| error.to_string()),
    |value: &NaiveDate| value.format("%F").to_string()
);

#[cfg(feature = "chrono")]
define_chrono_wire!(
    time,
    time_vec,
    [chrono::NaiveTime],
    NaiveTime,
    |input| NaiveTime::parse_from_str(input, "%H:%M:%S%.f").map_err(|error| error.to_string()),
    |value: &NaiveTime| value.format("%H:%M:%S%.f").to_string()
);

#[cfg(feature = "chrono")]
define_chrono_wire!(
    datetime,
    datetime_vec,
    [chrono::NaiveDateTime],
    NaiveDateTime,
    |input| NaiveDateTime::parse_from_str(input, "%Y-%m-%dT%H:%M:%S%.f")
        .map_err(|error| error.to_string()),
    |value: &NaiveDateTime| value.format("%Y-%m-%dT%H:%M:%S%.f").to_string()
);

#[cfg(feature = "chrono")]
define_chrono_wire!(
    instant,
    instant_vec,
    [chrono::DateTime, chrono::Datelike, chrono::SecondsFormat, chrono::Utc],
    DateTime<Utc>,
    |input| DateTime::parse_from_rfc3339(input)
        .map(|value| value.with_timezone(&Utc))
        .map_err(|error| error.to_string()),
    |value: &DateTime<Utc>| value.to_rfc3339_opts(SecondsFormat::AutoSi, true),
    serde::ser::Error => |value: &DateTime<Utc>| {
        crate::wire::validate_instant_year(value.year())
    }
);

/// Defines canonical scalar and vector wire adapters for URL values.
#[cfg(feature = "url")]
macro_rules! define_url_wire {
    () => {
        /// Canonical scalar URL wire adapter.
        pub(crate) mod url {
            use serde::Deserializer;
            use serde::Serializer;

            use super::Url;

            /// Serializes a URL through its canonical normalized string.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `value` - Parsed URL to serialize.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when serialization fails.
            #[inline]
            pub(crate) fn serialize<S>(value: &Url, serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                serializer.serialize_str(value.as_str())
            }

            /// Deserializes only a canonical normalized URL string.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// The parsed canonical URL.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for invalid or non-canonical URL text.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Url, D::Error>
            where
                D: Deserializer<'de>,
            {
                super::deserialize_canonical(
                    deserializer,
                    |input| Url::parse(input).map_err(|error| error.to_string()),
                    |value: &Url| value.as_str().to_owned(),
                )
            }
        }

        /// Canonical URL collection wire adapter.
        pub(crate) mod url_vec {
            use serde::Deserializer;
            use serde::Serializer;

            use super::Url;

            /// Serializes URLs through their canonical normalized strings.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `values` - Parsed URLs to serialize in order.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's sequence result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when sequence serialization fails.
            #[inline]
            pub(crate) fn serialize<S>(values: &[Url], serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                serializer.collect_seq(values.iter().map(|value| value.as_str()))
            }

            /// Deserializes only canonical normalized URL strings.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// Parsed canonical URLs in source order.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for invalid or non-canonical URL text.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<Url>, D::Error>
            where
                D: Deserializer<'de>,
            {
                super::deserialize_canonical_vec(
                    deserializer,
                    |input| Url::parse(input).map_err(|error| error.to_string()),
                    |value: &Url| value.as_str().to_owned(),
                )
            }
        }
    };
}

#[cfg(feature = "url")]
define_url_wire!();

/// Defines canonical scalar and vector wire adapters for a decimal-backed type.
#[cfg(feature = "big-integer")]
macro_rules! define_decimal_serde {
    ($scalar_module:ident, $vector_module:ident, $type:ident) => {
        /// Canonical scalar wire adapter generated for one decimal-backed type.
        pub(crate) mod $scalar_module {
            use num_bigint::$type;
            use serde::Deserializer;
            use serde::Serializer;

            use super::decimal;

            /// Serializes a decimal value as a canonical decimal string.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `value` - Decimal-backed value to serialize.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when serialization fails.
            #[inline]
            pub(crate) fn serialize<S>(value: &$type, serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                decimal::serialize(value, serializer)
            }

            /// Deserializes a decimal value from a canonical decimal string.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// The decoded decimal-backed value.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for malformed or non-canonical input.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<$type, D::Error>
            where
                D: Deserializer<'de>,
            {
                decimal::deserialize(deserializer)
            }
        }

        /// Canonical collection wire adapter generated for one decimal-backed type.
        pub(crate) mod $vector_module {
            use num_bigint::$type;
            use serde::Deserializer;
            use serde::Serializer;

            use super::decimal;

            /// Serializes decimal values as canonical decimal strings.
            ///
            /// # Type Parameters
            ///
            /// * `S` - Destination serializer type.
            ///
            /// # Parameters
            ///
            /// * `values` - Decimal-backed values to serialize in order.
            /// * `serializer` - Destination serializer.
            ///
            /// # Returns
            ///
            /// The destination serializer's sequence result.
            ///
            /// # Errors
            ///
            /// Returns `S::Error` when sequence serialization fails.
            #[inline]
            pub(crate) fn serialize<S>(values: &[$type], serializer: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                decimal::serialize_vec(values, serializer)
            }

            /// Deserializes decimal values from canonical decimal strings.
            ///
            /// # Type Parameters
            ///
            /// * `D` - Source deserializer type.
            ///
            /// # Parameters
            ///
            /// * `deserializer` - Source deserializer.
            ///
            /// # Returns
            ///
            /// Decoded decimal-backed values in source order.
            ///
            /// # Errors
            ///
            /// Returns `D::Error` for malformed or non-canonical input.
            #[inline]
            pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<$type>, D::Error>
            where
                D: Deserializer<'de>,
            {
                decimal::deserialize_vec(deserializer)
            }
        }
    };
}

#[cfg(feature = "big-integer")]
define_decimal_serde!(big_integer, big_integer_vec, BigInt);

/// Canonical arbitrary-precision decimal scalar payload adapter.
#[cfg(feature = "big-decimal")]
pub(crate) mod big_decimal {
    use bigdecimal::BigDecimal;
    use serde::Deserialize;
    use serde::Deserializer;
    use serde::Serialize;
    use serde::Serializer;
    use serde::de::Error as _;
    use serde::ser::Error as _;

    use super::BigDecimalPayload;

    /// Serializes a decimal as an exact `{ coefficient, scale }` payload.
    ///
    /// # Type Parameters
    ///
    /// * `S` - Destination serializer type.
    ///
    /// # Parameters
    ///
    /// * `value` - Decimal value to serialize exactly.
    /// * `serializer` - Destination serializer.
    ///
    /// # Returns
    ///
    /// The destination serializer's result.
    ///
    /// # Errors
    ///
    /// Returns `S::Error` when the scale is out of range or serialization
    /// fails.
    #[inline]
    pub(crate) fn serialize<S>(value: &BigDecimal, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        BigDecimalPayload::try_from(value)
            .map_err(S::Error::custom)?
            .serialize(serializer)
    }

    /// Deserializes and validates an exact decimal payload.
    ///
    /// # Type Parameters
    ///
    /// * `D` - Source deserializer type.
    ///
    /// # Parameters
    ///
    /// * `deserializer` - Source deserializer.
    ///
    /// # Returns
    ///
    /// The exact decoded decimal value.
    ///
    /// # Errors
    ///
    /// Returns `D::Error` for malformed payloads or invalid decimal scales.
    #[inline]
    pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<BigDecimal, D::Error>
    where
        D: Deserializer<'de>,
    {
        BigDecimalPayload::deserialize(deserializer)?
            .try_into()
            .map_err(D::Error::custom)
    }
}

/// Canonical arbitrary-precision decimal collection payload adapter.
#[cfg(feature = "big-decimal")]
pub(crate) mod big_decimal_vec {
    use bigdecimal::BigDecimal;
    use serde::Deserializer;
    use serde::Serializer;
    use serde::ser::Error as _;
    use serde::ser::SerializeSeq;

    use super::BigDecimalPayload;
    use super::internal::ValidatedSequenceVisitor;

    /// Serializes decimals as exact `{ coefficient, scale }` payloads.
    ///
    /// # Type Parameters
    ///
    /// * `S` - Destination serializer type.
    ///
    /// # Parameters
    ///
    /// * `values` - Decimal values to serialize in order.
    /// * `serializer` - Destination serializer.
    ///
    /// # Returns
    ///
    /// The destination serializer's sequence result.
    ///
    /// # Errors
    ///
    /// Returns `S::Error` for an out-of-range scale or serialization failure.
    pub(crate) fn serialize<S>(values: &[BigDecimal], serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let mut sequence = serializer.serialize_seq(Some(values.len()))?;
        for value in values {
            let payload = BigDecimalPayload::try_from(value).map_err(S::Error::custom)?;
            sequence.serialize_element(&payload)?;
        }
        sequence.end()
    }

    /// Deserializes and validates exact decimal payloads.
    ///
    /// # Type Parameters
    ///
    /// * `D` - Source deserializer type.
    ///
    /// # Parameters
    ///
    /// * `deserializer` - Source deserializer.
    ///
    /// # Returns
    ///
    /// Exact decoded decimal values in source order.
    ///
    /// # Errors
    ///
    /// Returns `D::Error` for malformed payloads or invalid decimal scales.
    #[inline]
    pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<BigDecimal>, D::Error>
    where
        D: Deserializer<'de>,
    {
        ValidatedSequenceVisitor::<BigDecimalPayload, BigDecimal, _>::new(
            |value: BigDecimalPayload| value.try_into().map_err(str::to_owned),
        )
        .deserialize(deserializer)
    }
}

/// Canonical scalar duration payload adapter.
pub(crate) mod duration {
    use std::time::Duration;

    use serde::Deserialize;
    use serde::Deserializer;
    use serde::Serialize;
    use serde::Serializer;
    use serde::de::Error as _;

    use super::DurationPayload;

    /// Serializes a duration as `{ secs, nanos }`.
    ///
    /// # Type Parameters
    ///
    /// * `S` - Destination serializer type.
    ///
    /// # Parameters
    ///
    /// * `value` - Duration to decompose into seconds and nanoseconds.
    /// * `serializer` - Destination serializer.
    ///
    /// # Returns
    ///
    /// The destination serializer's result.
    ///
    /// # Errors
    ///
    /// Returns `S::Error` when serialization fails.
    #[inline]
    pub(crate) fn serialize<S>(value: &Duration, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        DurationPayload::from(value).serialize(serializer)
    }

    /// Deserializes and validates a `{ secs, nanos }` duration payload.
    ///
    /// # Type Parameters
    ///
    /// * `D` - Source deserializer type.
    ///
    /// # Parameters
    ///
    /// * `deserializer` - Source deserializer.
    ///
    /// # Returns
    ///
    /// The decoded duration.
    ///
    /// # Errors
    ///
    /// Returns `D::Error` when decoding fails or nanoseconds are out of range.
    #[inline]
    pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
    where
        D: Deserializer<'de>,
    {
        DurationPayload::deserialize(deserializer)?
            .try_into()
            .map_err(D::Error::custom)
    }
}

/// Canonical duration collection payload adapter.
pub(crate) mod duration_vec {
    use std::time::Duration;

    use serde::Deserializer;
    use serde::Serializer;

    use super::DurationPayload;
    use super::internal::ValidatedSequenceVisitor;

    /// Serializes durations as a sequence of `{ secs, nanos }` payloads.
    ///
    /// # Type Parameters
    ///
    /// * `S` - Destination serializer type.
    ///
    /// # Parameters
    ///
    /// * `values` - Durations to serialize in order.
    /// * `serializer` - Destination serializer.
    ///
    /// # Returns
    ///
    /// The destination serializer's sequence result.
    ///
    /// # Errors
    ///
    /// Returns `S::Error` when sequence serialization fails.
    #[inline]
    pub(crate) fn serialize<S>(values: &[Duration], serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.collect_seq(values.iter().map(DurationPayload::from))
    }

    /// Deserializes and validates a sequence of duration payloads.
    ///
    /// # Type Parameters
    ///
    /// * `D` - Source deserializer type.
    ///
    /// # Parameters
    ///
    /// * `deserializer` - Source deserializer.
    ///
    /// # Returns
    ///
    /// Decoded durations in source order.
    ///
    /// # Errors
    ///
    /// Returns `D::Error` when decoding fails or any nanoseconds field is out
    /// of range.
    #[inline]
    pub(crate) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<Duration>, D::Error>
    where
        D: Deserializer<'de>,
    {
        ValidatedSequenceVisitor::<DurationPayload, Duration, _>::new(|value: DurationPayload| {
            value.try_into().map_err(str::to_owned)
        })
        .deserialize(deserializer)
    }
}

#[cfg(test)]
mod contract_boundary_tests {
    #[cfg(feature = "chrono")]
    #[test]
    fn test_instant_year_accepts_only_the_four_digit_wire_range() {
        assert!(super::validate_instant_year(0).is_ok());
        assert!(super::validate_instant_year(9999).is_ok());
        assert!(matches!(
            super::validate_instant_year(-1),
            Err(crate::ValueWireEncodeError::InstantYearOutOfRange { year: -1 }),
        ));
        assert!(matches!(
            super::validate_instant_year(10_000),
            Err(crate::ValueWireEncodeError::InstantYearOutOfRange { year: 10_000 }),
        ));
    }

    #[cfg(feature = "big-decimal")]
    #[test]
    fn test_decimal_scale_accepts_only_the_inclusive_wire_bound() {
        assert!(super::is_valid_big_decimal_scale(0));
        assert!(super::is_valid_big_decimal_scale(150_000));
        assert!(super::is_valid_big_decimal_scale(-150_000));
        assert!(!super::is_valid_big_decimal_scale(150_001));
        assert!(!super::is_valid_big_decimal_scale(-150_001));
        assert!(!super::is_valid_big_decimal_scale(i64::MIN));
    }
}