liminal_protocol/lifecycle/operations/

binding_fate.rs

use alloc::boxed::Box;

use crate::{
    algebra::{floor_transition, marker_clamped_floor},
    wire::DeliverySeq,
};

use super::{LiveFrontierError, LiveFrontierOwner, live_frontier::BindingFateOwnerPlan};
use crate::lifecycle::{
    CommittedDiedTerminal, Event, FrontierBinding, ObserverProgressProjection, OrdinaryBindingFate,
    RecoveredBindingFate, SealedBindingFateIntent, SealedBindingFateToken,
};

/// Closed terminal input accepted by protocol-owned binding-fate measurement.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BindingFateTerminal {
    /// Ordinary fate consumes the exact committed Died terminal.
    Ordinary(CommittedDiedTerminal),
    /// Recovered fate after committed Died receives no Died terminal.
    Recovered,
    /// Recovered fate after pending Died preserves exact finalizer authority.
    RecoveredAndReserveFinalizer,
}

/// Protocol-produced binding fate after measuring the post-release floor.
#[derive(Debug, PartialEq, Eq)]
pub enum MeasuredBindingFate {
    /// Ordinary no-marker fate with exact Died provenance.
    Ordinary(OrdinaryBindingFate),
    /// Fenced recovered fate with no Died terminal input.
    Recovered(RecoveredBindingFate),
}

impl MeasuredBindingFate {
    /// Returns the measured floor carried by either closed fate class.
    #[must_use]
    pub const fn resulting_floor(&self) -> DeliverySeq {
        match self {
            Self::Ordinary(fate) => fate.resulting_floor(),
            Self::Recovered(fate) => fate.resulting_floor(),
        }
    }

    /// Projects the protocol-measured floor for observer routing.
    #[must_use]
    pub const fn observer_progress_projection(&self) -> ObserverProgressProjection {
        match self {
            Self::Ordinary(fate) => fate.observer_progress_projection(),
            Self::Recovered(fate) => fate.observer_progress_projection(),
        }
    }
}

/// Successful protocol measurement retaining the coupled frontier owner.
#[derive(Debug, PartialEq, Eq)]
pub struct PreparedBindingFate {
    owner: LiveFrontierOwner,
    fate: MeasuredBindingFate,
    event: Event,
}

impl PreparedBindingFate {
    /// Borrows the measured fate.
    #[must_use]
    pub const fn fate(&self) -> &MeasuredBindingFate {
        &self.fate
    }

    /// Returns the internally minted binding-fate event.
    #[must_use]
    pub const fn event(&self) -> Event {
        self.event
    }

    /// Consumes the prepared transition into the measured next owner and fate.
    #[must_use]
    pub fn into_parts(self) -> (LiveFrontierOwner, MeasuredBindingFate, Event) {
        (self.owner, self.fate, self.event)
    }
}

/// Floor authority measured before a Pending-Died enclosing finalizer commits.
#[derive(Debug, PartialEq, Eq)]
pub struct PendingDiedOrdinaryFinalizer {
    resulting_floor: DeliverySeq,
    authority: FinalizerAuthority,
    provenance: Box<crate::lifecycle::storage::OrdinaryBindingFateRestore>,
}

#[derive(Debug, PartialEq, Eq)]
struct FinalizerAuthority;

/// Ordinary fate and unchanged owner prepared for an enclosing finalizer.
#[derive(Debug, PartialEq, Eq)]
pub struct PreparedPendingDiedOrdinaryFinalizer {
    owner: LiveFrontierOwner,
    fate: OrdinaryBindingFate,
    finalizer: PendingDiedOrdinaryFinalizer,
}

impl PreparedPendingDiedOrdinaryFinalizer {
    /// Returns the unchanged owner, measured fate, and one-use floor authority.
    #[must_use]
    pub fn into_parts(
        self,
    ) -> (
        LiveFrontierOwner,
        OrdinaryBindingFate,
        PendingDiedOrdinaryFinalizer,
    ) {
        (self.owner, self.fate, self.finalizer)
    }
}

