v0.1.0-pre.073

docs/guides/POSTGRES_STORAGE.md

@@ -0,0 +1,66 @@
+<!-- file: docs/guides/POSTGRES_STORAGE.md -->
+<!-- version: 1 -->
+
+# Guide PostgreSQL et contrats de stockage
+
+## Objectif
+
+`kb-store` consolide les contrats de stockage Core, raw, decode et PostgreSQL de bot2 dans une crate unique.
+
+## Connexion
+
+```rust
+let options = match kb_store::PostgresStoreOptions::new(
+    database_url,
+    10,
+    10_000,
+    true,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let store = match kb_store::PostgresStore::connect(options).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+Toujours utiliser `masked_dsn()` dans les diagnostics.
+
+## Domaines
+
+- raw : acquisitions et observations ;
+- Core : transactions, instructions, comptes et contexte normalisés ;
+- decode : ledger, observations décodées et matérialisations ;
+- replay : candidats et résumés bornés.
+
+## Migrations
+
+Les migrations sont idempotentes et ordonnées. Une nouvelle migration ne doit pas modifier rétroactivement une migration déjà publiée.
+
+## Repositories
+
+Les traits publics séparent le contrat de l’implémentation PostgreSQL. Les opérations de lecture utilisent des filtres et paginations bornés.
+
+## Diagnostics
+
+- health snapshot ;
+- migration snapshot ;
+- backend diagnostics ;
+- diagnostics des tables raw, Core et decode ;
+- validation des noms de tables.
+
+## Invariants
+
+- aucune donnée canonique ne doit être dupliquée sans justification ;
+- les écritures rejouables doivent être idempotentes ;
+- la progression de campagne doit rester cohérente avec les lignes effectivement traitées ;
+- les requêtes dynamiques n’acceptent que des identifiants validés ;
+- les erreurs PostgreSQL restent distinctes des erreurs de contrat.
+
+## Références
+
+- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
+- `kb-store/USAGE.md` ;
+- `kb-store/README.md`.