Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.4.7-pre.016

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-05 11:29:43 +02:00
parent 40d831f84d
commit 1d1f57ae78
42 changed files with 493 additions and 1203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
prompts/001.README.md
View File

@@ -1,8 +1,8 @@
<!-- file: prompts/001.README.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Prompts actifs
Ce répertoire contient uniquement les prompts nécessaires aux prochaines versions fonctionnelles. Les prompts utilisés pendant la migration bot3 sont archivés sous `olddocs/archivekbot3/prompts/`.
Ce répertoire contient uniquement les prompts nécessaires aux prochaines versions fonctionnelles. Les prompts clôturés sont archivés sous `olddocs/archivekbot3/prompts/`.
- [`027_v0_4_7_metaplex_token_metadata_completion.md`](027_v0_4_7_metaplex_token_metadata_completion.md) : reprise après `0.4.6` et achèvement de Metaplex Token Metadata.
- [`028_v0_4_8_spl_token_metadata_and_offchain_decision.md`](028_v0_4_8_spl_token_metadata_and_offchain_decision.md) : planification de SPL Token Metadata et décision sur le transport off-chain.

193
prompts/027_v0_4_7_metaplex_token_metadata_completion.md
View File

@@ -1,193 +0,0 @@
<!-- file: 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.

156
prompts/028_v0_4_8_spl_token_metadata_and_offchain_decision.md Normal file
View File

