# 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 dix capabilities RAW de `ksp-store-api` dispatchées vers le backend compilé : six `RawTransaction*` et quatre `RawAccount*` ; - 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 : ```text 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, 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 : ```text 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 à : ```text 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. ## Surface RAW `Store` implémente exactement dix capabilities RAW backend-neutral : ```text RawTransactionRead RawTransactionWrite RawTransactionObservationRead RawTransactionObservationWrite RawTransactionRetentionRead RawTransactionRetentionWrite RawAccountStateRead RawAccountStateWrite RawAccountObservationRead RawAccountObservationWrite ``` Pour `RawTransaction`, la façade fournit la lecture canonique et des observations, l'acquisition atomique transaction+observation, l'ajout idempotent d'observations, la pagination keyset et les transitions de rétention demandées par le caller. Pour `RawAccountState`, elle fournit : - lecture d'un état complet par référence durable `(network, pubkey, slot, state_hash)` ; - pagination keyset des références dans l'ordre total `(slot, pubkey, state_hash)`, avec filtre pubkey optionnel ; - écriture atomique état+observation avec idempotence exacte et conflit sur contenu divergent ; - lecture et ajout d'observations account ; - validation réseau avant dispatch pour les opérations dont l'input porte explicitement un réseau. Les cursors restent opaques et propres à leur famille. Store ne leur attribue aucune sémantique de batch, priorité ou scheduling. ## Hors périmètre Sont volontairement hors de cette surface : - rétention, archivage, purge, delete ou compaction 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. ## Documentation - [`USAGE.md`](USAGE.md) — guide pratique de construction, lifecycle et capabilities Store ; - [`../ksp-store-postgres-lib/README.md`](../ksp-store-postgres-lib/README.md) — responsabilité du backend PostgreSQL physique ; - [`../../config/std.store.json`](../../config/std.store.json) — targets Store committed ; - [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — architecture durable Store ; - [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — plan de fondation ; - [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — validation de fondation ; - [`../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) — plan `RawTransaction` ; - [`../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction` ; - [`../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) — design `RawAccountState` et complétude RAW ; - [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` et conformance 10/10.