errlanes/

fail.rs

use std::{error::Error, fmt};

use crate::profile::{AllLanes, LaneProfile, NarrowDenied, NarrowTransient};

use crate::lane::{Denied, Fatal, Lane, Transient};

/// Operator level, independent of any tracing dependency in the core API.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Level {
    Trace,
    Debug,
    Info,
    Warn,
    Error,
}

impl Level {
    /// The upper-case name written to the `error.level` span field.
    pub fn as_str(self) -> &'static str {
        match self {
            Level::Trace => "TRACE",
            Level::Debug => "DEBUG",
            Level::Info => "INFO",
            Level::Warn => "WARN",
            Level::Error => "ERROR",
        }
    }
}

#[cfg(feature = "tracing")]
impl From<Level> for tracing::Level {
    fn from(level: Level) -> Self {
        match level {
            Level::Trace => tracing::Level::TRACE,
            Level::Debug => tracing::Level::DEBUG,
            Level::Info => tracing::Level::INFO,
            Level::Warn => tracing::Level::WARN,
            Level::Error => tracing::Level::ERROR,
        }
    }
}

/// One code a rejection family can resolve to, with its operator-facing text.
///
/// ```
/// use errlanes::{CodeInfo, Rejection, RejectionCode};
///
/// fn describe<R: Rejection>() -> Vec<String> {
///     <R::Code as RejectionCode>::CODES
///         .iter()
///         .map(|CodeInfo { code, description }| {
///             format!("{code}: {}", description.unwrap_or("(undocumented)"))
///         })
///         .collect()
/// }
/// # fn main() {}
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CodeInfo {
    /// The wire identity, exactly what `Into<&'static str>` on the `Code` yields.
    pub code: &'static str,
    /// From `#[rejection(description = "..")]`, else the first paragraph of
    /// the leaf's `///` doc comment, else `None`. Never the `#[error("..")]`
    /// literal: that is a `Display` template, not prose.
    pub description: Option<&'static str>,
}

/// The code type of a rejection family: a closed, enumerable catalogue.
///
/// ```
/// use errlanes::RejectionCode;
///
/// /// The thing is missing.
/// #[derive(errlanes::Rejection, Debug)]
/// #[rejection(code = "NOT_FOUND")]
/// #[error("the thing is missing")]
/// struct NotFound;
///
/// for entry in <NotFoundCode as RejectionCode>::CODES {
///     assert_eq!(entry.code, "NOT_FOUND");
///     assert_eq!(entry.description, Some("The thing is missing."));
/// }
/// ```
pub trait RejectionCode:
    Copy + Eq + std::hash::Hash + fmt::Debug + fmt::Display + Into<&'static str> + Send + Sync + 'static
{
    /// Every code a value of this type can resolve to — complete through
    /// `delegate`, `code_and_level_from`, and `#[lift(..)]`-forwarded
    /// variants; no duplicates (a diamond keeps its first occurrence);
    /// declaration order, depth-first.
    const CODES: &'static [CodeInfo];
}

/// Const helpers the derive uses to build a deduplicated catalogue.
#[doc(hidden)]
pub mod __catalogue {
    use super::CodeInfo;

    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
    }

    /// Whether `code` is already among the first `taken` distinct entries
    /// found by walking `parts` in order (used to implement first-wins).
    const fn seen_before(parts: &[&[CodeInfo]], part: usize, idx: usize) -> bool {
        let code = parts[part][idx].code;
        let mut p = 0;
        while p <= part {
            let end = if p == part { idx } else { parts[p].len() };
            let mut i = 0;
            while i < end {
                if str_eq(parts[p][i].code, code) {
                    return true;
                }
                i += 1;
            }
            p += 1;
        }
        false
    }

    /// Count of distinct `code`s across `parts`, first occurrence wins.
    pub const fn catalogue_len(parts: &[&[CodeInfo]]) -> usize {
        let mut n = 0;
        let mut p = 0;
        while p < parts.len() {
            let mut i = 0;
            while i < parts[p].len() {
                if !seen_before(parts, p, i) {
                    n += 1;
                }
                i += 1;
            }
            p += 1;
        }
        n
    }

    /// The distinct entries of `parts` in declaration order. `N` must equal
    /// [`catalogue_len`]; a mismatch is a const-eval (compile) error.
    pub const fn catalogue<const N: usize>(parts: &[&[CodeInfo]]) -> [CodeInfo; N] {
        assert!(catalogue_len(parts) == N, "catalogue length mismatch");
        let mut out = [CodeInfo {
            code: "",
            description: None,
        }; N];
        let mut n = 0;
        let mut p = 0;
        while p < parts.len() {
            let mut i = 0;
            while i < parts[p].len() {
                if !seen_before(parts, p, i) {
                    out[n] = parts[p][i];
                    n += 1;
                }
                i += 1;
            }
            p += 1;
        }
        out
    }

    /// The `code` of every entry, same order.
    pub const fn codes_of<const N: usize>(entries: &[CodeInfo]) -> [&'static str; N] {
        assert!(entries.len() == N, "catalogue length mismatch");
        let mut out = [""; N];
        let mut i = 0;
        while i < N {
            out[i] = entries[i].code;
            i += 1;
        }
        out
    }
}

