v0.2.0-pre.1
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 24 -->
|
||||
<!-- version: 25 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -14,7 +14,8 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
|
||||
- [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.1`, établi par `0.1.1-pre.001` puis consolidé jusqu'à `0.1.1-rel.001`.
|
||||
- [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.2`, établi par `0.1.2-pre.001` puis consolidé jusqu'à `0.1.2-rel.001`.
|
||||
- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, exécuté jusqu'à `pre.015` puis publié par `0.1.3-rel.001`.
|
||||
- [`006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](006-V0_1_4_CONFIG_DESKTOP_PLAN.md) — plan actif de `0.1.4 — ksp-app-config-desk`, établi par `0.1.4-pre.001` avant toute implémentation Tauri fonctionnelle.
|
||||
- [`006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](006-V0_1_4_CONFIG_DESKTOP_PLAN.md) — plan historique clôturé de la release stable `0.1.4 — ksp-app-config-desk`, établi par `0.1.4-pre.001` puis consolidé jusqu'à `0.1.4-rel.001`.
|
||||
- [`007-V0_2_0_SERIES_PLANNING.md`](007-V0_2_0_SERIES_PLANNING.md) — plan actif de `0.2.0`, ouvert par `0.2.0-pre.001` pour auditer `khadhroony-bot3` et découper le reste de `0.2.x` sans implémentation N2 prématurée.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 25 -->
|
||||
<!-- version: 26 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -466,3 +466,5 @@ La série `0.2.0` doit notamment produire :
|
||||
|
||||
Le document directeur attendu pour cette session est `docs/plans/007-V0_2_0_SERIES_PLANNING.md`. Les numéros et périmètres des releases `0.2.1+` ne deviennent contractuels qu'après validation de ce plan.
|
||||
|
||||
`0.2.0-pre.001` a ouvert ce document avec la méthode d'audit, une première cartographie et une matrice provisoire. Les lots Wallet, Transport, Interface, Program et Execution restent volontairement non numérotés à ce stade ; les audits spécialisés suivants doivent encore challenger leur ordre et leur taille.
|
||||
|
||||
|
||||
589
docs/plans/007-V0_2_0_SERIES_PLANNING.md
Normal file
589
docs/plans/007-V0_2_0_SERIES_PLANNING.md
Normal file
@@ -0,0 +1,589 @@
|
||||
<!-- file: docs/plans/007-V0_2_0_SERIES_PLANNING.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Plan `0.2.0` — audit bot3 et planification de la série `0.2.x`
|
||||
|
||||
## 1. Statut, base et objectif
|
||||
|
||||
Ce document ouvre `0.2.0` avec `0.2.0-pre.001`.
|
||||
|
||||
`0.2.0` est une release intermédiaire de transition, d'audit et de planification. Elle ne livre pas de capacité Solana N2 fonctionnelle. Son résultat attendu est un cadrage suffisamment étayé pour découper le reste de `0.2.x` en releases concrètes et bornées sans reproduire mécaniquement l'architecture historique de `khadhroony-bot3`.
|
||||
|
||||
Base KSP fournie :
|
||||
|
||||
```text
|
||||
khadhroony-solana-project v0.1.4
|
||||
workspace.package.version = 0.1.4
|
||||
```
|
||||
|
||||
Snapshot bot3 audité :
|
||||
|
||||
```text
|
||||
archive d'échange : khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||||
workspace.package.version = 0.5.3-pre.5
|
||||
```
|
||||
|
||||
L'archive bot3 ne porte pas de métadonnée Git permettant de vérifier ici le commit correspondant au suffixe d'échange `fix010`. L'audit se fonde sur le contenu effectivement fourni.
|
||||
|
||||
Les fondations déjà stabilisées par KSP en `0.1.x` ne sont pas remigrées :
|
||||
|
||||
- `ksp-core-lib` ;
|
||||
- `ksp-logging-lib` ;
|
||||
- `ksp-config-lib` ;
|
||||
- `ksp-app-config-desk`.
|
||||
|
||||
Elles constituent des contraintes de jugement des composants historiques.
|
||||
|
||||
## 2. Principes de l'audit
|
||||
|
||||
### 2.1 Ne pas confondre cinq objets différents
|
||||
|
||||
Chaque élément bot3 doit être séparé en cinq dimensions avant décision :
|
||||
|
||||
1. **fonctionnalité** — besoin utilisateur ou système réellement utile ;
|
||||
2. **implémentation historique** — code, algorithme, organisation de modules et choix techniques utilisés dans bot3 ;
|
||||
3. **contrat public** — types, traits, invariants et comportements observables dont des consommateurs peuvent réellement dépendre ;
|
||||
4. **dépendance externe** — crate ou protocole tiers utilisé pour réaliser le contrat ;
|
||||
5. **convention de projet** — règle locale de nommage, validation, documentation ou composition qui peut être historique sans être intrinsèque à la fonctionnalité.
|
||||
|
||||
Une décision de reprise porte d'abord sur la fonctionnalité et le contrat utile. Elle ne vaut jamais autorisation implicite de copier le code ou son graphe de dépendances.
|
||||
|
||||
### 2.2 Statuts de décision
|
||||
|
||||
Chaque capacité significative reçoit l'un des statuts suivants.
|
||||
|
||||
#### `reprendre`
|
||||
|
||||
Le besoin et l'essentiel du contrat sont adaptés à KSP. L'implémentation peut néanmoins être réécrite, revalidée ou simplifiée.
|
||||
|
||||
#### `adapter`
|
||||
|
||||
Le besoin reste valable mais son API, son ownership, sa composition, ses DTOs ou une partie de ses invariants doivent être alignés sur KSP.
|
||||
|
||||
#### `refondre`
|
||||
|
||||
Le besoin demeure utile mais l'architecture historique ou les couplages sont incompatibles avec les frontières KSP ; une nouvelle conception est nécessaire avant implémentation.
|
||||
|
||||
#### `abandonner`
|
||||
|
||||
L'élément est legacy, redondant, hors objectif, dangereux ou remplacé par une capacité KSP déjà stabilisée.
|
||||
|
||||
#### `ajouter`
|
||||
|
||||
Le besoin est requis par les objectifs KSP mais bot3 ne fournit pas de contrat suffisant ou n'offre pas cette capacité.
|
||||
|
||||
### 2.3 Critères appliqués à chaque décision
|
||||
|
||||
La décision est évaluée avec les critères suivants :
|
||||
|
||||
- utilité concrète pour les cas d'usage KSP ;
|
||||
- cohérence avec les niveaux N1/N2/N3/N4 ;
|
||||
- ownership unique Config/Logging/Wire/Program/Execution ;
|
||||
- stabilité et ouverture du contrat public ;
|
||||
- séparation secret/public ;
|
||||
- indépendance vis-à-vis de Tauri ;
|
||||
- respect du firewall des dépendances externes ;
|
||||
- compatibilité avec les versions récentes des primitives/codecs ;
|
||||
- testabilité hors UI ;
|
||||
- observabilité via `ksp-logging-lib` ;
|
||||
- comportement async/concurrence ;
|
||||
- capacité d'évolution sans enum centrale ou couplage protocolaire fermé ;
|
||||
- dette connue, code legacy ou duplication ;
|
||||
- coût réel de réimplémentation contre valeur du contrat.
|
||||
|
||||
## 3. Méthode d'analyse
|
||||
|
||||
L'audit est mené par domaine et non par ordre historique des crates.
|
||||
|
||||
Pour chaque capacité :
|
||||
|
||||
1. localiser les crates, modules, applications et documents sources ;
|
||||
2. relever les APIs publiques et DTOs réellement consommables ;
|
||||
3. relever les dépendances Cargo directes et les dépendances fonctionnelles implicites ;
|
||||
4. relever Config, environnement, secrets et paramètres runtime nécessaires ;
|
||||
5. relever les usages directs de `tracing` et les exigences d'observabilité ;
|
||||
6. relever tests, scénarios, matrices et invariants de sécurité ;
|
||||
7. identifier les couplages historiques et duplications ;
|
||||
8. comparer avec les règles KSP stabilisées ;
|
||||
9. produire une ligne de matrice de décision ;
|
||||
10. relier la capacité au graphe de dépendances `0.2.x` ;
|
||||
11. seulement ensuite proposer un lot/release candidate.
|
||||
|
||||
La fiche d'audit canonique utilise la forme :
|
||||
|
||||
```text
|
||||
capacité / contrat
|
||||
source bot3
|
||||
fonctionnalité
|
||||
contrat public utile
|
||||
implémentation historique notable
|
||||
dépendances externes
|
||||
configuration / environnement
|
||||
logging / tracing
|
||||
scénarios / tests / invariants
|
||||
statut : reprendre | adapter | refondre | abandonner | ajouter
|
||||
justification
|
||||
propriétaire KSP pressenti
|
||||
dépendances KSP
|
||||
risques / dette à éviter
|
||||
release 0.2.x candidate non figée
|
||||
```
|
||||
|
||||
## 4. Cartographie initiale de bot3
|
||||
|
||||
Cette section est volontairement un inventaire de départ. Elle sera complétée par les prereleases d'audit spécialisées.
|
||||
|
||||
### 4.1 Crates de fondation historiques
|
||||
|
||||
| Source bot3 | Rôle historique | Décision de `pre.001` |
|
||||
|------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `ks-core` | erreurs/primitives minimales | ne pas remigrer ; comparer seulement les anciens consommateurs avec `ksp-core-lib` |
|
||||
| `ks-program-ids` | registre de Program IDs | abandonner comme composant KSP séparé ; ownership déjà repris par `ksp-core-lib` |
|
||||
| `ks-config` | documents Config, environnement, profils | ne pas remigrer ; ses anciens documents Wallet/Transport/Execution servent d'entrée d'audit pour de futures extensions de `ksp-config-lib` |
|
||||
| `ks-logging` | runtime tracing | ne pas remigrer ; tous les appels directs `tracing` des capacités historiques devront passer par `ksp-logging-lib` |
|
||||
|
||||
### 4.2 Wallet
|
||||
|
||||
Sources principales :
|
||||
|
||||
```text
|
||||
ks-wallet/
|
||||
ks-wallet-demo-scenarios/
|
||||
kb-app-demo-desktop/src/demo_wallet.rs
|
||||
ks-config/src/wallet.rs
|
||||
docs/NATIVE_FORMAT.md
|
||||
docs/WALLET_FORMAT_COMPATIBILITY.md
|
||||
docs/guides/WALLETS.md
|
||||
docs/validation/V0_5_2_WALLET_VALIDATION_REPORT.md
|
||||
```
|
||||
|
||||
Le Wallet bot3 est une surface relativement mature. L'inventaire initial identifie :
|
||||
|
||||
- alias validé ;
|
||||
- identité publique minimale sans secret ;
|
||||
- wallet temporaire en mémoire ;
|
||||
- manager multi-wallet borné à une racine ;
|
||||
- handle opaque de fichier wallet ;
|
||||
- format natif versionné `.kswallet` ;
|
||||
- Argon2id + XChaCha20-Poly1305 ;
|
||||
- mot de passe possédé, non clonable et redacted ;
|
||||
- capacité `UnlockedWallet` non clonable ;
|
||||
- signature sans getter public des octets privés ;
|
||||
- création atomique/no-clobber du format natif ;
|
||||
- changement de mot de passe sans changement de keypair ;
|
||||
- inspection externe sans import ;
|
||||
- migration legacy JSON non destructive ;
|
||||
- import/export `SolanaCliJson` 64 octets ;
|
||||
- import/export Base58 du keypair Solana complet 64 octets ;
|
||||
- détection de collisions d'alias/pubkey ;
|
||||
- validation indépendante de Tauri via `ks-wallet-demo-scenarios`.
|
||||
|
||||
Dette/éléments à ne pas reprendre tels quels :
|
||||
|
||||
- `TemporaryWalletStore` persiste encore un format JSON legacy et n'offre pas la même publication crash-safe que le format natif ;
|
||||
- `WalletPolicy` contient un `lamport_spend_limit` qui relève conceptuellement de la policy d'exécution supérieure, pas du stockage/secret wallet ;
|
||||
- la crate appelle directement `tracing` ;
|
||||
- les types `solana-keypair`/`solana-signer` font partie du contrat historique et doivent être réévalués contre la politique de primitives KSP, pas repris automatiquement ;
|
||||
- la fenêtre Wallets du desktop mélange inventaire wallet, RPC, balances, comptes token, transactions et sélection d'exécution ; KSP doit séparer application wallet et validation transport/execution selon les responsabilités réelles.
|
||||
|
||||
### 4.3 Transport on-chain
|
||||
|
||||
Sources principales :
|
||||
|
||||
```text
|
||||
ks-onchain-transport/
|
||||
ks-config/src/transport.rs
|
||||
kb-app-demo-desktop/src/demo_http.rs
|
||||
kb-app-demo-desktop/src/demo_ws.rs
|
||||
kb-app-demo-desktop/src/demo_transport.rs
|
||||
```
|
||||
|
||||
La crate historique contient 23 fichiers Rust et 124 tests annotés dans le snapshot fourni. Elle couvre notamment :
|
||||
|
||||
- JSON-RPC 2.0 ;
|
||||
- clients HTTP et WebSocket ;
|
||||
- pools d'endpoints ;
|
||||
- rôles, priorités, quotas et concurrence ;
|
||||
- timeouts ;
|
||||
- sessions WebSocket ;
|
||||
- subscribe/unsubscribe ;
|
||||
- reconnect borné ;
|
||||
- snapshots de session et événements ;
|
||||
- catalogue de méthodes HTTP standard ;
|
||||
- catalogue de subscriptions WS standard ;
|
||||
- typed requests/configs pour comptes, blocs, cluster, économie, tokens et transactions ;
|
||||
- méthodes techniques utiles à l'exécution : blockhash, fee, simulation, send, status/confirmation, airdrop ;
|
||||
- adaptation de `getSignaturesForAddress` et `getTransaction`.
|
||||
|
||||
Écarts déjà identifiés :
|
||||
|
||||
- les clients publics consomment directement des types `ks-config` ;
|
||||
- `SolanaRpcClient` dépend d'un type `ks_lib::MdSignature` ;
|
||||
- l'adaptation `getTransaction` produit directement `ks_lib::MdCanonicalTransaction` ;
|
||||
- la crate appelle directement `tracing` ;
|
||||
- les modèles transport, modèles canoniques Core et responsabilités d'exécution technique sont partiellement entremêlés ;
|
||||
- le découpage KSP exige des modèles homogènes possédés par le transport, indépendants du futur Store et du Program processing.
|
||||
|
||||
Le besoin transport est donc clairement à reprendre, mais la frontière publique doit être auditée avant toute migration.
|
||||
|
||||
### 4.4 Interface/wire
|
||||
|
||||
Bot3 ne possède pas une crate `ks-interface` dédiée. Les contrats wire sont dispersés principalement dans `ks-lib` et dans ses dépendances externes.
|
||||
|
||||
Le manifest bot3 montre notamment des dépendances directes à :
|
||||
|
||||
- interfaces Solana/Anza ;
|
||||
- interfaces SPL ;
|
||||
- `mpl-token-metadata` ;
|
||||
- `borsh` 1.x et un alias `borsh_0_10` ;
|
||||
- `wincode` ;
|
||||
- primitives Solana diverses.
|
||||
|
||||
`ks-lib` contient dans le snapshot fourni 188 fichiers sous `src/decoder/`, dont des modules `wire.rs`, `state.rs`, payloads, adapters et code de décodage. Cette organisation est une source d'inventaire, pas un modèle cible.
|
||||
|
||||
KSP exige que :
|
||||
|
||||
- `ksp-interface-lib` possède/réexporte le wire officiel nécessaire ;
|
||||
- les codecs wire y soient confinés lorsqu'ils servent au protocole ;
|
||||
- les dépendances protocole externes remplaçables ne forcent pas des générations anciennes ;
|
||||
- `ksp-program-lib` consomme des contrats typés au lieu de redécoder directement le wire ;
|
||||
- Metaplex Token Metadata et certaines interfaces SPL puissent être réimplémentés de manière compatible plutôt qu'importés comme dépendances runtime.
|
||||
|
||||
L'audit Interface doit donc être mené par **contrat wire utilisé**, pas par copie des modules `ks-lib`.
|
||||
|
||||
### 4.5 Program API / Program
|
||||
|
||||
Sources principales :
|
||||
|
||||
```text
|
||||
ks-lib/src/decoder/api/
|
||||
ks-lib/src/decoder/**
|
||||
ks-lib/src/executor/api/
|
||||
ks-lib/src/executor/**
|
||||
ks-lib/tests/external_decoder_api.rs
|
||||
ks-lib/tests/external_executor_api.rs
|
||||
```
|
||||
|
||||
Bot3 possède déjà des idées utiles :
|
||||
|
||||
- identité/descripteur de decoder ;
|
||||
- déclaration de couverture ;
|
||||
- reconnaissance compatible/incompatible ;
|
||||
- diagnostics et preuves ;
|
||||
- outcome explicite ;
|
||||
- trait de decoder d'instruction ;
|
||||
- capacités d'exécution ;
|
||||
- plan préparé ;
|
||||
- comptes et signers requis ;
|
||||
- politiques de cluster/simulation/blockhash/coûts ;
|
||||
- traits d'executor typé et générique.
|
||||
|
||||
Mais `ks-lib` regroupe decoder, executor et materializer dans une seule crate, avec 477 fichiers Rust dans le snapshot fourni. KSP a déjà décidé de séparer :
|
||||
|
||||
```text
|
||||
ksp-interface-lib
|
||||
ksp-program-api
|
||||
ksp-program-lib
|
||||
ksp-execution-policy-api
|
||||
ksp-execution-lib
|
||||
ksp-materializer-api / lib plus tard
|
||||
```
|
||||
|
||||
Les traits `DcApi*` / `ExApi*` sont donc des sources de concepts et de tests de compatibilité, pas des contrats à recopier.
|
||||
|
||||
### 4.6 Pipeline et execution historique
|
||||
|
||||
`ks-pipeline` orchestre dans bot3 backfill, Core extraction, replay, stateful processing, preflight et execution. Ce regroupement n'est pas retenu par KSP.
|
||||
|
||||
Pour `0.2.x`, seules les parties utiles à la future frontière Program/policy/execution doivent être étudiées. Les responsabilités Store, materialization, replay et workers restent hors périmètre et appartiennent à `0.3.x+`.
|
||||
|
||||
Point important : les opérations techniques `simulateTransaction`, `sendTransaction`, blockhash, fee et signature status peuvent rester des capacités du transport, tandis que le lifecycle « préparer -> policy -> blockhash -> signer -> simuler -> envoyer -> confirmer -> valider » appartient à `ksp-execution-lib` lorsque le premier scénario réel le justifie.
|
||||
|
||||
### 4.7 Scénarios et demos
|
||||
|
||||
Sources principales :
|
||||
|
||||
```text
|
||||
ks-wallet-demo-scenarios/
|
||||
ks-pipeline-demo-scenarios/
|
||||
kb-app-demo-desktop/
|
||||
```
|
||||
|
||||
Éléments positifs :
|
||||
|
||||
- scénario wallet réutilisable hors Tauri ;
|
||||
- campagnes Devnet spécialisées ;
|
||||
- fixtures contractuelles ;
|
||||
- validations de postconditions ;
|
||||
- séparation progressive entre logique réutilisable et DTO/UI desktop.
|
||||
|
||||
Éléments à corriger dans KSP :
|
||||
|
||||
- `ks-pipeline-demo-scenarios` reste très large et regroupe plusieurs domaines ;
|
||||
- il dépend directement de nombreuses crates Solana/SPL/Metaplex ;
|
||||
- `kb-app-demo-desktop` reste une application omnibus ;
|
||||
- certaines responsabilités ont historiquement été dupliquées entre desktop et scénarios.
|
||||
|
||||
KSP conserve le principe de validation réutilisable, mais avec des crates `ksp-scenario-<domain>-lib` et des applications spécialisées minces lorsque le scénario le justifie.
|
||||
|
||||
### 4.8 Off-chain
|
||||
|
||||
Aucune crate off-chain générale n'existe dans le snapshot bot3. Les documents bot3 indiquent explicitement que la résolution off-chain Metadata avait été reportée.
|
||||
|
||||
Il n'existe donc rien à migrer ici. `ksp-offchain-transport-lib` reste `need-driven` et sera classé `ajouter` seulement lorsqu'un premier besoin réel de `0.2.x` ou d'une série suivante l'exigera.
|
||||
|
||||
## 5. Première matrice de décision
|
||||
|
||||
Les décisions ci-dessous sont **provisoires**. Elles servent à orienter les audits spécialisés et ne figent aucun numéro `0.2.1+`.
|
||||
|
||||
| Capacité / contrat | Source bot3 | Statut initial | Justification | Propriétaire KSP pressenti | Dépendances / risques | Release candidate non figée |
|
||||
|----------------------------------------------------|---------------------------------------------------|----------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------|----------------------------------------------|
|
||||
| identité/alias wallet public | `ks-wallet::WalletAlias`, `WalletIdentity` | reprendre | contrat non secret utile et simple | `ksp-wallet-lib` | aligner erreurs/types Core | `0.2.x — lot Wallet` |
|
||||
| password possédé/redacted | `WalletPassword` | reprendre | invariant sécurité utile | `ksp-wallet-lib` | zeroization, pas de serde/clone | `0.2.x — lot Wallet` |
|
||||
| capacité wallet unlocked non clonable | `UnlockedWallet` | adapter | bonne frontière secret/signature, API externe à réévaluer | `ksp-wallet-lib` | primitives signer/keypair, lifetime mémoire | `0.2.x — lot Wallet` |
|
||||
| format natif `.kswallet` v1 | `ks-wallet/native.rs`, `NATIVE_FORMAT.md` | adapter | format versionné et authentifié utile ; doit être revalidé pour KSP | `ksp-wallet-lib` | compatibilité bot3, crypto, migration | `0.2.x — lot Wallet` |
|
||||
| création native atomique/no-clobber | `WalletManager::create` | reprendre | invariant de persistence utile | `ksp-wallet-lib` | filesystem/permissions/concurrence | `0.2.x — lot Wallet` |
|
||||
| scan/lookup borné | `WalletManager` | reprendre | limite de confiance claire | `ksp-wallet-lib` | symlinks/permissions à réauditer | `0.2.x — lot Wallet` |
|
||||
| import/export Solana CLI JSON + Base58 64 octets | `transfer.rs` | adapter | formats utiles mais secrets explicitement privilégiés | `ksp-wallet-lib` + app DTO | confirmations UI, path policy, zeroization | `0.2.x — lot Wallet/app` |
|
||||
| migration legacy JSON | `migrate_legacy` | adapter | utile si compatibilité bot3 réellement requise | `ksp-wallet-lib` | ne pas faire du legacy le format normal | `0.2.x — lot Wallet` |
|
||||
| `TemporaryWalletStore` JSON legacy | `wallet.rs` | abandonner | persistence historique plus faible et redondante | aucun | éviter deux stores secrets concurrents | `0.2.x — aucun` |
|
||||
| `WalletPolicy::lamport_spend_limit` | `wallet.rs` | refondre | policy métier mal placée dans Wallet | `ksp-execution-policy-api` ou policy de scenario | ne pas coupler secrets et safety | `0.2.x — lot Execution si nécessaire` |
|
||||
| document Config wallet | `ks-config/src/wallet.rs` | adapter | besoin de racine/profil/alias, mais Config KSP est déjà propriétaire | `ksp-config-lib` | aucun secret/mot de passe | même release que premier besoin Wallet |
|
||||
| app Wallet spécialisée | panneau `demo_wallet.rs` | refondre | bot3 mélange Wallet/RPC/execution ; KSP veut une app spécialisée | `ksp-app-wallet-desk` | DTO applicatifs, Config Desk comme référence | `0.2.x — lot Wallet app` |
|
||||
| scénario lifecycle Wallet | `ks-wallet-demo-scenarios` | adapter | validation hors Tauri utile | `ksp-scenario-wallet-lib` si le workflow justifie une crate | ne pas créer une API scénario générique | `0.2.x — avec Wallet/app` |
|
||||
| JSON-RPC HTTP générique | `ks-onchain-transport` | adapter | capacité fondamentale | `ksp-onchain-transport-lib` | reqwest, erreurs KSP, Logging | `0.2.x — lot Transport` |
|
||||
| sessions/subscriptions WS | `WsSession`, `standard_ws` | adapter | besoin acquisition/demos futur | `ksp-onchain-transport-lib` | reconnect, backpressure, cancellation | `0.2.x — lot Transport` |
|
||||
| pools/rôles/quota endpoints | `HttpEndpointPool`, `WsEndpointPool`, role config | adapter | utile pour providers multiples | `ksp-onchain-transport-lib` + Config adapter | éviter API publique dépendante de shape Config | `0.2.x — lot Transport` |
|
||||
| typed standard RPC contracts | `standard_http*`, `standard_ws` | reprendre | couverture et tests constituent une bonne référence | `ksp-onchain-transport-lib` | vérifier conformité RPC actuelle | `0.2.x — lot Transport par surfaces bornées` |
|
||||
| modèles techniques simulation/send/status | `execution_rpc.rs` | adapter | nécessaires au transport d'exécution, pas à la policy | `ksp-onchain-transport-lib` | lifecycle supérieur hors transport | `0.2.x — Transport puis Execution` |
|
||||
| `getTransaction -> ks_lib::MdCanonicalTransaction` | `get_transaction.rs` | refondre | dépendance Transport -> monolithe métier interdite | `ksp-onchain-transport-lib` pour acquisition homogène ; futur Core processing ailleurs | frontière raw/canonical à redéfinir | `0.2.x — lot Transport` |
|
||||
| `SolanaRpcClient` utilisant `ks_lib::MdSignature` | `client.rs` | refondre | contrat transport ne doit pas dépendre de Program/lib historique | `ksp-onchain-transport-lib` | choisir primitive/DTO transport minimal | `0.2.x — lot Transport` |
|
||||
| wire Solana/SPL officiel | dépendances + modules `ks-lib` | adapter | besoin certain mais ownership change | `ksp-interface-lib` | générations codecs/primitives | `0.2.x — lot Interface` |
|
||||
| wire Metaplex runtime via `mpl-token-metadata` | `ks-lib` | refondre | contraire à la politique KSP déjà décidée | `ksp-interface-lib` | compatibilité wire à prouver | `0.2.x/0.4.x selon première surface` |
|
||||
| double génération Borsh historique | `borsh_0_10` + `borsh` | abandonner comme stratégie cible | dette historique à ne pas institutionnaliser | `ksp-interface-lib` | audit `cargo tree -d` au premier wire réel | `0.2.x — lot Interface` |
|
||||
| contrats decoder ouverts | `decoder/api` | adapter | concepts utiles mais noms/types/ownership à redéfinir | `ksp-program-api` | extensibilité/persistabilité | `0.2.x — lot Program API` |
|
||||
| implementations decoder | `decoder/**` | refondre par surfaces | aucune migration massive ; seulement premiers besoins réels | `ksp-program-lib` | dépend de `ksp-interface-lib` | `0.2.x puis 0.4.x+` |
|
||||
| executor bot3 | `executor/**` | refondre | KSP remplace l'idée d'executor programme par `ProgramExecutionPreparer` | `ksp-program-api` + `ksp-program-lib` | aucune signature/RPC/policy dans Program | `0.2.x — lot Program` |
|
||||
| policy d'exécution | `ExApiExecutionPolicy`, pipeline preflight | refondre | les règles utiles sont dispersées entre executor/pipeline/config | `ksp-execution-policy-api` | ne créer qu'au premier scenario réel | `0.2.x — conditionnel` |
|
||||
| orchestration d'exécution | `ks-pipeline` | refondre | pipeline monolithique non retenu | `ksp-execution-lib` | Wallet + Transport + Program API + policy | `0.2.x — conditionnel` |
|
||||
| `ks-pipeline` comme crate monolithique | `ks-pipeline` | abandonner | explicitement contraire au découpage KSP | aucun | extraire seulement concepts utiles | `0.2.x — aucun` |
|
||||
| scenario crate multi-domaines | `ks-pipeline-demo-scenarios` | refondre | validation utile, granularité/dep firewall incorrects | `ksp-scenario-<domain>-lib` | pas de dépendances Solana directes depuis scénario | `0.2.x selon scenario` |
|
||||
| desktop demo omnibus | `kb-app-demo-desktop` | abandonner comme modèle cible | Config Desk a déjà établi la référence Tauri spécialisée | apps spécialisées | éviter agrégation progressive | `0.2.x — aucun` |
|
||||
| transport off-chain général | absent/reporté | ajouter conditionnellement | bot3 ne le fournit pas ; KSP le veut seulement au besoin | `ksp-offchain-transport-lib` | ne pas introduire par anticipation | à décider au premier besoin réel |
|
||||
|
||||
## 6. Écarts KSP déjà confirmés
|
||||
|
||||
### 6.1 Config
|
||||
|
||||
Les documents historiques `wallet.config.json`, `transport.config.json` et `execution.config.json` ne doivent pas être copiés comme sous-système Config parallèle.
|
||||
|
||||
Lorsqu'une capacité `0.2.x` a besoin d'un document :
|
||||
|
||||
- le document est enregistré dans `ksp-config-lib` ;
|
||||
- schema, profils, environnement, sensibilité et persistence restent gérés par `ksp-config-lib` ;
|
||||
- la bibliothèque fonctionnelle reçoit un settings/runtime model adapté sans parser elle-même `.env` ou les fichiers Config ;
|
||||
- aucun mot de passe ou keypair wallet n'est persisté dans Config.
|
||||
|
||||
### 6.2 Logging
|
||||
|
||||
Les appels `tracing::*` directs de bot3 sont des implémentations historiques.
|
||||
|
||||
Les nouvelles crates KSP comportementales utilisent la façade `ksp-logging-lib`. Aucun composant Wallet, Transport, Program ou Scenario ne crée son propre subscriber/runtime.
|
||||
|
||||
### 6.3 Tauri
|
||||
|
||||
`kb-app-demo-desktop` ne sert plus de modèle architectural général. Le modèle de référence est `ksp-app-config-desk` : app mince, DTOs applicatifs, bridge Logging, modals Bootstrap, séparation services/commands, validations frontend/Tauri et build Tauri final en dernière opération.
|
||||
|
||||
### 6.4 Dépendances externes
|
||||
|
||||
La centralisation workspace est obligatoire. L'audit doit distinguer :
|
||||
|
||||
- primitives fondamentales explicitement autorisées ;
|
||||
- crates d'interface officielles réexportables ;
|
||||
- crates protocole à réimplémenter ;
|
||||
- codecs wire appartenant à Interface ;
|
||||
- dépendances purement test/conformité.
|
||||
|
||||
Aucune version upstream n'est figée dans `pre.001`; les versions seront vérifiées depuis les sources officielles au moment où un lot décide réellement d'introduire la dépendance.
|
||||
|
||||
### 6.5 Program / Execution
|
||||
|
||||
La frontière cible reste :
|
||||
|
||||
```text
|
||||
wire
|
||||
|
|
||||
v
|
||||
ksp-interface-lib
|
||||
|
|
||||
v
|
||||
ksp-program-api <---- implementation externe éventuelle
|
||||
^ |
|
||||
| v
|
||||
ksp-program-lib
|
||||
|
||||
PreparedProgramExecution
|
||||
|
|
||||
+--> policy explicite
|
||||
+--> wallet/signers
|
||||
+--> transport RPC
|
||||
v
|
||||
ksp-execution-lib
|
||||
```
|
||||
|
||||
Program prépare techniquement ; Execution orchestre ; Policy autorise/refuse/contraint ; Wallet détient les secrets ; Transport réalise les appels réseau.
|
||||
|
||||
## 7. Graphe de dépendances fonctionnelles initial
|
||||
|
||||
Le graphe de départ est :
|
||||
|
||||
```text
|
||||
ksp-core-lib
|
||||
/ | \
|
||||
v v v
|
||||
ksp-config-lib | ksp-logging-lib
|
||||
| | |
|
||||
| | |
|
||||
v v v
|
||||
+-------------------------------+
|
||||
| |
|
||||
v v
|
||||
ksp-wallet-lib ksp-onchain-transport-lib
|
||||
| |
|
||||
| transport models
|
||||
| |
|
||||
| v
|
||||
| future acquisition consumers
|
||||
|
|
||||
| ksp-interface-lib
|
||||
| |
|
||||
| v
|
||||
| ksp-program-api
|
||||
| ^
|
||||
| |
|
||||
| ksp-program-lib
|
||||
| |
|
||||
+-------+--------+
|
||||
|
|
||||
v
|
||||
ksp-execution-policy-api [seulement si besoin réel]
|
||||
|
|
||||
v
|
||||
ksp-execution-lib [seulement si cycle réel]
|
||||
|
|
||||
v
|
||||
ksp-scenario-<domain>-lib
|
||||
|
|
||||
v
|
||||
app scenario spécialisée
|
||||
```
|
||||
|
||||
Relations importantes :
|
||||
|
||||
- Wallet, Transport et Interface peuvent commencer indépendamment ;
|
||||
- Program dépend d'Interface pour la première surface wire réelle ;
|
||||
- Execution dépend de Program API + Policy + Wallet + Transport ;
|
||||
- une app Wallet peut exister avant Program/Execution si elle valide le lifecycle Wallet sans exécuter de transaction ;
|
||||
- un scenario Transport peut valider HTTP/WS sans Store ;
|
||||
- Store/Materializer/worker restent exclus de `0.2.x` sauf découverte d'un contrat strictement nécessaire, qui devra alors être justifiée avant tout changement de roadmap.
|
||||
|
||||
## 8. Hypothèses de découpage du reste de `0.2.x`
|
||||
|
||||
`pre.001` ne fixe **aucun** numéro `0.2.1+`.
|
||||
|
||||
Les lots suivants sont uniquement des hypothèses à tester :
|
||||
|
||||
```text
|
||||
Lot A — Wallet foundation
|
||||
Lot B — Wallet specialized app + validation lifecycle
|
||||
Lot C — On-chain transport foundation
|
||||
Lot D — Transport validation/demo surfaces
|
||||
Lot E — Interface/wire foundation
|
||||
Lot F — Program API + first Program surface
|
||||
Lot G — Execution policy + execution orchestration, seulement si un premier scenario l'exige
|
||||
```
|
||||
|
||||
Deux ordres restent plausibles à ce stade :
|
||||
|
||||
```text
|
||||
A -> B -> C -> D -> E -> F -> G
|
||||
```
|
||||
|
||||
ou :
|
||||
|
||||
```text
|
||||
C -> D -> A -> B -> E -> F -> G
|
||||
```
|
||||
|
||||
Le choix dépendra notamment de :
|
||||
|
||||
- la maturité réellement récupérable du Wallet ;
|
||||
- la taille minimale cohérente du transport HTTP/WS ;
|
||||
- le premier cas d'usage Program retenu ;
|
||||
- la nécessité ou non d'un cycle d'exécution réel avant `0.3.x`/`0.4.x`.
|
||||
|
||||
Aucun numéro ne sera attribué tant que les audits Wallet, Transport, Interface et Program ne sont pas suffisamment complets.
|
||||
|
||||
## 9. Prévision souple des prereleases `0.2.0`
|
||||
|
||||
Prévision initiale :
|
||||
|
||||
```text
|
||||
pre.001 méthode d'audit + cartographie initiale + première matrice
|
||||
pre.002 audit Wallet + Config Wallet + app/scenario wallet
|
||||
pre.003 audit transport on-chain HTTP/WS + Config transport + modèles
|
||||
pre.004 audit Interface/wire + dépendances Solana/SPL/Metaplex + codecs
|
||||
pre.005 audit Program API/Program + decoder + ProgramExecutionPreparer
|
||||
pre.006 audit policy/execution + séparation transport/wallet/program + besoin réel
|
||||
pre.007 audit scenarios/demos + validation infrastructure + off-chain gaps
|
||||
pre.008 matrice consolidée + graphe final + découpage candidat 0.2.1+
|
||||
pre.009 challenge du découpage + missions/hors-scope/critères/prereleases par release
|
||||
pre.010 clôture : cohérence documentaire, nettoyage, prompt première release fonctionnelle
|
||||
```
|
||||
|
||||
Cette séquence peut être scindée ou réordonnée. En particulier, `pre.006` peut conclure que `ksp-execution-policy-api` / `ksp-execution-lib` doivent être reportés si aucun scénario `0.2.x` ne justifie encore leur implémentation.
|
||||
|
||||
## 10. Critères de clôture de `0.2.0`
|
||||
|
||||
`0.2.0` ne peut être clôturée que lorsque :
|
||||
|
||||
- les domaines Wallet, Transport, Interface, Program et Scenario ont un inventaire suffisant ;
|
||||
- policy/execution ont une décision explicite d'introduction ou de report ;
|
||||
- off-chain a une décision explicite `need-driven` ;
|
||||
- chaque capacité significative a un statut de matrice et une justification ;
|
||||
- les dépendances externes problématiques et doublons de générations sont identifiés ;
|
||||
- le graphe de dépendances cible est cohérent avec les règles KSP ;
|
||||
- le nombre et l'ordre des releases `0.2.1+` sont bornés par des missions concrètes ;
|
||||
- chaque release proposée possède mission, périmètre, hors-périmètre, dépendances, critères de clôture et estimation souple des prereleases ;
|
||||
- la première release fonctionnelle suivante est sélectionnée ;
|
||||
- son prompt de démarrage est préparé ;
|
||||
- les sujets non nécessaires sont reportés dans `docs/IDEAS.md` au lieu d'être introduits par anticipation.
|
||||
|
||||
## 11. Questions ouvertes après `pre.001`
|
||||
|
||||
Les questions suivantes structurent les audits suivants ; elles ne bloquent pas la clôture de `pre.001` :
|
||||
|
||||
1. Le format `.kswallet` bot3 doit-il être conservé byte-for-byte comme format KSP v1 compatible, ou KSP peut-il démarrer avec un nouveau magic/version et un import de compatibilité ?
|
||||
2. Quelle primitive de signer doit constituer le contrat public minimal de `ksp-wallet-lib` sans propager inutilement `solana-keypair` ?
|
||||
3. Les surfaces HTTP et WS de `ksp-onchain-transport-lib` tiennent-elles dans une même release bornée ou doivent-elles être séparées ?
|
||||
4. Quels modèles `getTransaction` sont réellement transport-level et lesquels appartiennent au futur Core processing ?
|
||||
5. Quelles interfaces Solana/SPL peuvent être réexportées directement et lesquelles doivent être possédées/réimplémentées par KSP ?
|
||||
6. Quel premier Program réel est le meilleur canari pour valider `ksp-interface-lib` + `ksp-program-api` + `ksp-program-lib` sans anticiper la grosse phase Core/SPL `0.4.x` ?
|
||||
7. Ce premier Program exige-t-il réellement un cycle d'exécution dans `0.2.x`, ou la préparation technique suffit-elle ?
|
||||
8. Une crate `ksp-scenario-wallet-lib` apporte-t-elle une valeur durable distincte des tests d'intégration Wallet et de `ksp-app-wallet-desk` ?
|
||||
9. Quel niveau de compatibilité opérateur avec les wallets/imports bot3 est réellement requis au démarrage de KSP ?
|
||||
|
||||
## 12. Hors périmètre de `pre.001`
|
||||
|
||||
Cette tranche ne :
|
||||
|
||||
- crée aucune nouvelle crate N2 ;
|
||||
- n'ajoute aucune dépendance Solana/SPL/Metaplex ;
|
||||
- ne copie aucun source bot3 ;
|
||||
- ne modifie aucun document Config runtime ;
|
||||
- ne crée aucun Store/Materializer/worker ;
|
||||
- ne fixe aucun numéro `0.2.1+` ;
|
||||
- ne sélectionne pas encore la première release fonctionnelle de la série ;
|
||||
- ne prétend pas avoir audité exhaustivement les 477 fichiers Rust de `ks-lib`.
|
||||
|
||||
Le prochain travail porte sur l'audit Wallet détaillé et la confirmation de ses contrats récupérables.
|
||||
Reference in New Issue
Block a user