khadhroony-solana-project/deltas/0.2.1/pre.004-fix.001.md

Delta v0.2.1-pre.004-fix.001

Base

Base attendue :

v0.2.1-pre.004

Version Cargo cible :

0.2.1-pre.4.fix.1

Objectif

Corriger la responsabilité Cargo des features externes révélée pendant l'audit de pre.004, sans modifier le comportement fonctionnel de la résilience HTTP :

• conserver au Cargo.toml racine la version et les options communes de résolution (default-features, etc.) ;
• retirer les activations features = [...] de [workspace.dependencies] ;
• activer chaque feature dans le manifeste de la crate KSP qui utilise réellement l'API correspondante ;
• distinguer lorsque c'est utile les features de production et celles requises uniquement par les tests ;
• formaliser explicitement cette règle sous DEP-CARGO-* ;
• ajouter une canarie empêchant le retour d'une activation de feature consumer dans [workspace.dependencies].

Ce fix ne modifie pas ROADMAP.md : il corrige un contrat Cargo et sa règle normative, pas la roadmap de 0.2.1.

Validation de pre.004 ayant précédé le fix

Après application de pre.004, le user a exécuté :

cargo fmt --all                              : exécuté
cargo check --workspace                     : OK
cargo clippy --workspace --all-targets       : OK
cargo test -p ksp-onchain-transport-lib      : OK, 72 tests Transport au total
cargo test --workspace                       : OK ; 1 test diagnostic ignoré comme prévu
cargo tree -p ksp-onchain-transport-lib -e features : exécuté
cargo tree -p ksp-onchain-transport-lib -e normal   : exécuté

Le problème n'est donc pas un échec fonctionnel de pre.004. L'audit cargo tree -e features a cependant rendu visible que les features Tokio déclarées au niveau workspace s'appliquaient au graphe Transport en plus de sa feature locale sync, ce qui rendait l'ownership des besoins réels trop global.

Décision normative

La politique KSP retenue est désormais explicite :

[workspace.dependencies]
    -> version
    -> default-features et autres options communes de résolution
    -> aucune activation features = [...]

crates/<consumer>/Cargo.toml
    -> dependency.workspace = true
    -> features = [...] nécessaires à ce consumer

Lorsqu'une feature n'est nécessaire qu'aux tests/benchmarks/examples, son activation appartient à la section de dépendances de développement correspondante.

Cette politique conserve la centralisation des versions sans transformer le feature-set d'une crate en politique implicite pour tous les autres consumers du workspace.

Répartition des features

serde

Le root conserve uniquement :

serde = { version = "^1.0" }

La feature derive est activée dans les trois crates qui utilisent réellement serde::Serialize / serde::Deserialize dérivés :

ksp-app-config-desk
ksp-config-lib
ksp-onchain-transport-lib

reqwest

Le root conserve :

reqwest = { version = "^0.13", default-features = false }

ksp-onchain-transport-lib active localement :

rustls

tracing / tracing-subscriber

Le root conserve les versions avec default-features = false.

Seul ksp-logging-lib, propriétaire KSP de ces dépendances, active :

tracing            : std
tracing-subscriber : fmt, json, ansi

tracing-appender ne possédait aucune feature explicite à déplacer.

chrono

Le root conserve uniquement la version avec default-features = false.

ksp-app-config-desk, seul consumer direct actuel de chrono::Utc::now, active localement :

std, now

tokio

Le root devient :

tokio = { version = "^1.53", default-features = false }

Les activations sont réparties selon l'usage réel :

ksp-app-config-desk
  dependencies     : time

ksp-logging-lib
  dev-dependencies : macros, rt, rt-multi-thread

ksp-onchain-transport-lib
  dependencies     : macros, sync, time
  dev-dependencies : rt

Pour Transport :

• sync couvre Notify, Semaphore et OwnedSemaphorePermit ;
• time couvre sleep_until / Instant ;
• macros est une dépendance de production car pool.rs utilise tokio::select! ;
• rt est requis par #[tokio::test] et reste donc activé uniquement côté développement ;
• aucun besoin Transport actuel ne justifie rt-multi-thread.

Règles KSP

docs/rules/RULES_DEPENDENCIES.md passe de la version 11 à 12.

DEP-CARGO-003 précise maintenant que les features d'usage ne sont pas activées sous [workspace.dependencies] et appartiennent aux manifests consumers.

Nouvelle règle DEP-CARGO-006 : une feature requise uniquement par tests/benchmarks/examples doit être activée dans la section de dépendances de développement appropriée ; l'unification Cargo ne transfère pas cet ownership au root.

Canarie Cargo

crates/ksp-onchain-transport-lib/tests/dependency_boundary.rs vérifie désormais aussi :

• le feature-set direct attendu de reqwest et tokio pour Transport ;
• la séparation du tokio/rt de test sous [dev-dependencies] ;
• l'absence de toute chaîne features = dans la section [workspace.dependencies] du manifeste racine.

Cette canarie complète le firewall Transport existant sans introduire de nouvelle dépendance d'audit.

Version Cargo

Le fix modifie plusieurs manifests et donc le contrat de build :

0.2.1-pre.4 -> 0.2.1-pre.4.fix.1

Toutes les crates KSP continuent d'hériter version.workspace = true.

Fichiers ajoutés

deltas/0.2.1/pre.004-fix.001.md

Fichiers modifiés

Cargo.toml
crates/ksp-app-config-desk/Cargo.toml
crates/ksp-config-lib/Cargo.toml
crates/ksp-logging-lib/Cargo.toml
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/tests/dependency_boundary.rs
docs/rules/RULES_DEPENDENCIES.md

Fichiers supprimés

Aucun.

Graphe de dépendances

Aucune crate externe n'est ajoutée ou retirée. Le fix modifie en revanche volontairement les feature-sets directs par consumer ; les audits Cargo doivent donc être rejoués après application.

Pour Transport, vérifier au minimum :

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

Il est également utile de vérifier les consumers dont les features ont été relocalisées :

cargo tree -p ksp-app-config-desk -e features
cargo tree -p ksp-config-lib -e features
cargo tree -p ksp-logging-lib -e features

Validation du fix

Le sandbox de préparation ne dispose pas de cargo/rustc. Les validations Rust du correctif ne sont donc pas déclarées réussies ici.

Après application :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib
cargo test --workspace

Puis exécuter les cargo tree indiqués ci-dessus afin de confirmer que chaque crate expose uniquement les features directes qu'elle possède, sous réserve de l'unification transitive normale de Cargo au niveau du build effectif.

Suite

Après validation et commit de ce fix, 0.2.1 reprend avec :

v0.2.1-pre.005

Le périmètre fonctionnel prévu de pre.005 reste inchangé : exécuteur HTTP JSON-RPC réel et quatre méthodes canari typées.