// file: crates/ksp-store-lib/src/lib.rs
// version: 10

#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]

//! Common backend-neutral Store runtime facade for KSP.
//!
//! The runtime facade owns backend selection, lifecycle, safe diagnostics and
//! backend-neutral capability dispatch. `0.3.3-pre.008` completed the six PostgreSQL
//! `RawTransaction` capabilities. `0.3.4-pre.008` adds the four `RawAccount*` capabilities
//! on both the physical backend and this common facade, completing the canonical RAW runtime inventory at
//! ten capabilities without exposing physical types. The `0.3.8` inspection
//! contracts are reexported here before backend/facade dispatch is opened.
//!
//! The default `postgres` feature compiles the official PostgreSQL backend as
//! an optional implementation dependency. No backend implementation type is
//! part of this crate's public surface.

mod constants;
mod error;
mod health;
mod settings;
mod store;

/// Error code reserved for operations attempted after a Store backend is closed.
pub use self::error::ERROR_CODE_BACKEND_CLOSED;
/// Error code used when a known Store backend is selected without its compiled feature.
pub use self::error::ERROR_CODE_BACKEND_NOT_COMPILED;
/// Error code used when a compiled Store backend cannot complete opening.
pub use self::error::ERROR_CODE_BACKEND_OPEN_FAILED;
/// Error code used when PostgreSQL physical configuration is malformed or unsupported.
pub use self::error::ERROR_CODE_POSTGRES_CONFIG_INVALID;
/// Error code used when PostgreSQL physical connection establishment fails.
pub use self::error::ERROR_CODE_POSTGRES_CONNECT_FAILED;
/// Error code used when PostgreSQL returns persisted RAW data incompatible with the Store contract.
pub use self::error::ERROR_CODE_POSTGRES_DATA_INVALID;
/// Error code used when a lightweight PostgreSQL health/readiness probe fails safely.
pub use self::error::ERROR_CODE_POSTGRES_HEALTH_FAILED;
/// Error code used when PostgreSQL migration/bootstrap execution fails safely.
pub use self::error::ERROR_CODE_POSTGRES_MIGRATION_FAILED;
/// Error code used when PostgreSQL migration history diverges from the embedded immutable KSP history.
pub use self::error::ERROR_CODE_POSTGRES_MIGRATION_MISMATCH;
/// Error code used when a requested RAW page size exceeds PostgreSQL's exact physical LIMIT boundary.
pub use self::error::ERROR_CODE_POSTGRES_PAGE_LIMIT_UNSUPPORTED;
/// Error code used when a bounded PostgreSQL pool operation reaches its deadline.
pub use self::error::ERROR_CODE_POSTGRES_POOL_TIMEOUT;
/// Error code used when a PostgreSQL RAW read statement fails safely.
pub use self::error::ERROR_CODE_POSTGRES_READ_FAILED;
/// Error code used when PostgreSQL cannot represent a requested RAW retention compaction state.
pub use self::error::ERROR_CODE_POSTGRES_RETENTION_COMPACTION_UNSUPPORTED;
/// Error code used when PostgreSQL schema history is newer than this Store runtime.
pub use self::error::ERROR_CODE_POSTGRES_SCHEMA_NEWER;
/// Error code used when PostgreSQL verified TLS setup or negotiation fails.
pub use self::error::ERROR_CODE_POSTGRES_TLS_FAILED;
/// Error code used when a PostgreSQL RAW write statement or transaction fails safely.
pub use self::error::ERROR_CODE_POSTGRES_WRITE_FAILED;
/// Error code used when a RAW write requires a canonical reference that is not durable.
pub use self::error::ERROR_CODE_RAW_REFERENCE_NOT_FOUND;
/// Error code used when Store settings violate backend-neutral bounds or invariants.
pub use self::error::ERROR_CODE_SETTINGS_INVALID;
/// Error code used when explicit Store shutdown exceeds its configured deadline.
pub use self::error::ERROR_CODE_SHUTDOWN_TIMEOUT;
/// Error code used when a network-scoped operation targets a network different from the Store binding.
pub use self::error::ERROR_CODE_WRONG_NETWORK;
/// Portable Store health/readiness projection containing only safe diagnostics.
pub use self::health::StoreHealthSnapshot;
/// Portable Store health state independent from physical backend types.
pub use self::health::StoreHealthState;
/// Safe synchronous Store runtime snapshot containing backend-neutral pool counters.
pub use self::health::StoreRuntimeSnapshot;
/// Bounded PostgreSQL bootstrap and migration settings owned by the Store facade.
pub use self::settings::PostgresBootstrapSettings;
/// Bounded PostgreSQL connection-pool settings owned by the Store facade.
pub use self::settings::PostgresPoolSettings;
/// PostgreSQL settings owned by the Store facade without exposing backend implementation types.
pub use self::settings::PostgresStoreSettings;
/// TLS policy accepted by the backend-neutral PostgreSQL settings surface.
pub use self::settings::PostgresTlsMode;
/// Backend identity understood independently from compiled Cargo features.
pub use self::settings::StoreBackendKind;
/// Backend-specific settings selected through the common Store facade.
pub use self::settings::StoreBackendSettings;
/// Complete backend-neutral settings consumed by the common Store runtime facade.
pub use self::settings::StoreSettings;
/// Opaque common Store runtime facade with consuming async shutdown.
pub use self::store::Store;
/// Error code used when a RAW write collides with divergent content for the same logical identity.
pub use ksp_store_api::ERROR_CODE_RAW_CONFLICT;
/// Error code used when a RAW Store model violates one of its backend-agnostic invariants.
pub use ksp_store_api::ERROR_CODE_RAW_MODEL_INVALID;
/// Error code used when a KSP-owned RAW persistence payload violates its format or admission contract.
pub use ksp_store_api::ERROR_CODE_RAW_PAYLOAD_INVALID;
/// Error code used when acquisition provenance is malformed, unsafe or internally inconsistent.
pub use ksp_store_api::ERROR_CODE_RAW_PROVENANCE_INVALID;
/// Error code used when one RAW query or cursor violates backend-agnostic query invariants.
pub use ksp_store_api::ERROR_CODE_RAW_QUERY_INVALID;
/// Error code used when a RAW retention transition violates the logical lifecycle contract.
pub use ksp_store_api::ERROR_CODE_RAW_RETENTION_INVALID;
/// Common KSP error type used by Store-facing contracts.
pub use ksp_store_api::Error;
/// Stable structured code identifying a KSP error category and condition.
pub use ksp_store_api::ErrorCode;
/// Structured contextual field attached to a KSP error.
pub use ksp_store_api::ErrorContext;
/// Maximum complete RAW account-data length admitted by the Store API.
pub use ksp_store_api::MAX_RAW_ACCOUNT_DATA_BYTES;
/// Maximum UTF-8 byte length accepted for one safe logical RAW/provenance code.
pub use ksp_store_api::MAX_RAW_CODE_BYTES;
/// Maximum opaque query cursor length admitted by the Store API.
pub use ksp_store_api::MAX_RAW_PAGE_CURSOR_BYTES;
/// Maximum KSP-owned canonical RAW payload admitted by the Store API.
pub use ksp_store_api::MAX_RAW_PAYLOAD_BYTES;
/// Maximum source-wire payload size recorded as acquisition metadata.
pub use ksp_store_api::MAX_RAW_SOURCE_PAYLOAD_BYTES;
/// Maximum supported Unix millisecond timestamp.
pub use ksp_store_api::MAX_RAW_UNIX_MILLIS;
/// Canonical Solana account address primitive shared by persistent models.
pub use ksp_store_api::Pubkey;
/// Persistable acquisition observation linked to one complete canonical RAW account state.
pub use ksp_store_api::RawAccountObservation;
/// Read capability for persisted RAW account-state observations.
pub use ksp_store_api::RawAccountObservationRead;
/// Write capability for additional observations of already persisted RAW account states.
pub use ksp_store_api::RawAccountObservationWrite;
/// Canonical complete N1 RAW account state independent from acquisition transport.
pub use ksp_store_api::RawAccountState;
/// Backend-independent random-access inspection query for RAW account states.
pub use ksp_store_api::RawAccountStateInspectionQuery;
/// Read capability for data-free random-access RAW account-state inspection.
pub use ksp_store_api::RawAccountStateInspectionRead;
/// Backend-independent list query for complete canonical RAW account states.
pub use ksp_store_api::RawAccountStateQuery;
/// Read capability for complete canonical RAW account states.
pub use ksp_store_api::RawAccountStateRead;
/// Durable backend-independent identity of one canonical RAW account state.
pub use ksp_store_api::RawAccountStateReference;
/// Data-free summary of one canonical RAW account state for operator inspection.
pub use ksp_store_api::RawAccountStateSummary;
/// Write capability for complete canonical RAW account-state acquisitions.
pub use ksp_store_api::RawAccountStateWrite;
/// Origin category describing why one acquisition was performed.
pub use ksp_store_api::RawAcquisitionOrigin;
/// Safe source-independent acquisition provenance attached to one persisted observation.
pub use ksp_store_api::RawAcquisitionProvenance;
/// Combined outcome of one atomic canonical RAW entity plus observation acquisition.
pub use ksp_store_api::RawAcquisitionWriteOutcome;
/// Fixed-size digest identifying canonical or source bytes without retaining them.
pub use ksp_store_api::RawContentHash;
/// Outcome for one canonical RAW entity in an idempotent persistence operation.
pub use ksp_store_api::RawEntityWriteOutcome;
/// Bounded identifier of one KSP-owned source-independent RAW persistence format.
pub use ksp_store_api::RawFormatId;
/// One bounded random-access inspection page with exact logical counts.
pub use ksp_store_api::RawInspectionPage;
/// Random-access page request dedicated to bounded interactive RAW inspection.
pub use ksp_store_api::RawInspectionPageRequest;
/// Bounded logical network/cluster identifier used in backend-independent Store identities.
pub use ksp_store_api::RawNetworkId;
/// Stable deterministic idempotence key for one persisted acquisition observation.
pub use ksp_store_api::RawObservationKey;
/// Outcome for one deterministic acquisition observation write.
pub use ksp_store_api::RawObservationWriteOutcome;
/// One deterministic page of backend-independent Store results.
pub use ksp_store_api::RawPage;
/// Opaque backend-owned cursor returned by one deterministic Store query.
pub use ksp_store_api::RawPageCursor;
/// Caller-requested page size without an arbitrary KSP policy ceiling.
pub use ksp_store_api::RawPageLimit;
/// Opaque-cursor page request used by backend-independent list operations.
pub use ksp_store_api::RawPageRequest;
/// Bounded source-independent KSP RAW persistence payload.
pub use ksp_store_api::RawPayload;
/// Bounded logical code used by acquisition provenance fields.
pub use ksp_store_api::RawProvenanceCode;
/// Logical availability state of one canonical RAW payload.
pub use ksp_store_api::RawRetentionState;
/// Outcome of one atomic RAW retention transition.
pub use ksp_store_api::RawRetentionWriteOutcome;
/// Optional inclusive Solana slot bounds for one Store query.
pub use ksp_store_api::RawSlotRange;
/// Deterministic traversal direction for Store list queries.
pub use ksp_store_api::RawSortDirection;
/// Bounded UTC timestamp represented as whole milliseconds since Unix epoch.
pub use ksp_store_api::RawTimestamp;
/// Canonical source-independent N1 RAW transaction persisted by Store backends.
pub use ksp_store_api::RawTransaction;
/// Explicit write mode for canonical RAW transaction acquisitions.
pub use ksp_store_api::RawTransactionAcquisitionMode;
/// Backend-independent random-access inspection query for RAW transactions.
pub use ksp_store_api::RawTransactionInspectionQuery;
/// Read capability for payload-free random-access RAW transaction inspection.
pub use ksp_store_api::RawTransactionInspectionRead;
/// Persistable acquisition observation linked to one canonical RAW transaction.
pub use ksp_store_api::RawTransactionObservation;
/// Read capability for persisted RAW transaction observations.
pub use ksp_store_api::RawTransactionObservationRead;
/// Write capability for additional observations of already persisted RAW transactions.
pub use ksp_store_api::RawTransactionObservationWrite;
/// Backend-independent list query for canonical RAW transactions.
pub use ksp_store_api::RawTransactionQuery;
/// Read capability for canonical RAW transactions.
pub use ksp_store_api::RawTransactionRead;
/// Durable backend-independent identity of one canonical RAW transaction.
pub use ksp_store_api::RawTransactionReference;
/// Read capability for canonical RAW transaction retention metadata.
pub use ksp_store_api::RawTransactionRetentionRead;
/// Requested compare-and-transition operation for one RAW transaction retention state.
pub use ksp_store_api::RawTransactionRetentionTransition;
/// Write capability for policy-authorized RAW transaction retention transitions.
pub use ksp_store_api::RawTransactionRetentionWrite;
/// Canonical 64-byte Solana transaction signature used by Store identities.
pub use ksp_store_api::RawTransactionSignature;
/// Payload-free summary of one canonical RAW transaction for operator inspection.
pub use ksp_store_api::RawTransactionSummary;
/// Minimal durable identity retained after a canonical RAW transaction payload is purged.
pub use ksp_store_api::RawTransactionTombstone;
/// Write capability for canonical RAW transaction acquisitions.
pub use ksp_store_api::RawTransactionWrite;
/// Common KSP result alias using [`Error`].
pub use ksp_store_api::Result;
/// Boxed async operation returned by object-safe Store capability contracts.
pub use ksp_store_api::StoreApiFuture;

/// Crate-owned tracing target reserved for Store runtime behavior.
pub(crate) use self::constants::TRACING_TARGET;

// Keep the mandatory crate-owned tracing target part of the compiled scaffold
// without inventing runtime logging before the first behavioral log site.
const _: &str = crate::TRACING_TARGET;