@@ -0,0 +1,156 @@
<!-- file: prompts/028_v0_4_8_spl_token_metadata_and_offchain_decision.md -->
<!-- version: 2 -->
# Prompt de session — 0.4.8 SPL Token Metadata et décision off-chain
## Mission
Reprendre `khadhroony-bot3` après la clôture de `0.4.7` et étudier SPL Token Metadata comme surface distincte de Metaplex Token Metadata et des metadata incorporées Token-2022.
La session doit commencer par une planification complète et structurée, puis conserver une planification vivante pendant tout le développement. Le plan initial doit couvrir l’ensemble de la version, mais il peut être corrigé, enrichi, réordonné ou regrouper des phases lorsque l’état réel du code le justifie.
## Exigences de départ obligatoires
Avant toute proposition d’architecture, modification de code ou création de delta :
1. lire les documents racine actifs, notamment `README.md`, `ROADMAP.md`, `RULES.md` et les documents auxquels ils renvoient ;
2. lire intégralement les règles et normes actives du projet :
- `docs/rules/RULES_GENERAL.md` ;
- `docs/rules/RULES_RUST.md` ;
- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
- `docs/rules/CRATE_DOCUMENTATION_RULES.md` ;
- `docs/rules/VERSION_DEVELOPMENT_LIFECYCLE.md` ;
3. relever et appliquer les conventions portant notamment sur :
- Rust 2024 et les restrictions du workspace ;
- visibilité, exports publics, imports et documentation Rust ;
- interdictions `unsafe`, `unwrap`, `expect`, `panic` et règles Tauri spécifiques ;
- entêtes `file:` et `version:` ;
- incrémentation des versions locales des fichiers modifiés ;
- lignes vides, fins de fichier et organisation des modules ;
- emplacement attendu de chaque type de code, test, fixture, IDL et document ;
- format, contenu et rôle de `README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md`, rapports, guides, prompts et archives ;
- documents à mettre à jour selon la nature de chaque modification ;
- ordre antéchronologique des changelogs et limitation de chaque changelog à son propre périmètre ;
- politique des prereleases, deltas, correctifs et archivages ;
4. inspecter les `README.md`, `USAGE.md`, `TODO.md` et `CHANGELOG.md` des crates directement concernées avant de les modifier ;
5. inspecter les audits, matrices, IDL, rapports de validation et archives pertinentes sans modifier les archives historiques ;
6. vérifier l’état réel du workspace avant d’utiliser une hypothèse issue d’une ancienne session ou d’un ancien document.
Une règle découverte en cours de session doit être intégrée immédiatement au travail courant ; elle ne doit pas être reportée à la clôture.
## Première prerelease obligatoire
La première prerelease est consacrée au plan et au brainstorming. Avant le code, elle doit :
- inventorier les programmes, Program ID, interfaces, comptes, instructions, builders et sources officielles ;
- distinguer précisément SPL Token Metadata, Solana Program Metadata, Metaplex Token Metadata et les metadata incorporées Token-2022 ;
- identifier ce qui existe déjà dans `kb-program-ids`, `kb-lib`, `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop`, `kb-store`, les matrices et les documents ;
- fixer le périmètre decoder/materializer/executor/pipeline/desktop ;
- décider les fixtures et scénarios réseau nécessaires ;
- découper les prereleases et définir leurs critères d’acceptation ;
- décider séparément le périmètre éventuel de `kb-offchain-transport` ;
- préciser les documents, changelogs, TODO, matrices et rapports à maintenir pendant chaque phase.
Le plan doit couvrir la version complète dès le départ, y compris les scénarios Devnet réels. Il reste toutefois souple : des étapes peuvent être ajoutées, déplacées, fusionnées ou séparées si les découvertes techniques l’exigent.
L’objectif opérationnel est de conserver des deltas petits et testables, dont la préparation reste généralement compatible avec une livraison toutes les 10 à 15 minutes de travail effectif. Une phase trop large doit être divisée ; des phases devenues artificiellement petites peuvent être regroupées.
## Scénarios Devnet réels obligatoirement prévus
L’erreur à ne pas reproduire depuis `0.4.7` est de ne pas avoir prévu les scénarios réels dans la planification initiale.
Pour chaque capacité exécutable retenue, le plan doit prévoir dès le départ, puis maintenir pendant le développement :
1. tests contractuels et synthétiques ;
2. campagne réutilisable dans `kb-pipeline-demo-scenarios` lorsque cela apporte une validation automatisable ;
3. panneau ou parcours réel dans `kb-app-demo-desktop` ;
4. fixture Devnet reproductible et préparée par les APIs Rust du workspace lorsque cela est approprié ;
5. simulation RPC du message exact ;
6. soumission confirmée lorsque l’opération est sûre et réalisable ;
7. lectures stateful, postconditions et matérialisation observables ;
8. état de validation explicite : synthétique, simulé Devnet, soumis Devnet, non applicable, indisponible ou reporté avec justification.
La mise en œuvre peut évoluer pendant la version, mais les scénarios réels ne doivent jamais disparaître du plan. Une surface ne doit pas être annoncée comme validée réseau sans preuve d’exécution réelle observée.
## Audit et gestion des IDL
Avant le code :
1. vérifier si une IDL officielle existe pour la surface SPL Metadata visée ;
2. examiner l’IDL déjà présente :
`idls/metadata.ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S.solana_program_metadata.V0_0_0.from_github_solana_program.json` ;
3. déterminer, depuis les sources officielles, si cette IDL correspond exactement au programme et au contrat étudiés ;
4. ne pas assimiler deux surfaces seulement parce que leurs noms contiennent « metadata ».
Lorsqu’une IDL officielle pertinente est trouvée :
- conserver une copie brute et non réécrite sous `idls/` ;
- appliquer la convention de nommage documentée dans `idls/001.README.md` ;
- encoder la provenance et la version dans le nom ;
- vérifier le Program ID déclaré, la validité JSON et l’empreinte ;
- mettre à jour au minimum :
- `idls/001.README.md` ;
- `docs/IDL_AUDIT.md` ;
- `docs/IDL_TO_KB_LIB_NOMENCLATURE.md` ;
- `docs/MISSING_PROGRAM_IDLS.md` si le statut « manquante » change ;
- les documents de classification ou de surface IDL concernés ;
- mettre à jour les compteurs, inventaires, provenance, nomenclature cible et décisions architecturales associées ;
- ne jamais inventer une version ou une provenance absente de la source.
Si aucune IDL officielle exploitable n’existe, documenter cette absence et utiliser les crates/interfaces officielles comme source de vérité sans fabriquer d’IDL.
## Frontières
- SPL Token Metadata reste distinct de Metaplex Token Metadata ;
- Solana Program Metadata doit être identifié exactement avant d’être assimilé ou non à SPL Token Metadata ;
- les metadata incorporées Token-2022 gardent leur propre contrat ;
- le fetch off-chain n’est pas incorporé au décodeur canonique ;
- les IDL et interfaces archivées restent des références statiques ;
- les archives sous `olddocs/` ne doivent pas être modifiées hors opération d’archivage explicitement prévue.
## Décision `kb-offchain-transport`
Étudier une crate dédiée pour HTTP(S), IPFS et Arweave avec : timeout, taille, type MIME, redirections, cache, hash, provenance, protection SSRF et interdiction des réseaux locaux. Le contenu distant ne modifie jamais le statut canonique du replay on-chain.
Cette décision doit rester séparée de l’implémentation canonique on-chain. Elle peut être reportée à une version suivante si son périmètre rend `0.4.8` trop large.
## Discipline documentaire pendant la version
À chaque delta :
- mettre à jour uniquement les documents rendus faux ou incomplets par les modifications du delta ;
- conserver les `README.md` et `USAGE.md` généralistes, structurés par fonction ou groupe, jamais comme journaux de prerelease ;
- réserver les détails chronologiques aux changelogs et rapports de validation ;
- supprimer des TODO les tâches réellement terminées ;
- ajouter seulement des TODO explicites, encore actionnables et placés dans le bon périmètre ;
- maintenir les changelogs du plus récent au plus ancien et limiter chaque entrée aux changements de son emplacement ;
- réconcilier les matrices, guides, rapports, nomenclatures et documents IDL avec le code livré ;
- archiver les documents de travail devenus historiques plutôt que de les laisser parmi les documents actifs.
## Dernière prerelease obligatoire
La dernière prerelease doit être réservée à :
- validations finales et conformité ;
- documentation générale et par crate ;
- nettoyage des TODO ;
- mise à jour du ROADMAP et des changelogs ;
- réconciliation des documents IDL ;
- archivage du plan, des rapports intermédiaires et du prompt de session ;
- préparation du prompt suivant ;
- préparation de la release finale.
La dernière prerelease ne doit pas servir à découvrir tardivement des scénarios Devnet qui n’auraient jamais été planifiés.
## Contrôles finaux
```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
```
Les validations Devnet doivent être exécutées selon les parcours documentés dans `kb-app-demo-desktop`, avec conservation des signatures, résultats de simulation, confirmations, postconditions et preuves de matérialisation pertinentes.