v0.3.1-pre.006

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_account.rs
-// version: 1
+// version: 2
 
 /// Read capability for complete canonical RAW account states.
 ///
@@ -12,21 +12,31 @@ pub trait RawAccountStateRead: std::marker::Send + std::marker::Sync {
         &'a self,
         reference: &'a crate::RawAccountStateReference,
     ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawAccountState>>>;
+
+    /// Lists deterministic account-state references using an opaque backend cursor.
+    ///
+    /// The backend must not invent a KSP policy ceiling below the caller's
+    /// request. A real backend/physical limitation may determine the page that
+    /// can be served and continuation is represented by the opaque cursor.
+    fn list_raw_account_states<'a>(
+        &'a self,
+        query: &'a crate::RawAccountStateQuery,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawPage<crate::RawAccountStateReference>>>;
 }
 
 /// 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.
+/// the other side fails. Divergent content for one logical identity is a stable
+/// conflict error, never a silent overwrite.
 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<()>>;
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawAcquisitionWriteOutcome>>;
 }
 
 /// Read capability for persisted RAW account-state observations.
@@ -41,9 +51,11 @@ pub trait RawAccountObservationRead: std::marker::Send + std::marker::Sync {
 /// 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`.
+/// without resubmitting account bytes. The referenced state must already exist.
 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<()>>;
+    fn record_raw_account_observation<'a>(
+        &'a self,
+        observation: crate::RawAccountObservation,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawObservationWriteOutcome>>;
 }

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

@@ -0,0 +1,29 @@
+// file: crates/ksp-store-api/src/capability/raw_retention.rs
+// version: 1
+
+/// Read capability for canonical RAW transaction retention metadata.
+pub trait RawTransactionRetentionRead: std::marker::Send + std::marker::Sync {
+    /// Reads the logical retention state for one known transaction identity.
+    fn get_raw_transaction_retention_state<'a>(
+        &'a self,
+        reference: &'a crate::RawTransactionReference,
+    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawRetentionState>>>;
+
+    /// Reads the minimal durable tombstone when the transaction payload was purged.
+    fn get_raw_transaction_tombstone<'a>(
+        &'a self,
+        reference: &'a crate::RawTransactionReference,
+    ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawTransactionTombstone>>>;
+}
+
+/// Write capability for policy-authorized RAW transaction retention transitions.
+///
+/// This contract applies a transition selected by an external worker/job policy;
+/// the Store backend never decides by itself that higher processing is complete.
+pub trait RawTransactionRetentionWrite: std::marker::Send + std::marker::Sync {
+    /// Applies one atomic forward lifecycle transition chosen by the caller.
+    fn transition_raw_transaction_retention<'a>(
+        &'a self,
+        transition: crate::RawTransactionRetentionTransition,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawRetentionWriteOutcome>>;
+}

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_transaction.rs
-// version: 1
+// version: 2
 
 /// Read capability for canonical RAW transactions.
 ///
@@ -12,21 +12,32 @@ pub trait RawTransactionRead: std::marker::Send + std::marker::Sync {
         &'a self,
         reference: &'a crate::RawTransactionReference,
     ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawTransaction>>>;
+
+    /// Lists deterministic transaction references using an opaque backend cursor.
+    ///
+    /// The backend must honor the caller-requested page limit unless a real
+    /// backend/physical limitation prevents it. `ksp-store-api` imposes no
+    /// arbitrary smaller result ceiling or executor policy.
+    fn list_raw_transactions<'a>(
+        &'a self,
+        query: &'a crate::RawTransactionQuery,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawPage<crate::RawTransactionReference>>>;
 }
 
 /// 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.
+/// side fails. Divergent content for one logical identity is a stable conflict
+/// error, never a silent overwrite.
 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<()>>;
+        mode: crate::RawTransactionAcquisitionMode,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawAcquisitionWriteOutcome>>;
 }
 
 /// Read capability for persisted RAW transaction observations.
@@ -42,9 +53,11 @@ pub trait RawTransactionObservationRead: std::marker::Send + std::marker::Sync {
 ///
 /// 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`.
+/// referenced transaction must already exist.
 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<()>>;
+    fn record_raw_transaction_observation<'a>(
+        &'a self,
+        observation: crate::RawTransactionObservation,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawObservationWriteOutcome>>;
 }