impl LiveFrontierOwner {
    /// Applies a measured Ordinary floor after its enclosing finalizer transition.
    ///
    /// # Errors
    ///
    /// Returns [`LiveFrontierError`] if retained charges, the measured floor,
    /// marker precedence, or closure accounting disagree with the post-finalizer owner.
    pub fn complete_pending_died_ordinary_finalizer(
        self,
        finalizer: PendingDiedOrdinaryFinalizer,
    ) -> Result<Self, LiveFrontierError> {
        let PendingDiedOrdinaryFinalizer {
            resulting_floor,
            authority,
            provenance,
        } = finalizer;
        let FinalizerAuthority = authority;
        let mut owner = self.install_finalized_binding_fate_floor(resulting_floor)?;
        owner.retain_ordinary_cursor_release(provenance);
        Ok(owner)
    }
}

/// Typed reason protocol-owned binding-fate measurement refused.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BindingFateMeasurementError {
    /// The sealed token has no unique ordinary or recovered authority.
    Token,
    /// The token names a different conversation.
    Conversation,
    /// The token's participant is absent from the coupled frontier.
    Participant,
    /// The token's binding epoch or cursor disagrees with the coupled frontier.
    Binding,
    /// Ordinary/recovered terminal input disagrees with the token class.
    Terminal,
    /// Hard observer progress exceeds the candidate high watermark.
    ObserverProgress,
    /// The measured checked floor is outside the delivery-sequence domain.
    ResultingFloor,
    /// The coupled frontier, retained charges, or closure baseline refused
    /// installation, CARRYING the protocol's own cause.
    ///
    /// §3.3: the cause rides this carrier BY TYPE, because the park-versus-fatal
    /// decision downstream is not allowed to read it back out of a formatted
    /// message. The payload is free — both this enum and `LiveFrontierError`
    /// are `Copy` (`live_frontier.rs:1047`), so the derives above survive it.
    OwnerTransition(LiveFrontierError),
}

/// Refused measurement preserving every move-only input for serial retry.
#[derive(Debug, PartialEq, Eq)]
pub struct BindingFateMeasurementRefused {
    owner: LiveFrontierOwner,
    token: SealedBindingFateToken,
    terminal: BindingFateTerminal,
    error: BindingFateMeasurementError,
}

impl BindingFateMeasurementRefused {
    /// Returns the typed refusal reason.
    #[must_use]
    pub const fn error(&self) -> BindingFateMeasurementError {
        self.error
    }

    /// Recovers every unchanged input for a same-lock serial retry.
    #[must_use]
    pub fn into_parts(
        self,
    ) -> (
        LiveFrontierOwner,
        SealedBindingFateToken,
        BindingFateTerminal,
    ) {
        (self.owner, self.token, self.terminal)
    }
}

struct ValidatedBindingFateMeasurement {
    participant_id: crate::wire::ParticipantId,
    binding_epoch: crate::wire::BindingEpoch,
    resulting_floor: DeliverySeq,
    owner_plan: BindingFateOwnerPlan,
}

struct ValidatedBindingFateFloor {
    participant_id: crate::wire::ParticipantId,
    binding_epoch: crate::wire::BindingEpoch,
    resulting_floor: DeliverySeq,
}

impl LiveFrontierOwner {
    /// Consumes one sealed fate token after measuring its real post-release floor.
    ///
    /// The server supplies only hard observer progress and the closed terminal
    /// class. The participant, binding epoch, current retained floor, candidate
    /// high watermark, and remaining member cursors all come from protocol-owned
    /// state. Recovered internally mints its event and accepts no terminal.
    ///
    /// # Errors
    ///
    /// Returns every input unchanged when authority, terminal class, observer
    /// progress, or checked floor validation fails.
    pub fn prepare_binding_fate(
        self,
        token: SealedBindingFateToken,
        terminal: BindingFateTerminal,
        hard_observer_progress: DeliverySeq,
    ) -> Result<PreparedBindingFate, Box<BindingFateMeasurementRefused>> {
        let measurement = match validate_binding_fate_measurement(
            &self,
            &token,
            terminal,
            hard_observer_progress,
        ) {
            Ok(measurement) => measurement,
            Err(error) => return refusal(self, token, terminal, error),
        };
        let event = Event::binding_fate_observed(
            measurement.participant_id,
            measurement.binding_epoch,
            measurement.resulting_floor,
        );
        let fate = match terminal {
            BindingFateTerminal::Ordinary(terminal) => token
                .ordinary_binding_fate(terminal, measurement.resulting_floor)
                .map(MeasuredBindingFate::Ordinary),
            BindingFateTerminal::Recovered | BindingFateTerminal::RecoveredAndReserveFinalizer => {
                token
                    .recovered_binding_fate_measured(measurement.resulting_floor)
                    .map(MeasuredBindingFate::Recovered)
            }
        };
        match fate {
            Ok(fate) => {
                let mut owner = self.install_binding_fate_transition(
                    measurement.owner_plan,
                    measurement.resulting_floor,
                );
                if let MeasuredBindingFate::Ordinary(source) = &fate {
                    owner.retain_ordinary_cursor_release(Box::new(source.storage_description()));
                }
                Ok(PreparedBindingFate { owner, fate, event })
            }
            Err(token) => Err(Box::new(BindingFateMeasurementRefused {
                owner: self,
                token: *token,
                terminal,
                error: BindingFateMeasurementError::Terminal,
            })),
        }
    }

