miniextendr_api/

condition.rs

//! Condition macros and signal enum for the Rust→R condition pipeline.
//!
//! This module provides two things:
//!
//! 1. **[`enum@RCondition`] enum** — the internal panic payload used by `error!()`,
//!    `warning!()`, `message!()`, and `condition!()` macros. Caught by
//!    [`crate::unwind_protect::with_r_unwind_protect`] before the generic
//!    panic→error path, then forwarded to R as a structured condition with
//!    `rust_*` class layering via
//!    [`crate::error_value::make_rust_condition_value`].
//!
//! 2. **[`AsRError`] struct** — wraps any `E: std::error::Error` and
//!    preserves the full error chain (cause/source) when converting to an R
//!    error message. Use as the `Err` type in `Result` returns.
//!
//! # When to reach for what
//!
//! There are three Rust→R error-emission paths and they are not
//! interchangeable. The crate-level rationale (why tagged-SEXP at all, what
//! `error_in_r` defaults imply, and the `with_r_unwind_protect` leak) lives
//! on [`crate::error_value`]; the practical picking-one summary:
//!
//! - **`panic!`** — escape hatch. Becomes class `c("rust_error",
//!   "simpleError", "error", "condition")` with `kind = "panic"`. Use for
//!   genuine bugs or impossible states. Cheapest in source; coarsest in R
//!   (callers can only match `rust_error` / `error`, not a specific class).
//! - **`error!` / `warning!` / `message!` / `condition!`** (this module) —
//!   typed conditions. Same transport, but allow an optional `class =
//!   "name"` so R-side `tryCatch` can route by class. `warning!` /
//!   `message!` / `condition!` are the only way to emit non-error
//!   conditions; `panic!` is always an error.
//! - **`Result<T, E>` with [`AsRError<E>`]** — value-style propagation
//!   through Rust code. Converts at the boundary; `kind = "result_err"`.
//!   Best when the failure path is real-and-recoverable in Rust and the
//!   error chain (`std::error::Error::source`) is worth preserving.
//!
//! `Rf_error` is *not* on this list. Direct `Rf_error` skips Rust
//! destructors unconditionally and is forbidden by lint MXL300; see
//! [`crate::error_value`] for the full reasoning.
//!
//! # Macro-vs-module name collision
//!
//! `#[macro_export]` puts each macro at the *crate root*, where `error!` and
//! `condition!` collide with the same-named modules `pub mod error` and `pub
//! mod condition`. The practical implication: `use miniextendr_api::{error,
//! condition}` imports the *modules*, not the macros, and a subsequent
//! `error!(...)` call fails to resolve.
//!
//! Workarounds, in rough order of ergonomics:
//!
//! 1. Invoke via fully-qualified path: `miniextendr_api::error!("...")`.
//! 2. `use miniextendr_api as mx;` then `mx::error!("...")`.
//! 3. `warning!` and `message!` have no module conflict — `use
//!    miniextendr_api::{warning, message};` works directly.
//!
//! See the individual macro docs for the per-macro reminder.
//!
//! # Condition macros
//!
//! The four macros are the user-facing API for raising non-panic conditions from
//! Rust. They ride the tagged-condition transport that every `#[miniextendr]`
//! function uses:
//!
//! ```ignore
//! use miniextendr_api::{error, warning, message, condition};
//!
//! #[miniextendr]
//! fn demo_error() {
//!     error!("something went wrong: {}", 42);
//! }
//!
//! #[miniextendr]
//! fn demo_warning() {
//!     warning!("something looks suspicious");
//! }
//!
//! #[miniextendr]
//! fn demo_message() {
//!     message!("progress: {} of {}", 1, 10);
//! }
//!
//! #[miniextendr]
//! fn demo_condition() {
//!     condition!("a signallable condition");
//! }
//! ```
//!
//! Optional `class =` extension for programmatic catching:
//!
//! ```ignore
//! #[miniextendr]
//! fn typed_error(name: &str) {
//!     error!(class = "my_error", "missing field: {name}");
//! }
//! ```
//!
//! ```r
//! tryCatch(typed_error("x"), my_error = function(e) "caught!")
//! # [1] "caught!"
//! ```
//!
//! Optional `data =` extension attaches structured fields readable as
//! `e$<name>` in handlers (rlang-`abort()`-style):
//!
//! ```ignore
//! #[miniextendr]
//! fn validate(value: i32) {
//!     if !(0..=100).contains(&value) {
//!         miniextendr_api::error!(
//!             class = "validation_error",
//!             data = [("value", value), ("min", 0), ("max", 100)],
//!             "value {value} out of range"
//!         );
//!     }
//! }
//! ```
//!
//! ```r
//! tryCatch(validate(150L), validation_error = function(e) c(e$value, e$min, e$max))
//! # [1] 150   0 100
//! ```
//!
//! Supported `data` value types (anything with `RValue: From<_>`): scalars and
//! `Vec`s of `i32`, `f64`, `bool`, `String` / `&str`; their NA-aware `Option` /
//! `Vec<Option<_>>` forms (`None` → R `NA`); the wide-integer ladder (`i64` /
//! `u32`, narrowed to `integer(1)` when it fits, `double(1)` otherwise); and the
//! [`RValue::debug`](crate::RValue::debug) escape hatch, which stringifies any
//! `T: Debug`. For nested lists or complex/raw/NA-bearing values build an
//! [`RValue`](crate::RValue) directly. The payload is built as a Send-safe owned
//! value at the call site and materialised as R objects on the main thread — so
//! `data =` works from worker-thread code too.
//!
//! Three `data =` grammars are accepted (see [`crate::error!`]):
//! - single pair: `data = ("name", value)`
//! - bracketed list: `data = [("a", v1), ("b", v2)]`
//! - keyed builder sugar: `data = { value = 42, code = 7 }` (bare-ident keys)
//!
//! # `AsRError`
//!
//! ```ignore
//! use miniextendr_api::condition::AsRError;
//!
//! #[miniextendr]
//! fn parse_config(path: &str) -> Result<i32, AsRError<std::io::Error>> {
//!     let content = std::fs::read_to_string(path).map_err(AsRError)?;
//!     Ok(content.len() as i32)
//! }
//! ```

// region: ConditionData — Send-safe owned condition-data payload

/// Named condition-data payload: an ordered list of `(name, value)` pairs.
///
/// Produced by the macros' `data = ...` form and consumed by
/// [`crate::error_value::make_rust_condition_value`]. Each value is an
/// [`RValue`](crate::RValue) — an owned, `Send`, R-native value tree. Send-safe
/// by construction (no live `SEXP`), so the payload can travel through
/// `panic_any` and cross the worker→main thread boundary; the R objects are
/// materialised on the main thread at the unwind boundary.
///
/// The macros accept any value with `RValue: From<_>` (scalars and `Vec`s of
/// `i32` / `f64` / `bool` / `String` / `&str`; their NA-aware `Option` /
/// `Vec<Option<_>>` forms; the `i64` / `u32` wide-integer ladder); a scalar
/// `7i32` becomes `integer(1)` and a `Vec<i32>` becomes `integer(n)`. Any
/// `T: Debug` rides along via [`RValue::debug`](crate::RValue::debug). For
/// nested lists or complex/raw values build an [`RValue`](crate::RValue)
/// directly.
pub type ConditionData = Vec<(String, crate::RValue)>;

// endregion

// region: ConditionCall — whether a condition reports a call

/// Whether a condition reports a call (`conditionCall()`): the per-condition
/// equivalent of R's `warning(..., call. = FALSE)` / `stop(..., call. = FALSE)`.
///
/// Every condition a `#[miniextendr]` function raises carries the call its
/// transport captured: the wrapper's call as written (or the caller's, under
/// `call = caller`), `NULL` in ALTREP and connection callbacks. A condition
/// about the data rather than the call opts out with [`ConditionCall::None`];
/// its siblings from the same function keep their call.
///
/// Spellings: `call = none` first in [`crate::warning!`], [`crate::error!`],
/// [`crate::condition!`] and the `defer_*!` macros;
/// [`RError::without_call`]; `#[condition(call = none)]` on a
/// `#[derive(RCondition)]` type or variant; or an
/// [`RConditionData::call`] impl.
///
/// On the tagged condition value the choice is the `call` slot itself:
/// `FALSE` for [`ConditionCall::None`], read back by the R helper (and by the
/// trait-ABI re-panic, [`RCondition::from_tagged_sexp`]) as "no call".
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ConditionCall {
    /// The call the transport captured (the default).
    #[default]
    Inherit,
    /// No call: `conditionCall()` is `NULL` and the printed condition has no
    /// `In f(...) :` prefix.
    None,
}

impl ConditionCall {
    /// `call` when the condition keeps its call, `None` otherwise: the call to
    /// hand a transport that takes the R call object directly.
    #[inline]
    pub fn apply(self, call: Option<crate::SEXP>) -> Option<crate::SEXP> {
        match self {
            ConditionCall::Inherit => call,
            ConditionCall::None => Option::None,
        }
    }
}

// endregion

// region: RCondition enum — structured condition payload

/// Owned payload for structured R conditions.
///
/// `#[derive(RCondition)]` gives a struct or enum a conversion into this
/// payload. Its `#[condition(kind = warning)]` (or `error` / `message` /
/// `condition`) chooses the signal; an enum variant can override the kind.
/// Convert with `RCondition::from(value)`, then call [`defer`](Self::defer)
/// to accompany a return value, or [`raise`](Self::raise) to leave Rust.
///
/// Raised by the `error!()`, `warning!()`, `message!()`, and `condition!()`
/// macros via `std::panic::panic_any`. Caught by `with_r_unwind_protect`
/// before the generic panic→string path and forwarded to R as a tagged SEXP
/// with `rust_*` class layering. The `defer_*` family
/// ([`crate::deferred_condition`]) queues the same payloads instead of
/// panicking, so the call still returns its value.
///
/// Every variant carries the same four parts: the message, the user classes
/// (prepended to the `rust_*` layering, empty for none), the optional `data`
/// fields and the [`ConditionCall`] choice. All four are owned and `Send`, so
/// the payload can be queued from a worker thread. Each variant is one kind
/// of the tagged condition value ([`crate::error_value::kind`]).
#[derive(Debug)]
pub enum RCondition {
    /// Raised by `error!(...)` / `error!(class = "...", ...)`, and by the
    /// `Result<T, E>` Err arm once reconstructed across a package boundary.
    Error {
        /// Human-readable condition message.
        message: String,
        /// User classes, most specific first, before the framework's classes.
        class: Vec<String>,
        /// Named fields attached to the R condition.
        data: Option<ConditionData>,
        /// Call attribution policy; messages always omit the call.
        call: ConditionCall,
    },
    /// Raised by `warning!(...)` / `warning!(class = "...", ...)`.
    Warning {
        /// Human-readable condition message.
        message: String,
        /// User classes, most specific first, before the framework's classes.
        class: Vec<String>,
        /// Named fields attached to the R condition.
        data: Option<ConditionData>,
        /// Call attribution policy; messages always omit the call.
        call: ConditionCall,
    },
    /// Raised by `message!(...)`, and queued by [`crate::defer_message()`]. Only
    /// the typed-payload path fills `class` (the macro has no `class =` form);
    /// the R helper layers it in front of `rust_message` like the other kinds.
    /// A message never reports a call, whatever `call` says.
    Message {
        /// Human-readable condition message.
        message: String,
        /// User classes, most specific first, before the framework's classes.
        class: Vec<String>,
        /// Named fields attached to the R condition.
        data: Option<ConditionData>,
        /// Call attribution policy; messages always omit the call.
        call: ConditionCall,
    },
    /// Raised by `condition!(...)` / `condition!(class = "...", ...)`.
    Condition {
        /// Human-readable condition message.
        message: String,
        /// User classes, most specific first, before the framework's classes.
        class: Vec<String>,
        /// Named fields attached to the R condition.
        data: Option<ConditionData>,
        /// Call attribution policy; messages always omit the call.
        call: ConditionCall,
    },
    /// An argument error, `kind = "conversion"`: raised by
    /// [`crate::arg_error!`] / [`ArgError::raise`] (built by
    /// [`RCondition::arg_error`]), and a failed argument conversion once
    /// reconstructed across a package boundary.
    Conversion {
        /// Human-readable condition message.
        message: String,
        /// User classes, most specific first, before the framework's classes.
        class: Vec<String>,
        /// Named fields attached to the R condition.
        data: Option<ConditionData>,
        /// Call attribution policy; messages always omit the call.
        call: ConditionCall,
    },
}

impl RCondition {
    /// Leave the current Rust body with this condition.
    ///
    /// The enclosing miniextendr guard forwards it to R with its kind and
    /// metadata intact. Like `warning!`, raising a warning still exits Rust:
    /// muffling it in R does not resume this Rust body. Use [`defer`](Self::defer)
    /// to keep computing and return a value.
    pub fn raise(self) -> ! {
        std::panic::panic_any(self)
    }

    /// Queue this condition until the current guarded call returns.
    ///
    /// Preserves its declared kind, classes, fields and call policy, including
    /// for a mixed-kind enum. Errors queued here stop R at that boundary.
    pub fn defer(self) {
        crate::deferred_condition::defer(self);
    }

    /// Split into the kind (one of [`crate::error_value::kind`]) and the
    /// [`ErrParts`] (message, class, data, call choice) that
    /// [`crate::error_value::condition_parts_value`] builds the tagged value
    /// from.
    #[doc(hidden)]
    pub fn into_parts(self) -> (&'static str, ErrParts) {
        use crate::error_value::kind;
        let (kind, message, class, data, call) = match self {
            RCondition::Error {
                message,
                class,
                data,
                call,
            } => (kind::ERROR, message, class, data, call),
            RCondition::Warning {
                message,
                class,
                data,
                call,
            } => (kind::WARNING, message, class, data, call),
            RCondition::Message {
                message,
                class,
                data,
                call,
            } => (kind::MESSAGE, message, class, data, call),
            RCondition::Condition {
                message,
                class,
                data,
                call,
            } => (kind::CONDITION, message, class, data, call),
            RCondition::Conversion {
                message,
                class,
                data,
                call,
            } => (kind::CONVERSION, message, class, data, call),
        };
        (
            kind,
            ErrParts {
                message,
                class,
                data,
                call,
            },
        )
    }

    /// The condition message, as `conditionMessage()` would read it in R.
    ///
    /// Use it on a condition [`catch_condition`] caught or
    /// [`capture`](crate::deferred_condition::capture) collected, for example
    /// to put a cause's text into a new message.
    pub fn message(&self) -> &str {
        match self {
            RCondition::Error { message, .. }
            | RCondition::Warning { message, .. }
            | RCondition::Message { message, .. }
            | RCondition::Condition { message, .. }
            | RCondition::Conversion { message, .. } => message,
        }
    }

    /// This condition with `parent` as its cause, as `rlang::abort(parent = )`
    /// chains conditions.
    ///
    /// R gets the cause as the field `e$parent`: a condition object with its
    /// own classes, message and fields (and its own parent, if it has one),
    /// built like the condition itself but not signalled. The cause's classes
    /// stay out of this condition's class vector, so a handler written for
    /// the cause's class does not catch this condition; code that wants the
    /// cause branches on it: `inherits(e$parent, "pkg_error_config")`.
    ///
    /// The cause reports the same call as this condition, or none when it was
    /// raised with `call = none`. A second `with_parent` replaces the first,
    /// and the cause replaces a `data` field this condition names `parent`.
    ///
    /// ```ignore
    /// match catch_condition(|| rebuild(&saved)) {
    ///     Ok(value) => value,
    ///     Err(cause) => RCondition::Error {
    ///         message: format!("could not rebuild: {}", cause.message()),
    ///         class: vec!["pkg_error_rebuild".into()],
    ///         data: None,
    ///         call: ConditionCall::Inherit,
    ///     }
    ///     .with_parent(cause)
    ///     .raise(),
    /// }
    /// ```
    pub fn with_parent(mut self, parent: RCondition) -> Self {
        let encoded = parent.into_tagged_rvalue();
        let data = match &mut self {
            RCondition::Error { data, .. }
            | RCondition::Warning { data, .. }
            | RCondition::Message { data, .. }
            | RCondition::Condition { data, .. }
            | RCondition::Conversion { data, .. } => data,
        };
        let fields = data.get_or_insert_with(Vec::new);
        fields.retain(|(name, _)| name != PARENT_FIELD);
        fields.push((PARENT_FIELD.to_owned(), encoded));
        self
    }

    /// The condition as the tagged value the R raise helper reads (`error`,
    /// `kind`, `class`, `call`, `data`), in [`RValue`](crate::RValue) form so
    /// it can travel inside another condition's data ([`Self::with_parent`]).
    fn into_tagged_rvalue(self) -> crate::RValue {
        use crate::RValue;
        let (kind, parts) = self.into_parts();
        let text = |value: String| RValue::Character(vec![Some(value)]);
        let class = if parts.class.is_empty() {
            RValue::Null
        } else {
            RValue::Character(parts.class.into_iter().map(Some).collect())
        };
        let call = match parts.call {
            ConditionCall::Inherit => RValue::Null,
            ConditionCall::None => RValue::Logical(vec![Some(false)]),
        };
        let data = parts.data.map_or(RValue::Null, |fields| {
            RValue::List(
                fields
                    .into_iter()
                    .map(|(name, value)| (Some(name), value))
                    .collect(),
            )
        });
        RValue::List(vec![
            (Some("error".to_owned()), text(parts.message)),
            (Some("kind".to_owned()), text(kind.to_owned())),
            (Some("class".to_owned()), class),
            (Some("call".to_owned()), call),
            (Some("data".to_owned()), data),
        ])
    }

    /// Which call the condition reports when R raises it: see
    /// [`ConditionCall`].
    pub fn call(&self) -> ConditionCall {
        match self {
            RCondition::Error { call, .. }
            | RCondition::Warning { call, .. }
            | RCondition::Message { call, .. }
            | RCondition::Condition { call, .. }
            | RCondition::Conversion { call, .. } => *call,
        }
    }

    /// The payload of [`crate::arg_error!`] and [`ArgError::raise`]: the
    /// argument error of parameter `param` (its R name) with `message`.
    ///
    /// `kind = "conversion"`, `e$param` as the only data field, and the class
    /// [`CONVERSION_ERROR_CLASS_MARKER`], which the generated R replaces with
    /// the crate's `conversion_error_class`: the condition the wrapper's own
    /// argument checks raise (`.miniextendr_arg_error`).
    #[doc(hidden)]
    pub fn arg_error(param: impl Into<String>, message: String, call: ConditionCall) -> Self {
        RCondition::Conversion {
            message,
            class: vec![CONVERSION_ERROR_CLASS_MARKER.to_string()],
            data: Some(vec![(
                CONVERSION_PARAM_FIELD.to_string(),
                crate::RValue::from(param.into()),
            )]),
            call,
        }
    }
}

/// The class that stands for the crate's `conversion_error_class` in a tagged
/// condition value (#1740).
///
/// A `macro_rules!` macro cannot read `[package.metadata.miniextendr]`, so
/// [`crate::arg_error!`] cannot name the crate's classes the way the
/// generated conversion arms do. It writes this class instead, and the
/// generated R wrapper's `.miniextendr_raise_condition` replaces it with
/// `.miniextendr_conversion_error_class`, the binding its own argument checks
/// read. The string is that binding's name. Where no generated wrapper raises
/// the condition (a raising guard: an ALTREP `RUnwind` callback,
/// [`crate::unwind_protect::with_r_unwind_protect_or_raise`]) Rust replaces it
/// with the classes `miniextendr_init!` registered for the package
/// ([`resolve_conversion_error_class_marker`]).
#[doc(hidden)]
pub const CONVERSION_ERROR_CLASS_MARKER: &str = ".miniextendr_conversion_error_class";

/// `class` with [`CONVERSION_ERROR_CLASS_MARKER`] replaced by `crate_classes`,
/// in place, as the generated `.miniextendr_raise_condition` replaces it in R.
/// A raising guard has no generated R to do it, so it calls this with
/// [`crate_conversion_error_class`].
pub(crate) fn resolve_conversion_error_class_marker(
    class: Vec<String>,
    crate_classes: &[&str],
) -> Vec<String> {
    let mut resolved = Vec::with_capacity(class.len() + crate_classes.len());
    for c in class {
        if c == CONVERSION_ERROR_CLASS_MARKER {
            resolved.extend(crate_classes.iter().map(|&k| k.to_string()));
        } else {
            resolved.push(c);
        }
    }
    resolved
}

/// The package crate's `conversion_error_class`, from the entry
/// `miniextendr_init!` registers in
/// [`MX_CONVERSION_ERROR_CLASS`](crate::registry::MX_CONVERSION_ERROR_CLASS)
/// (each package links its own copy of this crate, so it is that package's),
/// or on wasm32 from the `wasm_registry.rs` snapshot (#1768). Empty when the
/// crate sets none.
pub(crate) fn crate_conversion_error_class() -> &'static [&'static str] {
    crate::registry::conversion_error_class()
}

/// Run `f`, returning a condition raised inside it as `Err` instead of
/// letting it reach R; any other unwind carries on.
///
/// For a body that turns another function's failure into its own result: a
/// refusal that names the reason, a fallback, a retry.
///
/// ```ignore
/// use miniextendr_api::condition::catch_condition;
///
/// match catch_condition(|| rebuild(&snapshot)) {
///     Ok(object) => object,
///     Err(cause) => error!(
///         class = "pkg_error_rebuild",
///         data = ("cause", cause.message().to_string()),
///         "cannot rebuild the object: {}", cause.message()
///     ),
/// }
/// ```
///
/// **Caught:** every [`RCondition`](enum@RCondition) payload, with its kind, classes, data
/// and call choice: [`error!`](crate::error!) / [`rust_error!`](crate::rust_error!),
/// [`warning!`](crate::warning!), [`message!`](crate::message!),
/// [`condition!`](crate::condition!), [`RCondition::raise`], the argument and
/// conversion errors ([`RCondition::arg_error`]) and the `ExternalPtr` type
/// errors. An `Err` can be raised again with [`RCondition::raise`] or queued
/// with [`RCondition::defer`].
///
/// **Resumed** unchanged, with [`std::panic::resume_unwind`]:
/// - an R error, interrupt or other R exit crossing the Rust frames (R code
///   run through [`with_r_unwind_protect`](crate::unwind_protect::with_r_unwind_protect)
///   or [`eval_with_handlers`](crate::expression::eval_with_handlers)), so
///   R carries on to the context it was jumping to;
/// - a plain `panic!()` or any other payload, which still becomes an R error
///   at the boundary, with its source location.
///
/// Use [`try_eval_with_handlers`](crate::expression::try_eval_with_handlers)
/// to get an R error back as a value.
///
/// Deferred conditions queued inside `f` stay queued (see
/// [`deferred_condition::capture`](crate::deferred_condition::capture)). A
/// caught raise still runs the panic hook: with `MINIEXTENDR_BACKTRACE=true`
/// it prints the panic to stderr.
///
/// Generated `#[miniextendr(worker)]` wrappers run the body through it on the
/// worker thread: the payload is `Send`, so it crosses back to the main
/// thread as a value and is raised there with its class, data and call kept.
pub fn catch_condition<T>(f: impl FnOnce() -> T) -> Result<T, RCondition> {
    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)) {
        Ok(value) => Ok(value),
        Err(payload) => match payload.downcast::<RCondition>() {
            Ok(condition) => Err(*condition),
            Err(payload) => std::panic::resume_unwind(payload),
        },
    }
}

// endregion

// region: Macros

/// Internal: one condition-data field name, validated against the reserved
/// slots. Not part of the public API.
///
/// - `lit "name"` / `ident name`: the name is a literal, so the reserved-name
///   check runs at compile time (`const` assertion) and the field costs one
///   `to_string()` at runtime.
/// - `expr <e>`: a computed name; checked at runtime by
///   [`crate::condition::check_condition_field_name`].
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_condition_field_name {
    (lit $name:literal) => {{
        const _: () = ::core::assert!(
            !$crate::condition::is_reserved_condition_field($name),
            "condition data field name is reserved: `message`, `call` and `kind` are the condition's own slots, and `.mx_parent` carries its parent; rename the field"
        );
        ($name).to_string()
    }};
    (ident $name:ident) => {{
        const _: () = ::core::assert!(
            !$crate::condition::is_reserved_condition_field(::core::stringify!($name)),
            "condition data field name is reserved: `message`, `call` and `kind` are the condition's own slots, and `.mx_parent` carries its parent; rename the field"
        );
        ::core::stringify!($name).to_string()
    }};
    (expr $name:expr) => {
        $crate::condition::check_condition_field_name(($name).to_string())
    };
}

/// Internal: one `(name, value)` pair of a bracketed `data = [...]` list; the
/// name goes through the reserved-slot check (compile time for literals).
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_condition_pair {
    (($name:literal, $value:expr $(,)?)) => {
        ($crate::__mx_condition_field_name!(lit $name), $crate::RValue::from($value))
    };
    (($name:expr, $value:expr $(,)?)) => {
        ($crate::__mx_condition_field_name!(expr $name), $crate::RValue::from($value))
    };
}

