143 lines
8.4 KiB
Rust
143 lines
8.4 KiB
Rust
// 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;
|