/// A pure, caller-correctable domain outcome. Implemented by hand or via
/// `#[derive(errlanes::Rejection)]`, which emits `Display`/`Error` itself
/// (defaulting `Display` to the code) unless `#[rejection(error = manual)]`
/// hands that to `thiserror` or a hand-written impl.
pub trait Rejection: Error + Send + Sync + 'static {
    /// A stable, typed, wire-safe identity for this outcome.
    type Code: RejectionCode;

    fn code(&self) -> Self::Code;

    /// Operator level for this outcome. Rejections default to `Warn`.
    fn level(&self) -> Level {
        Level::Warn
    }
}

/// Consuming mapping. `#[derive(Lift)]` with `#[lift(Source)]` generates an exhaustive
/// mapping with `Unmapped = Infallible` and a total `From<Source>` conversion.
/// `#[lift(Source, unhandled = fatal)]` returns the original unmapped source;
/// [`Fail::lift`] wraps it as a fatal invariant with its source intact.
/// The derive does not require or implement [`Rejection`]. Derive `Rejection`
/// separately to provide codes and levels; simple lift mappings forward that
/// metadata by default unless the destination declares its own.
pub trait Lift<X>: Sized {
    type Unmapped;
    fn lift(x: X) -> Result<Self, Self::Unmapped>;
}

/// A total `From` counts as a strict lift, so one call-site method can require
/// only `Lift` and still cover both mapping modes. Bounded to `X: Rejection`
/// (rather than any `X`) so it does not overlap the `Lift<Infallible>`
/// blanket below — both are needed, since a [`crate::Classify`] wrapper's
/// rejected slot is either a `Rejection` or `Infallible` (never anything
/// else, by `RejectedSlot`'s own two impls).
impl<X: Rejection, P: From<X>> Lift<X> for P {
    type Unmapped = core::convert::Infallible;
    fn lift(x: X) -> Result<Self, Self::Unmapped> {
        Ok(P::from(x))
    }
}

/// Every destination lifts an `Infallible` rejected slot trivially — this is
/// what lets a fault-only [`crate::Classify`] wrapper satisfy the `Fail`
/// blanket for *any* `D`, with no `Lift`/`From` declared at all.
impl<P> Lift<core::convert::Infallible> for P {
    type Unmapped = core::convert::Infallible;
    fn lift(x: core::convert::Infallible) -> Result<Self, Self::Unmapped> {
        match x {}
    }
}

/// Conversion of an unmapped value into an enabled fatal slot. Strict lifts
/// have no unmapped values and therefore work with any destination profile.
#[doc(hidden)]
pub trait UnmappedInto<F> {
    fn unmapped_into(self) -> F;
}
impl<F> UnmappedInto<F> for core::convert::Infallible {
    fn unmapped_into(self) -> F {
        match self {}
    }
}
impl<R: Rejection> UnmappedInto<Fatal> for R {
    fn unmapped_into(self) -> Fatal {
        // `with_opaque_source`: `self` is a `Rejection`, whose `Display` may
        // embed caller-supplied input (see the trait's display discipline);
        // `source()` still returns it for a handler or test to
        // `downcast_ref`, but `message_chain` must not walk into it.
        Fatal::from_error(crate::FatalKind::Invariant, self)
            .with_context("unhandled rejection at partial lift")
            .with_opaque_source()
    }
}

/// `Fail` minus the `Rejected` lane: what an operation that cannot reject
/// (nothing about it is the caller's to correct) returns. Reads return
/// `Fault<L>`; writes return `Fail<{Entity}ConstraintViolation, L>` — the type
/// itself says whether a call can ever hand back a domain outcome.
#[derive(Debug, Clone)]
pub enum Fault<L: LaneProfile = AllLanes> {
    Denied(L::Denied),
    Transient(L::Transient),
    Fatal(L::Fatal),
}

