v0.4.7-pre.011

olddocs/archivekbot3/001.README.md

@@ -1,5 +1,5 @@
 <!-- file: olddocs/archivekbot3/001.README.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Archive documentaire de khadhroony-bot3
 
@@ -17,10 +17,14 @@ Les documents archivés :
 ## Arborescence
 
 - `docs/` : audits, plans et rapports bot3 remplacés ;
-- `prompts/` : prompts utilisés pendant la migration architecturale.
+- `prompts/` : prompts utilisés pendant la migration architecturale et les versions fonctionnelles clôturées.
 
 La documentation active reste sous `docs/`. Le point d’entrée normatif reste `RULES.md`.
 
 ## Clôture 0.4.6
 
 Les audits, guides et checklist temporaires utilisés pour clôturer la migration sont conservés sous `docs/` dans cette archive. Ils ne sont plus normatifs.
+
+## Clôture 0.4.7
+
+Le plan, le prompt de session et les rapports de prerelease de Metaplex Token Metadata sont archivés sous `docs/plans/`, `docs/validation/` et `prompts/`. Le rapport final actif reste sous `docs/validation/` jusqu’à la publication.

olddocs/archivekbot3/docs/plans/V0_4_7_METAPLEX_TOKEN_METADATA_COMPLETION_PLAN.md

