0.5.1-pre.002

ks-store/README.md

@@ -0,0 +1,52 @@
+<!-- file: ks-store/README.md -->
+<!-- version: 4 -->
+
+# ks-store
+
+`ks-store` consolide les contrats de stockage et l’implémentation PostgreSQL de `khadhroony-bot3`.
+
+## 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.
+
+## 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 ;
+- protéger les opérations multi-tables par transactions ;
+- borner toutes les requêtes de diagnostic et de replay exposées.
+
+## 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.
+
+## 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.
+
+## Documents
+
+- [Utilisation](USAGE.md)
+- [Travaux restants](TODO.md)
+- [Historique](CHANGELOG.md)
+- [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md)