// file: crates/ksp-store-api/src/lib.rs // version: 5 #![warn(missing_docs)] #![deny(unreachable_pub)] #![forbid(unsafe_code)] //! Backend-agnostic persistence contracts for KSP Store implementations. //! //! `ksp-store-api` owns persistent models plus the contracts that operate on //! them. The `0.3.1` release is limited to N1 RAW/acquisition data. N2 //! STRUCTURAL is a later, distinct layer and no Program decode belongs to this //! crate. //! //! Models and capabilities deliberately have separate private module homes. //! Backend implementations, SQL, migrations, Config, Transport and runtime //! dispatch remain outside this crate. mod capability; mod error; mod model; /// Boxed async operation returned by object-safe Store capability contracts. pub use self::capability::StoreApiFuture; /// 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. pub use self::capability::raw_account::RawAccountObservationWrite; /// Read capability for complete canonical RAW account states. pub use self::capability::raw_account::RawAccountStateRead; /// Write capability for complete canonical RAW account-state acquisitions. pub use self::capability::raw_account::RawAccountStateWrite; /// Read capability for canonical RAW transaction retention metadata. pub use self::capability::raw_retention::RawTransactionRetentionRead; /// Write capability for policy-authorized RAW transaction retention transitions. pub use self::capability::raw_retention::RawTransactionRetentionWrite; /// Read capability for persisted RAW transaction observations. pub use self::capability::raw_transaction::RawTransactionObservationRead; /// Write capability for additional observations of already persisted RAW transactions. pub use self::capability::raw_transaction::RawTransactionObservationWrite; /// Read capability for canonical RAW transactions. pub use self::capability::raw_transaction::RawTransactionRead; /// Write capability for canonical RAW transaction acquisitions. pub use self::capability::raw_transaction::RawTransactionWrite; /// Error code used when a RAW write collides with divergent content for the same logical identity. pub use self::error::ERROR_CODE_RAW_CONFLICT; /// Error code used when a RAW Store model violates one of its backend-agnostic invariants. pub use self::error::ERROR_CODE_RAW_MODEL_INVALID; /// Error code used when a KSP-owned RAW persistence payload violates its format or admission contract. 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; /// Error code used when one RAW query or cursor violates backend-agnostic query invariants. pub use self::error::ERROR_CODE_RAW_QUERY_INVALID; /// Error code used when a RAW retention transition violates the logical lifecycle contract. pub use self::error::ERROR_CODE_RAW_RETENTION_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; /// Combined outcome of one atomic canonical RAW entity plus observation acquisition. pub use self::model::raw_outcome::RawAcquisitionWriteOutcome; /// Outcome for one canonical RAW entity in an idempotent persistence operation. pub use self::model::raw_outcome::RawEntityWriteOutcome; /// Outcome for one deterministic acquisition observation write. pub use self::model::raw_outcome::RawObservationWriteOutcome; /// Maximum opaque query cursor length admitted by the Store API. pub use self::model::raw_pagination::MAX_RAW_PAGE_CURSOR_BYTES; /// Backend-independent list query for complete canonical RAW account states. pub use self::model::raw_pagination::RawAccountStateQuery; /// One deterministic page of backend-independent Store results. pub use self::model::raw_pagination::RawPage; /// Opaque backend-owned cursor returned by one deterministic Store query. pub use self::model::raw_pagination::RawPageCursor; /// Caller-requested page size without an arbitrary KSP policy ceiling. pub use self::model::raw_pagination::RawPageLimit; /// Opaque-cursor page request used by backend-independent list operations. pub use self::model::raw_pagination::RawPageRequest; /// Optional inclusive Solana slot bounds for one Store query. pub use self::model::raw_pagination::RawSlotRange; /// Deterministic traversal direction for Store list queries. pub use self::model::raw_pagination::RawSortDirection; /// Backend-independent list query for canonical RAW transactions. pub use self::model::raw_pagination::RawTransactionQuery; /// 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. pub use self::model::raw_primitives::MAX_RAW_PAYLOAD_BYTES; /// Maximum source-wire payload size recorded as acquisition metadata. pub use self::model::raw_primitives::MAX_RAW_SOURCE_PAYLOAD_BYTES; /// Maximum supported Unix millisecond timestamp. pub use self::model::raw_primitives::MAX_RAW_UNIX_MILLIS; /// Origin category describing why one acquisition was performed. pub use self::model::raw_primitives::RawAcquisitionOrigin; /// Safe source-independent acquisition provenance attached to one persisted observation. pub use self::model::raw_primitives::RawAcquisitionProvenance; /// Fixed-size digest identifying canonical or source bytes without retaining them. pub use self::model::raw_primitives::RawContentHash; /// Bounded identifier of one KSP-owned source-independent RAW persistence format. pub use self::model::raw_primitives::RawFormatId; /// Bounded logical network/cluster identifier used in backend-independent Store identities. pub use self::model::raw_primitives::RawNetworkId; /// Stable deterministic idempotence key for one persisted acquisition observation. pub use self::model::raw_primitives::RawObservationKey; /// Bounded source-independent KSP RAW persistence payload. pub use self::model::raw_primitives::RawPayload; /// Bounded logical code used by acquisition provenance fields. pub use self::model::raw_primitives::RawProvenanceCode; /// Bounded UTC timestamp represented as whole milliseconds since Unix epoch. pub use self::model::raw_primitives::RawTimestamp; /// Canonical 64-byte Solana transaction signature used by Store identities. pub use self::model::raw_primitives::RawTransactionSignature; /// Logical availability state of one canonical RAW payload. pub use self::model::raw_retention::RawRetentionState; /// Outcome of one atomic RAW retention transition. pub use self::model::raw_retention::RawRetentionWriteOutcome; /// Explicit write mode for canonical RAW transaction acquisitions. pub use self::model::raw_retention::RawTransactionAcquisitionMode; /// Requested compare-and-transition operation for one RAW transaction retention state. pub use self::model::raw_retention::RawTransactionRetentionTransition; /// Minimal durable identity retained after a canonical RAW transaction payload is purged. pub use self::model::raw_retention::RawTransactionTombstone; /// Canonical source-independent N1 RAW transaction persisted by Store backends. pub use self::model::raw_transaction::RawTransaction; /// Persistable acquisition observation linked to one canonical RAW transaction. pub use self::model::raw_transaction::RawTransactionObservation; /// Durable backend-independent identity of one canonical RAW transaction. pub use self::model::raw_transaction::RawTransactionReference; /// Common KSP error type used by Store-facing contracts. pub use ksp_core_lib::Error; /// Stable structured code identifying a KSP error category and condition. pub use ksp_core_lib::ErrorCode; /// Structured contextual field attached to a KSP error. pub use ksp_core_lib::ErrorContext; /// Canonical Solana account address primitive shared by persistent models. pub use ksp_core_lib::Pubkey; /// Common KSP result alias using [`Error`]. pub use ksp_core_lib::Result;