impl<L: LaneProfile> Fault<L> {
    pub fn lane(&self) -> Lane {
        match self {
            Fault::Denied(_) => Lane::Denied,
            Fault::Transient(_) => Lane::Transient,
            Fault::Fatal(_) => Lane::Fatal,
        }
    }

    pub fn is_transient(&self) -> bool {
        matches!(self, Fault::Transient(_))
    }

    pub fn is_fatal(&self) -> bool {
        matches!(self, Fault::Fatal(_))
    }

    pub fn is_denied(&self) -> bool {
        matches!(self, Fault::Denied(_))
    }

    /// The operator-safe one-line text for this failure — exactly what
    /// `record` writes to `exception.message`, for a boundary that must
    /// persist it rather than (or as well as) record it. `Transient`/
    /// `Fatal`: the whole `source()` chain joined with `": "`. `Denied`: its
    /// `Display`.
    pub fn message(&self) -> String {
        self.lanes().message()
    }

    /// Consumes the `Transient` lane, yielding the same profile with its
    /// transient slot disabled. `attempts` is what the retry loop counted; an
    /// exhausted transient becomes `Fatal(Exhausted)` with the last transient
    /// as its source.
    pub fn narrow_transient(self, attempts: u32) -> Fault<crate::profile::WithoutTransient<L>>
    where
        L::Transient: NarrowTransient<L::Fatal>,
    {
        match self {
            Fault::Denied(d) => Fault::Denied(d),
            Fault::Transient(last) => Fault::Fatal(last.narrow(attempts)),
            Fault::Fatal(f) => Fault::Fatal(f),
        }
    }

    /// Narrows away the `Denied` lane: a denial at a boundary with no
    /// subject (code running as the system) becomes `Fatal(Denied)` with
    /// the `Denied` as its source.
    pub fn narrow_denied(self) -> Fault<crate::profile::WithoutDenied<L>>
    where
        L::Denied: NarrowDenied<L::Fatal>,
    {
        match self {
            Fault::Denied(d) => Fault::Fatal(d.narrow()),
            Fault::Transient(t) => Fault::Transient(t),
            Fault::Fatal(f) => Fault::Fatal(f),
        }
    }
}

/// Borrowed lane accessors. `min_exhaustive_patterns` lets a *by-value* match
/// name only the lanes a profile enables, but a borrowed match still demands an
/// arm for every variant. These accessors are the borrowed form, so no caller
/// ever has to write a `match *never {}` arm. Each is available only when the
/// profile enables that lane, so `e.as_denied()` on a no-denial profile is a
/// compile error rather than a permanent `None`.
impl<L: LaneProfile<Denied = Denied>> Fault<L> {
    pub fn as_denied(&self) -> Option<&Denied> {
        match self {
            Fault::Denied(d) => Some(d),
            _ => None,
        }
    }
}

impl<L: LaneProfile<Transient = Transient>> Fault<L> {
    pub fn as_transient(&self) -> Option<&Transient> {
        match self {
            Fault::Transient(t) => Some(t),
            _ => None,
        }
    }

    pub fn is_congestion(&self) -> bool {
        self.as_transient().is_some_and(Transient::is_congestion)
    }

    /// See [`crate::TransientKind::is_contention`].
    pub fn is_contention(&self) -> bool {
        self.as_transient().is_some_and(Transient::is_contention)
    }
}

impl<L: LaneProfile<Fatal = Fatal>> Fault<L> {
    pub fn as_fatal(&self) -> Option<&Fatal> {
        match self {
            Fault::Fatal(f) => Some(f),
            _ => None,
        }
    }
}

impl<D, L: LaneProfile<Denied = Denied>> Fail<D, L> {
    pub fn as_denied(&self) -> Option<&Denied> {
        match self {
            Fail::Denied(d) => Some(d),
            _ => None,
        }
    }
}

impl<D, L: LaneProfile<Transient = Transient>> Fail<D, L> {
    pub fn as_transient(&self) -> Option<&Transient> {
        match self {
            Fail::Transient(t) => Some(t),
            _ => None,
        }
    }

    pub fn is_congestion(&self) -> bool {
        self.as_transient().is_some_and(Transient::is_congestion)
    }

    /// See [`crate::TransientKind::is_contention`].
    pub fn is_contention(&self) -> bool {
        self.as_transient().is_some_and(Transient::is_contention)
    }
}

impl<D, L: LaneProfile<Fatal = Fatal>> Fail<D, L> {
    pub fn as_fatal(&self) -> Option<&Fatal> {
        match self {
            Fail::Fatal(f) => Some(f),
            _ => None,
        }
    }
}

