0.3.16-pre.007

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_transaction.rs
-// version: 4
+// version: 5
 
 /// Read capability for canonical RAW transactions.
 ///
@@ -42,8 +42,9 @@ pub trait RawTransactionInspectionRead: std::marker::Send + std::marker::Sync {
 ///
 /// The transaction and its acquisition observation form one logical persistence
 /// operation. An implementation must not leave one side durable if the other
-/// side fails. Divergent content for one logical identity is a stable conflict
-/// error, never a silent overwrite.
+/// side fails. Divergent or incomparable content must be preserved as a durable
+/// variant/conflict outcome rather than silently overwriting the canonical transaction
+/// or being projected as a terminal persistence 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>(

crates/ksp-store-api/src/model/raw_outcome.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/model/raw_outcome.rs
-// version: 3
+// version: 4
 /// Outcome for one canonical RAW entity in an idempotent persistence operation.
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
@@ -31,13 +31,24 @@ pub enum RawObservationWriteOutcome {
 pub struct RawAcquisitionWriteOutcome {
     entity: crate::RawEntityWriteOutcome,
     observation: crate::RawObservationWriteOutcome,
+    transaction_variant: std::option::Option<crate::RawTransactionVariantWriteOutcome>,
 }
 
 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 };
+        return Self { entity, observation, transaction_variant: std::option::Option::None };
+    }
+
+    /// Creates one backend-independent atomic RAW transaction acquisition outcome with variant convergence classification.
+    #[must_use]
+    pub const fn with_transaction_variant(
+        entity: crate::RawEntityWriteOutcome,
+        observation: crate::RawObservationWriteOutcome,
+        transaction_variant: crate::RawTransactionVariantWriteOutcome,
+    ) -> Self {
+        return Self { entity, observation, transaction_variant: std::option::Option::Some(transaction_variant) };
     }
 
     /// Returns the canonical RAW entity write outcome.
@@ -51,6 +62,12 @@ impl RawAcquisitionWriteOutcome {
     pub const fn observation(&self) -> crate::RawObservationWriteOutcome {
         return self.observation;
     }
+
+    /// Returns the variant-aware transaction outcome when the persistence operation was a RAW transaction acquisition.
+    #[must_use]
+    pub const fn transaction_variant(&self) -> std::option::Option<crate::RawTransactionVariantWriteOutcome> {
+        return self.transaction_variant;
+    }
 }
 
 /// Durable Store outcome for one RAW transaction acquisition after variant-aware convergence.

crates/ksp-store-api/tests/public_api.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/tests/public_api.rs
-// version: 10
+// version: 11
 
 //! Integration canaries for the public `ksp-store-api` surface.
 
@@ -170,6 +170,13 @@ fn public_pre_006_query_outcome_and_retention_contracts_are_available_from_crate
         ksp_store_api::RawAcquisitionWriteOutcome::new(ksp_store_api::RawEntityWriteOutcome::Inserted, ksp_store_api::RawObservationWriteOutcome::Inserted);
     assert_eq!(outcome.entity(), ksp_store_api::RawEntityWriteOutcome::Inserted);
     assert_eq!(outcome.observation(), ksp_store_api::RawObservationWriteOutcome::Inserted);
+    assert_eq!(outcome.transaction_variant(), std::option::Option::None);
+    let variant_outcome = ksp_store_api::RawAcquisitionWriteOutcome::with_transaction_variant(
+        ksp_store_api::RawEntityWriteOutcome::AlreadyPresent,
+        ksp_store_api::RawObservationWriteOutcome::Inserted,
+        ksp_store_api::RawTransactionVariantWriteOutcome::QuarantinedConflict,
+    );
+    assert_eq!(variant_outcome.transaction_variant(), std::option::Option::Some(ksp_store_api::RawTransactionVariantWriteOutcome::QuarantinedConflict));
     let retention_read: std::option::Option<&dyn ksp_store_api::RawTransactionRetentionRead> = std::option::Option::None;
     let retention_write: std::option::Option<&dyn ksp_store_api::RawTransactionRetentionWrite> = std::option::Option::None;
     assert!(retention_read.is_none());