/// Internal: normalise a macro `data = ...` argument into
/// `Option<ConditionData>`. Not part of the public API.
///
/// Three forms are accepted:
/// - a single pair: `("name", value)`
/// - a bracketed list of pairs: `[("a", v1), ("b", v2)]`
/// - keyed builder sugar: `{ name = value, other = value }` — the field name is
///   a bare identifier (stringified by the macro), so `{ value = 42, code = 7 }`
///   is shorthand for `[("value", 42), ("code", 7)]`.
///
/// Each `value` is converted via `RValue::from`, so any type with an `RValue`
/// `From` impl (the scalar/vector/`Option`/wide-integer set, and tuples of
/// those as unnamed lists) works without ceremony.
///
/// Field names are checked against the condition's own slots (`message` /
/// `call` / `kind`): at compile time when the name is a literal or bare
/// identifier, at runtime otherwise.
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_condition_data {
    (($name:literal, $value:expr $(,)?)) => {
        ::std::option::Option::Some(::std::vec![(
            $crate::__mx_condition_field_name!(lit $name),
            $crate::RValue::from($value),
        )])
    };
    (($name:expr, $value:expr $(,)?)) => {
        ::std::option::Option::Some(::std::vec![(
            $crate::__mx_condition_field_name!(expr $name),
            $crate::RValue::from($value),
        )])
    };
    ([ $($pair:tt),* $(,)? ]) => {
        ::std::option::Option::Some(::std::vec![
            $( $crate::__mx_condition_pair!($pair), )*
        ])
    };
    ({ $($name:ident = $value:expr),* $(,)? }) => {
        ::std::option::Option::Some(::std::vec![
            $(
                (
                    $crate::__mx_condition_field_name!(ident $name),
                    $crate::RValue::from($value),
                ),
            )*
        ])
    };
}

/// Internal: parse the shared option grid of `error!` / `warning!` /
/// `condition!` and the `defer_*!` macros into `(call, class, data, message)`.
/// Not part of the public API.
///
/// Accepted orders (every part optional except the message):
/// `call = none`, then `class = ..`, then `data = ..`, then the `format!`
/// arguments. `class` takes anything implementing
/// [`crate::condition::ConditionClass`] (one string or several). A `call`
/// other than `none`, or one after `class` / `data`, is a compile error: a
/// `format!` string must start with a literal, so `call` as the first token is
/// never a message.
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::warning!(call = wrapper, "no such call option");
/// # }
/// ```
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::warning!(class = "pkg_warning", call = none, "`call` goes first");
/// # }
/// ```
///
/// ```
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::warning!(call = none, class = "pkg_warning", data = { n = 1 }, "plain");
/// # }
/// ```
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_condition_parts {
    // The option grid after the `call` choice: `(class, data, message)`.
    (@options class = $class:expr, call $($rest:tt)*) => {
        $crate::__mx_condition_parts!(@misplaced_call)
    };
    (@options class = $class:expr, data = $data:tt, call $($rest:tt)*) => {
        $crate::__mx_condition_parts!(@misplaced_call)
    };
    (@options data = $data:tt, call $($rest:tt)*) => {
        $crate::__mx_condition_parts!(@misplaced_call)
    };
    (@options class = $class:expr, data = $data:tt, $($arg:tt)*) => {
        (
            $crate::condition::ConditionClass::into_condition_class($class),
            $crate::__mx_condition_data!($data),
            ::std::format!($($arg)*),
        )
    };
    (@options data = $data:tt, $($arg:tt)*) => {
        (
            ::std::vec::Vec::<::std::string::String>::new(),
            $crate::__mx_condition_data!($data),
            ::std::format!($($arg)*),
        )
    };
    (@options class = $class:expr, $($arg:tt)*) => {
        (
            $crate::condition::ConditionClass::into_condition_class($class),
            ::std::option::Option::<$crate::condition::ConditionData>::None,
            ::std::format!($($arg)*),
        )
    };
    (@options $($arg:tt)*) => {
        (
            ::std::vec::Vec::<::std::string::String>::new(),
            ::std::option::Option::<$crate::condition::ConditionData>::None,
            ::std::format!($($arg)*),
        )
    };
    (@options call $($rest:tt)*) => {
        ::core::compile_error!("condition macros: `call = none` is given twice")
    };
    (@misplaced_call) => {
        ::core::compile_error!(
            "condition macros: `call = none` comes first, before `class = ...` and `data = ...`: \
             `warning!(call = none, class = \"...\", \"...\")`"
        )
    };
    // Entry: the optional `call = none`, then the option grid.
    (call = none, $($rest:tt)+) => {{
        let (__mx_class, __mx_data, __mx_message) =
            $crate::__mx_condition_parts!(@options $($rest)+);
        (
            $crate::condition::ConditionCall::None,
            __mx_class,
            __mx_data,
            __mx_message,
        )
    }};
    (call $($rest:tt)*) => {
        ::core::compile_error!(
            "condition macros: the only call option is `call = none` (no call, like R's \
             `call. = FALSE`), and it comes first, followed by a comma: \
             `warning!(call = none, \"...\")`"
        )
    };
    ($($rest:tt)*) => {{
        let (__mx_class, __mx_data, __mx_message) =
            $crate::__mx_condition_parts!(@options $($rest)*);
        (
            $crate::condition::ConditionCall::Inherit,
            __mx_class,
            __mx_data,
            __mx_message,
        )
    }};
}

/// Raise an R error from Rust with `rust_error` class layering.
///
/// Rides the tagged-condition transport that every `#[miniextendr]` function uses.
/// The raised condition has class `c("rust_error", "simpleError", "error", "condition")`.
///
/// An optional `class = "name"` form prepends a custom class for programmatic catching:
/// `c("name", "rust_error", "simpleError", "error", "condition")`. `class` also
/// takes a vector (`class = ["pkg_error_missing_field", "pkg_error"]`, or any
/// [`ConditionClass`] value) so handlers can catch the family or the member.
///
/// The framework layers (`rust_error`, `simpleError`, `error`, `condition`)
/// always follow the user classes; no option leaves them out. Handlers and
/// `inherits()` see the user classes as on an R `errorCondition()`; a test
/// that compares the whole class vector with an R implementation's compares
/// the leading classes instead.
///
/// # Structured `data = ...` payloads
///
/// An optional `data = ...` form (after `class`, before the message) attaches
/// named fields to the condition object, rlang-`abort()`-style. Handlers read
/// them as `e$<name>` instead of parsing the message string:
///
/// ```ignore
/// // Single field:
/// mx::error!(class = "range_error", data = ("value", value), "value {value} out of range");
///
/// // Multiple fields (bracketed list of pairs):
/// mx::error!(
///     class = "validation_error",
///     data = [("value", value), ("min", 0), ("max", 100)],
///     "value {value} out of range"
/// );
///
/// // Keyed builder sugar (bare-ident keys, stringified by the macro):
/// mx::error!(
///     class = "validation_error",
///     data = { value = value, min = 0, max = 100 },
///     "value {value} out of range"
/// );
/// ```
///
/// ```r
/// tryCatch(validate(150L), validation_error = function(e) c(e$value, e$min, e$max))
/// # [1] 150   0 100
/// ```
///
/// Argument order is fixed: `call = none` (optional), then `class = ...`
/// (optional), then `data = ...` (optional), then the format message.
///
/// Field names `message`, `call` and `kind` are the condition's own slots and
/// are rejected (at compile time for literal / bare-identifier names, at
/// runtime otherwise); give the field another name (`rule` instead of `kind`,
/// say). A downstream error type with such a field renames it where the
/// payload is built (`#[serde(rename)]`, a different key).
///
/// **Supported value types**: scalars and `Vec`s of `i32`, `f64`, `bool`, and
/// `String` (plus `&str` / `Vec<&str>`, converted to owned); their NA-aware
/// `Option` / `Vec<Option<_>>` forms (→ R `NA`); the wide-integer ladder (`i64`
/// / `u32`); and the [`RValue::debug`](crate::RValue::debug) escape hatch for
/// any `T: Debug`. The payload must be `Send` — it travels through `panic_any`
/// and may cross the worker→main thread boundary, so live `SEXP`s cannot ride
/// along; the R objects are materialised on the main thread at the unwind
/// boundary. For nested lists or complex/raw values build an
/// [`RValue`](crate::RValue) directly.
///
/// # Conditions without a call
///
/// A leading `call = none` raises the condition with no call, like R's
/// `stop(..., call. = FALSE)`: `conditionCall(e)` is `NULL` and the error
/// prints as `Error: <message>` instead of `Error in f(...) : <message>`. Use
/// it for a condition about the data rather than about the call. Classes and
/// `data` are unchanged:
///
/// ```ignore
/// mx::error!(call = none, class = "pkg_bad_row", data = { row = row }, "row {row} is malformed");
/// ```
///
/// The same marker exists as [`RError::without_call`] for `Result` errors and
/// as `#[condition(call = none)]` on a `#[derive(RCondition)]` type or
/// variant; see [`ConditionCall`].
///
/// # See also
///
/// - [`crate::warning!`] / [`crate::message!`] / [`crate::condition!`] — the
///   non-error sibling kinds (warning continues execution; message is muffled
///   by `suppressMessages`; condition is silent without a handler).
/// - [`std::panic!`] — escape hatch with the same `rust_error` class layering
///   but no custom-class slot. Use for true bugs / impossible states; reach for
///   `error!` when callers might want to route by class.
/// - [`AsRError`] — wraps `Result<_, E: std::error::Error>` for value-style
///   propagation through Rust code; converts at the boundary.
/// - [`crate::error_value`] — module-level rationale for the tagged-SEXP
///   transport and the `error_in_r` default.
///
/// **Name-collision note.** Because `pub mod error` exists at the crate root,
/// `use miniextendr_api::error` imports the module rather than this macro, and
/// glob imports (`use miniextendr_api::*;`) hit the same shadow. Prefer the
/// collision-free alias [`crate::rust_error!`], which has the identical
/// expansion; otherwise invoke via `miniextendr_api::error!(...)` (fully
/// qualified) or `mx::error!(...)` after `use miniextendr_api as mx;`.
///
/// # Examples
///
/// ```ignore
/// use miniextendr_api as mx;
///
/// #[miniextendr]
/// fn fail() {
///     mx::error!("something went wrong: {}", 42);
/// }
///
/// // With a custom class for tryCatch:
/// #[miniextendr]
/// fn typed_fail(name: &str) {
///     mx::error!(class = "my_error", "missing field: {name}");
/// }
/// ```
///
/// ```r
/// tryCatch(fail(), rust_error = function(e) conditionMessage(e))
/// # [1] "something went wrong: 42"
///
/// tryCatch(typed_fail("x"), my_error = function(e) "caught!")
/// # [1] "caught!"
/// ```
#[macro_export]
macro_rules! error {
    ($($t:tt)*) => {{
        let (__mx_call, __mx_class, __mx_data, __mx_message) =
            $crate::__mx_condition_parts!($($t)*);
        ::std::panic::panic_any($crate::condition::RCondition::Error {
            message: __mx_message,
            class: __mx_class,
            data: __mx_data,
            call: __mx_call,
        })
    }};
}

/// Collision-free alias for [`crate::error!`].
///
/// Identical expansion and grammar (`call = none`, `class = …`, `data = …`,
/// and the plain `format!` forms) — it exists so that `use miniextendr_api::*;` or
/// `use miniextendr_api::rust_error;` gives you a usable macro name. The bare
/// `error!` name is shadowed at the crate root by `pub mod error` (see the
/// name-collision note on [`crate::error!`]), so a glob or direct import
/// resolves to the module, not the macro. `rust_error!` has no such clash.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::rust_error;
///
/// #[miniextendr]
/// fn typed_fail(name: &str) {
///     rust_error!(class = "my_error", "missing field: {name}");
/// }
/// ```
#[macro_export]
macro_rules! rust_error {
    ($($t:tt)*) => { $crate::error!($($t)*) };
}

/// Raise an R warning from Rust with `rust_warning` class layering.
///
/// Rides the tagged-condition transport that every `#[miniextendr]` function uses.
/// Unlike `panic!`, execution continues after `warning!` is caught by a handler.
/// The raised condition has class `c("rust_warning", "simpleWarning", "warning", "condition")`.
///
/// An optional `class = "name"` form prepends a custom class. An optional
/// `data = ...` form (after `class`, before the message) attaches named fields
/// readable as `w$<name>` in handlers — same grammar and supported value types
/// as [`crate::error!`] (see there for details):
///
/// ```ignore
/// warning!(class = "truncation", data = ("dropped", n), "dropped {n} rows");
/// ```
///
/// A leading `call = none` raises the warning without a call, like R's
/// `warning(..., call. = FALSE)`: `conditionCall(w)` is `NULL` and the
/// printed warning has no `In f(...) :` prefix. Use it for a warning about the
/// data rather than about the call (see
/// [conditions without a call](crate::error!#conditions-without-a-call)):
///
/// ```ignore
/// warning!(call = none, class = "pkg_override", data = { row = row }, "row {row} overrides an earlier row");
/// ```
///
/// # See also
///
/// - [`crate::error!`] — fatal sibling; aborts the call instead of continuing.
/// - [`crate::defer_warning!`] / [`crate::defer_warning()`] — queue the warning
///   and still return the value (signalled when the call returns).
/// - [`crate::message!`] / [`crate::condition!`] — softer signal kinds (muffled
///   by `suppressMessages` / silent without handler, respectively).
/// - [`std::panic!`] — escape hatch when "continue after this" is not a sensible
///   semantic.
/// - [`crate::error_value`] — tagged-SEXP transport rationale.
///
/// No name-collision caveat: there is no `pub mod warning`, so
/// `use miniextendr_api::warning;` then `warning!(...)` works directly.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::warning;
///
/// #[miniextendr]
/// fn maybe_warn(x: i32) -> i32 {
///     if x > 100 {
///         warning!("x is large: {x}");
///     }
///     x * 2
/// }
/// ```
///
/// ```r
/// withCallingHandlers(
///   maybe_warn(200L),
///   warning = function(w) { cat("saw:", conditionMessage(w)); invokeRestart("muffleWarning") }
/// )
/// # saw: x is large: 200
/// # [1] 400
/// ```
#[macro_export]
macro_rules! warning {
    ($($t:tt)*) => {{
        let (__mx_call, __mx_class, __mx_data, __mx_message) =
            $crate::__mx_condition_parts!($($t)*);
        ::std::panic::panic_any($crate::condition::RCondition::Warning {
            message: __mx_message,
            class: __mx_class,
            data: __mx_data,
            call: __mx_call,
        })
    }};
}

/// Emit an R message from Rust with `rust_message` class layering.
///
/// Rides the tagged-condition transport that every `#[miniextendr]` function uses.
/// The raised condition has class `c("rust_message", "simpleMessage", "message", "condition")`.
/// Muffled by `suppressMessages()` automatically (standard R restart mechanism).
///
/// An optional `data = ...` form (before the message) attaches named fields
/// readable as `m$<name>` in `withCallingHandlers` — same grammar and
/// supported value types as [`crate::error!`] (see there for details). There
/// is no `class =` form for `message!`, and no `call =` form: an R message
/// carries no call (`conditionCall(m)` is `NULL`), so there is nothing to drop.
///
/// # See also
///
/// - [`crate::warning!`] / [`crate::condition!`] — louder/quieter sibling kinds.
/// - [`crate::error!`] — for fatal failures.
/// - [`std::panic!`] — escape hatch.
/// - [`crate::error_value`] — tagged-SEXP transport rationale.
///
/// No name-collision caveat: there is no `pub mod message`, so
/// `use miniextendr_api::message;` then `message!(...)` works directly.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::message;
///
/// #[miniextendr]
/// fn log_step(step: i32) {
///     message!("step {} complete", step);
/// }
/// ```
///
/// ```r
/// log_step(3L)
/// # step 3 complete
///
/// suppressMessages(log_step(3L))  # no output
/// ```
#[macro_export]
macro_rules! message {
    (call $($rest:tt)*) => {
        ::core::compile_error!(
            "message!: there is no `call` option, an R message carries no call"
        )
    };
    (data = $data:tt, $($arg:tt)*) => {
        ::std::panic::panic_any($crate::condition::RCondition::Message {
            message: ::std::format!($($arg)*),
            class: ::std::vec::Vec::new(),
            data: $crate::__mx_condition_data!($data),
            call: $crate::condition::ConditionCall::Inherit,
        })
    };
    ($($arg:tt)*) => {
        ::std::panic::panic_any($crate::condition::RCondition::Message {
            message: ::std::format!($($arg)*),
            class: ::std::vec::Vec::new(),
            data: ::std::option::Option::None,
            call: $crate::condition::ConditionCall::Inherit,
        })
    };
}

/// Signal a generic R condition from Rust with `rust_condition` class layering.
///
/// Rides the tagged-condition transport that every `#[miniextendr]` function uses.
/// Unlike `error!`, a bare condition is a silent no-op if there is no handler.
/// The raised condition has class `c("rust_condition", "simpleCondition", "condition")`.
///
/// An optional `class = "name"` form prepends a custom class. An optional
/// `data = ...` form (after `class`, before the message) attaches named fields
/// readable as `c$<name>` in handlers — same grammar and supported value types
/// as [`crate::error!`] (see there for details). A leading `call = none`
/// signals the condition without a call (`conditionCall(c)` is `NULL`), like
/// [`crate::error!`]'s.
///
/// # See also
///
/// - [`crate::error!`] / [`crate::warning!`] / [`crate::message!`] — louder
///   condition kinds. Pick `condition!` when "no handler = silent" is the
///   right default (progress events, structured logging hooks).
/// - [`std::panic!`] — escape hatch when the failure cannot be ignored.
/// - [`crate::error_value`] — tagged-SEXP transport rationale.
///
/// **Name-collision note.** Because `pub mod condition` exists at the crate
/// root, `use miniextendr_api::condition` imports the module rather than this
/// macro, and glob imports (`use miniextendr_api::*;`) hit the same shadow.
/// Prefer the collision-free alias [`crate::rust_condition!`], which has the
/// identical expansion; otherwise invoke via `miniextendr_api::condition!(...)`
/// (fully qualified) or `mx::condition!(...)` after `use miniextendr_api as mx;`.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::condition;
///
/// #[miniextendr]
/// fn signal_progress(n: i32) {
///     condition!(class = "my_progress", "processed {n} items");
/// }
/// ```
///
/// ```r
/// withCallingHandlers(
///   signal_progress(42L),
///   my_progress = function(c) cat("progress:", conditionMessage(c), "\n")
/// )
/// # progress: processed 42 items
/// ```
#[macro_export]
macro_rules! condition {
    ($($t:tt)*) => {{
        let (__mx_call, __mx_class, __mx_data, __mx_message) =
            $crate::__mx_condition_parts!($($t)*);
        ::std::panic::panic_any($crate::condition::RCondition::Condition {
            message: __mx_message,
            class: __mx_class,
            data: __mx_data,
            call: __mx_call,
        })
    }};
}

/// Collision-free alias for [`crate::condition!`].
///
/// Identical expansion and grammar (`call = none`, `class = …`, `data = …`,
/// and the plain `format!` forms) — it exists so that `use miniextendr_api::*;` or
/// `use miniextendr_api::rust_condition;` gives you a usable macro name. The
/// bare `condition!` name is shadowed at the crate root by `pub mod condition`
/// (see the name-collision note on [`crate::condition!`]), so a glob or direct
/// import resolves to the module, not the macro. `rust_condition!` has no such
/// clash.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::rust_condition;
///
/// #[miniextendr]
/// fn signal_progress(n: i32) {
///     rust_condition!(class = "my_progress", "processed {n} items");
/// }
/// ```
#[macro_export]
macro_rules! rust_condition {
    ($($t:tt)*) => { $crate::condition!($($t)*) };
}

/// Raise the argument error the generated R wrapper raises for a bad
/// argument, from a `#[miniextendr]` function body.
///
/// `arg_error!(param = "mode", "'mode' should be one of {}", choices)` raises
/// the condition of the wrapper's own argument checks (`match_arg`,
/// `inherits`, `no_na`, type preconditions) and of a failed argument
/// conversion: `kind = "conversion"`, `e$param` set to `param` (the
/// argument's R name), the message as formatted, and the crate's
/// `conversion_error_class` (`[package.metadata.miniextendr]`) before the
/// `rust_error` layering:
///
/// ```r
/// class(e)
/// # [1] "pkg_error_argument" "pkg_error" "rust_error" "simpleError" "error" "condition"
/// ```
///
/// Use it for a check that applies on some paths only, where a
/// `#[miniextendr]` attribute on the parameter would check every call: an
/// argument passed on to another function's body, say, which skips that
/// function's R wrapper and its checks. [`crate::match_arg_param`] matches a
/// raw choice argument with the wrapper's semantics and message and raises
/// through this macro.
///
/// It diverges like [`crate::error!`] (the same `panic_any` transport), and
/// conditions queued with [`crate::defer_warning!`] & co. are signalled first.
/// The call is the one the wrapper's checks report: the wrapper's call as
/// written, or under `#[miniextendr(call = caller)]` its caller's. A leading
/// `call = none` raises it without a call, as for the other condition macros.
/// There is no `class =` or `data =`: the classes are the crate's and the only
/// field is `param`, so the condition is the wrapper's.
///
/// ```ignore
/// use miniextendr_api::{arg_error, miniextendr};
///
/// #[miniextendr]
/// pub fn in_metres(x: f64, unit: &str) -> f64 {
///     match unit {
///         "m" => x,
///         "cm" => x / 100.0,
///         _ => arg_error!(param = "unit", "'unit' should be one of \"m\", \"cm\""),
///     }
/// }
/// ```
///
/// # How the crate's classes get there
///
/// A `macro_rules!` macro cannot read `[package.metadata.miniextendr]`, so the
/// tagged condition value carries the marker class
/// [`CONVERSION_ERROR_CLASS_MARKER`]
/// and the generated wrapper's `.miniextendr_raise_condition` replaces it with
/// `.miniextendr_conversion_error_class`, the binding its own checks use. Across
/// a trait-ABI call the consumer package's wrapper raises the condition, so
/// its crate's classes apply. A raising guard (an ALTREP `RUnwind` callback,
/// `with_r_unwind_protect_or_raise`) has no generated R: it resolves the
/// marker in Rust against the classes `miniextendr_init!` registered (on
/// wasm32, the copy in the `wasm_registry.rs` snapshot), then raises the same
/// condition, `kind = "conversion"` included (#1768). A connection callback
/// returns its fallback, as for any panic.
///
/// The generated `no_na` check after a conversion builds the same condition
/// with [`crate::error_value::arg_check_condition_value`], which takes the
/// classes the macro read at expansion time.
///
/// # Grammar
///
/// `arg_error!([call = none,] param = <expr>, <format string>, <args>...)`.
/// `param` is anything `Into<String>`. A `call` anywhere but first, a repeated
/// one, a missing `param`, and `class =` / `data =` are compile errors:
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::arg_error!(param = "mode", call = none, "bad");
/// # }
/// ```
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::arg_error!("'mode' is bad");
/// # }
/// ```
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::arg_error!(param = "mode", class = "pkg_error", "bad");
/// # }
/// ```
///
/// ```
/// # use miniextendr_api as mx;
/// # fn f(mode: &str) -> ! {
/// mx::arg_error!(call = none, param = "mode", "'mode' is {mode:?}")
/// # }
/// ```
#[macro_export]
macro_rules! arg_error {
    // Internal: after the optional `call = none`.
    (@param $call:expr; call $($rest:tt)*) => {
        ::core::compile_error!("arg_error!: `call = none` is given twice")
    };
    (@param $call:expr; param = $param:expr, call $($rest:tt)*) => {
        ::core::compile_error!(
            "arg_error!: `call = none` comes first, before `param`: \
             `arg_error!(call = none, param = \"mode\", \"...\")`"
        )
    };
    (@param $call:expr; param = $param:expr, class $($rest:tt)*) => {
        $crate::arg_error!(@no_class_or_data)
    };
    (@param $call:expr; param = $param:expr, data $($rest:tt)*) => {
        $crate::arg_error!(@no_class_or_data)
    };
    (@param $call:expr; param = $param:expr, $($arg:tt)+) => {
        ::std::panic::panic_any($crate::condition::RCondition::arg_error(
            $param,
            ::std::format!($($arg)+),
            $call,
        ))
    };
    (@param $call:expr; $($rest:tt)*) => {
        ::core::compile_error!(
            "arg_error!: name the argument, then give the message: \
             `arg_error!(param = \"mode\", \"'mode' should be one of ...\")`"
        )
    };
    (@no_class_or_data) => {
        ::core::compile_error!(
            "arg_error!: takes no `class` or `data`: its classes are the crate's \
             `conversion_error_class` and its only field is `param`, as for the wrapper's \
             own argument errors; use `error!` for a classed error"
        )
    };
    // Entry: the optional `call = none`, then `param = ...` and the message.
    (call = none, $($rest:tt)*) => {
        $crate::arg_error!(@param $crate::condition::ConditionCall::None; $($rest)*)
    };
    (call $($rest:tt)*) => {
        ::core::compile_error!(
            "arg_error!: the only call option is `call = none` (no call, like R's \
             `call. = FALSE`), and it comes first, followed by a comma: \
             `arg_error!(call = none, param = \"mode\", \"...\")`"
        )
    };
    ($($rest:tt)*) => {
        $crate::arg_error!(@param $crate::condition::ConditionCall::Inherit; $($rest)*)
    };
}

