v0.1.0-pre.070

kb-store/CHANGELOG.md

@@ -1,8 +1,12 @@
 <!-- file: kb-store/CHANGELOG.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # CHANGELOG — kb-store
 
+## 0.1.0-pre.070
+
+- enrichissement de `USAGE.md` avec plusieurs exemples couvrant les familles d’API publiques significatives.
+
 ## 0.1.0-pre.069
 
 ### Documentation

kb-store/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-store/USAGE.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Utilisation de kb-store
 
@@ -8,23 +8,23 @@
 ```rust
 let options = match kb_store::PostgresStoreOptions::new(
     database_url,
-    "public".to_string(),
     10,
-    std::time::Duration::from_secs(10),
+    10_000,
+    true,
 ) {
     Ok(value) => value,
     Err(error) => return Err(error),
 };
+
+println!("postgres endpoint: {}", options.masked_dsn());
+
 let store = match kb_store::PostgresStore::connect(options).await {
     Ok(value) => value,
     Err(error) => return Err(error),
 };
-if let Err(error) = store.initialize_store_schema().await {
-    return Err(error);
-}
 ```
 
-`PostgresStoreOptions::new` valide le DSN, le schéma, le nombre de connexions et le timeout. Utiliser `masked_dsn` ou `mask_postgres_dsn` dans les logs ; ne jamais journaliser le DSN brut.
+`PostgresStoreOptions::new` valide le DSN, le nombre de connexions et le timeout. Lorsque `auto_initialize_schema` vaut `true`, la connexion applique les schémas idempotents. Utiliser `masked_dsn` ou `mask_postgres_dsn` dans les logs ; ne jamais journaliser le DSN brut.
 
 ## Diagnostics
 
@@ -32,10 +32,44 @@ if let Err(error) = store.initialize_store_schema().await {
 let health = store.health_snapshot().await;
 let migrations = store.migration_snapshot().await;
 let backend = store.backend_diagnostics().await;
+
+println!("health={:?}", health.status);
+println!("migration={:?}", migrations.status);
+println!("backend={:?}", backend.descriptor.backend);
 ```
 
 Les diagnostics de tables raw, Core et decode/materialization sont également disponibles par les méthodes `*_table_diagnostics`.
 
+```rust
+let raw_tables = match store.raw_table_diagnostics().await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+for table in raw_tables {
+    println!(
+        "table={} domain={} exists={}",
+        table.table_name,
+        table.domain,
+        table.exists
+    );
+}
+```
+
+## Pagination bornée
+
+```rust
+let first_page = kb_store::PageRequest::first_page();
+
+let next_page = match kb_store::PageRequest::new(250, 250) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+assert_eq!(first_page.limit, kb_store::DEFAULT_PAGE_SIZE);
+assert!(next_page.limit <= kb_store::MAX_PAGE_SIZE);
+```
+
 ## Contrats de repositories
 
 Les traits publics principaux sont :
@@ -55,9 +89,32 @@ Ils permettent au pipeline de dépendre d’un contrat async plutôt que d’une
 ## Replay et requêtes bornées
 
 ```rust
-let candidates = store.replay_transaction_candidates(filter).await;
-let programs = store.replay_program_summaries(program_filter).await;
-let entities = store.replay_entity_summaries(entity_filter).await;
+let candidates = match store.replay_transaction_candidates(filter).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+for candidate in candidates {
+    println!(
+        "signature={} slot={}",
+        candidate.signature,
+        candidate.slot
+    );
+}
+```
+
+```rust
+let programs = match store.replay_program_summaries(program_filter).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+let entities = match store.replay_entity_summaries(entity_filter).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+println!("programs={}, entities={}", programs.len(), entities.len());
 ```
 
 Les filtres refusent les limites nulles ou supérieures aux bornes publiques. `PageRequest` impose également `DEFAULT_PAGE_SIZE` et `MAX_PAGE_SIZE`.
@@ -66,6 +123,24 @@ Les filtres refusent les limites nulles ou supérieures aux bornes publiques. `P
 
 Les bundles `CoreExtractionBundle`, `DecodePersistenceBundle` et `MaterializationPersistenceBundle` regroupent les écritures qui doivent réussir ou être annulées ensemble. Les consommateurs ne doivent pas reproduire manuellement ces transactions avec des écritures isolées.
 
+## Validation des noms de tables
+
+```rust
+if let Err(error) = kb_store::validate_raw_store_table_names() {
+    return Err(error);
+}
+if let Err(error) = kb_store::validate_core_store_table_names() {
+    return Err(error);
+}
+if let Err(error) = kb_store::validate_decode_store_table_names() {
+    return Err(error);
+}
+
+assert!(kb_store::is_valid_solana_table_name(
+    kb_store::CORE_TRANSACTIONS_TABLE_NAME
+));
+```
+
 ## Schéma et tables
 
 Les constantes `RAW_STORE_TABLE_NAMES`, `CORE_STORE_TABLE_NAMES` et `DECODE_STORE_TABLE_NAMES` exposent les noms canoniques. Les fonctions `validate_*_table_names` et `is_valid_solana_table_name` servent aux audits et outils d’administration.