// file: crates/ksp-store-api/src/capability/raw_account.rs
// version: 1

/// Read capability for complete canonical RAW account states.
///
/// Implementations must return the common Store model without leaking backend
/// rows, SQL handles or acquisition transport types. Absence is represented by
/// `None`; backend/runtime failures use the common KSP error contract.
pub trait RawAccountStateRead: std::marker::Send + std::marker::Sync {
    /// Reads one complete canonical RAW account state by durable reference.
    fn get_raw_account_state<'a>(
        &'a self,
        reference: &'a crate::RawAccountStateReference,
    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawAccountState>>>;
}

/// Write capability for complete RAW account-state acquisitions.
///
/// The account state and its acquisition observation form one logical
/// persistence operation. An implementation must not leave one side durable if
/// the other side fails. Detailed idempotence/conflict outcomes are introduced
/// by `0.3.1-pre.006`; this tranche exposes only success/failure.
pub trait RawAccountStateWrite: std::marker::Send + std::marker::Sync {
    /// Persists one complete RAW account state together with one observation atomically.
    fn persist_raw_account_acquisition<'a>(
        &'a self,
        state: crate::RawAccountState,
        observation: crate::RawAccountObservation,
    ) -> crate::StoreApiFuture<'a, crate::Result<()>>;
}

/// Read capability for persisted RAW account-state observations.
pub trait RawAccountObservationRead: std::marker::Send + std::marker::Sync {
    /// Reads one account observation by deterministic producer-owned idempotence key.
    fn get_raw_account_observation<'a>(
        &'a self,
        observation_key: &'a crate::RawObservationKey,
    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawAccountObservation>>>;
}

/// Write capability for an additional observation of an already persisted RAW account state.
///
/// This capability allows repeated HTTP/WS/gRPC acquisitions to be retained
/// without resubmitting account bytes. The referenced state must already exist;
/// detailed outcomes are deferred to `0.3.1-pre.006`.
pub trait RawAccountObservationWrite: std::marker::Send + std::marker::Sync {
    /// Persists one additional acquisition observation for an existing RAW account state.
    fn record_raw_account_observation<'a>(&'a self, observation: crate::RawAccountObservation) -> crate::StoreApiFuture<'a, crate::Result<()>>;
}