From 8e739b9e55b7fcb47cf3c92416d499e9885c067d Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 23 Aug 2026 15:13:03 +0200 Subject: [PATCH] v0.2.8-pre.005-fix.002 --- Cargo.toml | 4 +- .../src/ws_helius_transactions.rs | 11 +++- deltas/0.2.8/pre.005-fix.002.md | 58 +++++++++++++++++++ ...0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md | 23 ++++++-- docs/rules/RULES_RUST.md | 3 +- ...011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md | 39 ++++++++++++- 6 files changed, 125 insertions(+), 13 deletions(-) create mode 100644 deltas/0.2.8/pre.005-fix.002.md diff --git a/Cargo.toml b/Cargo.toml index 0e7130b..5c5f72a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 224 +# version: 225 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.2.8-pre.5.fix.1" +version = "0.2.8-pre.5.fix.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs b/crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs index 9112835..d320a40 100644 --- a/crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs +++ b/crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs -// version: 2 +// version: 3 const MAX_HELIUS_TRANSACTION_FILTER_ACCOUNTS: usize = 50_000; @@ -150,6 +150,7 @@ impl HeliusTransactionSubscribeFilter { return std::result::Result::Ok(()); } + #[cfg(test)] fn to_json_value(&self) -> serde_json::Value { let mut object = serde_json::Map::new(); if let std::option::Option::Some(vote) = self.vote { @@ -260,6 +261,7 @@ impl HeliusTransactionSubscribeOptions { return std::result::Result::Ok(()); } + #[cfg(test)] fn to_json_value(self) -> serde_json::Value { let mut object = serde_json::Map::new(); if let std::option::Option::Some(commitment) = self.commitment { @@ -333,6 +335,7 @@ impl std::fmt::Debug for HeliusTransactionSubscribeRequest { } } +#[cfg(test)] fn helius_transaction_subscribe_params(request: &crate::HeliusTransactionSubscribeRequest) -> ksp_core_lib::Result> { let validation = request.validate(); if let std::result::Result::Err(error) = validation { @@ -345,14 +348,17 @@ fn helius_transaction_subscribe_params(request: &crate::HeliusTransactionSubscri return std::result::Result::Ok(params); } +#[cfg(test)] const fn helius_transaction_subscribe_method() -> &'static str { return "transactionSubscribe"; } +#[cfg(test)] const fn helius_transaction_unsubscribe_method() -> &'static str { return "transactionUnsubscribe"; } +#[cfg(test)] fn decode_helius_transaction_subscribe_result(value: serde_json::Value) -> ksp_core_lib::Result { return match value.as_u64() { std::option::Option::Some(remote_id) => std::result::Result::Ok(remote_id), @@ -363,10 +369,12 @@ fn decode_helius_transaction_subscribe_result(value: serde_json::Value) -> ksp_c }; } +#[cfg(test)] fn helius_transaction_unsubscribe_params(remote_id: u64) -> std::vec::Vec { return std::vec![serde_json::Value::Number(remote_id.into())]; } +#[cfg(test)] fn decode_helius_transaction_unsubscribe_result(value: serde_json::Value) -> ksp_core_lib::Result { return match value.as_bool() { std::option::Option::Some(unsubscribed) => std::result::Result::Ok(unsubscribed), @@ -392,6 +400,7 @@ fn validate_account_list(field: &'static str, accounts: std::option::Option<&[ks return std::result::Result::Ok(()); } +#[cfg(test)] fn insert_account_list( object: &mut serde_json::Map, field: &'static str, diff --git a/deltas/0.2.8/pre.005-fix.002.md b/deltas/0.2.8/pre.005-fix.002.md new file mode 100644 index 0000000..358aacc --- /dev/null +++ b/deltas/0.2.8/pre.005-fix.002.md @@ -0,0 +1,58 @@ + + + +# Delta `0.2.8-pre.005-fix.002` — suppression des helpers wire morts hors tests + +## 1. Cause + +Le checkpoint de `pre.005-fix.001` corrige les quatre erreurs de type et valide les tests Transport, mais `cargo check`, `cargo clippy --workspace --all-targets` et la compilation des tests émettent encore neuf warnings `dead_code` dans `ws_helius_transactions.rs`. + +Ces warnings concernent uniquement des helpers strictement privés préparant le wire `transactionSubscribe`/`transactionUnsubscribe` avant son intégration actor de `pre.006`. Ils n'ont volontairement aucun consommateur de production en `pre.005`. + +## 2. Correction + +`pre.005-fix.002` ne réélargit aucune visibilité et n'ajoute aucun `#[allow(dead_code)]`. Les helpers concernés restent privés et sont compilés uniquement sous `#[cfg(test)]` : + +```text +HeliusTransactionSubscribeFilter::to_json_value +HeliusTransactionSubscribeOptions::to_json_value +helius_transaction_subscribe_params +helius_transaction_subscribe_method +helius_transaction_unsubscribe_method +decode_helius_transaction_subscribe_result +helius_transaction_unsubscribe_params +decode_helius_transaction_unsubscribe_result +insert_account_list +``` + +Le contrat public typed (`HeliusTransactionSubscribe*`) et les validations déterministes restent compilés dans le build de production. Les tests unitaires continuent d'accéder aux helpers privés via `super::Item`; les éléments visibles continuent d'être consommés via `crate::Item`. + +## 3. Règle durable + +`RUST-API-008` formalise qu'un helper strictement privé uniquement utile à un `unit_tests/` de préparation reste sous `#[cfg(test)]` tant qu'aucun chemin de production ne le consomme réellement. La visibilité ne doit pas être élargie et `#[allow(dead_code)]` ne doit pas servir de compensation. + +En `pre.006`, seuls les helpers réellement nécessaires à l'actor seront promus dans le build normal ; si un partage cross-module impose `pub(crate)`, il devra alors passer par le crate-root et être consommé via `crate::Item`. + +## 4. Fichiers + +```text +Cargo.toml +crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs +docs/rules/RULES_RUST.md +docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md +docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md +deltas/0.2.8/pre.005-fix.002.md +``` + +## 5. Gate opérateur + +```bash +cargo fmt --all +python3 scripts/audit_rust_workspace_rules.py +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +cargo test --workspace +``` + +Critère supplémentaire de fermeture : `cargo check` et Clippy ne doivent plus émettre les neuf warnings `dead_code` observés après `fix.001`. diff --git a/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md b/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md index 82e1f34..bcc20c7 100644 --- a/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md +++ b/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md @@ -1,9 +1,9 @@ - + # Plan `0.2.8` — Helius LaserStream WebSocket -> **Statut : `pre.004` et ses deux fixes sont validés. Le premier checkpoint de `0.2.8-pre.005` a révélé quatre erreurs de type dans les canaris JSON et une visibilité `pub(crate)` injustifiée pour des helpers utilisés uniquement par le module/tests. `0.2.8-pre.005-fix.001` est préparé pour corriger ces deux points et durcir l'audit des accès `super::PrivateItem` / `crate::VisibleItem`.** +> **Statut : `pre.004` et ses deux fixes sont validés. `pre.005-fix.001` corrige les erreurs de type et la visibilité test/private, mais son checkpoint reste non fermable à cause de neuf warnings `dead_code` sur des helpers wire strictement privés qui n'ont pas encore de consommateur de production. `0.2.8-pre.005-fix.002` les borne à `#[cfg(test)]` jusqu'à leur consommation réelle par l'actor en `pre.006`, sans `allow(dead_code)` ni élargissement de visibilité.** ## 1. Objet, base et état courant @@ -31,10 +31,11 @@ pre.004 Config V2 Helius validé pre.004-fix.001 redaction segmentaire + couverture Devnet Helius validées pre.004-fix.002 provenance composée validée pre.005 contrat typed transactionSubscribe/unsubscribe ; fix requis après checkpoint -pre.005-fix.001 correction types de canaris + visibilité/tests/règles préparée +pre.005-fix.001 correction types de canaris + visibilité/tests/règles appliquée +pre.005-fix.002 suppression warnings dead_code via cfg(test) des helpers wire préparée -workspace.package.version courant = 0.2.8-pre.5.fix.1 -commit attendu = v0.2.8-pre.005-fix.001 +workspace.package.version courant = 0.2.8-pre.5.fix.2 +commit attendu = v0.2.8-pre.005-fix.002 aucun tag prerelease ``` @@ -60,7 +61,8 @@ pre.004 DONE — Config V2 helius_laserstream + schema/fixtures + mapping Confi fix.002 DONE — provenance composée `DocumentLiteral` + `EnvironmentProcess` corrigée pre.005 FIX REQUIRED — transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe + bounds 50k + maxSupportedTransactionVersion conditionnel ; live handle différé à pre.006 - fix.001 PREPARED — assertions Vec/Value corrigées + helpers test-only privés + audit super/crate durci + fix.001 APPLIED — assertions Vec/Value corrigées + helpers test-only privés + audit super/crate durci + fix.002 PREPARED — helpers wire non consommés en production bornés à #[cfg(test)] ; zéro allow/dead-code compensatoire pre.006 transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races + late notifications + backpressure ciblée pre.007 heartbeat Helius WebSocket/idle + timers + interaction reconnect/control frames/shutdown @@ -1013,3 +1015,12 @@ cargo test -p ksp-onchain-transport-lib FAIL — mêmes 4 erreurs de type Le correctif ne change ni le contrat Helius public ni le wire. Il applique la règle de visibilité KSP : un helper utilisé seulement par son module et son sous-module de tests reste strictement privé ; le test l'appelle via `super::Item`. Les éléments `pub` et `pub(crate)` restent réexportés et consommés via `crate::Item`. Les helpers transaction wire de `pre.005` ne deviendront `pub(crate)` qu'en `pre.006` si l'actor les consomme réellement. Le script `audit_rust_export_completeness.py` est étendu pour détecter dans les `unit_tests/` séparés les accès non qualifiés aux items privés du parent et les accès non canoniques aux items visibles. + +### Checkpoint `pre.005-fix.001` et correctif `pre.005-fix.002` + +Le checkpoint opérateur après `fix.001` confirme que les erreurs `Vec`/`Value` sont corrigées et que les tests Transport passent (`322` unit, `39` public API, `27` release completeness, `4` doctests). Il révèle toutefois neuf warnings `dead_code` pendant `cargo check`, `clippy` et la compilation des tests : deux sérialiseurs privés, cinq helpers de contrôle subscribe/unsubscribe et le helper d'insertion de listes. + +Ces éléments ne sont pas encore consommés par un chemin de production en `pre.005`; leur seul consommateur légitime est le sous-module `unit_tests` rattaché au module propriétaire. `fix.002` applique donc `RUST-API-008` : ils restent strictement privés et sont placés sous `#[cfg(test)]`. Le contrat public typed et ses validations restent compilés en production. Aucune visibilité n'est élargie, aucun `#[allow(dead_code)]` n'est ajouté et le wire préparé reste couvert par les mêmes canaris. + +Leur promotion éventuelle en code de production est différée à `pre.006`, exactement au moment où l'actor WebSocket les consommera réellement ; si cette promotion exige `pub(crate)`, elle suivra alors la façade crate-root et les appels `crate::Item`. + diff --git a/docs/rules/RULES_RUST.md b/docs/rules/RULES_RUST.md index 2640a4c..31458d3 100644 --- a/docs/rules/RULES_RUST.md +++ b/docs/rules/RULES_RUST.md @@ -1,5 +1,5 @@ - + # Règles Rust générales @@ -49,6 +49,7 @@ Les règles `RUST-*` s'appliquent à tous les fichiers Rust de KSP : crates, sou - **RUST-API-005** — Les chemins internes de modules ne constituent jamais une API stable. - **RUST-API-006** — Si deux éléments crate-wide auraient le même nom au crate-root, ils sont renommés dans leurs modules propriétaires avec des noms canoniques non ambigus ; un alias de réexport n'est pas utilisé pour masquer la collision. - **RUST-API-007** — La visibilité d'un item n'est jamais élargie uniquement pour permettre son test. Un helper utilisé seulement par son module et ses `unit_tests/` reste privé et les tests y accèdent via `super::Item`; il ne devient `pub(crate)` que lorsqu'un autre module de production le consomme réellement, auquel cas `RUST-API-004` et `RUST-IMPORT-009` s'appliquent. +- **RUST-API-008** — Un helper strictement privé dont aucun chemin de production ne dépend encore et qui n'existe que pour un `unit_tests/` de préparation est compilé sous `#[cfg(test)]` jusqu'à sa première consommation de production réelle. Il ne reste pas mort dans le build normal et n'est pas conservé au moyen d'un `#[allow(dead_code)]` compensatoire. ## Formatage, blocs et ordre diff --git a/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md b/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md index b04f22e..eff6bcf 100644 --- a/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md +++ b/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md @@ -1,9 +1,9 @@ - + # Validation `0.2.8` — Helius LaserStream WebSocket -> **Statut : `pre.004` + ses fixes sont validés. Le checkpoint `pre.005` échoue uniquement sur quatre comparaisons de canaris `Vec`/`Value` et révèle cinq réexports `pub(crate)` test-only inutilisés. `pre.005-fix.001` corrige les canaris, rétablit les visibilités privées et durcit l'audit `super::`/`crate::`.** +> **Statut : `pre.004` + ses fixes sont validés. `pre.005-fix.001` corrige les erreurs de type et les chemins de visibilité, mais son checkpoint émet encore neuf warnings `dead_code` sur des helpers wire privés non consommés en production. `pre.005-fix.002` les compile uniquement sous `#[cfg(test)]` jusqu'à `pre.006`, sans modifier le contrat public Helius.** ## 1. Références @@ -22,6 +22,7 @@ pre.004 redaction/devnet fix deltas/0.2.8/pre.004-fix.001.md pre.004 provenance fix deltas/0.2.8/pre.004-fix.002.md pre.005 deltas/0.2.8/pre.005.md pre.005 visibility/test fix deltas/0.2.8/pre.005-fix.001.md +pre.005 dead-code fix deltas/0.2.8/pre.005-fix.002.md validation standard WS docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md HTTP compliance docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md KSP-TRANSPORT-007 docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md @@ -487,4 +488,36 @@ Critères du fix : [ ] tests Transport/workspace verts ``` -Verdict courant : **`pre.005` FIX REQUIRED ; `pre.005-fix.001` PREPARED.** +Verdict après ce checkpoint : **`pre.005` FIX REQUIRED ; `pre.005-fix.001` APPLIED mais gate warningful.** + +## 15. Gate `pre.005-fix.001` et `pre.005-fix.002` + +Checkpoint opérateur reçu après `pre.005-fix.001` : + +```text +[x] cargo fmt --all +[x] python3 scripts/audit_rust_workspace_rules.py = clean +[!] cargo check --workspace — compile, mais 9 warnings dead_code dans ws_helius_transactions.rs +[!] cargo clippy --workspace --all-targets — compile, mêmes 9 warnings +[x] cargo test -p ksp-onchain-transport-lib — 322 unit + 39 public + 27 completeness + 4 doctests +[ ] cargo test --workspace — non utilisé comme preuve de fermeture tant que le build reste warningful +``` + +Les neuf warnings portent exclusivement sur des helpers privés de préparation wire non encore consommés par un chemin de production : `to_json_value` (filtre/options), params/method/result subscribe/unsubscribe et `insert_account_list`. + +Critères `pre.005-fix.002` : + +```text +[ ] helpers wire test-only restent strictement privés +[ ] helpers wire test-only sont sous #[cfg(test)] +[ ] aucun #[allow(dead_code)] compensatoire +[ ] aucun pub(crate) test-only +[ ] tests privés continuent via super::Item +[ ] API publique continue via crate::Item +[ ] cargo check sans warning pre.005 +[ ] cargo clippy sans warning pre.005 +[ ] tests Transport/workspace verts +``` + +Verdict courant : **`pre.005` FIX REQUIRED ; `pre.005-fix.001` APPLIED ; `pre.005-fix.002` PREPARED.** +