// endregion

// region: Class vectors and reserved field names

/// What the condition macros' `class = …` (and [`RError::class`]) accept: one
/// class or several, as `&str` / `String` / arrays / `Vec` / slices.
///
/// The classes are prepended in order to the `rust_*` layering, so put the most
/// specific first: `class = ["pkg_error_missing_field", "pkg_error"]` renders
/// as `c("pkg_error_missing_field", "pkg_error", "rust_error", …)` and both
/// `tryCatch(pkg_error_missing_field = …)` and `tryCatch(pkg_error = …)` match.
pub trait ConditionClass {
    /// The class vector, most specific first.
    fn into_condition_class(self) -> Vec<String>;
}

impl ConditionClass for &str {
    fn into_condition_class(self) -> Vec<String> {
        vec![self.to_string()]
    }
}
impl ConditionClass for String {
    fn into_condition_class(self) -> Vec<String> {
        vec![self]
    }
}
impl ConditionClass for &String {
    fn into_condition_class(self) -> Vec<String> {
        vec![self.clone()]
    }
}
impl<const N: usize> ConditionClass for [&str; N] {
    fn into_condition_class(self) -> Vec<String> {
        self.iter().map(|s| s.to_string()).collect()
    }
}
impl<const N: usize> ConditionClass for [String; N] {
    fn into_condition_class(self) -> Vec<String> {
        self.into_iter().collect()
    }
}
impl ConditionClass for Vec<&str> {
    fn into_condition_class(self) -> Vec<String> {
        self.into_iter().map(str::to_string).collect()
    }
}
impl ConditionClass for Vec<String> {
    fn into_condition_class(self) -> Vec<String> {
        self
    }
}
impl ConditionClass for &[&str] {
    fn into_condition_class(self) -> Vec<String> {
        self.iter().map(|s| s.to_string()).collect()
    }
}
impl ConditionClass for &[String] {
    fn into_condition_class(self) -> Vec<String> {
        self.to_vec()
    }
}

/// Condition-data field names that would overwrite the condition object's own
/// slots when the R helper splices `data` in (`utils::modifyList` over
/// `list(message, call, kind)`).
pub const RESERVED_CONDITION_FIELDS: &[&str] = &["message", "call", "kind"];

/// `true` for [`RESERVED_CONDITION_FIELDS`]. `const` so the macros can reject a
/// literal field name at compile time:
///
/// ```compile_fail
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::rust_error!(data = ("kind", 1), "boom");
/// # }
/// ```
///
/// Any other name is fine, so the fix for a clash is a rename at the source:
///
/// ```
/// # use miniextendr_api as mx;
/// # fn f() {
/// mx::rust_error!(data = ("rule", 1), "boom");
/// # }
/// ```
pub const fn is_reserved_condition_field(name: &str) -> bool {
    str_eq(name, "message")
        || str_eq(name, "call")
        || str_eq(name, "kind")
        || str_eq(name, PARENT_FIELD)
}

/// `a == b`, usable in `const fn`.
const fn str_eq(a: &str, b: &str) -> bool {
    let (a, b) = (a.as_bytes(), b.as_bytes());
    if a.len() != b.len() {
        return false;
    }
    let mut i = 0;
    while i < a.len() {
        if a[i] != b[i] {
            return false;
        }
        i += 1;
    }
    true
}

/// The `data` field under which [`RCondition::with_parent`] sends a cause to
/// R; the raise helper turns it into the condition object `e$parent`.
const PARENT_FIELD: &str = ".mx_parent";

/// Runtime half of the reserved-name check, for computed field names (the
/// macros' `expr` path and [`RConditionData::data`] on user types). Panics
/// when `name` is reserved; the panic becomes a plain `rust_error` in R,
/// replacing the former silent overwrite.
#[track_caller]
pub fn check_condition_field_name(name: String) -> String {
    if is_reserved_condition_field(&name) {
        panic!(
            "condition data field `{name}` is reserved: `message`, `call` and `kind` are the \
             condition's own slots, and `.mx_parent` carries its parent; rename the field."
        );
    }
    name
}

/// Apply [`check_condition_field_name`] to every field of a payload.
#[track_caller]
pub fn check_condition_data(data: Option<ConditionData>) -> Option<ConditionData> {
    data.map(|fields| {
        fields
            .into_iter()
            .map(|(name, value)| (check_condition_field_name(name), value))
            .collect()
    })
}

// endregion

// region: Classed `Result` errors — RConditionData + RError

/// Give a `Result<T, E>` error type an R class vector and structured fields.
///
/// Every `#[miniextendr]` function or method returning `Result<T, E>` raises
/// `Err(e)` as an R error. Implement this trait for `E` (or return
/// [`RError`], which implements it) and the `Err` arm raises
/// `c(<class()…>, "rust_error", "simpleError", "error", "condition")` with
/// every `data()` field readable as `e$<name>`, so a thiserror-style error enum
/// can keep `?` composition *and* give R handlers something to dispatch on.
///
/// Without an impl, the `Err` arm falls back in two steps. Under the `serde`
/// feature an `E: serde::Serialize + Display` is classed from its serde shape
/// (see `serde_err_parts`: variant → member class, fields → data, `Display`
/// → message). Anything else is a bare `rust_error` whose message is
/// `format!("{e:?}")`.
///
/// ```ignore
/// use miniextendr_api::condition::{ConditionData, RConditionData};
///
/// #[derive(Debug, thiserror::Error)]
/// pub enum PkgError {
///     #[error("column `{column}` is missing")]
///     MissingColumn { column: String },
///     #[error("{value} exceeds {max}")]
///     TooLarge { value: f64, max: f64 },
/// }
///
/// impl RConditionData for PkgError {
///     fn message(&self) -> String { self.to_string() }
///     fn class(&self) -> Vec<String> {
///         let member = match self {
///             PkgError::MissingColumn { .. } => "pkg_error_missing_column",
///             PkgError::TooLarge { .. } => "pkg_error_too_large",
///         };
///         vec![member.into(), "pkg_error".into()]
///     }
///     fn data(&self) -> Option<ConditionData> {
///         Some(match self {
///             PkgError::MissingColumn { column } => vec![("column".into(), column.clone().into())],
///             PkgError::TooLarge { value, max } => vec![("value".into(), (*value).into()), ("max".into(), (*max).into())],
///         })
///     }
/// }
///
/// #[miniextendr]
/// pub fn check(value: f64) -> Result<f64, PkgError> { /* uses `?` freely */ }
/// ```
///
/// ```r
/// tryCatch(check(1e9), pkg_error_too_large = function(e) e$max)   # member
/// tryCatch(check(1e9), pkg_error = function(e) conditionMessage(e)) # family
/// ```
///
/// Detection is by trait, not by attribute: the generated `Err` arm probes
/// `E: RConditionData` first and falls back to the `Debug` rendering
/// otherwise, so existing `Result<T, String>` / `Result<T, MyDebugError>`
/// functions are unchanged. The condition's `kind` stays `"result_err"`.
///
/// The same impl classes argument-conversion failures: when a parameter
/// type's `TryFromSexp::Error` implements this trait, a failed conversion
/// raises its classes and fields with `kind = "conversion"`, the message
/// `'<p>' must be <expected>: <message()>` (or `invalid '<p>' argument:
/// <message()>` when the argument's type has no R-facing expectation), the
/// parameter's R name as `e$param` and the Rust type as `e$rust_type`
/// (unless `data()` has a field of the same name, which then wins). An error
/// type without the impl renders with `Display` and keeps the plain
/// `rust_error` class vector.
///
/// `data()` field names must not be `message`, `call` or `kind` (see
/// [`RESERVED_CONDITION_FIELDS`]); a reserved name raises a plain
/// `rust_error` explaining the clash, so rename such a field at the source.
///
/// [`call()`](RConditionData::call) returning [`ConditionCall::None`] drops
/// the call (`conditionCall(e)` is `NULL`), for errors and warnings about the
/// data rather than the call.
pub trait RConditionData {
    /// The condition message (`conditionMessage(e)`).
    fn message(&self) -> String;
    /// User classes, most specific first; empty for none.
    fn class(&self) -> Vec<String> {
        Vec::new()
    }
    /// Structured fields spliced into the condition object (`e$<name>`).
    fn data(&self) -> Option<ConditionData> {
        None
    }
    /// Whether the condition reports a call. [`ConditionCall::None`] makes
    /// `conditionCall()` `NULL`, like R's `call. = FALSE`, for a condition
    /// about the data rather than the call; the default keeps the call the
    /// transport captured. Honoured by `defer_*` and by `Result` returns;
    /// an argument-conversion error always keeps the call (see
    /// [`conversion_err_parts`]). `#[condition(call = none)]` on a derived
    /// type or variant overrides this.
    fn call(&self) -> ConditionCall {
        ConditionCall::Inherit
    }
    /// The whole message when this error refuses an argument, or `None`.
    ///
    /// When the error comes out of a parameter's conversion (the type's
    /// `TryFromSexp`, or its [`check_sexp`](crate::TryFromSexpElement::check_sexp)
    /// under `Option<T>` / `Vec<T>` / `Vec<Option<T>>`), a `Some` is the
    /// condition's message as given, in place of
    /// `'<p>' must be <expected>: <message()>`. The classes, `kind`,
    /// `e$param`, `e$rust_type` and the call are unchanged. This is how a type
    /// words a refusal once for every parameter of that type, as
    /// `#[miniextendr(inherits(..., message = ...))]` does for one parameter:
    /// both use the author's message as given and name the argument in
    /// `e$param`. Ignored everywhere else (`Result` returns, `defer_*`), and
    /// inside an `Either`, whose message names both arms. For a refused
    /// element of a list of objects (`Vec<T>` of a newtype over `List`), it
    /// is that element's reason, before the element's position, in the
    /// prefixed batched message: an element is not the whole argument.
    fn argument_message(&self) -> Option<String> {
        None
    }
}

/// `#[derive(RCondition)]`: [`RConditionData`] generated from a type's shape
/// (`#[condition(class = "…")]`, `#[condition(message = "…")]`, the
/// `rename` / `skip` / `debug` field options) and `From<T>` for
/// [`RCondition`](enum@RCondition) with the declared kind
/// (`#[condition(kind = …)]`, default `error`).
#[doc(inline)]
pub use miniextendr_macros::RCondition;

/// A ready-made classed error value for `Result<T, RError>` returns.
///
/// Carries a message, an optional class vector, structured fields and the
/// call choice, and implements [`RConditionData`]. Any
/// `std::error::Error` converts into it with `?` / [`From`] (the message keeps
/// the `caused by:` chain, like [`AsRError`]), after which the builder methods
/// add the R-facing parts ([`RError::class`], [`RError::data`],
/// [`RError::without_call`]):
///
/// ```ignore
/// use miniextendr_api::condition::RError;
///
/// #[miniextendr]
/// pub fn parse_port(s: &str) -> Result<i32, RError> {
///     let port: i32 = s
///         .parse()
///         .map_err(|e| RError::from(e).class(["pkg_bad_port", "pkg_error"]).data("input", s))?;
///     Ok(port)
/// }
/// ```
///
/// ```r
/// e <- tryCatch(parse_port("x"), pkg_bad_port = function(e) e)
/// e$input          # "x"
/// class(e)[1:2]    # "pkg_bad_port" "pkg_error"
/// ```
///
/// `RError` deliberately does **not** implement `std::error::Error`: that
/// keeps the blanket `From<E: Error>` coherent. It does implement `Display`
/// (the message), so it also works with `#[miniextendr(unwrap_in_r)]`.
#[derive(Debug, Clone)]
pub struct RError {
    message: String,
    class: Vec<String>,
    data: ConditionData,
    call: ConditionCall,
    argument_message: Option<String>,
}

impl RError {
    /// A classless error with `message`.
    pub fn new(message: impl Into<String>) -> Self {
        RError {
            message: message.into(),
            class: Vec::new(),
            data: Vec::new(),
            call: ConditionCall::Inherit,
            argument_message: None,
        }
    }

    /// Raise the condition without a call: `conditionCall(e)` is `NULL` and
    /// the printed condition has no `In f(...) :` prefix, like R's
    /// `stop(..., call. = FALSE)`. For an error or warning about the data, not
    /// the call. Applies to `Result` returns and the `defer_*` functions; see
    /// [`ConditionCall`].
    pub fn without_call(mut self) -> Self {
        self.call = ConditionCall::None;
        self
    }

    /// Append user classes (most specific first). Accepts one string or a
    /// vector, see [`ConditionClass`].
    pub fn class(mut self, class: impl ConditionClass) -> Self {
        self.class.extend(class.into_condition_class());
        self
    }

    /// Attach a structured field readable as `e$<name>`. Any value with an
    /// [`RValue`](crate::RValue) `From` impl works. The name must not be
    /// `message`, `call` or `kind`; see [`RESERVED_CONDITION_FIELDS`].
    pub fn data(mut self, name: impl Into<String>, value: impl Into<crate::RValue>) -> Self {
        self.data.push((name.into(), value.into()));
        self
    }

    /// The whole message of the argument error when this error refuses an
    /// argument, used as given instead of `'<p>' must be <expected>:
    /// <message>`; see [`RConditionData::argument_message`]. `message` stays
    /// the message everywhere else.
    ///
    /// ```ignore
    /// fn model_object(x: SEXP) -> Result<(), RError> {
    ///     if x.inherits_class(c"data.frame") {
    ///         return Err(RError::new("got a data frame")
    ///             .argument_message("use model_from_df() for a data frame"));
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub fn argument_message(mut self, message: impl Into<String>) -> Self {
        self.argument_message = Some(message.into());
        self
    }

    /// The message.
    pub fn message_str(&self) -> &str {
        &self.message
    }

    /// The whole argument-error message, if one was given
    /// ([`RError::argument_message`]).
    pub fn argument_message_str(&self) -> Option<&str> {
        self.argument_message.as_deref()
    }

    /// The user classes, most specific first.
    pub fn classes(&self) -> &[String] {
        &self.class
    }

    /// The structured fields as attached (unprefixed).
    pub fn fields(&self) -> &ConditionData {
        &self.data
    }
}

impl<E: std::error::Error> From<E> for RError {
    /// Message = the error's `Display` plus its `source()` chain, one
    /// `caused by:` line per link (same rendering as [`AsRError`]).
    fn from(err: E) -> Self {
        let mut message = err.to_string();
        let mut current: &dyn std::error::Error = &err;
        while let Some(source) = current.source() {
            message.push_str("\n  caused by: ");
            message.push_str(&source.to_string());
            current = source;
        }
        RError::new(message)
    }
}

impl std::fmt::Display for RError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl RConditionData for RError {
    fn message(&self) -> String {
        self.message.clone()
    }
    fn class(&self) -> Vec<String> {
        self.class.clone()
    }
    fn data(&self) -> Option<ConditionData> {
        (!self.data.is_empty()).then(|| self.data.clone())
    }
    fn call(&self) -> ConditionCall {
        self.call
    }
    fn argument_message(&self) -> Option<String> {
        self.argument_message.clone()
    }
}

/// Any classed error (an [`RError`], a `#[derive(RCondition)]` type)
/// converts into a [`SexpError::Condition`](crate::from_r::SexpError::Condition)
/// with its message, classes, fields and call choice, so a newtype's
/// [`check_sexp`](crate::TryFromSexpElement::check_sexp) can refuse with it
/// and a conversion whose error converts into `SexpError` keeps its classes.
impl<E: RConditionData> From<E> for crate::from_r::SexpError {
    fn from(e: E) -> Self {
        crate::from_r::SexpError::Condition(RError {
            message: e.message(),
            class: e.class(),
            data: e.data().unwrap_or_default(),
            call: e.call(),
            argument_message: e.argument_message(),
        })
    }
}

/// An argument error as a value: the parameter's R name and the message.
/// [`ArgError::raise`] raises it as the generated wrapper's own argument
/// error, through [`crate::arg_error!`].
///
/// [`crate::match_arg_param`] returns it for a choice argument the body
/// matches itself. Raise it where the argument is bad, or handle it:
///
/// ```ignore
/// use miniextendr_api::{SEXP, match_arg_param, miniextendr};
///
/// #[miniextendr]
/// pub fn prepare(data: SEXP, mode: SEXP) -> String {
///     if is_data_frame(data) {
///         let mode: Mode = match_arg_param(mode, "mode").unwrap_or_else(|e| e.raise());
///         // ...
///     }
///     // ...
/// }
/// ```
///
/// It does not implement [`RConditionData`]: returned as a body's `Err` it
/// would take the `Result` path (`kind = "result_err"`), not the argument
/// error's.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArgError {
    param: String,
    message: String,
}

impl ArgError {
    /// The argument error of parameter `param` (its R name) with `message`,
    /// used as given.
    pub fn new(param: impl Into<String>, message: impl Into<String>) -> Self {
        ArgError {
            param: param.into(),
            message: message.into(),
        }
    }

    /// The parameter's R name (`e$param`).
    pub fn param(&self) -> &str {
        &self.param
    }

    /// The message (`conditionMessage(e)`).
    pub fn message(&self) -> &str {
        &self.message
    }

    /// Raise it: `arg_error!(param = <param>, "{}", <message>)`. The
    /// condition is the one the generated wrapper raises for that parameter;
    /// see [`crate::arg_error!`].
    pub fn raise(self) -> ! {
        std::panic::panic_any(RCondition::arg_error(
            self.param,
            self.message,
            ConditionCall::Inherit,
        ))
    }
}

impl std::fmt::Display for ArgError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for ArgError {}

/// The parts of a condition the generated `Err` arms hand to
/// [`crate::error_value::result_err_condition_value`] /
/// [`crate::error_value::conversion_condition_value`], and that
/// [`RCondition::into_parts`] splits a payload into: message, user classes,
/// `data` fields and the [`ConditionCall`] choice.
#[doc(hidden)]
#[derive(Debug)]
pub struct ErrParts {
    pub message: String,
    pub class: Vec<String>,
    pub data: Option<ConditionData>,
    pub call: ConditionCall,
}

/// Autoref-specialisation probe, first stage, preferred arm: `E: RConditionData`.
///
/// Under the `serde` feature a declared-shape stage runs before this one: a
/// shape that `serde_error_shape!` declared for `E` wins over the impl (see
/// `ErrShapeDeclared`).
///
/// The generated code calls `(&e).__mx_classed_parts()` with both first-stage
/// traits in scope. Method resolution tries the receiver type `&E` by value
/// first, which only this impl (on `E`, taking `&self`) satisfies; the
/// [`ErrPartsUnclassed`] arm on `&E` needs one more auto-ref and is only
/// reached when `E` does not implement [`RConditionData`]. It yields `None`,
/// and the second stage ([`ErrPartsSerde`] / [`ErrPartsDebug`]) decides.
///
/// Two two-way probes rather than one three-way probe: the `Serialize` and
/// `Debug` bounds both hold for `&E` whenever they hold for `E`, so a single
/// method name with three impls at increasing reference depth is ambiguous at
/// the first step. Each stage has exactly one impl on `E` and one on `&E`.
#[doc(hidden)]
pub trait ErrPartsClassed {
    fn __mx_classed_parts(&self) -> Option<ErrParts>;
}

impl<E: RConditionData> ErrPartsClassed for E {
    #[track_caller]
    fn __mx_classed_parts(&self) -> Option<ErrParts> {
        Some(ErrParts {
            message: self.message(),
            class: self.class(),
            data: check_condition_data(self.data()),
            call: self.call(),
        })
    }
}

/// First stage, fallback arm: no [`RConditionData`] impl.
#[doc(hidden)]
pub trait ErrPartsUnclassed {
    fn __mx_classed_parts(&self) -> Option<ErrParts>;
}

impl<E> ErrPartsUnclassed for &E {
    fn __mx_classed_parts(&self) -> Option<ErrParts> {
        None
    }
}

/// Second stage, preferred arm: `E: Serialize + Display` under the `serde`
/// feature, classed via [`serde_err_parts`] with the defaults (`kind` tag,
/// the `<crate>_error` prefix the macro passes in, no shapes).
/// `#[miniextendr(serde_error(..))]` bypasses the probe with explicit options.
///
/// The trait exists without the feature so the generated `use` resolves; it
/// then has no impl and every type takes the [`ErrPartsDebug`] arm.
#[doc(hidden)]
pub trait ErrPartsSerde {
    fn __mx_fallback_parts(&self, prefix: &str) -> ErrParts;
}

#[cfg(feature = "serde")]
impl<E: ::serde::Serialize + std::fmt::Display> ErrPartsSerde for E {
    #[track_caller]
    fn __mx_fallback_parts(&self, prefix: &str) -> ErrParts {
        serde_err_parts(self, prefix, &[])
    }
}

/// Second stage, fallback arm: any `E: Debug` (the historical
/// `format!("{e:?}")` rendering, no class, no data).
#[doc(hidden)]
pub trait ErrPartsDebug {
    fn __mx_fallback_parts(&self, prefix: &str) -> ErrParts;
}

impl<E: std::fmt::Debug> ErrPartsDebug for &E {
    fn __mx_fallback_parts(&self, _prefix: &str) -> ErrParts {
        ErrParts {
            message: format!("{self:?}"),
            class: Vec::new(),
            data: None,
            call: ConditionCall::Inherit,
        }
    }
}

/// Internal: the `Err(e)` probe used by generated wrappers. Not public API.
///
/// `$prefix` is the family class for the serde arms (`<crate>_error`, computed
/// by the macro from `CARGO_CRATE_NAME` at expansion time). `$marker` is the
/// calling crate's marker type (`crate::__MiniextendrInitMarker`), under which
/// [`serde_error_shape!`](crate::serde_error_shape) declarations are looked up
/// first, under the `serde` feature: a declared shape wins over the stages
/// below (the `ErrShapeDeclared` probe).
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_result_err_parts {
    ($e:expr, $prefix:expr, $marker:ty) => {{
        #[allow(unused_imports)]
        use $crate::condition::{
            ErrPartsClassed as _, ErrPartsDebug as _, ErrPartsSerde as _, ErrPartsUnclassed as _,
        };
        match &$e {
            __mx_e => match $crate::__mx_declared_err_parts!(__mx_e, $prefix, $marker) {
                ::core::option::Option::Some(parts) => parts,
                ::core::option::Option::None => match __mx_e.__mx_classed_parts() {
                    ::core::option::Option::Some(parts) => parts,
                    ::core::option::Option::None => __mx_e.__mx_fallback_parts($prefix),
                },
            },
        }
    }};
}

// endregion

// region: Classed argument-conversion errors

/// Conversion probe, preferred arm: `E: RConditionData`.
///
/// When an argument fails its `TryFromSexp` conversion, the generated wrapper
/// calls `(&e).__mx_conversion_parts(expected_known)` with the three
/// conversion-probe traits in scope (see [`crate::__mx_conversion_err_parts!`]).
/// This impl, on `E` taking `&self`, matches the receiver `&E` by value, so a
/// `TryFromSexp::Error` that implements [`RConditionData`] contributes its
/// class vector, message and data. [`ConversionErrBuiltin`] matches at the
/// same step for the built-in conversion errors, which never implement
/// [`RConditionData`], so the two never compete. [`ConversionErrDisplay`]
/// needs one more auto-ref and is only reached otherwise.
///
/// Unlike the `Result` probe ([`crate::__mx_result_err_parts!`]) there is no
/// serde stage and the fallback is `Display`, not `Debug`: the generated code
/// has always rendered conversion errors with `Display`, which every built-in
/// error type (`SexpError`, `MatchArgError`, ...) implements.
#[doc(hidden)]
pub trait ConversionErrClassed {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts;
}

impl<E: RConditionData> ConversionErrClassed for E {
    #[track_caller]
    fn __mx_conversion_parts(&self, _expected_known: bool) -> ErrParts {
        ErrParts {
            message: self.message(),
            class: self.class(),
            data: check_condition_data(self.data()),
            call: self.call(),
        }
    }
}