impl<L: LaneProfile> fmt::Display for Fault<L> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Fault::Denied(d) => write!(f, "{d}"),
            Fault::Transient(t) => write!(f, "{t}"),
            Fault::Fatal(x) => write!(f, "{x}"),
        }
    }
}

impl<L: LaneProfile> Error for Fault<L> {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        // Same contract as `Fail::source` (pitfall 2): the lane payload
        // itself, so `lane_of` can downcast it.
        match self {
            Fault::Denied(d) => Some(d),
            Fault::Transient(t) => Some(t),
            Fault::Fatal(x) => Some(x),
        }
    }
}

/// The generic view over a domain rejection `D`, before retries have run.
///
/// **Display discipline**: [`Display`](fmt::Display)'s `Rejected` arm keeps
/// its `rejected: {d}` prefix for logs, but no boundary may build a
/// user-facing message from `to_string()` — a rejection's message may embed
/// caller-supplied input. Use [`as_rejected`](Fail::as_rejected) and
/// [`Rejection::code`] instead: `record_fail` keys `error.code` off the code,
/// never the message, and a GraphQL boundary should do the same for its error
/// extension.
#[derive(Debug, Clone)]
pub enum Fail<D, L: LaneProfile = AllLanes> {
    Rejected(D),
    Denied(L::Denied),
    Transient(L::Transient),
    Fatal(L::Fatal),
}

impl<D, L: LaneProfile> Fail<D, L> {
    pub fn lane(&self) -> Lane {
        match self {
            Fail::Rejected(_) => Lane::Rejected,
            Fail::Denied(_) => Lane::Denied,
            Fail::Transient(_) => Lane::Transient,
            Fail::Fatal(_) => Lane::Fatal,
        }
    }

    /// Lift the rejection and, when requested, expand the lane profile without
    /// changing any fault classification. The value-level form of
    /// [`ResultExt::lift`](crate::ResultExt::lift), with
    /// the same single rule: `P: Lift<D>` is satisfied by a total `From<D>`
    /// (through errlanes' blanket, `Unmapped = Infallible`) and by a partial
    /// `#[lift(Source, unhandled = fatal)]` mapping (`Unmapped = Source`),
    /// whose unmapped cases demote to `Fatal(Invariant)` with the rejection
    /// as their source — which is why a partial mapping requires the
    /// destination to admit `Fatal`. The strict/partial choice is declared
    /// once on the destination enum; the call site does not repeat it.
    pub fn lift<P: Lift<D>, M: LaneProfile>(self) -> Fail<P, M>
    where
        L::Denied: Into<M::Denied>,
        L::Transient: Into<M::Transient>,
        L::Fatal: Into<M::Fatal>,
        P::Unmapped: UnmappedInto<M::Fatal>,
    {
        match self {
            Self::Rejected(d) => match P::lift(d) {
                Ok(mapped) => Fail::Rejected(mapped),
                Err(unmapped) => Fail::Fatal(unmapped.unmapped_into()),
            },
            Self::Denied(d) => Fail::Denied(d.into()),
            Self::Transient(t) => Fail::Transient(t.into()),
            Self::Fatal(f) => Fail::Fatal(f.into()),
        }
    }

    pub fn lift_with<P, M: LaneProfile<Fatal = Fatal>>(
        self,
        f: impl FnOnce(D) -> Result<P, Fatal>,
    ) -> Fail<P, M>
    where
        L::Denied: Into<M::Denied>,
        L::Transient: Into<M::Transient>,
        L::Fatal: Into<M::Fatal>,
    {
        match self {
            Self::Rejected(d) => match f(d) {
                Ok(p) => Fail::Rejected(p),
                Err(e) => Fail::Fatal(e),
            },
            Self::Denied(d) => Fail::Denied(d.into()),
            Self::Transient(t) => Fail::Transient(t.into()),
            Self::Fatal(f) => Fail::Fatal(f.into()),
        }
    }

    pub fn map_rejected<D2>(self, f: impl FnOnce(D) -> D2) -> Fail<D2, L> {
        match self {
            Fail::Rejected(d) => Fail::Rejected(f(d)),
            Fail::Denied(d) => Fail::Denied(d),
            Fail::Transient(t) => Fail::Transient(t),
            Fail::Fatal(fatal) => Fail::Fatal(fatal),
        }
    }

