v0.3.8-pre.009

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/model/raw_inspection.rs
-// version: 1
+// version: 2
 
 /// Random-access page request dedicated to bounded interactive RAW inspection.
 ///
@@ -87,6 +87,202 @@ impl<T> RawInspectionPage<T> {
     }
 }
 
+/// Backend-independent random-access inspection query for RAW transaction observations.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawTransactionObservationInspectionQuery {
+    direction: crate::RawSortDirection,
+    network: crate::RawNetworkId,
+    page: crate::RawInspectionPageRequest,
+    transaction: std::option::Option<crate::RawTransactionReference>,
+}
+
+impl RawTransactionObservationInspectionQuery {
+    /// Creates one transaction-observation inspection query after enforcing network coherence.
+    pub fn try_new(
+        network: crate::RawNetworkId,
+        transaction: std::option::Option<crate::RawTransactionReference>,
+        direction: crate::RawSortDirection,
+        page: crate::RawInspectionPageRequest,
+    ) -> crate::Result<Self> {
+        if let std::option::Option::Some(reference) = transaction.as_ref() {
+            if reference.network() != &network {
+                return std::result::Result::Err(raw_model_error("transaction"));
+            }
+        }
+        return std::result::Result::Ok(Self { direction, network, page, transaction });
+    }
+
+    /// Returns the requested deterministic traversal direction.
+    #[must_use]
+    pub const fn direction(&self) -> crate::RawSortDirection {
+        return self.direction;
+    }
+
+    /// Returns the mandatory logical network scope.
+    #[must_use]
+    pub fn network(&self) -> &crate::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the random-access inspection page request.
+    #[must_use]
+    pub const fn page(&self) -> crate::RawInspectionPageRequest {
+        return self.page;
+    }
+
+    /// Returns the optional exact transaction identity used to filter observations.
+    #[must_use]
+    pub fn transaction(&self) -> std::option::Option<&crate::RawTransactionReference> {
+        return self.transaction.as_ref();
+    }
+}
+
+/// Backend-independent random-access inspection query for RAW account observations.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawAccountObservationInspectionQuery {
+    account: std::option::Option<crate::RawAccountStateReference>,
+    direction: crate::RawSortDirection,
+    network: crate::RawNetworkId,
+    page: crate::RawInspectionPageRequest,
+}
+
+impl RawAccountObservationInspectionQuery {
+    /// Creates one account-observation inspection query after enforcing network coherence.
+    pub fn try_new(
+        network: crate::RawNetworkId,
+        account: std::option::Option<crate::RawAccountStateReference>,
+        direction: crate::RawSortDirection,
+        page: crate::RawInspectionPageRequest,
+    ) -> crate::Result<Self> {
+        if let std::option::Option::Some(reference) = account.as_ref() {
+            if reference.network() != &network {
+                return std::result::Result::Err(raw_model_error("account"));
+            }
+        }
+        return std::result::Result::Ok(Self { account, direction, network, page });
+    }
+
+    /// Returns the optional exact account-state identity used to filter observations.
+    #[must_use]
+    pub fn account(&self) -> std::option::Option<&crate::RawAccountStateReference> {
+        return self.account.as_ref();
+    }
+
+    /// Returns the requested deterministic traversal direction.
+    #[must_use]
+    pub const fn direction(&self) -> crate::RawSortDirection {
+        return self.direction;
+    }
+
+    /// Returns the mandatory logical network scope.
+    #[must_use]
+    pub fn network(&self) -> &crate::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the random-access inspection page request.
+    #[must_use]
+    pub const fn page(&self) -> crate::RawInspectionPageRequest {
+        return self.page;
+    }
+}
+
+/// Safe observation summary for one canonical RAW transaction acquisition.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawTransactionObservationSummary {
+    observation_key: crate::RawObservationKey,
+    provenance: crate::RawAcquisitionProvenance,
+    transaction: crate::RawTransactionReference,
+}
+
+impl RawTransactionObservationSummary {
+    /// Creates one safe transaction-observation summary without RAW payload bytes.
+    #[must_use]
+    pub fn new(observation_key: crate::RawObservationKey, transaction: crate::RawTransactionReference, provenance: crate::RawAcquisitionProvenance) -> Self {
+        return Self { observation_key, provenance, transaction };
+    }
+
+    /// Returns the producer-owned deterministic observation key.
+    #[must_use]
+    pub const fn observation_key(&self) -> crate::RawObservationKey {
+        return self.observation_key;
+    }
+
+    /// Returns safe source-independent acquisition provenance.
+    #[must_use]
+    pub fn provenance(&self) -> &crate::RawAcquisitionProvenance {
+        return &self.provenance;
+    }
+
+    /// Returns the durable transaction identity observed by this acquisition.
+    #[must_use]
+    pub fn transaction(&self) -> &crate::RawTransactionReference {
+        return &self.transaction;
+    }
+}
+
+/// Safe observation summary for one canonical RAW account-state acquisition.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawAccountObservationSummary {
+    account: crate::RawAccountStateReference,
+    is_startup: std::option::Option<bool>,
+    observation_key: crate::RawObservationKey,
+    provenance: crate::RawAcquisitionProvenance,
+    transaction_signature: std::option::Option<crate::RawTransactionSignature>,
+    write_version: std::option::Option<u64>,
+}
+
+impl RawAccountObservationSummary {
+    /// Creates one safe account-observation summary without account data bytes.
+    #[must_use]
+    pub fn new(
+        observation_key: crate::RawObservationKey,
+        account: crate::RawAccountStateReference,
+        provenance: crate::RawAcquisitionProvenance,
+        is_startup: std::option::Option<bool>,
+        transaction_signature: std::option::Option<crate::RawTransactionSignature>,
+        write_version: std::option::Option<u64>,
+    ) -> Self {
+        return Self { account, is_startup, observation_key, provenance, transaction_signature, write_version };
+    }
+
+    /// Returns the durable account-state identity observed by this acquisition.
+    #[must_use]
+    pub fn account(&self) -> &crate::RawAccountStateReference {
+        return &self.account;
+    }
+
+    /// Returns the optional source-reported startup/replay marker.
+    #[must_use]
+    pub const fn is_startup(&self) -> std::option::Option<bool> {
+        return self.is_startup;
+    }
+
+    /// Returns the producer-owned deterministic observation key.
+    #[must_use]
+    pub const fn observation_key(&self) -> crate::RawObservationKey {
+        return self.observation_key;
+    }
+
+    /// Returns safe source-independent acquisition provenance.
+    #[must_use]
+    pub fn provenance(&self) -> &crate::RawAcquisitionProvenance {
+        return &self.provenance;
+    }
+
+    /// Returns the optional transaction signature associated with the observed account write.
+    #[must_use]
+    pub const fn transaction_signature(&self) -> std::option::Option<crate::RawTransactionSignature> {
+        return self.transaction_signature;
+    }
+
+    /// Returns the optional source-specific account write version.
+    #[must_use]
+    pub const fn write_version(&self) -> std::option::Option<u64> {
+        return self.write_version;
+    }
+}
+
 /// Backend-independent random-access inspection query for RAW transactions.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct RawTransactionInspectionQuery {