    /// Measures Ordinary without installing its owner transition before an enclosing finalizer.
    ///
    /// # Errors
    ///
    /// Returns every move-only input unchanged when the token, terminal,
    /// observer progress, measured floor, or pre-finalizer owner transition
    /// is inconsistent.
    pub fn prepare_pending_died_ordinary_finalizer(
        self,
        token: SealedBindingFateToken,
        terminal: CommittedDiedTerminal,
        hard_observer_progress: DeliverySeq,
    ) -> Result<PreparedPendingDiedOrdinaryFinalizer, Box<BindingFateMeasurementRefused>> {
        let terminal_input = BindingFateTerminal::Ordinary(terminal);
        let measurement = match validate_binding_fate_measurement(
            &self,
            &token,
            terminal_input,
            hard_observer_progress,
        ) {
            Ok(measurement) => measurement,
            Err(error) => {
                return Err(Box::new(BindingFateMeasurementRefused {
                    owner: self,
                    token,
                    terminal: terminal_input,
                    error,
                }));
            }
        };
        let resulting_floor = measurement.resulting_floor;
        match token.ordinary_binding_fate(terminal, resulting_floor) {
            Ok(fate) => Ok(PreparedPendingDiedOrdinaryFinalizer {
                owner: self,
                fate,
                finalizer: PendingDiedOrdinaryFinalizer {
                    resulting_floor,
                    authority: FinalizerAuthority,
                    provenance: Box::new(fate.storage_description()),
                },
            }),
            Err(token) => Err(Box::new(BindingFateMeasurementRefused {
                owner: self,
                token: *token,
                terminal: terminal_input,
                error: BindingFateMeasurementError::Terminal,
            })),
        }
    }

    /// Measures Ordinary after fenced proof minting consumed marker authority.
    ///
    /// The fenced attach transition itself owns the pending identity change, so
    /// this preparation validates the token, terminal, cursor, and exact floor
    /// but defers floor installation to the post-attach owner.
    ///
    /// # Errors
    ///
    /// Returns every move-only input unchanged when token authority, terminal,
    /// observer progress, or checked floor measurement is inconsistent.
    pub fn prepare_pending_died_ordinary_after_fenced_proof(
        self,
        token: SealedBindingFateToken,
        terminal: CommittedDiedTerminal,
        hard_observer_progress: DeliverySeq,
    ) -> Result<PreparedPendingDiedOrdinaryFinalizer, Box<BindingFateMeasurementRefused>> {
        let terminal_input = BindingFateTerminal::Ordinary(terminal);
        let measurement = match validate_binding_fate_floor(
            &self,
            &token,
            terminal_input,
            hard_observer_progress,
        ) {
            Ok(measurement) => measurement,
            Err(error) => {
                return Err(Box::new(BindingFateMeasurementRefused {
                    owner: self,
                    token,
                    terminal: terminal_input,
                    error,
                }));
            }
        };
        let resulting_floor = measurement.resulting_floor;
        match token.ordinary_binding_fate(terminal, resulting_floor) {
            Ok(fate) => Ok(PreparedPendingDiedOrdinaryFinalizer {
                owner: self,
                fate,
                finalizer: PendingDiedOrdinaryFinalizer {
                    resulting_floor,
                    authority: FinalizerAuthority,
                    provenance: Box::new(fate.storage_description()),
                },
            }),
            Err(token) => Err(Box::new(BindingFateMeasurementRefused {
                owner: self,
                token: *token,
                terminal: terminal_input,
                error: BindingFateMeasurementError::Terminal,
            })),
        }
    }
}

