v0.4.8-pre.001

2026-08-05 13:01:14 +02:00
parent 4d18550cca
commit 3e7e943d1c
8 changed files with 353 additions and 36 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/README.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->

 # Documentation active de Khadhroony Bot3

@@ -93,6 +93,10 @@ Les onze crates possèdent désormais `README.md`, `TODO.md`, `USAGE.md` et `CHA
 - [`validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md`](validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md) ;
 - [`validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md`](validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md) ;

+## Plans de version actifs
+
+- [`Plan 0.4.8 — Solana Program Metadata et complétude Token-2022`](plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md).
+
 ## Prompt de reprise

 - [`Prompt actif 0.4.8`](../prompts/028_v0_4_8_spl_token_metadata_and_offchain_decision.md).
--- a/docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md
+++ b/docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md
@@ -0,0 +1,299 @@
+<!-- file: docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md -->
+<!-- version: 1 -->
+
+# Plan `0.4.8` — Solana Program Metadata et complétude Token-2022
+
+## 1. Statut et rôle
+
+Ce document est le livrable principal de `0.4.8-pre.001`. Il constitue le plan vivant de la version et reste modifiable lorsque l’audit du code, des interfaces officielles, de l’IDL ou des validations Devnet impose un ajustement.
+
+Il doit être maintenu pendant chaque prerelease, puis archivé pendant la dernière prerelease après transfert des décisions durables vers le ROADMAP, les matrices, les guides, les rapports, les TODO et les changelogs concernés.
+
+`0.4.8-pre.001` ne livre aucune capacité fonctionnelle nouvelle. Elle fixe les frontières, inventorie l’existant, décide le périmètre de la version et planifie les preuves Devnet avant le code.
+
+## 2. Décisions de périmètre
+
+### 2.1 Surfaces strictement distinctes
+
+| Surface                           | Program ID ou frontière                                            | Rôle dans `0.4.8`                                                               |
+|-----------------------------------|--------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| Metaplex Token Metadata           | `metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s`                      | surface clôturée en `0.4.7`, hors développement principal                       |
+| Token-2022 Token Metadata         | programme Token-2022 `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | compléter le contrat déjà partiellement pris en charge                          |
+| `spl-token-metadata-interface`    | interface sans Program ID autonome imposé                          | source contractuelle des instructions metadata implémentées par Token-2022      |
+| Solana Program Metadata           | `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S`                      | nouvelle surface on-chain à implémenter sous `metadata/solana_program_metadata` |
+| contenu distant HTTP/IPFS/Arweave | transport off-chain indépendant                                    | hors `0.4.8`, reporté à l’horizon `0.15+`                                       |
+
+Aucun décodeur Token-2022 existant n’est un décodeur partiel de `ProgM6…`. Les deux contrats doivent conserver des namespaces, modèles, matrices, tests et scénarios distincts.
+
+### 2.2 Décision off-chain
+
+`kb-offchain-transport` n’est pas créée en `0.4.8` ni réservée artificiellement à `0.4.9`. Elle est reportée à l’horizon `0.15+`, lorsqu’un consommateur réel et une architecture de workers justifieront son coût de sécurité et de maintenance.
+
+La décision durable est la suivante :
+
+- les URI restent des données canoniques observées on-chain ;
+- aucun décodeur canonique ne télécharge de contenu distant ;
+- un futur transport HTTP(S), IPFS et Arweave devra borner timeout, taille, MIME, redirections, cache, hash et provenance ;
+- il devra empêcher SSRF, rebinding DNS, accès aux réseaux locaux et contournements IPv4/IPv6 ;
+- l’échec, la mutation ou le contenu d’une ressource distante ne modifiera jamais le statut canonique du replay on-chain.
+
+## 3. Inventaire initial du workspace `0.4.7-final`
+
+### 3.1 Solana Program Metadata
+
+Éléments déjà présents :
+
+- Program ID canonique dans `kb-program-ids` ;
+- IDL brute sous `idls/metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json` ;
+- entrée dans `docs/IDL_AUDIT.md` avec version déclarée, nombre d’instructions et empreinte ;
+- cible `metadata/solana_program_metadata` dans `docs/IDL_TO_KB_LIB_NOMENCLATURE.md` ;
+- décodeur réservé dans `kb-lib/src/decoder/metadata/solana_program_metadata.rs` ;
+- exécuteur réservé dans `kb-lib/src/executor/metadata/solana_program_metadata.rs`.
+
+Éléments non encore implémentés : modèles publics, décodage de comptes, décodage d’instructions, matérialisation, builders, exécution, orchestration pipeline, campagne Devnet et panneau desktop.
+
+### 3.2 Token-2022 Token Metadata
+
+Le workspace possède déjà une couverture partielle des extensions `MetadataPointer` et `TokenMetadata`, ainsi que des intents/builders associés. L’audit de `pre.002` doit établir une matrice exacte et non supposée des cinq opérations de `spl-token-metadata-interface` :
+
+- `Initialize` ;
+- `UpdateField` ;
+- `RemoveKey` ;
+- `UpdateAuthority` ;
+- `Emit`.
+
+Pour chacune, il faut relever séparément : modèle, décodage d’instruction, builder, exécuteur, préflight, lecture stateful, matérialisation, tests synthétiques, scénario automatisé, panneau desktop et preuve Devnet.
+
+### 3.3 IDL et sources de vérité
+
+L’IDL `ProgM6…` doit rester brute et non réécrite. Avant de coder, `pre.002` doit comparer :
+
+- le Program ID déclaré ;
+- les discriminateurs ;
+- les comptes et leurs contraintes ;
+- les types, options, bornes et erreurs ;
+- les neuf instructions inventoriées ;
+- l’état des builders officiels ou de référence ;
+- l’empreinte déjà documentée.
+
+Une divergence entre l’IDL et les crates/sources officielles doit être documentée avant toute décision. Aucune version ou provenance ne doit être inventée.
+
+## 4. Périmètre fonctionnel de la version
+
+### 4.1 Solana Program Metadata
+
+La cible complète comprend :
+
+- modèles et contrats publics ;
+- comptes `Buffer` et `Metadata` après vérification officielle ;
+- neuf instructions initialement inventoriées : `Write`, `Initialize`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim`, `Close`, `Allocate`, `Extend` ;
+- dérivations PDA canonical, non-canonical et génériques confirmées par les sources ;
+- décodeur de comptes et d’instructions ;
+- matérialisation dédiée aux metadata de programme ;
+- builders et exécuteur bornés ;
+- orchestration stateful dans `kb-pipeline` ;
+- campagne reproductible dans `kb-pipeline-demo-scenarios` ;
+- parcours réel dans `kb-app-demo-desktop` ;
+- preuves Devnet conservées dans un rapport dédié.
+
+### 4.2 Complétude Token-2022
+
+La cible est de compléter les cinq opérations de l’interface dans les modules Token-2022 existants, sans créer une nouvelle famille de programme :
+
+- décodage exact ;
+- intents et builders manquants ;
+- capacités d’exécution et préflights ;
+- lectures avant/après ;
+- postconditions ;
+- matérialisation ;
+- scénarios synthétiques et Devnet ;
+- panneau desktop distinct de Solana Program Metadata.
+
+## 5. Stratégie de validation obligatoire
+
+Pour chaque capacité exécutable retenue :
+
+1. test contractuel ou comparaison avec la source officielle ;
+2. tests synthétiques positifs, négatifs et bornés ;
+3. fixture créée par les APIs Rust du workspace lorsque cela est approprié ;
+4. construction du message exact ;
+5. simulation RPC conservée ;
+6. soumission Devnet lorsque l’opération est sûre et disponible ;
+7. confirmation et signature conservées ;
+8. lectures stateful avant/après ;
+9. postconditions explicites ;
+10. replay de la transaction confirmée ;
+11. matérialisation observable ;
+12. qualification exacte : synthétique, simulé Devnet, soumis Devnet, non applicable, indisponible ou reporté avec justification.
+
+Aucune preuve synthétique ou simple simulation ne doit être présentée comme une validation réseau confirmée.
+
+## 6. Fixtures et campagnes Devnet prévues
+
+### 6.1 Fixture Solana Program Metadata
+
+La campagne doit disposer d’un programme de fixture ou d’un programme contrôlé dont l’autorité nécessaire est maîtrisée. Elle doit permettre au minimum :
+
+- metadata canonical ;
+- metadata non-canonical si le contrat le permet ;
+- initialisation ;
+- écriture segmentée ;
+- remplacement ;
+- extension ;
+- trim ;
+- changement d’autorité ;
+- passage immutable ;
+- opération refusée après immutabilité ;
+- fermeture lorsque le contrat l’autorise.
+
+Le besoin éventuel de déployer un programme de fixture doit être confirmé en `pre.002` avant création de code dédié.
+
+### 6.2 Fixture Token-2022 Token Metadata
+
+La campagne doit créer un mint Token-2022 reproductible et couvrir :
+
+- allocation et initialisation des extensions ;
+- `MetadataPointer` ;
+- initialisation des metadata ;
+- mise à jour des champs standards ;
+- ajout et suppression d’un champ additionnel ;
+- changement ou suppression de l’update authority selon le contrat ;
+- `Emit` avec bornes valides et invalides ;
+- état avant/après, replay et matérialisation.
+
+Les URI utilisées restent de simples chaînes on-chain. Aucun contenu distant n’est téléchargé.
+
+## 7. Découpage prévisionnel des prereleases
+
+Le découpage est volontairement fin. Il peut être fusionné ou subdivisé pour conserver des deltas petits, cohérents et testables.
+
+### `0.4.8-pre.001` — planification et première mise à jour documentaire
+
+- décisions de frontières ;
+- plan vivant ;
+- ROADMAP corrigé ;
+- prompt actif corrigé ;
+- index documentaire ;
+- ouverture des versions workspace, frontend et Tauri sur `0.4.8`.
+
+Critère : aucun code fonctionnel, plan complet incluant Devnet et report off-chain explicite.
+
+### `0.4.8-pre.002` — audit contractuel et matrice d’écarts
+
+- lecture complète des documents des crates concernées ;
+- audit de l’IDL `ProgM6…` contre les sources officielles ;
+- inventaire exact des comptes, instructions, PDA, erreurs, builders et contraintes ;
+- matrice de couverture Token-2022 des cinq opérations ;
+- choix définitif des modèles, fixtures, matérialisations et scénarios ;
+- corrections documentaires IDL uniquement si l’audit rend les documents actuels faux.
+
+Critère : matrice fermée et sources de vérité citées avant implémentation.
+
+### `0.4.8-pre.003` — modèles Solana Program Metadata
+
+- types, enums, erreurs, bornes et sérialisation ;
+- tests contractuels des représentations publiques.
+
+### `0.4.8-pre.004` — décodeur de comptes Solana Program Metadata
+
+- comptes `Buffer` et `Metadata` ;
+- discriminateurs, options, données malformées et trailing bytes selon contrat.
+
+### `0.4.8-pre.005` — décodeur d’instructions Solana Program Metadata
+
+- neuf instructions confirmées ;
+- comptes, signataires, arguments, échecs et instructions internes/externes.
+
+### `0.4.8-pre.006` — matérialisation Solana Program Metadata
+
+- snapshots et observations dédiés ;
+- autorité, mutabilité, source, format, encodage, compression et données on-chain pertinentes ;
+- aucune résolution de contenu distant.
+
+### `0.4.8-pre.007` — builders et exécuteur Solana Program Metadata
+
+- PDA, calculs de taille et rent ;
+- builders contractuellement équivalents ;
+- politiques de signataires, autorités et capacités.
+
+### `0.4.8-pre.008` — pipeline stateful Solana Program Metadata
+
+- simulation, soumission, confirmation, lectures avant/après, postconditions, replay et matérialisation.
+
+### `0.4.8-pre.009` — campagne Devnet Solana Program Metadata
+
+- fixture Rust native ;
+- scénarios réutilisables ;
+- preuves RPC et rapport intermédiaire.
+
+### `0.4.8-pre.010` — complétude Token-2022 Token Metadata
+
+- implémentation des écarts confirmés de `Initialize`, `UpdateField`, `RemoveKey`, `UpdateAuthority` et `Emit` ;
+- tests synthétiques et stateful.
+
+### `0.4.8-pre.011` — campagne Devnet Token-2022 Token Metadata
+
+- fixture mint ;
+- simulations, soumissions sûres, confirmations, postconditions, replay et matérialisation.
+
+### `0.4.8-pre.012` — desktop metadata
+
+- accordéons ou sous-panneaux séparés pour `ProgM6…`, Token-2022 et Metaplex ;
+- réutilisation du JsonViewer commun pour les résultats intégralement JSON ;
+- préparation, simulation, soumission, lectures et preuves ;
+- aucun bouton de fetch URI.
+
+### `0.4.8-pre.013` — stockage, matrices et réconciliation transversale
+
+- stockage si de nouveaux contrats persistants sont requis ;
+- exports, registres, matrices, nomenclature IDL et guides ;
+- retrait des statuts `reserved` uniquement lorsque l’implémentation correspondante est réelle.
+
+### `0.4.8-pre.014` — clôture obligatoire
+
+Réservée à :
+
+- validations finales et conformité ;
+- documentation générale et par crate ;
+- nettoyage des TODO ;
+- ROADMAP et changelogs ;
+- réconciliation IDL ;
+- rapport final de validation ;
+- archivage du plan, des rapports intermédiaires et du prompt ;
+- préparation du prompt suivant et de la release finale.
+
+Aucune nouvelle campagne Devnet fondamentale ne doit être découverte pendant cette phase.
+
+## 8. Discipline documentaire par delta
+
+Chaque delta doit :
+
+- modifier uniquement les documents rendus faux ou incomplets ;
+- maintenir le plan vivant et son statut d’avancement ;
+- conserver README et USAGE généralistes ;
+- réserver la chronologie aux changelogs et rapports ;
+- supprimer les TODO terminés et n’ajouter que des tâches explicites ;
+- maintenir les changelogs en ordre antéchronologique et dans leur périmètre ;
+- mettre à jour les documents IDL seulement lorsqu’un statut, compteur, inventaire, provenance ou mapping change ;
+- ne jamais modifier `olddocs/` hors archivage explicitement planifié.
+
+## 9. Critères de clôture de `0.4.8`
+
+La version peut être clôturée lorsque :
+
+- Solana Program Metadata n’est plus une surface réservée et sa couverture livrée est explicitement bornée ;
+- les cinq opérations Token-2022 Token Metadata ont un statut exact par couche ;
+- les scénarios Devnet prévus ont été exécutés ou qualifiés comme indisponibles avec justification et preuves ;
+- le desktop distingue sans ambiguïté Metaplex, Token-2022 et `ProgM6…` ;
+- aucune résolution off-chain n’est intégrée aux décodeurs ;
+- matrices, IDL, exports, TODO, guides, rapports et changelogs concordent avec le code ;
+- les contrôles finaux réussissent :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test --workspace
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```