// file: crates/ksp-store-api/src/lib.rs
// version: 9
#![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 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.
pub use self::capability::raw_account::RawAccountObservationWrite;
/// Read capability for data-free random-access RAW account-state inspection.
pub use self::capability::raw_account::RawAccountStateInspectionRead;
/// 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 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.
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;
/// 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.
pub use self::model::raw_inspection::RawAccountStateSummary;
/// One bounded random-access inspection page with exact logical counts.
pub use self::model::raw_inspection::RawInspectionPage;
/// Random-access page request dedicated to bounded interactive RAW inspection.
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.
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;
/// Durable Store outcome for one variant-aware RAW transaction acquisition.
pub use self::model::raw_outcome::RawTransactionVariantWriteOutcome;
/// 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;
/// Durable lifecycle status of one RAW transaction conflict case.
pub use self::model::raw_transaction::RawTransactionConflictStatus;
/// 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;
/// Validated backend-neutral result of comparing canonical and incoming RAW transaction variants.
pub use self::model::raw_transaction::RawTransactionVariantComparison;
/// Stable non-zero Store identity of one persisted RAW transaction variant.
pub use self::model::raw_transaction::RawTransactionVariantId;
/// Origin of one persisted RAW transaction variant.
pub use self::model::raw_transaction::RawTransactionVariantOrigin;
/// Durable reference to one persisted RAW transaction variant.
pub use self::model::raw_transaction::RawTransactionVariantReference;
/// Backend-neutral quality relation between canonical and incoming RAW transaction variants.
pub use self::model::raw_transaction::RawTransactionVariantRelation;
/// Stable backend-neutral reason explaining one RAW transaction variant relation.
pub use self::model::raw_transaction::RawTransactionVariantRelationReason;
/// Compares one incoming RAW transaction variant against the currently canonical variant.
pub use self::model::raw_transaction::compare_raw_transaction_variants;
/// 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;