v0.3.8-pre.009

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_account.rs
-// version: 3
+// version: 4
 
 /// Read capability for complete canonical RAW account states.
 ///
@@ -62,6 +62,15 @@ pub trait RawAccountObservationRead: std::marker::Send + std::marker::Sync {
     ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawAccountObservation>>>;
 }
 
+/// Read capability for random-access RAW account-observation inspection.
+pub trait RawAccountObservationInspectionRead: std::marker::Send + std::marker::Sync {
+    /// Inspects one account-observation window with exact logical counts.
+    fn inspect_raw_account_observations<'a>(
+        &'a self,
+        query: &'a crate::RawAccountObservationInspectionQuery,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawInspectionPage<crate::RawAccountObservationSummary>>>;
+}
+
 /// Write capability for an additional observation of an already persisted RAW account state.
 ///
 /// This capability allows repeated HTTP/WS/gRPC acquisitions to be retained

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/capability/raw_transaction.rs
-// version: 3
+// version: 4
 
 /// Read capability for canonical RAW transactions.
 ///
@@ -63,6 +63,15 @@ pub trait RawTransactionObservationRead: std::marker::Send + std::marker::Sync {
     ) -> crate::StoreApiFuture<'a, crate::Result<std::option::Option<crate::RawTransactionObservation>>>;
 }
 
+/// Read capability for random-access RAW transaction-observation inspection.
+pub trait RawTransactionObservationInspectionRead: std::marker::Send + std::marker::Sync {
+    /// Inspects one transaction-observation window with exact logical counts.
+    fn inspect_raw_transaction_observations<'a>(
+        &'a self,
+        query: &'a crate::RawTransactionObservationInspectionQuery,
+    ) -> crate::StoreApiFuture<'a, crate::Result<crate::RawInspectionPage<crate::RawTransactionObservationSummary>>>;
+}
+
 /// Write capability for an additional observation of an already persisted RAW transaction.
 ///
 /// This capability exists so repeated acquisitions can be recorded without

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/lib.rs
-// version: 6
+// version: 7
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -22,6 +22,8 @@ mod model;
 
 /// Boxed async operation returned by object-safe Store capability contracts.
 pub use self::capability::StoreApiFuture;
+/// Read capability for random-access RAW account-observation inspection.
+pub use self::capability::raw_account::RawAccountObservationInspectionRead;
 /// 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.
@@ -38,6 +40,8 @@ pub use self::capability::raw_retention::RawTransactionRetentionRead;
 pub use self::capability::raw_retention::RawTransactionRetentionWrite;
 /// Read capability for payload-free random-access RAW transaction inspection.
 pub use self::capability::raw_transaction::RawTransactionInspectionRead;
+/// Read capability for random-access RAW transaction-observation inspection.
+pub use self::capability::raw_transaction::RawTransactionObservationInspectionRead;
 /// Read capability for persisted RAW transaction observations.
 pub use self::capability::raw_transaction::RawTransactionObservationRead;
 /// Write capability for additional observations of already persisted RAW transactions.
@@ -64,6 +68,10 @@ pub use self::model::raw_account::RawAccountObservation;
 pub use self::model::raw_account::RawAccountState;
 /// Durable backend-independent identity of one canonical RAW account state.
 pub use self::model::raw_account::RawAccountStateReference;
+/// Backend-independent random-access inspection query for RAW account observations.
+pub use self::model::raw_inspection::RawAccountObservationInspectionQuery;
+/// Safe observation summary for one canonical RAW account-state acquisition.
+pub use self::model::raw_inspection::RawAccountObservationSummary;
 /// Backend-independent random-access inspection query for RAW account states.
 pub use self::model::raw_inspection::RawAccountStateInspectionQuery;
 /// Data-free summary of one canonical RAW account state for operator inspection.
@@ -74,6 +82,10 @@ pub use self::model::raw_inspection::RawInspectionPage;
 pub use self::model::raw_inspection::RawInspectionPageRequest;
 /// Backend-independent random-access inspection query for RAW transactions.
 pub use self::model::raw_inspection::RawTransactionInspectionQuery;
+/// Backend-independent random-access inspection query for RAW transaction observations.
+pub use self::model::raw_inspection::RawTransactionObservationInspectionQuery;
+/// Safe observation summary for one canonical RAW transaction acquisition.
+pub use self::model::raw_inspection::RawTransactionObservationSummary;
 /// Payload-free summary of one canonical RAW transaction for operator inspection.
 pub use self::model::raw_inspection::RawTransactionSummary;
 /// Combined outcome of one atomic canonical RAW entity plus observation acquisition.

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 {