/// Conversion probe, built-in arm: the framework's own conversion errors
/// ([`SexpError`](crate::from_r::SexpError) and the
/// [`SexpTypeError`](crate::from_r::SexpTypeError) /
/// [`SexpClassError`](crate::from_r::SexpClassError) /
/// [`SexpLengthError`](crate::from_r::SexpLengthError) /
/// [`SexpNaError`](crate::from_r::SexpNaError) it wraps, and
/// [`MatchArgError`](crate::match_arg::MatchArgError)), reworded for R
/// users (#1591).
///
/// Their `Display` text is written for the package author: SEXPTYPE names
/// (`expected INTSXP, got STRSXP`) and a variant prefix (`invalid value: ...`).
/// The condition message says instead what the argument should have been,
/// with the reason from `SexpError::r_reason` (`got character`,
/// `got length 2`, `NA is not allowed`, the invalid value's own text, ...)
/// or `MatchArgError::r_reason` (`got "zzz"`).
///
/// `expected_known` is set by the macro when it knows the argument's R-facing
/// expectation and puts it in the message prefix (`'x' must be a single
/// integer`); the reason then does not repeat it. The type names are those of
/// [`sexptype_name`](crate::typed_list::sexptype_name) (`numeric` for a
/// double, `list`, `NULL`, ...).
#[doc(hidden)]
pub trait ConversionErrBuiltin {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts;
}

/// The R-facing reason for a built-in conversion error, see
/// [`ConversionErrBuiltin`].
fn builtin_reason_parts(message: String) -> ErrParts {
    ErrParts {
        message,
        class: Vec::new(),
        data: None,
        call: ConditionCall::Inherit,
    }
}

impl ConversionErrBuiltin for crate::from_r::SexpTypeError {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts {
        builtin_reason_parts(self.r_reason(expected_known))
    }
}

impl ConversionErrBuiltin for crate::from_r::SexpClassError {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts {
        builtin_reason_parts(self.r_reason(expected_known))
    }
}

impl ConversionErrBuiltin for crate::from_r::SexpLengthError {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts {
        builtin_reason_parts(self.r_reason(expected_known))
    }
}

impl ConversionErrBuiltin for crate::from_r::SexpNaError {
    fn __mx_conversion_parts(&self, _expected_known: bool) -> ErrParts {
        builtin_reason_parts("NA is not allowed".to_string())
    }
}

/// A `SexpError` also carries the classes and fields of the check refusals
/// ([`SexpError::Condition`](crate::from_r::SexpError::Condition)) whose
/// reasons its message reports, directly or from an `Either` arm.
impl ConversionErrBuiltin for crate::from_r::SexpError {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts {
        let mut parts = builtin_reason_parts(self.r_reason(expected_known));
        let mut data = ConditionData::new();
        for refusal in self.reported_conditions() {
            for class in refusal.classes() {
                if !parts.class.contains(class) {
                    parts.class.push(class.clone());
                }
            }
            for (name, value) in refusal.fields() {
                if !data.iter().any(|(seen, _)| seen == name) {
                    data.push((name.clone(), value.clone()));
                }
            }
        }
        parts.data = check_condition_data((!data.is_empty()).then_some(data));
        parts
    }
}

impl ConversionErrBuiltin for crate::match_arg::MatchArgError {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts {
        builtin_reason_parts(self.r_reason(expected_known))
    }
}

/// Conversion probe, fallback arm: any `E: Display`. The message is the
/// error's `Display` text, with no class and no data, so the condition keeps
/// the plain `rust_error` class vector.
#[doc(hidden)]
pub trait ConversionErrDisplay {
    fn __mx_conversion_parts(&self, expected_known: bool) -> ErrParts;
}

impl<E: std::fmt::Display> ConversionErrDisplay for &E {
    fn __mx_conversion_parts(&self, _expected_known: bool) -> ErrParts {
        ErrParts {
            message: self.to_string(),
            class: Vec::new(),
            data: None,
            call: ConditionCall::Inherit,
        }
    }
}

/// Internal: the argument-conversion `Err(e)` probe used by generated
/// wrappers. Not public API. Yields the error's own [`ErrParts`];
/// [`crate::error_value::conversion_condition_value`] adds the parameter
/// context.
///
/// The second argument is `expected_known` (see [`ConversionErrBuiltin`]):
/// `true` when the message prefix already states what the argument should
/// be. It defaults to `false`.
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_conversion_err_parts {
    ($e:expr) => {
        $crate::__mx_conversion_err_parts!($e, false)
    };
    ($e:expr, $expected_known:expr) => {{
        #[allow(unused_imports)]
        use $crate::condition::{
            ConversionErrBuiltin as _, ConversionErrClassed as _, ConversionErrDisplay as _,
        };
        match &$e {
            __mx_e => __mx_e.__mx_conversion_parts($expected_known),
        }
    }};
}

/// Expectation probe, built-in arm: an error that knows what the value should
/// have been. A `match_arg` choice error (`MatchArgError`, or a `SexpError`
/// carrying one, as `#[derive(MatchArg)]`'s `TryFromSexp` returns) names its
/// choices: `one of "fast", "slow"`; a class error names the class
/// (`a data frame`); an `Either` whose arms both refused the kind of value
/// names both (`one of "fast", "slow", or numeric`).
#[doc(hidden)]
pub trait ConversionExpectBuiltin {
    fn __mx_conversion_expectation(&self) -> Option<String>;
}

impl ConversionExpectBuiltin for crate::from_r::SexpError {
    fn __mx_conversion_expectation(&self) -> Option<String> {
        self.r_expectation()
    }
}

impl ConversionExpectBuiltin for crate::match_arg::MatchArgError {
    fn __mx_conversion_expectation(&self) -> Option<String> {
        Some(self.expectation())
    }
}

/// Expectation probe, fallback arm: any other error type says nothing about
/// what the value should have been.
#[doc(hidden)]
pub trait ConversionExpectNone {
    fn __mx_conversion_expectation(&self) -> Option<String>;
}

impl<E> ConversionExpectNone for &E {
    fn __mx_conversion_expectation(&self) -> Option<String> {
        None
    }
}

/// Internal: what a failed argument conversion's error says the value should
/// have been, for a parameter whose Rust type gives the macro no R-facing
/// expectation (#1594). `Some("one of \"fast\", \"slow\"")` for a `match_arg`
/// choice error, `Some("a data frame")` for a class error, the joined
/// expectation of an `Either` whose arms both refused the kind of value,
/// `None` otherwise. Not public API.
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_conversion_expectation {
    ($e:expr) => {{
        #[allow(unused_imports)]
        use $crate::condition::{ConversionExpectBuiltin as _, ConversionExpectNone as _};
        match &$e {
            __mx_e => __mx_e.__mx_conversion_expectation(),
        }
    }};
}

/// Whole-message probe, built-in arm: a `match_arg` choice error, as a
/// [`MatchArgError`](crate::match_arg::MatchArgError) or at the top of a
/// `SexpError` (`#[derive(MatchArg)]`'s `TryFromSexp` returns one), words the
/// whole argument error the way the wrapper's R-side `match_arg` check
/// (`.miniextendr_match_arg`) does, from the same
/// [`MatchArgError::arg_error`](crate::match_arg::MatchArgError::arg_error)
/// (#1767): `'mode' should be one of "fast", "slow"`, `'mode' must be of
/// length 1`, `'mode' must be NULL or a character vector`. So a `match_arg`
/// type converted without `#[miniextendr(match_arg)]` and one checked by the
/// wrapper raise the same message.
///
/// A choice error inside an `Either` is not one: the `Either` names both of
/// its arms (`'x' must be one of "oral", "bolus", or a single double: got
/// logical`).
#[doc(hidden)]
pub trait ConversionArgMessageBuiltin {
    fn __mx_conversion_arg_message(&self, name: &str) -> Option<String>;
}

impl ConversionArgMessageBuiltin for crate::match_arg::MatchArgError {
    fn __mx_conversion_arg_message(&self, name: &str) -> Option<String> {
        Some(self.arg_error(name).message().to_string())
    }
}

impl ConversionArgMessageBuiltin for crate::from_r::SexpError {
    fn __mx_conversion_arg_message(&self, name: &str) -> Option<String> {
        match self {
            crate::from_r::SexpError::MatchArg(e) => Some(e.arg_error(name).message().to_string()),
            // A type's check refusal (`check_sexp` under `Option<T>` /
            // `Vec<T>`, or a conversion whose error converted into
            // `SexpError`) with its own whole message (#1833).
            crate::from_r::SexpError::Condition(e) => e.argument_message_str().map(str::to_string),
            _ => None,
        }
    }
}

/// Whole-message probe, classed arm: any [`RConditionData`] answers with its
/// [`argument_message`](RConditionData::argument_message), so a type's own
/// conversion error can word the whole argument error (#1833). Same autoref
/// level as [`ConversionArgMessageBuiltin`], like [`ConversionErrClassed`]:
/// no built-in error type implements [`RConditionData`].
#[doc(hidden)]
pub trait ConversionArgMessageClassed {
    fn __mx_conversion_arg_message(&self, name: &str) -> Option<String>;
}

impl<E: RConditionData> ConversionArgMessageClassed for E {
    fn __mx_conversion_arg_message(&self, _name: &str) -> Option<String> {
        self.argument_message()
    }
}

/// Whole-message probe, fallback arm: any other error leaves the message to
/// the prefix and the error's reason.
#[doc(hidden)]
pub trait ConversionArgMessageNone {
    fn __mx_conversion_arg_message(&self, name: &str) -> Option<String>;
}

impl<E> ConversionArgMessageNone for &E {
    fn __mx_conversion_arg_message(&self, _name: &str) -> Option<String> {
        None
    }
}

/// Internal: the whole message of a failed argument conversion whose error
/// words it itself (a `match_arg` choice error, see
/// [`ConversionArgMessageBuiltin`], or an error with an
/// [`argument_message`](RConditionData::argument_message), see
/// [`ConversionArgMessageClassed`]), for the argument `$name`; `None`
/// otherwise. [`crate::error_value::conversion_condition_value`] then uses it
/// in place of `<prefix>: <reason>`. Not public API.
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_conversion_arg_message {
    ($e:expr, $name:expr) => {{
        #[allow(unused_imports)]
        use $crate::condition::{
            ConversionArgMessageBuiltin as _, ConversionArgMessageClassed as _,
            ConversionArgMessageNone as _,
        };
        match &$e {
            __mx_e => __mx_e.__mx_conversion_arg_message($name),
        }
    }};
}

/// The message prefix of a conversion failure whose expectation comes from
/// the error at run time (see [`crate::__mx_conversion_expectation!`]):
/// `'<p>' must be <expected>` (`'<p>' must be NULL or <expected>` for an
/// `Option<_>` parameter, `nullable`), else `invalid '<p>' argument`.
#[doc(hidden)]
pub fn conversion_prefix(param: &str, nullable: bool, expected: Option<&str>) -> String {
    match expected {
        Some(expected) if nullable => format!("'{param}' must be NULL or {expected}"),
        Some(expected) => format!("'{param}' must be {expected}"),
        None => format!("invalid '{param}' argument"),
    }
}

/// The name of the structured field that carries the failing parameter's R
/// name on every argument-conversion condition (`e$param`).
const CONVERSION_PARAM_FIELD: &str = "param";

/// The name of the structured field that carries the Rust type an argument
/// failed to convert to (`e$rust_type`, #1591).
const CONVERSION_RUST_TYPE_FIELD: &str = "rust_type";

/// Combine an argument-conversion error's own parts with the wrapper's
/// parameter context.
///
/// - The message becomes `<prefix>: <error message>`. For an argument the
///   macro writes the prefix in R terms (#1591): `'<p>' must be <expected>`
///   when it knows what the argument should be (`'x' must be a single
///   integer`, `'dv' must be numeric`), `invalid '<p>' argument` otherwise.
///   A sidecar setter passes its own prefix. An error that words the whole
///   argument error itself, a `match_arg` choice error (#1767) or one with an
///   [`argument_message`](RConditionData::argument_message) (#1833), gives
///   `arg_message` ([`crate::__mx_conversion_arg_message!`]), which is the
///   message instead.
/// - The class vector is the error's own (empty for the built-in and
///   `Display` arms), followed by `crate_class`, the crate's
///   `conversion_error_class` from `[package.metadata.miniextendr]`, minus
///   any class the error already names. The R helper appends the
///   `rust_error` layering after both.
/// - `param` (the parameter's R name) is added as the first data field,
///   `e$param`, and `rust_type` (the Rust type as written in the signature,
///   when given) after it, `e$rust_type`. Neither is added when the error's
///   own data already has a field of that name: the type author's value is
///   kept, since the framework never overwrites a field the type author
///   chose, and R's `e$name` reads only the first of two same-named fields.
/// - The call is always the wrapper's ([`ConditionCall::Inherit`]), whatever
///   the error type's [`RConditionData::call`] says: the R-side checks
///   (`.miniextendr_arg_error`) raise the same condition with the call
///   (#1591), and an argument error must not differ by which side caught it.
#[doc(hidden)]
pub fn conversion_err_parts(
    prefix: &str,
    param: &str,
    rust_type: Option<&str>,
    crate_class: &[&str],
    parts: ErrParts,
    arg_message: Option<String>,
) -> ErrParts {
    let ErrParts {
        message,
        mut class,
        data,
        call: _,
    } = parts;
    let message = arg_message.unwrap_or_else(|| format!("{prefix}: {message}"));
    for extra in crate_class {
        if !class.iter().any(|c| c == extra) {
            class.push((*extra).to_string());
        }
    }
    let mut fields = data.unwrap_or_default();
    let has_field =
        |fields: &ConditionData, field: &str| fields.iter().any(|(name, _)| name == field);
    let mut at = 0;
    if !has_field(&fields, CONVERSION_PARAM_FIELD) {
        fields.insert(0, (CONVERSION_PARAM_FIELD.to_string(), param.into()));
        at = 1;
    }
    if let Some(rust_type) = rust_type
        && !has_field(&fields, CONVERSION_RUST_TYPE_FIELD)
    {
        fields.insert(
            at,
            (CONVERSION_RUST_TYPE_FIELD.to_string(), rust_type.into()),
        );
    }
    ErrParts {
        message,
        class,
        data: Some(fields),
        call: ConditionCall::Inherit,
    }
}

/// The parts of an argument check that failed in Rust after the conversion:
/// `#[miniextendr(no_na)]` on a reading marker (`AsNumeric*`,
/// `AsCharacter*`) whose converted value holds an `NA` that R's `anyNA()`
/// did not see (the hidden `TryFromSexp::__mx_has_na` says so), or on an
/// `Either`, which has no R guard, an `NA` the arm taken refuses
/// (`TryFromSexp::__mx_input_has_na`).
///
/// The shape is the R guard's (`.miniextendr_arg_error`): `message` as given
/// (the macro writes `'<p>' must not be NA` or the author's own message),
/// the classes `crate_class` (the crate's `conversion_error_class`), and
/// `param` as the only data field, `e$param`. No `rust_type`: the R guard
/// has none, and the two paths raise one condition.
#[doc(hidden)]
pub fn arg_check_parts(message: &str, param: &str, crate_class: &[&str]) -> ErrParts {
    ErrParts {
        message: message.to_string(),
        class: crate_class.iter().map(|c| (*c).to_string()).collect(),
        data: Some(vec![(CONVERSION_PARAM_FIELD.to_string(), param.into())]),
        call: ConditionCall::Inherit,
    }
}

// endregion

// region: SerdeErrorShape — `serde_error` options as a shared const (#2207)

/// The options of `#[miniextendr(serde_error(..))]` as a value: declared once,
/// shared by every function that returns one error type.
///
/// ```
/// use miniextendr_api::condition::SerdeErrorShape;
///
/// pub const ENGINE: SerdeErrorShape = SerdeErrorShape::new()
///     .prefix("engine")
///     .skip(&["message"])
///     .as_character(&["rule", "column"])
///     .as_integer(&["n"]);
/// ```
///
/// Declare it for the error type with
/// [`serde_error_shape!`](crate::serde_error_shape), and every
/// `#[miniextendr]` function or method of the crate that returns that type
/// uses it, without naming it:
///
/// ```ignore
/// miniextendr_api::serde_error_shape!(EngineError = ENGINE);
///
/// #[miniextendr]
/// pub fn check(x: f64) -> Result<f64, EngineError> { /* ... */ }
/// ```
///
/// A function can override it for itself: with options of its own, or with
/// another shape named by path, which applies after the declared one:
///
/// ```ignore
/// #[miniextendr(serde_error(as_double("n")))]
/// pub fn rate(x: f64) -> Result<f64, EngineError> { /* ... */ }
///
/// #[miniextendr(serde_error(shape = STRICT, as_double("n")))]
/// pub fn strict_rate(x: f64) -> Result<f64, EngineError> { /* ... */ }
/// ```
///
/// The path resolves where the function is defined (`STRICT`,
/// `crate::errors::STRICT`, or `Self::SHAPE` on a method for an associated
/// const of its type), so a misspelt one is a compile error. The options act
/// on the serde-classed `Err` arm, which needs the `serde` feature.
///
/// # Options
///
/// One method per `serde_error` option. Fields are named as the error
/// serializes them, before any `rename`:
///
/// - [`tag`](Self::tag): the internally tagged discriminator field consumed
///   as the variant; `"kind"` when unset.
/// - [`prefix`](Self::prefix): the family class; `<crate>_error`, from the
///   function's crate, when unset.
/// - [`skip`](Self::skip): fields to drop.
/// - [`rename`](Self::rename): `(from, to)` pairs; field `from` reaches R as
///   `e$to`.
/// - [`as_character`](Self::as_character), [`as_integer`](Self::as_integer),
///   [`as_double`](Self::as_double), [`as_logical`](Self::as_logical): the
///   field's usual serialization as one vector of that R type, as the
///   `miniextendr_api::serde::as_character` & co. field helpers give it from
///   the error type's own `#[serde(serialize_with = ..)]`: `character(0)` for
///   an empty sequence, `NA` for a `None` element. A value that doesn't fit
///   (a string under `as_integer`) raises an R error naming the field and the
///   option.
///
/// A field that a variant doesn't carry is a no-op for that variant, so one
/// shape covers an enum whose variants differ.
///
/// # Precedence
///
/// Shapes apply in order: the one declared for the error type, then
/// `serde_error(shape = ..)`, then the function's own options; for a field
/// set by more than one, the later wins. A later `skip` drops a field an
/// earlier shape types or renames, and a later `as_*` or `rename` keeps a
/// field an earlier shape skips. A type and a new name compose: the
/// function's `rename(n = "count")` keeps the shape's `as_integer(&["n"])`.
/// A later `tag` or `prefix` replaces an earlier one.
///
/// # Contradictions don't compile
///
/// Each method checks its fields against the options already set and panics
/// during const evaluation, so a `const` holding a contradictory shape is a
/// compile error (E0080) naming the field:
///
/// - a field in two `as_*` lists;
/// - a field skipped and also typed or renamed;
/// - a field listed twice, renamed twice, or two renames onto one name;
/// - a `rename` target that is one of the condition's own slots (`message`,
///   `call`, `kind`);
/// - an empty list or name, and an option set twice.
///
/// ```compile_fail,E0080
/// use miniextendr_api::condition::SerdeErrorShape;
///
/// const ENGINE: SerdeErrorShape = SerdeErrorShape::new()
///     .as_integer(&["n"])
///     .as_double(&["n"]);
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SerdeErrorShape {
    tag: Option<&'static str>,
    prefix: Option<&'static str>,
    skip: &'static [&'static str],
    rename: &'static [(&'static str, &'static str)],
    /// The `as_*` lists, in [`SHAPE_TYPE_OPTIONS`] order.
    types: [&'static [&'static str]; 4],
}

/// The `as_*` options, in the order of [`SerdeErrorShape`]'s type lists.
const SHAPE_TYPE_OPTIONS: [&str; 4] = ["as_logical", "as_integer", "as_double", "as_character"];

impl SerdeErrorShape {
    /// The discriminator field when no shape names one.
    #[cfg(feature = "serde")]
    const DEFAULT_TAG: &'static str = "kind";

    /// A shape that sets nothing.
    pub const fn new() -> Self {
        SerdeErrorShape {
            tag: None,
            prefix: None,
            skip: &[],
            rename: &[],
            types: [&[]; 4],
        }
    }

    /// The internally tagged discriminator field (`#[serde(tag = "...")]`),
    /// consumed as the variant.
    #[track_caller]
    pub const fn tag(mut self, tag: &'static str) -> Self {
        self.tag = Some(scalar_option("tag", self.tag, tag));
        self
    }

    /// The family class: conditions get `c("<prefix>_<variant>", "<prefix>")`.
    #[track_caller]
    pub const fn prefix(mut self, prefix: &'static str) -> Self {
        self.prefix = Some(scalar_option("prefix", self.prefix, prefix));
        self
    }

    /// Drop these payload fields.
    #[track_caller]
    pub const fn skip(mut self, fields: &'static [&'static str]) -> Self {
        check_field_list("skip", self.skip.is_empty(), fields);
        let mut i = 0;
        while i < fields.len() {
            let name = fields[i];
            if let Some(option) = self.type_option(name) {
                conflict(name, option, "skip", "a skipped field has no R type");
            }
            if self.renames(name) {
                conflict(name, "rename", "skip", "a skipped field has no name");
            }
            i += 1;
        }
        self.skip = fields;
        self
    }

    /// Splice field `from` as `to`, for each `(from, to)` pair.
    #[track_caller]
    pub const fn rename(mut self, pairs: &'static [(&'static str, &'static str)]) -> Self {
        if !self.rename.is_empty() {
            set_twice("rename");
        }
        if pairs.is_empty() {
            fail(ShapeMessage::new().push("`rename` needs at least one pair"));
        }
        let mut i = 0;
        while i < pairs.len() {
            let (from, to) = pairs[i];
            if from.is_empty() || to.is_empty() {
                fail(ShapeMessage::new().push("`rename` has an empty name"));
            }
            if is_reserved_condition_field(to) {
                fail(ShapeMessage::new().push("`rename` target `").push(to).push(
                    "` is reserved: `message`, `call` and `kind` are the condition's own slots",
                ));
            }
            let mut j = 0;
            while j < i {
                if str_eq(pairs[j].0, from) {
                    fail(
                        ShapeMessage::new()
                            .push("field `")
                            .push(from)
                            .push("` is renamed twice"),
                    );
                }
                if str_eq(pairs[j].1, to) {
                    fail(
                        ShapeMessage::new()
                            .push("two `rename` pairs target `")
                            .push(to)
                            .push("`; R would read only the first"),
                    );
                }
                j += 1;
            }
            if const_contains(self.skip, from) {
                conflict(from, "skip", "rename", "a skipped field has no name");
            }
            i += 1;
        }
        self.rename = pairs;
        self
    }

    /// Give these fields an R `logical` vector.
    #[track_caller]
    pub const fn as_logical(self, fields: &'static [&'static str]) -> Self {
        self.with_type(0, fields)
    }

    /// Give these fields an R `integer` vector; a value outside R's integer
    /// range is an error, not a double.
    #[track_caller]
    pub const fn as_integer(self, fields: &'static [&'static str]) -> Self {
        self.with_type(1, fields)
    }

    /// Give these fields an R `double` vector; integers widen.
    #[track_caller]
    pub const fn as_double(self, fields: &'static [&'static str]) -> Self {
        self.with_type(2, fields)
    }

    /// Give these fields an R `character` vector.
    #[track_caller]
    pub const fn as_character(self, fields: &'static [&'static str]) -> Self {
        self.with_type(3, fields)
    }

    #[track_caller]
    const fn with_type(mut self, index: usize, fields: &'static [&'static str]) -> Self {
        let option = SHAPE_TYPE_OPTIONS[index];
        check_field_list(option, self.types[index].is_empty(), fields);
        let mut i = 0;
        while i < fields.len() {
            let name = fields[i];
            if const_contains(self.skip, name) {
                conflict(name, "skip", option, "a skipped field has no R type");
            }
            if let Some(other) = self.type_option(name) {
                conflict(name, other, option, "a field has one R type");
            }
            i += 1;
        }
        self.types[index] = fields;
        self
    }

    /// The `as_*` option that lists `name`.
    const fn type_option(&self, name: &str) -> Option<&'static str> {
        let mut i = 0;
        while i < self.types.len() {
            if const_contains(self.types[i], name) {
                return Some(SHAPE_TYPE_OPTIONS[i]);
            }
            i += 1;
        }
        None
    }

    /// Whether a `rename` pair renames `name`.
    const fn renames(&self, name: &str) -> bool {
        let mut i = 0;
        while i < self.rename.len() {
            if str_eq(self.rename[i].0, name) {
                return true;
            }
            i += 1;
        }
        false
    }
}

impl Default for SerdeErrorShape {
    fn default() -> Self {
        Self::new()
    }
}

/// `tag` / `prefix`: set once, never empty.
#[track_caller]
const fn scalar_option(
    option: &str,
    current: Option<&'static str>,
    value: &'static str,
) -> &'static str {
    if current.is_some() {
        set_twice(option);
    }
    if value.is_empty() {
        fail(
            ShapeMessage::new()
                .push("`")
                .push(option)
                .push("` must not be empty"),
        );
    }
    value
}

