v0.3.1-pre.005

crates/ksp-store-api/src/capability.rs

@@ -1,8 +1,18 @@
 // file: crates/ksp-store-api/src/capability.rs
-// version: 1
+// version: 2
 
 //! Private home for backend-agnostic Store capability contracts.
 //!
-//! `0.3.1-pre.002` establishes the ownership boundary only. Concrete read and
-//! write capabilities are introduced after the RAW models they operate on are
-//! defined; no backend/runtime contract belongs here.
+//! Capabilities are split by persistent family and operation direction so a
+//! backend can implement only the contracts it actually supports. The runtime
+//! Store facade, backend selection and concrete database implementations remain
+//! outside `ksp-store-api`.
+
+pub(crate) mod raw_account;
+pub(crate) mod raw_transaction;
+
+/// Boxed async operation returned by object-safe Store capability contracts.
+///
+/// The alias uses only standard-library primitives so backend implementations
+/// need no async helper dependency merely to implement `ksp-store-api`.
+pub type StoreApiFuture<'a, T> = std::pin::Pin<std::boxed::Box<dyn std::future::Future<Output = T> + std::marker::Send + 'a>>;

crates/ksp-store-api/src/capability/raw_account.rs

@@ -0,0 +1,49 @@
+// 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<()>>;
+}

crates/ksp-store-api/src/capability/raw_transaction.rs

@@ -0,0 +1,50 @@
+// file: crates/ksp-store-api/src/capability/raw_transaction.rs
+// version: 1
+
+/// Read capability for canonical RAW transactions.
+///
+/// Implementations must return the canonical Store model without exposing
+/// backend rows, SQL handles or transport-specific DTOs. Absence is represented
+/// by `None`; backend/runtime failures use the common KSP error contract.
+pub trait RawTransactionRead: std::marker::Send + std::marker::Sync {
+    /// Reads one canonical RAW transaction by durable backend-independent reference.
+    fn get_raw_transaction<'a>(
+        &'a self,
+        reference: &'a crate::RawTransactionReference,
+    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawTransaction>>>;
+}
+
+/// Write capability for canonical RAW transaction acquisitions.
+///
+/// The transaction 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 RawTransactionWrite: std::marker::Send + std::marker::Sync {
+    /// Persists one complete RAW transaction together with one observation atomically.
+    fn persist_raw_transaction_acquisition<'a>(
+        &'a self,
+        transaction: crate::RawTransaction,
+        observation: crate::RawTransactionObservation,
+    ) -> crate::StoreApiFuture<'a, crate::Result<()>>;
+}
+
+/// Read capability for persisted RAW transaction observations.
+pub trait RawTransactionObservationRead: std::marker::Send + std::marker::Sync {
+    /// Reads one transaction observation by deterministic producer-owned idempotence key.
+    fn get_raw_transaction_observation<'a>(
+        &'a self,
+        observation_key: &'a crate::RawObservationKey,
+    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawTransactionObservation>>>;
+}
+
+/// Write capability for an additional observation of an already persisted RAW transaction.
+///
+/// This capability exists so repeated acquisitions can be recorded without
+/// resubmitting the potentially large canonical transaction payload. The
+/// referenced transaction must already exist; detailed outcomes are deferred to
+/// `0.3.1-pre.006`.
+pub trait RawTransactionObservationWrite: std::marker::Send + std::marker::Sync {
+    /// Persists one additional acquisition observation for an existing RAW transaction.
+    fn record_raw_transaction_observation<'a>(&'a self, observation: crate::RawTransactionObservation) -> crate::StoreApiFuture<'a, crate::Result<()>>;
+}

crates/ksp-store-api/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/lib.rs
-// version: 3
+// version: 4
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -20,6 +20,24 @@ mod capability;
 mod error;
 mod model;
 
+/// Boxed async operation returned by object-safe Store capability contracts.
+pub use self::capability::StoreApiFuture;
+/// Read capability for persisted RAW account-state observations.
+pub use self::capability::raw_account::RawAccountObservationRead;
+/// Write capability for additional observations of already persisted RAW account states.
+pub use self::capability::raw_account::RawAccountObservationWrite;
+/// Read capability for complete canonical RAW account states.
+pub use self::capability::raw_account::RawAccountStateRead;
+/// Write capability for complete canonical RAW account-state acquisitions.
+pub use self::capability::raw_account::RawAccountStateWrite;
+/// Read capability for persisted RAW transaction observations.
+pub use self::capability::raw_transaction::RawTransactionObservationRead;
+/// Write capability for additional observations of already persisted RAW transactions.
+pub use self::capability::raw_transaction::RawTransactionObservationWrite;
+/// Read capability for canonical RAW transactions.
+pub use self::capability::raw_transaction::RawTransactionRead;
+/// Write capability for canonical RAW transaction acquisitions.
+pub use self::capability::raw_transaction::RawTransactionWrite;
 /// Error code used when a RAW Store model violates one of its backend-agnostic invariants.
 pub use self::error::ERROR_CODE_RAW_MODEL_INVALID;
 /// Error code used when a KSP-owned RAW persistence payload violates its format or admission contract.