minerva 0.2.0

use super::SealedEpoch;

/// A seal record whose consignment **was accepted**: the certifiable grade.
///
/// [`Epochs::try_seal`](super::Epochs::try_seal) returning a record means
/// *this replica's rounds completed*, never that its peers hold the same
/// record. [`EpochShadow::consign`](crate::metis::EpochShadow::consign) is
/// where the difference is caught, and is the only door that *earns* this
/// grade, so a record this replica's own document plane refuses cannot reach
/// a certificate by that route.
///
/// The qualifier is load-bearing. [`vouch`](Self::vouch) mints the same grade
/// from any [`SealedEpoch`] without the coverage check, transferring the
/// whole validation obligation to its caller; it is audited rather than
/// absent, and the guarantee above excludes it.
///
/// The consignment door is the right gate because it is the only one reading
/// a *second source*: the sealed join comes from peer **reports**, its
/// coverage check from the deltas actually **delivered**.
///
/// # What it does not claim
///
/// Acceptance is a *local* fact and the scope stops there: this replica's
/// delivered set covers the sealed join exactly. Not a quorum, not a
/// signature, and not evidence that any peer accepted the same record.
/// The argument, the sufficiency bound, and the audit are
/// `docs/metis-trust-grades.adoc`'s S335 addendum.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Consigned {
    record: SealedEpoch,
}

impl Consigned {
    /// The certifiable seal record: the digest input a checkpoint
    /// certificate binds over.
    #[must_use]
    pub const fn record(&self) -> &SealedEpoch {
        &self.record
    }

    /// The door's own mint, private so acceptance is the only source.
    pub(super) const fn accepted(record: SealedEpoch) -> Self {
        Self { record }
    }

    /// Asserts, on the caller's authority, that `record`'s consignment was
    /// accepted elsewhere.
    ///
    /// # The audit
    ///
    /// Grepping this constructor should enumerate every certifiable record
    /// that was not accepted at the door. There are exactly two honest shapes.
    /// Both sit beside a *restore* door, which is no coincidence: acceptance
    /// is an event, and a machine rebuilt from evidence did not live through
    /// it. Both are also **consumer-side**, because the restore doors hand
    /// back a machine rather than a grade. The worked example is the fleet
    /// replica's `vouch_restored_lineage`.
    ///
    /// * A joiner admitted through
    ///   [`bootstrap`](super::Epochs::bootstrap) holds records it never
    ///   consigned. They arrived as *verified peer claims*, checked against
    ///   an authenticated certificate one layer up: a stronger warrant than
    ///   local acceptance, and one Minerva cannot re-derive.
    /// * A machine restored through
    ///   [`rehydrate`](super::Epochs::rehydrate) holds records whose
    ///   consignments it *did* accept before the crash. A checkpoint is
    ///   written at a seal and the seal path runs past this door, so the
    ///   restored lineage is exactly the accepted one.
    ///
    /// Neither covers a record sealed *after* the checkpoint and re-derived
    /// by journal replay: that must earn the grade again, which is why a
    /// wedged replica stays wedged across a restart instead of laundering
    /// its divergent seal into certifiability.
    ///
    /// Every other call is a caller choosing to skip the check --- sometimes
    /// right, never silent.
    #[must_use]
    pub const fn vouch(record: SealedEpoch) -> Self {
        Self { record }
    }
}