v0.5.3-pre.002

docs/guides/POSTGRES_STORAGE.md

@@ -1,32 +1,37 @@
 <!-- file: docs/guides/POSTGRES_STORAGE.md -->
-<!-- version: 3 -->
+<!-- version: 5 -->
 
 # Guide PostgreSQL et contrats de stockage
 
 ## Objectif
 
-`ks-store` consolide les contrats de stockage Core, raw, decode et PostgreSQL de bot2 dans une crate unique.
+`ks-store` porte la frontière de stockage généraliste. PostgreSQL reste le backend opérationnel actif, mais il est encapsulé derrière la façade publique backend-agnostique `Store`.
 
 ## Connexion
 
+Les consommateurs ne construisent plus `PostgresStore`, `PostgresStoreOptions` ni un pool SQLx. Ils transmettent le backend sélectionné et ses options résolues à `StoreOpenOptions`; `ks-store` valide et interprète ensuite les paramètres PostgreSQL.
+
 ```rust
-let options = match ks_store::PostgresStoreOptions::new(
-    database_url,
-    10,
-    10_000,
+let options = match ks_store::StoreOpenOptions::new(
     true,
+    "postgres",
+    serde_json::json!({
+        "url": database_url,
+        "max_connections": 10,
+        "connect_timeout_ms": 10_000,
+        "auto_initialize_schema": true
+    }),
 ) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
-
-let store = match ks_store::PostgresStore::connect(options).await {
+let store = match ks_store::Store::open(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.
+Le descripteur public éventuellement affiché provient du résumé runtime et est déjà masqué par `ks-store`. Le DSN brut et les options backend ne doivent jamais être propagés dans les DTO, erreurs applicatives ou logs normaux.
 
 ## Domaines
 
@@ -37,7 +42,9 @@ Toujours utiliser `masked_dsn()` dans les diagnostics.
 
 ## Migrations
 
-Les migrations sont idempotentes et ordonnées. Une nouvelle migration ne doit pas modifier rétroactivement une migration déjà publiée.
+`0.5.3-pre.002` conserve temporairement le schéma PostgreSQL historique `kb_sol_*` et son mécanisme d'initialisation afin de réaliser d'abord la rupture d'API backend. `pre.003` reconstruit le baseline sous `k_sol_*`, range les ressources sous `ks-store/migrations/postgres/` et impose une instruction SQL par fichier exécutée par les fonctions privées du backend.
+
+Les bases Devnet/Mainnet/test `0.5.2` sont reconstructibles : aucune compatibilité in-place n'est requise pour ce changement de baseline.
 
 ## Compatibilité des identités de processeurs
 
@@ -47,15 +54,20 @@ Aucune migration SQL automatique de ces valeurs n'est ajoutée en `0.5.1` : avan
 
 ## 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.
+Les traits publics et la façade `Store` décrivent des opérations fonctionnelles indépendantes du moteur. PostgreSQL implémente ces contrats à l’intérieur de `ks-store`; aucune crate consommatrice ne reçoit `PgPool`, un type SQLx ou une requête concrète. Les opérations de lecture utilisent des filtres et paginations bornés.
 
 ## Diagnostics
 
+La surface publique expose :
+
 - health snapshot ;
 - migration snapshot ;
-- backend diagnostics ;
-- diagnostics des tables raw, Core et decode ;
-- validation des noms de tables.
+- backend descriptor masqué ;
+- résumé de configuration sanitisé ;
+- résumé d'initialisation/vérification par modèle logique ;
+- diagnostics de ressources raw/Core/decode/materialization sans nom physique d'objet.
+
+Les noms de tables, index, contraintes et le SQL restent des détails backend-internes. Les traces PostgreSQL utilisent l’unique `target: crate::TRACING_TARGET` (`ks-store`) avec les champs structurés `backend="postgres"`, `domain="ks-store.pg"` et un `action` précis (`connection`, `migration`, `query`, `health`, `replay`, etc.).
 
 ## Invariants
 
@@ -63,7 +75,7 @@ Les traits publics séparent le contrat de l’implémentation PostgreSQL. Les o
 - 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.
+- les détails PostgreSQL utiles au diagnostic restent backend-internes ; les erreurs traversant la façade publique ne doivent jamais divulguer DSN, password ou options sensibles.
 
 ## Références