    /// Narrows to the domain outcome, or the non-domain fault. `let d =
    /// e.rejected()?;` propagates the fault into any enclosing `Fail<_, L>` (or
    /// a [`Carrier`](crate::Carrier)) via the blanket `From<Fault<L>>`.
    pub fn rejected(self) -> Result<D, Fault<L>> {
        match self {
            Fail::Rejected(d) => Ok(d),
            Fail::Denied(d) => Err(Fault::Denied(d)),
            Fail::Transient(t) => Err(Fault::Transient(t)),
            Fail::Fatal(f) => Err(Fault::Fatal(f)),
        }
    }

    pub fn as_rejected(&self) -> Option<&D> {
        match self {
            Fail::Rejected(d) => Some(d),
            _ => None,
        }
    }

    pub fn is_transient(&self) -> bool {
        matches!(self, Fail::Transient(_))
    }

    pub fn is_fatal(&self) -> bool {
        matches!(self, Fail::Fatal(_))
    }

    pub fn is_denied(&self) -> bool {
        matches!(self, Fail::Denied(_))
    }

    /// The operator-safe one-line text for this failure — exactly what
    /// `record` writes to `exception.message`, for a boundary that must
    /// persist it rather than (or as well as) record it. `Transient`/
    /// `Fatal`: the whole `source()` chain joined with `": "`. `Denied`: its
    /// `Display`. `Rejected`: the rejection's `code`, never its message
    /// (display discipline — a rejection's message may embed caller-supplied
    /// input).
    pub fn message(&self) -> String
    where
        D: Rejection,
    {
        self.lanes().message()
    }

    /// Consumes the `Transient` lane, yielding the same rejection over `L`
    /// with its transient slot disabled. An exhausted transient becomes
    /// `Fatal(Exhausted)`, carrying `attempts` and the last transient as its
    /// source.
    pub fn narrow_transient(self, attempts: u32) -> Fail<D, crate::profile::WithoutTransient<L>>
    where
        L::Transient: NarrowTransient<L::Fatal>,
    {
        match self {
            Fail::Rejected(d) => Fail::Rejected(d),
            Fail::Denied(d) => Fail::Denied(d),
            Fail::Transient(last) => Fail::Fatal(last.narrow(attempts)),
            Fail::Fatal(f) => Fail::Fatal(f),
        }
    }

    /// Narrows away the `Denied` lane: a denial at a boundary with no
    /// subject (code running as the system) becomes `Fatal(Denied)` with
    /// the `Denied` as its source.
    pub fn narrow_denied(self) -> Fail<D, crate::profile::WithoutDenied<L>>
    where
        L::Denied: NarrowDenied<L::Fatal>,
    {
        match self {
            Fail::Rejected(d) => Fail::Rejected(d),
            Fail::Denied(d) => Fail::Fatal(d.narrow()),
            Fail::Transient(t) => Fail::Transient(t),
            Fail::Fatal(f) => Fail::Fatal(f),
        }
    }

    /// Narrows away the `Rejected` lane: a rejection at a boundary with no
    /// caller to correct it is an invariant violation, and becomes
    /// `Fatal(Invariant)` with the rejection as its source — the same rule
    /// a partial `#[lift(.., unhandled = fatal)]` applies. Nothing is left
    /// to reject, so the result is a `Fault`. `with_opaque_source`: `d`'s
    /// `Display` may embed caller-supplied input (the same display
    /// discipline `Rejection` documents everywhere else), so `source()`
    /// still returns it for a handler or test to `downcast_ref`, but
    /// `message_chain` must not walk into it.
    pub fn narrow_rejected(self) -> Fault<L>
    where
        D: Rejection,
        L: LaneProfile<Fatal = Fatal>,
    {
        match self {
            Fail::Rejected(d) => Fault::Fatal(invariant_from_rejection(d)),
            Fail::Denied(d) => Fault::Denied(d),
            Fail::Transient(t) => Fault::Transient(t),
            Fail::Fatal(f) => Fault::Fatal(f),
        }
    }
}

/// The one construction site for "a rejection with no caller left to correct
/// it": `Fatal(Invariant)` carrying the rejection as its source. Shared by
/// [`Fail::narrow_rejected`] and the bare-rejection `narrow_rejected` in
/// `result_ext`, so both apply the same context and the same
/// `with_opaque_source` discipline (`d`'s `Display` may embed caller input).
pub(crate) fn invariant_from_rejection<D: Rejection>(d: D) -> Fatal {
    Fatal::from_error(crate::FatalKind::Invariant, d)
        .with_context("rejected with no caller to correct")
        .with_opaque_source()
}

impl<D: fmt::Display, L: LaneProfile> fmt::Display for Fail<D, L> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Fail::Rejected(d) => write!(f, "rejected: {d}"),
            Fail::Denied(d) => write!(f, "{d}"),
            Fail::Transient(t) => write!(f, "{t}"),
            Fail::Fatal(x) => write!(f, "{x}"),
        }
    }
}

