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 :

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 :

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.

Surface RAW

Store implémente exactement dix capabilities RAW backend-neutral :

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 — guide pratique de construction, lifecycle et capabilities Store ;
../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 — validation de fondation ;
../../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 — validation RawTransaction ;
../../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 — validation RawAccountState et conformance 10/10.