ic-backup 0.64.0

//! Pure admission of independently qualified original lifecycle settlement.

use super::{
    IcObservationAssociationError, IcObservationReplyView, IcObservationResponseView,
    validate_response,
};
use crate::model::settlement::EffectAttribution;
use crate::model::{
    artifacts::ArtifactChecksumRecord,
    attempt_journal::{AttemptJournalRecord, ObservationOutcomeRecord},
    ic_observation::{IcLifecycleSettlement, IcObservationRequest, IcObservationResponse},
    ic_request::IcManagementMethodRecord as Method,
};
use crate::policy::settlement_identity::{SettlementIdentity, SettlementIdentityMismatch};
use thiserror::Error;

/// Matched passive original attribution, never an authenticated receipt.
#[derive(Debug)]
pub struct IcLifecycleSettlementView<'a> {
    observation: IcObservationResponseView<'a>,
    settlement: &'a IcLifecycleSettlement,
}
impl<'a> IcLifecycleSettlementView<'a> {
    /// Read the independently claimed outcome; integration qualification precedes recording.
    #[must_use]
    pub const fn outcome(&self) -> ObservationOutcomeRecord {
        match &self.settlement.attribution {
            EffectAttribution::Applied { .. } => ObservationOutcomeRecord::Applied,
            EffectAttribution::NotApplied { .. } => ObservationOutcomeRecord::NotApplied,
            EffectAttribution::Unresolved { .. } => ObservationOutcomeRecord::Uncertain,
        }
    }
    /// Read exact bounded status association under original reservations.
    #[must_use]
    pub const fn observation(&self) -> &IcObservationResponseView<'a> {
        &self.observation
    }
    /// Read original attribution and retained qualification evidence.
    #[must_use]
    pub const fn settlement(&self) -> &'a IcLifecycleSettlement {
        self.settlement
    }
}

/// Bind independently qualified stop/start/load settlement to the original status evidence.
///
/// Reuses current reservation/actual claim checks and the bounded status decoder.
/// Current status, controllers and module hashes never infer any outcome. Applied
/// load claims independently qualify exact restored state; desired status does not
/// identify the original request. Opposite state cannot exclude transient application.
/// Lost replies cannot enter this successful-observation boundary as uncertainty.
///
/// This matches passive claims only. Authentication, chronology, attribution,
/// freshness, read permission and command custody remain integration-owned. Only
/// that integration explicitly records the existing journal receipt. No IO, calls,
/// automatic transitions, retries, refunds, restart or terminal/release admission occur.
/// # Errors
/// Rejects capture/inventory lanes, changed reservations/actual claims, invalid wire,
/// different authority/attempts, challenge or exact retained status/evidence identity.
pub fn validate_lifecycle_settlement<'a>(
    request: &IcObservationRequest<'a>,
    journal: &AttemptJournalRecord,
    response: &'a IcObservationResponse,
    challenge: &ArtifactChecksumRecord,
    settlement: &'a IcLifecycleSettlement,
) -> Result<IcLifecycleSettlementView<'a>, IcLifecycleSettlementError> {
    if !matches!(
        request.mutation().method(),
        Method::StopCanister | Method::StartCanister | Method::LoadCanisterSnapshot
    ) || request.payload().method() != Method::CanisterStatus
    {
        return Err(IcLifecycleSettlementError::UnsupportedMethod);
    }
    let observation = validate_response(request, journal, response)?;
    SettlementIdentity::from(&settlement.context).compare(&SettlementIdentity {
        authority: &request.authority().digest(),
        mutation_attempt: request.mutation_attempt(),
        observation_attempt: request.observation_attempt(),
        challenge,
    })?;
    let IcObservationReplyView::Status(status) = observation.reply() else {
        return Err(IcLifecycleSettlementError::UnsupportedMethod);
    };
    if settlement.status != status.digest() {
        return Err(IcLifecycleSettlementError::StatusMismatch);
    }
    if settlement.context.observation_evidence != response.input().evidence {
        return Err(IcLifecycleSettlementError::ObservationEvidenceMismatch);
    }
    Ok(IcLifecycleSettlementView {
        observation,
        settlement,
    })
}

/// Typed local claim denial; original allowances, obligations and references remain retained.
#[derive(Debug, Error)]
pub enum IcLifecycleSettlementError {
    /// Only original stop/start/load with a separately reserved status call is supported.
    #[error("lifecycle settlement requires original stop/start/load and status observation")]
    UnsupportedMethod,
    /// Existing association, current reservation or bounded decoder rejected.
    #[error(transparent)]
    Observation(#[from] IcObservationAssociationError),
    /// Exact original settlement identity or retained evidence differs.
    #[error(transparent)]
    Identity(#[from] SettlementIdentityMismatch),
    /// Exact original status request/raw reply digest differs.
    #[error("lifecycle settlement status evidence differs")]
    StatusMismatch,
    /// Retained opaque observation evidence differs even if reply bytes match.
    #[error("lifecycle settlement observation evidence differs")]
    ObservationEvidenceMismatch,
}

#[cfg(test)]
mod tests;