From 79b67f8eaecced295848146ce59bee62c909cfc6 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Mon, 17 Aug 2026 22:43:07 +0200 Subject: [PATCH] v0.2.1-pre.007 --- Cargo.toml | 4 +- ROADMAP.md | 6 +- config/std.logging.json | 8 +- crates/ksp-config-lib/Cargo.toml | 5 +- crates/ksp-config-lib/README.md | 4 +- .../tests/transport_devnet_smoke.rs | 32 ++ crates/ksp-onchain-transport-lib/README.md | 135 ++++++ crates/ksp-onchain-transport-lib/USAGE.md | 164 +++++++ .../tests/release_completeness.rs | 48 ++ deltas/0.2.1/pre.007.md | 310 +++++++++++++ docs/000-README.md | 7 +- docs/architecture/004-COMPONENT_INVENTORY.md | 6 +- docs/plans/000-README.md | 4 +- docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md | 4 +- docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md | 42 +- docs/rules/FILE_CONTRACTS.md | 4 +- docs/validation/000-README.md | 3 +- docs/validation/003-V0_2_1_ONCHAIN_HTTP.md | 194 ++++++++ prompts/000-README.md | 10 +- prompts/007-V0_2_2_START_PROMPT.md | 431 ++++++++++++++++++ 20 files changed, 1379 insertions(+), 42 deletions(-) create mode 100644 crates/ksp-config-lib/tests/transport_devnet_smoke.rs create mode 100644 crates/ksp-onchain-transport-lib/README.md create mode 100644 crates/ksp-onchain-transport-lib/USAGE.md create mode 100644 crates/ksp-onchain-transport-lib/tests/release_completeness.rs create mode 100644 deltas/0.2.1/pre.007.md create mode 100644 docs/validation/003-V0_2_1_ONCHAIN_HTTP.md create mode 100644 prompts/007-V0_2_2_START_PROMPT.md diff --git a/Cargo.toml b/Cargo.toml index badc1a0..7de7f81 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 107 +# version: 108 [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.1-pre.6.fix.2" +version = "0.2.1-pre.7" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index ce58804..0018964 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -41,11 +41,11 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U ### Cadrage - [X] `0.2.0` — Audit bot3, ordre fonctionnel de `0.2.x`, architecture durable, discipline de sizing et pipeline RAW/CORE/DECODE/SPECIALIZED stabilisés. -- [/] `0.2.1` — HTTP foundation en cours : matrice 52+14, runtime/routing/résilience/exécution HTTP et 4 canaris typés acquis ; `std.transport` et l’adapter Config -> Transport sont matérialisés, la compliance/smoke/documentation de clôture reste planifiée. +- [/] `0.2.1` — HTTP foundation fonctionnellement complète dans la candidate de clôture : matrice 52+14, runtime/routing/résilience/exécution HTTP, 4 canaris typés, `std.transport`, adapter Config -> Transport, canaries de clôture, smoke Devnet opt-in et documentation durable sont matérialisés ; seule la publication stable `rel.001` reste à valider. ### Releases fonctionnelles décidées/pressenties -- [/] `0.2.1` — **HTTP transport foundation réduite par le gate `pre.001`** : crate/settings/JSON-RPC/registry exhaustif 52 current + 14 deprecated historiques, pool/rôles/limites/retry/Config adapter, et 4 méthodes typées canari (`getBalance`, `getGenesisHash`, `getHealth`, `getVersion`). +- [/] `0.2.1` — **HTTP transport foundation réduite par le gate `pre.001`** : surface candidate de release complète ; 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`) ; publication stable encore en attente. - [ ] `0.2.2` — Compléter HTTP Accounts + Tokens + Cluster : 5 méthodes Accounts restantes + 5 Tokens + 12 Cluster restantes, soit 22 méthodes. - [ ] `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. diff --git a/config/std.logging.json b/config/std.logging.json index ab9cce4..93b2f2e 100644 --- a/config/std.logging.json +++ b/config/std.logging.json @@ -41,14 +41,14 @@ } }, { - "output_id": "file.onchain_transport.debug", + "output_id": "file.onchain_transport.info", "enabled": true, - "path": "transport/onchain/ksp-onchain-transport-debug.log", + "path": "transport/onchain/ksp-onchain-transport.log", "rotation": "daily", "format": "human", "ansi": false, "filter": { - "level": "debug", + "level": "info", "targets": [ "ksp-onchain-transport-lib" ], @@ -90,7 +90,7 @@ }, { "target_prefix": "ksp-onchain-transport-lib", - "level": "debug" + "level": "info" } ] } diff --git a/crates/ksp-config-lib/Cargo.toml b/crates/ksp-config-lib/Cargo.toml index c00564c..b276517 100644 --- a/crates/ksp-config-lib/Cargo.toml +++ b/crates/ksp-config-lib/Cargo.toml @@ -1,5 +1,5 @@ # file: crates/ksp-config-lib/Cargo.toml -# version: 5 +# version: 6 [package] name = "ksp-config-lib" @@ -15,5 +15,8 @@ serde = { workspace = true, features = ["derive"] } serde_json.workspace = true jsonschema.workspace = true +[dev-dependencies] +tokio = { workspace = true, features = ["macros", "rt"] } + [lints] workspace = true diff --git a/crates/ksp-config-lib/README.md b/crates/ksp-config-lib/README.md index dd9436d..614dc2e 100644 --- a/crates/ksp-config-lib/README.md +++ b/crates/ksp-config-lib/README.md @@ -1,5 +1,5 @@ - + # ksp-config-lib @@ -70,7 +70,7 @@ La dépendance inverse est interdite : `ksp-core-lib`, `ksp-logging-lib` et `ksp Config ne possède pas le `LoggingGuard`. L'application ou le service qui orchestre le runtime construit la configuration effective puis possède le lifecycle `ksp_logging_lib::initialize/reinitialize`. -Tauri et les DTO TS-RS restent hors de cette crate. La future `ksp-app-config-desk` doit rester une frontière applicative mince au-dessus des APIs Config. +Tauri et les DTO TS-RS restent hors de cette crate. `ksp-app-config-desk` reste une frontière applicative mince au-dessus des APIs Config et découvre les documents standards via le registre Config sans déplacer leur logique métier dans l'application. ## Secrets diff --git a/crates/ksp-config-lib/tests/transport_devnet_smoke.rs b/crates/ksp-config-lib/tests/transport_devnet_smoke.rs new file mode 100644 index 0000000..b0805b3 --- /dev/null +++ b/crates/ksp-config-lib/tests/transport_devnet_smoke.rs @@ -0,0 +1,32 @@ +// file: crates/ksp-config-lib/tests/transport_devnet_smoke.rs +// version: 1 + +//! Opt-in live Devnet smoke for the Config -> Transport foundation path. + +#[tokio::test(flavor = "current_thread")] +#[ignore = "opt-in live Solana Devnet smoke; performs external network requests"] +async fn committed_devnet_transport_profile_reaches_all_foundation_canaries() { + let workspace = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../.."); + let bootstrap = ksp_config_lib::ConfigBootstrapOptions::from_paths(workspace.join("config"), workspace.join("config/schemas")) + .expect("committed Config roots must be valid"); + let registry = ksp_config_lib::ConfigFileRegistry::defaults().expect("default Config registry must be valid"); + let engine = ksp_config_lib::ConfigDocumentEngine::new(bootstrap, registry); + let environment = ksp_config_lib::ConfigEnvironment::load().expect("Config must capture the opt-in smoke environment"); + let resolved = engine + .load_resolved_transport_config(std::option::Option::Some("devnet_public"), &environment) + .expect("committed devnet_public Transport profile must resolve"); + assert_eq!(resolved.profile_id(), "devnet_public"); + let pool = ksp_onchain_transport_lib::HttpTransportPool::new(resolved.into_settings()).expect("resolved Transport settings must construct the HTTP pool"); + let role = ksp_onchain_transport_lib::HttpRoleName::new("default"); + let health = pool.get_health(&role).await.expect("Devnet getHealth smoke must succeed"); + assert_eq!(health, ksp_onchain_transport_lib::SolanaNodeHealth::Healthy); + let genesis_hash = pool.get_genesis_hash(&role).await.expect("Devnet getGenesisHash smoke must succeed"); + assert!(!genesis_hash.as_str().is_empty()); + let version = pool.get_version(&role).await.expect("Devnet getVersion smoke must succeed"); + assert!(!version.solana_core().is_empty()); + let balance = pool + .get_balance(&role, &ksp_core_lib::PRGIDPK_SOLANA_SYSTEM, std::option::Option::None) + .await + .expect("Devnet getBalance smoke must succeed"); + assert!(balance.context().slot() > 0); +} diff --git a/crates/ksp-onchain-transport-lib/README.md b/crates/ksp-onchain-transport-lib/README.md new file mode 100644 index 0000000..f8eefe9 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/README.md @@ -0,0 +1,135 @@ + + + +# `ksp-onchain-transport-lib` + +`ksp-onchain-transport-lib` est la bibliothèque KSP propriétaire du transport on-chain Solana. Sa première surface est le transport HTTP JSON-RPC ; les extensions WebSocket et gRPC sont introduites séparément lorsque leur release les cible. + +## Responsabilités + +La crate possède : + +- les settings runtime HTTP publics ; +- les endpoints nommés et leurs metadata provider/cluster ; +- les rôles, capabilities/request kinds et priorités ; +- la sélection/fairness/fallback du pool ; +- les limites RPS/burst/concurrence et le cooldown ; +- les deadlines et timeouts ; +- le retry/backoff borné et la règle no-resend après dispatch ambigu ; +- les enveloppes JSON-RPC 2.0 et leur validation ; +- le registre audité des méthodes Solana HTTP ; +- l'exécution générique des méthodes standard supportées ; +- les wrappers typés explicitement livrés par KSP ; +- les snapshots runtime sûrs ; +- l'observabilité Transport via `ksp-logging-lib`. + +La crate ne possède ni documents Config, ni persistence Store, ni modèles Program/métier. + +## Frontières de dépendances + +La direction autorisée est : + +```text +ksp-config-lib + -> ksp-onchain-transport-lib + -> ksp-core-lib + -> ksp-logging-lib + -> reqwest / tokio / serde +``` + +La direction inverse est interdite : + +```text +ksp-onchain-transport-lib -X-> ksp-config-lib +ksp-onchain-transport-lib -X-> Store +ksp-onchain-transport-lib -X-> Program +ksp-onchain-transport-lib -X-> tracing direct +``` + +`ksp-config-lib` peut donc charger `std.transport.json` et construire `HttpTransportSettings`, tandis que Transport reste directement utilisable par un consumer qui fournit lui-même ses settings. + +## Surface HTTP standard + +Le registre KSP conserve deux inventaires distincts : + +```text +52 méthodes HTTP courantes +14 méthodes historiques Deprecated / runtime Removed +``` + +Le registre porte notamment : + +- catégorie ; +- request kind ; +- statut documentaire ; +- statut runtime ; +- forme de requête stable/legacy ; +- type d'opération ; +- classe de retry ; +- remplacement historique éventuel ; +- release de couverture typée KSP. + +Les quatre wrappers typés de la foundation sont : + +```text +getBalance +getGenesisHash +getHealth +getVersion +``` + +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 14 méthodes historiques restent découvrables pour la compliance mais sont `Removed` et ne sont pas simulées comme appelables. + +## Résilience + +L'admission est calculée par couple endpoint/rôle. Le pool applique : + +1. rôle et capability ; +2. priorité croissante ; +3. round-robin dans le meilleur tier ; +4. RPS/burst ; +5. concurrence ; +6. cooldown rate-limit ; +7. fallback vers les pairs puis les tiers inférieurs ; +8. deadline commune à l'opération et ses retries. + +Les retries ne sont autorisés que lorsque la metadata de méthode et l'état de dispatch les rendent sûrs. `WriteSubmission / NeverAfterDispatch` interdit tout resend automatique après un dispatch ambigu. + +Les erreurs JSON-RPC applicatives ne sont pas transformées en retries transport génériques. + +## Sécurité et diagnostics + +Les URLs d'endpoint peuvent contenir des credentials. Elles ne sont donc pas exposées par les `Debug`, snapshots ou logs ordinaires. + +Les `reqwest::Error` attachées comme source sont neutralisées avec `without_url()` avant exposition dans le contrat d'erreur KSP. + +Le target de tracing est possédé explicitement par : + +```text +src/constants.rs +TRACING_TARGET = "ksp-onchain-transport-lib" +``` + +La configuration Logging de référence conserve un fichier dédié Transport à niveau `info`. Un niveau `debug`/`trace` ciblé peut être réactivé temporairement via Config lors d'un développement ou diagnostic explicite. + +## Tests + +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 : + +```text +Config -> std.transport/devnet_public -> HttpTransportPool + -> getHealth/getGenesisHash/getVersion/getBalance +``` + +Il est `ignored` par défaut et doit être exécuté explicitement. + +## 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 ; +- [`../../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 new file mode 100644 index 0000000..f5f174d --- /dev/null +++ b/crates/ksp-onchain-transport-lib/USAGE.md @@ -0,0 +1,164 @@ + + + +# Utilisation de `ksp-onchain-transport-lib` + +Ce guide présente les surfaces publiques destinées aux consumers. Les notes de release restent dans `CHANGELOG.md` et les deltas. + +## 1. Construction directe du runtime + +Transport peut être utilisé sans Config. Le consumer construit les settings publics puis le pool : + +```rust +let url = match ksp_onchain_transport_lib::HttpEndpointUrl::parse("https://api.devnet.solana.com") { + Ok(value) => value, + Err(error) => return Err(error), +}; +let role = ksp_onchain_transport_lib::HttpEndpointRoleSettings::new( + ksp_onchain_transport_lib::HttpRoleName::new("default"), + true, + vec![ksp_onchain_transport_lib::HttpRequestKind::wildcard()], + 100, + ksp_onchain_transport_lib::HttpRoleLimits::new(None, None, None, None), +); +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"), + url, + std::time::Duration::from_secs(5), + std::time::Duration::from_secs(15), + Some(8), + vec![role], +); +let settings = ksp_onchain_transport_lib::HttpTransportSettings::new( + vec![endpoint], + ksp_onchain_transport_lib::HttpRetrySettings::new( + 2, + std::time::Duration::from_millis(100), + std::time::Duration::from_secs(2), + ), +); +let pool = match ksp_onchain_transport_lib::HttpTransportPool::new(settings) { + Ok(value) => value, + Err(error) => return Err(error), +}; +``` + +`HttpTransportSettings::validate()` peut être appelé explicitement avant la construction du pool lorsque le consumer veut séparer validation et initialisation. + +## 2. Construction via `ksp-config-lib` + +Lorsque le consumer utilise Config, la direction reste Config -> Transport : + +```rust +let resolved = match engine.load_resolved_transport_config(Some("devnet_public"), &environment) { + Ok(value) => value, + Err(error) => return Err(error), +}; +let pool = match ksp_onchain_transport_lib::HttpTransportPool::new(resolved.into_settings()) { + Ok(value) => value, + Err(error) => return Err(error), +}; +``` + +Le document standard peut contenir une URL provenant d'un `KSP_SECRET_*`. La valeur réelle est transmise au runtime, mais les projections sûres et `Debug` restent redacted. + +## 3. Appels typés + +Les wrappers typés se trouvent directement sur `HttpTransportPool`. + +```rust +let role = ksp_onchain_transport_lib::HttpRoleName::new("default"); +let health = pool.get_health(&role).await; +let genesis_hash = pool.get_genesis_hash(&role).await; +let version = pool.get_version(&role).await; +let balance = pool + .get_balance( + &role, + &ksp_core_lib::PRGIDPK_SOLANA_SYSTEM, + Some(&ksp_onchain_transport_lib::GetBalanceConfig::new( + Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed), + None, + )), + ) + .await; +``` + +Les types de retour associés sont : + +```text +SolanaNodeHealth +SolanaGenesisHash +SolanaNodeVersion +GetBalanceResult +SolanaRpcContext +``` + +`GetBalanceResult::value()` renvoie les lamports et `context()` fournit le slot/API version retournés par Solana. + +## 4. Exécution JSON-RPC standard générique + +Une méthode courante auditée peut être appelée via son descriptor : + +```rust +if let Some(descriptor) = ksp_onchain_transport_lib::find_http_rpc_method("getSlot") { + let _result = pool.execute_standard_rpc(&role, descriptor, vec![]).await; +} +``` + +Cette API retourne un `serde_json::Value`. Elle est utile pour les consumers techniques et pour préparer les futures surfaces typées, mais elle ne remplace pas le wrapper typé d'une méthode dans la matrice de couverture KSP. + +Avant exécution, `ensure_runtime_supported()` est appliqué. Une méthode historique `Removed` retourne `ERROR_CODE_METHOD_REMOVED` au lieu d'émettre un appel réseau fictif. + +## 5. Sélection et admission sans exécuter la requête + +Pour inspecter le routing : + +```rust +if let Some(descriptor) = ksp_onchain_transport_lib::find_http_rpc_method("getBalance") { + let _selection = pool.select_for_method(&role, descriptor); + let _permit = pool.acquire_for_method(&role, descriptor).await; +} +``` + +Dans le même bloc, `acquire_for_method()` réserve réellement la capacité RPS/concurrence sous deadline. + +`HttpRequestPermit` détient la capacité de concurrence jusqu'à sa destruction. Aucun verrou synchrone n'est conservé pendant l'attente réseau. + +## 6. Snapshots runtime + +`HttpTransportPool::snapshot()` fournit une vue sûre des endpoints/rôles : disponibilité, limites, requêtes en vol, cooldown restant et compteurs runtime. + +Les URLs d'endpoint n'y apparaissent jamais. + +## 7. Retry et write submissions + +La policy de retry est portée par la metadata des méthodes et `evaluate_transport_retry()`. + +Les reads/simulations classés `RetrySafe` peuvent être réessayés dans le budget configuré lorsqu'une cause transport est explicitement retryable. + +Pour une opération `WriteSubmission / NeverAfterDispatch`, un timeout ou autre résultat ambigu après dispatch arrête la resoumission automatique. Le consumer métier ne doit pas contourner cette protection avec une boucle de retry externe aveugle. + +## 8. Logging + +Les événements Transport utilisent le target : + +```text +ksp-onchain-transport-lib +``` + +Ne jamais journaliser l'URL complète, un token provider, un body massif, une transaction complète ou une réponse complète. + +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 + +Le smoke live est volontairement hors des tests par défaut : + +```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. diff --git a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs new file mode 100644 index 0000000..e420aa3 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs @@ -0,0 +1,48 @@ +// file: crates/ksp-onchain-transport-lib/tests/release_completeness.rs +// version: 1 + +//! Release-level completeness canaries for the `0.2.1` HTTP foundation contract. + +#[test] +fn release_registry_partition_matches_the_audited_http_plan() { + let mut foundation = 0_usize; + let mut accounts_tokens_cluster = 0_usize; + let mut transactions = 0_usize; + let mut blocks_economics = 0_usize; + let mut historical_in_current = 0_usize; + for descriptor in ksp_onchain_transport_lib::current_http_rpc_methods() { + match descriptor.coverage_release() { + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_1 => foundation += 1, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_2 => accounts_tokens_cluster += 1, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_3 => transactions += 1, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_4 => blocks_economics += 1, + ksp_onchain_transport_lib::HttpRpcCoverageRelease::Historical => historical_in_current += 1, + } + } + assert_eq!(ksp_onchain_transport_lib::current_http_rpc_methods().len(), 52); + assert_eq!(ksp_onchain_transport_lib::historical_http_rpc_methods().len(), 14); + assert_eq!(foundation, 4); + assert_eq!(accounts_tokens_cluster, 22); + assert_eq!(transactions, 11); + assert_eq!(blocks_economics, 15); + assert_eq!(historical_in_current, 0); +} + +#[test] +fn release_foundation_canaries_and_historical_statuses_are_exact() { + let mut foundation_names = std::vec::Vec::<&str>::new(); + for descriptor in ksp_onchain_transport_lib::current_http_rpc_methods() { + if descriptor.coverage_release() == ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_1 { + foundation_names.push(descriptor.method()); + assert_eq!(descriptor.runtime_status(), ksp_onchain_transport_lib::RpcRuntimeStatus::Supported); + } + } + foundation_names.sort_unstable(); + assert_eq!(foundation_names, std::vec!["getBalance", "getGenesisHash", "getHealth", "getVersion"]); + for descriptor in ksp_onchain_transport_lib::historical_http_rpc_methods() { + assert_eq!(descriptor.documentation_status(), ksp_onchain_transport_lib::RpcDocumentationStatus::Deprecated); + assert_eq!(descriptor.runtime_status(), ksp_onchain_transport_lib::RpcRuntimeStatus::Removed); + assert_eq!(descriptor.coverage_release(), ksp_onchain_transport_lib::HttpRpcCoverageRelease::Historical); + assert_eq!(descriptor.transport_retry_class(), ksp_onchain_transport_lib::TransportRetryClass::NotApplicable); + } +} diff --git a/deltas/0.2.1/pre.007.md b/deltas/0.2.1/pre.007.md new file mode 100644 index 0000000..46cc9ba --- /dev/null +++ b/deltas/0.2.1/pre.007.md @@ -0,0 +1,310 @@ + + + +# Delta `v0.2.1-pre.007` + +## Base + +Base attendue : + +```text +v0.2.1-pre.006-fix.002 +``` + +Cette base a été validée localement par l'opérateur le 2026-08-17 avec : + +- `cargo fmt --all` ; +- `cargo check --workspace` ; +- `cargo clippy --workspace --all-targets` ; +- `cargo test -p ksp-onchain-transport-lib` ; +- `cargo test -p ksp-app-config-desk` ; +- `cargo test -p ksp-config-lib` ; +- `cargo test -p ksp-core-lib` ; +- `cargo test --workspace`. + +Le test Transport renforcé contre la fuite d'URL dans les sources `reqwest::Error` passe également sur cette base. + +Version Cargo cible : + +```text +0.2.1-pre.7 +``` + +## Objectif + +Fermer la dernière prerelease fonctionnelle de `0.2.1` sans rouvrir le périmètre HTTP : + +- revérifier la matrice officielle Solana ; +- figer la complétude `52 + 14` et la partition `4 / 22 / 11 / 15` par des canaries publiques ; +- fournir un smoke Devnet opt-in de bout en bout Config -> Transport ; +- produire le README et le guide d'utilisation durables de Transport ; +- remettre la baseline Logging Transport à `info` avant stable ; +- absorber les écarts documentaires réservés par l'audit complet de `pre.006-fix.002` ; +- produire la matrice de validation finale et le prompt de démarrage `0.2.2` ; +- préparer un `rel.001` strictement publicationnel. + +Aucune cinquième méthode HTTP typée n'est ajoutée dans cette tranche. + +## Revérification officielle HTTP Solana + +La documentation officielle Solana a été revérifiée le 2026-08-17 : + +```text +https://solana.com/docs/rpc/http +https://solana.com/docs/rpc/deprecated/confirmtransaction +``` + +Le résultat reste compatible avec la matrice acquise : + +```text +52 méthodes HTTP courantes +14 méthodes historiques Deprecated +``` + +L'index courant confirme également le transport JSON-RPC 2.0 sur HTTP `POST` avec `Content-Type: application/json`. + +Les 14 méthodes historiques restent représentées dans KSP comme `Deprecated / Removed / Historical` et ne sont pas simulées comme appelables. + +## Canaries de complétude de release + +Nouveau test public : + +```text +crates/ksp-onchain-transport-lib/tests/release_completeness.rs +``` + +Il fige depuis l'API publique : + +```text +current == 52 +historical == 14 +coverage == 4 / 22 / 11 / 15 +V0_2_1 == getBalance/getGenesisHash/getHealth/getVersion +historical => Deprecated + Removed + Historical + NotApplicable +``` + +La candidate déclare désormais **80 tests Transport**. + +La surface raw/générique `execute_standard_rpc()` reste disponible mais ne compte pas comme couverture typée des 48 méthodes reportées à `0.2.2`–`0.2.4`. + +## Smoke Devnet opt-in Config -> Transport + +Nouveau test : + +```text +crates/ksp-config-lib/tests/transport_devnet_smoke.rs +``` + +Il est volontairement : + +```rust +#[ignore = "opt-in live Solana Devnet smoke; performs external network requests"] +``` + +Le chemin validé est : + +```text +ConfigFileRegistry::defaults() + -> cfg.std.transport + -> profile devnet_public + -> ConfigEnvironment + -> ResolvedTransportConfig + -> HttpTransportSettings + -> HttpTransportPool + -> getHealth + -> getGenesisHash + -> getVersion + -> getBalance(System Program) +``` + +Transport ne lit donc toujours pas directement l'environnement. + +Le test Config nécessite Tokio uniquement comme dev-dependency local : + +```toml +[dev-dependencies] +tokio = { workspace = true, features = ["macros", "rt"] } +``` + +La candidate déclare **114 tests Config**, dont cet unique smoke Devnet `ignored`. + +Exécution opt-in : + +```bash +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Un incident ou rate-limit du RPC public Devnet reste un signal externe à analyser ; les gates reproductibles restent les tests déterministes par défaut. + +## Logging Transport avant stable + +Le sink dédié introduit pendant le développement est conservé, mais sa baseline revient de `debug` à `info` conformément à la politique de clôture : + +```text +output_id : file.onchain_transport.info +path : transport/onchain/ksp-onchain-transport.log +target : ksp-onchain-transport-lib +level : info +``` + +La console et le fichier général restent à `info`. Un niveau `debug`/`trace` ciblé peut être réactivé temporairement via Config lors d'un futur développement, puis doit être refermé avant publication stable. + +## Documentation durable Transport + +Nouveaux documents : + +```text +crates/ksp-onchain-transport-lib/README.md +crates/ksp-onchain-transport-lib/USAGE.md +``` + +Ils documentent : + +- responsabilités et firewall de dépendances ; +- registre `52 current + 14 historical` ; +- différence raw/générique vs couverture typée ; +- quatre canaris `0.2.1` ; +- pool/routing/admission/résilience ; +- retry/no-resend ; +- sécurité des URLs et sources `reqwest` ; +- target Logging explicite ; +- construction directe ou via Config ; +- snapshots et smoke Devnet opt-in. + +## Normalisation documentaire issue de l'audit complet + +Les écarts purement documentaires réservés par `pre.006-fix.002` sont absorbés ici : + +- `FILE-GEN-003` décrit désormais `bindings/` et `gen/` comme artefacts générés/reconstructibles ignorés par défaut, et non comme convention encore future ; +- `crates/ksp-config-lib/README.md` ne présente plus `ksp-app-config-desk` comme future ; +- l'inventaire des composants décrit `0.2.1` comme foundation HTTP + registre `52+14` + quatre wrappers canari, et non comme surface typed HTTP complète ; +- les index docs/plans/validation/prompts sont synchronisés avec les nouveaux livrables ; +- le ROADMAP conserve uniquement l'état synthétique de la candidate et reste `[/]` jusqu'à la publication stable. + +Les prompts et deltas historiques consommés restent immuables même lorsqu'ils décrivent l'état de leur époque. + +## Matrice de validation finale + +Nouveau document : + +```text +docs/validation/003-V0_2_1_ONCHAIN_HTTP.md +``` + +Il regroupe les critères de clôture, les preuves acquises, les commandes Cargo/cargo-tree attendues et les conditions de passage à `rel.001`. + +## Prompt de reprise `0.2.2` + +Nouveau prompt : + +```text +prompts/007-V0_2_2_START_PROMPT.md +``` + +Il ouvre `0.2.2 — HTTP Accounts + Tokens + Cluster` par un nouveau `pre.001` d'audit/brainstorming/sizing et conserve la partition nominale actuelle de 22 méthodes : + +```text +Accounts : 5 +Tokens : 5 +Cluster : 12 +``` + +Il exige une revérification officielle du jour avant toute implémentation lourde et rappelle que l'appel raw ne vaut jamais couverture typée. + +## Préparation de `rel.001` + +`CHANGELOG.md` n'est volontairement pas modifié dans cette prerelease. Si la candidate passe les validations opérateur, `rel.001` doit rester minimal : + +```text +workspace.package.version -> 0.2.1 +ROADMAP : 0.2.1 -> [X] +CHANGELOG : synthèse stable 0.2.1 +plan 008 / validation 003 : statut clôturé + preuves opérateur +deltas/0.2.1/rel.001.md +commit v0.2.1-rel.001 +tag v0.2.1 +``` + +Aucune nouvelle fonctionnalité HTTP ne doit être introduite dans `rel.001`. + +## Fichiers ajoutés + +```text +crates/ksp-config-lib/tests/transport_devnet_smoke.rs +crates/ksp-onchain-transport-lib/README.md +crates/ksp-onchain-transport-lib/USAGE.md +crates/ksp-onchain-transport-lib/tests/release_completeness.rs +docs/validation/003-V0_2_1_ONCHAIN_HTTP.md +prompts/007-V0_2_2_START_PROMPT.md +deltas/0.2.1/pre.007.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +ROADMAP.md +config/std.logging.json +crates/ksp-config-lib/Cargo.toml +crates/ksp-config-lib/README.md +docs/000-README.md +docs/architecture/004-COMPONENT_INVENTORY.md +docs/plans/000-README.md +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md +docs/rules/FILE_CONTRACTS.md +docs/validation/000-README.md +prompts/000-README.md +``` + +Aucun ancien delta et aucun `CHANGELOG.md` ne sont modifiés. + +## Validation statique de génération + +Effectuée dans le sandbox : + +- comparaison différentielle avec `pre.006-fix.002` ; +- parsing de tous les TOML et JSON du workspace ; +- validation Draft 2020-12 de `std.logging.json`, `std.transport.json` et de l'exemple Transport contre leurs schemas ; +- contrôle des headers et incréments de version des fichiers modifiés ; +- contrôle de l'unique fin de ligne des fichiers livrés ; +- contrôle des lignes Rust/TOML <= 160 colonnes ; +- contrôle des fences Markdown et des liens Markdown relatifs des fichiers modifiés ; +- confirmation que les anciens deltas sont byte-for-byte inchangés ; +- contrôle de la baseline Logging Transport `info` ; +- comptage statique de 80 tests Transport et 114 tests Config, dont un smoke Config `ignored` ; +- contrôle des tableaux de registre Rust `[52]` et `[14]`. + +Non exécutées dans le sandbox : `cargo`, `rustc` et `rustfmt` n'y sont pas disponibles. Aucune réussite Cargo de `pre.007` n'est donc déclarée avant validation opérateur. + +## Validation requise après application + +```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, de manière opt-in : + +```bash +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Les `cargo tree` Config sont requis car `pre.007` ajoute un dev-dependency Tokio local au smoke live. Si les validations déterministes et les audits de graphe sont propres, la tranche suivante est `0.2.1-rel.001`. diff --git a/docs/000-README.md b/docs/000-README.md index 48d3f0f..e7e56b4 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -44,7 +44,8 @@ docs/ ├── validation/ │ ├── 000-README.md │ ├── 001-V0_1_4_CONFIG_DESKTOP.md -│ └── 002-V0_2_0_SERIES_PLANNING.md +│ ├── 002-V0_2_0_SERIES_PLANNING.md +│ └── 003-V0_2_1_ONCHAIN_HTTP.md └── rules/ ├── FILE_CONTRACTS.md ├── PROMPT_STRUCTURE.md @@ -61,7 +62,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). `0.2.1` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son `pre.001` applique le gate de sizing, crée le plan actif [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md) et produit d'abord un split HTTP sur `0.2.1`–`0.2.6`. `0.2.1-pre.001-fix.001` recalibre ensuite ce split sur `0.2.1`–`0.2.4` sans perdre l'inventaire exhaustif, et précise que plusieurs releases peuvent être enchaînées dans un même chat si chacune est clôturée séparément et si le sizing de la suivante reste positif. +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). `0.2.1` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son `pre.001` applique le gate de sizing et crée [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md); `pre.001-fix.001` recalibre la couverture typed sur `0.2.1`–`0.2.4` sans perdre l'inventaire exhaustif. `pre.007` prépare maintenant la clôture de la foundation avec [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport, smoke Devnet opt-in et [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md). `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 a5a4431..f2466c7 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -23,7 +23,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse | 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` | JSON-RPC HTTP complet, settings, pools, rôles | +| 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 | @@ -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. 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 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. 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 600168d..a401197 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -16,7 +16,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`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 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 actif de `0.2.1`, établi par `0.2.1-pre.001` puis recalibré par `0.2.1-pre.001-fix.001`; il contient l'inventaire officiel 52 méthodes HTTP courantes + 14 Deprecated historiques, l'audit bot3, le design Transport/Config et le split courant de la couverture HTTP sur `0.2.1`–`0.2.4`, avec enchaînement possible de releases dans une même session sous gate de sizing. +- [`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`. 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 69c7cbe..56d1745 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 @@ -378,7 +378,7 @@ Mission : créer `ksp-onchain-transport-lib` avec la foundation HTTP JSON-RPC in Inclure : settings publics ; endpoint/provider/cluster ; pool logique ; rôles/capabilities/request kinds ouverts ; priorités/limites/concurrence ; timeout/retry/backoff ; JSON-RPC ; metadata centrale de statut méthode + forme de requête + runtime ; warning centralisé lorsqu'un contrat supported est deprecated/unstable ; document Config standard + adapter Config -> Transport ; `getBalance`, `getGenesisHash`, `getHealth`, `getVersion`. -Le plan détaillé actif est `docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`. Un appel raw/générique ne compte pas comme couverture typée des méthodes reportées. +Le plan détaillé actif est `docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`. `pre.007` clôt la surface candidate avec canaries de complétude, smoke Devnet opt-in Config -> Transport, README/USAGE et prompt `0.2.2`. Un appel raw/générique ne compte pas comme couverture typée des méthodes reportées. ## `0.2.2` à `0.2.4` — complétude HTTP Solana diff --git a/docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md b/docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md index 15028ce..42e489e 100644 --- a/docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md +++ b/docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md @@ -1,5 +1,5 @@ - + # `0.2.1-pre.001` — plan `ksp-onchain-transport-lib` HTTP Solana foundation @@ -7,6 +7,8 @@ Ce document ouvre `0.2.1` à partir de la base stable fournie `0.2.0` et exécute le gate de sizing imposé par le prompt `006` avant toute grosse implémentation. Sa version initiale appartient à `0.2.1-pre.001`; le split de releases présenté dans cette version du plan est le recalibrage documentaire de `0.2.1-pre.001-fix.001`. +> **État `pre.007` : candidate de clôture.** La foundation HTTP réduite est fonctionnellement matérialisée ; `pre.007` ajoute les canaries finales, le smoke Devnet opt-in, README/USAGE, la matrice de validation durable et le prompt `0.2.2`. La publication stable reste séparée dans `rel.001` après validations opérateur. + Conclusion du gate : ```text @@ -766,7 +768,7 @@ Interdits par défaut : Les erreurs `reqwest` utiles sont remappées/réémises via `ksp-logging-lib`; aucun target externe n'est activé globalement par Transport. -Pendant le développement actif de `0.2.1`, `std.logging.json` conserve sa baseline générale à `info` mais autorise `debug` uniquement pour `ksp-onchain-transport-lib` et route ces événements vers un fichier dédié `transport/onchain/ksp-onchain-transport-debug.log`. La console et `file.all.info` restent à `info`. Ce routage ciblé suit `DEP-LOG-012` et évite de placer tout le profil en `debug`. Conformément à `KSP-APP-031`, la dernière tranche de clôture réévalue cette verbosité et la ramène à `info`/`warn` avant la stable, sauf justification opératoire explicite. +Pendant le développement actif jusqu'à `pre.006`, `std.logging.json` autorisait `debug` uniquement pour `ksp-onchain-transport-lib` et routait ces événements vers un fichier dédié. `pre.007` applique `KSP-APP-031` : le target et le sink dédié reviennent à `info`, avec le fichier `transport/onchain/ksp-onchain-transport.log`. La console et `file.all.info` restent également à `info`. Un développement/correctif futur peut relever temporairement uniquement ce target/sink via Config Desk conformément à `DEP-LOG-012`. ## 19. Architecture de tests @@ -871,15 +873,15 @@ La release peut devenir stable seulement si : ## 22. Prévision souple des prereleases de la `0.2.1` réduite -| Tranche | Objectif | -|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `pre.001` | audit KSP + bot3 + docs officielles, matrice 52+14, architecture, split et sizing | -| `pre.002` | **réalisé** : crate/workspace, codes erreur, settings/validation, JSON-RPC, descriptors/status, base Logging | -| `pre.003` | **réalisé** : endpoint client + pool logique + rôles/capabilities + priorité/fairness/fallback + snapshots sûrs | -| `pre.004` | **réalisé** : RPS/burst/concurrence/cooldown + deadline commune + retry/backoff + classification retry/no-resend | -| `pre.005` | **réalisé** : exécution HTTP JSON-RPC + `getHealth`, `getVersion`, `getGenesisHash`, `getBalance` + fixtures déterministes + centralisation des canaries workspace dans Core | -| `pre.006` | **réalisé** : `std.transport` schema/document/example + registry Config + adapter Config -> Transport + sensibilité/provenance/env tests | -| `pre.007` | completeness/canaries, smoke opt-in, `cargo tree`, README/USAGE, docs finales, prompt `0.2.2`, préparation `rel.001` | +| Tranche | Objectif | +|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `pre.001` | audit KSP + bot3 + docs officielles, matrice 52+14, architecture, split et sizing | +| `pre.002` | **réalisé** : crate/workspace, codes erreur, settings/validation, JSON-RPC, descriptors/status, base Logging | +| `pre.003` | **réalisé** : endpoint client + pool logique + rôles/capabilities + priorité/fairness/fallback + snapshots sûrs | +| `pre.004` | **réalisé** : RPS/burst/concurrence/cooldown + deadline commune + retry/backoff + classification retry/no-resend | +| `pre.005` | **réalisé** : exécution HTTP JSON-RPC + `getHealth`, `getVersion`, `getGenesisHash`, `getBalance` + fixtures déterministes + centralisation des canaries workspace dans Core | +| `pre.006` | **réalisé** : `std.transport` schema/document/example + registry Config + adapter Config -> Transport + sensibilité/provenance/env tests | +| `pre.007` | **réalisé côté livraison candidate** : completeness/canaries, smoke opt-in, README/USAGE, docs finales, prompt `0.2.2`, préparation `rel.001`; `cargo tree`/Cargo restent à valider opérateur | Ce découpage est révisable si une tranche dépasse le budget ; la release réduite, contrairement au scope initial, reste raisonnablement clôturable dans la session. @@ -972,7 +974,23 @@ Restent à `pre.006` : document/schema/exemple `std.transport`, enregistrement C `pre.006-fix.002`, déclenché par l’audit complet du workspace avant clôture, corrige une fuite diagnostique potentielle : les `reqwest::Error` attachées à `ksp_core_lib::Error` sont désormais neutralisées par `without_url()` avant `with_source`, avec une canarie timeout portant un secret dans la query de l’endpoint. Le même audit remet aussi en conformité les fins de ligne des fichiers courants concernés par `GEN-FILE-005` et corrige le rustdoc Transport devenu obsolète après l’introduction de l’adapter Config -> Transport. Les écarts purement documentaires sans impact code/config restent volontairement réservés à `pre.007`. -Restent à `pre.007` : completeness/canaries finales, smoke réseau opt-in, audit `cargo tree`, README/USAGE, documentation de clôture, prompt `0.2.2` et préparation de `rel.001`. +### 22.6 État candidat après `0.2.1-pre.007` + +`pre.007` ferme le périmètre de développement de la foundation sans ajouter de méthode HTTP typed au-delà des quatre canaris : + +- `workspace.package.version = 0.2.1-pre.7` ; +- revérification officielle du 2026-08-17 : l’index Solana HTTP courant expose toujours 52 méthodes et la navigation Deprecated conserve les 14 noms historiques audités ; +- deux canaries d’intégration publiques figent la partition `52 current / 14 historical / 4-22-11-15` et le set exact des quatre canaris `0.2.1` ; +- la candidate déclare **80 tests Transport** et **114 tests Config**, dont un unique smoke Devnet Config `ignored` ; +- un smoke Devnet `ignored` sous `ksp-config-lib` valide de manière opt-in la chaîne Config -> `devnet_public` -> Transport -> `getHealth/getGenesisHash/getVersion/getBalance`, sans lecture d’environnement dans Transport ; +- `ksp-onchain-transport-lib/README.md` et `USAGE.md` documentent frontières, API raw vs typed, résilience, sécurité, Config et utilisation ; +- `docs/validation/003-V0_2_1_ONCHAIN_HTTP.md` devient la matrice durable de clôture ; +- le niveau de référence du sink Transport dédié revient de `debug` à `info` avant stable ; +- les écarts documentaires résiduels issus de l’audit complet sont normalisés : convention `bindings/gen`, README Config et inventaire composant HTTP ; +- `prompts/007-V0_2_2_START_PROMPT.md` prépare `0.2.2 — HTTP Accounts + Tokens + Cluster` avec un nouvel audit officiel et gate de sizing ; +- `CHANGELOG.md` n’est pas encore modifié : l’entrée stable `0.2.1` appartient à `rel.001`, conformément au workflow des releases précédentes. + +Les validations Cargo et `cargo tree` de cette candidate doivent être exécutées sur le dépôt canonique. Si elles sont propres, `rel.001` reste strictement publicationnel : version stable, statuts ROADMAP/plan/validation, entrée CHANGELOG, delta de release, commit et tag `v0.2.1`. ## 23. Séquence `0.2.x` recalibrée diff --git a/docs/rules/FILE_CONTRACTS.md b/docs/rules/FILE_CONTRACTS.md index b29aa7a..ba3671a 100644 --- a/docs/rules/FILE_CONTRACTS.md +++ b/docs/rules/FILE_CONTRACTS.md @@ -1,5 +1,5 @@ - + # Contrats des fichiers @@ -85,7 +85,7 @@ Pour un document standard profilé, `default_profile` et `profiles` sont des cl - **FILE-GEN-001** — Un fichier généré n'est jamais modifié manuellement lorsque sa source de vérité est un générateur. - **FILE-GEN-002** — Le choix de versionner ou ignorer une famille générée est décidé explicitement lorsqu'elle apparaît. -- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP ; ils seront traités lorsqu'ils apparaîtront. +- **FILE-GEN-003** — Les répertoires générés `bindings/` et `gen/` des toolchains Tauri/TS-RS restent des artefacts reconstruisibles et ne sont pas versionnés par défaut. Ils sont ignorés par le dépôt ; leurs sources de vérité restent les DTO/configurations/générateurs KSP. Toute exception de versionnement doit être explicitement justifiée et documentée. ## Documentation durable des crates et applications diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index e21b484..367b4e0 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -11,3 +11,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. diff --git a/docs/validation/003-V0_2_1_ONCHAIN_HTTP.md b/docs/validation/003-V0_2_1_ONCHAIN_HTTP.md new file mode 100644 index 0000000..4f6a89a --- /dev/null +++ b/docs/validation/003-V0_2_1_ONCHAIN_HTTP.md @@ -0,0 +1,194 @@ + + + +# Validation `0.2.1` — HTTP Solana foundation + +## Objet + +Cette matrice synthétise les critères de clôture de `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation`, les preuves acquises jusqu'à `pre.006-fix.002` et les validations finales attendues de `pre.007` avant publication `rel.001`. + +Elle ne remplace ni `docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md` ni les deltas `0.2.1`. + +## Base de clôture + +```text +base validée : 0.2.1-pre.6.fix.2 +candidate finale : 0.2.1-pre.7 +``` + +La base `pre.006-fix.002` a été validée par l'opérateur le 2026-08-17 avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, les tests ciblés Transport/Config Desk/Config/Core et `cargo test --workspace`. + +## Revérification officielle Solana + +Revérification de clôture effectuée le 2026-08-17. + +Index HTTP officiel : + +```text +https://solana.com/docs/rpc/http +``` + +L'index courant expose toujours **52 méthodes HTTP** et confirme JSON-RPC 2.0 sur HTTP `POST` avec `Content-Type: application/json`. + +La navigation officielle `Deprecated Methods`, visible depuis les pages deprecated telles que : + +```text +https://solana.com/docs/rpc/deprecated/confirmtransaction +``` + +expose toujours les **14 noms historiques** audités : + +```text +confirmTransaction +getConfirmedBlock +getConfirmedBlocks +getConfirmedBlocksWithLimit +getConfirmedSignaturesForAddress2 +getConfirmedTransaction +getFeeCalculatorForBlockhash +getFeeRateGovernor +getFees +getRecentBlockhash +getSignatureConfirmation +getSignatureStatus +getSnapshotSlot +getStakeActivation +``` + +KSP les conserve comme `Deprecated / Removed / Historical`; `0.2.1` ne simule pas leur appelabilité runtime. + +## Matrice de clôture + +| Critère | État candidat `pre.007` | Preuve / contrat | +|------------------------------------------------------------|-------------------------|-----------------------------------------------------------------------| +| Crate `ksp-onchain-transport-lib` présente et indépendante | OK | manifest + canary Core `workspace_dependencies` | +| Transport -X-> Config/Store/Program | OK | canary de firewall workspace | +| Transport -X-> `tracing` direct | OK | ownership Logging + `ksp-logging-lib` | +| Features Cargo activées localement par consumer | OK | canary workspace + manifests | +| Target Logging explicite possédé par la crate | OK | `src/constants.rs` + canary `workspace_logging` | +| URL endpoint redacted dans settings/snapshots/Debug | OK | tests settings/client/pool/public API | +| `reqwest::Error` source sans URL sensible | OK | `without_url()` + canary timeout secret | +| JSON-RPC 2.0 request/response/id/error | OK | tests `json_rpc` | +| Registry HTTP courant | OK | 52 descriptors + canary de release | +| Registry historique Deprecated | OK | 14 descriptors `Removed` + canary de release | +| Partition typed future | OK | `4 / 22 / 11 / 15` pour `0.2.1`–`0.2.4` | +| Quatre canaris typés exacts | OK | `getBalance`, `getGenesisHash`, `getHealth`, `getVersion` | +| Pool rôles/capabilities/priorités/fairness | OK | tests pool | +| RPS/burst/concurrence/cooldown | OK | tests resilience/pool | +| Deadline/timeout/retry borné | OK | tests executor/resilience | +| No-resend après dispatch ambigu | OK | descriptor + policy + tests | +| 429/Retry-After et statuts temporaires | OK | tests executor | +| Config standard Transport | OK | `std.transport.json` + schema + example | +| Direction Config -> Transport | OK | adapter `load_resolved_transport_config` | +| Sensibilité/provenance/env Transport | OK | tests Config | +| Logging Transport dédié | OK | sink dédié `info` dans `std.logging.json` | +| Tests réseau par défaut déterministes | OK | fixtures + serveur HTTP local | +| Smoke Devnet | OPT-IN | `tests/transport_devnet_smoke.rs`, ignored par défaut | +| README durable | OK | `crates/ksp-onchain-transport-lib/README.md` | +| USAGE durable | OK | `crates/ksp-onchain-transport-lib/USAGE.md` | +| Prompt release suivante | OK | `prompts/007-V0_2_2_START_PROMPT.md` | +| Matrice HTTP globale préservée | OK | plan `008`; 48 méthodes restantes restent affectées à `0.2.2`–`0.2.4` | + +## Canaries de complétude finales + +`pre.007` ajoute une intégration publique dédiée qui vérifie : + +```text +current == 52 +historical == 14 +coverage == 4 / 22 / 11 / 15 +V0_2_1 == getBalance/getGenesisHash/getHealth/getVersion +historical => Deprecated + Removed + NotApplicable +``` + +Ces checks complètent les tests unitaires existants du registre et protègent la frontière de release depuis l'API publique. + +La candidate déclare **80 tests Transport** et **114 tests Config**, dont le smoke Devnet Config unique marqué `ignored`. Ces nombres sont des canaries de clôture de la candidate et devront être confirmés par Cargo sur le dépôt canonique. + +## Smoke Devnet opt-in + +Le smoke live appartient à `ksp-config-lib`, car il doit prouver la chaîne : + +```text +Config + -> profile devnet_public + -> HttpTransportSettings + -> HttpTransportPool + -> getHealth + -> getGenesisHash + -> getVersion + -> getBalance(System Program) +``` + +Transport ne lit donc pas directement l'environnement. + +Exécution explicite : + +```bash +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Ce test dépend d'un service Devnet externe. Il reste ignoré dans les suites déterministes et un incident/rate-limit du RPC public n'est pas assimilé à une régression locale sans analyse. + +## Audit `cargo tree` final attendu + +À exécuter sur le dépôt canonique : + +```bash +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 +``` + +Points attendus : + +- pas de Config sous Transport ; +- Config dépend de Transport dans le sens autorisé ; +- pas de Store/Program ; +- pas de `tracing` direct chez Transport ; +- `reqwest/rustls`, `serde/derive`, Tokio Transport et Tokio de test Config restent activés localement par les crates consommatrices. + +## Validations finales de `pre.007` + +Avant commit : + +```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 +``` + +Puis, de manière opt-in : + +```bash +cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapture +``` + +Le smoke live est une preuve supplémentaire ; les suites déterministes restent la gate reproductible de publication. + +## Préparation de `rel.001` + +Si les validations de `pre.007` sont propres, `rel.001` doit rester minimal : + +```text +workspace.package.version -> 0.2.1 +ROADMAP : 0.2.1 -> [X] +CHANGELOG : synthèse stable 0.2.1 +plan 008 / matrice 003 : statut clôturé et preuves opérateur +nouveau delta deltas/0.2.1/rel.001.md +commit v0.2.1-rel.001 +tag v0.2.1 +``` + +Aucune nouvelle capacité HTTP ne doit être introduite dans `rel.001`. diff --git a/prompts/000-README.md b/prompts/000-README.md index 5f09626..ea351ee 100644 --- a/prompts/000-README.md +++ b/prompts/000-README.md @@ -1,5 +1,5 @@ - + # Prompts KSP @@ -24,7 +24,7 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par - [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt historique ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3` ; - [`002-V0_1_2_START_PROMPT.md`](002-V0_1_2_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.2 — Logging foundation` après publication stable de `0.1.1`. - [`003-V0_1_3_START_PROMPT.md`](003-V0_1_3_START_PROMPT.md) — prompt historique destiné à ouvrir `0.1.3 — Configuration foundation` après publication stable de `0.1.2` ; -- [`004-V0_1_4_START_PROMPT.md`](004-V0_1_4_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.4 — ksp-app-config-desk` après publication stable de `0.1.3`. -- [`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 ». +- [`004-V0_1_4_START_PROMPT.md`](004-V0_1_4_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.4 — ksp-app-config-desk` après publication stable de `0.1.3` ; +- [`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`. diff --git a/prompts/007-V0_2_2_START_PROMPT.md b/prompts/007-V0_2_2_START_PROMPT.md new file mode 100644 index 0000000..0935f1c --- /dev/null +++ b/prompts/007-V0_2_2_START_PROMPT.md @@ -0,0 +1,431 @@ + + + +# Prompt de démarrage `0.2.2` — HTTP Accounts + Tokens + Cluster + +## 1. Contexte de reprise + +La base attendue est la release stable : + +```text +v0.2.1 +``` + +`0.2.1` a stabilisé `ksp-onchain-transport-lib` comme foundation HTTP Solana : settings runtime, endpoints/pool/rôles, limites et résilience, JSON-RPC 2.0, registry audité, exécution HTTP générique, Config -> Transport et quatre wrappers typés canari. + +Les invariants à préserver sont notamment : + +```text +52 méthodes HTTP courantes auditées +14 méthodes historiques Deprecated / runtime Removed +4 wrappers typés acquis : getBalance/getGenesisHash/getHealth/getVersion +partition planifiée : 4 / 22 / 11 / 15 sur 0.2.1–0.2.4 +Transport -X-> Config/Store/Program/tracing direct +Config -> Transport autorisé +no-resend après dispatch ambigu pour WriteSubmission +URLs/provider credentials absents des diagnostics ordinaires +``` + +La release à ouvrir est : + +```text +0.2.2 — HTTP Accounts + Tokens + Cluster +``` + +La première tranche est : + +```text +0.2.2-pre.001 +``` + +`pre.001` commence par **audit officiel actuel + brainstorming + dimensionnement** avant implémentation lourde. + +## 2. Mission + +Compléter la surface **typée** KSP des familles Accounts, Tokens et Cluster restantes, en réutilisant sans duplication la foundation HTTP de `0.2.1`. + +La cible issue du plan `0.2.1` contient actuellement 22 méthodes : + +### Accounts — 5 + +```text +getAccountInfo +getLargestAccounts +getMinimumBalanceForRentExemption +getMultipleAccounts +getProgramAccounts +``` + +`getBalance` est déjà acquis en `0.2.1` et ne doit pas être réimplémenté. + +### Tokens — 5 + +```text +getTokenAccountBalance +getTokenAccountsByDelegate +getTokenAccountsByOwner +getTokenLargestAccounts +getTokenSupply +``` + +### Cluster — 12 + +```text +getClusterNodes +getEpochInfo +getEpochSchedule +getHighestSnapshotSlot +getIdentity +getLeaderSchedule +getMaxRetransmitSlot +getMaxShredInsertSlot +getSlot +getSlotLeader +getSlotLeaders +getVoteAccounts +``` + +`getGenesisHash`, `getHealth` et `getVersion` sont déjà acquis en `0.2.1`. + +Ces 22 noms sont la **partition KSP actuellement planifiée**, pas une vérité externe immuable. `pre.001` doit revérifier la documentation Solana du jour avant de confirmer le périmètre. + +## 3. 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/validation/003-V0_2_1_ONCHAIN_HTTP.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/ + +crates/ksp-config-lib/src/transport.rs +config/std.transport.json +config/schemas/std.transport.schema.json +``` + +Les deltas `0.2.1` servent de trace historique ; ne pas les réécrire. + +## 4. Sources externes normatives + +Au début de `pre.001`, consulter la documentation officielle **actuelle** Solana : + +```text +https://solana.com/docs/rpc/http +``` + +Pour chaque méthode cible, revérifier : + +- nom exact ; +- catégorie ; +- paramètres et ordre ; +- limites de cardinalité ; +- objets config ; +- commitment/minContextSlot ; +- encoding/dataSlice/filters ; +- nullable/optional ; +- forme exacte du résultat ; +- champs versionnés/optionnels ; +- erreurs significatives ; +- statut stable/deprecated/unstable ; +- éventuelle évolution depuis l'audit du 2026-08-17. + +Revérifier également l'index global afin de détecter une méthode ajoutée/supprimée/déplacée depuis `0.2.1`. + +Pour une question technique sur une crate externe, utiliser uniquement sa documentation/source primaire actuelle. + +## 5. Gate de sizing obligatoire + +Avant implémentation, répondre explicitement : + +```text +Les 22 wrappers typés + DTOs partagés + tests + documentation peuvent-ils être clôturés proprement dans cette session ? +``` + +Si NON : + +- ne pas compresser artificiellement la release ; +- proposer immédiatement un split cohérent de `0.2.2` avant développement lourd ; +- mettre à jour la séquence sans perdre aucune méthode. + +Une prerelease vise environ 15–20 minutes de travail effectif. + +## 6. Architecture à préserver + +Ne pas reconstruire un second transport par famille. + +Le flux reste : + +```text +wrapper typé + -> descriptor central + -> execute_standard_rpc + -> pool/admission + -> reqwest HTTP + -> JSON-RPC validation + -> decode typé +``` + +Réutiliser : + +- `HttpTransportPool` ; +- `HttpRpcMethodDescriptor` ; +- `HttpRpcCoverageRelease` ; +- request kinds ; +- retry metadata ; +- JSON-RPC KSP ; +- erreurs KSP ; +- Logging KSP ; +- redaction existante. + +Aucun wrapper typé ne doit bypasser le pool, la deadline, le retry ou le contrôle central de statut. + +## 7. DTOs et wire HTTP + +Créer des types KSP dédiés à la surface HTTP lorsque cela améliore réellement le contrat public. + +Principes : + +- utiliser `ksp_core_lib::Pubkey` pour les adresses publiques ; +- ne pas ajouter `solana-client` ni SDK RPC haut niveau ; +- ne pas dépendre de Store ou Program ; +- ne pas introduire `ksp-interface-lib` par anticipation ; +- ne pas décoder des programmes/accounts métier dans Transport ; +- conserver les valeurs JSON parsed/encoded à un niveau transport approprié ; +- ajouter `base64`, `bs58` ou autre dépendance seulement si le contrat typé retenu en a réellement besoin après audit ; +- mutualiser les objets réellement communs (`context`, account data/config, token amount, filters, epoch/leader structures) sans créer un « mega DTO » artificiel. + +Les types de résultats doivent conserver les `null` et options documentés au lieu d'inventer des valeurs. + +## 8. Accounts + +Auditer et typer notamment : + +- account absent vs présent ; +- `encoding` ; +- `dataSlice` ; +- `filters` de `getProgramAccounts` ; +- `withContext` ; +- `sortResults` si toujours documenté ; +- limites documentées de `getMultipleAccounts` ; +- rent exemption ; +- largest accounts et filtres éventuels. + +Ne pas convertir une réponse account en modèle Program/décodé. + +## 9. Tokens + +Les méthodes Token restent du **transport RPC standard Solana**, pas du decoding SPL Program. + +Auditer : + +- `TokenAmount` ; +- owner/delegate ; +- filtre exclusif `{mint}` ou `{programId}` ; +- encodings/dataSlice ; +- `minContextSlot` ; +- largest accounts ; +- supply. + +Aucune dépendance directe à une crate SPL n'est ajoutée uniquement pour représenter le JSON RPC si des DTOs KSP simples suffisent. + +## 10. Cluster + +Auditer précisément les formes de : + +- node contact info ; +- epoch info/schedule ; +- snapshot slots ; +- identity ; +- leader schedule et slot leaders ; +- max retransmit/shred slots ; +- slot ; +- vote accounts. + +Conserver les champs optionnels/versionnés documentés et ne pas supposer qu'un provider retourne toujours toutes les extensions. + +## 11. Surface raw vs typed + +`execute_standard_rpc()` reste public et utile, mais : + +> un appel raw/générique ne compte jamais comme couverture typée de `0.2.2`. + +Une méthode cible est clôturée seulement lorsque son wrapper public, ses paramètres/configs, son résultat et ses tests sont présents selon la matrice de la release. + +## 12. Erreurs, retry et sécurité + +Conserver les invariants `0.2.1` : + +- JSON-RPC application error distincte d'une erreur transport ; +- timeout/connection/status remappés sans URL sensible ; +- `reqwest::Error::without_url()` avant exposition comme source ; +- aucune URL/token/body complet dans `Debug`/logs ; +- retry uniquement selon descriptor/policy ; +- pas de nouvelle hiérarchie d'erreurs locale parallèle à `ksp_core_lib::Error`. + +Toutes les nouvelles méthodes de `0.2.2` sont a priori des reads, mais `pre.001` doit vérifier leur statut/opération actuel au lieu de l'assumer silencieusement. + +## 13. Logging + +Utiliser uniquement : + +```text +ksp_logging_lib +crate::TRACING_TARGET +``` + +Le target reste : + +```text +ksp-onchain-transport-lib +``` + +Éviter les logs par méthode redondants. Préférer les événements génériques du transport avec metadata sûre : méthode, rôle, endpoint logique, tentative, statut technique. + +Un niveau `debug` ciblé peut être rouvert temporairement pendant le développement, puis doit revenir à `info`/`warn` dans la dernière prerelease conformément aux règles KSP. + +## 14. Config + +Ne modifier `std.transport.json` ou son schema que si une capacité réellement nécessaire de `0.2.2` ne peut pas être exprimée par le contrat existant. + +La direction reste : + +```text +ksp-config-lib -> ksp-onchain-transport-lib +``` + +Transport ne lit jamais `.env` ou `std::env::var*`. + +## 15. Tests + +Pour chaque méthode typée, couvrir au minimum : + +- sérialisation de la request ; +- résultat success ; +- nullable/optional pertinent ; +- config/overload pertinent ; +- erreur significative ; +- invariants de cardinalité/filtre lorsque documentés. + +Utiliser fixtures déterministes et serveur HTTP local ; Internet est interdit aux tests par défaut. + +Conserver/étendre les canaries de release : + +```text +current == inventaire officiel confirmé +historical == inventaire officiel confirmé +partition de couverture exacte +0.2.1 canaries inchangés +0.2.2 exact method set +aucune méthode 0.2.3/0.2.4 déclarée typed-complete prématurément +``` + +Un smoke Devnet opt-in peut tester un sous-ensemble représentatif, mais il ne remplace pas les fixtures. + +## 16. Dépendances Cargo + +Rappels : + +- versions/default-features communes au root `[workspace.dependencies]` ; +- features d'usage activées dans chaque crate consommatrice ; +- toute nouvelle dépendance externe commune est d'abord déclarée au root ; +- `cargo tree` normal/doublons/features est rejoué lorsqu'une dépendance ou feature change. + +Ne pas ajouter une dépendance uniquement parce que bot3 l'utilisait. + +## 17. Documentation et clôture + +La dernière prerelease de `0.2.2` doit : + +- réauditer la matrice officielle ; +- exécuter les canaries finales ; +- mettre à jour README/USAGE si la surface publique change ; +- mettre à jour la validation durable ; +- ramener le logging temporairement élevé à sa baseline ; +- préparer le prompt `0.2.3 — HTTP Transactions` ; +- préparer un `rel.001` minimal. + +`CHANGELOG.md` reçoit l'entrée `0.2.2` au moment de la publication stable, pas comme journal de prereleases. + +## 18. Prévision souple initiale + +À confirmer par `pre.001` : + +| Tranche | Objectif indicatif | +|-----------|----------------------------------------------------------------------------------------| +| `pre.001` | re-audit officiel, matrice exacte, DTOs communs, dépendances, sizing | +| `pre.002` | primitives/configs/results communs Accounts/Token + fixtures de base | +| `pre.003` | 5 méthodes Accounts typées + tests | +| `pre.004` | 5 méthodes Tokens typées + tests | +| `pre.005` | première moitié des 12 méthodes Cluster + tests | +| `pre.006` | seconde moitié Cluster + tests | +| `pre.007` | canaries de complétude, smoke opt-in, docs finales, prompt `0.2.3`, préparation stable | + +Ce tableau n'est pas contractuel. Scinder une tranche si elle dépasse le budget ; ne jamais compresser un groupe pour conserver artificiellement un numéro. + +## 19. Validations minimales + +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 --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 si elle n'a pas été exécutée. + +## 20. Critères de sortie + +`0.2.2` peut devenir stable seulement si : + +- l'inventaire officiel actuel est revérifié ; +- les méthodes ciblées sont précisément celles retenues après cet audit ; +- chaque méthode cible possède un contrat public typé et des tests déterministes ; +- les quatre canaris `0.2.1` restent inchangés ; +- la partition globale ne perd aucune méthode future ; +- aucune dépendance/frontière KSP n'est violée ; +- redaction/retry/logging restent conformes ; +- README/USAGE sont à jour ; +- validations Cargo et canaries passent ; +- prompt `0.2.3` est prêt ; +- `rel.001` ne contient plus de développement fonctionnel nouveau.