Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.8-pre.005-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 15:02:41 +02:00
parent 92224e5ac6
commit 53dbb5bccd
9 changed files with 264 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.004` et ses deux fixes sont validés par checkpoint opérateur complet. `0.2.8-pre.005` est préparé : contrat typed `transactionSubscribe`, filtres/options Helius, `tokenAccounts`, limites 50k et wire `transactionUnsubscribe`, sans exposer encore de handle transaction avant l'intégration actor de `pre.006`.**
> **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`.**
## 1. Objet, base et état courant
@@ -30,10 +30,11 @@ pre.003 six familles standard Helius validées
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 préparé
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
workspace.package.version courant = 0.2.8-pre.5
commit attendu = v0.2.8-pre.005
workspace.package.version courant = 0.2.8-pre.5.fix.1
commit attendu = v0.2.8-pre.005-fix.001
aucun tag prerelease
```
@@ -57,8 +58,9 @@ pre.004 DONE — Config V2 helius_laserstream + schema/fixtures + mapping Confi
+ secret/redaction Helius mainnet/devnet validés
fix.001 DONE — redaction segmentaire corrigée + représentation Devnet Helius ajoutée
fix.002 DONE — provenance composée `DocumentLiteral` + `EnvironmentProcess` corrigée
pre.005 PREPARED — transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
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>/Value corrigées + helpers test-only privés + audit super/crate durci
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
@@ -995,3 +997,19 @@ new dependency aucune
```
La séparation `pre.005` / `pre.006` est normative : publier dès maintenant un `transaction_subscribe()` public sans registry de notification/reconnect produirait un handle transitoire qui perdrait les notifications. Le contrat public de requête est donc stable dès `pre.005`, tandis que l'abonnement live est ajouté atomiquement avec l'actor integration en `pre.006`.
### Checkpoint `pre.005` et correctif `pre.005-fix.001`
Le premier checkpoint opérateur de `pre.005` a donné :
```text
cargo fmt --all OK
python3 scripts/audit_rust_workspace_rules.py clean mais incomplet pour la règle test/private
cargo check --workspace OK avec 5 warnings unused pub(crate) reexports
cargo clippy --workspace --all-targets FAIL — 4 comparaisons Vec<Value> / Value
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.

7
docs/rules/RULES_RUST.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_RUST.md -->
<!-- version: 8 -->
<!-- version: 9 -->
# Règles Rust générales
@@ -35,7 +35,7 @@ Les règles `RUST-*` s'appliquent à tous les fichiers Rust de KSP : crates, sou
- **RUST-IMPORT-009** — Dans sa propre crate, un élément `pub` ou `pub(crate)` partagé est appelé via `crate::Item`, y compris depuis son module de déclaration lorsque le contrat est crate-wide.
- **RUST-IMPORT-010** — Un chemin `crate::module::Item` est interdit pour un élément partagé `pub`/`pub(crate)` qui peut être consommé via le crate-root. Le chemin du module interne n'est pas une façade.
- **RUST-IMPORT-011** — Un élément strictement privé à un module n'est pas réexporté et est appelé par son nom local dans ce module.
- **RUST-IMPORT-012** — Dans un sous-module de tests, `super::Item` est réservé à un élément strictement privé du module parent. Un élément `pub` ou `pub(crate)` continue d'être appelé via `crate::Item`.
- **RUST-IMPORT-012** — Dans un fichier `unit_tests/...` rattaché au module parent, tout élément strictement privé du parent est appelé explicitement via `super::Item`. Inversement, un élément `pub` ou `pub(crate)` n'est jamais appelé via `super::` ni par un nom nu : il continue d'être appelé via le crate-root `crate::Item`, y compris lorsque le test est rattaché à son module de déclaration.
- **RUST-IMPORT-013** — Les réexports internes commencent par `self::`. Un réexport d'une crate externe peut utiliser directement le chemin externe canonique.
- **RUST-IMPORT-014** — Un export correspond à une ligne de réexport distincte ; les accolades ne servent jamais à regrouper une façade.
- **RUST-IMPORT-015** — Une crate externe rendue publique uniquement pour l'hygiène d'une macro exportée conserve son nom canonique, porte `#[doc(hidden)]` et ne devient pas une API de consommation. `ksp-logging-lib::tracing` est ce bridge technique pour les macros Logging ; les autres crates KSP n'y accèdent jamais directement.
@@ -48,6 +48,7 @@ Les règles `RUST-*` s'appliquent à tous les fichiers Rust de KSP : crates, sou
- **RUST-API-004** — Un élément `pub(crate)` consommé hors de son module est réexporté au crate-root via `pub(crate) use` puis appelé via `crate::Item`.
- **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.
## Formatage, blocs et ordre
@@ -102,7 +103,7 @@ Les règles `RUST-*` s'appliquent à tous les fichiers Rust de KSP : crates, sou
- **RUST-AUDIT-001** — `scripts/audit_rust_workspace_rules.py` est le point d'entrée obligatoire de l'audit Rust KSP. Il exécute les audits généraux, la complétude des réexports/chemins et les frontières KSP sans fusionner leurs responsabilités.
- **RUST-AUDIT-002** — L'audit est dependency-free côté Python standard et échoue avec un code non nul dès qu'une violation mécanique est détectée.
- **RUST-AUDIT-003** — L'audit contrôle au minimum : headers/version/newline, lints de crate-root, visibilité interdite, `use`/aliases/groupes/globs/scope, rustdocs visibles, structure des blocs de réexports, ordre des imports de traits et constantes lorsque KSP le possède, lignes vides dans fonctions/structs/enums, complétude des réexports crate-root, chemins `crate::module::Item`, usage de `super::` dans les tests séparés et frontières KSP directement vérifiables. L'ordre intra-bloc des `use`/réexports reste la responsabilité canonique de `cargo fmt --all` et n'est pas réimplémenté par le script.
- **RUST-AUDIT-003** — L'audit contrôle au minimum : headers/version/newline, lints de crate-root, visibilité interdite, `use`/aliases/groupes/globs/scope, rustdocs visibles, structure des blocs de réexports, ordre des imports de traits et constantes lorsque KSP le possède, lignes vides dans fonctions/structs/enums, complétude des réexports crate-root, chemins `crate::module::Item`, accès `super::PrivateItem` et `crate::VisibleItem` dans les tests séparés, ainsi que les frontières KSP directement vérifiables. L'ordre intra-bloc des `use`/réexports reste la responsabilité canonique de `cargo fmt --all` et n'est pas réimplémenté par le script.
- **RUST-AUDIT-004** — Les règles contextuelles qui ne peuvent pas être prouvées sans interpréter la sémantique restent des critères de revue humaine ; le script ne doit pas produire de faux sentiment de complétude.
## Contrôle avant livraison