/// A field list: set once, not empty, each name non-empty and listed once.
#[track_caller]
const fn check_field_list(option: &str, unset: bool, fields: &[&str]) {
    if !unset {
        set_twice(option);
    }
    if fields.is_empty() {
        fail(
            ShapeMessage::new()
                .push("`")
                .push(option)
                .push("` needs at least one field"),
        );
    }
    let mut i = 0;
    while i < fields.len() {
        if fields[i].is_empty() {
            fail(
                ShapeMessage::new()
                    .push("`")
                    .push(option)
                    .push("` has an empty field name"),
            );
        }
        let mut j = 0;
        while j < i {
            if str_eq(fields[j], fields[i]) {
                fail(
                    ShapeMessage::new()
                        .push("field `")
                        .push(fields[i])
                        .push("` is listed twice in `")
                        .push(option)
                        .push("`"),
                );
            }
            j += 1;
        }
        i += 1;
    }
}

#[track_caller]
const fn set_twice(option: &str) -> ! {
    fail(
        ShapeMessage::new()
            .push("`")
            .push(option)
            .push("` is set twice; set each option once"),
    )
}

#[track_caller]
const fn conflict(name: &str, first: &str, second: &str, why: &str) -> ! {
    fail(
        ShapeMessage::new()
            .push("field `")
            .push(name)
            .push("` is in both `")
            .push(first)
            .push("` and `")
            .push(second)
            .push("`; ")
            .push(why),
    )
}

const fn const_contains(list: &[&str], name: &str) -> bool {
    let mut i = 0;
    while i < list.len() {
        if str_eq(list[i], name) {
            return true;
        }
        i += 1;
    }
    false
}

/// A const-evaluation panic message. `const fn` can't `format!`, so the parts
/// are copied into a fixed buffer.
struct ShapeMessage {
    buf: [u8; 256],
    len: usize,
}

impl ShapeMessage {
    const fn new() -> Self {
        ShapeMessage {
            buf: [0; 256],
            len: 0,
        }
        .push("SerdeErrorShape: ")
    }

    const fn push(mut self, text: &str) -> Self {
        let bytes = text.as_bytes();
        let mut i = 0;
        while i < bytes.len() && self.len < self.buf.len() {
            self.buf[self.len] = bytes[i];
            self.len += 1;
            i += 1;
        }
        self
    }
}

/// Panic with `message`. `#[track_caller]` here and on every caller puts the
/// compile error at the user's `const`, not in this crate.
#[track_caller]
const fn fail(message: ShapeMessage) -> ! {
    let (text, _) = message.buf.split_at(message.len);
    match core::str::from_utf8(text) {
        Ok(text) => panic!("{}", text),
        // The buffer ended inside a long field name's character.
        Err(_) => {
            panic!("SerdeErrorShape: contradictory options; a field name is too long to quote")
        }
    }
}

// endregion

// region: Serde-tagged Result errors (#[miniextendr(serde_error)])

/// Build the `Err`-arm parts from the error's serde shape.
///
/// Reached three ways: for a `Result<T, E>` whose `E` has a shape declared
/// by [`serde_error_shape!`](crate::serde_error_shape) (the
/// [`ErrShapeDeclared`] probe arm, that one shape); automatically, for every
/// other `E` that is `Serialize + Display` without an [`RConditionData`] impl
/// (the [`ErrPartsSerde`] probe arm, no shapes); or explicitly through
/// `#[miniextendr(serde_error(..))]`, whose options arrive as `shapes`: the
/// declared shape first (one that sets nothing when there is none), then the
/// named `shape = ..`, then the function's own options as an inline const,
/// each applied in order (see [`SerdeErrorShape`], "Precedence").
/// `prefix` is the macro's `<crate>_error`, used when no shape sets one.
///
/// Message from `Display`; classes `[<prefix>_<variant>, <prefix>]` when the
/// serialized value carries a variant, `[<prefix>]` otherwise; data from the
/// serialized fields (checked against the reserved names). `tag` names the
/// internally-tagged discriminator field (`#[serde(tag = "kind")]`), which is
/// consumed as the member class rather than spliced as data; externally tagged
/// enums (serde's default) yield the variant name directly. See
/// `docs/CONDITIONS.md`, "Classed `Result` errors".
///
/// Field control, applied to the payload fields before the reserved-name
/// check (`serde_error(skip(..), rename(..), as_*(..))`, #1457, #2207):
///
/// - `skip`: fields with these names are dropped.
/// - `as_character` / `as_integer` / `as_double` / `as_logical`: the field's
///   value becomes one vector of that type, through the same conversion as
///   the `serde::as_*` field helpers; a value that doesn't fit panics, naming
///   the field and the option.
/// - `rename`: `(from, to)` pairs; a field named `from` is spliced as `to`.
/// - A remaining field named `message` whose value is the single string equal
///   to the `Display` output is dropped: it duplicates the condition's own
///   `message` slot, so a wrapped parser error of the shape
///   `Variant { message: String }` reaches R without any option.
///
/// Names that a given variant does not carry are a no-op for that variant.
/// Any other collision with `message`, `call` or `kind` still panics via
/// [`check_condition_data`].
///
/// After `skip` / `rename` the field names must be distinct: a `rename` whose
/// target is a name the variant already carries (or two payload fields that
/// serialize under one name) would give the condition two entries with the
/// same name, of which R's `e$name` reads only the first. That panics too,
/// naming the field and the rename that produced it (#1459).
///
/// Serialization failing (a map with non-string keys, a custom `Serialize`
/// erroring) panics with both failures in the message: the original error
/// text must not be lost behind the reporting problem.
#[cfg(feature = "serde")]
#[doc(hidden)]
#[track_caller]
pub fn serde_err_parts<E: ?Sized + ::serde::Serialize + std::fmt::Display>(
    e: &E,
    prefix: &str,
    shapes: &[&SerdeErrorShape],
) -> ErrParts {
    let message = e.to_string();
    let tag = shapes
        .iter()
        .rev()
        .find_map(|s| s.tag)
        .unwrap_or(SerdeErrorShape::DEFAULT_TAG);
    let prefix = shapes.iter().rev().find_map(|s| s.prefix).unwrap_or(prefix);
    let (member, fields) = match crate::serde::rvalue_ser::tagged_parts(e, tag) {
        Ok(parts) => parts,
        Err(err) => panic!(
            "#[miniextendr(serde_error)]: serializing `{}` for its condition data failed ({err}); \
             the original error was: {message}",
            std::any::type_name::<E>()
        ),
    };
    let mut class = Vec::with_capacity(2);
    if let Some(member) = member {
        class.push(format!("{prefix}_{member}"));
    }
    class.push(prefix.to_string());
    let mut renames = Vec::new();
    let mut data: ConditionData = Vec::with_capacity(fields.len());
    for (name, value) in fields {
        let Some(field) = FieldShape::resolve(shapes, &name) else {
            continue;
        };
        let value = match field.atomic {
            None => value,
            Some(atomic) => match atomic.try_coerce(value) {
                Ok(value) => value,
                Err(element) => panic!(
                    "#[miniextendr(serde_error)]: `{}` on condition data field `{name}` failed: \
                     {}; the original error was: {message}",
                    atomic.helper(),
                    atomic.mismatch(element)
                ),
            },
        };
        if let Some((from, to)) = field.rename {
            renames.push((from, to));
            data.push((to.to_string(), value));
            continue;
        }
        let echoes_display = name == "message"
            && matches!(&value, crate::RValue::Character(v)
                if v.len() == 1 && v[0].as_deref() == Some(message.as_str()));
        if !echoes_display {
            data.push((name, value));
        }
    }
    check_distinct_field_names(&data, &renames);
    ErrParts {
        message,
        class,
        data: check_condition_data((!data.is_empty()).then_some(data)),
        call: ConditionCall::Inherit,
    }
}

/// What the shapes, applied in order, give one payload field.
#[cfg(feature = "serde")]
#[derive(Default)]
struct FieldShape {
    atomic: Option<crate::serde::rvalue_ser::Atomic>,
    rename: Option<(&'static str, &'static str)>,
}

#[cfg(feature = "serde")]
impl FieldShape {
    /// `None` when the last shape that names the field skips it. A later
    /// `skip` drops what earlier shapes set; a later type or rename replaces
    /// that setting and keeps the field.
    fn resolve(shapes: &[&SerdeErrorShape], name: &str) -> Option<Self> {
        let mut skipped = false;
        let mut field = FieldShape::default();
        for shape in shapes {
            if shape.skip.contains(&name) {
                skipped = true;
                field = FieldShape::default();
            }
            if let Some(i) = shape.types.iter().position(|list| list.contains(&name)) {
                skipped = false;
                field.atomic = Some(crate::serde::rvalue_ser::Atomic::ALL[i]);
            }
            if let Some(&pair) = shape.rename.iter().find(|(from, _)| *from == name) {
                skipped = false;
                field.rename = Some(pair);
            }
        }
        (!skipped).then_some(field)
    }
}

/// Panic when two payload fields share a name after `skip` / `rename`.
///
/// R's `e$<name>` returns the first entry with that name and the second is
/// unreachable, which is the silent-overwrite failure the reserved-name rule
/// exists to remove (#1440). Neither first-wins nor last-wins would report it.
#[cfg(feature = "serde")]
#[track_caller]
fn check_distinct_field_names(fields: &[(String, crate::RValue)], rename: &[(&str, &str)]) {
    let mut seen = std::collections::HashSet::with_capacity(fields.len());
    for (name, _) in fields {
        if seen.insert(name.as_str()) {
            continue;
        }
        let renames: Vec<String> = rename
            .iter()
            .filter(|(_, to)| *to == name)
            .map(|(from, to)| format!("`rename({from} = \"{to}\")`"))
            .collect();
        if renames.is_empty() {
            panic!(
                "#[miniextendr(serde_error)]: condition data field `{name}` appears twice in the \
                 serialized payload; R's `e${name}` would read only the first. Give the fields \
                 distinct names or `skip` one of them."
            );
        }
        panic!(
            "#[miniextendr(serde_error)]: condition data field `{name}` appears twice: {} targets \
             a name this variant already carries; R's `e${name}` would read only the first. Pick \
             another target or `skip` the existing field.",
            renames.join(" and ")
        );
    }
}

// endregion

// region: Declared shapes — one SerdeErrorShape per error type (#2207)

/// The [`SerdeErrorShape`] declared for the error type `Self` by the crate
/// whose marker type is `M`. Implemented by
/// [`serde_error_shape!`](crate::serde_error_shape), not by hand.
///
/// `M` is a type local to the declaring crate (`miniextendr_init!` defines it
/// at the crate root). That is what lets an R-facing crate declare a shape
/// for an error type from a crate that doesn't depend on miniextendr: the
/// orphan rule accepts `impl ForeignTrait<LocalType> for ForeignType`. It also
/// scopes the declaration to the crate: another crate returning the same type
/// looks up its own declaration.
///
/// The supertraits make a declaration for a type that can't be serialized, or
/// has no `Display` for the condition message, an error at the declaration.
#[cfg(feature = "serde")]
pub trait SerdeErrorShapeFor<M>: ::serde::Serialize + std::fmt::Display {
    /// The declared shape.
    const SHAPE: &'static SerdeErrorShape;
}

/// Declare the [`SerdeErrorShape`] of an error type once, for every
/// `#[miniextendr]` function and method of this crate that returns it.
///
/// ```ignore
/// use miniextendr_api::condition::SerdeErrorShape;
///
/// pub const ENGINE: SerdeErrorShape = SerdeErrorShape::new()
///     .prefix("engine")
///     .as_character(&["rule"])
///     .as_integer(&["n"]);
///
/// miniextendr_api::serde_error_shape!(engine::Error = ENGINE);
///
/// // Both raise with ENGINE's field types; neither names it.
/// #[miniextendr]
/// pub fn check(x: f64) -> Result<f64, engine::Error> { /* ... */ }
///
/// #[miniextendr]
/// pub fn rate(x: f64) -> Result<f64, engine::Error> { /* ... */ }
/// ```
///
/// The right-hand side is any constant expression of type
/// `SerdeErrorShape`: a path, as above, or the builder chain itself. The type
/// must be `Serialize + Display` and may come from any crate, including one
/// that can't depend on miniextendr. The declaration goes anywhere in the
/// crate that calls `miniextendr_init!`, which defines the marker type it is
/// keyed by (see [`SerdeErrorShapeFor`]); it applies to that crate's
/// functions only.
///
/// # Precedence
///
/// Every `Err` of the type, from a function with or without
/// `#[miniextendr(serde_error(..))]`, is classed through serde with the
/// declared shape applied first. A function's `serde_error(shape = X)` applies
/// next and its own options last; for a field set more than once, the later
/// setting wins, by the rules under [`SerdeErrorShape`], "Precedence".
///
/// The declaration also wins over an [`RConditionData`] impl of the type: it is
/// the R-facing crate's choice for its own functions, where the impl is the
/// error crate's general one.
///
/// # One declaration per type
///
/// A second declaration for a type in the same crate is the compiler's
/// conflicting-implementations error:
///
/// ```compile_fail,E0119
/// use miniextendr_api::condition::SerdeErrorShape;
///
/// miniextendr_api::miniextendr_init!(pkg);
///
/// const A: SerdeErrorShape = SerdeErrorShape::new().prefix("a");
/// const B: SerdeErrorShape = SerdeErrorShape::new().prefix("b");
///
/// miniextendr_api::serde_error_shape!(String = A);
/// miniextendr_api::serde_error_shape!(String = B);
///
/// fn main() {}
/// ```
#[cfg(feature = "serde")]
#[macro_export]
// `crate::` is meant: the marker is the calling crate's.
#[allow(clippy::crate_in_macro_def)]
macro_rules! serde_error_shape {
    ($error:ty = $shape:expr $(,)?) => {
        impl $crate::condition::SerdeErrorShapeFor<crate::__MiniextendrInitMarker> for $error {
            const SHAPE: &'static $crate::condition::SerdeErrorShape = &$shape;
        }
    };
}

/// Declare the `SerdeErrorShape` of an error type once, for every
/// `#[miniextendr]` function and method of this crate that returns it. Needs
/// the `serde` feature, without which a declaration is a compile error.
#[cfg(not(feature = "serde"))]
#[macro_export]
macro_rules! serde_error_shape {
    ($($input:tt)*) => {
        ::core::compile_error!(
            "`serde_error_shape!` needs the `serde` feature of miniextendr-api; \
             enable it to class errors through serde"
        );
    };
}

/// The receiver of the declared-shape probe: the error, and the marker `M` of
/// the crate whose declaration to look up.
#[cfg(feature = "serde")]
#[doc(hidden)]
pub struct DeclaredShapeProbe<'a, M, E>(pub &'a E, pub std::marker::PhantomData<fn() -> M>);

/// Declared-shape probe, preferred arm: `E` has a shape declared under `M`.
///
/// The generated code calls `(&probe).__mx_declared_parts(..)` with both
/// traits in scope. This impl, on the probe taking `&self`, matches the
/// receiver `&DeclaredShapeProbe` by value; [`ErrShapeUndeclared`] on
/// `&DeclaredShapeProbe` needs one more auto-ref and is only reached when
/// nothing is declared.
#[cfg(feature = "serde")]
#[doc(hidden)]
pub trait ErrShapeDeclared {
    /// The parts under the declared shape, for an `Err` arm without
    /// `serde_error(..)`. The call to [`serde_err_parts`] lives here, where
    /// `E: Serialize + Display` holds, so an undeclared `E` needn't be.
    fn __mx_declared_parts(&self, prefix: &str) -> Option<ErrParts>;
    /// The declared shape, first in `serde_error(..)`'s shape list.
    fn __mx_declared_shape(&self) -> &'static SerdeErrorShape;
}

#[cfg(feature = "serde")]
impl<M, E: SerdeErrorShapeFor<M>> ErrShapeDeclared for DeclaredShapeProbe<'_, M, E> {
    #[track_caller]
    fn __mx_declared_parts(&self, prefix: &str) -> Option<ErrParts> {
        Some(serde_err_parts(self.0, prefix, &[E::SHAPE]))
    }

    fn __mx_declared_shape(&self) -> &'static SerdeErrorShape {
        E::SHAPE
    }
}

/// Declared-shape probe, fallback arm: no declaration. No parts, and a shape
/// that sets nothing.
#[cfg(feature = "serde")]
#[doc(hidden)]
pub trait ErrShapeUndeclared {
    fn __mx_declared_parts(&self, prefix: &str) -> Option<ErrParts>;
    fn __mx_declared_shape(&self) -> &'static SerdeErrorShape;
}

#[cfg(feature = "serde")]
impl<M, E> ErrShapeUndeclared for &DeclaredShapeProbe<'_, M, E> {
    fn __mx_declared_parts(&self, _prefix: &str) -> Option<ErrParts> {
        None
    }

    fn __mx_declared_shape(&self) -> &'static SerdeErrorShape {
        const NONE: &SerdeErrorShape = &SerdeErrorShape::new();
        NONE
    }
}

/// Internal: the declared-shape stage of [`crate::__mx_result_err_parts!`].
/// Without the `serde` feature it is `None` and `$marker` is never resolved,
/// so a crate without `miniextendr_init!` (a test crate) still compiles.
#[cfg(feature = "serde")]
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_declared_err_parts {
    ($e:ident, $prefix:expr, $marker:ty) => {{
        #[allow(unused_imports)]
        use $crate::condition::{ErrShapeDeclared as _, ErrShapeUndeclared as _};
        (&$crate::condition::DeclaredShapeProbe::<$marker, _>($e, ::core::marker::PhantomData))
            .__mx_declared_parts($prefix)
    }};
}

/// Internal: the declared-shape stage of [`crate::__mx_result_err_parts!`];
/// nothing can be declared without the `serde` feature.
#[cfg(not(feature = "serde"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_declared_err_parts {
    ($e:ident, $prefix:expr, $marker:ty) => {
        ::core::option::Option::None::<$crate::condition::ErrParts>
    };
}

/// Internal: the shape `serde_error_shape!` declared for the type of `$e`
/// under `$marker`, or one that sets nothing. It leads the shape list of a
/// `#[miniextendr(serde_error(..))]` `Err` arm.
#[cfg(feature = "serde")]
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_declared_serde_shape {
    ($e:expr, $marker:ty) => {{
        #[allow(unused_imports)]
        use $crate::condition::{ErrShapeDeclared as _, ErrShapeUndeclared as _};
        (&$crate::condition::DeclaredShapeProbe::<$marker, _>(&$e, ::core::marker::PhantomData))
            .__mx_declared_shape()
    }};
}

/// Internal: without the `serde` feature, a shape that sets nothing.
/// `serde_error(..)` needs the feature anyway: its `serde_err_parts` call
/// reports that, and `$marker` is never resolved.
#[cfg(not(feature = "serde"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __mx_declared_serde_shape {
    ($e:expr, $marker:ty) => {{
        const NONE: &$crate::condition::SerdeErrorShape =
            &$crate::condition::SerdeErrorShape::new();
        NONE
    }};
}

// endregion

// region: from_tagged_sexp + repanic_if_rust_error — shim re-panic helpers

impl RCondition {
    /// Reconstruct an [`RCondition::Error`] from a tagged SEXP produced by
    /// [`crate::error_value::make_rust_condition_value`].
    ///
    /// Returns `Some(RCondition)` when `sexp` has class `"rust_condition_value"` AND
    /// the `"__rust_condition__"` attribute is `TRUE`. Returns `None` for all other
    /// SEXPs (normal return values, `R_NilValue`, etc.).
    ///
    /// Reconstructs the matching variant for each kind: `"error"`/`"panic"`/
    /// `"result_err"`/`"none_err"`/`"other_rust_error"` →
    /// [`RCondition::Error`] (class, message, data and a [`ConditionCall::None`]
    /// choice kept; the kind itself is not carried by the variant);
    /// `"conversion"` → [`RCondition::Conversion`], so an argument error keeps
    /// `kind = "conversion"` across a package boundary (and an
    /// [`crate::arg_error!`] its class marker, which the consumer's wrapper
    /// resolves); `"warning"` → [`RCondition::Warning`]; `"message"` →
    /// [`RCondition::Message`]; `"condition"` → [`RCondition::Condition`].
    /// Unknown kinds degrade to [`RCondition::Error`] with the kind string
    /// prefixed to the message.
    ///
    /// # Safety
    ///
    /// Must be called from R's main thread.
    pub unsafe fn from_tagged_sexp(sexp: crate::SEXP) -> Option<Self> {
        use crate::SexpExt;
        use crate::from_r::TryFromSexp;

        // Use SexpExt::inherits_class — wraps Rf_inherits, already main-thread.
        if !sexp.inherits_class(c"rust_condition_value") {
            return None;
        }

        // Belt-and-suspenders PROTECT across the full inspection window. The reads
        // below are nominally non-allocating, but R-devel's GC is aggressive enough
        // (see MEMORY.md "Common gotchas") that a defensive guard is cheap and
        // closes the door on subtle regressions if the read path ever changes.
        let _guard = unsafe { crate::gc_protect::OwnedProtect::new(sexp) };

        // Verify the __rust_condition__ marker attribute is TRUE (a length-1 LGLSXP
        // with value 1). This guards against coincidental class attribute collisions.
        let attr_sym = crate::cached_class::rust_condition_attr_symbol();
        let marker = sexp.get_attr(attr_sym);
        // marker should be a scalar logical TRUE: is_logical() and logical_elt(0) == 1
        if !marker.is_logical() || marker.logical_elt(0) != 1 {
            return None;
        }

        // It's a tagged SEXP. Read the elements.
        // Both 3-element (legacy) and 4-element (condition) forms have:
        //   [0] = error message (STRSXP)
        //   [1] = kind string (STRSXP)
        //   [2] = class name or NULL (only in 4-element form; absent in legacy)

        let len = sexp.len();

        // Defense-in-depth: a tagged SEXP must have at least the message and kind
        // slots. inherits_class + __rust_condition__ marker should already imply this,
        // but a corrupted/spoofed SEXP that satisfies both checks shouldn't OOB
        // the vector_elt reads below.
        if len < 2 {
            return None;
        }

        let msg_sexp = sexp.vector_elt(0);
        let msg: String = msg_sexp
            .string_elt_str(0)
            .unwrap_or("<invalid error message>")
            .to_string();

        let kind_sexp = sexp.vector_elt(1);
        let kind: &str = kind_sexp
            .string_elt_str(0)
            .unwrap_or(crate::error_value::kind::PANIC);

        // Class slot is element [2] in the 4-element form (NULL in legacy form):
        // a STRSXP of any length (the user class vector, family last).
        let class: Vec<String> = if len >= 4 {
            let class_sexp = sexp.vector_elt(2);
            if class_sexp.is_nil() || !class_sexp.is_character() {
                Vec::new()
            } else {
                (0..class_sexp.len() as isize)
                    .filter_map(|i| class_sexp.string_elt_str(i).map(str::to_string))
                    .collect()
            }
        } else {
            Vec::new()
        };

        use crate::error_value::kind as kind_const;

        // Slot [4] is the optional named-list condition data, present when `len >= 5`.
        //
        // Each field value is decoded through the single SEXP→owned-tree walker,
        // [`RValue::try_from_sexp`], so structured fields survive the cross-package
        // trait-ABI re-panic path (`repanic_if_rust_error`): the consumer's outer
        // `with_r_unwind_protect` guard rebuilds the tagged SEXP from the
        // reconstructed `RCondition`, which now carries the data — so `e$field_name`
        // is accessible in R handlers even when the error crossed a package boundary.
        //
        // `RValue` is NA-aware (logical/integer/character carry `None`; double
        // carries the `NA_REAL` bit), so NA-bearing fields now round-trip faithfully
        // rather than being dropped. Fields whose name is missing/empty, or whose
        // value is not R data (closures, environments, …, which `try_from_sexp`
        // rejects) are dropped — safe degradation that preserves message/class/kind.
        //
        // All reads here are non-allocating copies into owned Rust values, so no new
        // SEXPs are created and the existing `_guard` OwnedProtect suffices.
        let data: Option<ConditionData> = if len >= 5 {
            let data_sexp = sexp.vector_elt(4);
            if data_sexp.is_nil() || !data_sexp.is_list() {
                None
            } else {
                let data_len = data_sexp.len();
                let names_sexp = data_sexp.get_names();
                let mut fields: ConditionData = Vec::with_capacity(data_len);
                for i in 0..data_len as isize {
                    // Read the field name from the names attribute. If missing/empty, skip.
                    let name: String = if names_sexp.is_nil() || !names_sexp.is_character() {
                        continue;
                    } else {
                        match names_sexp.string_elt_str(i) {
                            Some(s) if !s.is_empty() => s.to_string(),
                            _ => continue,
                        }
                    };
                    if let Ok(value) = crate::RValue::try_from_sexp(data_sexp.vector_elt(i)) {
                        fields.push((name, value));
                    }
                }
                if fields.is_empty() {
                    None
                } else {
                    Some(fields)
                }
            }
        } else {
            None
        };

        // Slot [3] is the call. Only the "no call" marker (`FALSE`, see
        // `make_rust_condition_value_with_data`) survives the re-panic: a call
        // object captured by the producer names the vtable shim's frame, and the
        // consumer's outer guard attributes the condition to its own call.
        let call = if len >= 4 && is_no_call_marker(sexp.vector_elt(3)) {
            ConditionCall::None
        } else {
            ConditionCall::Inherit
        };

        let cond = match kind {
            kind_const::ERROR
            | kind_const::PANIC
            | kind_const::RESULT_ERR
            | kind_const::NONE_ERR
            | kind_const::OTHER_RUST_ERROR => RCondition::Error {
                message: msg,
                class,
                data,
                call,
            },
            kind_const::CONVERSION => RCondition::Conversion {
                message: msg,
                class,
                data,
                call,
            },
            kind_const::WARNING => RCondition::Warning {
                message: msg,
                class,
                data,
                call,
            },
            kind_const::MESSAGE => RCondition::Message {
                message: msg,
                class,
                data,
                call,
            },
            kind_const::CONDITION => RCondition::Condition {
                message: msg,
                class,
                data,
                call,
            },
            other => {
                // Unknown kind — degrade to error
                RCondition::Error {
                    message: format!("[{other}] {msg}"),
                    class,
                    data,
                    call,
                }
            }
        };
        Some(cond)
    }
}