@@ -0,0 +1,603 @@
+<!-- file: olddocs/archivekbot3/docs/plans/V0_4_7_METAPLEX_TOKEN_METADATA_COMPLETION_PLAN.md -->
+<!-- version: 11 -->
+
+# Plan `0.4.7` — achèvement de Metaplex Token Metadata
+
+## 1. Statut du document
+
+Ce document constitue le livrable de planification de `0.4.7-pre.001`.
+
+Il est temporaire et normatif pendant le développement de `0.4.7`. Il devra être mis à jour lorsque les preuves techniques imposent un changement d’ordre ou de périmètre, puis archivé sous `olddocs/archivekbot3/` pendant la prerelease finale après transfert de ses informations durables vers les documents actifs appropriés.
+
+Aucune capacité fonctionnelle Metaplex nouvelle n’est introduite par cette prerelease. Le correctif `pre.001-delta-fix-001` intègre la relecture systématique de tous les documents actifs sous `docs/` et aligne ce plan sur leurs règles transversales.
+
+## 2. Conclusion de l’audit initial
+
+La reprise part de la base bot3 complète migrée depuis bot2. La migration elle-même n’est pas partielle.
+
+La surface existante ne doit pas être réimplémentée :
+
+- le Program ID canonique est enregistré ;
+- le décodeur d’instructions est enregistré au runtime ;
+- les 58 discriminants publics `0..57` sont inventoriés dans la matrice active ;
+- les instructions actuelles et historiques sont distinguées ;
+- les principales familles de comptes Metaplex sont décodées avec validation d’owner, PDA, seeds, longueurs et suffixes ;
+- un modèle canonique de comptes actifs, expérimentaux et historiques existe ;
+- la matérialisation de l’état metadata principal et des comptes canoniques existe déjà ;
+- la séparation avec les metadata incorporées de Token-2022 est explicite ;
+- l’exécuteur est enregistré mais reste réservé : support `Maybe`, zéro instruction construite et payload `reserved_executor` ;
+- aucune orchestration stateful Metaplex dédiée n’est encore présente dans `kb-pipeline` ;
+- aucun scénario CLI Metaplex réutilisable ni panneau desktop d’exécution Metaplex n’est encore présent.
+
+La version `0.4.7` doit donc achever la surface autour de l’existant, pas recommencer le décodeur ou les projections déjà prouvées.
+
+## 3. Frontière fermée de la version
+
+### 3.1 Inclus
+
+- audit de propriété des faits matérialisés ;
+- complétion ciblée des faits metadata, admin, lifecycle et risk/compliance réellement absents ;
+- classification exécutable, decode-only ou non supportée de chaque instruction ;
+- intents typés et builders de toutes les opérations officiellement constructibles, non obsolètes et non remplacées ;
+- préflight borné, politique de confirmation, simulation obligatoire et plafonds de dépense ;
+- lectures stateful et corrélations de comptes Metaplex ;
+- postconditions et postvalidation ;
+- intégration replay et matérialisation idempotente ;
+- scénarios UI Devnet/Testnet dans le desktop, fixtures et validations automatisées parallèles dans `kb-pipeline-demo-scenarios` ;
+- adaptateurs Tauri et panneaux strictement nécessaires ;
+- documentation et clôture de version.
+
+### 3.2 Exclus
+
+- JSON off-chain référencé par URI ;
+- fetch HTTP, IPFS ou Arweave ;
+- création de `kb-offchain-transport` ;
+- SPL Token Metadata ;
+- Metaplex Core ;
+- Metaplex Bubblegum au-delà des frontières explicitement nécessaires pour classer une instruction bridge ;
+- réécriture des décodeurs ou comptes déjà couverts sans écart démontré ;
+- validation réseau déclarée lorsque les fixtures ou autorités nécessaires ne sont pas disponibles.
+
+Les sujets off-chain et SPL Token Metadata restent affectés à `0.4.8`.
+
+## 4. Inventaire de la base réutilisable
+
+### 4.1 Instructions
+
+La matrice active inventorie 58 instructions :
+
+- 41 actuelles ;
+- 15 historiques ;
+- 1 historique dépréciée ;
+- 1 bridge actuelle liée à Bubblegum.
+
+Les familles déjà décodées comprennent notamment :
+
+- création et mise à jour metadata V1, V2, V3 et wrappers modernes ;
+- vérification, dévérification et administration de collections ;
+- collections dimensionnées ;
+- autorités d’usage et utilisation ;
+- signature de créateur et primary sale ;
+- normalisation, token standard et unverification de créateur ;
+- master editions, printed editions et conversions historiques ;
+- délégation, révocation, transfert, burn, lock, unlock et fermeture ;
+- freeze/thaw historiques ;
+- escrow et collect ;
+- wrappers modernes `Create`, `Mint`, `Print`, `Update`, `Use`, `Verify` et `Unverify` ;
+- migration, resize et gaps historiques finaux.
+
+Le statut `decode: unspecified` encore présent dans certaines entrées de matrice est un défaut documentaire de classification, pas une preuve d’absence automatique dans le code. Il devra être résolu par confrontation entre matrice, registre du décodeur et tests avant toute modification fonctionnelle.
+
+### 4.2 Comptes
+
+Les familles déjà couvertes comprennent :
+
+- Metadata ;
+- Edition et Master Edition ;
+- Edition Marker ;
+- Token Record programmable ;
+- Metadata Delegate Record et Holder Delegate Record ;
+- Collection Authority Record et Use Authority Record ;
+- Token Owned Escrow ;
+- Reservation List historique.
+
+Le modèle canonique porte déjà :
+
+- identité et Program ID ;
+- provenance ;
+- lifecycle actif, expérimental ou historique ;
+- politique de matérialisation ;
+- politique d’exécution candidate ou interdite pour l’historique.
+
+### 4.3 Matérialisation
+
+Les fonctions existantes matérialisent déjà :
+
+- les metadata incorporées Token-2022 sous le domaine distinct `spl_token_2022_embedded_metadata` ;
+- l’état Metadata Metaplex sous le domaine `metaplex_token_metadata` ;
+- les autres snapshots canoniques de comptes Metaplex ;
+- une surface de risque metadata dédiée existe mais reste à auditer pour sa couverture réelle.
+
+L’audit de `0.4.7` doit produire une table de propriété unique par fait avant d’ajouter une projection.
+
+### 4.4 Exécution
+
+L’exécuteur `ExMetadataMetaplexTokenMetadataExecutor` existe mais est réservé :
+
+- il reconnaît le Program ID ;
+- il retourne `Maybe` pour cette surface ;
+- il ne construit aucune instruction ;
+- il ne possède pas encore d’intents, de builders, de préflight ou de postconditions Metaplex.
+
+### 4.5 Pipeline et applications
+
+L’extraction Core, le replay générique, le stockage canonique et la matérialisation générique sont réutilisables.
+
+Les manques Metaplex spécifiques sont :
+
+- contrat de lecture stateful ;
+- corrélation mint/metadata/edition/token record/collection/authority/rule set ;
+- orchestration de préparation et d’exécution ;
+- postvalidation ;
+- diagnostics structurés ;
+- scénarios Devnet/Testnet et CLI ;
+- adaptateurs et panneaux desktop.
+
+## 5. Liste fermée des manques réels
+
+Le développement fonctionnel de `0.4.7` est limité aux éléments suivants.
+
+### 5.1 Contrat de couverture
+
+1. Résoudre chaque statut de matrice incomplet ou ancien.
+2. Attribuer à chaque instruction un statut exact :
+   - `executable_current` ;
+   - `decode_only_historical` ;
+   - `decode_only_bridge_boundary` ;
+   - `unsupported_with_reason` ;
+   - `executable_deprecated` ;
+   - `decode_only_replaced`.
+3. Attribuer à chaque instruction exécutable : builder officiel, comptes, signers, préconditions, confirmation et postconditions.
+4. Maintenir l’inventaire exhaustif `0..57`.
+
+### 5.2 Matérialisation
+
+1. Produire la table de propriété des faits.
+2. Vérifier la couverture de : nom, symbole, URI, seller fee, créateurs, collection, uses, token standard, mutabilité et programmable config.
+3. Vérifier la couverture de : update authority, collection authority, delegates et changements d’autorité.
+4. Vérifier la couverture lifecycle : création, mise à jour, vérification, édition, burn, lock/unlock et transitions prouvées.
+5. Vérifier la couverture risk/compliance : royalties, créateurs non vérifiés, mutabilité, rule sets et délégations sensibles.
+6. Ajouter uniquement les faits absents et stables.
+7. Ajouter les tests de non-fusion avec Token-2022 metadata.
+
+### 5.3 Exécuteur
+
+1. Définir les intents typés.
+2. Définir les builders à partir de `mpl-token-metadata` officiel pour toute opération officiellement constructible, non obsolète et non remplacée.
+3. Vérifier l’ordre des comptes et les signers exacts.
+4. Calculer les coûts contrôlables et plafonds de dépense.
+5. Rendre la simulation obligatoire avant soumission.
+6. Définir les confirmations opérateur sensibles.
+7. Interdire explicitement l’exécution des variantes historiques, obsolètes ou remplacées lorsque leur reconstruction n’est plus légitime.
+8. Remplacer le support `Maybe` réservé par une décision déterministe fondée sur l’intent.
+9. Interdire tout `Unsupported(reason)` motivé seulement par une priorité, un report ou une opération non retenue.
+
+### 5.4 Stateful, préflight et postconditions
+
+1. Lire les comptes nécessaires avec bornes de taille et owner exact.
+2. Recalculer les PDA et seeds.
+3. Vérifier les relations mint, metadata, edition, token account, collection et authority.
+4. Vérifier mutabilité, vérification, délégation, token standard et programmable config.
+5. Vérifier les rule sets et comptes d’autorisation lorsqu’ils s’appliquent.
+6. Définir les cas `not_applicable` au lieu de masquer une absence de preuve.
+7. Relire l’état après confirmation et vérifier les postconditions opérationnelles.
+
+### 5.5 Pipeline généraliste
+
+`kb-pipeline` doit rester utilisable depuis toute application, service, worker, CLI ou test, sans hypothèse propre à Devnet/Testnet.
+
+1. Ajouter les DTO et résultats Metaplex strictement nécessaires.
+2. Ajouter la corrélation stateful.
+3. Ajouter la préparation et l’orchestration d’exécution.
+4. Ajouter la postvalidation.
+5. Raccorder les observations au replay et à la matérialisation idempotente.
+6. Fournir des diagnostics stables pour scénarios et desktop.
+
+### 5.6 Scénarios Devnet/Testnet et desktop
+
+Les scénarios UI Devnet/Testnet restent dans `kb-app-demo-desktop`. `kb-pipeline-demo-scenarios` fournit en parallèle les fixtures, aides de campagne et tests automatisés capables de reproduire les mêmes parcours à partir des APIs généralistes de `kb-pipeline`.
+
+1. Conserver et compléter dans le desktop les scénarios UI simulation-only par défaut.
+2. Ajouter dans `kb-pipeline-demo-scenarios`, lorsque cela apporte une preuve utile à `0.4.7`, des tests automatisés Metaplex équivalents aux parcours desktop ; cette pratique doit ensuite être généralisée pendant la série `0.5.x`.
+3. Ajouter les fixtures synthétiques et fixtures réseau disponibles.
+4. Produire des résultats structurés et preuves de postcondition communs ou comparables entre tests automatisés et démonstrations UI.
+5. N'étendre `kb-pipeline-demo-scenarios-cli` que lorsqu'une préparation de fixture exige réellement une commande dédiée ; ne pas en faire implicitement le lanceur général de tous les scénarios.
+6. Ajouter uniquement les commandes Tauri et panneaux nécessaires, tout en conservant dans le desktop les états et séquences propres à l'expérience UI.
+7. Maintenir les primitives et orchestrations généralistes hors du desktop, dans `kb-pipeline` ou la crate métier propriétaire.
+
+## 6. Choix structurants
+
+### 6.1 Granularité des intents
+
+**Option A — un intent par instruction Metaplex**
+
+- fidélité maximale au SDK ;
+- surface publique volumineuse ;
+- duplication probable entre instructions historiques et wrappers modernes.
+
+**Option B — intents métier canoniques compilés vers une instruction actuelle**
+
+- API plus stable ;
+- meilleure séparation entre intention et génération SDK ;
+- nécessite une table explicite de résolution et empêche de choisir arbitrairement une variante historique.
+
+**Option C — intents hybrides**
+
+- intents métier pour les opérations communes ;
+- intents spécialisés pour les opérations Metaplex sans équivalent métier simple ;
+- complexité intermédiaire.
+
+**Recommandation : Option C.** Elle correspond à l’architecture d’exécution existante, limite l’exposition des détails historiques et conserve les opérations programmables spécifiques.
+
+### 6.2 Périmètre exécutable initial
+
+**Option A — toutes les instructions actuelles en une seule campagne**
+
+- couverture maximale immédiate ;
+- risque élevé de validation superficielle et de prereleases trop larges.
+
+**Option B — noyau sûr puis extensions par familles**
+
+- commence par create/update et opérations administratives dont les contrats sont les plus directement vérifiables ;
+- ajoute ensuite collections, délégations, programmable NFT, éditions, uses et escrow ;
+- permet une validation stateful progressive.
+
+**Option C — uniquement les wrappers modernes**
+
+- surface plus petite ;
+- couverture insuffisante de plusieurs opérations actuelles sans wrapper moderne complet.
+
+**Recommandation : Option B.** Aucune famille ne devient exécutable avant preuve complète de ses comptes, signers, préflight et postconditions.
+
+### 6.3 Propriété des faits matérialisés
+
+**Option A — un matérialiseur Metaplex monolithique**
+
+- simple à appeler ;
+- mélange metadata, administration, lifecycle et risque.
+
+**Option B — propriété par domaine fonctionnel existant**
+
+- metadata possède les attributs descriptifs ;
+- admin possède autorités et délégations ;
+- lifecycle possède les transitions prouvées ;
+- risk/compliance possède uniquement les signaux dérivés ;
+- exige une table anti-duplication.
+
+**Recommandation : Option B.** Elle respecte la règle de propriétaire unique et les frontières déjà utilisées par le workspace.
+
+### 6.4 Rule sets programmables
+
+**Option A — accepter un rule set opaque et transmettre les comptes fournis**
+
+- mise en œuvre rapide ;
+- ne prouve pas l’autorisation et affaiblit le fail-closed.
+
+**Option B — limiter l’envoi programmable aux rule sets et authorization data vérifiables**
+
+- cohérent avec simulation-first et préflight strict ;
+- le builder universel reste présent lorsqu’il est officiellement constructible ; l’envoi peut rester interdit faute de preuve stateful suffisante.
+
+**Recommandation : Option B.** Une opération programmable officiellement constructible conserve son builder, mais sa préparation ou son envoi échoue explicitement lorsque le rule set ou les données d’autorisation ne peuvent pas être vérifiés. Cette limite ne doit pas être confondue avec une absence d’implémentation de l’exécuteur.
+
+### 6.5 Validation réseau
+
+**Option A — exiger Devnet pour toute opération exécutable**
+
+- preuve forte ;
+- peut bloquer les opérations nécessitant des actifs, autorités ou rule sets indisponibles.
+
+**Option B — niveaux de preuve distincts**
+
+- builder parity et tests synthétiques obligatoires ;
+- simulation réseau lorsque les comptes existent ;
+- envoi et postcondition uniquement avec fixture contrôlée ;
+- statut réseau exact consigné par opération.
+
+**Recommandation : Option B.** La version peut clôturer avec certaines opérations validées synthétiquement seulement, à condition que ce statut soit explicite et que leur exécution publique soit limitée en conséquence.
+
+## 7. Ordonnancement proposé par prerelease
+
+La numérotation ci-dessous est un plan fermé initial. Elle peut être regroupée uniquement si deux lots restent cohérents et si le plan est mis à jour avant livraison.
+
+### `0.4.7-pre.001` — planification et inventaire
+
+**Travaux**
+
+- audit de la base migrée ;
+- inventaire instructions, comptes, matérialisations, exécuteur, pipeline et applications ;
+- liste fermée des manques ;
+- options architecturales et recommandations ;
+- plan par prerelease.
+
+**Acceptation**
+
+- aucun code fonctionnel Metaplex ajouté ;
+- plan accepté avant `pre.002` ;
+- confirmation qu’aucune capacité existante ne sera réimplémentée sans écart prouvé.
+
+### `0.4.7-pre.002` — contrat de couverture et propriété des faits
+
+**Dépendance** : acceptation de `pre.001`.
+
+**Travaux**
+
+- corriger les statuts incomplets de la matrice ;
+- classer les 58 instructions ;
+- produire la table instruction → builder/comptes/signers/préflight/postconditions ;
+- produire la table fait → propriétaire unique ;
+- compléter uniquement les projections stables manquantes et leurs tests.
+
+**Acceptation**
+
+- matrice exhaustive et sans statut ambigu ;
+- aucune duplication silencieuse avec Token-2022 ;
+- tests de matérialisation et d’idempotence ciblés validés.
+
+### `0.4.7-pre.003` — fondations de l’exécuteur et noyau metadata
+
+**Dépendance** : matrice et propriété des faits stabilisées.
+
+**Travaux**
+
+- intents communs, enveloppe d’exécution et politiques de coût ;
+- builders des wrappers courants `Create` (42) et `Update` (50), sans reconstruire les anciennes instructions remplacées ;
+- signers, comptes, PDA et mutabilité ;
+- simulation obligatoire ;
+- postconditions de création et mise à jour.
+
+**Acceptation**
+
+- parity tests avec builders officiels ;
+- erreurs fail-closed avant signature ;
+- variantes historiques rejetées explicitement.
+
+### `0.4.7-pre.004` — collections, créateurs et autorités — implémentée, validation locale requise
+
+**Travaux**
+
+- wrappers courants `Verify` et `Unverify` pour collections et créateurs ;
+- wrapper courant `Delegate`/`Revoke` pour les autorités de collection lorsque la variante correspondante est prouvée ;
+- aucune reconstruction de `SignMetadata`, des instructions sized collection historiques ni de `UpdatePrimarySaleHappenedViaToken` ;
+- confirmations opérateur et postconditions.
+
+**Acceptation**
+
+- autorités et records corrélés statefully ;
+- transitions de vérification prouvées ;
+- mauvais owners, PDA, authority et collection rejetés.
+
+### `0.4.7-pre.005` — programmable NFTs et délégations — réalisée
+
+**Travaux**
+
+- delegate/revoke ;
+- transfer, burn, lock, unlock et close accounts officiellement constructibles ;
+- token records, programmable config, rule sets et authorization data ;
+- politique de confirmation renforcée.
+
+**Acceptation**
+
+- aucune transmission opaque de rule set non vérifié ;
+- simulation et postconditions par opération ;
+- builders présents pour toute opération officiellement constructible ; préparation ou envoi refusé avec une raison stable lorsque les préconditions stateful ne sont pas prouvables.
+
+### `0.4.7-pre.006` — editions, use, escrow et opérations restantes — réalisée
+
+**Travaux**
+
+- master edition et printed edition actuelles ;
+- use authority et utilization ;
+- escrow et collect ;
+- create/mint/print/update/use/verify/unverify wrappers restants ;
+- resize/migrate et toute autre opération restante lorsque leurs contrats officiels permettent une construction exacte ;
+- classification définitive des instructions historiques et bridge.
+
+**Acceptation**
+
+- la surface `kb-lib` est fermée pour les 58 instructions : chaque opération officiellement constructible courante ou obsolète possède un intent et un builder ; seules les versions remplacées et la frontière Bubblegum restent sans builder ;
+- les opérations obsolètes encore officiellement constructibles sont exécutables sous `#[deprecated]` et approbation opérateur explicite ; les versions remplacées ne sont pas réexposées ;
+- aucun `Unsupported(reason)` ne masque une opération simplement non réalisée ou reportée ;
+- contrats d’edition marker et supply bornés ;
+- frontières Bubblegum explicites ;
+- `pre.007` ne doit normalement plus ajouter de builder Metaplex, sauf correction d’un écart démontré dans la matrice.
+
+### `0.4.7-pre.007` — intégration au pipeline généraliste stateful
+
+**Dépendance** : intents et familles exécutables stabilisés.
+
+**Travaux**
+
+- lectures stateful bornées ;
+- corrélation des comptes ;
+- préparation, simulation, confirmation, soumission et postvalidation ;
+- diagnostics structurés ;
+- replay et matérialisation idempotente.
+
+**Acceptation**
+
+- résultats déterministes et exploitables depuis toute application, service, worker, CLI ou test, sans dépendance aux scénarios de démonstration ;
+- tests de conflits Metaplex/Token-2022 ;
+- replay PostgreSQL idempotent.
+
+### `0.4.7-pre.008` — fixtures et validations automatisées Devnet/Testnet
+
+**Travaux**
+
+- fixtures NFT, SFT, fungible, collection et pNFT ;
+- scénarios synthétiques de démonstration ;
+- aides de préparation des campagnes Devnet/Testnet ;
+- tests automatisés Metaplex reproduisant, lorsque pertinent pour `0.4.7`, les parcours destinés au desktop ;
+- simulation-only par défaut dans les tests et campagnes ;
+- extension ciblée du CLI uniquement si une fixture Metaplex ne peut pas être préparée proprement autrement ;
+- résultats et preuves de postcondition.
+
+**Acceptation**
+
+- couverture automatisée parallèle disponible pour les parcours Metaplex retenus, sans suppression ni migration des scénarios UI du desktop ;
+- tests et campagnes fondés exclusivement sur les APIs généralistes de `kb-pipeline` et les contrats métier propriétaires ;
+- aucune soumission réelle automatique sans garde-fou explicite adapté aux tests réseau ;
+- statuts de validation réseau exacts.
+
+### `0.4.7-pre.009` — desktop
+
+**Dépendance** : APIs généralistes et contrats de fixtures stabilisés.
+
+**Travaux**
+
+- conservation et achèvement des scénarios UI Devnet/Testnet dans le desktop ;
+- adaptateurs Tauri minces autour des APIs généralistes ;
+- panneaux nécessaires ;
+- affichage préflight, simulation, confirmation et postconditions ;
+- aucun déplacement de logique métier vers l’application.
+
+**Acceptation**
+
+- audits Tauri/frontend validés ;
+- fonctionnement manuel des parcours retenus ;
+- réouverture et état applicatif cohérents.
+
+### `0.4.7-pre.010` — corpus et validations croisées — réalisée, validation locale requise
+
+**Travaux**
+
+- outer et CPI ;
+- succès et échec transactionnel ;
+- Program ID, owner, PDA, comptes, payload, suffixe et discriminant invalides ;
+- corpus NFT/SFT/fungible/collection/pNFT ;
+- simulations, envois disponibles et postconditions ;
+- rapports de validation.
+
+**Acceptation**
+
+- aucune validation réseau surdéclarée ;
+- matrice, tests, rapports et runtime alignés ;
+- écarts résiduels fermés ou reportés explicitement.
+
+### `0.4.7-pre.011` — clôture
+
+**Travaux**
+
+- aucune nouvelle surface majeure ;
+- tests finaux et audits de conformité ;
+- documentation générale et des crates ;
+- nettoyage des TODO, outils temporaires et références obsolètes ;
+- archivage du présent plan et des rapports devenus historiques ;
+- prompt `0.4.8` avec prerelease initiale de planification et prerelease finale de clôture ;
+- livraison finale.
+
+**Acceptation**
+
+- commandes de validation finales réussies ;
+- code, matrices, registres, bindings et documentation alignés ;
+- archive finale conforme aux règles du workspace.
+
+## 8. Dépendances et ordre critique
+
+L’ordre critique est :
+
+1. classification exhaustive ;
+2. propriété des faits ;
+3. intents et builders ;
+4. préflight et postconditions ;
+5. pipeline stateful ;
+6. fixtures et validations automatisées Devnet/Testnet ;
+7. scénarios UI desktop ;
+8. validation croisée ;
+9. clôture.
+
+Le desktop ne doit pas précéder la stabilisation des APIs généralistes et des contrats de fixtures. `kb-pipeline-demo-scenarios` ne doit pas absorber une orchestration généraliste ni remplacer les scénarios UI du desktop. Le pipeline ne doit pas autoriser la préparation ou l’envoi d’une opération avant stabilisation de son intent et de son contrat stateful. Une instruction ne doit pas être déclarée envoyable uniquement parce qu’un builder SDK existe, mais tout builder officiellement constructible doit être implémenté dans `kb-lib` sauf statut historique, obsolète ou remplacé documenté.
+
+## 9. Critères globaux d’acceptation
+
+`0.4.7` est fonctionnellement achevée lorsque :
+
+- les 58 instructions sont classées sans ambiguïté ;
+- les comptes pris en charge conservent owners, PDA, seeds, bornes et variantes historiques ;
+- les faits matérialisés ont un propriétaire unique ;
+- toutes les opérations officiellement constructibles, non obsolètes et non remplacées possèdent intents, builders et contrats exacts ; leurs signers, coûts, préflight, simulation, confirmation et postconditions sont appliqués dès qu’ils sont pertinents ;
+- les opérations historiques sont decode-only ;
+- le pipeline généraliste expose des résultats structurés et idempotents sans dépendance à un cluster de démonstration ;
+- les scénarios UI Devnet/Testnet restent disponibles dans le desktop ;
+- les parcours retenus disposent en parallèle d’une couverture automatisée dans `kb-pipeline-demo-scenarios` lorsque cette preuve est nécessaire à `0.4.7` ;
+- le desktop reste propriétaire de ses états et séquences UI, sans absorber les primitives généralistes ;
+- les conflits entre sources metadata restent explicites ;
+- le fetch off-chain est absent ;
+- chaque validation réseau est déclarée selon la preuve réellement obtenue.
+
+## 10. Validations prévues
+
+Pendant chaque prerelease :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+```
+
+Les tests ciblés des crates modifiées sont obligatoires avant livraison du delta.
+
+À la clôture :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test --workspace
+```
+
+Si le desktop est modifié :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+## 11. Décisions requises avant `pre.002`
+
+Le développement fonctionnel peut commencer après acceptation des recommandations suivantes :
+
+1. intents hybrides, métier lorsque possible et spécialisés lorsque nécessaire ;
+2. activation progressive par familles, avec fermeture exhaustive de toute la surface exécutable à la fin de `pre.006` ;
+3. propriété des faits par domaines metadata/admin/lifecycle/risk ;
+4. rule sets programmables fail-closed ;
+5. niveaux de preuve distincts pour les validations synthétiques, simulation réseau et envoi réel ;
+6. séquence de prereleases `pre.002` à `pre.011` décrite ci-dessus.
+
+
+## État de `0.4.7-pre.007`
+
+- lectures stateful bornées dans `kb-pipeline` ;
+- préflight généraliste lié aux plans `kb-lib` ;
+- orchestration simulation-first, résolution des signers et postconditions explicites ;
+- aucune dépendance vers `kb-pipeline-demo-scenarios` ;
+- les fixtures et campagnes réseau restent réservées à `pre.008`.
+
+
+## État de `0.4.7-pre.008`
+
+- inventaire synthétique fermé pour NFT, SFT, fungible, collection et pNFT ;
+- matrice automatisée de validation Metaplex avec preuves bornées ;
+- aucune soumission automatique ;
+- CLI inchangé faute de besoin démontré pour une fixture Metaplex dédiée ;
+- scénarios UI du desktop conservés pour `pre.009`.
+
+
+## État de `0.4.7-pre.009`
+
+- fenêtre desktop Metaplex dédiée ;
+- adaptateurs Tauri limités aux contrats de scénarios ;
+- affichage des exigences de préflight, simulation-first et postconditions ;
+- scénario sélectionné restauré à la réouverture ;
+- aucune logique métier dupliquée et aucune soumission automatique.

