khadhroony-bot3/docs/decisions/WINCODE_COMPATIBILITY_POLICY.md

Politique de compatibilité wincode

1. Objet

Ce document explique pourquoi le workspace khadhroony-bot3 contraint actuellement wincode à la famille 0.5.x et pourquoi le contrôle du Cargo.lock local existe.

Cette contrainte est un garde-fou de compatibilité de dépendances. Elle ne constitue pas un écart fonctionnel à réexaminer dans chaque prompt ou chaque livraison documentaire.

2. Incident à l’origine de la règle

Pendant la migration vers bot3, l’apparition de wincode 0.6.0 dans la résolution de dépendances a créé une incompatibilité avec des crates Solana ou interfaces encore fondées sur les traits de wincode 0.5.x.

Les familles wincode 0.5 et wincode 0.6 ne sont pas interchangeables au niveau de leurs traits et types. Une résolution transitive non maîtrisée peut donc produire des erreurs de compilation même lorsque les noms des APIs paraissent identiques.

3. Décision actuelle

Tant que les interfaces Solana consommées par le workspace utilisent la famille 0.5.x :

wincode = "^0.5"

La résolution locale attendue est :

wincode 0.5.5
solana-wincode-varint 1.0.0

Le script scripts/audit_khadhroony_workspace_rules.py vérifie :

1. la contrainte ^0.5 dans le catalogue de dépendances workspace ;
2. la présence du Cargo.lock local ;
3. l’absence d’une seconde famille wincode incompatible ;
4. les versions résolues attendues.

4. Rôle du Cargo.lock

Le Cargo.lock est nécessaire à ce contrôle parce que Cargo.toml décrit une plage de versions, tandis que le lockfile démontre la résolution réellement utilisée par le workspace.

Les archives de livraison peuvent ne pas contenir ce fichier selon leur convention d’empaquetage. Dans ce cas :

• l’absence du lockfile dans l’archive n’est pas un défaut fonctionnel du projet ;
• le contrôle complet doit être exécuté dans le workspace local réel avec son Cargo.lock ;
• la livraison ne doit pas répéter cette limite comme un nouvel écart documentaire à chaque session ;
• le lockfile peut être fourni ponctuellement à la session lorsqu’une exécution de l’audit est nécessaire.

5. Évolution future

Le passage à wincode 0.6+ ne doit pas être effectué par simple mise à jour de version. Il exige :

• l’inventaire des crates directes et transitives utilisant wincode ;
• la vérification des versions d’interfaces Solana compatibles ;
• l’absence de familles de traits concurrentes ;
• la compilation de l’ensemble du workspace ;
• les tests des décodeurs et parseurs concernés ;
• la mise à jour de la règle et du script d’audit dans le même changement.

Jusqu’à cette migration explicitement validée, wincode 0.5.5 reste la résolution normative du workspace.