v0.5.3-pre.002

ks-store/README.md

@@ -1,48 +1,56 @@
 <!-- file: ks-store/README.md -->
-<!-- version: 4 -->
+<!-- version: 6 -->
 
 # ks-store
 
-`ks-store` consolide les contrats de stockage et l’implémentation PostgreSQL de `khadhroony-bot3`.
+`ks-store` porte la frontière de persistance généraliste de Khadhroony Solana. Les consommateurs utilisent des contrats fonctionnels et une façade `Store` indépendante du moteur concret ; PostgreSQL reste l'implémentation opérationnelle de `0.5.3`, confinée à l'intérieur de la crate.
 
 ## Périmètre
 
 La crate expose :
 
-- DTO et entités raw, observations, Core, décodage, matérialisation et ledger ;
-- traits async de repositories indépendants du backend ;
-- pagination et filtres bornés ;
-- `PostgresStore` et ses options de connexion ;
-- initialisation idempotente du schéma et migrations SQL ;
-- diagnostics read-only, healthchecks et résumés de replay ;
-- transactions atomiques pour extraction, décodage et matérialisation.
+- `Store` et `StoreOpenOptions` comme façade d'ouverture et handle persistant backend-agnostique ;
+- les DTO et entités raw, observations, Core, décodage, matérialisation et ledger ;
+- les traits async `StoreHealthStore`, `RawTransactionStore`, `CoreTransactionStore`, `CoreExtractionStore` et `DecodePipelineStore` ;
+- les filtres et résultats de replay sans préfixe backend ;
+- des diagnostics et résumés runtime/init sanitisés ne révélant ni secret ni nom physique d'objet ;
+- des transactions atomiques pour extraction, décodage et matérialisation.
+
+## Frontière backend
+
+`PostgresStore`, `PostgresStoreOptions`, `sqlx::PgPool`, les requêtes SQL et les noms physiques de tables sont privés à `ks-store`. `ks-pipeline`, les scénarios et les applications ne doivent connaître que `Store`, les repositories et les DTO fonctionnels.
+
+`ks-store` ne dépend pas de `ks-config`. Un consommateur lui fournit un backend sélectionné et un objet `backend_options` opaque ; seul `ks-store` interprète et valide les paramètres PostgreSQL puis crée la connexion.
+
+## Configuration et sécurité
+
+`StoreOpenOptions` ne dérive pas `Debug` et ne rend pas les options backend accessibles après construction. Les résumés publics exposent uniquement des informations explicitement sanitisées : code backend, présence d'une connexion, état d'initialisation, health, modèle logique et compteurs.
+
+Le backend PostgreSQL masque le descripteur de connexion et utilise l’unique target de crate `ks-store`, complété par `backend="postgres"`, `domain="ks-store.pg"` et un champ `action` structuré. Aucun DSN, password ou valeur bindée n'est destiné aux diagnostics publics.
+
+## Schéma pendant `0.5.3`
+
+`0.5.3-pre.002` ne modifie pas encore les tables héritées `kb_sol_*`. Leur reconstruction sous `k_sol_*`, les ressources SQL atomiques et le gel N1/N2/N3 commencent en `pre.003` conformément au plan actif.
 
 ## Responsabilités
 
 - garantir les invariants des données persistées ;
-- séparer contrats et implémentation PostgreSQL à l’intérieur de la crate consolidée ;
-- maintenir les tables canoniques `kb_sol_*` ;
-- fournir au pipeline des frontières async typées ;
+- posséder la connexion et l'initialisation du backend actif ;
+- fournir des frontières async typées au pipeline ;
 - protéger les opérations multi-tables par transactions ;
-- borner toutes les requêtes de diagnostic et de replay exposées.
+- borner les diagnostics et replay exposés ;
+- permettre le remplacement futur de PostgreSQL sans réécriture des consommateurs.
 
 ## Hors périmètre
 
-La crate ne décode pas les instructions, n’acquiert pas les transactions et ne décide pas quelle matérialisation exécuter. Elle persiste les résultats produits par `ks-lib` et orchestrés par `ks-pipeline`.
-
-## API publique
-
-Les consommateurs utilisent principalement `PostgresStore`, `PostgresStoreOptions`, les traits `*Store`, les DTO `*Insert`/`*Row`, les filtres de replay et les diagnostics. Les constantes de tables et fonctions de validation sont publiques pour les audits et outils d’administration.
+La crate ne décode pas les instructions, n'acquiert pas les transactions et ne décide pas quelle matérialisation ou projection N4 exécuter. Elle persiste les faits produits par `ks-lib` et orchestrés par `ks-pipeline`.
 
 ## Relations
 
 - dépend de `ks-core` pour les erreurs ;
 - utilise les contrats de replay de `ks-lib` ;
-- est consommée principalement par `ks-pipeline`, les scénarios de démonstration et le desktop.
-
-## Statut
-
-Le stockage consolidé dispose de tests unitaires étendus et de tests PostgreSQL optionnels pilotés par environnement. Les opérations réelles exigent un serveur PostgreSQL et l’application préalable des migrations.
+- est consommée principalement par `ks-pipeline`, `ks-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
+- ne dépend pas de `ks-config`.
 
 ## Documents
 
@@ -50,3 +58,4 @@ Le stockage consolidé dispose de tests unitaires étendus et de tests PostgreSQ
 - [Travaux restants](TODO.md)
 - [Historique](CHANGELOG.md)
 - [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md)
+- [Plan actif `0.5.3`](../docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md)