diff --git a/Cargo.toml b/Cargo.toml index bf30233..63d5e03 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 115 +# version: 116 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib"] [workspace.package] -version = "0.2.2-pre.6.fix.1" +version = "0.2.2-pre.7" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 3c34d36..bb314c9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -46,7 +46,7 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U ### Releases fonctionnelles décidées/pressenties - [X] `0.2.1` — **HTTP transport foundation réduite par le gate `pre.001`** : crate/settings/JSON-RPC/registry 52 current + 14 deprecated historiques, pool/rôles/limites/retry, Config adapter, documentation et 4 méthodes typées canari (`getBalance`, `getGenesisHash`, `getHealth`, `getVersion`) publiés stables. -- [/] `0.2.2` — Compléter HTTP Accounts + Tokens + Cluster : 5 méthodes Accounts restantes + 5 Tokens + 12 Cluster restantes, soit 22 méthodes ; `pre.001` confirme le périmètre officiel et un sizing positif. +- [/] `0.2.2` — HTTP Accounts + Tokens + Cluster : candidate `pre.007` avec 22 wrappers typés (5 Accounts + 5 Tokens + 12 Cluster), canaries de complétude, smoke Devnet Transport opt-in et documentation de clôture ; publication stable encore requise. - [ ] `0.2.3` — Compléter les 11 méthodes HTTP Transactions, y compris write/submission technique avec politique no-resend ambigu. - [ ] `0.2.4` — Compléter les 10 méthodes HTTP Blocks + 5 Economics et exécuter la compliance finale de toute la surface HTTP 52 current + 14 deprecated historiques. - [ ] `0.2.5` — Introduire `ksp-wallet-lib`, le format `.kspwallet`, la gestion sûre des secrets et une architecture d'import/export extensible ; exclure `WalletPolicy`. diff --git a/crates/ksp-onchain-transport-lib/README.md b/crates/ksp-onchain-transport-lib/README.md index f8eefe9..c44f2ef 100644 --- a/crates/ksp-onchain-transport-lib/README.md +++ b/crates/ksp-onchain-transport-lib/README.md @@ -1,5 +1,5 @@ - + # `ksp-onchain-transport-lib` @@ -69,16 +69,16 @@ Le registre porte notamment : - remplacement historique éventuel ; - release de couverture typée KSP. -Les quatre wrappers typés de la foundation sont : +La surface typée candidate après `0.2.2-pre.007` contient **26 méthodes** : ```text -getBalance -getGenesisHash -getHealth -getVersion +0.2.1 foundation : 4 +0.2.2 Accounts : 5 +0.2.2 Tokens : 5 +0.2.2 Cluster : 12 ``` -Les autres méthodes courantes peuvent déjà passer par l'exécuteur JSON-RPC standard générique lorsqu'un consumer fournit explicitement descriptor et paramètres JSON. Cette surface raw/générique **ne vaut pas couverture typée** : les wrappers et DTOs typés restants sont introduits selon la matrice HTTP KSP. +Les quatre canaris foundation restent `getBalance`, `getGenesisHash`, `getHealth` et `getVersion`. `0.2.2` ajoute les 22 wrappers Accounts/Tokens/Cluster affectés à `HttpRpcCoverageRelease::V0_2_2`. Les 26 méthodes Transactions/Blocks/Economics encore affectées à `0.2.3`–`0.2.4` peuvent déjà passer par l'exécuteur JSON-RPC standard générique lorsqu'un consumer fournit explicitement descriptor et paramètres JSON, mais cette surface raw/générique **ne vaut pas couverture typée**. Les 14 méthodes historiques restent découvrables pour la compliance mais sont `Removed` et ne sont pas simulées comme appelables. @@ -118,18 +118,22 @@ La configuration Logging de référence conserve un fichier dédié Transport à Les tests par défaut sont déterministes et n'exigent pas Internet : fixtures JSON et serveur HTTP local couvrent requêtes, réponses, retry, 429, timeout, redaction et routing. -Un smoke Devnet live existe côté `ksp-config-lib` afin de tester la chaîne réelle : +Deux smokes Devnet opt-in sont séparés par responsabilité : ```text -Config -> std.transport/devnet_public -> HttpTransportPool - -> getHealth/getGenesisHash/getVersion/getBalance +Transport pur : settings programmatiques -> HttpTransportPool + -> getAccountInfo/getTokenSupply/getEpochInfo/getVoteAccounts + +Composition historique : Config -> std.transport/devnet_public -> HttpTransportPool + -> getHealth/getGenesisHash/getVersion/getBalance ``` -Il est `ignored` par défaut et doit être exécuté explicitement. +Les deux sont `ignored` par défaut. Le smoke Transport appartient durablement à cette crate ; le smoke cross-crates hébergé dans Config reste transitoire jusqu'à l'existence d'une surface KSP d'intégration/orchestration appropriée. ## Documentation -- [`USAGE.md`](USAGE.md) — consommation directe, Config -> Transport, API typed/raw et inspection runtime ; -- [`../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — plan et matrice HTTP ; -- [`../../docs/validation/003-V0_2_1_ONCHAIN_HTTP.md`](../../docs/validation/003-V0_2_1_ONCHAIN_HTTP.md) — matrice de clôture ; +- [`USAGE.md`](USAGE.md) — consommation directe, Config -> Transport, API typed/raw, smokes et inspection runtime ; +- [`../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — foundation HTTP stable ; +- [`../../docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](../../docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) — extension typed Accounts/Tokens/Cluster ; +- [`../../docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](../../docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) — matrice de clôture candidate `0.2.2` ; - [`../../config/std.transport.json`](../../config/std.transport.json) — configuration standard HTTP. diff --git a/crates/ksp-onchain-transport-lib/USAGE.md b/crates/ksp-onchain-transport-lib/USAGE.md index f5f174d..2305706 100644 --- a/crates/ksp-onchain-transport-lib/USAGE.md +++ b/crates/ksp-onchain-transport-lib/USAGE.md @@ -1,5 +1,5 @@ - + # Utilisation de `ksp-onchain-transport-lib` @@ -86,17 +86,17 @@ let balance = pool .await; ``` -Les types de retour associés sont : +Les quatre canaris `0.2.1` restent disponibles. `0.2.2` ajoute les wrappers typés Accounts, Tokens et Cluster. Exemples représentatifs : -```text -SolanaNodeHealth -SolanaGenesisHash -SolanaNodeVersion -GetBalanceResult -SolanaRpcContext +```rust +let account = pool + .get_account_info(&role, &ksp_core_lib::PRGIDPK_SOLANA_SYSTEM, None) + .await; +let epoch = pool.get_epoch_info(&role, None).await; +let vote_accounts = pool.get_vote_accounts(&role, None).await; ``` -`GetBalanceResult::value()` renvoie les lamports et `context()` fournit le slot/API version retournés par Solana. +La surface candidate contient 26 wrappers typés au total : 4 foundation + 5 Accounts + 5 Tokens + 12 Cluster. Les DTOs Transport conservent les `null`, options et formes wire : données Account encodées/`jsonParsed`, `TokenAmount.uiAmount`, contexte RPC, nodes, epoch, leader schedule et vote accounts. Aucun décodage Program/SPL métier n'est effectué ici. ## 4. Exécution JSON-RPC standard générique @@ -153,12 +153,22 @@ Ne jamais journaliser l'URL complète, un token provider, un body massif, une tr La configuration standard route les événements `info` de Transport vers un fichier dédié. Pour une investigation temporaire, élever uniquement ce target/sink à `debug` ou `trace`, puis revenir à `info` avant clôture du développement. -## 9. Smoke Devnet opt-in +## 9. Smokes Devnet opt-in -Le smoke live est volontairement hors des tests par défaut : +Le smoke **Transport pur** construit ses settings programmatiquement et exerce un sous-ensemble représentatif de `0.2.2` : + +```bash +cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Il appelle `getAccountInfo`, `getTokenSupply`, `getEpochInfo` et `getVoteAccounts`. Le mint utilisé par `getTokenSupply` est celui de l'exemple Devnet de la documentation officielle courante ; si cet état externe disparaît, le smoke doit être réaudité plutôt que transformé en test déterministe. + +Le smoke historique de **composition Config -> Transport** reste également disponible : ```bash cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture ``` -Il charge le profil Config `devnet_public`, construit le pool puis appelle les quatre wrappers typés. Les endpoints publics Solana étant rate-limités et non destinés à la production, un échec réseau externe n'est pas interprété comme un échec déterministe de la suite locale. +Il valide le profil committé `devnet_public` et les quatre canaris foundation. Il reste transitoirement hébergé dans Config : les futurs smokes cross-crates ne doivent pas faire de Config leur destination générale et devront migrer vers une surface d'intégration/orchestration dédiée lorsqu'elle existera. + +Les endpoints publics Solana sont rate-limités et non destinés à la production. Un échec réseau externe n'est pas assimilé automatiquement à une régression locale ; les fixtures HTTP locales restent les gates reproductibles. diff --git a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs index b58aba5..bbebde4 100644 --- a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs +++ b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/tests/release_completeness.rs -// version: 5 +// version: 6 //! Release-level completeness canaries for the `0.2.1` HTTP foundation contract. @@ -143,3 +143,54 @@ fn release_pre_006_completes_cluster_subset_exactly_and_retry_safe() { assert_eq!(actual, expected); assert_eq!(actual.len(), 12); } + +#[test] +fn release_pre_007_v0_2_2_exact_set_is_complete_without_advancing_future_releases() { + let mut expected = std::vec![ + "getAccountInfo", + "getClusterNodes", + "getEpochInfo", + "getEpochSchedule", + "getHighestSnapshotSlot", + "getIdentity", + "getLargestAccounts", + "getLeaderSchedule", + "getMaxRetransmitSlot", + "getMaxShredInsertSlot", + "getMinimumBalanceForRentExemption", + "getMultipleAccounts", + "getProgramAccounts", + "getSlot", + "getSlotLeader", + "getSlotLeaders", + "getTokenAccountBalance", + "getTokenAccountsByDelegate", + "getTokenAccountsByOwner", + "getTokenLargestAccounts", + "getTokenSupply", + "getVoteAccounts", + ]; + let mut actual = std::vec::Vec::new(); + let mut future_transactions = 0_usize; + let mut future_blocks_economics = 0_usize; + for descriptor in ksp_onchain_transport_lib::current_http_rpc_methods() { + match descriptor.coverage_release() { + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_2 => { + actual.push(descriptor.method()); + assert_eq!(descriptor.documentation_status(), ksp_onchain_transport_lib::RpcDocumentationStatus::Stable); + assert_eq!(descriptor.runtime_status(), ksp_onchain_transport_lib::RpcRuntimeStatus::Supported); + assert_eq!(descriptor.operation_kind(), ksp_onchain_transport_lib::RpcOperationKind::Read); + assert_eq!(descriptor.transport_retry_class(), ksp_onchain_transport_lib::TransportRetryClass::RetrySafe); + }, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_3 => future_transactions += 1, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_4 => future_blocks_economics += 1, + _ => {}, + } + } + actual.sort_unstable(); + expected.sort_unstable(); + assert_eq!(actual, expected); + assert_eq!(actual.len(), 22); + assert_eq!(future_transactions, 11); + assert_eq!(future_blocks_economics, 15); +} diff --git a/crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs b/crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs new file mode 100644 index 0000000..f085654 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs @@ -0,0 +1,84 @@ +// file: crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs +// version: 1 + +//! Opt-in live Devnet smoke for the pure Transport Accounts/Tokens/Cluster path. + +fn devnet_pool() -> ksp_onchain_transport_lib::HttpTransportPool { + let role = ksp_onchain_transport_lib::HttpRoleName::new("default"); + let role_settings = ksp_onchain_transport_lib::HttpEndpointRoleSettings::new( + role, + true, + std::vec![ksp_onchain_transport_lib::HttpRequestKind::wildcard()], + 0, + ksp_onchain_transport_lib::HttpRoleLimits::new( + std::option::Option::None, + std::option::Option::None, + std::option::Option::None, + std::option::Option::None, + ), + ); + let endpoint_url = + ksp_onchain_transport_lib::HttpEndpointUrl::parse("https://api.devnet.solana.com").expect("official Solana Devnet endpoint URL must remain valid"); + let endpoint = ksp_onchain_transport_lib::HttpEndpointSettings::new( + "solana_devnet_public", + true, + ksp_onchain_transport_lib::HttpProviderName::new("solana-public"), + ksp_onchain_transport_lib::HttpClusterName::new("devnet"), + endpoint_url, + std::time::Duration::from_secs(5), + std::time::Duration::from_secs(20), + std::option::Option::Some(4), + std::vec![role_settings], + ); + let settings = ksp_onchain_transport_lib::HttpTransportSettings::new( + std::vec![endpoint], + ksp_onchain_transport_lib::HttpRetrySettings::new(1, std::time::Duration::from_millis(250), std::time::Duration::from_secs(2)), + ); + return ksp_onchain_transport_lib::HttpTransportPool::new(settings).expect("programmatic Devnet Transport settings must construct a pool"); +} + +#[tokio::test(flavor = "current_thread")] +#[ignore = "opt-in live Solana Devnet smoke; performs external network requests"] +async fn programmatic_devnet_transport_reaches_accounts_tokens_and_cluster_wrappers() { + let pool = devnet_pool(); + let role = ksp_onchain_transport_lib::HttpRoleName::new("default"); + + let account_config = ksp_onchain_transport_lib::SolanaAccountInfoConfig::new( + std::option::Option::Some(ksp_onchain_transport_lib::SolanaAccountEncoding::Base64), + std::option::Option::None, + std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Finalized), + std::option::Option::None, + ); + let account = pool + .get_account_info(&role, &ksp_core_lib::PRGIDPK_SOLANA_SYSTEM, std::option::Option::Some(&account_config)) + .await + .expect("Devnet getAccountInfo smoke must succeed"); + assert!(account.context().slot() > 0); + assert!(account.value().is_some()); + + // Current official getTokenSupply documentation uses this Devnet mint in its example. + let token_mint = "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E" + .parse::() + .expect("official Devnet token mint example must remain a valid Pubkey literal"); + let token_supply = pool + .get_token_supply(&role, &token_mint, std::option::Option::None) + .await + .expect("Devnet getTokenSupply smoke must succeed for the documented mint"); + assert!(token_supply.context().slot() > 0); + assert!(!token_supply.value().amount().is_empty()); + + let epoch = pool + .get_epoch_info( + &role, + std::option::Option::Some(&ksp_onchain_transport_lib::SolanaContextConfig::new( + std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Finalized), + std::option::Option::None, + )), + ) + .await + .expect("Devnet getEpochInfo smoke must succeed"); + assert!(epoch.absolute_slot() > 0); + + let vote_accounts = pool.get_vote_accounts(&role, std::option::Option::None).await.expect("Devnet getVoteAccounts smoke must succeed"); + assert!(!vote_accounts.current().is_empty() || !vote_accounts.delinquent().is_empty()); +} diff --git a/deltas/0.2.2/pre.007.md b/deltas/0.2.2/pre.007.md new file mode 100644 index 0000000..43a6972 --- /dev/null +++ b/deltas/0.2.2/pre.007.md @@ -0,0 +1,248 @@ + + + +# Delta `v0.2.2-pre.007` + +## Base + +Base attendue : + +```text +v0.2.2-pre.006-fix.001 +``` + +Cette base a été validée localement par l'opérateur le 2026-08-18 avec : + +- `cargo fmt --all` ; +- `cargo check --workspace` ; +- `cargo clippy --workspace --all-targets` ; +- `cargo test -p ksp-onchain-transport-lib`. + +Résultats Transport communiqués : + +```text +127 unit tests passed +13 public API tests passed +6 release completeness tests passed +0 warning clippy signalé +``` + +Version Cargo cible : + +```text +0.2.2-pre.7 +``` + +## Objectif + +Fermer la dernière prerelease fonctionnelle de `0.2.2` sans ajouter de nouvelle méthode HTTP : + +- revérifier l'inventaire officiel Solana ; +- figer la complétude exacte des 22 wrappers `0.2.2` ; +- ajouter un smoke Devnet opt-in **Transport pur** avec settings programmatiques ; +- conserver séparément le smoke historique de composition Config -> Transport ; +- synchroniser README/USAGE et la documentation d'architecture/planification ; +- produire la matrice finale `0.2.2` ; +- produire le prompt de démarrage `0.2.3 — HTTP Transactions` ; +- préparer un `rel.001` strictement publicationnel. + +Aucun 23e wrapper `0.2.2` et aucune méthode Transactions n'est introduit dans cette tranche. + +## Réaudit officiel final + +La documentation officielle Solana a été revérifiée le 2026-08-18 : + +```text +https://solana.com/docs/rpc/http +https://solana.com/docs/rpc/deprecated/confirmtransaction +``` + +L'index courant contient toujours : + +```text +52 méthodes HTTP courantes +14 méthodes historiques Deprecated +``` + +Les familles restent : + +```text +Accounts : 6 current +Tokens : 5 current +Cluster : 15 current +``` + +En retranchant les quatre canaris `0.2.1` (`getBalance`, `getGenesisHash`, `getHealth`, `getVersion`), la partition `0.2.2` reste exactement `5 + 5 + 12 = 22`. Aucun recalibrage n'est nécessaire. + +## Canaries de complétude + +`tests/release_completeness.rs` gagne un canary final qui fige depuis l'API publique : + +```text +V0_2_2 exact set == 22 méthodes du plan 009 +22 => Stable + Supported + Read + RetrySafe +V0_2_3 count == 11 +V0_2_4 count == 15 +``` + +Les canaries antérieures `52 + 14`, `4 / 22 / 11 / 15`, foundation exacte, Accounts, Tokens et Cluster restent inchangées. + +La candidate attend donc : + +```text +127 tests unitaires Transport +13 tests public API +7 tests release completeness +1 smoke Devnet Transport ignored par défaut +``` + +## Smoke Devnet Transport pur + +Nouveau test : + +```text +crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs +``` + +Contrairement au smoke historique de `0.2.1`, il ne dépend pas de Config : + +```text +settings programmatiques + -> https://api.devnet.solana.com + -> HttpTransportPool + -> getAccountInfo(System Program) + -> getTokenSupply(mint de l'exemple Devnet officiel courant) + -> getEpochInfo + -> getVoteAccounts +``` + +Exécution opt-in : + +```bash +cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Ce smoke appartient durablement à Transport parce qu'il ne valide que Transport. Il reste `ignored` car il dépend d'un réseau externe et d'un état Devnet. + +Le smoke `crates/ksp-config-lib/tests/transport_devnet_smoke.rs` reste séparé et valide uniquement la composition historique : + +```text +Config -> Transport -> quatre canaris foundation +``` + +Il reste transitoire et devra migrer vers une future surface d'intégration/orchestration/demo ; Config ne devient pas la destination générale des smokes cross-crates. + +## Documentation durable + +Mises à jour : + +- README Transport : 26 wrappers typed candidats, répartition 4 + 5 + 5 + 12 et ownership des deux smokes ; +- USAGE Transport : exemples typed `0.2.2` et commandes des deux smokes ; +- inventaire composant : état candidate `0.2.2` ; +- séquence fonctionnelle : `pre.002`–`pre.006` exécutées et `pre.007` candidate ; +- plan `009` : état candidate, réaudit final, smoke et préparation stable ; +- ROADMAP : `0.2.2` passe à `[/]`, pas à `[X]` avant stable ; +- index docs/plans/validation/prompts synchronisés. + +Nouveaux documents : + +```text +docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md +prompts/008-V0_2_3_START_PROMPT.md +``` + +`CHANGELOG.md` n'est volontairement pas modifié dans cette prerelease. + +## Prompt `0.2.3` + +Le prompt suivant cible exactement les 11 méthodes Transactions actuellement affectées à `V0_2_3` : + +```text +8 Read / RetrySafe +2 WriteSubmission / NeverAfterDispatch +1 Simulation / RetrySafe +``` + +Il impose un nouveau `pre.001` d'audit/sizing et met au premier plan la règle no-resend de `requestAirdrop` et `sendTransaction`. + +## Préparation de `rel.001` + +Si la candidate passe les validations opérateur, `rel.001` doit rester publicationnel : + +```text +workspace.package.version -> 0.2.2 +ROADMAP : 0.2.2 -> [X] +CHANGELOG : synthèse stable 0.2.2 +plan 009 / validation 004 : clôture + preuves opérateur +deltas/0.2.2/rel.001.md +commit v0.2.2-rel.001 +tag v0.2.2 après validation du commit +``` + +Aucun développement fonctionnel nouveau ne doit entrer dans `rel.001`. + +## Fichiers ajoutés + +```text +crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs +docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md +prompts/008-V0_2_3_START_PROMPT.md +deltas/0.2.2/pre.007.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +ROADMAP.md +crates/ksp-onchain-transport-lib/README.md +crates/ksp-onchain-transport-lib/USAGE.md +crates/ksp-onchain-transport-lib/tests/release_completeness.rs +docs/000-README.md +docs/architecture/004-COMPONENT_INVENTORY.md +docs/plans/000-README.md +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md +docs/validation/000-README.md +prompts/000-README.md +``` + +Aucun ancien delta et aucun `CHANGELOG.md` ne sont modifiés. + +## Validations exécutées dans la préparation de livraison + +Contrôles statiques exécutés : + +- version Cargo `0.2.2-pre.7` ; +- présence exacte des 22 noms dans le canary final ; +- fixture live absente des suites par défaut via `#[ignore]` ; +- smoke Transport sans dépendance Config ni lecture d'environnement ; +- index docs/plans/validation/prompts synchronisés ; +- versions de fichiers modifiés incrémentées ; +- aucun ajout de dépendance/feature Cargo ; +- archive réextraite et comparée au payload préparé. + +Cargo n'est pas disponible dans l'environnement de préparation. Les validations suivantes restent donc à exécuter par l'opérateur sur le dépôt canonique : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +cargo test -p ksp-config-lib +cargo test -p ksp-core-lib +cargo test -p ksp-app-config-desk +cargo test --workspace + +cargo tree -p ksp-onchain-transport-lib +cargo tree -p ksp-onchain-transport-lib -d +cargo tree -p ksp-onchain-transport-lib -e features +cargo tree -p ksp-onchain-transport-lib -e normal +cargo tree -p ksp-config-lib +cargo tree -p ksp-config-lib -d +cargo tree -p ksp-config-lib -e features +cargo tree -p ksp-config-lib -e normal + +cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` diff --git a/docs/000-README.md b/docs/000-README.md index 05eb35c..a03e39a 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -63,7 +63,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é ## Documents de planification -Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) devient le point d'entrée de `0.2.2`. Son `pre.001` ouvre le plan actif [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md), qui confirme après réaudit officiel le périmètre de 22 wrappers typés et son découpage de travail. +Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert `0.2.2`. Le plan [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) est amené en clôture candidate par `pre.007` avec les 22 wrappers typés Accounts/Tokens/Cluster, un smoke Devnet Transport pur et la matrice [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md). Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) prépare la release suivante `0.2.3 — HTTP Transactions`. `IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales. diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index f2466c7..d804ab3 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -17,41 +17,41 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse ## Inventaire synthétique -| Domaine | Composant | Type | Statut | Première cible actuelle | Mission | -|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|----------------------------------------------------------| -| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales | -| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP | -| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config | -| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config | -| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.1` | foundation HTTP, registry 52+14, pools/rôles, 4 canaris | -| Wallet | `ksp-wallet-lib` | lib | Retenu | `0.2.5` | `.kspwallet`, secrets, signature, import/export | -| Wallet Desk | `ksp-app-wallet-desk` | app | Retenu | `0.2.6` | Wallet + Config composite + HTTP/balance | -| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.7` | WebSocket Solana complet, sessions/subscriptions | -| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.8` | LaserStream WebSocket comme extension du moteur standard | -| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.9` | client gRPC standard/provider-neutral | -| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.10` | première abstraction/provider de prix SOL/USD, SOL/EUR | -| Price Desk | nom à fixer | app | Retenu | `0.2.11` | visualisation/validation des prix | -| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.12` | façade wire officielle + API publique wire | -| Program API | `ksp-program-api` | API | Retenu | `0.2.13` | contrats extensibles Program | -| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles | -| Program extension | `ksp-program--lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` | -| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord | -| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord | -| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables | -| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW | -| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW | -| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus | -| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW | -| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE | -| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu | -| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation | -| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes | -| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte | -| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport | -| Scenarios | `ksp-scenario--lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe | -| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun | -| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC | -| Trading Intelligence | noms à définir | libs/jobs | Futur | après données stables | features/signaux/anomalies/ML | +| Domaine | Composant | Type | Statut | Première cible actuelle | Mission | +|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|-----------------------------------------------------------| +| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales | +| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP | +| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config | +| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config | +| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.1` | foundation HTTP + 26 wrappers typés après candidate 0.2.2 | +| Wallet | `ksp-wallet-lib` | lib | Retenu | `0.2.5` | `.kspwallet`, secrets, signature, import/export | +| Wallet Desk | `ksp-app-wallet-desk` | app | Retenu | `0.2.6` | Wallet + Config composite + HTTP/balance | +| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.7` | WebSocket Solana complet, sessions/subscriptions | +| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.8` | LaserStream WebSocket comme extension du moteur standard | +| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.9` | client gRPC standard/provider-neutral | +| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.10` | première abstraction/provider de prix SOL/USD, SOL/EUR | +| Price Desk | nom à fixer | app | Retenu | `0.2.11` | visualisation/validation des prix | +| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.12` | façade wire officielle + API publique wire | +| Program API | `ksp-program-api` | API | Retenu | `0.2.13` | contrats extensibles Program | +| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles | +| Program extension | `ksp-program--lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` | +| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord | +| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord | +| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables | +| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW | +| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW | +| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus | +| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW | +| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE | +| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu | +| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation | +| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes | +| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte | +| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport | +| Scenarios | `ksp-scenario--lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe | +| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun | +| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC | +| Trading Intelligence | noms à définir | libs/jobs | Futur | après données stables | features/signaux/anomalies/ML | ## Contrats séparés retenus @@ -78,7 +78,7 @@ ksp-data-api ## Transport -`ksp-onchain-transport-lib` doit couvrir l'intégralité des opérations documentées de la surface ciblée par chaque release. `0.2.1` stabilise la foundation HTTP et quatre wrappers typés canari ; la couverture typée des 48 autres méthodes courantes reste explicitement répartie sur `0.2.2`–`0.2.4`. Les statuts deprecated/obsolete encore fonctionnels et unstable/experimental restent exposés avec warning runtime KSP. +`ksp-onchain-transport-lib` doit couvrir l'intégralité des opérations documentées de la surface ciblée par chaque release. `0.2.1` stabilise la foundation HTTP et quatre wrappers typés canari. La candidate `0.2.2-pre.007` ajoute les 22 wrappers Accounts/Tokens/Cluster, soit 26 wrappers typés au total ; les 26 méthodes Transactions/Blocks/Economics restantes restent affectées à `0.2.3`–`0.2.4`. Les statuts deprecated/obsolete encore fonctionnels et unstable/experimental restent exposés avec warning runtime KSP. La Config standard Transport appartient à `ksp-config-lib`, qui adapte vers les settings publics du transport ; le transport ne dépend jamais de Config. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index d48b9bd..1102f45 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -17,7 +17,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`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 historique clôturé de la release stable `0.2.0`, ouvert par `pre.001`, consolidé par `pre.002`, audité par `pre.003` puis publié par `rel.001`; il fixe l'ordre `0.2.1+`, la stratégie RAW/CORE/DECODE/SPECIALIZED, les vertical slices Program et le prompt `0.2.1`. - [`008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — plan de `0.2.1`, établi par `0.2.1-pre.001`, recalibré par `pre.001-fix.001` et amené en clôture candidate par `pre.007`; il conserve l'inventaire 52 méthodes HTTP courantes + 14 Deprecated historiques, le design Transport/Config et le split de couverture typée sur `0.2.1`–`0.2.4`. -- [`009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) — plan actif de `0.2.2`, établi par `0.2.2-pre.001` après réaudit officiel ; il confirme les 22 méthodes Accounts/Tokens/Cluster, leurs formes wire communes et le sizing de la release. +- [`009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) — plan de `0.2.2`, établi par `pre.001`, corrigé par `pre.001-fix.001` après réaudit Agave v4.2.1 puis amené en clôture candidate par `pre.007`; il couvre les 22 wrappers Accounts/Tokens/Cluster, le smoke Transport opt-in et la préparation de `0.2.3`. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index 0c4d585..da5238a 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # Séquence des releases fonctionnelles KSP @@ -390,7 +390,7 @@ Ces trois releases constituent le découpage nominal, pas une obligation de troi Chaque `pre.001` réaudite la documentation officielle actuelle. Les méthodes Deprecated réellement retirées restent tracées comme historiques/runtime removed au lieu d'être simulées. -`0.2.2-pre.001` a effectué ce réaudit : la partition reste 22 méthodes (5 Accounts + 5 Tokens + 12 Cluster) et le gate de sizing est positif. Le plan d'exécution actif est `docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`. +`0.2.2-pre.001` a confirmé la partition de 22 méthodes et son fix documentaire a recoupé les formes wire avec Agave v4.2.1. Les tranches `pre.002`–`pre.006` ont livré les DTOs puis les 5 Accounts, 5 Tokens et 12 Cluster. `pre.007` constitue la candidate de clôture : canary exacte 22/22, smoke Devnet Transport pur, README/USAGE, matrice de validation `004` et prompt `0.2.3`. Le smoke cross-crates Config -> Transport de `0.2.1` reste séparé et transitoire. ## `0.2.5` — Wallet foundation diff --git a/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md index 3d135eb..ade2ea5 100644 --- a/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md +++ b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md @@ -1,11 +1,11 @@ - + # Plan `0.2.2` — HTTP Accounts + Tokens + Cluster ## Statut -Ce plan ouvre `0.2.2-pre.001` sur la base stable `v0.2.1`. +Ce plan, ouvert par `0.2.2-pre.001` sur la base stable `v0.2.1`, est amené en clôture candidate par `0.2.2-pre.007`. `0.2.1` a déjà stabilisé la foundation HTTP commune : settings, endpoints/pool/rôles, admission et limites, retry, JSON-RPC 2.0, registry des méthodes, exécution HTTP générique, adapter Config -> Transport et quatre wrappers typés canari. @@ -454,6 +454,34 @@ Un smoke Devnet opt-in pourra couvrir un sous-ensemble représentatif, sans jama Le découpage est volontairement asymétrique : `pre.006` contient moins de méthodes mais les formes les plus complexes. Toute tranche qui dépasse le budget est scindée en une prerelease supplémentaire plutôt que compressée. +## État de la candidate `pre.007` + +Les tranches fonctionnelles ont livré la surface prévue sans nouvelle dépendance externe : + +```text +pre.002 : primitives/configs/results communs +pre.003 : 5 Accounts +pre.004 : 5 Tokens +pre.005 : 7 Cluster simples +pre.006 : 5 Cluster restants +pre.007 : clôture candidate +``` + +La surface typed candidate est donc : + +```text +0.2.1 : 4 wrappers foundation +0.2.2 : 22 wrappers Accounts/Tokens/Cluster +total : 26 wrappers typed +future : 11 Transactions + 15 Blocks/Economics +``` + +Le réaudit final du 2026-08-18 de `https://solana.com/docs/rpc/http` confirme toujours les 52 méthodes HTTP courantes et la même répartition des familles. La navigation Deprecated conserve les 14 méthodes historiques déjà enregistrées. Aucune méthode de `0.2.2` n'est déplacée ou reclassée. + +Un smoke Devnet opt-in **propre à Transport** est ajouté sous `crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs`. Il construit ses settings programmatiquement et exerce `getAccountInfo`, `getTokenSupply`, `getEpochInfo` et `getVoteAccounts`. Le smoke historique `Config -> Transport` reste distinct et transitoirement hébergé dans Config. Les fixtures HTTP locales restent les preuves reproductibles par défaut. + +La matrice durable de clôture est `docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md` et le prompt suivant est `prompts/008-V0_2_3_START_PROMPT.md`. `CHANGELOG.md` reste réservé à `rel.001`. + ## Hors périmètre Sont exclus de `0.2.2` : diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index 367b4e0..1589ffd 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -12,3 +12,4 @@ Documents : - [`001-V0_1_4_CONFIG_DESKTOP.md`](001-V0_1_4_CONFIG_DESKTOP.md) — matrice finale de `0.1.4 — ksp-app-config-desk`. - [`002-V0_2_0_SERIES_PLANNING.md`](002-V0_2_0_SERIES_PLANNING.md) — matrice finale de la release stable `0.2.0`, avec audit de cohérence et preuves opérateur de `pre.003`. - [`003-V0_2_1_ONCHAIN_HTTP.md`](003-V0_2_1_ONCHAIN_HTTP.md) — matrice de clôture de `0.2.1 — HTTP Solana foundation`, registry 52+14, résilience, Config -> Transport, quatre canaris et smoke Devnet opt-in. +- [`004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) — matrice de clôture candidate de `0.2.2`, 22 wrappers Accounts/Tokens/Cluster, canaries 52+14, smoke Devnet Transport pur et préparation de `0.2.3`. diff --git a/docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md b/docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md new file mode 100644 index 0000000..beeb45b --- /dev/null +++ b/docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md @@ -0,0 +1,247 @@ + + + +# Validation finale `0.2.2` — HTTP Accounts + Tokens + Cluster + +## Statut + +Cette matrice accompagne la candidate `0.2.2-pre.007`. Elle ne publie pas encore la release stable : les preuves opérateur finales doivent être enregistrées avant `0.2.2-rel.001`. + +Base fonctionnelle validée avant `pre.007` : + +```text +v0.2.2-pre.006-fix.001 +``` + +L'opérateur a validé cette base le 2026-08-18 avec : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +``` + +Résultats Transport communiqués : + +```text +127 unit tests passed +13 public API tests passed +6 release completeness passed +0 warning clippy signalé +``` + +## Réaudit officiel final + +Le 2026-08-18, l'index officiel courant a été revérifié : + +```text +https://solana.com/docs/rpc/http +https://solana.com/docs/rpc/deprecated/confirmtransaction +``` + +La matrice reste : + +```text +52 méthodes HTTP courantes +14 méthodes historiques Deprecated +``` + +Répartition courante utile à cette release : + +```text +Accounts : 6 = getBalance acquis en 0.2.1 + 5 en 0.2.2 +Tokens : 5 = 5 en 0.2.2 +Cluster : 15 = getGenesisHash/getHealth/getVersion acquis en 0.2.1 + 12 en 0.2.2 +``` + +Aucune méthode `0.2.2` n'est reclassée Deprecated/Unstable. Les 22 descriptors restent `Stable / Supported / Read / RetrySafe`. + +## Surface typée candidate + +`0.2.2` ajoute exactement : + +```text +Accounts : 5 +Tokens : 5 +Cluster : 12 +Total : 22 +``` + +Avec les quatre canaris de `0.2.1`, Transport expose donc 26 wrappers typed à la candidate. + +Les partitions futures restent intactes : + +```text +0.2.3 Transactions : 11 +0.2.4 Blocks + Economics : 15 +``` + +L'API raw `execute_standard_rpc()` reste disponible mais ne compte pas comme couverture typed d'une méthode future. + +## Contrats wire à préserver + +La candidate doit conserver notamment : + +- `Account.data` legacy / encoded / `jsonParsed` sans décodage Program ; +- `Account.space: Option` ; +- comptes absents sous `null` ; +- `getProgramAccounts` bare vs contextualisé ; +- `TokenAmount.amount` et `uiAmountString` comme chaînes exactes ; +- `TokenAmount.uiAmount: Option` ; +- selector Token exclusif `Mint | ProgramId` ; +- `ClusterNode.clientId: Option` ; +- `EpochInfo.transactionCount: Option` ; +- `SnapshotSlotInfo.incremental: Option` ; +- `getLeaderSchedule -> Option` ; +- `VoteAccountInfo.inflationRewardsCommissionBps: Option` ; +- triplets `epochCredits` sans interprétation métier. + +Limites locales figées : + +```text +getMultipleAccounts <= 100 +getProgramAccounts <= 4 filtres +memcmp raw <= 128 octets +getSlotLeaders 1..=5000 +``` + +## Canaries de complétude + +`tests/release_completeness.rs` protège : + +```text +current == 52 +historical == 14 +partition == 4 / 22 / 11 / 15 +0.2.1 exact == 4 canaris foundation +0.2.2 exact == 22 Accounts/Tokens/Cluster +0.2.3 count == 11 sans avancement typed prématuré +0.2.4 count == 15 sans avancement typed prématuré +historical => Deprecated + Removed + Historical + NotApplicable +``` + +Après `pre.007`, la suite attendue est : + +```text +127 unit tests +13 public API tests +7 release completeness tests +1 smoke Transport live ignored par défaut +``` + +## Smoke Devnet Transport pur + +Nouveau test : + +```text +crates/ksp-onchain-transport-lib/tests/transport_devnet_smoke.rs +``` + +Il construit `HttpTransportSettings` programmatiquement, sans Config ni environnement : + +```text +https://api.devnet.solana.com + -> getAccountInfo(System Program) + -> getTokenSupply(mint de l'exemple Devnet officiel courant) + -> getEpochInfo + -> getVoteAccounts +``` + +Exécution explicite : + +```bash +cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Le test est `ignored` par défaut. Un incident réseau/rate-limit ou la disparition d'un état externe documenté doit être analysé séparément ; il ne remplace jamais les fixtures HTTP locales. + +## Smoke de composition Config -> Transport + +Le smoke historique `0.2.1` reste disponible : + +```bash +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Il valide `Config -> profil devnet_public -> Transport -> quatre canaris foundation`. + +Ownership : ce smoke cross-crates est transitoire. `ksp-config-lib` ne doit pas devenir la destination générale des smokes `Config + autre crate`; il migrera vers une future surface d'intégration/orchestration/demo appropriée. + +## Dépendances, sécurité et logging + +La candidate ne doit introduire : + +```text +aucune dépendance externe nouvelle +aucune dépendance Transport -> Config/Store/Program +aucun tracing direct hors ksp-logging-lib +aucun client HTTP parallèle +``` + +Les invariants de sécurité `0.2.1` restent obligatoires : URL/provider credentials absents des diagnostics ordinaires, `reqwest::Error::without_url()` avant exposition comme source, aucune réponse/body massif journalisé par défaut. + +La baseline Logging Transport reste `info` avant publication stable. + +## Documentation candidate + +Doivent être synchronisés : + +```text +crates/ksp-onchain-transport-lib/README.md +crates/ksp-onchain-transport-lib/USAGE.md +docs/architecture/004-COMPONENT_INVENTORY.md +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md +ROADMAP.md +prompts/008-V0_2_3_START_PROMPT.md +``` + +`CHANGELOG.md` reste volontairement inchangé avant `rel.001`. + +## Validations finales opérateur à exécuter sur `pre.007` + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +cargo test -p ksp-config-lib +cargo test -p ksp-core-lib +cargo test -p ksp-app-config-desk +cargo test --workspace + +cargo tree -p ksp-onchain-transport-lib +cargo tree -p ksp-onchain-transport-lib -d +cargo tree -p ksp-onchain-transport-lib -e features +cargo tree -p ksp-onchain-transport-lib -e normal +cargo tree -p ksp-config-lib +cargo tree -p ksp-config-lib -d +cargo tree -p ksp-config-lib -e features +cargo tree -p ksp-config-lib -e normal +``` + +Puis les deux smokes opt-in : + +```bash +cargo test -p ksp-onchain-transport-lib --test transport_devnet_smoke -- --ignored --nocapture +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Les résultats doivent être reportés dans `rel.001`; cette matrice ne les anticipe pas. + +## Passage à `rel.001` + +Si toutes les validations passent, `rel.001` doit rester strictement publicationnel : + +```text +workspace.package.version -> 0.2.2 +ROADMAP : 0.2.2 -> [X] +CHANGELOG : synthèse stable 0.2.2 +plan 009 / validation 004 : statut clôturé + preuves opérateur +deltas/0.2.2/rel.001.md +commit v0.2.2-rel.001 +tag stable v0.2.2 après validation du commit +``` + +Aucune nouvelle méthode HTTP, aucun nouveau DTO et aucun nouveau comportement runtime ne doivent apparaître dans `rel.001`. diff --git a/prompts/000-README.md b/prompts/000-README.md index ea351ee..38abbfd 100644 --- a/prompts/000-README.md +++ b/prompts/000-README.md @@ -1,5 +1,5 @@ - + # Prompts KSP @@ -28,3 +28,4 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par - [`005-V0_2_0_START_PROMPT.md`](005-V0_2_0_START_PROMPT.md) — prompt de reprise préparé à la clôture de `0.1.4`; il ouvre `0.2.0-pre.001`, release intermédiaire d'audit de `khadhroony-bot3`, de comparaison avec KSP et de planification/découpage du reste de `0.2.x` ; - [`006-V0_2_1_START_PROMPT.md`](006-V0_2_1_START_PROMPT.md) — prompt finalisé par `0.2.0-pre.003`, destiné à ouvrir `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation` après publication stable de `0.2.0`; il impose l'audit exhaustif des surfaces HTTP courantes et deprecated/unstable officiellement documentées, la séparation Config/Transport, les pools/rôles et le gate de sizing « une release = une session » ; - [`007-V0_2_2_START_PROMPT.md`](007-V0_2_2_START_PROMPT.md) — prompt préparé par la dernière prerelease de `0.2.1`, destiné à ouvrir `0.2.2 — HTTP Accounts + Tokens + Cluster` après publication stable de `0.2.1`; il cible les 22 wrappers typés restants de ces familles et impose un nouvel audit officiel/gate de sizing à `pre.001`. +- [`008-V0_2_3_START_PROMPT.md`](008-V0_2_3_START_PROMPT.md) — prompt préparé par la dernière prerelease de `0.2.2`, destiné à ouvrir `0.2.3 — HTTP Transactions` après publication stable de `0.2.2`; il cible les 11 méthodes Transactions et impose un audit actuel ainsi que la politique no-resend des write submissions. diff --git a/prompts/008-V0_2_3_START_PROMPT.md b/prompts/008-V0_2_3_START_PROMPT.md new file mode 100644 index 0000000..c070451 --- /dev/null +++ b/prompts/008-V0_2_3_START_PROMPT.md @@ -0,0 +1,268 @@ + + + +# Prompt de démarrage `0.2.3` — HTTP Transactions + +## 1. Contexte de reprise + +La base attendue est la release stable : + +```text +v0.2.2 +``` + +`0.2.1` a stabilisé la foundation HTTP Solana et quatre canaris typed. `0.2.2` complète Accounts/Tokens/Cluster avec 22 wrappers supplémentaires, un smoke Devnet Transport pur, des DTOs wire communs et les canaries de clôture. + +La surface acquise au démarrage de `0.2.3` doit donc être : + +```text +52 méthodes HTTP courantes enregistrées +14 méthodes historiques Deprecated / runtime Removed +26 wrappers typed : 4 foundation + 22 Accounts/Tokens/Cluster +partition restante : 11 Transactions + 15 Blocks/Economics +Transport -X-> Config/Store/Program/tracing direct +Config -> Transport autorisé +``` + +La release à ouvrir est : + +```text +0.2.3 — HTTP Transactions +``` + +La première tranche est `0.2.3-pre.001` et commence par **audit officiel actuel + brainstorming + sizing** avant toute implémentation lourde. + +## 2. Mission + +Compléter les 11 méthodes Transactions affectées à `HttpRpcCoverageRelease::V0_2_3` : + +```text +getFeeForMessage +getLatestBlockhash +getRecentPrioritizationFees +getSignaturesForAddress +getSignatureStatuses +getTransaction +getTransactionCount +isBlockhashValid +requestAirdrop +sendTransaction +simulateTransaction +``` + +Cette liste est la partition KSP actuelle. `pre.001` doit la revérifier contre la documentation Solana du jour avant de confirmer le périmètre. + +## 3. Classification de sécurité à préserver + +La metadata KSP actuelle distingue : + +```text +8 Read / RetrySafe +2 WriteSubmission / NeverAfterDispatch : requestAirdrop, sendTransaction +1 Simulation / RetrySafe : simulateTransaction +``` + +`pre.001` doit vérifier que cette classification reste correcte. La règle la plus importante est : + +> aucune resoumission automatique d'une WriteSubmission après un dispatch ambigu. + +Un timeout après dispatch, une rupture de connexion après envoi ou toute autre issue où KSP ne peut pas prouver l'absence de dispatch doit arrêter le retry automatique. + +## 4. Sources internes obligatoires + +Relire avant modification : + +```text +ROADMAP.md +CHANGELOG.md +RULES.md + +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md +docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md +docs/validation/003-V0_2_1_ONCHAIN_HTTP.md +docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md + +docs/architecture/002-LAYERS_AND_DEPENDENCIES.md +docs/architecture/003-COMPONENT_CONTRACTS.md +docs/architecture/004-COMPONENT_INVENTORY.md +docs/architecture/005-DEPENDENCY_GRAPH.md + +docs/rules/RULES_DEPENDENCIES.md +docs/rules/RULES_RUST.md +docs/rules/RULES_KSP.md +docs/rules/FILE_CONTRACTS.md +docs/rules/VERSION_WORKFLOW.md +docs/rules/PROMPT_STRUCTURE.md + +crates/ksp-onchain-transport-lib/README.md +crates/ksp-onchain-transport-lib/USAGE.md +crates/ksp-onchain-transport-lib/src/ +crates/ksp-onchain-transport-lib/unit_tests/ +crates/ksp-onchain-transport-lib/tests/ +``` + +Les anciens deltas sont historiques et ne doivent pas être réécrits. + +## 5. Sources externes normatives + +Au début de `pre.001`, réauditer : + +```text +https://solana.com/docs/rpc/http +https://solana.com/docs/rpc/json-structures +``` + +Et les sources primaires Agave actuelles lorsque la documentation HTTP laisse une ambiguïté sur les configs, limites ou champs wire. + +Pour chaque méthode Transaction vérifier : + +- paramètres et ordre exacts ; +- commitments/minContextSlot ; +- encodings actuels et formes legacy ; +- cardinalités ; +- null/optional ; +- structures de signature/status/transaction/meta ; +- `maxSupportedTransactionVersion` ; +- erreurs significatives ; +- statut stable/deprecated/unstable ; +- limites provider/runtime utiles avant I/O. + +`getTransaction` doit notamment conserver explicitement sa forme moderne et la compatibilité legacy encore auditée, sans présenter la forme legacy comme recommandée. + +## 6. Gate de sizing obligatoire + +Répondre explicitement : + +```text +Les 11 wrappers Transactions, leurs DTOs/wires, les règles write/simulation, les tests et la documentation peuvent-ils être clôturés proprement dans cette session ? +``` + +Si NON, scinder `0.2.3` avant implémentation lourde. Une prerelease vise environ 15–20 minutes de travail effectif. + +## 7. Architecture Transport + +Conserver le flux unique : + +```text +wrapper typed + -> descriptor central + -> execute_standard_rpc + -> pool/admission + -> executor HTTP + -> validation JSON-RPC + -> decode typed +``` + +Interdits : client HTTP parallèle, `reqwest` direct par wrapper, bypass retry/deadline/admission, Transport -> Config, modèle Store/Program, `tracing` direct. + +Réutiliser les primitives `SolanaCommitment`, `SolanaContextConfig`, `SolanaRpcContext` et les erreurs KSP lorsque pertinentes. + +## 8. Transaction wire et dépendances + +Ne pas ajouter une crate Solana RPC/client haut niveau pour recopier les types du wire. + +`pre.001` doit décider explicitement si la représentation/validation des messages et transactions sérialisés justifie enfin une dépendance `base64`, `bs58` ou autre. Ne pas ajouter une dépendance seulement parce que les exemples RPC l'utilisent. + +Les apps/workers ne doivent pas recevoir de dépendance protocolaire Solana supplémentaire : la surface publique appartient à Transport/Core. + +## 9. Read methods + +Auditer particulièrement : + +- fee/message et blockhash contextuels ; +- recent prioritization fees ; +- signatures pagination `before/until/limit` ; +- signature statuses et recherche historique ; +- transaction nullable, encoding et version ; +- transaction count ; +- validité d'un blockhash. + +Conserver l'ordre des listes et les `null` documentés. + +## 10. Write submissions + +### `requestAirdrop` + +Considérer l'appel comme une soumission : une signature retournée n'autorise pas un resend automatique aveugle après résultat ambigu. + +### `sendTransaction` + +La règle no-resend est critique. Le wrapper doit utiliser la policy centrale existante et ne jamais introduire sa propre boucle de retry. + +Le contrat Transport ne devient pas un executor métier : il transporte une transaction déjà construite/signée et préserve les options RPC. + +## 11. `simulateTransaction` + +Simulation n'est pas une WriteSubmission et reste retry-safe selon la metadata actuelle, sous réserve du réaudit `pre.001`. + +Préserver les options et résultats utiles sans introduire de décodage Program métier. + +## 12. Tests + +Fixtures HTTP locales obligatoires pour chaque méthode : + +- request exacte ; +- success typed ; +- null/optional ; +- config/legacy pertinent ; +- erreurs RPC ; +- cardinalités ; +- write dispatch/no-resend ; +- simulation. + +Conserver les canaries : + +```text +current == 52 confirmées +historical == 14 confirmées +0.2.1 exact == 4 +0.2.2 exact == 22 +0.2.3 exact == 11 +0.2.4 reste 15 sans avancement prématuré +``` + +Les smokes live restent opt-in et ne remplacent jamais les fixtures. + +## 13. Documentation et fin de release + +La dernière prerelease doit, comme `0.2.2-pre.007` : + +- réauditer l'inventaire officiel ; +- figer les canaries de complétude ; +- décider/ajouter un smoke opt-in pertinent sans créer une mauvaise ownership boundary ; +- synchroniser README/USAGE, plan et matrice de validation ; +- préparer le prompt `0.2.4` ; +- laisser `CHANGELOG.md` à `rel.001` ; +- préparer une release stable strictement publicationnelle. + +## 14. Validations + +Pendant le développement : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +``` + +À la clôture : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +cargo test -p ksp-config-lib +cargo test -p ksp-core-lib +cargo test -p ksp-app-config-desk +cargo test --workspace + +cargo tree -p ksp-onchain-transport-lib +cargo tree -p ksp-onchain-transport-lib -d +cargo tree -p ksp-onchain-transport-lib -e features +cargo tree -p ksp-onchain-transport-lib -e normal +``` + +Ne jamais déclarer une commande réussie sans preuve opérateur ou exécution réelle.