59
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.004` + `fix.001` + `fix.002` validés par checkpoint opérateur complet. `pre.005` est préparé : contrat public typed de requête Helius transaction, validations 50k/version, `tokenAccounts`, wire subscribe/unsubscribe et canari actor local ; le handle live reste volontairement différé à `pre.006`.**
> **Statut : `pre.004` + ses fixes sont validés. Le checkpoint `pre.005` échoue uniquement sur quatre comparaisons de canaris `Vec<Value>`/`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::`.**
## 1. Références
@@ -21,6 +21,7 @@ pre.004 deltas/0.2.8/pre.004.md
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
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
@@ -134,22 +135,22 @@ Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `fix.001` et `pre.003` so
### 4.2 Invariants architecture
| Critère | Décision | Preuve cible | État |
|-------------------------------------|------------------------------------------------------------------|---------------------------------|--------|
| Critère | Décision | Preuve cible | État |
|-------------------------------------|------------------------------------------------------------------|---------------------------------|--------------------|
| actor physique | un seul `WsSession` actor partagé | source/runtime canary | pre.002 implémenté |
| façade standard | `SolanaStandardWsSession` | public API canary | pre.002 implémenté |
| façade Helius | `HeliusLaserStreamWsSession` | public API canary | pre.002 implémenté |
| namespace LaserStream WS | `WsProtocolKind` + `ws_endpoints` possèdent `helius_laserstream` | API/Config/docs canary | pre.004 validé |
| LaserStream gRPC | backend/type/Config distincts, hors `0.2.8` | absence de réutilisation WS | décidé |
| namespace LaserStream WS | `WsProtocolKind` + `ws_endpoints` possèdent `helius_laserstream` | API/Config/docs canary | pre.004 validé |
| LaserStream gRPC | backend/type/Config distincts, hors `0.2.8` | absence de réutilisation WS | décidé |
| escape hatch Helius | aucun `inner()`/`into_inner()` public | compile-fail/source canary | pre.002 implémenté |
| generic Helius `WsSession::connect` | ne doit pas permettre de contourner la façade | invalid protocol pre-I/O canary | pre.002 implémenté |
| Helius unsupported | absent de la façade | compile-fail/API absence canary | pre.003 validé |
| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 validé |
| DTO duplication | seulement si wire/sémantique divergent | public/source audit | décidé |
| Config direction | Config -> Transport uniquement | ownership tests | pre.004 validé |
| heartbeat | Helius-only, actor commun | deterministic timers | décidé |
| secret | query URL derrière `WsEndpointUrl` | redaction canaries | pre.004 validé |
| new Rust dependency | aucune | manifest/tree audit | décidé |
| Helius unsupported | absent de la façade | compile-fail/API absence canary | pre.003 validé |
| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 validé |
| DTO duplication | seulement si wire/sémantique divergent | public/source audit | décidé |
| Config direction | Config -> Transport uniquement | ownership tests | pre.004 validé |
| heartbeat | Helius-only, actor commun | deterministic timers | décidé |
| secret | query URL derrière `WsEndpointUrl` | redaction canaries | pre.004 validé |
| new Rust dependency | aucune | manifest/tree audit | décidé |
## 5. Contrat `transactionSubscribe` à valider
@@ -339,6 +340,7 @@ Constats `pre.002-fix.001` :
Aucun split en fichiers supplémentaires n'est retenu : les plans historiques `0.2.5`–`0.2.7` sont de taille comparable ou supérieure, et le contenu du plan `015` reste entièrement centré sur une seule release. Le problème identifié était **l'ordre interne et la duplication de responsabilités**, pas la nécessité d'un nouveau type de document.
## 12. Gates opérateur `pre.004` / `fix.001` / `fix.002`
Premier passage `pre.004` reçu le 2026-08-23 :
@@ -455,3 +457,34 @@ Gates opérateur `pre.005` à exécuter :
```
Verdict courant : **`pre.004` et ses fixes DONE ; `pre.005` PREPARED.**
## 14. Gate `pre.005` et `pre.005-fix.001`
Checkpoint opérateur initial `pre.005` :
```text
[x] cargo fmt --all
[x] audit Rust général/workspace
[x] cargo check --workspace compile
[!] cargo check — 5 warnings de réexports pub(crate) utilisés uniquement par les tests
[ ] cargo clippy --workspace --all-targets — 4 erreurs E0277 Vec<Value> == Value
[ ] cargo test -p ksp-onchain-transport-lib — mêmes 4 erreurs E0277
[ ] cargo test --workspace — non retenu comme preuve de fermeture tant que Transport ne compile pas en tests
```
Critères du fix :
```text
[ ] les quatre attentes JSON comparent Vec<Value> à Vec<Value>
[ ] les helpers wire utilisés uniquement par le module/tests sont strictement privés
[ ] aucun pub(crate) test-only ni #[allow(dead_code)] compensatoire
[ ] unit_tests utilise super::Helper pour ces items privés
[ ] unit_tests continue d'utiliser crate::Item pour tous les éléments pub/pub(crate)
[ ] l'audit détecte private parent utilisé sans super::
[ ] l'audit détecte visible parent utilisé via super:: ou nom nu
[ ] cargo check sans les cinq warnings pre.005
[ ] clippy Transport/workspace vert
[ ] tests Transport/workspace verts
```
Verdict courant : **`pre.005` FIX REQUIRED ; `pre.005-fix.001` PREPARED.**