0.4.7-pre.001
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/ARCHITECTURE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Architecture générale
|
||||
|
||||
@@ -66,7 +66,8 @@ Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacité
|
||||
|
||||
### 2.5 Démonstrations et applications
|
||||
|
||||
- `kb-pipeline-demo-scenarios` fournit une bibliothèque réutilisable et le binaire `kb-pipeline-demo-scenarios-cli`.
|
||||
- `kb-pipeline-demo-scenarios` fournit les fixtures et les campagnes automatisées spécifiques à Devnet/Testnet. Ces campagnes peuvent reproduire en parallèle les parcours de démonstration du desktop afin de les valider par des tests sans déplacer les scénarios UI hors de `kb-app-demo-desktop`.
|
||||
- Le binaire `kb-pipeline-demo-scenarios-cli` a été introduit pour préparer les fixtures SPL Token-2022 utilisées ensuite par les démonstrations d’exécution Devnet ; il ne constitue pas, par défaut, une interface générale de tous les scénarios.
|
||||
- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop.
|
||||
- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son périmètre reste incomplet.
|
||||
|
||||
@@ -98,10 +99,11 @@ L’exécution suit un flux séparé : intention typée, construction, préfligh
|
||||
- Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de `kb-program-ids`.
|
||||
- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`.
|
||||
- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`.
|
||||
- Les scénarios réutilisables doivent migrer vers `kb-pipeline-demo-scenarios` plutôt que rester enfouis dans l’UI.
|
||||
- Les scénarios UI spécifiques à Devnet/Testnet restent dans `kb-app-demo-desktop`. Lorsqu’un même parcours doit être validé automatiquement, un scénario équivalent est ajouté en parallèle dans les tests de `kb-pipeline-demo-scenarios` ; cette duplication contrôlée de parcours de validation ne déplace pas le scénario UI.
|
||||
- Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à `kb-pipeline` ou à la crate métier propriétaire.
|
||||
- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont consommées par plusieurs tests.
|
||||
- Les archives documentaires ne participent ni au build ni aux décisions normatives.
|
||||
|
||||
## 5. État de migration
|
||||
|
||||
L’architecture bot3 est alignée fonctionnellement sur le périmètre bot2 `0.4.6`. Les travaux Metaplex Token Metadata partiellement migrés sont repris séparément dans `0.4.7`.
|
||||
L’architecture bot3 est alignée fonctionnellement sur le périmètre bot2 `0.4.6`. Tout le travail Metaplex Token Metadata réalisé dans bot2 a été migré dans bot3 ; `0.4.7` achève cette surface à partir de cette base migrée complète.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Architecture du pipeline
|
||||
|
||||
## 1. Responsabilité
|
||||
|
||||
`kb-pipeline` coordonne des opérations qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution.
|
||||
`kb-pipeline` coordonne des opérations généralistes qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution. Il ne dépend d’aucun scénario, wallet ou actif propre à un réseau de démonstration.
|
||||
|
||||
## 2. Familles de traitements
|
||||
|
||||
@@ -42,7 +42,13 @@ kb-wallet -> signataires lorsque requis
|
||||
|
||||
## 4. Scénarios de démonstration
|
||||
|
||||
`kb-pipeline-demo-scenarios` doit contenir les scénarios réutilisables hors UI. `kb-app-demo-desktop` adapte leurs requêtes, progrès et résultats en payloads Tauri. Une dépendance à l’application desktop dans le sens inverse serait incorrecte.
|
||||
`kb-pipeline-demo-scenarios` contient les fixtures, aides de campagne et tests automatisés spécifiques à Devnet ou Testnet. Ses tests peuvent reproduire les mêmes parcours fonctionnels que les démonstrations UI afin de fournir une validation automatisée parallèle, sans retirer ni déplacer les scénarios Devnet/Testnet de `kb-app-demo-desktop`.
|
||||
|
||||
Cette crate peut préparer des wallets temporaires, demander des airdrops, créer des mints ou comptes de test, enchaîner plusieurs opérations et réunir les preuves d’une campagne réseau. Ces responsabilités spécifiques aux validations réseau ne doivent pas remonter dans `kb-pipeline`.
|
||||
|
||||
Le binaire `kb-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios.
|
||||
|
||||
`kb-app-demo-desktop` conserve ses commandes, états et parcours UI de démonstration Devnet/Testnet. Les tests parallèles de `kb-pipeline-demo-scenarios` vérifient des parcours équivalents à partir des APIs généralistes ; ils ne remplacent pas les démonstrations desktop. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite.
|
||||
|
||||
## 5. Contrats de preuve
|
||||
|
||||
@@ -51,5 +57,5 @@ Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contra
|
||||
## 6. Limites connues
|
||||
|
||||
- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
|
||||
- Certains scénarios restent à rendre pleinement autonomes hors desktop.
|
||||
- La couverture automatisée parallèle des scénarios desktop reste à étendre progressivement dans `kb-pipeline-demo-scenarios`, notamment pendant la série `0.5.x`.
|
||||
- La documentation détaillée des APIs publiques du pipeline sera produite dans `kb-pipeline/USAGE.md` après inventaire des exports.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/SURFACE_CRATE_MATRIX.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Matrice des responsabilités par surface
|
||||
|
||||
@@ -13,15 +13,15 @@
|
||||
|
||||
## 2. Matrice
|
||||
|
||||
| Surface | `kb-lib` | `kb-pipeline` | `kb-store` | `kb-onchain-transport` | scénarios | desktop |
|
||||
|-------------------------|-----------------------------------------|---------------------------------------------|------------------------|------------------------|-----------------------------------|----------------------------------------------|
|
||||
| Solana Core | décodeurs, exécuteurs, matérialisateurs | extraction, replay, exécution | persistance | RPC | validations Devnet | panneaux fonctionnels |
|
||||
| SPL Memo | décodage v1/v3/v4, exécution v4 | replay et exécution v4 | persistance | RPC | scénario Memo v4 | panneau Memo v4 |
|
||||
| SPL Token classique | contrats et implémentations | stateful, préflight, orchestration | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
|
||||
| SPL ATA | contrats et implémentations | état et orchestration | persistance | RPC | scénarios classique/Token-2022 | panneaux fonctionnels |
|
||||
| Token-2022 | contrats et implémentations | corrélation, preuves, préflight, validation | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
|
||||
| Registre ElGamal | implémentation partielle confirmée | traitement stateful à vérifier par API | persistance selon flux | acquisition de comptes | pas de validation réelle déclarée | présentation non raccordée fonctionnellement |
|
||||
| Metaplex Token Metadata | décodeur partiellement migré | à compléter selon besoins | à compléter | acquisition standard | à créer/compléter | à créer/compléter |
|
||||
| Surface | `kb-lib` | `kb-pipeline` | `kb-store` | `kb-onchain-transport` | scénarios | desktop |
|
||||
|-------------------------|-------------------------------------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------|------------------------|--------------------------------------------|----------------------------------------------|
|
||||
| Solana Core | décodeurs, exécuteurs, matérialisateurs | extraction, replay, exécution | persistance | RPC | validations Devnet | panneaux fonctionnels |
|
||||
| SPL Memo | décodage v1/v3/v4, exécution v4 | replay et exécution v4 | persistance | RPC | scénario Memo v4 | panneau Memo v4 |
|
||||
| SPL Token classique | contrats et implémentations | stateful, préflight, orchestration | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
|
||||
| SPL ATA | contrats et implémentations | état et orchestration | persistance | RPC | scénarios classique/Token-2022 | panneaux fonctionnels |
|
||||
| Token-2022 | contrats et implémentations | corrélation, preuves, préflight, validation | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
|
||||
| Registre ElGamal | implémentation partielle confirmée | traitement stateful à vérifier par API | persistance selon flux | acquisition de comptes | pas de validation réelle déclarée | présentation non raccordée fonctionnellement |
|
||||
| Metaplex Token Metadata | décodeurs de comptes/instructions et matérialisation migrés ; exécuteur réservé à achever | pipeline généraliste Metaplex à achever | persistance générique présente ; projections à auditer | acquisition standard | scénarios Devnet/Testnet à créer/compléter | adaptateurs et panneaux à créer/compléter |
|
||||
|
||||
## 3. Interprétation
|
||||
|
||||
@@ -32,4 +32,4 @@ Cette matrice décrit les responsabilités observées au niveau architectural. E
|
||||
- Memo v1 et v3 restent non exécutables.
|
||||
- Memo v4 est exécutable.
|
||||
- Le registre ElGamal ne doit pas être présenté comme validé Devnet/Mainnet.
|
||||
- Metaplex Token Metadata appartient au travail `0.4.7` commencé avant la migration et seulement partiellement repris dans bot3.
|
||||
- Tout le travail Metaplex Token Metadata réalisé dans bot2 a été migré dans bot3. `0.4.7` doit achever la surface sans présenter cette migration comme partielle.
|
||||
|
||||
578
docs/plans/V0_4_7_METAPLEX_TOKEN_METADATA_COMPLETION_PLAN.md
Normal file
578
docs/plans/V0_4_7_METAPLEX_TOKEN_METADATA_COMPLETION_PLAN.md
Normal file
@@ -0,0 +1,578 @@
|
||||
<!-- file: docs/plans/V0_4_7_METAPLEX_TOKEN_METADATA_COMPLETION_PLAN.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# 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` ;
|
||||
- `decode_only_obsolete` ;
|
||||
- `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 create/update actuels officiellement constructibles ;
|
||||
- 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
|
||||
|
||||
**Travaux**
|
||||
|
||||
- verify/unverify/set-and-verify ;
|
||||
- sized collection items ;
|
||||
- collection authority approve/revoke ;
|
||||
- creator sign/unverify et primary sale ;
|
||||
- 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
|
||||
|
||||
**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
|
||||
|
||||
**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, non obsolète et non remplacée possède un intent et un builder ;
|
||||
- aucune instruction historique, obsolète ou remplacée n’est exécutable lorsque sa reconstruction n’est plus légitime ;
|
||||
- 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
|
||||
|
||||
**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.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_SPECIFIC_KHADHROONY.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Règles spécifiques à `khadhroony-bot3`
|
||||
|
||||
@@ -33,16 +33,53 @@ Toute divergence avec une règle générale doit être explicitement documentée
|
||||
|
||||
## Règles d'architecture
|
||||
|
||||
### Couverture des décodeurs
|
||||
|
||||
- Les décodeurs ne dépendent pas de PostgreSQL, SQLite, RPC, Tauri, wallet, stratégie ou matérialisateurs.
|
||||
- Les matérialisateurs ne dépendent pas du RPC, du wallet, de Tauri ou des décodeurs spécifiques.
|
||||
- Pour chaque programme Solana, quelle que soit sa famille, un décodeur doit couvrir maximalement tout wire officiellement identifiable de sa surface, qu'il soit historique, courant, récent, expérimental ou publié avant son déploiement généralisé. Ces statuts doivent rester explicites et ne constituent pas un motif pour supprimer le décodage.
|
||||
- Pour chaque programme Solana, quelle que soit sa famille, le décodeur doit couvrir maximalement tout wire officiellement identifiable : historique, courant, déprécié, expérimental, en développement ou publié avant son déploiement généralisé.
|
||||
- Le statut historique, déprécié, expérimental, en développement ou non encore déployé partout ne constitue jamais à lui seul un motif pour omettre un discriminant, un layout de compte ou une variante de wire officiellement documentée.
|
||||
- Lorsqu'un wire officiel est identifiable mais pas encore interprétable complètement, le décodeur doit produire une classification bornée et explicite, conserver les preuves disponibles et refuser toute interprétation inventée.
|
||||
- Les discriminants, layouts et variantes inconnus doivent échouer de manière bornée et diagnostiquée ; ils ne doivent pas être assimilés silencieusement à une variante connue.
|
||||
- Une observation lisible issue d'une transaction échouée peut conserver une intention non commitée ; elle ne doit jamais être présentée comme une mutation réussie.
|
||||
- Pour chaque programme Solana, les matérialisateurs doivent projeter maximalement tous les faits métier stables et prouvés par le décodage, y compris les états historiques, obsolètes, dépréciés ou seulement rencontrables pendant un backfill. Le statut historique interdit l'exécution, mais ne constitue jamais à lui seul un motif de non-matérialisation.
|
||||
- La matrice contractuelle et les tests doivent distinguer explicitement les variantes courantes, historiques, dépréciées, expérimentales, en développement et inconnues.
|
||||
|
||||
### Couverture des matérialisateurs
|
||||
|
||||
- Les matérialisateurs ne dépendent pas du RPC, du wallet, de Tauri ou des décodeurs spécifiques.
|
||||
- Pour chaque programme Solana, les matérialisateurs doivent projeter maximalement tous les faits métier stables et prouvés par les sorties normalisées du décodage, y compris les états historiques, obsolètes, dépréciés, expérimentaux ou seulement rencontrables pendant un backfill.
|
||||
- Une instruction ou un compte decode-only peut et doit produire une matérialisation lorsque son observation prouve un fait stable relevant d'un propriétaire métier identifié.
|
||||
- Le statut historique interdit éventuellement l'exécution, mais ne constitue jamais à lui seul un motif de non-matérialisation.
|
||||
- Toute projection historique doit conserver explicitement son lifecycle, sa version de layout, sa provenance, son slot ou ordre d'observation lorsqu'ils sont connus, et ne doit jamais écraser silencieusement un état actif plus récent.
|
||||
- Une même réalité métier doit avoir une seule projection canonique. Les snapshots de comptes sont la source autoritative de l'état final lorsqu'ils sont disponibles ; les instructions et événements corrélés restent des observations de mutation et ne doivent pas produire un doublon concurrent du même état.
|
||||
- Les matérialisateurs doivent refuser les transactions non commitées pour les mutations d'état, tout en pouvant conserver séparément une intention non commitée lorsque le modèle métier le prévoit explicitement.
|
||||
- Toute absence volontaire de projection doit être documentée avec une justification technique précise. Un matérialisateur ne doit inventer ni état final, ni montant, ni autorité, ni frais, ni agrégation que l'observation ne prouve pas.
|
||||
- Pour chaque programme Solana, les exécuteurs doivent couvrir maximalement les opérations officiellement appelables et les opérations expérimentales publiées lorsque leurs contrats exacts et garde-fous sont prouvés. Les opérations historiques, dépréciées ou obsolètes doivent rester décodables et matérialisables, mais ne doivent jamais être exposées à l'exécution ; cette exclusion doit être explicite dans la matrice et le README.
|
||||
|
||||
### Couverture des exécuteurs
|
||||
|
||||
- Pour chaque programme Solana, les exécuteurs doivent couvrir maximalement toutes les opérations officiellement constructibles ou appelables qui ne sont ni obsolètes ni remplacées par une variante canonique imposée.
|
||||
- Cette obligation couvre les opérations courantes, récentes, expérimentales, en développement et publiées avant leur déploiement généralisé dès lors que leur wire, leurs comptes, leurs signers et leurs garde-fous exacts sont prouvés.
|
||||
- Une opération ne peut pas être exclue parce qu'elle n'a pas été arbitrairement retenue pour une version. Chaque opération officiellement connue doit recevoir un statut déterministe : `Supported`, `Unsupported(reason)`, `DecodeOnlyHistorical`, `DecodeOnlyObsolete`, `DecodeOnlyReplaced` ou frontière de programme explicitement documentée.
|
||||
- `Unsupported(reason)` est réservé à une impossibilité technique ou contractuelle précise et vérifiable. Il ne doit jamais masquer un travail non réalisé, un choix de priorité ou une absence d'inventaire.
|
||||
- Les opérations historiques, dépréciées, obsolètes ou remplacées restent décodables et matérialisables lorsqu'elles prouvent des faits, mais ne doivent pas être exposées à l'exécution lorsque la variante n'est plus légitime à construire.
|
||||
- Le déploiement sur un cluster, la disponibilité d'une fixture, la simulation réseau et l'autorisation d'envoi sont des niveaux de preuve distincts ; leur absence ne supprime pas un builder universel officiellement constructible.
|
||||
- Toute exclusion d'exécution doit être explicite dans la matrice contractuelle, les capacités runtime et la documentation publique de la surface.
|
||||
|
||||
### Frontière des pipelines
|
||||
|
||||
- `kb-pipeline` est le pipeline généraliste, réutilisable et indépendant d'un environnement de démonstration. Ses contrats doivent pouvoir être appelés depuis une application, un service, un worker, un CLI, des tests ou une autre orchestration, sur tout cluster compatible autorisé par la configuration.
|
||||
- `kb-pipeline` possède l'orchestration générique du backfill, de l'extraction Core, du replay, des corrélations stateful, du préflight, de la préparation, de la simulation, de la soumission autorisée, de la confirmation, de la postvalidation et de la matérialisation idempotente.
|
||||
- `kb-pipeline` ne doit contenir ni wallet, mint, compte, airdrop, autorité, adresse, séquence ou hypothèse codée en dur pour une démonstration Devnet ou Testnet.
|
||||
- `kb-pipeline-demo-scenarios` contient les fixtures, aides de campagne et tests automatisés spécifiques aux réseaux de test, actuellement Devnet ou Testnet.
|
||||
- Les scénarios UI Devnet/Testnet restent dans `kb-app-demo-desktop`. Ils ne doivent pas être déplacés vers `kb-pipeline-demo-scenarios` au seul motif qu'un scénario automatisé équivalent est souhaité.
|
||||
- Lorsqu'un parcours UI doit être couvert automatiquement, `kb-pipeline-demo-scenarios` ajoute en parallèle un test ou une campagne équivalente fondée sur les mêmes APIs généralistes. Cette couverture parallèle complète la démonstration desktop ; elle ne la remplace pas.
|
||||
- `kb-pipeline-demo-scenarios` peut préparer des wallets temporaires, demander des airdrops, créer des actifs de test, enchaîner plusieurs appels du pipeline généraliste et produire des preuves de validation réseau.
|
||||
- Le binaire `kb-pipeline-demo-scenarios-cli` reste un outil ciblé tant que son contrat public ne prévoit pas explicitement d'autres commandes. Son usage historique de préparation des fixtures SPL Token-2022 ne doit pas être généralisé implicitement à tous les scénarios.
|
||||
- `kb-pipeline-demo-scenarios` dépend de `kb-pipeline` ; la dépendance inverse est interdite.
|
||||
- Une primitive ou orchestration réellement réutilisable hors d'un scénario UI ou d'une campagne de validation précise doit être placée dans `kb-pipeline` ou la crate métier propriétaire. Les adaptateurs, états et séquences propres aux démonstrations UI restent dans le desktop.
|
||||
- Les scénarios Mainnet sans écriture, par exemple les validations de backfill ou de replay, relèvent du pipeline généraliste et de documents de validation dédiés ; ils ne justifient pas l'introduction d'une logique Mainnet spécifique dans la crate de scénarios Devnet/Testnet.
|
||||
|
||||
### Autres frontières
|
||||
|
||||
- `kb-store` possède les contrats de persistance neutres et les adaptateurs de base de données.
|
||||
- PostgreSQL est l'adaptateur de production de `kb-store`.
|
||||
- Un futur adaptateur SQLite doit rester interne à `kb-store` et limité aux tests, imports et corpus locaux.
|
||||
@@ -182,9 +219,7 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
|
||||
- Les garde-fous communs doivent être placés dans les modules de sécurité partagés de `kb-lib`.
|
||||
- Aucun exécuteur ne doit envoyer de transaction sans simulation et validation explicite.
|
||||
- Les surfaces non classifiées ne doivent pas avoir de crate exécuteur.
|
||||
- Pour chaque programme Solana et contrairement aux décodeurs, les exécuteurs ne construisent pas les opérations obsolètes ou purement historiques. Ils couvrent uniquement les opérations courantes et expérimentales officiellement constructibles, avec un statut exact `Supported` ou `Unsupported(reason)`.
|
||||
- Le statut expérimental, récent ou non encore déployé partout n'interdit pas un builder universel lorsqu'un wire officiel exact existe. Le déploiement, la simulation et l'autorisation d'envoi restent trois décisions séparées ; la bibliothèque ne doit pas imposer artificiellement un cluster.
|
||||
|
||||
- La section « Couverture des exécuteurs » ci-dessus est normative pour chaque surface : la migration fonctionnelle doit fermer l’inventaire complet et ne peut pas sélectionner arbitrairement un sous-ensemble d’opérations officiellement constructibles.
|
||||
|
||||
- Les champs JSON exposés à TypeScript ne doivent pas utiliser directement `serde_json::Value` avec `TS-rs`; utiliser une chaîne JSON sérialisée (`std::string::String`) ou un type Rust typé exportable.
|
||||
- Les APIs qui gardent des payloads dynamiques doivent fournir des helpers explicites basés sur `serde_json::to_string` et `serde_json::to_string_pretty`.
|
||||
|
||||
Reference in New Issue
Block a user