khadhroony-solana-project/crates/ksp-store-lib/README.md

ksp-store-lib

ksp-store-lib est la façade runtime Store commune de KSP.

Elle expose aux consumers une surface backend-neutral, réexporte les contrats RAW de ksp-store-api, sélectionne uniquement les backends compilés et masque leurs objets physiques. Le backend PostgreSQL officiel est activé par défaut via la feature postgres et reste implémenté dans ksp-store-postgres-lib.

Responsabilités

ksp-store-lib possède :

• StoreSettings, avec un réseau logique unique, un backend sélectionné et un timeout de fermeture borné ;
• les settings PostgreSQL publics KSP-owned : pool, TLS, bootstrap/migrations et URI sensible ;
• la feature postgres par défaut et le comportement explicite backend_not_compiled lorsque PostgreSQL est sélectionné sans cette feature ;
• Store::open, qui ne retourne une instance qu'après validation, ouverture physique du backend compilé et bootstrap/history réussis ;
• Store::runtime_snapshot() pour les compteurs runtime sûrs sans I/O ;
• Store::health().await pour la readiness portable et bornée ;
• Store::close(self).await pour la fermeture explicite bornée ;
• le mapping des erreurs backend vers des codes Store stables sans exposer les erreurs physiques ;
• les six capabilities RawTransaction* dispatchées vers le backend compilé ;
• une validation réseau backend-neutral avant dispatch pour toutes les opérations qui portent explicitement un réseau ;
• les réexports crate-root de ksp-store-api nécessaires aux consumers ordinaires.

Une instance = un réseau

Une instance Store représente exactement :

1 Store = 1 RawNetworkId + 1 backend physique sélectionné

Le runtime Store n'est pas un multiplexeur multi-database ou multi-réseau. La sélection d'un target nommé appartient à Config. Le document std.store peut donc définir plusieurs targets indépendants — par exemple Devnet, Mainnet et Testnet — mais un appel à Store::open reçoit les settings d'un seul target.

Cette séparation permet d'utiliser des bases PostgreSQL distinctes par réseau tout en conservant le réseau dans l'identité logique des données RAW.

PostgreSQL

Avec la feature par défaut :

ksp-store-lib
    -> ksp-store-api
    -> ksp-logging-lib
    -> ksp-store-postgres-lib

ksp-store-lib ne réexporte aucun type tokio-postgres, Deadpool ou Rustls.

Les modes TLS publics sont volontairement limités à :

Disabled
VerifyFull

VerifyFull impose TLS avec vérification de la chaîne et de l'identité serveur. La policy typée Store prime sur les paramètres TLS présents dans l'URI.

Config et secrets

Store ne lit ni .env, ni variables KSP_* / KSPB_*, ni variables/fichiers implicites libpq (PG*, .pgpass, fichiers TLS PostgreSQL).

ksp-config-lib possède std.store, la résolution des secrets et la sélection du target. Il construit ensuite un StoreSettings backend-neutral. L'URI PostgreSQL reste nécessaire au runtime mais n'a aucun getter public dans ksp-store-lib et son Debug est redacted.

Les targets committed sont actuellement :

devnet   -> network devnet       -> base indépendante
mainnet  -> network mainnet-beta -> base indépendante
testnet  -> network testnet      -> base indépendante

Les credentials restent dans les variables KSP_SECRET_STORE_*_POSTGRES_URI ou le .env possédé par Config.

Surface actuelle et hors périmètre

Depuis 0.3.3-pre.008, Store implémente les six capabilities transactionnelles acquises dans ksp-store-api :

RawTransactionRead
RawTransactionWrite
RawTransactionObservationRead
RawTransactionObservationWrite
RawTransactionRetentionRead
RawTransactionRetentionWrite

Le consumer continue à manipuler uniquement les modèles et outcomes backend-neutral. Les erreurs physiques PostgreSQL sont projetées vers des codes Store stables tels que store.wrong_network, store.raw_reference_not_found, store.postgres_read_failed, store.postgres_write_failed, store.postgres_data_invalid et store.postgres_page_limit_unsupported.

Sont volontairement hors de cette surface :

• persistence/query/rétention PostgreSQL de RawAccountState ;
• batch-size, priorité, backlog ou policy de worker/job ;
• transport d'acquisition, Program decoding et materialization ;
• exposition publique de SQL, pool, client, row, statement ou transaction PostgreSQL.

La vertical slice RawTransaction est désormais dispatchée ; RawAccountState reste la tranche suivante de 0.3.4 afin que la façade conserve une progression explicite par capability.

Documentation

• USAGE.md — construction des settings, ouverture, health et fermeture ;
• ../ksp-store-postgres-lib/README.md — responsabilité du backend PostgreSQL physique ;
• ../../config/std.store.json — targets Store committed ;
• ../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md — architecture durable Store ;
• ../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md — plan de fondation ;
• ../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md — matrice de validation.