v0.3.1-pre.004

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/lib.rs
-// version: 2
+// version: 3
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -26,6 +26,14 @@ pub use self::error::ERROR_CODE_RAW_MODEL_INVALID;
 pub use self::error::ERROR_CODE_RAW_PAYLOAD_INVALID;
 /// Error code used when acquisition provenance is malformed, unsafe or internally inconsistent.
 pub use self::error::ERROR_CODE_RAW_PROVENANCE_INVALID;
+/// Persistable acquisition observation linked to one complete canonical RAW account state.
+pub use self::model::raw_account::RawAccountObservation;
+/// Canonical complete N1 RAW account state independent from acquisition transport.
+pub use self::model::raw_account::RawAccountState;
+/// Durable backend-independent identity of one canonical RAW account state.
+pub use self::model::raw_account::RawAccountStateReference;
+/// Maximum complete RAW account-data length admitted by the Store API.
+pub use self::model::raw_primitives::MAX_RAW_ACCOUNT_DATA_BYTES;
 /// Maximum UTF-8 byte length accepted for one safe logical RAW/provenance code.
 pub use self::model::raw_primitives::MAX_RAW_CODE_BYTES;
 /// Maximum KSP-owned canonical RAW payload admitted by the Store API.

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/src/model.rs
-// version: 2
+// version: 3
 
 //! Private home for persistent Store models.
 //!
@@ -8,5 +8,6 @@
 //! backend capabilities remain separate even when one capability operates on
 //! one or more models.
 
+pub(crate) mod raw_account;
 pub(crate) mod raw_primitives;
 pub(crate) mod raw_transaction;

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