impl<D: Error + 'static, L: LaneProfile> Error for Fail<D, L> {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            // The lane payload itself must be the *next* link in the chain
            // so that `lane_of` can find it by downcasting.
            Fail::Rejected(d) => Some(d),
            Fail::Denied(d) => Some(d),
            Fail::Transient(t) => Some(t),
            Fail::Fatal(x) => Some(x),
        }
    }
}

pub(crate) mod sealed {
    pub trait Sealed {}
    impl<D: super::Rejection, L: super::LaneProfile> Sealed for super::Fail<D, L> {}
    impl<L: super::LaneProfile> Sealed for super::Fault<L> {}
    impl<C: crate::Carrier> Sealed for C {}
}

/// Sealed. The thing `retry`/`record` need from any error they are handed:
/// its lane, and how to narrow it. Implemented by [`Fail<D, L>`], by
/// [`Fault<L>`] — the two shapes a generated repo op can return — and by every
/// [`Carrier`](crate::Carrier) whose built-in is `Laned`.
pub trait Laned: sealed::Sealed + Error + Send + Sync + 'static + Sized {
    type WithoutTransient: Error + Send + Sync + 'static;

    fn lane(&self) -> Lane;

    /// The operator level of this failure: the lane's default
    /// ([`Lane::level`]), overridden only by a `Rejected` outcome's
    /// [`Rejection::level`].
    fn level(&self) -> Level;

    fn is_transient(&self) -> bool {
        self.lane() == Lane::Transient
    }

    fn is_fatal(&self) -> bool {
        self.lane() == Lane::Fatal
    }

    fn is_denied(&self) -> bool {
        self.lane() == Lane::Denied
    }

    fn narrow_transient(self, attempts: u32) -> Self::WithoutTransient;

    /// The operator-safe one-line text for this failure — exactly what
    /// `record` writes to `exception.message`, for a boundary that must
    /// persist it rather than (or as well as) record it. `Transient`/
    /// `Fatal`: the whole `source()` chain joined with `": "`. `Denied`: its
    /// `Display`. `Rejected`: the rejection's `code`, never its message
    /// (display discipline — a rejection's message may embed caller-supplied
    /// input).
    fn message(&self) -> String;

    #[cfg(feature = "tracing")]
    fn record(&self, span: &tracing::Span);

    /// Backs [`crate::emit`].
    #[cfg(feature = "tracing")]
    #[doc(hidden)]
    fn emit_event(&self);
}

/// Note the `NarrowTransient` bound: a profile that admits `Transient` but
/// not `Fatal` is not `Laned`, so `retry` cannot be handed one. Retrying an
/// operation that claims it can never fail permanently is exactly the
/// contradiction the bound rules out.
impl<D: Rejection, L: LaneProfile> Laned for Fail<D, L>
where
    L::Transient: NarrowTransient<L::Fatal>,
{
    type WithoutTransient = Fail<D, crate::profile::WithoutTransient<L>>;

    fn lane(&self) -> Lane {
        Fail::lane(self)
    }

    fn level(&self) -> Level {
        self.lanes().level()
    }

    fn narrow_transient(self, attempts: u32) -> Self::WithoutTransient {
        Fail::narrow_transient(self, attempts)
    }

    fn message(&self) -> String {
        Fail::message(self)
    }

    #[cfg(feature = "tracing")]
    fn record(&self, span: &tracing::Span) {
        self.lanes().record(span);
    }

    #[cfg(feature = "tracing")]
    fn emit_event(&self) {
        self.lanes().emit();
    }
}

/// A carrier is `Laned` exactly when its built-in is, and narrows through it.
/// Disjoint from the two built-in impls above: `Fault` / `Fail` are not
/// carriers, and downstream cannot implement `Carrier` for them (orphan rule).
impl<C: crate::Carrier> Laned for C
where
    C::Repr: Laned,
    <C as crate::IntoLanes>::Rejected: crate::carrier::LaneRejected,
{
    type WithoutTransient = <C::Repr as Laned>::WithoutTransient;

    fn lane(&self) -> Lane {
        crate::Carrier::lanes(self).lane()
    }

    fn level(&self) -> Level {
        crate::Carrier::lanes(self).level()
    }

    fn narrow_transient(self, attempts: u32) -> Self::WithoutTransient {
        self.into_repr().narrow_transient(attempts)
    }

    fn message(&self) -> String {
        crate::Carrier::lanes(self).message()
    }

    #[cfg(feature = "tracing")]
    fn record(&self, span: &tracing::Span) {
        crate::Carrier::lanes(self).record(span);
    }

    #[cfg(feature = "tracing")]
    fn emit_event(&self) {
        crate::Carrier::lanes(self).emit();
    }
}

