v0.4.8-pre.013

kb-pipeline/USAGE.md

@@ -1,8 +1,14 @@
 <!-- file: kb-pipeline/USAGE.md -->
-<!-- version: 10 -->
+<!-- version: 16 -->
 
 # Utilisation de kb-pipeline
 
+## Lecture stateful des Edition Markers Metaplex
+
+Les lectures stateful `Edition` acceptent les allocations Metaplex courantes après validation par `kb-lib`. Un `Print` récent produit notamment une allocation compacte de 42 octets alors que la structure Borsh `Edition` sérialise 41 octets ; le pipeline ne recalcule pas cette règle et consomme uniquement le snapshot déjà validé par le décodeur. Les erreurs de décodage stateful conservent l’adresse et le `kind` demandés pour localiser la postcondition fautive.
+
+Les campagnes d’éditions imprimées peuvent demander un snapshot borné `EditionMarker` en fournissant le mint maître et le numéro d’édition. Le pipeline dérive et vérifie le contrat du compte via le décodeur Metaplex existant, puis expose notamment `marker_group`, `edition`, `byte_index`, `bit_mask`, `edition_taken` et le ledger. Cette lecture sert à prouver qu’un numéro d’édition a été consommé ; elle ne suppose pas que le marker est fermé lors d’un burn. La validation de requête contrôle aussi les pubkeys utilisées pour les dérivations `Edition`, `EditionMarker` et `TokenRecord` avant tout accès RPC.
+
 ## Objectif
 
 La crate expose les campagnes bornées d’acquisition, d’extraction, de replay et les inspections stateful nécessaires aux applications et scénarios.
@@ -261,7 +267,9 @@ async fn read_metaplex_metadata(
 }
 ```
 
-Pour une edition, fournir le mint dans `MetaplexTokenMetadataAccountKind::Edition`. Pour un token record programmable, fournir le mint et le token account dans `TokenRecord`.
+Pour une edition, fournir le mint dans `MetaplexTokenMetadataAccountKind::Edition`. Pour un token record programmable, fournir le mint et le token account dans `TokenRecord`. Pour un Token Owned Escrow, utiliser `TokenOwnedEscrow` : le décodeur récupère le mint parent et l’autorité depuis le compte, puis valide lui-même le PDA et le bump avant projection stateful.
+
+`MAX_METAPLEX_TOKEN_METADATA_ACCOUNT_BYTES` représente la borne d'une lecture RPC complète et suit `kb_onchain_transport::MAX_COMPLETE_ACCOUNT_DATA_BYTES`, soit actuellement `65536` octets. Cette borne stateful ne doit pas être confondue avec les bornes propres aux décodeurs pour des octets déjà disponibles offline ou avec un futur lecteur par tranches.
 
 ## Inspecter le préflight Metaplex
 
@@ -326,6 +334,8 @@ fn validate_metaplex_execution(
 
 Pour une soumission réelle, `submit` et `operator_confirmed` doivent être vrais et le plan ne doit plus être en `dry_run`.
 
+Une requête `submit=false` peut conserver une simulation exacte ayant échoué afin qu’un appelant classe explicitement une indisponibilité runtime. Dans ce cas, le rapport reste non soumettable et contient le marqueur `failed_simulation_retained_for_probe_only`. Avec `submit=true`, une simulation échouée reste une erreur de readiness et `send_authorized` ne peut jamais devenir vrai.
+
 ## Agréger les postconditions Metaplex
 
 ```rust