/// `true` for the tagged value's "no call" marker in the `call` slot: a
/// length-1 logical `FALSE` ([`ConditionCall::None`]). A call object or `NULL`
/// is not the marker.
fn is_no_call_marker(call: crate::SEXP) -> bool {
    use crate::SexpExt;
    call.is_logical() && call.len() == 1 && call.logical_elt(0) == 0
}

/// Inspect a SEXP returned by a trait-ABI vtable shim and, if it is a tagged
/// error value, re-panic with the reconstructed [`enum@RCondition`].
///
/// This is the "re-panic at the View boundary" step of Approach 1 from the
/// issue-345 plan. The caller (a generated View method wrapper) does:
///
/// ```ignore
/// let result = { vtable_call };
/// ::miniextendr_api::trait_abi::repanic_if_rust_error(result);
/// // ... convert result normally if we reach here
/// ```
///
/// When `sexp` is a tagged error value:
/// - `RCondition::Error` / `RCondition::Warning` / etc. → `panic_any!(cond)`.
///   The outer `with_r_unwind_protect` in the consumer's C entry point will
///   catch this and produce a tagged SEXP for the consumer's R wrapper.
///
/// When `sexp` is a normal value: this is a no-op.
///
/// # Safety
///
/// Must be called from R's main thread. `sexp` must be a valid (possibly
/// tagged) SEXP.
pub unsafe fn repanic_if_rust_error(sexp: crate::SEXP) {
    if let Some(cond) = unsafe { RCondition::from_tagged_sexp(sexp) } {
        std::panic::panic_any(cond);
    }
}

// endregion

// region: AsRError struct — wraps std::error::Error for Result returns

/// Structured error wrapper that preserves the `std::error::Error` cause chain.
///
/// When displayed, formats the error message with its full source chain:
/// ```text
/// top-level message
///   caused by: middle error
///   caused by: root cause
/// ```
///
/// Implements `From<E>` so it works with `?` and `.map_err(AsRError)`.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::condition::AsRError;
/// use std::num::ParseIntError;
///
/// #[miniextendr]
/// fn parse_number(s: &str) -> Result<i32, AsRError<ParseIntError>> {
///     s.parse::<i32>().map_err(AsRError)
/// }
/// ```
pub struct AsRError<E: std::error::Error>(pub E);

impl<E: std::error::Error> From<E> for AsRError<E> {
    #[inline]
    fn from(err: E) -> Self {
        AsRError(err)
    }
}

impl<E: std::error::Error> std::fmt::Display for AsRError<E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Write the top-level message
        write!(f, "{}", self.0)?;

        // Walk the cause chain
        let mut current: &dyn std::error::Error = &self.0;
        while let Some(source) = current.source() {
            write!(f, "\n  caused by: {source}")?;
            current = source;
        }

        Ok(())
    }
}

impl<E: std::error::Error> std::fmt::Debug for AsRError<E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "AsRError<{}>({})", std::any::type_name::<E>(), self)
    }
}

impl<E: std::error::Error> AsRError<E> {
    /// Get the inner error.
    #[inline]
    pub fn into_inner(self) -> E {
        self.0
    }

    /// Get the Rust type name of the wrapped error (for programmatic matching).
    #[inline]
    pub fn rust_type_name(&self) -> &'static str {
        std::any::type_name::<E>()
    }

    /// Collect the full cause chain as a `Vec<String>`.
    pub fn cause_chain(&self) -> Vec<String> {
        let mut chain = vec![self.0.to_string()];
        let mut current: &dyn std::error::Error = &self.0;
        while let Some(source) = current.source() {
            chain.push(source.to_string());
            current = source;
        }
        chain
    }
}

// endregion

// region: Tests — macro grammar + payload contents (no R runtime needed)

#[cfg(test)]
mod condition_macro_tests {
    use super::{ConditionData, RCondition};
    use crate::RValue;

    /// The marker type of a crate that declares no `serde_error_shape!`, for
    /// the `Err` probe's marker argument (resolved only under `serde`).
    #[cfg(feature = "serde")]
    enum NoShapes {}

    /// Catch the `panic_any(RCondition)` raised by a macro invocation and
    /// return the payload. No R runtime needed — the macros panic before any
    /// R API call.
    fn catch(f: impl FnOnce() + std::panic::UnwindSafe) -> RCondition {
        let payload = std::panic::catch_unwind(f).expect_err("macro must panic");
        *payload
            .downcast::<RCondition>()
            .expect("payload must be RCondition")
    }

    fn assert_data(data: &Option<ConditionData>, expected: &[(&str, RValue)]) {
        let data = data.as_ref().expect("data must be Some");
        assert_eq!(data.len(), expected.len());
        for ((name, value), (exp_name, exp_value)) in data.iter().zip(expected) {
            assert_eq!(name, exp_name);
            // RValue has no PartialEq (f64); compare via Debug.
            assert_eq!(format!("{value:?}"), format!("{exp_value:?}"));
        }
    }

    /// `catch_condition` returns every condition kind as `Err` with its
    /// classes and data, and the value on success.
    #[test]
    fn catch_condition_returns_each_kind() {
        use super::catch_condition;
        use crate::error_value::kind;
        assert_eq!(catch_condition(|| 3).unwrap(), 3);
        let error = catch_condition::<()>(|| {
            crate::error!(
                class = ["member", "family"],
                data = ("n", 2),
                "failed {}",
                1
            )
        })
        .unwrap_err();
        let (error_kind, parts) = error.into_parts();
        assert_eq!(error_kind, kind::ERROR);
        assert_eq!(parts.message, "failed 1");
        assert_eq!(parts.class, ["member", "family"]);
        assert_data(&parts.data, &[("n", RValue::from(2))]);
        let kinds = [
            catch_condition::<()>(|| crate::warning!("w")),
            catch_condition::<()>(|| crate::message!("m")),
            catch_condition::<()>(|| crate::condition!("c")),
            catch_condition::<()>(|| {
                RCondition::arg_error("x", "bad".to_string(), super::ConditionCall::Inherit).raise()
            }),
        ]
        .map(|caught| caught.unwrap_err().into_parts().0);
        assert_eq!(
            kinds,
            [
                kind::WARNING,
                kind::MESSAGE,
                kind::CONDITION,
                kind::CONVERSION
            ]
        );
    }

    /// Any other payload, a plain `panic!()` included, resumes unchanged.
    #[test]
    fn catch_condition_resumes_other_panics() {
        use super::catch_condition;
        struct Foreign(u8);
        let payload = std::panic::catch_unwind(|| catch_condition::<()>(|| panic!("plain")))
            .expect_err("a plain panic must resume");
        assert_eq!(payload.downcast_ref::<&str>(), Some(&"plain"));
        let payload = std::panic::catch_unwind(|| {
            catch_condition::<()>(|| std::panic::panic_any(Foreign(9)))
        })
        .expect_err("a foreign payload must resume");
        assert_eq!(payload.downcast_ref::<Foreign>().map(|f| f.0), Some(9));
    }

