0.1.0

migration/khadhroony-bot2-reference/kb_executor_spl_token/README.md

@@ -0,0 +1,98 @@
+<!-- file: kb_executor_spl_token/README.md -->
+<!-- version: 4 -->
+
+# kb_executor_spl_token
+
+Ce crate construit des plans typés pour le programme SPL Token classique exact :
+
+```text
+TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
+```
+
+Il ne dépend ni du RPC, ni du wallet, ni de Tauri, ni du décodeur. La lecture d’état, la simulation,
+la signature, l’envoi et la validation post-exécution appartiennent à l’orchestration commune.
+
+## Politique de surface
+
+Le décodeur conserve les 28 tags publiés, y compris les formes historiques. L’exécuteur expose 24
+opérations encore courantes ou récentes et refuse quatre initialisations obsolètes dépendantes de
+Rent : `InitializeMint`, `InitializeAccount`, `InitializeMultisig` et `InitializeAccount2`. Leurs
+équivalents actuels utilisent respectivement `InitializeMint2`, `InitializeAccount3` et
+`InitializeMultisig2`.
+
+Les opérations non checked `Transfer`, `Approve`, `MintTo` et `Burn` restent constructibles : leur
+wire est ancien, mais les builders officiels 3.0.0 les publient toujours et elles ne sont pas
+obsolètes. Les variantes checked doivent être préférées lorsqu’un mint et ses decimals sont connus.
+
+## Contrat typé
+
+`SplTokenExecutionIntent` contient :
+
+- un identifiant d’intent et un fee payer ;
+- une `ExecutionPolicy` commune, simulation obligatoire et dry-run par défaut ;
+- une instruction typée ou un `Batch` de sous-instructions non batch ;
+- les comptes métier explicites ;
+- une autorité simple ou un multisig avec signataires ordonnés ;
+- les montants bruts sous forme de chaînes décimales JSON, converties en `u64` seulement dans le
+  builder ;
+- les decimals séparés lorsqu’ils appartiennent réellement au wire.
+
+Les doublons des metas multisig sont conservés dans l’ordre officiel. La liste des signataires
+transactionnels est dédupliquée séparément avec le fee payer.
+
+## Builders
+
+Chaque opération appelle directement le builder `spl-token-interface 3.0.0`. Cela couvre les
+initialisations actuelles, transferts, délégations, changements d’autorité, mint/burn, close,
+freeze/thaw, variantes checked, `SyncNative`, les trois instructions de return data,
+`InitializeImmutableOwner`, `WithdrawExcessLamports`, `UnwrapLamports` et `Batch`.
+
+`InitializeImmutableOwner` est explicitement un no-op de compatibilité sur le programme classique ;
+il n’est jamais présenté comme une extension Token-2022.
+
+`Batch` est borné à 64 enfants, 512 occurrences de comptes et 255 octets de data par enfant. Son
+type enfant exclut structurellement un autre `Batch`. Les slices de comptes et l’ordre produits par
+le builder officiel sont conservés.
+
+## Constructibilité et clusters
+
+La constructibilité de bibliothèque ne dépend pas du cluster. `UnwrapLamports` et `Batch` sont
+publiés avec un builder exact dans l’interface 3.0.0 et sont donc constructibles. Deux simulations
+réussies le 16 juillet 2026 prouvent leur présence sur le programme classique Devnet. Cette preuve
+n'est pas extrapolée à Localnet, Testnet ou Mainnet. Mainnet demeure gouverné par
+`kb_execution_safety` et la confirmation opérateur, pas par une interdiction interne à ce crate.
+
+Les opérations d’initialisation supposent que les comptes ont déjà été créés avec la bonne taille,
+le bon owner et le bon financement. La création System et le rent ne sont pas masqués dans une
+instruction Token ; le préflight stateful de la tranche suivante les vérifiera sans utiliser ATA.
+
+## Coûts et validation
+
+Les montants token ne sont pas des frais réseau et ne sont pas reportés comme lamports dépensés.
+Un montant explicite `UnwrapLamports` est déclaré dans `requested_spend_lamports`; un unwrap total
+et `WithdrawExcessLamports` restent simulation-only tant qu’une lecture d’état n’a pas borné les
+lamports déplaçables. Le plafond de frais reste séparé dans `ExecutionCostLimit`.
+
+Toute construction impose une simulation, un plafond de frais positif, une insertion canonique,
+l’extraction core et le replay décodé. Les mutations exigent aussi la validation de matérialisation ;
+les conversions, requêtes de return data et le no-op de compatibilité n’inventent aucune projection.
+
+## Limites actuelles
+
+- aucun préflight Mint/Account/Multisig dans ce crate : ces lectures sont implémentées dans
+  `kb_pipeline` afin de conserver l'exécuteur pur ;
+- aucun envoi ni simulation RPC dans ce crate ; l'orchestrateur commun a validé ces étapes sur
+  Devnet pour `TransferChecked` et le lifecycle contrôlé ;
+- aucun compte ATA créé implicitement ;
+- aucun support Token-2022 ;
+- aucun déploiement de `UnwrapLamports` ou `Batch` revendiqué hors Devnet sans simulation cluster
+  dédiée.
+
+Le parcours Devnet réel a prouvé simulation, soumission, confirmation, hydratation canonique,
+extraction, replay, matérialisation et idempotence pour les opérations du lifecycle documentées dans
+`docs/SPL_TOKEN_MATRIX.json`. La démo Tauri refuse volontairement un envoi si le wallet du profil ne
+résout pas aussi l'autorité Token requise ; elle ne prend jamais en charge une clé externe implicite.
+
+Le probe Devnet simulation-only du 16 juillet 2026 a validé le wire déployé de `Batch` avec un
+enfant `TransferChecked` de montant nul en 270 compute units, puis `UnwrapLamports` d'un lamport en
+140 compute units. Aucune transaction n'a été signée ou envoyée par ce probe.