# 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 : ```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 RawTransaction `Store` implémente les six capabilities transactionnelles acquises dans `ksp-store-api` : ```text RawTransactionRead RawTransactionWrite RawTransactionObservationRead RawTransactionObservationWrite RawTransactionRetentionRead RawTransactionRetentionWrite ``` Le consumer manipule uniquement les modèles et outcomes backend-neutral. Les erreurs physiques PostgreSQL sont projetées vers des codes Store stables sans exposer le backend. La façade fournit ainsi : - lecture d'une transaction canonique, de ses observations et de sa rétention ; - écriture atomique transaction + observation ; - ajout idempotent d'observations ; - pagination keyset déterministe par cursor opaque ; - application de transitions de rétention demandées par le caller ; - validation réseau avant dispatch lorsqu'un input porte explicitement son réseau. ## Hors périmètre 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. ## 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`.