    /// `arg_error!` (#1740): the conversion kind, the crate-class marker as
    /// the only class, `param` as the only field, and the call choice.
    #[test]
    fn arg_error_payload() {
        use super::{CONVERSION_ERROR_CLASS_MARKER, ConditionCall};
        let choices = r#""fast", "slow""#;
        let check = |cond: RCondition, call: ConditionCall| {
            let RCondition::Conversion {
                message,
                class,
                data,
                call: got_call,
            } = cond
            else {
                panic!("expected RCondition::Conversion, got {cond:?}");
            };
            assert_eq!(message, r#"'mode' should be one of "fast", "slow""#);
            assert_eq!(class, [CONVERSION_ERROR_CLASS_MARKER]);
            assert_data(&data, &[("param", RValue::from("mode"))]);
            assert_eq!(got_call, call);
        };
        check(
            catch(|| crate::arg_error!(param = "mode", "'mode' should be one of {choices}")),
            ConditionCall::Inherit,
        );
        let param = String::from("mode");
        check(
            catch(move || {
                crate::arg_error!(
                    call = none,
                    param = param,
                    "'mode' should be one of {}",
                    choices
                )
            }),
            ConditionCall::None,
        );
        check(
            catch(|| {
                super::ArgError::new("mode", format!("'mode' should be one of {choices}")).raise()
            }),
            ConditionCall::Inherit,
        );

        let (kind, parts) = catch(|| crate::arg_error!(param = "x", "bad")).into_parts();
        assert_eq!(kind, crate::error_value::kind::CONVERSION);
        assert_eq!(parts.message, "bad");
    }

    /// A raising guard resolves the marker in Rust: the crate's classes take
    /// its place, every other class keeps its position, and with no crate
    /// classes the marker just goes.
    #[test]
    fn raising_guard_resolves_the_conversion_class_marker() {
        use super::CONVERSION_ERROR_CLASS_MARKER as MARKER;
        use super::resolve_conversion_error_class_marker as resolve;
        let class = || vec!["a".to_string(), MARKER.to_string(), "b".to_string()];
        assert_eq!(
            resolve(class(), &["pkg_error_argument", "pkg_error"]),
            ["a", "pkg_error_argument", "pkg_error", "b"]
        );
        assert_eq!(resolve(class(), &[]), ["a", "b"]);
        assert_eq!(
            resolve(vec![MARKER.to_string()], &["pkg_error"]),
            ["pkg_error"]
        );
        assert_eq!(resolve(vec!["a".to_string()], &["pkg_error"]), ["a"]);
    }

    #[test]
    fn error_class_vector_and_keyed_data() {
        let cond = catch(|| {
            crate::error!(
                class = ["member", "family"],
                data = { rule = 1, detail = "inner" },
                "layered"
            )
        });
        match cond {
            RCondition::Error {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "layered");
                assert_eq!(class, vec!["member", "family"]);
                assert_data(
                    &data,
                    &[
                        ("rule", RValue::Integer(vec![Some(1)])),
                        ("detail", RValue::Character(vec![Some("inner".to_string())])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn error_class_vector_from_vec_string() {
        let classes = vec!["a".to_string(), "b".to_string()];
        let cond = catch(move || crate::warning!(class = classes, "w"));
        match cond {
            RCondition::Warning { class, .. } => assert_eq!(class, vec!["a", "b"]),
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn reserved_field_name_runtime_check_panics() {
        let name = String::from("kind");
        let payload = std::panic::catch_unwind(move || crate::error!(data = (name, 1), "x"))
            .expect_err("must panic");
        let msg = payload
            .downcast_ref::<String>()
            .cloned()
            .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
            .expect("plain panic message");
        assert!(msg.contains("reserved"), "got: {msg}");
        assert!(msg.contains("rename"), "got: {msg}");
    }

    #[cfg(feature = "serde")]
    mod serde_err_parts {
        use super::super::{SerdeErrorShape, serde_err_parts};
        use crate::RValue;
        use ::serde::Serialize;

        #[derive(Serialize)]
        #[serde(tag = "kind", rename_all = "snake_case")]
        enum Tagged {
            MissingField { field: String },
            Io,
        }

        impl std::fmt::Display for Tagged {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                match self {
                    Tagged::MissingField { field } => write!(f, "field `{field}` is missing"),
                    Tagged::Io => f.write_str("io"),
                }
            }
        }

        #[derive(Serialize)]
        struct Plain {
            code: i32,
        }

        impl std::fmt::Display for Plain {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                write!(f, "plain {}", self.code)
            }
        }

        #[derive(Serialize)]
        enum Clash {
            Bad { kind: String },
        }

        impl std::fmt::Display for Clash {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("clash")
            }
        }

        #[test]
        fn internally_tagged_variant_becomes_member_class_and_fields_become_data() {
            let parts =
                serde_err_parts(&Tagged::MissingField { field: "id".into() }, "engine", &[]);
            assert_eq!(parts.message, "field `id` is missing");
            assert_eq!(parts.class, ["engine_missing_field", "engine"]);
            let data = parts.data.expect("fields become data");
            assert_eq!(data.len(), 1);
            assert_eq!(data[0].0, "field");
            assert!(
                matches!(&data[0].1, RValue::Character(v) if v == &vec![Some("id".to_string())])
            );
        }

        #[test]
        fn unit_variant_has_classes_but_no_data() {
            let parts = serde_err_parts(&Tagged::Io, "engine", &[]);
            assert_eq!(parts.class, ["engine_io", "engine"]);
            assert!(parts.data.is_none());
        }

        #[test]
        fn value_without_variant_gets_only_the_family_class() {
            let parts = serde_err_parts(&Plain { code: 3 }, "engine", &[]);
            assert_eq!(parts.message, "plain 3");
            assert_eq!(parts.class, ["engine"]);
            let data = parts.data.expect("struct fields become data");
            assert_eq!(data[0].0, "code");
        }

        #[test]
        fn reserved_payload_field_is_rejected() {
            let err = std::panic::AssertUnwindSafe(Clash::Bad { kind: "x".into() });
            let payload = std::panic::catch_unwind(move || {
                serde_err_parts(&err.0, "p", &[&SerdeErrorShape::new().tag("type")])
            })
            .expect_err("must panic");
            let msg = payload
                .downcast_ref::<String>()
                .cloned()
                .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
                .unwrap_or_default();
            assert!(msg.contains("reserved"), "{msg}");
            assert!(msg.contains("`kind`"), "{msg}");
        }

        /// The wrapped-parser-error shape (#1457): a `message` payload field.
        #[derive(Serialize)]
        #[serde(tag = "kind", rename_all = "snake_case")]
        enum Wrapped {
            /// `Display` adds context, so `message` is not redundant.
            Parse {
                message: String,
                line: u32,
            },
            /// `Display` is the field verbatim.
            Echo {
                message: String,
            },
            Bad {
                call: String,
            },
        }

        impl std::fmt::Display for Wrapped {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                match self {
                    Wrapped::Parse { message, line } => write!(f, "line {line}: {message}"),
                    Wrapped::Echo { message } => f.write_str(message),
                    Wrapped::Bad { .. } => f.write_str("bad"),
                }
            }
        }

        fn panic_message(f: impl FnOnce() + std::panic::UnwindSafe) -> String {
            let payload = std::panic::catch_unwind(f).expect_err("must panic");
            payload
                .downcast_ref::<String>()
                .cloned()
                .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
                .unwrap_or_default()
        }

        fn names(parts: &super::super::ErrParts) -> Vec<&str> {
            parts
                .data
                .as_deref()
                .unwrap_or_default()
                .iter()
                .map(|(n, _)| n.as_str())
                .collect()
        }

        #[test]
        fn message_field_equal_to_display_is_dropped_without_options() {
            let parts = serde_err_parts(
                &Wrapped::Echo {
                    message: "boom".into(),
                },
                "p",
                &[],
            );
            assert_eq!(parts.message, "boom");
            assert_eq!(parts.class, ["p_echo", "p"]);
            assert!(parts.data.is_none(), "{:?}", parts.data);
        }

        #[test]
        fn message_field_differing_from_display_is_still_rejected() {
            let err = std::panic::AssertUnwindSafe(Wrapped::Parse {
                message: "unexpected token".into(),
                line: 3,
            });
            let msg = panic_message(move || {
                serde_err_parts(&err.0, "p", &[]);
            });
            assert!(msg.contains("reserved"), "{msg}");
            assert!(msg.contains("`message`"), "{msg}");
        }

        #[test]
        fn skip_drops_the_named_field_and_is_a_no_op_elsewhere() {
            let parts = serde_err_parts(
                &Wrapped::Parse {
                    message: "unexpected token".into(),
                    line: 3,
                },
                "p",
                &[&SerdeErrorShape::new().skip(&["message", "absent"])],
            );
            assert_eq!(parts.message, "line 3: unexpected token");
            assert_eq!(parts.class, ["p_parse", "p"]);
            assert_eq!(names(&parts), ["line"]);

            // `skip` runs before the Display-equality rule; same outcome.
            let parts = serde_err_parts(
                &Wrapped::Echo {
                    message: "boom".into(),
                },
                "p",
                &[&SerdeErrorShape::new().skip(&["message"])],
            );
            assert!(parts.data.is_none());

            // A variant without the skipped field but with another reserved
            // name still fails the reserved-name check.
            let err = std::panic::AssertUnwindSafe(Wrapped::Bad { call: "f()".into() });
            let msg = panic_message(move || {
                serde_err_parts(&err.0, "p", &[&SerdeErrorShape::new().skip(&["message"])]);
            });
            assert!(msg.contains("`call`"), "{msg}");
        }

        #[test]
        fn rename_splices_the_field_under_the_new_name() {
            let parts = serde_err_parts(
                &Wrapped::Parse {
                    message: "unexpected token".into(),
                    line: 3,
                },
                "p",
                &[&SerdeErrorShape::new().rename(&[("message", "detail"), ("absent", "other")])],
            );
            assert_eq!(names(&parts), ["detail", "line"]);
            let data = parts.data.expect("data");
            assert!(matches!(
                &data[0].1,
                RValue::Character(v) if v == &vec![Some("unexpected token".to_string())]
            ));

            // `rename` wins over the Display-equality drop: the caller asked
            // for the field explicitly.
            let parts = serde_err_parts(
                &Wrapped::Echo {
                    message: "boom".into(),
                },
                "p",
                &[&SerdeErrorShape::new().rename(&[("message", "detail")])],
            );
            assert_eq!(names(&parts), ["detail"]);
        }

        /// The probe's second stage under the `serde` feature: an
        /// `E: Serialize + Display` is classed with the defaults and the
        /// macro-supplied prefix; a `String` error gets the family class and
        /// its text unquoted.
        #[test]
        fn err_parts_probe_classes_serialize_display_types() {
            let parts = crate::__mx_result_err_parts!(Tagged::Io, "p", super::NoShapes);
            assert_eq!(parts.message, "io");
            assert_eq!(parts.class, ["p_io", "p"]);
            assert!(parts.data.is_none());

            let parts = crate::__mx_result_err_parts!(
                Tagged::MissingField { field: "id".into() },
                "p",
                super::NoShapes
            );
            assert_eq!(parts.class, ["p_missing_field", "p"]);
            assert_eq!(names(&parts), ["field"]);

            let parts =
                crate::__mx_result_err_parts!(String::from("bad input"), "p", super::NoShapes);
            assert_eq!(parts.message, "bad input");
            assert_eq!(parts.class, ["p"]);
            assert!(parts.data.is_none());

            let parts = crate::__mx_result_err_parts!("static text", "p", super::NoShapes);
            assert_eq!(parts.message, "static text");
            assert_eq!(parts.class, ["p"]);
        }

        /// #1459: a `rename` target the variant already carries would give the
        /// condition two `line` entries; R reads only the first.
        #[test]
        fn rename_onto_a_name_the_variant_carries_panics() {
            let err = std::panic::AssertUnwindSafe(Wrapped::Parse {
                message: "unexpected token".into(),
                line: 3,
            });
            let msg = panic_message(move || {
                serde_err_parts(
                    &err.0,
                    "p",
                    &[&SerdeErrorShape::new().rename(&[("message", "line")])],
                );
            });
            assert!(msg.contains("field `line` appears twice"), "{msg}");
            assert!(msg.contains("`rename(message = \"line\")`"), "{msg}");

            // The same attribute is fine on a variant without `line`.
            let parts = serde_err_parts(
                &Wrapped::Echo {
                    message: "boom".into(),
                },
                "p",
                &[&SerdeErrorShape::new().rename(&[("message", "line")])],
            );
            assert_eq!(names(&parts), ["line"]);
        }

        /// A target that only *another* variant carries is no collision, and
        /// `skip` frees a name for `rename` because both run before the check.
        #[test]
        fn rename_target_is_checked_per_variant_after_skip() {
            let parts = serde_err_parts(
                &Wrapped::Bad { call: "f()".into() },
                "p",
                &[&SerdeErrorShape::new().rename(&[("call", "line")])],
            );
            assert_eq!(names(&parts), ["line"]);

            let parts = serde_err_parts(
                &Wrapped::Parse {
                    message: "unexpected token".into(),
                    line: 3,
                },
                "p",
                &[&SerdeErrorShape::new()
                    .skip(&["line"])
                    .rename(&[("message", "line")])],
            );
            assert_eq!(names(&parts), ["line"]);
            let data = parts.data.expect("data");
            assert!(matches!(
                &data[0].1,
                RValue::Character(v) if v == &vec![Some("unexpected token".to_string())]
            ));
        }
    }

    /// `SerdeErrorShape`'s const checks (#2207). Called at run time here, the
    /// same panics a `const` turns into a compile error.
    mod serde_error_shape_checks {
        use super::super::SerdeErrorShape;

        fn panic_message(f: impl FnOnce() -> SerdeErrorShape + std::panic::UnwindSafe) -> String {
            let payload = std::panic::catch_unwind(f).expect_err("must panic");
            payload
                .downcast_ref::<String>()
                .cloned()
                .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
                .unwrap_or_default()
        }

        #[test]
        fn a_consistent_shape_builds_in_a_const() {
            const ENGINE: SerdeErrorShape = SerdeErrorShape::new()
                .tag("type")
                .prefix("engine")
                .skip(&["message"])
                .rename(&[("source", "cause")])
                .as_character(&["rule", "column", "source"])
                .as_integer(&["n"])
                .as_double(&["rate"])
                .as_logical(&["exact"]);
            assert_ne!(ENGINE, SerdeErrorShape::new());
            assert_eq!(SerdeErrorShape::default(), SerdeErrorShape::new());
        }

        #[test]
        fn a_field_in_two_type_lists_is_refused() {
            let msg = panic_message(|| {
                SerdeErrorShape::new()
                    .as_integer(&["rule", "n"])
                    .as_double(&["n"])
            });
            assert_eq!(
                msg,
                "SerdeErrorShape: field `n` is in both `as_integer` and `as_double`; a field has \
                 one R type"
            );
        }

        #[test]
        fn a_skipped_field_takes_no_type_or_name() {
            let msg = panic_message(|| SerdeErrorShape::new().skip(&["n"]).as_integer(&["n"]));
            assert!(
                msg.contains("field `n` is in both `skip` and `as_integer`"),
                "{msg}"
            );
            let msg = panic_message(|| SerdeErrorShape::new().as_logical(&["n"]).skip(&["n"]));
            assert!(
                msg.contains("field `n` is in both `as_logical` and `skip`"),
                "{msg}"
            );
            let msg = panic_message(|| {
                SerdeErrorShape::new()
                    .skip(&["message"])
                    .rename(&[("message", "detail")])
            });
            assert!(
                msg.contains("field `message` is in both `skip` and `rename`"),
                "{msg}"
            );
            let msg = panic_message(|| {
                SerdeErrorShape::new()
                    .rename(&[("message", "detail")])
                    .skip(&["message"])
            });
            assert!(
                msg.contains("field `message` is in both `rename` and `skip`"),
                "{msg}"
            );
        }

        #[test]
        fn rename_mirrors_the_attribute_grammar() {
            let msg = panic_message(|| SerdeErrorShape::new().rename(&[("detail", "kind")]));
            assert!(msg.contains("target `kind` is reserved"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().rename(&[("a", "b"), ("a", "c")]));
            assert!(msg.contains("field `a` is renamed twice"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().rename(&[("a", "b"), ("c", "b")]));
            assert!(msg.contains("two `rename` pairs target `b`"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().rename(&[("a", "")]));
            assert!(msg.contains("`rename` has an empty name"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().rename(&[]));
            assert!(msg.contains("`rename` needs at least one pair"), "{msg}");
        }

        #[test]
        fn lists_and_options_are_set_once_and_not_empty() {
            let msg = panic_message(|| SerdeErrorShape::new().skip(&["a"]).skip(&["b"]));
            assert!(msg.contains("`skip` is set twice"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().as_double(&["a"]).as_double(&["b"]));
            assert!(msg.contains("`as_double` is set twice"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().prefix("a").prefix("b"));
            assert!(msg.contains("`prefix` is set twice"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().tag(""));
            assert!(msg.contains("`tag` must not be empty"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().as_character(&[]));
            assert!(
                msg.contains("`as_character` needs at least one field"),
                "{msg}"
            );
            let msg = panic_message(|| SerdeErrorShape::new().skip(&[""]));
            assert!(msg.contains("`skip` has an empty field name"), "{msg}");
            let msg = panic_message(|| SerdeErrorShape::new().as_integer(&["n", "n"]));
            assert!(
                msg.contains("field `n` is listed twice in `as_integer`"),
                "{msg}"
            );
        }

        /// The message buffer is 256 bytes; a name it cuts inside a
        /// character falls back to a message without the name.
        #[test]
        fn a_long_field_name_still_panics_with_a_message() {
            // "SerdeErrorShape: field `" is 24 bytes; the buffer ends inside `é`.
            let name: &'static str = Box::leak(format!("{}é", "x".repeat(231)).into_boxed_str());
            let names: &'static [&'static str] = Box::leak(Box::new([name]));
            let msg = panic_message(move || SerdeErrorShape::new().as_integer(names).skip(names));
            assert_eq!(
                msg,
                "SerdeErrorShape: contradictory options; a field name is too long to quote"
            );
        }
    }

    /// The `as_*` options and shape precedence at the condition boundary
    /// (#2207), on a hand-written `Serialize` that uses no field helper.
    #[cfg(feature = "serde")]
    mod serde_error_shape {
        use super::super::{SHAPE_TYPE_OPTIONS, SerdeErrorShape, serde_err_parts};
        use crate::RValue;
        use crate::serde::rvalue_ser::Atomic;

        /// The shape of an error type in a crate that can't depend on
        /// miniextendr: internally tagged by hand.
        struct Engine {
            rule: Vec<String>,
            n: u32,
            rate: i64,
            flags: Vec<Option<bool>>,
        }

        impl ::serde::Serialize for Engine {
            fn serialize<S: ::serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
                use ::serde::ser::SerializeStruct;
                let mut st = s.serialize_struct("Engine", 5)?;
                st.serialize_field("kind", "rule")?;
                st.serialize_field("rule", &self.rule)?;
                st.serialize_field("n", &self.n)?;
                st.serialize_field("rate", &self.rate)?;
                st.serialize_field("flags", &self.flags)?;
                st.end()
            }
        }

        impl std::fmt::Display for Engine {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("rule failed")
            }
        }

        fn engine() -> Engine {
            Engine {
                rule: Vec::new(),
                n: 3,
                rate: 5,
                flags: vec![Some(true), None],
            }
        }

        fn field<'a>(parts: &'a super::super::ErrParts, name: &str) -> &'a RValue {
            parts
                .data
                .as_deref()
                .unwrap_or_default()
                .iter()
                .find(|(n, _)| n == name)
                .map(|(_, v)| v)
                .unwrap_or_else(|| panic!("no field `{name}` in {:?}", parts.data))
        }

        fn panic_message(f: impl FnOnce() + std::panic::UnwindSafe) -> String {
            let payload = std::panic::catch_unwind(f).expect_err("must panic");
            payload
                .downcast_ref::<String>()
                .cloned()
                .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
                .unwrap_or_default()
        }

        #[test]
        fn atomic_order_matches_the_shape_lists() {
            for (atomic, option) in Atomic::ALL.iter().zip(SHAPE_TYPE_OPTIONS) {
                assert_eq!(atomic.helper(), option);
            }
        }

        #[test]
        fn without_options_the_fields_keep_their_usual_serialization() {
            let parts = serde_err_parts(&engine(), "p", &[]);
            assert_eq!(parts.class, ["p_rule", "p"]);
            assert!(matches!(field(&parts, "rule"), RValue::List(v) if v.is_empty()));
            assert!(matches!(field(&parts, "n"), RValue::Integer(v) if v == &[Some(3)]));
            assert!(matches!(field(&parts, "flags"), RValue::List(v) if v.len() == 2));
        }

        #[test]
        fn each_type_option_gives_its_vector() {
            const SHAPE: SerdeErrorShape = SerdeErrorShape::new()
                .as_character(&["rule"])
                .as_double(&["n"])
                .as_integer(&["rate"])
                .as_logical(&["flags"]);
            let parts = serde_err_parts(&engine(), "p", &[&SHAPE]);
            assert!(matches!(field(&parts, "rule"), RValue::Character(v) if v.is_empty()));
            assert!(matches!(field(&parts, "n"), RValue::Double(v) if v == &[3.0]));
            assert!(matches!(field(&parts, "rate"), RValue::Integer(v) if v == &[Some(5)]));
            assert!(matches!(
                field(&parts, "flags"),
                RValue::Logical(v) if v == &[Some(true), None]
            ));
        }

        #[test]
        fn a_value_that_does_not_fit_names_the_field_and_the_option() {
            let shape = SerdeErrorShape::new().as_integer(&["rate"]);
            let err = std::panic::AssertUnwindSafe(Engine {
                rate: 1 << 40,
                ..engine()
            });
            let msg = panic_message(move || {
                serde_err_parts(&err.0, "p", &[&shape]);
            });
            assert_eq!(
                msg,
                "#[miniextendr(serde_error)]: `as_integer` on condition data field `rate` \
                 failed: the field is not an integer that fits an R integer or `None`; the \
                 original error was: rule failed"
            );

            let shape = SerdeErrorShape::new().as_logical(&["rule"]);
            let err = std::panic::AssertUnwindSafe(Engine {
                rule: vec!["a".into(), "b".into()],
                ..engine()
            });
            let msg = panic_message(move || {
                serde_err_parts(&err.0, "p", &[&shape]);
            });
            assert!(
                msg.contains(
                    "`as_logical` on condition data field `rule` failed: the field is not a logical"
                ),
                "{msg}"
            );
        }

        /// The keys are the names as the error serializes them: an `as_*`
        /// option and a `rename` of one field compose.
        #[test]
        fn type_and_rename_compose_on_the_serialized_name() {
            let shape = SerdeErrorShape::new()
                .rename(&[("rule", "rules")])
                .as_character(&["rule"]);
            let parts = serde_err_parts(&engine(), "p", &[&shape]);
            assert!(matches!(field(&parts, "rules"), RValue::Character(v) if v.is_empty()));
        }

        /// The function's options (the last shape) win for each setting of a
        /// field; what only the named shape sets stays.
        #[test]
        fn later_shapes_win_per_field() {
            let named = SerdeErrorShape::new()
                .tag("type")
                .prefix("engine")
                .skip(&["n"])
                .as_integer(&["rate"])
                .rename(&[("rule", "rules")])
                .as_character(&["rule"]);
            let own = SerdeErrorShape::new().tag("kind").as_double(&["n", "rate"]);
            let parts = serde_err_parts(&engine(), "p", &[&named, &own]);
            assert_eq!(parts.class, ["engine_rule", "engine"]);
            assert!(matches!(field(&parts, "n"), RValue::Double(v) if v == &[3.0]));
            assert!(matches!(field(&parts, "rate"), RValue::Double(v) if v == &[5.0]));
            assert!(matches!(field(&parts, "rules"), RValue::Character(v) if v.is_empty()));

            // A later `skip` drops a field the earlier shape typed; a later
            // `rename` keeps the earlier type.
            let named = SerdeErrorShape::new()
                .as_integer(&["n"])
                .as_double(&["rate"]);
            let own = SerdeErrorShape::new()
                .prefix("own")
                .skip(&["rate"])
                .rename(&[("n", "count")]);
            let parts = serde_err_parts(&engine(), "p", &[&named, &own]);
            assert_eq!(parts.class, ["own_rule", "own"]);
            let names: Vec<&str> = parts
                .data
                .as_deref()
                .unwrap_or_default()
                .iter()
                .map(|(n, _)| n.as_str())
                .collect();
            assert_eq!(names, ["rule", "count", "flags"]);
            assert!(matches!(field(&parts, "count"), RValue::Integer(v) if v == &[Some(3)]));

            // A later rename keeps a field an earlier shape skipped.
            let named = SerdeErrorShape::new().skip(&["n"]);
            let own = SerdeErrorShape::new().rename(&[("n", "count")]);
            let parts = serde_err_parts(&engine(), "p", &[&named, &own]);
            assert!(matches!(field(&parts, "count"), RValue::Integer(v) if v == &[Some(3)]));
        }

        /// A field the payload lacks is a no-op, as for `skip` / `rename`.
        #[test]
        fn a_field_the_payload_lacks_is_a_no_op() {
            let shape = SerdeErrorShape::new()
                .as_character(&["column"])
                .as_integer(&["absent"]);
            let parts = serde_err_parts(&engine(), "p", &[&shape]);
            assert_eq!(parts.data.as_deref().unwrap_or_default().len(), 4);
        }
    }

    #[test]
    fn rerror_reserved_field_rejected_at_err_arm() {
        use super::RError;
        let err = std::panic::AssertUnwindSafe(RError::new("m").data("kind", 2));
        let payload =
            std::panic::catch_unwind(move || crate::__mx_result_err_parts!(err.0, "p", NoShapes))
                .expect_err("must panic");
        let msg = payload
            .downcast_ref::<String>()
            .cloned()
            .or_else(|| payload.downcast_ref::<&str>().map(|s| s.to_string()))
            .expect("plain panic message");
        assert!(msg.contains("reserved"), "got: {msg}");
        assert!(msg.contains("`kind`"), "got: {msg}");
    }

    /// The probe's first stage: an `RConditionData` impl wins outright.
    #[test]
    fn err_parts_probe_prefers_rconditionerror() {
        use super::RError;
        let e = RError::new("m")
            .class(["member", "family"])
            .data("input", 1);
        let parts = crate::__mx_result_err_parts!(e, "p", NoShapes);
        assert_eq!(parts.message, "m");
        assert_eq!(parts.class, ["member", "family"]);
        assert_eq!(parts.data.expect("data")[0].0, "input");
    }

    /// The probe's last resort: a type that is neither `RConditionData` nor
    /// `Serialize` renders with `Debug`, no class, no data.
    #[test]
    fn err_parts_probe_falls_back_to_debug() {
        #[derive(Debug)]
        struct Opaque;
        let parts = crate::__mx_result_err_parts!(Opaque, "p", NoShapes);
        assert_eq!(parts.message, "Opaque");
        assert!(parts.class.is_empty());
        assert!(parts.data.is_none());
    }

    /// The conversion probe's built-in arm (#1591): the framework's own
    /// conversion errors are not `RConditionData`, keep the plain class
    /// vector and no data, and read in R terms instead of their `Display`
    /// text. Other error types still render with `Display` (not `Debug`).
    #[test]
    fn conversion_probe_rewords_builtin_errors() {
        use crate::SEXPTYPE;
        use crate::from_r::{
            SexpClassError, SexpError, SexpLengthError, SexpNaError, SexpTypeError,
        };

        // The probe takes the owned error, as in the generated `Err(e)` arm.
        let message = |e: &SexpError, known: bool| {
            crate::__mx_conversion_err_parts!(e.clone(), known).message
        };

        let e = SexpError::InvalidValue("non-numeric value(s): \"BLQ\" (element 2)".into());
        let parts = crate::__mx_conversion_err_parts!(e, true);
        assert_eq!(parts.message, "non-numeric value(s): \"BLQ\" (element 2)");
        assert!(parts.class.is_empty());
        assert!(parts.data.is_none());
        assert_eq!(message(&e, false), message(&e, true));

        let e = SexpError::Type(SexpTypeError {
            expected: SEXPTYPE::INTSXP,
            actual: SEXPTYPE::STRSXP,
        });
        assert_eq!(message(&e, true), "got character");
        assert_eq!(message(&e, false), "expected integer, got character");
        // The macro states a type error's expectation; the error gives none.
        assert_eq!(e.r_expectation(), None);
        // A class error names the class, as the expectation and in the
        // per-element reason.
        let e = SexpError::Class(SexpClassError {
            expected: "a data frame",
            actual: SEXPTYPE::VECSXP,
        });
        assert_eq!(message(&e, true), "got list");
        assert_eq!(message(&e, false), "expected a data frame, got list");
        assert_eq!(e.r_expectation().as_deref(), Some("a data frame"));
        let e = SexpError::Length(SexpLengthError {
            expected: 1,
            actual: 2,
        });
        assert_eq!(message(&e, true), "got length 2");
        assert_eq!(message(&e, false), "expected length 1, got length 2");
        let e = SexpError::Na(SexpNaError {
            sexp_type: SEXPTYPE::REALSXP,
        });
        assert_eq!(message(&e, true), "NA is not allowed");
        assert_eq!(message(&e, false), "NA is not allowed");
        assert_eq!(
            message(&SexpError::MissingField("id".into()), true),
            "missing field 'id'"
        );
        assert_eq!(
            message(&SexpError::DuplicateName("id".into()), true),
            "duplicate name 'id'"
        );
        // The bare error structs some conversions return take the same arm.
        let e = SexpTypeError {
            expected: SEXPTYPE::REALSXP,
            actual: SEXPTYPE::VECSXP,
        };
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            "got list"
        );
        // The one-argument form is the no-expectation form.
        assert_eq!(
            crate::__mx_conversion_err_parts!(e).message,
            "expected numeric, got list"
        );
        let e = SexpClassError {
            expected: "a data frame",
            actual: SEXPTYPE::INTSXP,
        };
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            "got integer"
        );
        assert_eq!(
            crate::__mx_conversion_err_parts!(e).message,
            "expected a data frame, got integer"
        );

        // `MatchArgError` takes the built-in arm too: R-worded, and after the
        // `one of ...` expectation just the input.
        use crate::match_arg::MatchArgError;
        const CHOICES: &[&str] = &["fast", "slow"];
        let e = MatchArgError::IsNa {
            choices: CHOICES,
            aliases: &[],
        };
        let parts = crate::__mx_conversion_err_parts!(e.clone());
        assert_eq!(parts.message, r#"expected one of "fast", "slow", got NA"#);
        assert!(parts.class.is_empty());
        assert!(parts.data.is_none());
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            "NA is not allowed"
        );
        let e = MatchArgError::NoMatch {
            input: "zzz".into(),
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_err_parts!(e.clone()).message,
            r#"expected one of "fast", "slow", got "zzz""#
        );
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            r#"got "zzz""#
        );
        let e = MatchArgError::InvalidType {
            actual: SEXPTYPE::REALSXP,
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_err_parts!(e.clone()).message,
            r#"expected one of "fast", "slow" (a string or factor), got numeric"#
        );
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            "got numeric"
        );
        let e = MatchArgError::InvalidLength {
            actual: 2,
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            "got length 2"
        );

        // A plain `&str` / `String` error (neither `Serialize`-classed nor
        // `Debug`-quoted, unlike the `Result` probe).
        let parts = crate::__mx_conversion_err_parts!(String::from("bad input"), true);
        assert_eq!(parts.message, "bad input");
        assert!(parts.class.is_empty());
    }

    /// A `match_arg` choice error knows what the value should have been, as a
    /// `MatchArgError` or inside the `SexpError` `#[derive(MatchArg)]`'s
    /// `TryFromSexp` returns; other errors do not (#1594). The prefix built
    /// from it reads like a statically known one.
    #[test]
    fn conversion_expectation_probe_names_match_arg_choices() {
        use super::conversion_prefix;
        use crate::from_r::SexpError;
        use crate::match_arg::MatchArgError;
        let e = MatchArgError::NoMatch {
            input: "zzz".into(),
            choices: &["fast", "slow"],
            aliases: &[],
        };
        let expected = Some(r#"one of "fast", "slow""#.to_string());
        assert_eq!(crate::__mx_conversion_expectation!(e.clone()), expected);
        let e = SexpError::from(e);
        assert_eq!(crate::__mx_conversion_expectation!(e.clone()), expected);
        assert_eq!(
            crate::__mx_conversion_err_parts!(e, true).message,
            r#"got "zzz""#
        );
        assert_eq!(
            crate::__mx_conversion_expectation!(SexpError::InvalidValue("x".into())),
            None
        );
        assert_eq!(
            crate::__mx_conversion_expectation!(String::from("bad input")),
            None
        );

        assert_eq!(
            conversion_prefix("mode", false, expected.as_deref()),
            r#"'mode' must be one of "fast", "slow""#
        );
        assert_eq!(
            conversion_prefix("mode", true, expected.as_deref()),
            r#"'mode' must be NULL or one of "fast", "slow""#
        );
        assert_eq!(conversion_prefix("x", true, None), "invalid 'x' argument");
    }

    /// An `Either` whose arms both refused the kind of value (a type or class
    /// error, a `match_arg` refusal of a non-string, or a nested `Either` of
    /// those) names both arms, as the reason and as the expectation; an arm
    /// that got further gives the reason instead.
    #[cfg(feature = "either")]
    #[test]
    fn either_conversion_names_both_arms_that_refused_the_kind() {
        use crate::SEXPTYPE;
        use crate::from_r::{SexpClassError, SexpError, SexpLengthError, SexpTypeError};
        use crate::match_arg::MatchArgError;

        let either = |l: SexpError, r: SexpError| SexpError::EitherConversion {
            left_error: Box::new(l),
            right_error: Box::new(r),
        };
        let ty = |expected, actual| SexpError::Type(SexpTypeError { expected, actual });
        let frame = |actual| {
            SexpError::Class(SexpClassError {
                expected: "a data frame",
                actual,
            })
        };
        let refused = |actual, choices| {
            SexpError::MatchArg(MatchArgError::InvalidType {
                actual,
                choices,
                aliases: &[],
            })
        };
        const ROUTES: &[&str] = &["oral", "bolus"];
        const MODES: &[&str] = &["fast", "bolus"];
        // (error, reason with the expectation known, reason without it,
        // expectation)
        let check = |e: SexpError, known: &str, unknown: &str, expected: Option<&str>| {
            assert_eq!(e.r_reason(true), known, "{e}");
            assert_eq!(e.r_reason(false), unknown, "{e}");
            assert_eq!(e.r_expectation().as_deref(), expected, "{e}");
        };
        use SEXPTYPE::{INTSXP, LGLSXP, REALSXP, STRSXP, VECSXP};

        check(
            either(ty(INTSXP, REALSXP), ty(STRSXP, REALSXP)),
            "got numeric",
            "expected integer or character, got numeric",
            Some("integer or character"),
        );
        check(
            either(ty(REALSXP, VECSXP), frame(VECSXP)),
            "got list",
            "expected numeric or a data frame, got list",
            Some("numeric or a data frame"),
        );
        check(
            either(frame(INTSXP), ty(STRSXP, INTSXP)),
            "got integer",
            "expected a data frame or character, got integer",
            Some("a data frame or character"),
        );
        check(
            either(refused(LGLSXP, ROUTES), ty(REALSXP, LGLSXP)),
            "got logical",
            r#"expected one of "oral", "bolus", or numeric, got logical"#,
            Some(r#"one of "oral", "bolus", or numeric"#),
        );
        check(
            either(ty(REALSXP, LGLSXP), refused(LGLSXP, ROUTES)),
            "got logical",
            r#"expected numeric or one of "oral", "bolus", got logical"#,
            Some(r#"numeric or one of "oral", "bolus""#),
        );
        // Two choice lists read as one, each choice once.
        check(
            either(refused(REALSXP, ROUTES), refused(REALSXP, MODES)),
            "got numeric",
            r#"expected one of "oral", "bolus", "fast", got numeric"#,
            Some(r#"one of "oral", "bolus", "fast""#),
        );
        // The listed aliases follow the choices, before the other arm; an
        // unlisted one is left out (#2148). Two choice lists keep both
        // lists' aliases, in the order of the joined choices.
        use crate::match_arg::MatchArgAlias;
        const ROUTE_ALIASES: &[MatchArgAlias] = &[
            MatchArgAlias::new("po", "oral"),
            MatchArgAlias::unlisted("iv", "bolus"),
        ];
        const MODE_ALIASES: &[MatchArgAlias] = &[MatchArgAlias::new("quick", "fast")];
        let aliased = |actual, choices, aliases| {
            SexpError::MatchArg(MatchArgError::InvalidType {
                actual,
                choices,
                aliases,
            })
        };
        check(
            either(aliased(LGLSXP, ROUTES, ROUTE_ALIASES), ty(REALSXP, LGLSXP)),
            "got logical",
            r#"expected one of "oral", "bolus" (or "po" for "oral"), or numeric, got logical"#,
            Some(r#"one of "oral", "bolus" (or "po" for "oral"), or numeric"#),
        );
        check(
            either(ty(REALSXP, LGLSXP), aliased(LGLSXP, ROUTES, ROUTE_ALIASES)),
            "got logical",
            r#"expected numeric or one of "oral", "bolus" (or "po" for "oral"), got logical"#,
            Some(r#"numeric or one of "oral", "bolus" (or "po" for "oral")"#),
        );
        check(
            either(
                aliased(REALSXP, MODES, MODE_ALIASES),
                aliased(REALSXP, ROUTES, ROUTE_ALIASES),
            ),
            "got numeric",
            r#"expected one of "fast", "bolus", "oral" (or "quick" for "fast", "po" for "oral"), got numeric"#,
            Some(r#"one of "fast", "bolus", "oral" (or "quick" for "fast", "po" for "oral")"#),
        );
        // A nested `Either` whose arms both refused the kind is one arm.
        let inner = either(refused(VECSXP, ROUTES), ty(REALSXP, VECSXP));
        check(
            either(ty(LGLSXP, VECSXP), inner),
            "got list",
            r#"expected logical or one of "oral", "bolus", or numeric, got list"#,
            Some(r#"logical or one of "oral", "bolus", or numeric"#),
        );

        // A string that matched no choice got further than a type error: its
        // reason, and no joined expectation.
        let no_match = SexpError::MatchArg(MatchArgError::NoMatch {
            input: "zzz".into(),
            choices: ROUTES,
            aliases: &[],
        });
        check(
            either(no_match.clone(), ty(REALSXP, STRSXP)),
            r#"got "zzz""#,
            r#"expected one of "oral", "bolus", got "zzz""#,
            None,
        );
        let length = SexpError::Length(SexpLengthError {
            expected: 1,
            actual: 2,
        });
        check(
            either(refused(REALSXP, ROUTES), length.clone()),
            "got length 2",
            "expected length 1, got length 2",
            None,
        );
        let bad_value = SexpError::InvalidValue("data.frame has no column names".into());
        check(
            either(ty(REALSXP, VECSXP), bad_value.clone()),
            "data.frame has no column names",
            "data.frame has no column names",
            None,
        );
        check(
            either(bad_value, length),
            "data.frame has no column names; got length 2",
            "data.frame has no column names; expected length 1, got length 2",
            None,
        );
        // A nested `Either` that got further is not a kind mismatch.
        check(
            either(ty(LGLSXP, STRSXP), either(no_match, ty(REALSXP, STRSXP))),
            r#"got "zzz""#,
            r#"expected one of "oral", "bolus", got "zzz""#,
            None,
        );
    }

    /// An `Either` parameter is worded side by side from what the wrapper
    /// knows (`from_r::either_expectation`): a known side by its text,
    /// whatever its error, so the text is the same for every failure; an
    /// opaque side by what its type declares, else by what its own error
    /// expected (a kind, the choices of a `match_arg` enum), else by its noun.
    /// `None` only when no side is named by more than its noun.
    #[cfg(feature = "either")]
    #[test]
    fn either_expectation_words_each_side() {
        use crate::SEXPTYPE::{REALSXP, STRSXP, VECSXP};
        use crate::from_r::{
            ExpectedArm, SexpClassError, SexpError, SexpLengthError, SexpTypeError,
            either_expectation,
        };
        use crate::match_arg::MatchArgError;

        let either = |l: SexpError, r: SexpError| SexpError::EitherConversion {
            left_error: Box::new(l),
            right_error: Box::new(r),
        };
        let ty = |expected, actual| SexpError::Type(SexpTypeError { expected, actual });
        let frame = || {
            SexpError::Class(SexpClassError {
                expected: "a data frame",
                actual: REALSXP,
            })
        };
        let length = || {
            SexpError::Length(SexpLengthError {
                expected: 1,
                actual: 2,
            })
        };
        let bad_value = || SexpError::InvalidValue("invalid UUID".into());
        const ROUTES: &[&str] = &["oral", "bolus"];
        let no_match = || {
            SexpError::MatchArg(MatchArgError::NoMatch {
                input: "zzz".into(),
                choices: ROUTES,
                aliases: &[],
            })
        };

        let number = ExpectedArm::Known("a single number");
        let table = ExpectedArm::Known("a data frame");
        let dose = ExpectedArm::Opaque {
            declared: Some("a single number"),
            noun: "a `Dose`",
        };
        let route = ExpectedArm::Opaque {
            declared: None,
            noun: "a `Route`",
        };
        let doc_id = ExpectedArm::Opaque {
            declared: None,
            noun: "a `DocId`",
        };
        let pattern = ExpectedArm::Opaque {
            declared: None,
            noun: "a `Pattern`",
        };
        let words = |arms: &ExpectedArm<'_>, e: SexpError| either_expectation(&e, arms);

        // Known sides: the same text whichever side got further.
        let plain = ExpectedArm::Either(&number, &table);
        for e in [
            either(length(), frame()),
            either(ty(REALSXP, VECSXP), frame()),
        ] {
            assert_eq!(
                words(&plain, e).as_deref(),
                Some("a single number or a data frame")
            );
        }
        // A newtype side declares its inner type's text.
        let newtype = ExpectedArm::Either(&dose, &table);
        assert_eq!(
            words(&newtype, either(length(), frame())).as_deref(),
            Some("a single number or a data frame")
        );
        // An opaque side named by its error: a type error's kind, a
        // `match_arg` enum's choices whether or not the value was a string.
        let by_kind = ExpectedArm::Either(&doc_id, &number);
        assert_eq!(
            words(&by_kind, either(ty(STRSXP, VECSXP), length())).as_deref(),
            Some("character or a single number")
        );
        let choices = ExpectedArm::Either(&route, &number);
        for e in [either(no_match(), frame()), either(no_match(), length())] {
            assert_eq!(
                words(&choices, e).as_deref(),
                Some(r#"one of "oral", "bolus", or a single number"#)
            );
        }
        // An opaque side whose error names nothing: its noun, beside a side
        // that is known.
        assert_eq!(
            words(&by_kind, either(bad_value(), ty(REALSXP, STRSXP))).as_deref(),
            Some("a `DocId` or a single number")
        );
        // `NULL or` an optional side, and a nested `Either` side by side.
        let optional = ExpectedArm::Nullable(&table);
        let nullable = ExpectedArm::Either(&number, &optional);
        assert_eq!(
            words(&nullable, either(length(), frame())).as_deref(),
            Some("a single number or NULL or a data frame")
        );
        let inner = ExpectedArm::Either(&route, &table);
        let nested = ExpectedArm::Either(&number, &inner);
        assert_eq!(
            words(&nested, either(length(), either(no_match(), frame()))).as_deref(),
            Some(r#"a single number or one of "oral", "bolus", or a data frame"#)
        );
        // No side named by more than its noun: no expectation.
        let opaque = ExpectedArm::Either(&doc_id, &pattern);
        assert_eq!(words(&opaque, either(bad_value(), length())), None);
        // An error that is not an `Either` one does not fit the sides.
        assert_eq!(words(&plain, length()), None);
    }

    /// The conversion probe's preferred arm: an `RConditionData` error type
    /// contributes its class vector, message and data.
    #[test]
    fn conversion_probe_prefers_rconditionerror() {
        use super::RError;
        let e = RError::new("must be positive")
            .class(["pkg_bad_arg", "pkg_error"])
            .data("value", -1);
        let parts = crate::__mx_conversion_err_parts!(e, true);
        assert_eq!(parts.message, "must be positive");
        assert_eq!(parts.class, ["pkg_bad_arg", "pkg_error"]);
        assert_eq!(parts.data.expect("data")[0].0, "value");
    }

    /// A reserved data name on a conversion error is rejected like on a
    /// `Result` error, instead of overwriting `e$kind`.
    #[test]
    fn conversion_probe_rejects_reserved_fields() {
        use super::RError;
        let err = std::panic::AssertUnwindSafe(RError::new("m").data("kind", 2));
        let payload = std::panic::catch_unwind(move || crate::__mx_conversion_err_parts!(err.0))
            .expect_err("must panic");
        let msg = payload
            .downcast_ref::<String>()
            .cloned()
            .expect("plain panic message");
        assert!(msg.contains("reserved"), "got: {msg}");
    }

    fn field_names(parts: &super::ErrParts) -> Vec<&str> {
        parts
            .data
            .as_ref()
            .map(|d| d.iter().map(|(n, _)| n.as_str()).collect())
            .unwrap_or_default()
    }

    fn character_field<'a>(parts: &'a super::ErrParts, name: &str) -> Option<&'a str> {
        parts
            .data
            .as_ref()?
            .iter()
            .find(|(n, _)| n == name)
            .and_then(|(_, v)| match v {
                crate::RValue::Character(v) => v.first()?.as_deref(),
                _ => None,
            })
    }

    /// `conversion_err_parts`: the prefix leads the message, the class is
    /// kept, `param` comes first in the data and `rust_type` second.
    #[test]
    fn conversion_err_parts_adds_prefix_param_and_rust_type() {
        use super::{ErrParts, conversion_err_parts};
        use crate::RValue;

        let plain = conversion_err_parts(
            "'dv' must be numeric",
            "dv",
            Some("AsNumericVec"),
            &[],
            ErrParts {
                message: "non-numeric value(s): \"BLQ\" (element 2)".into(),
                class: Vec::new(),
                data: None,
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(
            plain.message,
            "'dv' must be numeric: non-numeric value(s): \"BLQ\" (element 2)"
        );
        assert!(plain.class.is_empty());
        assert_eq!(field_names(&plain), ["param", "rust_type"]);
        assert_eq!(character_field(&plain, "param"), Some("dv"));
        assert_eq!(character_field(&plain, "rust_type"), Some("AsNumericVec"));

        let classed = conversion_err_parts(
            "invalid 'x' argument",
            "x",
            Some("Count"),
            &[],
            ErrParts {
                message: "must be positive".into(),
                class: vec!["pkg_bad_arg".into(), "pkg_error".into()],
                data: Some(vec![("value".into(), RValue::from(-1))]),
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(classed.message, "invalid 'x' argument: must be positive");
        assert_eq!(classed.class, ["pkg_bad_arg", "pkg_error"]);
        assert_eq!(field_names(&classed), ["param", "rust_type", "value"]);

        // Without a Rust type only `param` is added.
        let untyped = conversion_err_parts(
            "'value' must be a number",
            "value",
            None,
            &[],
            ErrParts {
                message: "got \"abc\"".into(),
                class: Vec::new(),
                data: None,
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(untyped.message, "'value' must be a number: got \"abc\"");
        assert_eq!(field_names(&untyped), ["param"]);
    }

    /// An argument error keeps the call whatever the error type's `call()`
    /// says: the R-side checks raise the same condition with the call.
    #[test]
    fn conversion_err_parts_keeps_the_call() {
        use super::{ConditionCall, ErrParts, conversion_err_parts};

        let parts = conversion_err_parts(
            "invalid 'x' argument",
            "x",
            None,
            &[],
            ErrParts {
                message: "bad".into(),
                class: Vec::new(),
                data: None,
                call: ConditionCall::None,
            },
            None,
        );
        assert_eq!(parts.call, ConditionCall::Inherit);
    }

    /// The crate's `conversion_error_class` follows the error's own classes,
    /// skipping those it already names; a plain error gets only the crate's.
    #[test]
    fn conversion_err_parts_appends_the_crate_class() {
        use super::{ErrParts, conversion_err_parts};

        let crate_class = ["pkg_error_argument", "pkg_error"];
        let plain = conversion_err_parts(
            "'x' must be a single integer",
            "x",
            Some("i32"),
            &crate_class,
            ErrParts {
                message: "got character".into(),
                class: Vec::new(),
                data: None,
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(plain.class, ["pkg_error_argument", "pkg_error"]);

        let classed = conversion_err_parts(
            "invalid 'x' argument",
            "x",
            Some("Count"),
            &crate_class,
            ErrParts {
                message: "must be positive".into(),
                class: vec!["pkg_error_negative".into(), "pkg_error".into()],
                data: None,
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(
            classed.class,
            ["pkg_error_negative", "pkg_error", "pkg_error_argument"]
        );
    }

    /// `arg_check_parts`: the message as given, the crate class alone, and
    /// `param` as the only field (no `rust_type`), as the R guard raises it.
    #[test]
    fn arg_check_parts_matches_the_r_guard() {
        use super::arg_check_parts;

        let parts = arg_check_parts("'dv' must not contain NA", "dv", &[]);
        assert_eq!(parts.message, "'dv' must not contain NA");
        assert!(parts.class.is_empty());
        assert_eq!(field_names(&parts), ["param"]);
        assert_eq!(character_field(&parts, "param"), Some("dv"));

        let custom = "`x` can't be NA: 100% \"sure\"\ncaf\u{e9}()";
        let parts = arg_check_parts(custom, "x", &["pkg_error_argument", "pkg_error"]);
        assert_eq!(parts.message, custom);
        assert_eq!(parts.class, ["pkg_error_argument", "pkg_error"]);
        assert_eq!(field_names(&parts), ["param"]);
    }

    /// A `param` or `rust_type` field of the error type's own wins: the
    /// framework's field is not added, so `e$param` / `e$rust_type` read the
    /// type's value.
    #[test]
    fn conversion_err_parts_keeps_the_types_own_fields() {
        use super::{ErrParts, conversion_err_parts};
        use crate::RValue;

        let parts = conversion_err_parts(
            "invalid 'hyper' argument",
            "hyper",
            Some("Hyperparams"),
            &[],
            ErrParts {
                message: "hyperparameter 'beta' must be non-negative".into(),
                class: Vec::new(),
                data: Some(vec![
                    ("value".into(), RValue::from(-2.0)),
                    ("param".into(), RValue::from("beta")),
                ]),
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(field_names(&parts), ["rust_type", "value", "param"]);
        assert_eq!(character_field(&parts, "param"), Some("beta"));

        let parts = conversion_err_parts(
            "invalid 'x' argument",
            "x",
            Some("Wrapped"),
            &[],
            ErrParts {
                message: "bad".into(),
                class: Vec::new(),
                data: Some(vec![("rust_type".into(), RValue::from("Inner"))]),
                call: super::ConditionCall::Inherit,
            },
            None,
        );
        assert_eq!(field_names(&parts), ["param", "rust_type"]);
        assert_eq!(character_field(&parts, "rust_type"), Some("Inner"));
    }

    /// An error that words the whole argument error gives the message in
    /// place of `<prefix>: <reason>`; class and fields are as for any other.
    #[test]
    fn conversion_err_parts_takes_a_whole_message() {
        use super::{ErrParts, conversion_err_parts};

        let parts = conversion_err_parts(
            "'mode' must be one of \"fast\", \"slow\"",
            "mode",
            Some("Mode"),
            &["pkg_error_argument"],
            ErrParts {
                message: "got \"zzz\"".into(),
                class: Vec::new(),
                data: None,
                call: super::ConditionCall::Inherit,
            },
            Some("'mode' should be one of \"fast\", \"slow\"".into()),
        );
        assert_eq!(parts.message, "'mode' should be one of \"fast\", \"slow\"");
        assert_eq!(parts.class, ["pkg_error_argument"]);
        assert_eq!(field_names(&parts), ["param", "rust_type"]);
    }

    /// A `match_arg` choice error, bare or at the top of a `SexpError`, words
    /// the whole argument error as `.miniextendr_match_arg` does (#1767);
    /// other errors do not.
    #[test]
    fn conversion_arg_message_probe_words_match_arg_errors_as_the_check() {
        use crate::SEXPTYPE;
        use crate::from_r::SexpError;
        use crate::match_arg::MatchArgError;

        const CHOICES: &[&str] = &["fast", "slow"];
        let one_of = Some(r#"'mode' should be one of "fast", "slow""#.to_string());
        let no_match = MatchArgError::NoMatch {
            input: "zzz".into(),
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_arg_message!(no_match.clone(), "mode"),
            one_of
        );
        assert_eq!(
            crate::__mx_conversion_arg_message!(SexpError::from(no_match), "mode"),
            one_of
        );
        let na = MatchArgError::IsNa {
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(crate::__mx_conversion_arg_message!(na, "mode"), one_of);
        let long = MatchArgError::InvalidLength {
            actual: 2,
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_arg_message!(SexpError::from(long), "mode").as_deref(),
            Some("'mode' must be of length 1")
        );
        let number = MatchArgError::InvalidType {
            actual: SEXPTYPE::REALSXP,
            choices: CHOICES,
            aliases: &[],
        };
        assert_eq!(
            crate::__mx_conversion_arg_message!(number, "speed").as_deref(),
            Some("'speed' must be NULL or a character vector")
        );

        assert_eq!(
            crate::__mx_conversion_arg_message!(SexpError::InvalidValue("x".into()), "mode"),
            None
        );
        assert_eq!(
            crate::__mx_conversion_arg_message!(String::from("bad input"), "mode"),
            None
        );
    }

    /// A choice error inside an `Either` leaves the message to the `Either`,
    /// which names both arms.
    #[cfg(feature = "either")]
    #[test]
    fn conversion_arg_message_probe_leaves_an_either_alone() {
        use crate::from_r::SexpError;
        use crate::match_arg::MatchArgError;

        let either = SexpError::EitherConversion {
            left_error: Box::new(SexpError::from(MatchArgError::NoMatch {
                input: "zzz".into(),
                choices: &["fast", "slow"],
                aliases: &[],
            })),
            right_error: Box::new(SexpError::InvalidValue("x".into())),
        };
        assert_eq!(crate::__mx_conversion_arg_message!(either, "mode"), None);
    }

    /// A classed error with an `argument_message` words the whole argument
    /// error, directly or carried in a `SexpError` from a type's
    /// `check_sexp`; without one, or inside an `Either`, it does not (#1833).
    #[test]
    fn conversion_arg_message_probe_takes_a_classed_errors_argument_message() {
        use super::{ConditionCall, RConditionData, RError};
        use crate::from_r::SexpError;

        let advice = "use model_from_df() for a data frame";
        let refusal = || {
            RError::new("got a data frame")
                .class("mx_model_refused")
                .argument_message(advice)
        };
        assert_eq!(
            crate::__mx_conversion_arg_message!(refusal(), "fit").as_deref(),
            Some(advice)
        );
        let carried = SexpError::from(refusal());
        assert_eq!(
            crate::__mx_conversion_arg_message!(carried, "fit").as_deref(),
            Some(advice)
        );
        assert_eq!(
            crate::__mx_conversion_arg_message!(RError::new("got a data frame"), "fit"),
            None
        );
        assert_eq!(
            crate::__mx_conversion_arg_message!(SexpError::from(RError::new("no")), "fit"),
            None
        );

        // A hand-written impl answers through the trait method.
        struct ModelRefused;
        impl RConditionData for ModelRefused {
            fn message(&self) -> String {
                "got a data frame".into()
            }
            fn argument_message(&self) -> Option<String> {
                Some("use model_from_df() for a data frame".into())
            }
        }
        assert_eq!(
            crate::__mx_conversion_arg_message!(ModelRefused, "fit").as_deref(),
            Some(advice)
        );
        // The conversion into `SexpError` keeps it, and the call choice.
        let SexpError::Condition(kept) = SexpError::from(ModelRefused) else {
            panic!("a classed error converts into SexpError::Condition");
        };
        assert_eq!(kept.argument_message_str(), Some(advice));
        assert!(matches!(kept.call(), ConditionCall::Inherit));
    }

    /// A type's refusal inside an `Either` leaves the message to the
    /// `Either`, which names both arms.
    #[cfg(feature = "either")]
    #[test]
    fn conversion_arg_message_probe_leaves_a_classed_refusal_in_an_either_alone() {
        use super::RError;
        use crate::from_r::SexpError;

        let either = SexpError::EitherConversion {
            left_error: Box::new(SexpError::from(
                RError::new("got a data frame").argument_message("use model_from_df()"),
            )),
            right_error: Box::new(SexpError::InvalidValue("x".into())),
        };
        assert_eq!(crate::__mx_conversion_arg_message!(either, "fit"), None);
    }

    #[test]
    fn rerror_builder_and_from_error() {
        use super::{RConditionData, RError};
        let e: RError = "x".parse::<i32>().unwrap_err().into();
        let e = e.class(["member", "family"]).data("input", "x");
        assert!(e.message_str().contains("invalid digit"));
        assert_eq!(RConditionData::class(&e), vec!["member", "family"]);
        let data = RConditionData::data(&e).expect("data");
        assert_eq!(data[0].0, "input");

        assert!(RConditionData::data(&RError::new("m")).is_none());
        assert!(super::is_reserved_condition_field("call"));
        assert!(!super::is_reserved_condition_field("calls"));
    }

    #[test]
    fn error_message_only_backcompat() {
        let cond = catch(|| crate::error!("plain {}", 42));
        match cond {
            RCondition::Error {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "plain 42");
                assert!(class.is_empty());
                assert!(data.is_none());
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn error_class_only_backcompat() {
        let cond = catch(|| crate::error!(class = "my_error", "missing field: {}", "x"));
        match cond {
            RCondition::Error {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "missing field: x");
                assert_eq!(class, vec!["my_error"]);
                assert!(data.is_none());
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn error_single_data_pair() {
        let value = 41_i32;
        let cond = catch(move || crate::error!(data = ("value", value), "v = {value}"));
        match cond {
            RCondition::Error {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "v = 41");
                assert!(class.is_empty());
                assert_data(&data, &[("value", RValue::Integer(vec![Some(41)]))]);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn error_class_and_data_list_all_value_types() {
        let cond = catch(|| {
            crate::error!(
                class = "validation_error",
                data = [
                    ("value", 1.5),
                    ("code", 7),
                    ("label", "lhs"),
                    ("fatal", false),
                    ("ints", vec![1, 2]),
                    ("reals", vec![0.5_f64]),
                    ("flags", vec![true]),
                    ("labels", vec!["a".to_string()])
                ],
                "out of range"
            )
        });
        match cond {
            RCondition::Error {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "out of range");
                assert_eq!(class, vec!["validation_error"]);
                assert_data(
                    &data,
                    &[
                        ("value", RValue::Double(vec![1.5])),
                        ("code", RValue::Integer(vec![Some(7)])),
                        ("label", RValue::Character(vec![Some("lhs".into())])),
                        ("fatal", RValue::Logical(vec![Some(false)])),
                        ("ints", RValue::Integer(vec![Some(1), Some(2)])),
                        ("reals", RValue::Double(vec![0.5])),
                        ("flags", RValue::Logical(vec![Some(true)])),
                        ("labels", RValue::Character(vec![Some("a".into())])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn warning_with_class_and_data() {
        let cond = catch(|| crate::warning!(class = "trunc", data = ("dropped", 3), "dropped"));
        match cond {
            RCondition::Warning {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "dropped");
                assert_eq!(class, vec!["trunc"]);
                assert_data(&data, &[("dropped", RValue::Integer(vec![Some(3)]))]);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn message_with_data() {
        let cond = catch(|| crate::message!(data = ("step", 2), "step {}", 2));
        match cond {
            RCondition::Message { message, data, .. } => {
                assert_eq!(message, "step 2");
                assert_data(&data, &[("step", RValue::Integer(vec![Some(2)]))]);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn condition_with_class_and_data() {
        let cond =
            catch(|| crate::condition!(class = "progress", data = [("n", 10)], "processed {}", 10));
        match cond {
            RCondition::Condition {
                message,
                class,
                data,
                call: super::ConditionCall::Inherit,
            } => {
                assert_eq!(message, "processed 10");
                assert_eq!(class, vec!["progress"]);
                assert_data(&data, &[("n", RValue::Integer(vec![Some(10)]))]);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn call_none_on_every_condition_macro() {
        use super::ConditionCall;

        match catch(|| crate::error!(call = none, "plain {}", 1)) {
            RCondition::Error {
                message,
                class,
                data,
                call,
            } => {
                assert_eq!(message, "plain 1");
                assert!(class.is_empty());
                assert!(data.is_none());
                assert_eq!(call, ConditionCall::None);
            }
            other => panic!("wrong variant: {other:?}"),
        }
        match catch(|| crate::rust_error!(call = none, class = ["member", "family"], "e")) {
            RCondition::Error { class, call, .. } => {
                assert_eq!(class, vec!["member", "family"]);
                assert_eq!(call, ConditionCall::None);
            }
            other => panic!("wrong variant: {other:?}"),
        }
        match catch(|| {
            crate::warning!(
                call = none,
                class = "pkg_override",
                data = { profile = 3 },
                "overrides an earlier row"
            )
        }) {
            RCondition::Warning {
                message,
                class,
                data,
                call,
            } => {
                assert_eq!(message, "overrides an earlier row");
                assert_eq!(class, vec!["pkg_override"]);
                assert_data(&data, &[("profile", RValue::Integer(vec![Some(3)]))]);
                assert_eq!(call, ConditionCall::None);
            }
            other => panic!("wrong variant: {other:?}"),
        }
        match catch(|| crate::condition!(call = none, data = ("n", 1), "tick")) {
            RCondition::Condition { data, call, .. } => {
                assert_data(&data, &[("n", RValue::Integer(vec![Some(1)]))]);
                assert_eq!(call, ConditionCall::None);
            }
            other => panic!("wrong variant: {other:?}"),
        }
        match catch(|| crate::rust_condition!(call = none, "tick")) {
            RCondition::Condition { call, .. } => assert_eq!(call, ConditionCall::None),
            other => panic!("wrong variant: {other:?}"),
        }
        // Without `call = none` the call is inherited.
        match catch(|| crate::warning!("sibling")) {
            RCondition::Warning { call, .. } => assert_eq!(call, ConditionCall::Inherit),
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn rerror_without_call_reaches_the_err_parts() {
        use super::{ConditionCall, RConditionData, RError};

        let plain = RError::new("m").class("c");
        assert_eq!(RConditionData::call(&plain), ConditionCall::Inherit);
        let callless = plain.clone().without_call();
        assert_eq!(RConditionData::call(&callless), ConditionCall::None);
        let parts = crate::__mx_result_err_parts!(callless, "pkg_error", NoShapes);
        assert_eq!(parts.call, ConditionCall::None);
        assert_eq!(parts.class, vec!["c"]);
        let parts = crate::__mx_result_err_parts!(plain, "pkg_error", NoShapes);
        assert_eq!(parts.call, ConditionCall::Inherit);
    }

    #[test]
    fn data_list_trailing_comma() {
        let cond = catch(|| crate::error!(data = [("a", 1), ("b", 2),], "msg"));
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[
                        ("a", RValue::Integer(vec![Some(1)])),
                        ("b", RValue::Integer(vec![Some(2)])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    // region: keyed builder sugar (ported from #1044/#995)

    #[test]
    fn keyed_builder_arm_stringifies_idents() {
        let cond = catch(|| crate::error!(data = { value = 42, code = 7 }, "boom"));
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[
                        ("value", RValue::Integer(vec![Some(42)])),
                        ("code", RValue::Integer(vec![Some(7)])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn keyed_builder_arm_trailing_comma_and_mixed_types() {
        let cond = catch(|| {
            crate::warning!(
                class = "trunc",
                data = { dropped = 3, ratio = 0.5_f64, tag = "rows", },
                "dropped some"
            )
        });
        match cond {
            RCondition::Warning { data, class, .. } => {
                assert_eq!(class, vec!["trunc"]);
                assert_data(
                    &data,
                    &[
                        ("dropped", RValue::Integer(vec![Some(3)])),
                        ("ratio", RValue::Double(vec![0.5])),
                        ("tag", RValue::Character(vec![Some("rows".into())])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    // endregion

    // region: NA-aware + wide-int + debug value types via the macro (#995)

    #[test]
    fn option_scalar_fields_carry_na() {
        let cond = catch(|| {
            crate::error!(
                data = [("present", Some(9_i32)), ("missing", None::<i32>)],
                "opts"
            )
        });
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[
                        ("present", RValue::Integer(vec![Some(9)])),
                        ("missing", RValue::Integer(vec![None])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn vec_option_field_carries_embedded_na() {
        let cond =
            catch(|| crate::error!(data = ("codes", vec![Some(1_i32), None, Some(3)]), "vec"));
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[("codes", RValue::Integer(vec![Some(1), None, Some(3)]))],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn wide_integer_ladder_via_macro() {
        // Fits in i32 → integer; beyond → double.
        let cond = catch(|| {
            crate::error!(
                data = [("small", 42_i64), ("big", 5_000_000_000_i64)],
                "wide"
            )
        });
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[
                        ("small", RValue::Integer(vec![Some(42)])),
                        ("big", RValue::Double(vec![5_000_000_000.0])),
                    ],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn debug_fallback_via_macro() {
        let cond = catch(|| crate::error!(data = ("range", RValue::debug(0..=100)), "dbg"));
        match cond {
            RCondition::Error { data, .. } => {
                assert_data(
                    &data,
                    &[("range", RValue::Character(vec![Some("0..=100".into())]))],
                );
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    // endregion
}

// endregion