@@ -0,0 +1,231 @@
+// file: crates/ksp-store-api/src/model/raw_account.rs
+// version: 1
+
+/// Durable backend-independent identity of one canonical RAW account state.
+///
+/// The content hash is part of the identity because one account can be written more than once
+/// inside the same slot while standard HTTP/WebSocket surfaces do not expose Yellowstone's
+/// `write_version`. Multiple observations of the same complete state therefore converge on the
+/// same reference without making a provider-specific write ordinal part of the common model.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct RawAccountStateReference {
+    network: crate::RawNetworkId,
+    pubkey: ksp_core_lib::Pubkey,
+    slot: u64,
+    state_hash: crate::RawContentHash,
+}
+
+impl RawAccountStateReference {
+    /// Creates one durable account-state identity from network, account, slot and canonical state digest.
+    #[must_use]
+    pub fn new(network: crate::RawNetworkId, pubkey: ksp_core_lib::Pubkey, slot: u64, state_hash: crate::RawContentHash) -> Self {
+        return Self { network, pubkey, slot, state_hash };
+    }
+
+    /// Returns the logical Solana network/cluster identifier.
+    #[must_use]
+    pub fn network(&self) -> &crate::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the account public key.
+    #[must_use]
+    pub const fn pubkey(&self) -> &ksp_core_lib::Pubkey {
+        return &self.pubkey;
+    }
+
+    /// Returns the slot associated with this complete account state.
+    #[must_use]
+    pub const fn slot(&self) -> u64 {
+        return self.slot;
+    }
+
+    /// Returns the producer-supplied digest of the complete canonical account state.
+    #[must_use]
+    pub const fn state_hash(&self) -> crate::RawContentHash {
+        return self.state_hash;
+    }
+}
+
+/// Canonical complete N1 RAW account state independent from HTTP, WebSocket or gRPC acquisition.
+///
+/// Only complete raw account bytes are admissible. A transport response using `jsonParsed`, a
+/// request-side data slice, or a response without a durable slot context must be normalized or
+/// reacquired before this model is constructed.
+pub struct RawAccountState {
+    data: std::boxed::Box<[u8]>,
+    executable: bool,
+    lamports: u64,
+    owner: ksp_core_lib::Pubkey,
+    reference: crate::RawAccountStateReference,
+    rent_epoch: u64,
+}
+
+impl RawAccountState {
+    /// Creates one complete canonical RAW account state after Store-owned admission checks.
+    pub fn try_new(
+        reference: crate::RawAccountStateReference,
+        lamports: u64,
+        owner: ksp_core_lib::Pubkey,
+        executable: bool,
+        rent_epoch: u64,
+        data: std::boxed::Box<[u8]>,
+    ) -> ksp_core_lib::Result<Self> {
+        if data.len() > crate::MAX_RAW_ACCOUNT_DATA_BYTES {
+            return std::result::Result::Err(
+                ksp_core_lib::Error::new(crate::ERROR_CODE_RAW_MODEL_INVALID, "invalid backend-agnostic RAW Store model")
+                    .with_context("field", "account_data")
+                    .with_context("actual_len", data.len().to_string())
+                    .with_context("maximum_len", crate::MAX_RAW_ACCOUNT_DATA_BYTES.to_string()),
+            );
+        }
+        return std::result::Result::Ok(Self { data, executable, lamports, owner, reference, rent_epoch });
+    }
+
+    /// Returns the exact complete account bytes used by future decoders.
+    #[must_use]
+    pub fn data(&self) -> &[u8] {
+        return self.data.as_ref();
+    }
+
+    /// Returns the complete account-data length in bytes.
+    #[must_use]
+    pub fn data_len(&self) -> usize {
+        return self.data.len();
+    }
+
+    /// Returns whether the account is executable.
+    #[must_use]
+    pub const fn executable(&self) -> bool {
+        return self.executable;
+    }
+
+    /// Returns the account lamport balance.
+    #[must_use]
+    pub const fn lamports(&self) -> u64 {
+        return self.lamports;
+    }
+
+    /// Returns the account owner program public key.
+    #[must_use]
+    pub const fn owner(&self) -> &ksp_core_lib::Pubkey {
+        return &self.owner;
+    }
+
+    /// Returns the durable source-independent account-state identity.
+    #[must_use]
+    pub fn reference(&self) -> &crate::RawAccountStateReference {
+        return &self.reference;
+    }
+
+    /// Returns the rent epoch reported for this account state.
+    #[must_use]
+    pub const fn rent_epoch(&self) -> u64 {
+        return self.rent_epoch;
+    }
+}
+
+impl std::fmt::Debug for RawAccountState {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter
+            .debug_struct("RawAccountState")
+            .field("reference", &self.reference)
+            .field("lamports", &self.lamports)
+            .field("owner", &self.owner)
+            .field("executable", &self.executable)
+            .field("rent_epoch", &self.rent_epoch)
+            .field("data_len", &self.data.len())
+            .finish();
+    }
+}
+
+/// Persistable acquisition observation linked to one complete canonical RAW account state.
+///
+/// Yellowstone-only metadata remains optional observation detail and never changes the canonical
+/// account state itself. HTTP/WS acquisitions therefore use the same observation type without
+/// inventing a `write_version`, transaction signature or startup flag.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RawAccountObservation {
+    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 RawAccountObservation {
+    /// Creates one successful observation of a complete canonical RAW account state.
+    #[must_use]
+    pub fn new(observation_key: crate::RawObservationKey, account: crate::RawAccountStateReference, provenance: crate::RawAcquisitionProvenance) -> Self {
+        return Self {
+            account,
+            is_startup: std::option::Option::None,
+            observation_key,
+            provenance,
+            transaction_signature: std::option::Option::None,
+            write_version: std::option::Option::None,
+        };
+    }
+
+    /// Attaches a provider-reported startup/replay marker when the source exposes one.
+    #[must_use]
+    pub fn with_is_startup(mut self, value: bool) -> Self {
+        self.is_startup = std::option::Option::Some(value);
+        return self;
+    }
+
+    /// Attaches the transaction signature associated with the account write when exposed by the source.
+    #[must_use]
+    pub fn with_transaction_signature(mut self, value: crate::RawTransactionSignature) -> Self {
+        self.transaction_signature = std::option::Option::Some(value);
+        return self;
+    }
+
+    /// Attaches the source-specific account write version when the source exposes one.
+    #[must_use]
+    pub fn with_write_version(mut self, value: u64) -> Self {
+        self.write_version = std::option::Option::Some(value);
+        return self;
+    }
+
+    /// 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 deterministic producer-owned observation idempotence 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 this 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;
+    }
+}
+
+#[cfg(test)]
+#[path = "../../unit_tests/model/raw_account.rs"]
+mod tests;

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

@@ -1,6 +1,10 @@
 // file: crates/ksp-store-api/src/model/raw_primitives.rs
-// version: 1
+// version: 2
 
+/// Maximum complete RAW account-data length admitted by the Store API.
+///
+/// This is a Store admission guard, not a Solana protocol-size claim.
+pub const MAX_RAW_ACCOUNT_DATA_BYTES: usize = 16 * 1024 * 1024;
 /// Maximum UTF-8 byte length accepted for one safe logical RAW/provenance code.
 pub const MAX_RAW_CODE_BYTES: usize = 128;
 /// Maximum KSP-owned canonical RAW payload admitted by the Store API.

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

