v0.2.7-pre.009

crates/ksp-onchain-transport-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
-<!-- version: 14 -->
+<!-- version: 15 -->
 
 # Utilisation de `ksp-onchain-transport-lib`
 
@@ -92,12 +92,40 @@ let snapshot = session.snapshot();
 
 Deux appels `WsSession::connect` avec le même endpoint créent volontairement deux connexions physiques distinctes. Il n'existe encore aucun pool de sessions automatique.
 
-Le socket brut et la primitive JSON-RPC générique ne sont pas publics. À partir de `pre.006`, le moteur générique de subscription typed existe dans la crate mais sa création reste `pub(crate)` jusqu'aux wrappers standard publics des tranches `pre.009+` ; il ne constitue donc toujours pas une escape hatch provider-specific.
+Le socket brut et la primitive JSON-RPC générique ne sont pas publics. Le moteur générique de subscription typed existe depuis `pre.006` mais sa création reste `pub(crate)` même après l'ouverture des premiers wrappers standards en `pre.009`; il ne constitue donc pas une escape hatch provider-specific.
 
-`WsSubscription<T>` est déjà le handle public commun que ces wrappers retourneront. Il porte un `WsSubscriptionId` local stable, jamais le remote ID numérique du serveur. Les notifications arrivent via un receiver typed borné et `unsubscribe().await` exécute le `*Unsubscribe` correspondant en préservant son résultat booléen.
+`WsSubscription<T>` est le handle public commun retourné par les wrappers standards. Il porte un `WsSubscriptionId` local stable, jamais le remote ID numérique du serveur. Les notifications arrivent via un receiver typed borné et `unsubscribe().await` exécute le `*Unsubscribe` correspondant en préservant son résultat booléen.
 
 Le snapshot de session expose les subscriptions actuellement enregistrées via `WsSubscriptionSnapshot`, avec `remote_bound: bool` seulement. Le remote ID réel n'est jamais projeté.
 
+### Premiers wrappers standards publics
+
+Depuis `0.2.7-pre.009`, trois familles stables peuvent être créées directement sur la session :
+
+```rust
+let account = match "11111111111111111111111111111111".parse::<ksp_core_lib::Pubkey>() {
+    Ok(value) => value,
+    Err(error) => return Err(error.into()),
+};
+let account_config = ksp_onchain_transport_lib::SolanaAccountSubscribeConfig::new(
+    Some(ksp_onchain_transport_lib::SolanaAccountEncoding::Base64),
+    None,
+    Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed),
+);
+let mut account_subscription = match session.account_subscribe(&account, Some(&account_config)).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let next = account_subscription.recv().await;
+let removed = account_subscription.unsubscribe().await;
+```
+
+La même session expose `program_subscribe()` avec `SolanaProgramSubscribeConfig` et `logs_subscribe()` avec `SolanaLogsSubscribeFilter` plus `SolanaCommitmentConfig`. Pour `logsSubscribe`, `Mentions(pubkey)` représente exactement une adresse, conformément à la contrainte upstream retenue par l'audit.
+
+`accountSubscribe` ne propose pas `minContextSlot`: le champ existe dans un config partagé upstream mais est ignoré par le handler PubSub audité. `programSubscribe` conserve en revanche `withContext`; `SolanaProgramNotification` permet au consumer de traiter explicitement une notification contextée ou non contextée.
+
+Les trois wrappers retournent le même handle `WsSubscription<T>` : reconnect, resubscribe, overflow, cause terminale et unsubscribe restent donc uniformes. Aucun wrapper public n'accepte un nom de méthode JSON-RPC arbitraire ni un remote subscription ID.
+
 ### Reconnect automatique borné
 
 Depuis `0.2.7-pre.007`, les settings de session contrôlent réellement le reconnect physique. Une perte de socket publie `Reconnecting { attempt }`, invalide les remote IDs et incrémente `continuity_gap_count`. Avec la policy par défaut `ActiveSubscriptions`, les handles logiques gardent leur `WsSubscriptionId` et passent temporairement en `Resubscribing`; l'actor recrée leurs subscriptions dans l'ordre local avant de republier `Active`.
@@ -122,7 +150,7 @@ Le consumer doit traiter `overflow_count` et `continuity_gap_count` comme deux s
 
 ```rust
 let session = ksp_onchain_transport_lib::WsSession::connect(endpoint).await?;
-// ... utilisation future des subscriptions typed ...
+// ... account_subscribe/program_subscribe/logs_subscribe puis recv()/unsubscribe() ...
 session.close().await?;
 ```