impl<L: LaneProfile> Laned for Fault<L>
where
    L::Transient: NarrowTransient<L::Fatal>,
{
    type WithoutTransient = Fault<crate::profile::WithoutTransient<L>>;

    fn lane(&self) -> Lane {
        Fault::lane(self)
    }

    fn level(&self) -> Level {
        self.lanes().level()
    }

    fn narrow_transient(self, attempts: u32) -> Self::WithoutTransient {
        Fault::narrow_transient(self, attempts)
    }

    fn message(&self) -> String {
        Fault::message(self)
    }

    #[cfg(feature = "tracing")]
    fn record(&self, span: &tracing::Span) {
        self.lanes().record(span);
    }

    #[cfg(feature = "tracing")]
    fn emit_event(&self) {
        self.lanes().emit();
    }
}

/// Compile-time field metadata used by the rejection composition protocol.
#[doc(hidden)]
pub trait RejectionField<const VARIANT: u64, const FIELD: usize> {
    type Type;
}

/// Borrowed metadata protocol; forwarding does not clone or reconstruct errors.
#[doc(hidden)]
pub trait RejectionMetadata<const VARIANT: u64>: Rejection {
    type Fields<'a>;
    /// The codes this one variant can resolve to: its own leaf, or whatever
    /// it forwards (`delegate`, `code_and_level_from`, `#[lift(..)]`).
    const CODES: &'static [CodeInfo];
    fn field_code(fields: Self::Fields<'_>) -> Self::Code;
    fn field_level(fields: Self::Fields<'_>) -> Level;
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::lane::{Exhausted, FatalKind, TransientKind};

    #[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)]
    struct SmallCode;
    impl fmt::Display for SmallCode {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("SMALL")
        }
    }
    impl From<SmallCode> for &'static str {
        fn from(_: SmallCode) -> Self {
            "SMALL"
        }
    }
    impl RejectionCode for SmallCode {
        const CODES: &'static [CodeInfo] = &[CodeInfo {
            code: "SMALL",
            description: None,
        }];
    }

    #[derive(Debug, Clone, PartialEq, Eq)]
    struct Small;
    impl fmt::Display for Small {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("small")
        }
    }
    impl Error for Small {}
    impl Rejection for Small {
        type Code = SmallCode;
        fn code(&self) -> SmallCode {
            SmallCode
        }
    }

    #[derive(Debug, Clone, PartialEq, Eq)]
    struct Big(Small);
    impl fmt::Display for Big {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            write!(f, "big({})", self.0)
        }
    }
    impl Error for Big {}
    impl From<Small> for Big {
        fn from(s: Small) -> Self {
            Big(s)
        }
    }
    impl Rejection for Big {
        type Code = SmallCode;
        fn code(&self) -> SmallCode {
            self.0.code()
        }
    }

    #[test]
    fn expand_preserves_the_lane() {
        let f: Fail<Small> = Fail::Rejected(Small);
        let converted: Fail<Big> = f.lift();
        assert_eq!(converted.lane(), Lane::Rejected);
        assert_eq!(converted.as_rejected(), Some(&Big(Small)));

        let t: Fail<Small> = Transient::new(TransientKind::Deadlock).into();
        let converted: Fail<Big> = t.lift();
        assert_eq!(converted.lane(), Lane::Transient);
    }

    #[test]
    fn expand_with_demotes_an_unmapped_rejection_to_fatal() {
        let f: Fail<Small> = Fail::Rejected(Small);
        let converted: Fail<Big> = f.lift_with(|_| Err(Fatal::invariant("unmapped")));
        assert_eq!(converted.lane(), Lane::Fatal);

        let f: Fail<Small> = Fail::Rejected(Small);
        let converted: Fail<Big> = f.lift_with(|s| Ok(Big(s)));
        assert_eq!(converted.lane(), Lane::Rejected);
    }

    /// Regression: `UnmappedInto<Fatal> for R: Rejection` (the partial-lift
    /// path) must keep the unmapped rejection reachable by `downcast_ref`
    /// for a handler or test, but never let its `Display` -- which may embed
    /// caller-supplied input -- reach an operator-facing message.
    #[test]
    fn unmapped_rejection_demoted_to_fatal_does_not_leak_its_display() {
        let fatal: Fatal = Small.unmapped_into();
        assert_eq!(fatal.kind, FatalKind::Invariant);
        assert!(
            fatal.source().unwrap().downcast_ref::<Small>().is_some(),
            "the rejection must still be reachable for a handler or test to downcast"
        );
        let message = crate::dynamic::message_chain(&fatal);
        assert!(
            !message.contains("small"),
            "a partial lift's unmapped rejection's Display must never reach an \
             operator-facing message; got {message:?}"
        );
    }

    /// Same regression as `unmapped_rejection_demoted_to_fatal_does_not_leak_its_display`,
    /// for `narrow_rejected`'s own construction site.
    #[test]
    fn narrow_rejected_does_not_leak_the_rejections_display() {
        let f: Fail<Small> = Fail::Rejected(Small);
        let narrowed = f.narrow_rejected();
        match &narrowed {
            Fault::Fatal(fatal) => {
                assert_eq!(fatal.kind, FatalKind::Invariant);
                assert!(fatal.source().unwrap().downcast_ref::<Small>().is_some());
            }
            other => panic!("expected Fatal(Invariant), got {other:?}"),
        }
        let message = narrowed.message();
        assert!(
            !message.contains("small"),
            "narrow_rejected's rejection Display must never reach an operator-facing \
             message; got {message:?}"
        );
    }

    #[test]
    fn narrow_transient_turns_transient_into_exhausted_and_leaves_everything_else_alone() {
        let t: Fail<Small> = Transient::new(TransientKind::Deadlock).into();
        match t.narrow_transient(3) {
            Fail::Fatal(f) => {
                assert_eq!(f.kind, FatalKind::Exhausted);
                let e = Error::source(&f)
                    .and_then(|s| s.downcast_ref::<Exhausted>())
                    .expect("exhaustion is the fatal's source");
                assert_eq!(e.attempts, 3);
                assert_eq!(e.last.kind, TransientKind::Deadlock);
            }
            other => panic!("expected Fatal(Exhausted), got {other:?}"),
        }

        let r: Fail<Small> = Fail::Rejected(Small);
        assert!(matches!(r.narrow_transient(1), Fail::Rejected(Small)));

        let fatal: Fail<Small> = Fatal::new(FatalKind::Config).into();
        assert!(matches!(fatal.narrow_transient(1), Fail::Fatal(_)));
    }

    #[test]
    fn fault_converts_into_any_fail_via_the_real_blanket() {
        let fault: Fault = Fatal::new(FatalKind::CorruptState).into();
        let converted: Fail<Small> = fault.into();
        assert_eq!(converted.lane(), Lane::Fatal);
    }

    #[test]
    fn rejected_narrows_or_returns_the_fault() {
        let f: Fail<Small> = Fail::Rejected(Small);
        assert_eq!(f.rejected().unwrap(), Small);

        let t: Fail<Small> = Transient::new(TransientKind::Deadlock).into();
        assert!(t.rejected().is_err());
    }

    #[test]
    fn fail_source_is_the_lane_payload_itself_so_lane_of_can_downcast_it() {
        let t: Fail<Small> = Transient::new(TransientKind::Deadlock).into();
        let source = std::error::Error::source(&t).expect("source present");
        assert!(source.is::<Transient>());
    }

    #[test]
    fn fault_source_is_the_lane_payload_itself_so_lane_of_can_downcast_it() {
        let t: Fault = Transient::new(TransientKind::Deadlock).into();
        let source = std::error::Error::source(&t).expect("source present");
        assert!(source.is::<Transient>());
    }

    #[test]
    fn laned_narrow_transient_agrees_between_fail_and_fault() {
        fn exhausted_attempts(e: &(dyn Error + 'static)) -> u32 {
            e.source()
                .and_then(|s| s.downcast_ref::<Exhausted>())
                .expect("exhaustion is the fatal's source")
                .attempts
        }

        let t: Fail<Small> = Transient::new(TransientKind::Deadlock).into();
        let narrowed: Fail<Small, crate::profile::WithoutTransient<AllLanes>> =
            Laned::narrow_transient(t, 2);
        assert_eq!(narrowed.lane(), Lane::Fatal);
        assert_eq!(exhausted_attempts(narrowed.as_fatal().unwrap()), 2);

        let t: Fault = Transient::new(TransientKind::Deadlock).into();
        let narrowed: Fault<crate::profile::WithoutTransient<AllLanes>> =
            Laned::narrow_transient(t, 2);
        assert_eq!(narrowed.lane(), Lane::Fatal);
        assert_eq!(exhausted_attempts(narrowed.as_fatal().unwrap()), 2);
    }
}