@@ -1,10 +1,10 @@
 // file: crates/ksp-store-api/tests/dependency_boundary.rs
-// version: 2
+// version: 3
 
 //! Dependency canaries for the Store API RAW foundation.
 
 #[test]
-fn pre_003_manifest_keeps_exact_core_only_runtime_dependency() {
+fn pre_004_manifest_keeps_exact_core_only_runtime_dependency() {
     let manifest = include_str!("../Cargo.toml");
     let dependencies_tail = manifest.split("[dependencies]").nth(1);
     assert!(dependencies_tail.is_some(), "Store API dependencies section must exist");
@@ -49,17 +49,19 @@ fn pre_003_manifest_keeps_exact_core_only_runtime_dependency() {
 }
 
 #[test]
-fn pre_003_source_boundary_keeps_raw_models_passive_and_backend_free() {
+fn pre_004_source_boundary_keeps_raw_models_passive_and_backend_free() {
     let crate_root = include_str!("../src/lib.rs");
     let model_home = include_str!("../src/model.rs");
+    let raw_account = include_str!("../src/model/raw_account.rs");
     let raw_primitives = include_str!("../src/model/raw_primitives.rs");
     let raw_transaction = include_str!("../src/model/raw_transaction.rs");
     assert!(crate_root.contains("mod capability;"));
     assert!(crate_root.contains("mod error;"));
     assert!(crate_root.contains("mod model;"));
+    assert!(model_home.contains("raw_account"));
     assert!(model_home.contains("raw_primitives"));
     assert!(model_home.contains("raw_transaction"));
-    for source in [crate_root, model_home, raw_primitives, raw_transaction] {
+    for source in [crate_root, model_home, raw_account, raw_primitives, raw_transaction] {
         for forbidden in [
             "ksp_store_lib",
             "ksp_store_postgres_lib",
@@ -77,6 +79,9 @@ fn pre_003_source_boundary_keeps_raw_models_passive_and_backend_free() {
         }
     }
     assert!(!raw_transaction.contains("RawLog"));
+    for forbidden in ["TransactionStatusObservation", "RawLogNotification", "RawSlotEvent", "RawVoteEvent", "RawBlock", "YellowstoneEntry"] {
+        assert!(!crate_root.contains(forbidden), "deferred pre.004 model leaked into Store API surface: {forbidden}");
+    }
     return;
 }
 

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-api/tests/public_api.rs
-// version: 2
+// version: 3
 
 //! Integration canaries for the public `ksp-store-api` surface.
 
@@ -80,3 +80,48 @@ fn public_pre_003_surface_keeps_backend_and_structural_types_out() {
     }
     return;
 }
+
+#[test]
+fn public_pre_004_raw_account_state_and_observation_are_constructible_from_crate_root() {
+    let network = match ksp_store_api::RawNetworkId::new("mainnet-beta".to_owned()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let reference = ksp_store_api::RawAccountStateReference::new(
+        network,
+        ksp_store_api::Pubkey::new_from_array([21_u8; 32]),
+        55,
+        ksp_store_api::RawContentHash::new([22_u8; 32]),
+    );
+    let state = ksp_store_api::RawAccountState::try_new(
+        reference.clone(),
+        123,
+        ksp_store_api::Pubkey::new_from_array([23_u8; 32]),
+        false,
+        9,
+        vec![1_u8, 2_u8].into_boxed_slice(),
+    );
+    assert!(state.is_ok());
+    let received_at = match ksp_store_api::RawTimestamp::from_unix_millis(2_000) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let provider = match code("provider") {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let protocol = match code("solana_http") {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let method = match code("getAccountInfo") {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let provenance = ksp_store_api::RawAcquisitionProvenance::new(provider, protocol, method, ksp_store_api::RawAcquisitionOrigin::Backfill, received_at);
+    let observation = ksp_store_api::RawAccountObservation::new(ksp_store_api::RawObservationKey::new([24_u8; 32]), reference, provenance);
+    assert_eq!(observation.account().slot(), 55);
+    assert!(observation.write_version().is_none());
+    assert_eq!(ksp_store_api::MAX_RAW_ACCOUNT_DATA_BYTES, 16 * 1024 * 1024);
+    return;
+}

crates/ksp-store-api/unit_tests/model/raw_account.rs

@@ -0,0 +1,108 @@
+// file: crates/ksp-store-api/unit_tests/model/raw_account.rs
+// version: 1
+
+fn network() -> std::option::Option<crate::RawNetworkId> {
+    return match crate::RawNetworkId::new("mainnet-beta".to_owned()) {
+        std::result::Result::Ok(value) => std::option::Option::Some(value),
+        std::result::Result::Err(_) => std::option::Option::None,
+    };
+}
+
+fn provenance() -> std::option::Option<crate::RawAcquisitionProvenance> {
+    let provider = match crate::RawProvenanceCode::new("publicnode".to_owned()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    let protocol = match crate::RawProvenanceCode::new("yellowstone_grpc".to_owned()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    let method = match crate::RawProvenanceCode::new("accounts".to_owned()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    let received_at = match crate::RawTimestamp::from_unix_millis(1_000) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    return std::option::Option::Some(crate::RawAcquisitionProvenance::new(provider, protocol, method, crate::RawAcquisitionOrigin::Live, received_at));
+}
+
+#[test]
+fn raw_account_state_preserves_complete_common_fields_and_redacts_data_debug() {
+    let network = match network() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let pubkey = ksp_core_lib::Pubkey::new_from_array([1_u8; 32]);
+    let owner = ksp_core_lib::Pubkey::new_from_array([2_u8; 32]);
+    let reference = crate::RawAccountStateReference::new(network, pubkey, 42, crate::RawContentHash::new([3_u8; 32]));
+    let data = b"ACCOUNT_DATA_SENTINEL_NEVER_RENDER".to_vec().into_boxed_slice();
+    let state_result = crate::RawAccountState::try_new(reference.clone(), 500, owner, false, 7, data);
+    assert!(state_result.is_ok());
+    let state = match state_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(state.reference(), &reference);
+    assert_eq!(state.lamports(), 500);
+    assert!(!state.executable());
+    assert_eq!(state.rent_epoch(), 7);
+    assert_eq!(state.data(), b"ACCOUNT_DATA_SENTINEL_NEVER_RENDER");
+    let debug = format!("{state:?}");
+    assert!(!debug.contains("ACCOUNT_DATA_SENTINEL_NEVER_RENDER"));
+    assert!(debug.contains("data_len"));
+    return;
+}
+
+#[test]
+fn raw_account_state_rejects_only_oversized_data_and_allows_empty_accounts() {
+    let first_network = match network() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let first_reference =
+        crate::RawAccountStateReference::new(first_network, ksp_core_lib::Pubkey::new_from_array([4_u8; 32]), 1, crate::RawContentHash::new([5_u8; 32]));
+    let empty = crate::RawAccountState::try_new(
+        first_reference,
+        0,
+        ksp_core_lib::Pubkey::new_from_array([6_u8; 32]),
+        false,
+        0,
+        std::vec::Vec::new().into_boxed_slice(),
+    );
+    assert!(empty.is_ok());
+    let second_network = match network() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let second_reference =
+        crate::RawAccountStateReference::new(second_network, ksp_core_lib::Pubkey::new_from_array([7_u8; 32]), 2, crate::RawContentHash::new([8_u8; 32]));
+    let oversized = vec![0_u8; crate::MAX_RAW_ACCOUNT_DATA_BYTES + 1].into_boxed_slice();
+    let rejected = crate::RawAccountState::try_new(second_reference, 0, ksp_core_lib::Pubkey::new_from_array([9_u8; 32]), false, 0, oversized);
+    assert!(rejected.is_err());
+    return;
+}
+
+#[test]
+fn raw_account_observation_keeps_yellowstone_specific_metadata_optional() {
+    let network = match network() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let reference =
+        crate::RawAccountStateReference::new(network, ksp_core_lib::Pubkey::new_from_array([10_u8; 32]), 99, crate::RawContentHash::new([11_u8; 32]));
+    let provenance = match provenance() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let observation = crate::RawAccountObservation::new(crate::RawObservationKey::new([12_u8; 32]), reference.clone(), provenance)
+        .with_write_version(17)
+        .with_transaction_signature(crate::RawTransactionSignature::new([13_u8; 64]))
+        .with_is_startup(false);
+    assert_eq!(observation.account(), &reference);
+    assert_eq!(observation.write_version(), std::option::Option::Some(17));
+    assert_eq!(observation.is_startup(), std::option::Option::Some(false));
+    assert_eq!(observation.transaction_signature(), std::option::Option::Some(crate::RawTransactionSignature::new([13_u8; 64])));
+    return;
+}