v0.4.7-pre.011

kb-lib/README.md

@@ -1,70 +1,64 @@
 <!-- file: kb-lib/README.md -->
-<!-- version: 17 -->
+<!-- version: 19 -->
 
 # kb-lib
 
-`kb-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle expose les modèles partagés, les contrats et implémentations de décodage, de matérialisation, d’exécution et de sécurité nécessaires au pipeline Solana.
-
-- Metaplex Token Metadata expose les wrappers canoniques courants et conserve les opérations obsolètes encore constructibles sous une API Rust `#[deprecated]` avec approbation opérateur explicite ; les versions remplacées ne reçoivent qu’un renvoi vers leur remplacement canonique final.
+`kb-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle fournit les modèles, décodeurs, matérialisateurs, exécuteurs et contrats de sécurité indépendants du transport, du stockage et de l’interface utilisateur.
 
 ## Périmètre
 
-La crate regroupe quatre familles internes, exposées par la façade `kb_lib` :
+La crate couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et Metaplex Token Metadata.
 
-- décodeurs et contrats de décodage contextualisé ;
-- exécuteurs, plans préparés et politiques de sécurité ;
-- matérialisateurs et projections structurées ;
-- modèles canoniques utilisés par les autres crates.
+Pour Metaplex Token Metadata, elle fournit :
 
-Elle couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et le décodeur Metaplex Token Metadata. De nombreux décodeurs et exécuteurs réservés exposent seulement une identité et une compatibilité conservatrice ; ils ne constituent pas une implémentation fonctionnelle.
+- le décodage des 58 discriminants et des principales familles de comptes ;
+- la propriété unique des faits metadata, admin, lifecycle et risk/compliance ;
+- 20 opérations courantes exécutables ;
+- 15 opérations obsolètes encore constructibles, exposées comme dépréciées et soumises à une approbation explicite ;
+- 22 versions remplacées conservées en décodage uniquement et redirigées vers leur remplacement canonique final ;
+- une frontière explicite avec Bubblegum et avec les metadata incorporées de Token-2022.
 
 ## Responsabilités
 
-- reconnaître et décoder une instruction à partir d’un contexte canonique ;
-- publier des déclarations de couverture déterministes ;
+- reconnaître et décoder des instructions contextualisées ;
+- décoder les comptes on-chain pris en charge ;
 - produire des observations et diagnostics typés ;
-- construire des plans d’exécution bornés et vérifiables ;
-- appliquer les politiques de sécurité avant simulation, signature ou envoi ;
-- matérialiser les observations commitées selon des contrats explicites ;
-- conserver des modèles indépendants du stockage, du transport et de l’interface desktop.
+- matérialiser les faits stables et prouvés ;
+- construire des plans d’exécution bornés ;
+- déclarer les comptes, signers, coûts et confirmations nécessaires ;
+- appliquer les garde-fous fail-closed avant simulation, signature ou envoi ;
+- exposer des modèles indépendants du RPC, de PostgreSQL et de Tauri.
 
 ## Hors périmètre
 
-`kb-lib` ne persiste aucune donnée, ne dialogue pas directement avec un RPC, ne sélectionne pas un endpoint et ne gère pas les secrets de wallet. Ces responsabilités appartiennent respectivement à `kb-store`, `kb-onchain-transport`, `kb-pipeline` et `kb-wallet`.
+`kb-lib` ne sélectionne aucun endpoint, ne lit pas directement un RPC, ne persiste aucune donnée, ne gère pas les secrets de wallet et ne soumet aucune transaction.
 
 ## Surface publique principale
 
-La façade publique est organisée autour de :
+- contrats `DcApi*` et décodeurs concrets `Dc*Decoder` ;
+- parseurs de comptes et d’états bornés ;
+- contrats `MtApi*` et matérialisateurs concrets ;
+- contrats `ExApi*`, politiques de sécurité et exécuteurs `Ex*Executor` ;
+- `ExMetadataMetaplexTokenMetadataExecutor`, `ExMetaplexTokenMetadataExecutionIntent` et `ExMetaplexTokenMetadataOperation` ;
+- modèles canoniques `Md*` réexportés par la façade.
 
-- `DcApiInstructionDecoder`, `DcApiProtocolDecoder` et les types `DcApi*` ;
-- les décodeurs concrets `DcSolanaCoreDecoder`, `DcSplMemoDecoder`, `DcSplTokenDecoder`, `DcSplAssociatedTokenAccountDecoder`, `DcSplToken2022Decoder`, `DcSplElgamalRegistryDecoder` et `DcMetadataMetaplexTokenMetadataDecoder` ;
-- `ExApiTypedInstructionExecutor`, `ExApiInstructionExecutor`, les politiques `ExApi*` et les exécuteurs concrets `Ex*Executor` ;
-- `ExSafetyChecker` et les décisions de sécurité associées ;
-- `MtApiEventMaterializer`, les types `MtApi*` et les matérialisateurs concrets ;
-- `MdCoreInstructionReplayInput` et les modèles canoniques réexportés.
+Les exemples d’appel et invariants sont documentés dans [USAGE.md](USAGE.md).
 
-Le catalogue détaillé et les exemples se trouvent dans [USAGE.md](USAGE.md).
+## Relations avec le workspace
 
-## Matrices contractuelles
-
-Les matrices actives sont maintenues sous [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Elles servent à la fois de références documentaires et de fixtures exécutées par des tests. Elles ne sont pas dupliquées dans la documentation de la crate.
-
-## Relations
-
-- dépend de `kb-core` pour le contrat d’erreur commun ;
-- dépend de `kb-program-ids` pour le registre canonique des programmes ;
+- dépend de `kb-core` et `kb-program-ids` ;
 - est consommée par `kb-pipeline`, `kb-store`, `kb-onchain-transport`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
-- ne dépend jamais de `kb-store` ni d’une application.
+- ne dépend jamais de `kb-store`, `kb-pipeline` ni d’une application.
 
 ## Statut et limites
 
-La migration des surfaces historiques jusqu’à un périmètre proche de bot2 `0.4.6` est largement réalisée. Le décodeur Metaplex Token Metadata couvre les 58 discriminants et les matérialisations possèdent désormais un contrat fermé de propriété des faits. L’exécuteur Metaplex ferme désormais les 35 opérations officiellement constructibles : 20 opérations courantes et 15 opérations obsolètes conservées sous `#[deprecated]` avec approbation opérateur explicite. Les 22 versions remplacées restent decode-only et Bubblegum demeure une frontière externe. La fermeture inclut les éditions, uses, escrow, mint, print, collect, migrate et resize. Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
+La surface fonctionnelle Metaplex de la crate est achevée. Les campagnes Devnet restantes relèvent de `kb-pipeline-demo-scenarios` et de `kb-app-demo-desktop`, non d’un manque de builder dans `kb-lib`.
 
-## Documents
+Le registre ElGamal n’est pas déclaré validé réellement sur réseau.
 
-- [Utilisation](USAGE.md)
-- [Travaux restants](TODO.md)
-- [Historique de la crate](CHANGELOG.md)
-- [Architecture générale](../docs/architecture/ARCHITECTURE.md)
-- [Pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
-- [Matrice des surfaces](../docs/architecture/SURFACE_CRATE_MATRIX.md)
+## Documentation
+
+- [Guide d’utilisation](USAGE.md)
+- [Travaux restant à réaliser](TODO.md)
+- [Historique des changements](CHANGELOG.md)
+- [Matrice contractuelle Metaplex](../test-fixtures/contract-matrices/METAPLEX_TOKEN_METADATA_MATRIX.json)