v0.3.1-pre.007

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_retention.rs
-// version: 1
+// version: 2
 
 /// Read capability for canonical RAW transaction retention metadata.
 pub trait RawTransactionRetentionRead: std::marker::Send + std::marker::Sync {
@@ -20,6 +20,10 @@ pub trait RawTransactionRetentionRead: std::marker::Send + std::marker::Sync {
 ///
 /// This contract applies a transition selected by an external worker/job policy;
 /// the Store backend never decides by itself that higher processing is complete.
+/// Implementations must compare the persisted state with `transition.expected()`
+/// atomically with the update. A concurrent state change must return
+/// [`crate::RawRetentionWriteOutcome::ExpectedStateMismatch`] unless the entity
+/// is already at the requested target.
 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>(