// file: crates/ksp-store-api/src/model/raw_outcome.rs
// version: 3
/// Outcome for one canonical RAW entity in an idempotent persistence operation.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum RawEntityWriteOutcome {
    /// The canonical RAW entity was inserted for the first time.
    Inserted,
    /// Identical canonical content was already durable.
    AlreadyPresent,
    /// A previously purged RAW entity was explicitly rehydrated.
    Rehydrated,
    /// Normal persistence skipped a durable purged tombstone.
    SkippedPurged,
}

/// Outcome for one deterministic acquisition observation write.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum RawObservationWriteOutcome {
    /// The observation was inserted for the first time.
    Inserted,
    /// The same observation key already identified identical durable content.
    AlreadyPresent,
    /// No observation was recorded because the associated RAW entity was intentionally skipped.
    NotRecorded,
}

/// Combined outcome of one atomic canonical RAW entity plus observation acquisition.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct RawAcquisitionWriteOutcome {
    entity: crate::RawEntityWriteOutcome,
    observation: crate::RawObservationWriteOutcome,
}

impl RawAcquisitionWriteOutcome {
    /// Creates one backend-independent atomic acquisition outcome.
    #[must_use]
    pub const fn new(entity: crate::RawEntityWriteOutcome, observation: crate::RawObservationWriteOutcome) -> Self {
        return Self { entity, observation };
    }

    /// Returns the canonical RAW entity write outcome.
    #[must_use]
    pub const fn entity(&self) -> crate::RawEntityWriteOutcome {
        return self.entity;
    }

    /// Returns the acquisition observation write outcome.
    #[must_use]
    pub const fn observation(&self) -> crate::RawObservationWriteOutcome {
        return self.observation;
    }
}

/// Durable Store outcome for one RAW transaction acquisition after variant-aware convergence.
///
/// Every variant represents a successful Store-domain result. In particular,
/// [`Self::QuarantinedConflict`] is durable success and must not be reinterpreted as a
/// transport failure or terminal persistence error by callers.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum RawTransactionVariantWriteOutcome {
    /// First durable variant became the initial canonical transaction.
    InsertedCanonical,
    /// Incoming content exactly matched an already durable variant/canonical representation.
    ObservedExact,
    /// Incoming content was durably observed while the current canonical variant remained strictly more complete.
    ObservedCompatibleLessComplete,
    /// Incoming content was durably persisted and atomically promoted because it was strictly more complete.
    PromotedCompatibleMoreComplete,
    /// Divergent or incomparable content was durably preserved without changing the current canonical variant.
    QuarantinedConflict,
    /// Explicit force-rehydration restored a previously purged logical transaction into variant-aware storage.
    Rehydrated,
    /// Normal acquisition respected an existing purged tombstone and performed no rehydration.
    SkippedPurged,
}