v0.2.2-pre.001

deltas/0.2.2/pre.001.md

@@ -0,0 +1,180 @@
+<!-- file: deltas/0.2.2/pre.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.2-pre.001` — réaudit HTTP Accounts/Tokens/Cluster, DTOs et sizing
+
+## Base requise
+
+Release stable attendue :
+
+```text
+v0.2.1
+```
+
+L'archive KSP fournie porte `workspace.package.version = "0.2.1"`. Elle ne contient pas `.git`; le tag `v0.2.1` n'est donc pas revérifiable
+localement depuis le zip.
+
+## Objectif
+
+Exécuter la première tranche obligatoire de `0.2.2` sans implémentation fonctionnelle lourde : relire les contrats KSP, réauditer la surface
+HTTP Solana officielle actuelle, confirmer la matrice des 22 méthodes Accounts/Tokens/Cluster, cadrer les DTOs wire, évaluer les dépendances et
+trancher le gate de sizing.
+
+## Version Cargo
+
+Conformément à `VER-ID-009`, la prerelease non-fix synchronise le signal technique :
+
+```text
+0.2.1 -> 0.2.2-pre.1
+```
+
+Aucune source Rust, dépendance Cargo ou configuration runtime n'est modifiée dans cette tranche.
+
+## Résultats principaux
+
+- index HTTP Solana courant réaudité : **52 méthodes** ;
+- navigation Deprecated officielle : **14 méthodes historiques**, inchangées ;
+- familles de la release : Accounts `6 = 1 acquis + 5 ciblés`, Tokens `5 = 5 ciblés`, Cluster `15 = 3 acquis + 12 ciblés` ;
+- aucune méthode ajoutée/supprimée/déplacée détectée depuis l'audit `0.2.1` du 2026-08-17 ;
+- les 22 méthodes ciblées restent des méthodes courantes non marquées Deprecated/Unstable et les descriptors KSP restent `Read + RetrySafe` ;
+- `getMultipleAccounts` conserve la limite documentée de 100 adresses ;
+- `getSlotLeaders` conserve la limite documentée `1..=5000` ;
+- `getLargestAccounts` et `getProgramAccounts` documentent toujours `sortResults` ;
+- `getProgramAccounts` conserve sa réponse bare par défaut et contextualisée avec `withContext=true` ;
+- la source primaire Agave confirme trois filtres Program Accounts (`dataSize`, `memcmp`, `tokenAccountState`), 4 filtres max et 128 octets décodés max pour `memcmp` ;
+- le wire Account requiert une union pour `data`, y compris le fallback `jsonParsed -> [base64]`, et `space` reste nullable ;
+- `TokenAmount.uiAmount` reste nullable ;
+- `getHighestSnapshotSlot` conserve `incremental: null` et la source officielle Agave confirme une erreur `NoSnapshot` en absence de snapshot ;
+- `getLeaderSchedule` conserve son overload slot/config particulier ;
+- `getVoteAccounts` conserve `current/delinquent` et les epoch credits triples; la source Agave courante borne cet historique RPC à 5 entrées par validator.
+
+## Gate de sizing
+
+Question obligatoire :
+
+```text
+Les 22 wrappers typés + DTOs partagés + tests + documentation peuvent-ils être clôturés proprement dans cette session ?
+```
+
+Réponse :
+
+```text
+OUI.
+```
+
+Aucun split de release n'est nécessaire. Le plan conserve `0.2.2` à 22 méthodes et répartit le travail sur DTOs communs, Accounts, Tokens,
+Cluster simple, Cluster schedule/slot/vote puis clôture. Si une tranche réelle dépasse le budget KSP, elle sera scindée par une prerelease
+supplémentaire sans déplacer de méthode hors `0.2.2`.
+
+## Décisions prises
+
+- conserver exactement la partition `4 / 22 / 11 / 15` de `0.2.1`–`0.2.4` ;
+- ne pas reconstruire un transport par famille ; tous les wrappers passent par descriptor + `execute_standard_rpc` ;
+- mutualiser `SolanaCommitment` et `SolanaRpcContext` sans casser les réexports `0.2.1` ;
+- représenter Account data comme une forme wire discriminée, sans décodage Program/SPL ;
+- conserver `jsonParsed.parsed` comme `serde_json::Value` dans Transport ;
+- utiliser `ksp_core_lib::Pubkey` dans les DTOs publics, avec wire structs privés puis conversion explicite ;
+- représenter le selector Token comme une union exclusive `mint` / `programId` ;
+- représenter le résultat `getProgramAccounts` comme bare ou contextualisé selon `withContext` ;
+- conserver les endpoints de `getClusterNodes` comme chaînes wire optionnelles au contrat public ;
+- conserver les `null` documentés (`Account`, `space`, `uiAmount`, `transactionCount`, snapshot incremental, leader schedule) ;
+- ne pas modifier Config : le contrat `std.transport` existant suffit ;
+- ne pas ajouter `base64`, `bs58`, SPL, `solana-client` ou SDK RPC haut niveau à `pre.001`; les formes encodées `memcmp` peuvent rester des chaînes wire tant qu’aucun décodage local n’est requis.
+
+## Prévision de travail
+
+```text
+pre.001  audit officiel + matrice + DTOs + dépendances + sizing
+pre.002  primitives/configs/results partagés + fixtures de base
+pre.003  5 Accounts + tests
+pre.004  5 Tokens + tests
+pre.005  Cluster simple (7 méthodes) + tests
+pre.006  Cluster schedule/slot/vote (5 méthodes) + tests
+pre.007  canaries + smoke opt-in si utile + docs + prompt 0.2.3 + préparation stable
+```
+
+Une prerelease supplémentaire reste autorisée si le budget réel d'une tranche l'exige.
+
+## Fichiers ajoutés
+
+```text
+docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
+deltas/0.2.2/pre.001.md
+```
+
+## Fichiers modifiés
+
+```text
+Cargo.toml
+ROADMAP.md
+docs/000-README.md
+docs/plans/000-README.md
+docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
+```
+
+## Fichiers supprimés
+
+Aucun.
+
+## Fichiers volontairement inchangés
+
+```text
+CHANGELOG.md
+docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
+docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
+crates/ksp-onchain-transport-lib/src/**
+crates/ksp-onchain-transport-lib/unit_tests/**
+crates/ksp-onchain-transport-lib/tests/**
+crates/ksp-config-lib/src/transport.rs
+config/std.transport.json
+config/schemas/std.transport.schema.json
+```
+
+Les deltas `0.2.1` restent historiques et ne sont pas réécrits.
+
+## Validations exécutées
+
+- relecture des sources KSP obligatoires du prompt `0.2.2` ;
+- inspection de l'archive stable KSP fournie et de la foundation Transport `0.2.1` ;
+- confirmation locale que le registry assigne déjà exactement les 22 méthodes ciblées à `HttpRpcCoverageRelease::V0_2_2` ;
+- confirmation locale que ces 22 descriptors sont `Stable / Supported / Stable`, `Read`, `RetrySafe` ;
+- consultation de l'index HTTP Solana officiel courant et des 22 pages de méthodes ciblées ;
+- consultation de la navigation Deprecated officielle courante ;
+- consultation de `Solana RPC JSON Structures` pour Account data et TokenAmount ;
+- consultation des sources Agave `v3.1.8` liées par les pages officielles pour les ambiguïtés Account, filters/memcmp, cardinalités RPC, largest accounts, snapshot, leader schedule,
+  cluster node et vote accounts ;
+- contrôle documentaire de la matrice `52 current / 14 historical / 4+22+11+15` ;
+- contrôle de l'absence de nouvelle dépendance ou de besoin Config dans le design de `pre.001`.
+
+## Validations non exécutées
+
+Le sandbox courant ne fournit pas le binaire `cargo` (`command -v cargo` ne retourne aucun chemin). Les validations Cargo suivantes n'ont donc pas
+été exécutées ici et doivent être rejouées sur le checkout de développement avant commit :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-onchain-transport-lib
+```
+
+Aucun `cargo tree` n'est nécessaire dans cette tranche car aucune dépendance ni feature n'a changé. Les quatre vues `cargo tree` du prompt restent
+obligatoires dès qu'une prerelease change une dépendance/feature et à la clôture.
+
+L'archive KSP fournie ne contient pas `.git`; le commit attendu après application et validations suit `VER-GIT-001` :
+
+```text
+v0.2.2-pre.001
+```
+
+## Questions ouvertes
+
+Aucune question bloquante pour `pre.002`.
+
+Les détails exacts de nommage Rust des DTOs restent ajustables pendant leur implémentation, mais les invariants wire et frontières fixés par le
+plan `009` ne doivent pas être relâchés pour simplifier artificiellement les wrappers.
+
+## Suite
+
+`0.2.2-pre.002` : introduire les primitives/configs/results partagés, mutualiser Context/Commitment, fixer les conversions wire et installer les
+fixtures déterministes communes avant les wrappers Accounts.