fn validate_binding_fate_measurement(
    owner: &LiveFrontierOwner,
    token: &SealedBindingFateToken,
    terminal: BindingFateTerminal,
    hard_observer_progress: DeliverySeq,
) -> Result<ValidatedBindingFateMeasurement, BindingFateMeasurementError> {
    let floor = validate_binding_fate_floor(owner, token, terminal, hard_observer_progress)?;
    let owner_plan = owner
        .prepare_binding_fate_transition(
            floor.participant_id,
            floor.binding_epoch,
            token
                .measurement_context()
                .ok_or(BindingFateMeasurementError::Token)?
                .cursor,
            floor.resulting_floor,
            terminal == BindingFateTerminal::RecoveredAndReserveFinalizer,
        )
        .map_err(BindingFateMeasurementError::OwnerTransition)?;
    Ok(ValidatedBindingFateMeasurement {
        participant_id: floor.participant_id,
        binding_epoch: floor.binding_epoch,
        resulting_floor: floor.resulting_floor,
        owner_plan,
    })
}

fn validate_binding_fate_floor(
    owner: &LiveFrontierOwner,
    token: &SealedBindingFateToken,
    terminal: BindingFateTerminal,
    hard_observer_progress: DeliverySeq,
) -> Result<ValidatedBindingFateFloor, BindingFateMeasurementError> {
    let Some(context) = token.measurement_context() else {
        return Err(BindingFateMeasurementError::Token);
    };
    if context.conversation_id != owner.frontiers().conversation_id() {
        return Err(BindingFateMeasurementError::Conversation);
    }
    let Some(participant) = owner
        .frontiers()
        .active_identities()
        .participants()
        .iter()
        .find(|participant| participant.participant_index() == context.participant_id)
    else {
        return Err(BindingFateMeasurementError::Participant);
    };
    if participant.cursor() != context.cursor
        || participant.binding() != FrontierBinding::Bound(context.binding_epoch)
            && participant.binding() != FrontierBinding::Detached(context.binding_epoch)
    {
        return Err(BindingFateMeasurementError::Binding);
    }
    let terminal_matches = match (token.intent(), terminal) {
        (Some(SealedBindingFateIntent::Ordinary), BindingFateTerminal::Ordinary(died)) => {
            died.conversation_id() == context.conversation_id
                && died.participant_id() == context.participant_id
                && died.binding_epoch() == context.binding_epoch
        }
        (
            Some(SealedBindingFateIntent::Recovered { .. }),
            BindingFateTerminal::Recovered | BindingFateTerminal::RecoveredAndReserveFinalizer,
        ) => true,
        _ => false,
    };
    if !terminal_matches {
        return Err(BindingFateMeasurementError::Terminal);
    }
    let candidate_high_watermark = owner.frontiers().sequence().ledger().high_watermark();
    if hard_observer_progress > candidate_high_watermark {
        return Err(BindingFateMeasurementError::ObserverProgress);
    }
    let minimum_remaining_cursor = owner
        .frontiers()
        .active_identities()
        .participants()
        .iter()
        .filter(|participant| participant.participant_index() != context.participant_id)
        .map(|participant| participant.cursor())
        .min();
    let measured = floor_transition(
        owner.frontiers().retained_floor(),
        minimum_remaining_cursor,
        candidate_high_watermark,
        hard_observer_progress,
        owner.frontiers().retained_floor(),
    );
    // §3.1 MARKERS PIN THE FLOOR (docs/design/F8-MARKER-POISON.md §3.1).
    //
    // `floor_transition` above takes no marker input of any kind -- its five
    // arguments are the retained floor, the minimum remaining cursor, the
    // candidate high watermark, hard observer progress, and the retained floor
    // again. Downstream, the live-frontier transition REFUSES a floor that
    // crosses a retained marker (`LiveFrontierError::Precedence`). Those were
    // two halves of one invariant with neither clamping, so the computation
    // could produce a floor the transition was obliged to reject: the incident
    // in §1, where the refusal WAS collapsed to a bare `OwnerTransition` and
    // the Died row carrying the intent WAS already durable by the time the
    // measurement ran. Both halves of that clause describe the PRE-FIX path and
    // nothing else. §3.3 now carries the cause by type (`OwnerTransition` takes
    // a `LiveFrontierError`), and §3.2 split the live path so the measurement
    // runs BEFORE the source append -- only the combined boot form still
    // measures against a source that is already durable.
    //
    // The purpose of a retained marker is precisely that its record stays
    // replayable until acked. Pinning is the marker's meaning; unsatisfiability
    // was the bug. So the measured floor is LOWERED to the minimum retained
    // marker-record sequence and can no longer cross one.
    //
    // NOT `cap_floor` (PRECEDENCE-CLAMP M2). `floor_transition`'s fifth argument
    // is named `cap_floor` and is `max(base_result, cap_floor)` — a floor
    // RAISER. This clamp LOWERS. Routing the lowest marker through `cap_floor`
    // yields `max(base, marker)`, which still sits above the marker in exactly
    // the poisoning case and would raise floors in cases that work today. The
    // clamp therefore has its own named primitive, `marker_clamped_floor`, and
    // never travels through `cap_floor`.
    //
    // The `Precedence` refusal STAYS as a backstop invariant. After this clamp
    // it should be unreachable from this path, and a reachable backstop firing
    // is a bug report rather than control flow.
    //
    // WHY A CLAMP BESIDE `search_capacity_floor` AND NOT A REUSE OF IT
    // (PRECEDENCE-CLAMP M3, decided rather than guessed).
    // `ordinary_record_projection.rs`'s `search_capacity_floor` does the
    // structurally similar thing for its own invariant, and it is the wrong
    // tool here for three independent reasons, any one of which is fatal:
    //   1. DIRECTION. It SEARCHES UPWARD, walking the floor to successively
    //      higher retained sequences until a capacity/credit baseline admits,
    //      and it feeds its answer back through `floor_transition`'s `cap_floor`
    //      — a raiser. Precedence needs the floor LOWERED.
    //   2. INVARIANT. Its subject is capacity: whether the resulting retained
    //      charge fits the configured cap. Precedence's subject is replayability:
    //      an unacked marker must stay retained. It treats a marker anchor below
    //      its chosen floor as an ERROR (`MarkerAnchorCapacity`) rather than as a
    //      bound, which is the opposite of pinning.
    //   3. INPUTS. It is a function of `OrdinaryProjectionFacts` — an order
    //      ledger, a sequence ledger, an admission request, encoded charges —
    //      none of which exist at a binding-fate measurement.
    // The two are NOT interchangeable, so the marker rule gets its own named
    // primitive, `marker_clamped_floor`, and the two live side by side.
    let lowest_retained_marker_seq = owner
        .frontiers()
        .retained_marker_records()
        .iter()
        .map(|record| record.delivery_seq)
        .min();
    let clamped_floor = marker_clamped_floor(measured.resulting_floor, lowest_retained_marker_seq);
    let Ok(resulting_floor) = DeliverySeq::try_from(clamped_floor) else {
        return Err(BindingFateMeasurementError::ResultingFloor);
    };
    Ok(ValidatedBindingFateFloor {
        participant_id: context.participant_id,
        binding_epoch: context.binding_epoch,
        resulting_floor,
    })
}

