v0.3.3-pre.004

crates/ksp-store-postgres-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-store-postgres-lib/USAGE.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Utilisation de ksp-store-postgres-lib
 
@@ -115,7 +115,7 @@ checksum SHA-256
 
 Le runner est transactionnel et sérialisé par advisory transaction lock. Une divergence de checksum/nom/version ou une history plus récente est terminale ; aucun down migration automatique n'est exécuté.
 
-`auto_migrate = false` permet de vérifier l'état sans appliquer de migration pending.
+`schema_autocreate` contrôle l'initialisation/adoption du schéma et `schema_autoupdate` les migrations pending ainsi que les réparations additives sûres. Le constructeur legacy `auto_migrate` mappe encore les deux politiques pour compatibilité source.
 
 ## 6. Classifier les erreurs sans fuite
 
@@ -123,13 +123,16 @@ Le runner est transactionnel et sérialisé par advisory transaction lock. Une d
 match error.kind() {
     ksp_store_postgres_lib::PostgresBackendErrorKind::ConfigInvalid => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::ConnectFailed => {}
+    ksp_store_postgres_lib::PostgresBackendErrorKind::DataInvalid => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::PoolTimeout => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::HealthFailed => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::MigrationFailed => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::MigrationMismatch => {}
+    ksp_store_postgres_lib::PostgresBackendErrorKind::ReadFailed => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::SchemaNewer => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::ShutdownTimeout => {}
     ksp_store_postgres_lib::PostgresBackendErrorKind::TlsFailed => {}
+    ksp_store_postgres_lib::PostgresBackendErrorKind::WrongNetwork => {}
     _ => {}
 }
 
@@ -138,18 +141,40 @@ let _safe_phase = error.phase();
 
 Ne pas reconstruire un diagnostic utilisateur à partir de l'erreur brute PostgreSQL : cette erreur n'est volontairement pas conservée par le bridge.
 
-## 7. Ce que cette crate ne permet pas encore
+## 7. Lectures RAW transaction
 
-La fondation physique n'implémente pas les traits `RawTransaction*` ou `RawAccount*` de `ksp-store-api`.
+Depuis `0.3.3-pre.004`, un backend ouvert expose quatre lectures backend-specific retournant exclusivement les modèles communs :
 
-Un backend ouvert et healthy prouve uniquement :
-
-```text
-connexion/pool
-TLS selon policy
-bootstrap/history
-health/readiness
-close borné
+```rust
+let transaction = backend.get_raw_transaction(&reference).await;
+let observation = backend.get_raw_transaction_observation(&observation_key).await;
+let retention = backend.get_raw_transaction_retention_state(&reference).await;
+let tombstone = backend.get_raw_transaction_tombstone(&reference).await;
 ```
 
-Il ne prouve aucune persistence métier RAW.
+Le backend ne rend jamais `tokio_postgres::Row`, SQL, SQLSTATE ou valeur de bind. Pour les références réseau-scopées, un mauvais réseau est rejeté avant acquisition d'un client du pool. Une corruption de row est projetée vers `DataInvalid`, un échec physique de lecture vers `ReadFailed`, et les erreurs de pool conservent leur classification bornée existante.
+
+`get_raw_transaction` retourne :
+
+```text
+Full      -> payload chaud
+Archived  -> payload archive reconstruit
+Purged    -> None
+absent    -> None
+```
+
+Le tombstone `Purged` reste lisible séparément.
+
+## 8. Ce que cette crate ne permet pas encore
+
+La tranche ne fournit pas encore :
+
+```text
+list_raw_transactions / cursor
+écritures canonique + observation
+transitions de rétention
+implémentations complètes des six traits RawTransaction*
+capabilities RawAccount*
+```
+
+Ces surfaces sont ajoutées dans les prereleases suivantes avant le dispatch `ksp-store-lib`.