minerva 0.2.0

/// A peer's protocol-round claim, bound to the peer that made it.
///
/// The epoch machine's two peer-report doors,
/// [`confirm`](super::Epochs::confirm) and
/// [`adopt_report`](super::Epochs::adopt_report), fold a value *attributed to
/// a station*. Until S333 they took a bare `(station, value)` pair, so
/// nothing structurally connected the two: any caller could pair any station
/// with any claim, and the seal record that the whole duplicate contract and
/// every downstream certificate rest on was derived from unattributed
/// scalars. `Vouched` closes that pairing, in the same idiom
/// [`Received`](crate::metis::Received) closes it on the receive path and
/// [`Cut`](crate::metis::Cut) closes it for witnessed frontiers: the station
/// is *inside* the evidence, so the door reads it out rather than being told.
///
/// # What vouching means, and what it does not
///
/// Vouching is the caller's assertion that this claim genuinely came from
/// this station. Minerva has no identity or signature domain (the non-goals
/// keep membership and transport caller-side), so it cannot check that
/// itself; what it can do is refuse to accept an unvouched claim, which
/// gives a caller's verification an unavoidable, greppable place to live.
///
/// It does **not** detect equivocation, and it is important not to read it
/// as though it did. A Byzantine station may validly vouch two different
/// claims to two peers. Each recipient's vouch is then genuine, both fold,
/// and the sealed records diverge; the local machine sees one voice saying
/// one thing and has no basis to suspect otherwise. Detecting a contradiction
/// requires comparing what different members were told, which is inherently
/// cross-member evidence and stays the caller's
/// (`fleet::byzantine` maps exactly what one forked voice does, and the
/// exposure survives this type).
///
/// So the honest scope: `Vouched` closes *misattribution* and makes the trust
/// boundary explicit. It is necessary for, and not a substitute for, the
/// cross-member conviction that closes equivocation.
///
/// # The escape
///
/// Minerva mints no `Vouched` itself, because no shipped path here holds the
/// proof. [`trust`](Self::trust) is therefore the only constructor, and it is
/// an *audited door* rather than a convenience: every call is a caller
/// asserting provenance it is responsible for. Under the crate's standing
/// crash-only model a peer's report is honest by assumption and `trust` is
/// simply the shape that assumption takes; under a Byzantine caller it is the
/// line the caller's verification must sit on.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Vouched<T> {
    by: u32,
    claim: T,
}

impl<T> Vouched<T> {
    /// Vouches that `claim` came from station `by`.
    ///
    /// # The audit
    ///
    /// This is the one door into the type and it verifies nothing: the caller
    /// is asserting provenance on its own authority. A caller with an
    /// identity domain should call this *only* on the far side of its own
    /// verification, so that grepping `Vouched::trust` enumerates every point
    /// where a peer's word enters the epoch machine. A caller under the
    /// crash-only model calls it freely, which is exactly what that model
    /// says.
    #[must_use]
    pub const fn trust(by: u32, claim: T) -> Self {
        Self { by, claim }
    }

    /// The station that made the claim.
    #[must_use]
    pub const fn by(&self) -> u32 {
        self.by
    }

    /// Borrows the claim.
    #[must_use]
    pub const fn claim(&self) -> &T {
        &self.claim
    }

    /// Takes the claim, discarding the attribution.
    #[must_use]
    pub fn into_claim(self) -> T {
        self.claim
    }
}