fn refusal(
    owner: LiveFrontierOwner,
    token: SealedBindingFateToken,
    terminal: BindingFateTerminal,
    error: BindingFateMeasurementError,
) -> Result<PreparedBindingFate, Box<BindingFateMeasurementRefused>> {
    Err(Box::new(BindingFateMeasurementRefused {
        owner,
        token,
        terminal,
        error,
    }))
}

impl PendingDiedOrdinaryFinalizer {
    /// Borrows the exact already-measured finalization floor into canonical bytes.
    #[must_use]
    pub const fn encode_checkpoint(&self) -> [u8; 8] {
        self.resulting_floor.to_be_bytes()
    }

    /// Restores only the finalizer belonging to a validated ordinary death fate.
    ///
    /// The live owner's existing completion checks still govern floor installation.
    ///
    /// # Errors
    ///
    /// Refuses an incorrect width or a floor different from the validated fate.
    pub fn restore_checkpoint(
        body: &[u8],
        fate: &OrdinaryBindingFate,
    ) -> Result<Self, crate::lifecycle::OwnerCheckpointRestoreError> {
        let bytes: [u8; 8] = body.try_into().map_err(|_| {
            crate::lifecycle::OwnerCheckpointRestoreError::Field("pending_died_finalizer.framing")
        })?;
        let resulting_floor = u64::from_be_bytes(bytes);
        if resulting_floor != fate.resulting_floor() {
            return Err(crate::lifecycle::OwnerCheckpointRestoreError::Field(
                "pending_died_finalizer.floor",
            ));
        }
        Ok(Self {
            resulting_floor,
            authority: FinalizerAuthority,
            provenance: Box::new(fate.storage_description()),
        })
    }
}