olddocs/archivekbot3/prompts/027_v0_4_7_metaplex_token_metadata_completion.md

@@ -0,0 +1,193 @@
+<!-- file: olddocs/archivekbot3/prompts/027_v0_4_7_metaplex_token_metadata_completion.md -->
+<!-- version: 2 -->
+
+# Prompt de session — `0.4.7` Achèvement de Metaplex Token Metadata
+
+## 1. Mission
+
+Reprendre `khadhroony-bot3` après la clôture validée de `0.4.6` et achever la surface Metaplex Token Metadata partiellement développée dans bot2. Tout ce qui avait été réalisé dans bot2 a été migré dans bot3 ; la reprise doit donc partir de cette base migrée complète, sans présenter la migration comme partielle.
+
+Le travail ne consiste pas à recommencer le décodeur ni les matérialisations déjà présentes. Il doit partir de l’état réel du code, établir un plan de travail fermé, puis compléter l’exécuteur, les contrats stateful, le pipeline, les scénarios réutilisables, le CLI, le desktop et les validations finales.
+
+Program ID canonique :
+
+```text
+metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
+```
+
+## 2. Base validée `0.4.6`
+
+La base comprend :
+
+- architecture bot3 consolidée en onze crates ;
+- Solana Core, SPL Memo, SPL Token classique, ATA et Token-2022 ;
+- transports HTTP/WebSocket, stockage PostgreSQL, extraction Core et replay ;
+- exécution simulation-first, confirmations, signers et postvalidation ;
+- décodeur Metaplex Token Metadata d’instructions ;
+- décodeur des comptes Metaplex avec owners, PDA, seeds, bornes et variantes historiques ;
+- matrice `test-fixtures/contract-matrices/METAPLEX_TOKEN_METADATA_MATRIX.json` ;
+- matérialisation metadata déjà substantielle ;
+- coexistence explicite avec les metadata incorporées de Token-2022 ;
+- workspace, matrices, registres et bindings TS-RS validés.
+
+Exception conservée : le registre ElGamal n’est pas déclaré validé réellement sur réseau. Cette exception ne doit pas être mêlée au jalon Metaplex.
+
+## 3. Lectures obligatoires
+
+1. `RULES.md`, `README.md`, `ROADMAP.md`, `CHANGELOG.md` et ce prompt ;
+2. `kb-lib/README.md`, `kb-lib/USAGE.md`, `kb-lib/TODO.md` ;
+3. `kb-pipeline/README.md`, `kb-pipeline-demo-scenarios/README.md` et `kb-app-demo-desktop/README.md` ;
+4. la matrice Metaplex active et les tests existants ;
+5. l’IDL archivée `idls/metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json` ;
+6. le prompt historique `olddocs/archivekbot2/prompts/026_v0_4_7_metaplex_token_metadata.md`, uniquement comme source historique à confronter au code bot3 actuel.
+
+## 4. Première prerelease — plan de travail et brainstorming
+
+La première prerelease de `0.4.7` est consacrée exclusivement à la préparation du développement. Elle ne doit pas introduire l’exécuteur, le pipeline Metaplex ou les démonstrations finales.
+
+Elle doit :
+
+- relire le code, les matrices, les tests, les documents actifs et les sources officielles retenues ;
+- inventorier les instructions et comptes déjà décodés ;
+- inventorier les projections metadata, admin, lifecycle et risk/compliance déjà présentes ;
+- identifier les opérations actuelles, historiques decode-only et non supportées ;
+- distinguer les travaux certains, les choix d’architecture et les questions encore ouvertes ;
+- proposer plusieurs options lorsque des choix structurants existent ;
+- produire un plan de travail ordonné par prerelease, avec dépendances, critères d’acceptation et validations prévues ;
+- établir une liste fermée des manques réels ;
+- confirmer explicitement qu’aucune capacité déjà couverte ne sera réimplémentée.
+
+Cette première prerelease doit aboutir à un plan accepté avant le commencement du développement fonctionnel.
+
+## 5. Frontière fonctionnelle
+
+Metaplex Token Metadata reste distinct de :
+
+- metadata incorporées de Token-2022 ;
+- SPL Token Metadata, prévu en `0.4.8` ;
+- Metaplex Core ;
+- JSON off-chain référencé par URI.
+
+Le fetch HTTP/IPFS/Arweave et la création éventuelle de `kb-offchain-transport` sont hors périmètre de `0.4.7`. Cette décision sera étudiée en `0.4.8` avec SPL Token Metadata.
+
+## 6. Matérialisation
+
+Auditer les projections existantes et compléter uniquement les faits stables manquants :
+
+- metadata : nom, symbole, URI, seller fee, créateurs, collection, uses, token standard, mutabilité et programmable config ;
+- admin : update authority, collection authority, delegates et changements d’autorité ;
+- lifecycle : création, mise à jour, vérification, édition, burn, lock/unlock et transitions prouvées ;
+- risk/compliance : royalties, mutabilité, créateurs non vérifiés, rule sets et délégations sensibles.
+
+Chaque fait doit avoir un propriétaire unique. Ne jamais fusionner silencieusement metadata Metaplex et metadata Token-2022.
+
+## 7. Exécution
+
+Implémenter dans `kb-lib` :
+
+- intents typés ;
+- builders validés contre les interfaces officielles ;
+- liste exacte des signers et comptes ;
+- coûts et plafonds de dépense ;
+- dry-run par défaut et simulation obligatoire ;
+- confirmation opérateur dédiée pour burn, changement d’autorité, verify/unverify, delegate/revoke, lock/unlock ;
+- classification explicite des opérations historiques decode-only.
+
+## 8. Préflight et postconditions
+
+Vérifier selon l’opération :
+
+- owner et Program ID ;
+- PDA et seeds ;
+- mint, metadata, edition, token account, collection et authority ;
+- état de mutabilité, vérification, délégation, token standard et programmable config ;
+- cohérence des rule sets et comptes d’autorisation ;
+- postconditions stateful après soumission.
+
+Tout écart doit échouer avant signature ou être classé explicitement non applicable.
+
+## 9. Pipeline
+
+Intégrer dans `kb-pipeline` :
+
+- lectures stateful bornées ;
+- préparation et orchestration d’exécution ;
+- corrélation des comptes Metaplex ;
+- postvalidation ;
+- insertion canonique, extraction Core, replay et matérialisation idempotente ;
+- diagnostics stables et résultats exploitables par les scénarios.
+
+## 10. Scénarios et démonstrations
+
+Ajouter dans `kb-pipeline-demo-scenarios` :
+
+- scénarios simulation-only par défaut ;
+- CLI pour les opérations retenues ;
+- fixtures synthétiques et, si possible, réseau ;
+- résultats structurés et preuves de postcondition.
+
+Ajouter dans `kb-app-demo-desktop` uniquement les adaptateurs Tauri et panneaux nécessaires. La logique fonctionnelle doit rester dans les crates réutilisables.
+
+## 11. Corpus et validations
+
+Couvrir au minimum :
+
+- NFT, SFT, token fongible, collection et programmable NFT ;
+- outer et CPI ;
+- transactions réussies et échouées ;
+- mauvais Program ID, owner, PDA, comptes, payload tronqué, suffixe et discriminant inconnu ;
+- conflits entre metadata Metaplex et metadata Token-2022 ;
+- replay PostgreSQL idempotent ;
+- simulation, confirmation, envoi et postconditions pour les opérations exécutables.
+
+Ne pas déclarer une validation réseau si les fixtures ou préconditions ne sont pas disponibles.
+
+## 12. Documentation pendant le développement
+
+Mettre à jour au fil des prereleases uniquement les documents nécessaires pour refléter les décisions et contrats réellement introduits :
+
+- les quatre documents des crates modifiées ;
+- la matrice Metaplex active ;
+- la documentation des opérations supportées, decode-only et non supportées ;
+- les rapports de validation propres aux capacités effectivement testées.
+
+La mise à jour générale de clôture appartient à la dernière prerelease.
+
+## 13. Dernière prerelease — clôture de `0.4.7`
+
+La dernière prerelease doit être réservée à la clôture de la version. Elle ne doit pas introduire une nouvelle surface fonctionnelle majeure.
+
+Elle doit obligatoirement :
+
+- exécuter les tests finaux, les audits de conformité et les validations applicatives nécessaires ;
+- vérifier l’alignement entre code, matrices, registres, bindings TS-RS et documentation ;
+- mettre à jour définitivement `README.md`, `ROADMAP.md` et `CHANGELOG.md` ;
+- mettre à jour les `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` des crates concernées ;
+- retirer des TODO les tâches terminées et transférer les travaux reportés vers la version correcte ;
+- archiver les prompts, plans, rapports ou documents de travail devenus historiques ;
+- supprimer les outils temporaires, fichiers de validation et références obsolètes qui ne doivent pas rester dans la version publiée ;
+- préparer le prompt complet de la session `0.4.8 — SPL Token Metadata et décision off-chain metadata` ;
+- vérifier que ce prompt commence lui aussi par une prerelease de planification et se termine par une prerelease de clôture ;
+- préparer la livraison finale de `0.4.7` selon les règles du workspace.
+
+## 14. Validation finale
+
+Exécuter :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test --workspace
+```
+
+Si le desktop est modifié, valider avec :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+## 15. Livraisons
+
+Après l’archive complète de départ, livrer uniquement des ZIP delta contenant `delta.md`, sans SHA-256. Les correctifs d’une même prerelease utilisent `-delta-fix-XXX.zip`, avec une numérotation recommençant à `fix-001` pour chaque nouvelle prerelease.